KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

google-recaptcha

★ 82 Open GitHub ↗

Google recaptcha module for NestJS❤

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Google recaptcha module

This package provides protection for endpoints using [reCAPTCHA](https://www.google.com/recaptcha/about/) for [NestJS](https://docs.nestjs.com/) REST and GraphQL applications. By integrating with reCAPTCHA, this package helps to prevent automated abuse such as spam and bots, improving the security and reliability of your application.

[![NPM Version](https://img.shields.io/npm/v/@nestlab/google-recaptcha.svg)](https://www.npmjs.com/package/@nestlab/google-recaptcha)
[![Licence](https://img.shields.io/npm/l/@nestlab/google-recaptcha.svg)](https://github.com/chvarkov/google-recaptcha/blob/master/LICENSE)
[![NPM Downloads](https://img.shields.io/npm/dm/@nestlab/google-recaptcha.svg)](https://www.npmjs.com/package/@nestlab/google-recaptcha)
[![Build status](https://github.com/chvarkov/google-recaptcha/actions/workflows/test.yml/badge.svg)](https://github.com/chvarkov/google-recaptcha/actions/workflows/test.yml)
[![Coverage Status](https://chvarkov.github.io/google-recaptcha/badges/coverage.svg)](https://github.com/chvarkov/google-recaptcha/actions)

## Table of Contents

* [Installation](#installation)
* [Changes](#changes)
* [Configuration](#configuration)
  * [Options](#options)
  * [REST application](#rest-application)
    * [reCAPTCHA v2](#rest-recaptcha-v2)
    * [reCAPTCHA v3](#rest-recaptcha-v3)
    * [reCAPTCHA Enterprise](#rest-recaptcha-enterprise)
  * [Graphql application](#graphql-application)
    * [reCAPTCHA v2](#graphql-recaptcha-v2)
    * [reCAPTCHA v3](#graphql-recaptcha-v3)
    * [reCAPTCHA Enterprise](#graphql-recaptcha-enterprise)
* [Usage](#usage)
  * [REST application](#usage-in-rest-application)
  * [Graphql application](#usage-in-graphql-application)
  * [Validate in service](#validate-in-service)
  * [Validate in service (Enterprise)](#validate-in-service-enterprise)
  * [Dynamic Recaptcha configuration](#dynamic-recaptcha-configuration)
  * [Error handling](#error-handling)
* [Contribution](#contribution)
* [License](#license)

Usage example [here](https://github.com/chvarkov/google-recaptcha-example)

## Installation

```
$ npm i @nestlab/google-recaptcha
```

## Changes

The list of changes made in the project can be found in the [CHANGELOG.md](./CHANGELOG.md) file.

## Configuration

### Options

**GoogleRecaptchaModuleOptions**

| Property | Description |
|-------------------|-------------|
| `response` | **Required.** Type: `(request) => string` Function that returns response (recaptcha token) by request |
| `secretKey` | Optional. Type: `string` Google recaptcha secret key. Must be set if you don't use reCAPTCHA Enterprise |
| `debug` | Optional. Type: `boolean` Default: `false` Enables logging requests, responses, errors and transformed results |
| `logger` | Optional. Type: `Logger` Default: `new Logger()` Instance of custom logger that extended from Logger (@nestjs/common) |
| `skipIf` | Optional. Type: `boolean` \| `(request) => boolean \| Promise<boolean>` Function that returns true if you allow the request to skip the recaptcha verification. Useful for involing other check methods (e.g. custom privileged API key) or for development or testing |
| `enterprise` | Optional. Type: `GoogleRecaptchaEnterpriseOptions` Options for using reCAPTCHA Enterprise API. Cannot be used with `secretKey` option. |
| `network` | Optional. Type: `GoogleRecaptchaNetwork` \| `string` Default: `GoogleRecaptchaNetwork.Google` If your server has trouble connecting to https://google.com then you can set networks: `GoogleRecaptchaNetwork.Google` = 'https://www.google.com/recaptcha/api/siteverify' `GoogleRecaptchaNetwork.Recaptcha` = 'https://recaptcha.net/recaptcha/api/siteverify' or set any api url |
| `score` | Optional. Type: `number` \| `(score: number) => boolean` Score validator for reCAPTCHA v3 or enterprise. `number` - minimum available score. `(score: number) => boolean` - function with custom validation rules. |
| `actions` | Optional. Type: `string[]` Available action list for reCAPTCHA v3 or enterprise. You can make this check stricter by passing the action property parameter to `@Recaptcha(...)` decorator. |
| `remoteIp` | Optional. Type: `(request) => string` A function that returns a remote IP address from the request |
| `axiosConfig` | Optional. Type: `AxiosRequestConfig` Allows to setup proxy, response timeout, https agent etc... |
| `global` 		| Optional. Type: `boolean` Default: `false` Defines a module in the [global scope](https://docs.nestjs.com/modules#global-modules). |

**GoogleRecaptchaEnterpriseOptions**

| Property | Description |
|-----------------|-------------|
| `projectId` | **Required.** Type: `string` Google Cloud project ID |
| `siteKey` | **Required.** Type: `string` [reCAPTCHA key](https://cloud.google.com/recaptcha-enterprise/docs/keys) associated with the site/app. |
| `apiKey` | **Required.** Type: `string` API key associated with the current project. Must have permission `reCAPTCHA Enterprise API`. You can manage credentials [here](https://console.cloud.google.com/apis/credentials). |

The module provides two static methods for configuration: `forRoot` and `forRootAsync`.

**forRoot**

> forRoot(options: GoogleRecaptchaModuleOptions): DynamicModule

The `forRoot` method accepts a `GoogleRecaptchaModuleOptions` object that configures the module. This method should be used in the root `AppModule`. Example usage:

```typescript
@Module({
    imports: [
        GoogleRecaptchaModule.forRoot({
            secretKey: process.env.GOOGLE_RECAPTCHA_SECRET_KEY,
            response: req => req.headers.recaptcha,
        })
    ],
})
export class AppModule {
}
```

**forRootAsync**

> forRootAsync(options: ModuleAsyncOptions): DynamicModule

The `forRootAsync` method is similar to `forRoot`, but allows for asynchronous configuration. 
It accepts a `GoogleRecaptchaModuleAsyncOptions` object that returns a configuration object or a Promise that resolves to a configuration object. 
Read more about [ConfigService](https://docs.nestjs.com/techniques/configuration#getting-started) and [custom getter function](https://docs.nestjs.com/techniques/configuration#custom-getter-functions).

Example usage:

```typescript
@Module({
    imports: [
        GoogleRecaptchaModule.forRootAsync({
            imports: [ConfigModule],
            useFactory: (configService: ConfigService) => configService.googleRecaptchaOptions,
            inject: [ConfigService],
        })
    ],
})
export class AppModule {
}
```

### REST application

#### REST reCAPTCHA V2

```typescript
@Module({
    imports: [
        GoogleRecaptchaModule.forRoot({
            secretKey: process.env.GOOGLE_RECAPTCHA_SECRET_KEY,
            response: req => req.headers.recaptcha,
            skipIf: process.env.NODE_ENV !== 'production',
        }),
    ],
})
export class AppModule {
}
```