Captcha

The captcha plugin adds bot protection to any KavachOS endpoint. It validates a client-side token before the request is processed, blocking automated sign-ups and credential stuffing without extra middleware.

Supported providers

Provider	Value
Cloudflare Turnstile	`'turnstile'`
hCaptcha	`'hcaptcha'`
Google reCAPTCHA v2	`'recaptcha-v2'`
Google reCAPTCHA v3	`'recaptcha-v3'`

Setup

lib/kavach.ts

import { createKavach } from 'kavachos';
import { captcha } from 'kavachos/auth'; 

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://auth.example.com',
  plugins: [
    captcha({ 
      provider: 'turnstile', 
      secretKey: process.env.TURNSTILE_SECRET_KEY!, 
      endpoints: ['/auth/sign-up', '/auth/sign-in'], 
    }), 
  ],
});

Client-side token

Add the provider’s widget to your form. When the user completes the challenge, include the token in the request body as captchaToken.

const res = await fetch('/auth/sign-up', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'correct horse battery',
    captchaToken: turnstile.getResponse(), 
  }),
});

The captchaToken field is stripped from the request before it reaches other plugins. Other plugin handlers never see it. Error codes

Code	Status	Meaning
`CAPTCHA_MISSING`	400	Request did not include a token
`CAPTCHA_INVALID`	403	Provider rejected the token

reCAPTCHA v3 score threshold

For reCAPTCHA v3, set a minimum score (0.0–1.0). Requests below the threshold are rejected:

lib/kavach.ts

captcha({
  provider: 'recaptcha-v3',
  secretKey: process.env.RECAPTCHA_SECRET!,
  minScore: 0.5, 
  endpoints: ['/auth/sign-up'],
}),

Configuration reference

required

Captcha provider to use.

string

required

Server-side secret key from the provider dashboard.

string[]

default:"["

List of endpoint paths where captcha validation is enforced. Defaults to sign-up and sign-in.

number

Minimum score for reCAPTCHA v3. Ignored for other providers.

string

Request body field that contains the captcha token.

Overview

Methods

OAuth providers

Enterprise

Supported providers

Setup

Client-side token

reCAPTCHA v3 score threshold

Configuration reference

​Supported providers

​Setup

​Client-side token

​reCAPTCHA v3 score threshold

​Configuration reference

Supported providers

Setup

Client-side token

reCAPTCHA v3 score threshold

Configuration reference