nestjs-captcha Library

Configuration

import { CaptchaModule, CaptchaType } from '@nathapp/nestjs-captcha';

@Module({
  imports: [
    CaptchaModule.register({
      enabled: true,
      extract: { type: 'header', key: 'x-captcha-token' },
      type: CaptchaType.Recaptcha,
      options: {
        secret: process.env.CAPTCHA_SECRET,
        // reCAPTCHA v3 score policy: reject responses scoring below 0.9.
        threshold: 0.9,
        // Exact hostname the upstream response must report.
        expectedHostname: 'api.example.com',
      },
    }),
  ],
})
export class AppModule {}

Both policies are optional but validated at provider construction, so a misconfigured threshold (must be a finite number within [0, 1]) or an empty/whitespace expectedHostname fails application bootstrap rather than the first guarded request. When an enabled recaptcha provider sets neither policy, a one-time warning is logged at construction (never including the secret or a token).

reCAPTCHA v3 score checks vs. scoreless v2 / Turnstile

• reCAPTCHA v3: set threshold to enforce the score returned by Google. The guard rejects a missing, non-numeric, non-finite, or out-of-[0, 1] score whenever a threshold is configured. threshold: 0 is honored — a score of 0 passes, but a missing/invalid score still fails. With no threshold, scoreless reCAPTCHA v2 responses are accepted on success alone.
• reCAPTCHA v2: do not set threshold; there is no score to check, so the guard verifies success only.
• Turnstile: there is no score policy. Turnstile responses are accepted on success alone; threshold does not apply.
• expectedHostname: applies to both reCAPTCHA and Turnstile. When set, the upstream hostname must match exactly (api.example.com); a different domain, a subdomain, a suffix host, or an absent hostname is rejected. There is no wildcard matching and no request-Host-derived allowlist.
• In every case the guard requires success === true; a truthy non-boolean value (such as the string "true") is not treated as success.

DefaultCaptchaModuleFactory

DefaultCaptchaModuleFactory reads configuration from ConfigService (env):

1. CAPTCHA_ENABLED = true/false, 1/0
2. CAPTCHA_TYPE = recaptcha, turnstile
3. CAPTCHA_SECRET = the secret
4. CAPTCHA_ENDPOINT = custom endpoint
5. CAPTCHA_THRESHOLD = for recaptcha

DefaultCaptchaModuleFactory extracts the token from the header with key x-captcha-token.