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.