pithy turnstile

Wire Cloudflare’s Turnstile test keys into dev and staging, provision the real production widget, write every environment’s sitekey into pithy.config.ts, and tear it back down.

This is the provisioning half of the turnstile capability; bot-gating a public route is what the keys are for.

Synopsis

pithy turnstile provision [--worker <name>] [--allow-shared-domain] [--json]
pithy turnstile deprovision [--worker <name>] [--json]

Both subcommands need a Cloudflare account. A production widget is an account resource, and its secret is written to a managed store through a deployed dispatcher.

Flags

FlagApplies toDefaultPurpose
--worker <name>boththe project’s only WorkerThe web-facing Worker. Its production address binds the widget, its turnstile({ ... }) registration is read for the widget modes, and its pithy.config.ts gets the sitekeys. Required when the project has several
--allow-shared-domainprovisionfalseProvision even though another Turnstile widget already covers the domain
--jsonbothfalseOne line of machine-readable output

There is no --env. A widget binds to the domain a human loads it on, so prod is not a parameter: the production hostname is resolved from the target Worker, and dev and staging get Cloudflare’s documented test keys either way.

There is no --mode. Which widgets exist is declared in the Worker’s pithy.config.ts, and a flag would be a second source of truth that drifts the moment somebody enables one in config.

What it does

provision reads the enabled widget modes from the target Worker’s turnstile({ widgets }) — visible, invisible, or both — and resolves the production hostname through the one address resolver: the Worker’s domains declaration for prod, else its env.prod route, else a hand-set vars.BASE_URL. The modes and the sitekeys come from the same Worker. They used to come from two: the modes from the first Worker composing turnstile, the sitekeys to --worker.

Then it does five things. dev and staging get Cloudflare’s documented test secret, written per environment — dev to the dev secrets file, staging to its managed store. prod gets a real widget per mode, bound to that hostname, its secret written to the production managed store. The account the widgets live in is recorded as turnstile-account for dev, staging and prod, on every run, reuse included. The control-plane widget read needs it to ask Cloudflare’s analytics about a real widget, and an existing project picks it up by running provision again. It is an account id, not a token. Every environment’s public sitekey is written into the Worker’s pithy.config.ts, in the turnstile({ ... }) registration: the always-pass test sitekey for dev and staging, the real widget’s for prod. And any TURNSTILE_SITEKEY_* var an older provisioner left in that Worker’s wrangler.jsonc, or in dev.json, is removed. Only that Worker’s: a var the old split left in a Worker composing no turnstile, or in the project root’s .dev.vars, is yours to delete, and pithy doctor says so.

Every refusal is decided before anything is created. A domain a foreign widget already covers, production widgets of which some exist and some do not, and a sitekey the writer would refuse are all readable from the account’s widget list and the Worker’s config. So they are checked first, and a refused run leaves the account, the secret stores and every file as it found them. deprovision checks its sitekey edit before it deletes anything, for the same reason.

The sitekeys are a build input

The front end gets its sitekey from virtual:pithy/turnstile, which the pithy() Vite plugin inlines when the bundle is built, from widgets.<mode>.sitekeys.<environment>. So that block is where provisioning writes, and nothing it writes reaches a deployed bundle until the Worker is built and deployed again. Redeploy staging and prod after provisioning. The output says so.

A phone does not get its sitekey from a bundle. It loads the Worker’s public GET /turnstile/widget page in a WebView, and the deployed Worker resolves the sitekey for its own environment on each request. So a phone build needs no rebuild after provisioning, and the Worker’s redeploy is what puts the new sitekey in front of it.

A React Native app’s web build keeps its own copy. It reads its sitekey from the app’s src/pithy-config.generated.ts, from the projection for the environment EXPO_PUBLIC_PITHY_ENV names, so a prod web build renders prod’s sitekey. After provisioning, run pithy ui sync --app <name> to write the new sitekeys into that file, then build the web build again.

Before this, the sitekeys went into env.<name>.vars and .dev.vars as TURNSTILE_SITEKEY_<MODE>, where no code read them: the config stayed blank, no widget rendered, and sign-in failed closed on a successful provision.

String literals, in place, and nothing else. A value is replaced only where the config states a string literal. An expression that already resolves to the value — dev: testSitekey("visible") — is left alone. One that resolves to something else is refused by key, before a byte is written. After writing, the config is loaded back through the real loader, and a value the capability does not then resolve puts the file back and refuses.

A declared environment beyond dev, staging and prod has no sitekey. The projection indexes sitekeys by the environment being built, so a declared live renders no widget and sign-in there is blocked. Nothing provisions it — a test key is accepted only where one belongs, and the one real widget is prod’s — so provision names it in its output rather than leave the bundle to say enabled: false in silence.

