NestJS Turnstile Captcha

A NestJS module for validating Cloudflare Turnstile CAPTCHA tokens.

Description

This module makes it easy to integrate Cloudflare Turnstile CAPTCHA verification into your NestJS applications.
Supports both synchronous and asynchronous module configuration. Includes a Guard for convenient use in controllers.

Installation

npm install nestjs-cloudflare-turnstile --save
# or
yarn add nestjs-cloudflare-turnstile

Usage

Import the module (synchronous)

import { Module } from '@nestjs/common';
import { TurnstileModule } from 'nestjs-cloudflare-turnstile';

@Module({
       imports: [
              TurnstileModule.forRoot({
                     secretKey: process.env.TURNSTILE_SECRET_KEY,
                     token: req => req.body.captchaToken,
                     skipIf: false
              }),
       ],
})
export class AppModule {}

Import the module (asynchronous)

import { Module } from '@nestjs/common'
import { TurnstileModule } from 'nestjs-cloudflare-turnstile'

@Module({
	imports: [
		TurnstileModule.forRootAsync({
			useFactory: async (configService: ConfigService) => ({
				secretKey: configService.get('CAPTCHA_SECRET_KEY'),
				token: req => req.headers['captcha-token'],
				skipIf: false
			}),
		}),
	],
})
export class AppModule {}

Example separate config for useFactory

If you prefer to keep your configuration logic separate, you can create a dedicated config provider:

// /config/turnstile.config.ts
import { ConfigService } from '@nestjs/config'
import type { TurnstileOptions } from 'nestjs-cloudflare-turnstile'

export function getTurnstileConfig(configService: ConfigService): TurnstileOptions {
	return {
		secretKey: configService.getOrThrow<string>('TURNSTILE_SECRET_KEY'),
		token: req => req.body.captcha,
		skipIf: false
	}
}

Then use it in your module:

import { Module } from '@nestjs/common';
import { TurnstileModule } from 'nestjs-cloudflare-turnstile';
import { getTurnstileConfig } from '@/config/turnstile.config';

@Module({
       imports: [
		TurnstileModule.forRootAsync({
			imports: [ConfigModule],
			useFactory: getTurnstileConfig,
			inject: [ConfigService]
		}),
       ],
})
export class AppModule {}

Using the Guard in Controllers

import { Controller, Post, Body } from '@nestjs/common';
import { TurnstileCaptcha } from 'nestjs-cloudflare-turnstile';

@Controller('auth')
export class AuthController {

       @Post('login')
       @TurnstileCaptcha()
       login() {
              return { success: true };
       }
}

Support

If you have any questions or encounter any issues, please don’t hesitate to contact the author or submit an issue in the repository.

• Author: Artur Docenko (MikroTik2)
• Contributors:
  • Artur Docenko

License

This project is licensed under the MIT License.