nest-cloudflare-turnstile

☁️ Cloudflare Turnstile integration for NestJS

Documentation

• 🧩 Simple and easy - This library provides just one guard to protect your endpoints with Cloudflare Turnstile Captcha!

Installation:

npm install nest-cloudflare-turnstile --save

add module to imports array with forRoot method:

  imports: [TurnstileModule.forRoot({
    secretKey: '1x0000000000000000000000000000000AA',
    tokenResponse: (req) => req.body?.turnstileToken // or you can use req.headers.turnstileToken
  })],

or with forRootAsync method:

 imports: [
    TurnstileModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => {
        const secretKey = config.get<string>(
          'CLOUDFLARE_TURNSTILE_PRIVATE_KEY',
        );
        if (!secretKey) {
          throw new Error('Missing Cloudflare Turnstile secret');
        }

        return {
          secretKey,
          tokenResponse: (req) => req.body?.turnstileToken,
        };
      },
    }),
  ]

use TurnstileCaptcha decorator on controller:

  import { TurnstileCaptcha } from 'nest-cloudflare-turnstile'

  @Post()
  @TurnstileCaptcha()
  getHello(): string {
    return this.appService.getHello();
  }

skipIf

Use skipIf to bypass Turnstile validation conditionally. Useful for development or test environments:

imports: [TurnstileModule.forRoot({
  secretKey: '1x0000000000000000000000000000000AA',
  tokenResponse: (req) => req.body?.turnstileToken,
  skipIf: process.env.NODE_ENV === 'development',
})],

exceptionFactory