A feature build needs nothing provisioned. The sitekey block carries an optional feature key, and a branch build left with none resolves Cloudflare’s always-pass test sitekey for the widget’s mode; the gate resolves the matching test secret the same way when the branch’s secrets store holds none. Both halves are defaults rather than writes, because a feature’s config and store are generated per branch and nothing this command writes could reach them — which is why a branch deployment used to answer 500 turnstile/config on every sign-in. State feature to run a real widget on a branch, or "" for no widget at all; provision never writes that key.

A test key belongs in dev, staging and a feature build, and nowhere else — the gate enforces that. Cloudflare flags its own answers from a documented test key, so a Worker stamped prod — or stamped nothing — refuses one with turnstile/config rather than letting a secret that passes everybody stand in for a widget. It is the same flag that lets those three sign in at all: a test key’s answer carries no action, which the login gate’s action binding would otherwise refuse.

Idempotent, with one consequence worth stating because it is the failure adopters hit. A re-run reuses an existing production widget rather than creating a second one — but Cloudflare never returns an existing widget’s secret, so it cannot be recomposed. A re-run over widgets that already exist leaves the stored secret exactly as it was, and reports that it did. If the secret was never stored, re-running will not heal it; deprovision then provision is what does.

--allow-shared-domain is the escape hatch for the one legitimate case: an adopter already running a hand-made widget on that host who is not ready to retire it. Off by default, because the refusal is the useful answer.

deprovision deletes the production widget for each declared mode, deletes the managed secret, the dev secret and turnstile-account in each, blanks each mode’s prod sitekey in pithy.config.ts, and removes any stranded sitekey var. The test sitekeys stay: they are Cloudflare’s published constants. It is the inverse of provision and the first half of the repair for a lost production secret. A Worker that composes no turnstile has nothing to deprovision, and deprovision says so and exits 0: api does not compose turnstile. Nothing to deprovision., or "modes": [] under --json.

--json

$ pithy turnstile provision --json
{"command":"turnstile provision","schemaVersion":1,"modes":["visible"],"widgets":[{"mode":"visible","sitekey":"0x4AAA…","created":true}],"productionSecretWritten":true,"sitekeys":{"visible":{"dev":"1x00000000000000000000AA","staging":"1x00000000000000000000AA","prod":"0x4AAA…"}},"strandedVarsRemoved":[{"name":"TURNSTILE_SITEKEY_VISIBLE","environment":"prod"}],"configFile":"apps/web/pithy.config.ts","redeployRequired":true,"environmentsWithoutSitekeys":[]}
KeyTypeMeaning
command"turnstile provision"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
modes"visible" and/or "invisible"The widget modes the config declares, and that this run acted on
widgetsobject[]One entry per production widget
widgets[].mode"visible" or "invisible"Which widget this entry is
widgets[].sitekeystringThe production public sitekey. Public by definition: the front end renders the widget with it
widgets[].createdbooleanTrue when this run created the widget; false on idempotent reuse
productionSecretWrittenbooleanWhether the production secret was written this run. False when every widget already existed
sitekeysobjectPer mode, the dev, staging and prod sitekeys written into pithy.config.ts. Public by definition
strandedVarsRemovedobject[]Each TURNSTILE_SITEKEY_* var removed this run: its name, and the environment whose vars held it (dev for the top level and dev.json). Empty on a project provisioned since the sitekey moved into config
configFilestringThe pithy.config.ts the sitekeys were written to, relative to the project root
redeployRequiredtrueAlways. The sitekeys are inlined when the front end is built, so no deployed bundle carries them until the Worker is deployed again
environmentsWithoutSitekeysstring[]Every declared environment beyond dev, staging, prod and a feature build. Builds there render no widget, and sign-in is blocked
$ pithy turnstile deprovision --json
{"command":"turnstile deprovision","schemaVersion":1,"modes":["visible","invisible"]}
KeyTypeMeaning
command"turnstile deprovision"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
modes"visible" and/or "invisible"The widget modes torn down. Empty when the Worker composes no turnstile, and nothing was

Errors

Each is a problem line then an action line. Under --json it is one {"error": …} line on stderr with exit, retryable and, where the cause is known, fix, and the process exits by its class — 2 for a call to fix, 3 for something to set up first, 4 to retry, 5 for a person.

The Worker does not compose turnstile. provision only. The target, --worker or the project’s only Worker, has no turnstile({ ... }) registration. The modes are never read from a sibling.

<worker> does not compose the turnstile capability.
Add `turnstile({ ... })` to <worker>'s pithy.config.ts (run `pithy add turnstile --worker <worker> --with-prerequisites`), or name the Worker that composes it with --worker.

