Turnstile overview

The smallest capability in the kit, and one of the most useful. One piece of stackable middleware, no tables, a read-only route on the control plane, a widget page for native apps, and one question answered: is this a human?

It is not a verification strategy, and that distinction is the whole design

A route’s verification strategy answers who is this? — bearer, session, signed webhook, control plane, public. A humanity check answers is this a human?

Those are different questions, so a humanity check can never be a route’s identity gate. It is middleware that stacks on top of whatever the route already does:

app.use("/signup", turnstile());                       // public route, now bot-gated
app.use("/auth/magic-link", turnstile({ action: "login" }));
app.use("/lead", turnstile({ mode: "invisible" }));

A public signup route that still requires a token. A magic-link route that gates credential entry. A lead form that runs the check silently. Same middleware, three placements.

It fails closed

A missing token, a failed verdict, an action mismatch, an unreachable verification service, a malformed response — all deny. A bot gate that opens when it cannot check is not a bot gate.

Three error classes on the gate, and the third is the one worth knowing about:

CodeStatusWhen
turnstile/missing_token400No token where one was required
turnstile/failed403The token did not pass, or the check could not complete
turnstile/config500The deployment is at fault — a missing, malformed or unrecognized secret, or a test key outside dev, staging and a feature build

A wrong secret is not a failed challenge. Cloudflare answers invalid-input-secret for a secret it never issued, and every request is refused for as long as it is wired. That is a 500 rather than a 403 on purpose: a 403 would send whoever is debugging it to look at the user, which is the wrong person and an hour gone. The 500’s action line names the command that fixes it.

Binding a token to its route

Pass action and the middleware asserts the returned action matches, denying on mismatch. That binds a token to the route it was solved for, so a token harvested from your signup form cannot be replayed against your login.

Test keys, where they belong

dev and staging get Cloudflare’s documented test keys, wired automatically by pithy turnstile provision, and a feature build resolves the same always-pass pair by default. Production gets a real widget bound to your real hostname.

The gate enforces that boundary rather than trusting it: Cloudflare flags its own answers from a test key, so a Worker stamped prod — or stamped nothing — refuses one. A secret that passes everybody must not be able to stand in for a widget.

The same flag is what lets dev, staging and a feature build sign in at all: a test key’s answer carries no action, which an action-bound login gate would otherwise refuse.

Which widget guards each environment

A management client can ask. GET /turnstile/admin/widgets, behind the turnstile:widgets:read control-plane scope, reports the sitekey in force for the Worker’s environment, whether it is a real widget or a test key, and for a real one how its challenges went, from Cloudflare’s Turnstile analytics. A test key where one belongs is reported as deliberate, never as zero challenges. A test key in prod is reported as broken. The reference has the four states.

It reads on the application’s one runtime token, adding analytics:read to it. Turnstile holds no Cloudflare token of its own.

A widget a phone can render

A native app has no page to draw Cloudflare’s widget into, so the Worker serves one. GET /turnstile/widget is a public page on the Worker’s own origin that renders the login widget for that environment and posts the solved token back over window.ReactNativeWebView.postMessage. The app loads it in react-native-webview and sends the token where config’s token says, as a browser would: the cf-turnstile-response body field by default, or the header it names. Auth’s sign-in gate reads it from the same place. pithy ui add react-native scaffolds exactly that.

The production widget’s allowed hostnames must include the Worker’s origin, or production refuses the challenge. pithy turnstile provision binds the widget to the Worker’s production hostname, so a provisioned widget already does; one made by hand has to list it. The reference has the messages the page posts.

What it deliberately does not do

It ships no front-end component. Your app renders the widget with the public sitekey and posts the response token; the middleware verifies it. The stubs pithy ui add react and pithy ui add react-native scaffold include a widget that does exactly that, reading the sitekey from the composed config, and the React Native one loads the Worker’s widget page on a phone.

It has no tables, no migrations and no bindings. There is nothing durable to provision beyond the widget, its secret and the account it lives in, and nothing else to clean up.

It does not rate-limit. Auth’s edge limiter and its per-action limiter do that, and they answer a different question again — how often rather than who or whether human.

It has no deep-dives, and the cluster should stay that way. There is not more to say.

When you would reach for it

Any public route that costs you something when a bot finds it: signup, magic-link send, one-time-code send, a lead form, a contact form, an invite acceptance.

Compose it beside auth and the two integrate with no wiring at all — auth auto-gates its own magic-link and one-time-code send routes when turnstile is present.

What it needs

It requires secrets: the widget secrets and the account record are read through the registry, and so is the runtime token the widget read uses.

auth is optional, and composing both is where the zero-config integration happens.

ESC