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 withverify, 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
Withprovider: '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
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.Related
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.