Google recaptcha module

This package provides protection for endpoints using reCAPTCHA for NestJS 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.

Installation

$ npm i @nestlab/google-recaptcha

Changes

The list of changes made in the project can be found in the 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.

GoogleRecaptchaEnterpriseOptions

Property	Description
`projectId`	Required. Type: `string` Google Cloud project ID
`siteKey`	Required. Type: `string` reCAPTCHA key 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.

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:

@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 and custom getter function.

Example usage:

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