Spam protection

Beginner walkthrough

Prerequisites: Read the two beginner guides below, finish Web local setup, and open this monorepo at its root in your editor. Web settings belong in apps/web/.env.local; Next.js does not read the root .env. /dashboard in the default fake mode is a no-database demo; /auth needs a migrated database.

Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.

1. Create a Turnstile test widget for the exact local/deployed hostname. In apps/web/.env.local, set CAPTCHA_PROVIDER=turnstile and NEXT_PUBLIC_TURNSTILE_SITE_KEY; put TURNSTILE_SECRET_KEY only in the server secret store.

2. Restart and submit a test contact form.

3. Expect the challenge and a successful valid-token response. If every request fails, compare hostname and key pair; never expose the secret key.

For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.

• Before you start
• Terminal basics
• Web local setup
• Agent prompts & project memory

Enable both keys

CAPTCHA_PROVIDER=off is the default. Select turnstile, configure the matching hostname in your Turnstile application and provide both keys. NEXT_PUBLIC_TURNSTILE_SITE_KEY is public; TURNSTILE_SECRET_KEY is used only by the server verifier.

CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.

Preserve the protected surfaces

The gate covers contact/newsletter forms and Better Auth sign-in, sign-up, OTP and password-reset credential endpoints. It complements validation/rate limiting; it is not a substitute for sessions or workspace authorization.

Verify rejection and recovery

Test a valid token, missing/expired/invalid token, verifier failure and a retry after the client widget resets. Keep actionable human-check copy and keyboard access; inspect the chosen auth engine's coverage before switching providers.

• Protected forms
• Auth engine differences

Setup and configuration

CAPTCHA_PROVIDER selects the verifier: off (the default, so local development stays credential-free) or turnstile. Enabling turnstile requires TURNSTILE_SECRET_KEY on the server and NEXT_PUBLIC_TURNSTILE_SITE_KEY for the client widget — the config schema fails startup if either is missing.

apps/web/src/captcha.ts composes one process-wide verifier that posts the token to Cloudflare's siteverify endpoint with a ten-second timeout and fails closed — an unverifiable token is never treated as proof of humanity.

CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms

Implementation workflow

CaptchaWidget (src/captcha-widget.tsx) renders the widget and injects the cf-turnstile-response field into the parent form, while auth client calls carry the token in the x-captcha-response header. The contact and newsletter actions verify before writing — a failed check returns status=captcha instead of creating a lead.

packages/auth mounts better-auth's captcha plugin when the provider is on; CAPTCHA_ENDPOINTS covers the credential-entry and token-issuing routes — sign-in, sign-up, OTP send, password reset. Consuming endpoints such as check-verification-otp stay unlisted: the OTP or token itself is the proof there.

Verification and troubleshooting

Submit each protected form with a missing token and a malformed one — both must fail closed. Verify an unreachable siteverify rejects rather than passes, provider=off leaves local development open, and the secret never reaches client bundles or logs.