Turnstile

Turnstile is Cloudflare’s bot check. When it is on, the form shows a small widget that decides in the visitor’s browser whether this looks like a person. The widget puts a token in the form. The server sends that token and a secret key to Cloudflare, and sends the mail only if Cloudflare accepts it.

It is off by default. The honeypot and the rate limit already stop simple scripts. Add Turnstile when a form attracts real abuse, or when the client asks for it. It loads a script from Cloudflare, so tell the client, and check their privacy text. The ruleset forbids adding anything that tracks visitors unless the client asks.

What you’ll do

1. Turn Turnstile on for a form.
2. Create a Turnstile widget in Cloudflare and copy its two keys.
3. Set the keys where the site builds and where it runs.

Turn it on for a form

For a new form, pass --turnstile:

npx mdlake add-form contact --turnstile

For an existing form, set turnstile: true in src/forms/<name>.ts:

export default defineForm({
  // ...schema, fields, recipientEnv, subject, success
  turnstile: true,
})

Turnstile is a property of one form. Other forms on the same site are not affected.

The keys

Cloudflare gives each widget a pair of keys.

To get them, add a Turnstile widget for the site’s domain in your Cloudflare account, and copy the site key and the secret key. The names of Cloudflare’s menus change from time to time, so follow Cloudflare’s own Turnstile documentation for the clicks.

Where to put them:

If you change the site key after the site is built, the page still carries the old one. Rebuild.

Test keys for development

You do not need a Cloudflare account to work on the site. When the keys are not set, development uses Cloudflare’s published test keys, which always pass:

The kit applies them like this:

• The dev server (npm run dev) uses the always-passing site key when PUBLIC_TURNSTILE_SITE_KEY is not set.
• The Node handler uses the always-passing secret when TURNSTILE_SECRET_KEY is not set and NODE_ENV is not production. The generated Bicep sets NODE_ENV=production.
• The .NET backend uses the always-passing secret when the secret is not set and the environment is Development.

To see the failure path locally, put the always-fails keys in your .env.

What happens when a check fails

Turnstile never lets a submission through by accident. The server answers:

When the browser gets an error after sending, the form resets the widget so the visitor can try again with a fresh token.

The build also checks the site key. A form with turnstile: true fails the build with “The form “contact” uses Turnstile, but PUBLIC_TURNSTILE_SITE_KEY is not set for this build.” when no key is set outside the dev server.

How it works

1. The Form component loads https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit once and renders the widget inside the form. The widget adds a hidden field named cf-turnstile-response.
2. The browser posts that field with the rest of the form.
3. After the schema accepts the values, the server posts the secret, the token and, when known, the visitor’s address to https://challenges.cloudflare.com/turnstile/v0/siteverify.
4. Only success: true continues to the mail step.

If the site sets a Content Security Policy, allow challenges.cloudflare.com for scripts, frames and connections.

For tests, TURNSTILE_VERIFY_URL replaces the Cloudflare address (the kit’s tests use a stand-in server). The .NET backend reads the same variable. Do not set it in production.

What can go wrong

What’s next

• Forms for the rest of the form options.
• GitHub Actions and Azure DevOps for the build variable.