Skip to main content
theAuth verifies captcha tokens against Cloudflare Turnstile, hCaptcha, or Google reCAPTCHA. It ships as a verification module, not a plugin: there is no captcha() plugin export, and theAuth does not intercept your auth endpoints. You pass the captcha config key, then call theauth.captcha from your own route handlers before you process a sign-up or sign-in request.

Supported providers

Setup

lib/theauth.ts
theauth.captcha is null unless the captcha key is passed, so use theauth.captcha?. or theauth.captcha!. in handlers.

Verify a token in your handler

Add the provider’s widget to your form and send the token to your server. Check it with verify, passing the client IP when you have it:
Protect a sign-up route (server)
verify(token, ip?) returns { success: boolean, score?: number, error?: string }. An empty token returns { success: false, error: 'Missing captcha token' }. A network failure or non-2xx response from the provider also returns success: false with an error message.

Header-based check

theauth.captcha.middleware(request) reads the token from the X-Captcha-Token request header and returns { valid: boolean, error?: string }. It takes the client IP from CF-Connecting-IP or the first X-Forwarded-For entry.
Header check (server)
Client

reCAPTCHA v3 score threshold

With provider: 'recaptcha', when the provider response includes a score (reCAPTCHA v3), verify rejects scores below minScore (0.0 to 1.0, default 0.5):
lib/theauth.ts
minScore is ignored for Turnstile and hCaptcha. For hCaptcha, a score from the provider is returned in the result but not compared with a threshold.

Configuration reference

'recaptcha' | 'hcaptcha' | 'turnstile'
required
Captcha provider to use.
string
required
Server-side secret key from the provider dashboard.
number
default:0.5
Minimum score for reCAPTCHA v3. Ignored for other providers.
string[]
Endpoint names intended to require captcha (documented default: sign-up, sign-in, reset-password). Accepted in the config type, but theAuth does not currently read it, so enforcement is up to your own handlers.

Username and password

A sign-up and sign-in flow you can put captcha checks in front of.

Anonymous auth

Guest sessions as an alternative to requiring sign-up upfront.

Rate limiting

Request-level rate limiting for agent and auth endpoints.

Hooks

Lifecycle hooks you can attach to your instance.
Last modified on October 7, 2026