RecaptchaConfig

Package: @nauth-toolkit/core Type: Interface (Configuration)

Configuration interface for Google reCAPTCHA bot protection.

NestJS

import { NAuthModuleConfig } from '@nauth-toolkit/nestjs';

Express

import { NAuthConfig } from '@nauth-toolkit/core';

Fastify

import { NAuthConfig } from '@nauth-toolkit/core';

Properties

Property	Type	Required	Description
actionScores	Record<string, number>	No	Per-action minimum score overrides. Falls back to minimumScore for unlisted actions. Keys are action names (login, signup, password_reset).
enabled	boolean	Yes	Enable reCAPTCHA validation. When true, routes marked with @RequireRecaptcha() will enforce validation.
minimumScore	number	No	Default minimum score for v3/Enterprise (0.0-1.0). Used when no per-action override exists in actionScores. Default: 0.5.
provider	RecaptchaProvider	Yes	Provider implementation: RecaptchaV2Provider, RecaptchaV3Provider, or RecaptchaEnterpriseProvider.
validateOnStartup	'warn' | 'error' | false	No	Validate credentials at startup by probing Google's API. 'warn' (default): log warning on failure. 'error': throw and halt startup. false: skip validation.

Examples

v3 (Recommended)

NestJS

import { NAuthModule } from '@nauth-toolkit/nestjs';
import { RecaptchaV3Provider } from '@nauth-toolkit/recaptcha';

@Module({
  imports: [
    NAuthModule.forRoot({
      recaptcha: {
        enabled: true,
        provider: new RecaptchaV3Provider({
          secretKey: process.env.RECAPTCHA_V3_SECRET_KEY!,
        }),
        minimumScore: 0.5,
      },
    }),
  ],
})
export class AppModule {}

// In your controller, mark protected endpoints:
@Controller('auth')
export class AuthController {
  @Public()
  @RequireRecaptcha()
  @Post('login')
  async login(@Body() dto: LoginDTO) {
    return this.authService.login(dto);
  }
}

Express

import { NAuth } from '@nauth-toolkit/core';
import { ExpressAdapter } from '@nauth-toolkit/express';
import { RecaptchaV3Provider } from '@nauth-toolkit/recaptcha';

const nauth = await NAuth.create({
  config: {
    recaptcha: {
      enabled: true,
      provider: new RecaptchaV3Provider({
        secretKey: process.env.RECAPTCHA_V3_SECRET_KEY!,
      }),
      minimumScore: 0.5,
    },
  },
  dataSource,
  adapter: new ExpressAdapter(),
});

Fastify

import { NAuth } from '@nauth-toolkit/core';
import { FastifyAdapter } from '@nauth-toolkit/fastify';
import { RecaptchaV3Provider } from '@nauth-toolkit/recaptcha';

const nauth = await NAuth.create({
  config: {
    recaptcha: {
      enabled: true,
      provider: new RecaptchaV3Provider({
        secretKey: process.env.RECAPTCHA_V3_SECRET_KEY!,
      }),
      minimumScore: 0.5,
    },
  },
  dataSource,
  adapter: new FastifyAdapter(),
});

Enterprise

NestJS

import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

@Module({
  imports: [
    NAuthModule.forRoot({
      recaptcha: {
        enabled: true,
        provider: new RecaptchaEnterpriseProvider({
          projectId: process.env.RECAPTCHA_PROJECT_ID!,
          apiKey: process.env.RECAPTCHA_API_KEY!,
          siteKey: process.env.RECAPTCHA_SITE_KEY!,
        }),
        minimumScore: 0.7,
        actionScores: {
          login: 0.3,   // More permissive for returning users
          signup: 0.7,  // Stricter for new registrations
        },
      },
    }),
  ],
})

Express

import { NAuth } from '@nauth-toolkit/core';
import { ExpressAdapter } from '@nauth-toolkit/express';
import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

const nauth = await NAuth.create({
  config: {
    recaptcha: {
      enabled: true,
      provider: new RecaptchaEnterpriseProvider({
        projectId: process.env.RECAPTCHA_PROJECT_ID!,
        apiKey: process.env.RECAPTCHA_API_KEY!,
        siteKey: process.env.RECAPTCHA_SITE_KEY!,
      }),
      minimumScore: 0.7,
      actionScores: {
        login: 0.3,
        signup: 0.7,
      },
    },
  },
  dataSource,
  adapter: new ExpressAdapter(),
});

Fastify

import { NAuth } from '@nauth-toolkit/core';
import { FastifyAdapter } from '@nauth-toolkit/fastify';
import { RecaptchaEnterpriseProvider } from '@nauth-toolkit/recaptcha';

const nauth = await NAuth.create({
  config: {
    recaptcha: {
      enabled: true,
      provider: new RecaptchaEnterpriseProvider({
        projectId: process.env.RECAPTCHA_PROJECT_ID!,
        apiKey: process.env.RECAPTCHA_API_KEY!,
        siteKey: process.env.RECAPTCHA_SITE_KEY!,
      }),
      minimumScore: 0.7,
      actionScores: {
        login: 0.3,
        signup: 0.7,
      },
    },
  },
  dataSource,
  adapter: new FastifyAdapter(),
});

Related

• RecaptchaV2Provider - Checkbox-based
• RecaptchaV3Provider - Score-based
• RecaptchaEnterpriseProvider - Enterprise features
• reCAPTCHA Guide - Complete implementation guide