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

Configuration for reCAPTCHA V3

@Module({
    imports: [
        GoogleRecaptchaModule.forRoot({
            secretKey: process.env.GOOGLE_RECAPTCHA_SECRET_KEY,
            response: (req: IncomingMessage) => (req.headers.recaptcha || '').toString(),
            skipIf: process.env.NODE_ENV !== 'production',
            actions: ['SignUp', 'SignIn'],
            score: 0.8,
        })
    ],
})
export class AppModule {
}

Configuration for reCAPTCHA Enterprise

@Module({
    imports: [
        GoogleRecaptchaModule.forRoot({
            response: (req: IncomingMessage) => (req.headers.recaptcha || '').toString(),
            skipIf: process.env.NODE_ENV !== 'production',
            actions: ['SignUp', 'SignIn'],
            score: 0.8,
            enterprise: { 
                projectId: process.env.RECAPTCHA_ENTERPRISE_PROJECT_ID, 
                siteKey: process.env.RECAPTCHA_ENTERPRISE_SITE_KEY, 
                apiKey: process.env.RECAPTCHA_ENTERPRISE_API_KEY, 
            },
        })
    ],
})
export class AppModule {
}

Tip: header names transforming to lower case.

For example: If you send 'Recaptcha' header then use (req) => req.headers.recaptcha

Configuration options

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 recCAPTCHA Enterprise API. Cannot using 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. `number` - minimum available score. `(score: number) => boolean` - function with custom validation rules.
`actions`	Optional. Type: `string[]` Available action list for reCAPTCHA v3. You can make this check stricter by passing the action property parameter to `@Recaptcha(...)` decorator.
`axiosConfig`	Optional. Type: `AxiosRequestConfig` Allows to setup proxy, response timeout, https agent etc...

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.

If you want import configs from your ConfigService via custom getter function that will return GoogleRecaptchaModuleOptions object.

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

Usage

Validate in service

@Injectable()
export class SomeService {
    constructor(private readonly recaptchaValidator: GoogleRecaptchaValidator) {
    }

    async someAction(recaptchaToken: string): Promise<void> {
        const result = await this.recaptchaValidator.validate({
            response: recaptchaToken,
            score: 0.8,
            action: 'SomeAction',
        });
        
        if (!result.success) {
            throw new GoogleRecaptchaException(result.errors);
        }
        // TODO: Your implemetation
    }
}

Validate in service (Enterprise)

@Injectable()
export class SomeService {
    constructor(private readonly recaptchaEnterpriseValidator: GoogleRecaptchaEnterpriseValidator) {
    }

    async someAction(recaptchaToken: string): Promise<void> {
        const result = await this.recaptchaEnterpriseValidator.validate({
            response: recaptchaToken,
            score: 0.8,
            action: 'SomeAction',
        });
        
        if (!result.success) {
            throw new GoogleRecaptchaException(result.errors);
        }
        
        const riskAnalytics = result.getEnterpriseRiskAnalytics();
        
        // TODO: Your implemetation
    }
}

Guard

Use @Recaptcha decorator to protect your endpoints.


@Controller('feedback')
export class FeedbackController {
    @Recaptcha()
    @Post('send')
    async send(): Promise<any> {
        // TODO: Your implementation.
    }
}

You can override default property that contain recaptcha for specific endpoint.


@Controller('feedback')
export class FeedbackController {
    @Recaptcha({response: req => req.body.recaptha})
    @Post('send')
    async send(): Promise<any> {
        // TODO: Your implementation.
    }
}

Also you can override recaptcha v3 options.


@Controller('feedback')
export class FeedbackController {
    @Recaptcha({response: req => req.body.recaptha, action: 'Send', score: 0.8})
    @Post('send')
    async send(): Promise<any> {
        // TODO: Your implementation.
    }
}

Get verification result


@Controller('feedback')
export class FeedbackController {
    @Recaptcha()
    @Post('send')
    async send(@RecaptchaResult() recaptchaResult: GoogleRecaptchaValidationResult): Promise<any> {
        console.log(`Action: ${recaptchaResult.action} Score: ${recaptchaResult.score}`);
        // TODO: Your implementation.
    }
}