Named with --worker, it is a usage error, exit 2: another --worker is the fix. The project’s only Worker, unnamed, is core/precondition_failed, exit 3, with that same pithy add as its fix, <worker> being the Worker’s apps/ directory. --with-prerequisites is there because turnstile declares secrets and that Worker does not compose it yet; a Worker that already does is named without it.

No widgets are declared. The capability is composed, but its widgets block is empty, so there is nothing to provision.

Another widget already covers the domain. A widget outside this project is bound to the production hostname. Refused before anything is created. --allow-shared-domain lets the run past it.

A Turnstile widget named "<name>" already covers <domain>.
Bind this project to a different domain, delete that widget, or re-run with --allow-shared-domain.

A sitekey cannot be written. The registration has no widgets.<mode>.sitekeys.<environment> key to write into, or that key is an expression that resolves to something else. The registration is found only where turnstile({ opens a line, so a config that writes the whole capabilities array on one line is refused for every key. Checked before a widget is created or deleted and before a secret or a file is written, so nothing is.

Could not write widgets.visible.sitekeys.staging in <path>. Each is an expression that resolves to something else.
Set widgets.visible.sitekeys.staging: "1x00000000000000000000AA" in the turnstile({ ... }) registration by hand, then run the command again. Only string literals are written.

The written sitekeys are not what the capability reads. The config, loaded back, resolves something other than what was written. The file is restored.

The sitekeys written to <path> are not what the turnstile capability reads. The file was restored.
Set widgets.visible.sitekeys.prod: "0x4AAA…" in the turnstile({ ... }) registration by hand.

The production widgets are in a mixed state. One mode’s widget exists and another’s does not, so no consistent production secret can be composed. Refused before anything is written — unless someone else creates or deletes a widget while the run is creating its own, which the run finds only after it has written the test secret and created a widget. Then the refusal says what it wrote, by mode and sitekey, so the one outcome is the whole account of the run. The provision it names is your own run again, every flag you gave it carried.

Turnstile production widgets are in a mixed state — some exist, some do not.
Starting over is the way to a consistent production secret. `pithy turnstile deprovision --worker web` deletes the Turnstile widget, whose sitekey every client embeds. That is a person's decision, not a fix. After it, `pithy turnstile provision --worker web` writes the secret again.

Cloudflare credentials are missing. No signed-in session and no account token. It is core/precondition_failed, exit 3.

Cloudflare credentials are missing.
Run pithy cloudflare connect to sign in, or export CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN for this project's account. Then run this again.

The Worker has no production address. Nothing resolved — no domains declaration, no env.prod route, no vars.BASE_URL. It is core/precondition_failed, exit 3: the call is right and the project is missing what it depends on.

<worker> has no production address.
Declare it in the Worker's pithy.config.ts — `domains: { prod: { pattern: "app.example.com", zone: "example.com" } }`. The Turnstile widget binds to that domain.

A domains block the kit refuses is a separate refusal, and it is fatal: an invalid domain is a config error, so the widget is not bound to an address you never declared. A domain is an ASCII hostname — no scheme, no path, no port, and no internationalized name, because Cloudflare Workers will not route one.

Several Workers, no --worker. The same input/required refusal pithy add raises, exit 2.

The project has no name. It scopes both the widget names and the dispatcher’s target, and it is never guessed: a wrong one reuses another project’s widget on provision and deletes a neighbor’s on teardown.

Examples

$ pithy turnstile provision
Test secret wired for dev and staging. 1 production widget(s) ready (1 new).
A feature deployment uses the same test pair by default — nothing to provision, and no redeploy of a branch needed for it.
Sitekeys written to apps/web/pithy.config.ts for dev, staging and prod.
The build inlines them. Redeploy staging and prod before the widget renders there.
Done.

A re-run over a widget that already exists says what it left alone:

$ pithy turnstile provision
Test secret wired for dev and staging. 1 production widget(s) ready (0 new).
A feature deployment uses the same test pair by default — nothing to provision, and no redeploy of a branch needed for it.
Production widgets already existed; their secret was left as-is. If the production gate returns turnstile/config, starting over is the way through. `pithy turnstile deprovision --worker web` deletes the Turnstile widget, whose sitekey every client embeds. That is a person's decision, not a fix. After it, `pithy turnstile provision --worker web` writes the secret again.
Sitekeys written to apps/web/pithy.config.ts for dev, staging and prod.
The build inlines them. Redeploy staging and prod before the widget renders there.
Done.

Repair a production gate answering turnstile/config. Deprovisioning deletes the production widget every client embeds the sitekey of, so it is a person’s decision rather than a fix:

pithy turnstile deprovision
pithy turnstile provision
ESC