@nestlab/google-recaptcha

Google recaptcha module

The NestJS module to protect your endpoints via google recaptcha.

• Installation
• Configuration
• Usage
• Error handling

Usage example here

Installation

$ npm i @nestlab/google-recaptcha

Configuration

@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,
            agent: null
        })
    ],
})
export class AppModule {
}

Configuration options

Property	Description
secretKey	Required. Type: string Google recaptcha secret key
response	Required. Type: (request) => string Function that returns response (recaptcha token) by request
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
network	Optional. Type: GoogleRecaptchaNetwork | boolean 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
agent	Optional. Type: https.Agent If you need to use an agent

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

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(req => req.body.recaptha)
    @Post('send')
    async send(): Promise<any> {
        // 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 {
    @UseGuards(Guard1, GoogleRecaptchaGuard, Guard2)
    @Post('send')
    async send(): Promise<any> {
        // TODO: Your implementation.
    }
}

Error handling

Google recaptcha guard will throw GoogleRecaptchaException on error.

GoogleRecaptchaException has data with google recaptcha error codes.

GoogleRecaptchaException ← HttpException ← Error.

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!

Changelog

v1.2.0

• Updated google recaptcha module options.
• Removed option useRecaptchaNet: boolean
• Added option: network: GoogleRecaptchaNetwork | string <br>If your server has trouble connecting to 'https://google.com' then you can set networks: <br/>GoogleRecaptchaNetwork.Google = 'https://www.google.com/recaptcha/api/siteverify' </br>GoogleRecaptchaNetwork.Recaptcha = 'https://recaptcha.net/recaptcha/api/siteverify' or set any api url