If you want use google recaptcha guard in combination with another guards then you can use @UseGuards decorator.


@Controller('feedback')
export class FeedbackController {
    @SetRecaptchaOptions({action: 'Send', score: 0.8})
    @UseGuards(Guard1, GoogleRecaptchaGuard, Guard2)
    @Post('send')
    async send(): Promise<any> {
        // TODO: Your implementation.
    }
}

GraphQL guard

Use @Recaptcha decorator to protect your resolver.

@Recaptcha()
@Resolver(of => Recipe)
export class RecipesResolver {
    @Query(returns => Recipe)
    async recipe(@Args('id') id: string): Promise<Recipe> {
        // TODO: Your implementation.
    }
}

You can override default property that contain recaptcha for specific query, mutation or subscription.

@Recaptcha()
@Resolver(of => Recipe)
export class RecipesResolver {
    @Query(returns => Recipe)
    async recipe(@Args('id') id: string): Promise<Recipe> {
        // TODO: Your implementation.
    }

    // Overridden default header. This query using X-Recaptcha header 
    @Recaptcha({response: (req: IncomingMessage) => (req.headers['x-recaptcha'] || '').toString()})
    @Query(returns => [Recipe])
    recipes(@Args() recipesArgs: RecipesArgs): Promise<Recipe[]> {
        // TODO: Your implementation.
    }
}

Error handling

Google recaptcha guard will throw GoogleRecaptchaException on error.

GoogleRecaptchaException

GoogleRecaptchaException has data with google recaptcha error codes.

GoogleRecaptchaException ← HttpException ← Error.

GoogleRecaptchaNetworkException

GoogleRecaptchaNetworkException has error code ErrorCode.NetworkError.

GoogleRecaptchaNetworkException ← GoogleRecaptchaException

You can handle it via ExceptionFilter.

Example exception filter implementation.


@Catch(GoogleRecaptchaException)
export class GoogleRecaptchaFilter implements ExceptionFilter {
    catch(exception: GoogleRecaptchaException, host: ArgumentsHost): any {
        // TODO: Your exception filter implementation
    }
}

And add your filter to application


async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    app.useGlobalFilters(new ErrorFilter(), new GoogleRecaptchaFilter());
    await app.listen(3000);
}
bootstrap();

Enjoy!

v3.1.0

Added support reCAPTCHA Enterprise API.
Updated module options:
- Updated secretKey as optional (shouldn't use for enterprise configuration).
- Added enterprise option

| Property | Description | |---------------------------------|-------------| | enterprise.projectId | Required. Type: string Google Cloud project ID | | enterprise.siteKey | Required. Type: string reCAPTCHA key associated with the site/app. | | enterprise.apiKey | Required. Type: string API key associated with the current project. Must have permission reCAPTCHA Enterprise API. You can manage credentials here. |

Updated GoogleRecaptchaValidator interface

class GoogleRecaptchaValidator {
    validate(options: VerifyResponseOptions): Promise<RecaptchaVerificationResult<VerifyResponseV3>>;
}

Addded recaptcha validator for enterprise

@Injectable()
export class SomeService {
    constructor(private readonly recaptchaEnterpriseValidator: GoogleRecaptchaEnterpriseValidator) {
    }

    async someAction(recaptchaToken: string): Promise<void> {
        const result = await this.recaptchaEnterpriseValidator.validate({
            response: recaptchaToken,
            score: 0.8,
            action: 'SomeAction',
        });
        
        if (!result.success) {
            throw new GoogleRecaptchaException(result.errors);
        }
        
        const riskAnalytics = result.getEnterpriseRiskAnalytics();
        
        console.log('score', riskAnalysis.score);
        console.log('score', riskAnalysis.reasons);

        // TODO: Your implemetation
    }
}

Keywords

FAQs

What is @nestlab/google-recaptcha?

Is @nestlab/google-recaptcha popular?

Is @nestlab/google-recaptcha well maintained?

Package last updated on 15 Aug 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install