@nestlab/google-recaptcha

Google recaptcha module

The NestJS module to protect your endpoints via google recaptcha.

Supported for HTTP and GraphQL NestJS applications.

• Installation
• Configuration
• Usage
  • Validate in service
  • Validate in service (enterprise)
  • Guard
  • GraphQL guard
• 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!

Changelog

v3.1.2

• Fixed http exception statuses for error codes: site-mismatch, browser-error (HTTP status - 400).
• Added error code: incorrect-captcha-sol.