Google recaptcha module

The NestJS module to protect your endpoints via google recaptcha.

Supported for HTTP and GraphQL NestJS applications.

Installation
Configuration
Usage
Error handling

Usage example here

Installation

$ npm i @nestlab/google-recaptcha

Configuration

Configuration for REST application

@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 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.
`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!

Dzixxx/google-recaptcha