RecaptchaV3Provider

Package: @nauth-toolkit/recaptcha Type: Provider Class

Score-based invisible reCAPTCHA provider without user interaction.

NestJS

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

Express

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

Fastify

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

Constructor

new RecaptchaV3Provider(config: RecaptchaV3Config)

RecaptchaV3Config

Property	Type	Required	Description
secretKey	string	Yes	Secret key from Google reCAPTCHA admin console.
timeout	number	No	Request timeout in milliseconds. Default: 10000.

Methods

verify()

Verify reCAPTCHA v3 token with Google's API and return risk score.

async verify(token: string, remoteIp?: string, action?: string): Promise<RecaptchaVerificationResult>

Parameters

• token - reCAPTCHA token from client
• remoteIp - Client IP address (optional, recommended)
• action - Action name (e.g., 'login', 'signup')

Returns

• RecaptchaVerificationResult - Verification result with success status and score (0.0-1.0)

validateConfig()

Validate provider credentials at startup by sending a probe request to Google's API.

async validateConfig(): Promise<RecaptchaValidationResult>

Returns

• RecaptchaValidationResult - { valid, message, hint?, httpStatus? }

Called automatically during NAuth.create() when validateOnStartup is 'warn' (default) or 'error'. Detects invalid secret keys before a real user hits the endpoint.

Example

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, // Adjust based on your needs
      },
    }),
  ],
})
export class AppModule {}

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(),
});

Score-Based Validation

reCAPTCHA v3 returns a score between 0.0 and 1.0:

Score Range	Interpretation	Recommended Action
0.9 - 1.0	Very likely human	Allow
0.7 - 0.9	Likely human	Allow
0.5 - 0.7	Neutral	Allow with monitoring
0.3 - 0.5	Suspicious	Additional verification
0.0 - 0.3	Very likely bot	Block or challenge

Configure minimumScore in RecaptchaConfig based on your security vs UX trade-off:

• 0.3: Permissive, fewer false positives
• 0.5: Balanced (recommended)
• 0.7: Strict, may block legitimate users

Use actionScores for per-action thresholds (e.g., stricter for signup, more permissive for login). See RecaptchaConfig for details.

When to Use

• Invisible protection without user friction
• Score-based decisions for flexibility
• Most web applications (recommended default)

Setup

1. Go to Google reCAPTCHA Admin Console
2. Create a new site with reCAPTCHA v3
3. Add your domains (including localhost for development)
4. Copy the secret key for backend configuration
5. Copy the site key for frontend integration

Related

• RecaptchaConfig - Configuration interface
• RecaptchaV2Provider - Checkbox alternative
• RecaptchaEnterpriseProvider - Enterprise version
• reCAPTCHA Guide - Complete implementation guide