# Bot Protection with Turnstile

> Cloudflare Turnstile on sign-up, sign-in, password reset and emailed links and codes: keys, which endpoints it guards, the forms, CSP and testing.

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/captcha*

---

[Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) checks that a real browser fills the auth forms, usually without the user doing anything. It stops bots that create accounts, try passwords from many IPs or send emails to strangers, where the [per-IP rate limits](./rate-limits) alone don't help.

## Turn It On

1. In the Cloudflare dashboard, go to **Turnstile** and add a widget for your domain (and `localhost` for local work). Use the **Managed** mode.
2. Set both keys:

```bash {% title="apps/web/.env" %}
TURNSTILE_SITE_KEY=0x4AAAAAAA...
TURNSTILE_SECRET_KEY=0x4AAAAAAA...
```

Deployed: `TURNSTILE_SITE_KEY` is public (the browser gets it). The secret is a Worker secret: `pnpm --filter web exec void secret put TURNSTILE_SECRET_KEY`.

Captcha is on when both are set. Setting only one makes every request answer 500, with the missing key named in the logs. With neither, Better Auth's [captcha plugin](https://www.better-auth.com/docs/plugins/captcha) isn't registered and the forms show no check.

{% callout type="note" %}
Cloudflare's test keys: site key `1x00000000000000000000AA` and secret `1x0000000000000000000000000000000AA` always pass, and the widget says "For testing only". `env.example` lists them in a comment; e2e uses them.
{% /callout %}

## What It Guards

| Endpoint | Form |
|---|---|
| `/api/auth/sign-up/email` | Sign up with a password |
| `/api/auth/sign-in/email` | Sign in with a password |
| `/api/auth/request-password-reset` | Forgot password |
| `/api/auth/send-verification-email` | "Send the link again" |
| `/api/auth/sign-in/magic-link` | Send Email Link |
| `/api/auth/email-otp/send-verification-otp` | Email me a code (and resend) |

Not guarded:
- OAuth: the provider checks the user.
- Passkeys: the device checks the user.
- Entering an email code, a 2FA code or a new password: each has its own attempt limits, and its code or link came from the user's inbox or device.

A request without a token gets `400 MISSING_RESPONSE`. A token Cloudflare refuses, or one solved on another host than `SITE_URL`'s (a site key can list several, e.g. staging and `localhost`), gets `403 VERIFICATION_FAILED`. Cloudflare's test secrets skip the host check: their answers name `example.com`. If Cloudflare can't be reached within 10 seconds, the request fails (`500 UNKNOWN_ERROR`) rather than letting bots through. The forms show each as a message (`auth.errors.*`).

The list is `CAPTCHA_PATHS` in `packages/better-auth/src/captcha.ts`. Only browser requests to `/api/auth/*` are checked; `auth.api.*` calls from your server code are not.

## The Forms

`CaptchaProvider` (in `apps/web/pages/auth/layout.tsx`) holds one Turnstile check per page, shown where the page renders `<CaptchaWidget />`. Every form on the page uses it:

- Each request takes a token of its own and sends it in Better Auth's `x-captcha-response` header; then the widget solves a new one. A token works only once, also when the request fails, so two forms submitted together each wait for their own.
- A submit before the check finishes waits for it (up to 30 seconds), so a fast user or an interactive challenge doesn't cause an error.
- When Turnstile can't load (an ad blocker, a network or CSP block, an unsupported browser) or errors, submits don't wait: they go without a token and the form says the check didn't load ("Reload the page and try again"). Captcha fails closed.
- The widget follows the app's theme and the browser's language (Turnstile errors on a locale it doesn't know). Sign-in and sign-up show it only when an email method is on: OAuth and passkeys don't use it.

A form of your own that calls a guarded endpoint wraps its call with `useCaptcha()` from `@kit/auth/captcha`:

```tsx
const { withCaptcha } = useCaptcha();

const { error } = await withCaptcha((fetchOptions) =>
  authClient.signIn.email({ email, password, fetchOptions }),
);
```

Put it on a page under `pages/auth/` (inside the provider), with `<CaptchaWidget />` on the page. Without the widget the form's requests fail at once, and the console says `no <CaptchaWidget /> on this page`. To guard another endpoint, add its path to `CAPTCHA_PATHS` and wrap its form the same way.

## Content Security Policy

`apps/web/config/security.config.ts` already allows `https://challenges.cloudflare.com` in `script-src`, `frame-src` and `connect-src`. Turnstile's script is loaded by the kit's own nonce'd script, which `'strict-dynamic'` trusts, so the CSP keeps its nonce and needs nothing else ([Content Security Policy](../security/content-security-policy)).

## Testing

- `packages/better-auth/src/__tests__/captcha.test.ts` mocks Cloudflare's siteverify. It checks every guarded endpoint: no token is refused, a refused token is refused, and a good one goes through. It also checks the host rule, that the request fails when Cloudflare is down, that other endpoints are untouched, and the key pairing.
- E2E runs every spec with the test keys (`SIGN_IN_METHOD_ENV`), so every form goes through the real widget. `captcha.spec.ts` covers:
  - the widget shows on sign-in, sign-up and reset, without CSP violations;
  - a sign-in submitted before the check finishes still works;
  - the server refuses a request without a token.
- API calls in specs send `CAPTCHA_TEST_HEADERS`.
- The e2e fixture sends a made-up `cf-connecting-ip` to the app, and strips it from requests to Cloudflare, which answers 403 to a browser that sends that header.
