@pithy-sh/turnstile 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/turnstile
+
+A Cloudflare Turnstile humanity check for Pithy. One piece of stackable middleware. No tables of its own.
+
+It answers one question — *is this a human?* — and stacks on top of any route's real verification strategy. It is not one itself.
+
+```sh
+pithy add turnstile
+```
+
+**Documentation: [pithy.sh/docs/capabilities/turnstile](https://pithy.sh/docs/capabilities/turnstile).** Overview, adding it, using it, and the reference: provisioning, the widget rules, dev values.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pithy-sh/turnstile",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/turnstile"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "hono": "^4.13.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,30 @@
+{
+  "name": "turnstile",
+  "package": "@pithy-sh/turnstile",
+  "requiredBindings": [],
+  "peerCapabilities": ["secrets"],
+  "optionalCapabilities": ["auth"],
+  "secrets": [
+    {
+      "name": "turnstile-secret-keys",
+      "origin": {
+        "kind": "obtained",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/turnstile/get-started/widget-management/dashboard/"
+      },
+      "rotation": {
+        "kind": "provider",
+        "issuer": "cloudflare",
+        "documentation": "https://developers.cloudflare.com/api/resources/turnstile/subresources/widgets/methods/rotate_secret/"
+      }
+    }
+  ],
+  "whenToEnable": "Stop bots at credential-entry and form-submit points without asking real users to prove themselves. Stacks a Cloudflare Turnstile humanity check on any route — magic-link and OTP login, signup, lead capture, contact. dev and staging wire Cloudflare's test keys automatically; only `prod` provisions a real widget. The widget secret is stored and read through @pithy-sh/secrets, so the secrets capability is required.",
+  "scaffold": [
+    "Edit `turnstile({ ... })` in pithy.config.ts: declare the widget mode(s) you use (`visible` for pages where the challenge should be seen, like login; `invisible` for silent forms) and the `protect` map (action → mode). `login` is gated by the visible widget by default. Social/OAuth login is never gated.",
+    "Ensure the secrets capability is provisioned (`pithy add secrets` then `pithy secrets provision`) — the turnstile widget secret is stored and read through @pithy-sh/secrets, which the secrets capability sets up.",
+    "Run `pithy turnstile provision` — it writes Cloudflare's documented test secret for dev (into .dev.vars) and staging (into the staging secrets store), and provisions the real prod widget, storing its secret in the prod secrets store and writing the public sitekeys to config.",
+    "Stack the gate on a route: `import { turnstile } from \"@pithy-sh/turnstile/src/http/middleware\"` and `app.use(\"/signup\", turnstile())`. It reads the token from the `cf-turnstile-response` body field (or a header) and resolves the secret through @pithy-sh/secrets. Render the widget on your front-end with the public sitekey — Pithy ships no front-end component."
+  ],
+  "configOptions": []
+}

package/src/capability.ts

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { TurnstileClientProjection } from "./client/projection";
+import { TURNSTILE_LOGIN_ACTION, TurnstileConfig, type TurnstileConfigInput } from "./config/config";
+import { turnstileSecretsRegistry } from "./secret/registry";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/** The turnstile capability, with its resolved config attached for inspection (e.g. by `@pithy-sh/auth`). */
+export interface TurnstileCapability extends Capability {
+  turnstileConfig: TurnstileConfig;
+}
+
+/**
+ * The turnstile capability. It is **stateless** — no tables, no migrations, no routes, no global
+ * middleware, and **no bindings of its own**. Its widget secret is read through `@pithy-sh/secrets`
+ * (CLAUDE.md §secrets) — whatever bindings that read needs are contributed by the `secrets` capability,
+ * which this one depends on; turnstile contributes only its validated config. A humanity check stacks
+ * per-route via the `turnstile()` middleware (`@pithy-sh/turnstile/src/http/middleware`), never as a
+ * blanket middleware or an identity strategy.
+ *
+ * `@pithy-sh/auth` reads `turnstileConfig.protect` to decide which of its routes (magic-link, OTP) get a
+ * gate and at which widget mode; this package never imports auth.
+ */
+export function turnstile(config: TurnstileConfigInput = {}): TurnstileCapability {
+  const resolved = TurnstileConfig.parse(config);
+  const capability = defineCapability({
+    name: "turnstile",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    config: TurnstileConfig,
+    // The widget secret is read through @pithy-sh/secrets, so the secrets capability must be composed;
+    // createBackend fails fast if it isn't (rather than 500-ing each gated request).
+    dependsOn: ["secrets"],
+    // The slice of secrets turnstile reads — aggregated into the shared per-invocation accessor at startup.
+    secretRegistry: turnstileSecretsRegistry,
+    /**
+     * The client-safe projection — exactly what renders the login widget: the mode `protect.login`
+     * names, that widget's **public** sitekey for the environment being built, the **action** the widget
+     * must solve for, and where the front end must put the response token so the middleware finds it.
+     *
+     * The widget *secret* is never here: it lives in the secrets store (`turnstileSecretsRegistry`) and
+     * is read only inside the Worker, so a sitekey is the whole of what a browser sees — which is what
+     * it is for. Every unrenderable shape projects `{ enabled: false }` (no `login` gate, the named
+     * widget unconfigured, or no sitekey for this environment) so a screen branches instead of
+     * mounting a widget that cannot solve.
+     *
+     * **`action` rides here because the boundary was already being crossed** (#377). The label is baked
+     * into the token at render and asserted by the route, so it is one contract with two ends, and it
+     * was written out at both — where nothing before production could catch them disagreeing. See
+     * {@link TURNSTILE_LOGIN_ACTION} for why that is worse than it sounds and which gates hold it.
+     *
+     * The return type is {@link TurnstileClientProjection} — **declared, not inferred**. `ClientProjection`
+     * is `{ enabled: boolean }` plus a JSON catchall, which accepts anything this closure could return.
+     * The declared type is what makes a dropped field, and a `mode` widened by a third widget in
+     * `TurnstileConfig`, a compile error here rather than a browser's problem.
+     */
+    client: ({ environment }): TurnstileClientProjection => {
+      const mode = resolved.protect[TURNSTILE_LOGIN_ACTION];
+      if (!mode) return { enabled: false };
+      const widget = resolved.widgets[mode];
+      if (!widget) return { enabled: false };
+      // Indexed as a record: `environment` is any adopter name, not just the three documented keys.
+      const sitekeys: Record<string, string | undefined> = widget.sitekeys;
+      const sitekey = sitekeys[environment];
+      if (!sitekey) return { enabled: false };
+      return {
+        enabled: true,
+        mode,
+        sitekey,
+        // What the widget solves for, and what the route asserts. One statement, carried across.
+        action: TURNSTILE_LOGIN_ACTION,
+        // Shaped like the config it comes from (`token.field` / `token.header`), so a screen reads the
+        // same two names the middleware does. `header` is null rather than absent: `undefined` is not
+        // JSON, and the projection is inlined into a bundle with JSON.stringify.
+        token: { field: resolved.token.field, header: resolved.token.header ?? null },
+      };
+    },
+    requiredBindings: [],
+  });
+  return Object.assign(capability, { turnstileConfig: resolved });
+}
+
+/** Whether a capability is the turnstile capability — carries its resolved config. */
+export function isTurnstileCapability(capability: Capability): capability is TurnstileCapability {
+  return capability.name === "turnstile" && "turnstileConfig" in capability;
+}

package/src/client/projection.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What a browser may know about this project's Turnstile — the shape of `virtual:pithy/turnstile`.
+ *
+ * **This declaration is the contract, and the projection is checked against it.** It is written here
+ * rather than inferred from the closure that builds it, and that is the whole point: an inferred type
+ * follows whatever the producer last happened to say, so a projection that dropped a field, or widened
+ * `mode` because the config grew a third widget, would take the type with it and nothing would go red.
+ * Declared, the arrow is the thing that has to change. Adding a widget mode to `TurnstileConfig` is a
+ * compile error at `client:` until somebody decides, on purpose, whether a browser should see it.
+ *
+ * **This is the only statement of the shape.** `@pithy-sh/ui-react`'s `templates/client-env.d.ts` — the
+ * ambient declaration `pithy ui add react` copies into an adopter's Worker — is generated from this type
+ * by `@pithy-sh/vite`'s `clientEnvDeclaration.ts` (#398). The unions and the per-field doc comments below
+ * are emitted verbatim, so what is written here is what a screen author reads.
+ */
+export type TurnstileClientProjection =
+  | {
+      /**
+       * Turnstile is not composed, or has no renderable login widget for this environment. A screen
+       * branches rather than mounting a widget that cannot solve.
+       */
+      enabled: false;
+    }
+  | {
+      /** Turnstile is composed AND has a renderable login widget for this environment. */
+      enabled: true;
+      /** The public sitekey for the build's environment. The widget secret stays in the secrets store. */
+      sitekey: string;
+      /** The widget mode `protect.login` names. */
+      mode: "visible" | "invisible";
+      /**
+       * The action label the widget must be solved for. Render it, never retype it: the sign-in route
+       * asserts this exact string against the token, and dev and staging cannot notice a copy that has
+       * drifted — Cloudflare's test keys answer with no action at all, so the first environment that
+       * can tell is the one where a mismatch refuses every sign-in. #377.
+       */
+      action: string;
+      /** Where the response token goes: a body field, or a header when one is configured. */
+      token: {
+        /** The body field the middleware reads the token from. */
+        field: string;
+        /** The header it reads instead, or null when none is configured. */
+        header: string | null;
+      };
+    };

package/src/cloudflare-test.d.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare
+// config in `vitest.workers.config.ts`: the dedicated `SECRETS` D1 the widget secret's row lives in,
+// and the master key that decrypts it. `cloudflare:test` types its `env` as `Cloudflare.Env`, so test
+// bindings are declared by augmenting that interface.
+declare namespace Cloudflare {
+  interface Env {
+    SECRETS: D1Database;
+    /** The master-key config as a string (the `.dev.vars` shape), set in `vitest.workers.config.ts`. */
+    SECRETS_ENCRYPTION_KEYS: string;
+  }
+}

package/src/config/config.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The default request body field a Turnstile widget posts its response token in. Cloudflare's
+ * client-side widget names the hidden input `cf-turnstile-response`, so this is the field the
+ * middleware reads unless the app overrides it (or reads from a header instead).
+ */
+export const DEFAULT_TOKEN_FIELD = "cf-turnstile-response";
+
+/**
+ * **The action label of the passwordless sign-in gate, stated once for the whole kit (#377).**
+ *
+ * Turnstile bakes an action into the token at widget render and echoes it back from siteverify, and the
+ * gate refuses a token whose action is not the one the route expects. So the string is a contract with
+ * two ends — the widget that solves for it and the route that asserts it — and it used to be written out
+ * at both: `createAuthRoutes` stacked `turnstile({ action: "login" })` and the scaffolded
+ * `turnstile.tsx` declared its own `const ACTION = "login"`.
+ *
+ * **Nothing before production can notice the two disagreeing**, which is what makes a second copy
+ * unaffordable here rather than merely untidy. Cloudflare's always-pass test secret — the one
+ * `pithy turnstile provision` wires into dev and staging — answers with **no `action` field at all**, and
+ * the gate accepts exactly that answer in exactly those two environments (#374, {@link
+ * ../http/middleware.testKeyCarriesNoAction}). A drifted pair is therefore invisible in dev, invisible in
+ * staging, and in prod refuses **every** sign-in with a 403 that says the challenge failed — pointing an
+ * operator at the user rather than at the mismatch.
+ *
+ * So there is one statement, and both ends read it: the client projection carries it to the browser
+ * (`capability.ts`'s `client`, reaching the widget as `turnstileConfig.action`), and `@pithy-sh/auth`
+ * imports it for the gate it stacks. It is also the `protect` key the login mode is configured under, so
+ * the config default below is built from it too — three readers, no second literal.
+ *
+ * The gates that keep it that way, and where the blindness above is restated for whoever is reading one:
+ * `@pithy-sh/auth`'s `src/http/turnstileActionBinding.test.ts` (the route asserts the projected action)
+ * and `@pithy-sh/ui-react`'s `src/turnstileAction.test.tsx` (the widget solves for the projected action).
+ */
+export const TURNSTILE_LOGIN_ACTION = "login";
+
+/**
+ * The two widget modes Pithy provisions, in the app's own terms. `visible` is a Cloudflare *managed*
+ * widget (CF decides whether to show an interaction) — for a surface where the challenge should be
+ * seen, like a login page. `invisible` runs silently — for a form that should not interrupt, like a
+ * lead capture. The logical maximum is one of each per domain.
+ */
+export const TurnstileMode = z
+  .enum(["visible", "invisible"])
+  .describe("A Turnstile widget mode: `visible` (a CF managed widget) or `invisible` (runs silently).");
+export type TurnstileMode = z.infer<typeof TurnstileMode>;
+
+/**
+ * The public sitekey for one widget, per environment. The sitekey is public — the front-end renders
+ * the widget with it — so it lives in config, not in secrets. dev and staging carry Cloudflare's
+ * documented test keys (wired automatically, no real widget); `prod` carries the real widget's
+ * sitekey, written by `pithy turnstile provision`.
+ *
+ * The keys are Pithy's environment names verbatim, because that is what the client projection indexes
+ * them by — a bundle built for `prod` reads `sitekeys.prod`. They are not free-form labels.
+ */
+export const TurnstileSitekeys = z
+  .object({
+    dev: z.string().describe("Dev sitekey — a Cloudflare test key, wired automatically (no real widget is created)."),
+    staging: z
+      .string()
+      .describe("Staging sitekey — a Cloudflare test key, wired automatically (no real widget is created)."),
+    prod: z.string().describe("Prod sitekey — the real widget's public key, set by `pithy turnstile provision`."),
+  })
+  .describe("Per-environment public sitekeys the front-end renders the widget with.");
+export type TurnstileSitekeys = z.infer<typeof TurnstileSitekeys>;
+
+/** One provisioned widget: its per-environment public sitekeys. The mode is the key under `widgets`. */
+export const TurnstileWidget = z
+  .object({
+    sitekeys: TurnstileSitekeys.describe("Per-environment public sitekeys for this widget."),
+  })
+  .describe("A single Turnstile widget (one mode), with its per-environment public sitekeys.");
+export type TurnstileWidget = z.infer<typeof TurnstileWidget>;
+
+/**
+ * Where the middleware reads the response token from. By default it reads the `cf-turnstile-response`
+ * body field (form or JSON). Set `header` to read the token from a request header instead — useful for
+ * a JSON API or a mobile client that sends the token out-of-band.
+ */
+export const TurnstileTokenSource = z
+  .object({
+    field: z
+      .string()
+      .default(DEFAULT_TOKEN_FIELD)
+      .describe(
+        "Request body field carrying the token (form or JSON). Cloudflare's widget uses `cf-turnstile-response`.",
+      ),
+    header: z
+      .string()
+      .optional()
+      .describe("If set, read the token from this request header instead of the body field."),
+  })
+  .describe("Where the middleware reads the Turnstile response token from.");
+export type TurnstileTokenSource = z.infer<typeof TurnstileTokenSource>;
+
+/**
+ * Configuration for the turnstile capability, authored in `pithy.config.ts`. It declares which widgets
+ * the app uses (up to one `visible` and one `invisible` per domain), which protected actions get a
+ * humanity gate and at which mode, and where the token is read from. The widget *secret* is never here —
+ * it is stored and read through `@pithy-sh/secrets`; only the public sitekeys live in config.
+ *
+ * Social/OAuth login is deliberately never gated: the provider runs its own bot defense and the redirect
+ * flow carries no token. `@pithy-sh/auth` reads `protect` to stack `turnstile()` on its magic-link/OTP
+ * routes; this package never imports auth.
+ */
+export const TurnstileConfig = z
+  .object({
+    widgets: z
+      .object({
+        visible: TurnstileWidget.optional().describe(
+          "The visible (managed) widget — shows a challenge where it should be seen, e.g. a login page.",
+        ),
+        invisible: TurnstileWidget.optional().describe(
+          "The invisible widget — runs silently where a form should not be interrupted, e.g. lead capture.",
+        ),
+      })
+      .default({})
+      .describe("Up to two widgets per domain: one `visible`, one `invisible`. Declare only the modes you need."),
+    protect: z
+      .record(z.string(), TurnstileMode)
+      // Built from the constant, not written out again: the key an action is configured under and the
+      // action label a token is solved for are the same string, and #377 is what a second copy costs.
+      .default({ [TURNSTILE_LOGIN_ACTION]: "visible" })
+      .describe(
+        "Protected action → widget mode. `login` (magic-link, OTP) defaults to the visible widget; add your own form actions. Social/OAuth is never gated.",
+      ),
+    token: TurnstileTokenSource.default({ field: DEFAULT_TOKEN_FIELD }).describe(
+      "Where the response token is read from (body field by default, or a header).",
+    ),
+  })
+  .describe("Configuration for the turnstile humanity-check capability.");
+export type TurnstileConfig = z.output<typeof TurnstileConfig>;
+export type TurnstileConfigInput = z.input<typeof TurnstileConfig>;

package/src/error/errors.ts

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/turnstile` throw sugar. The `turnstile/*` codes live in core's closed `KitErrorPayload`
+ * union (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as `@pithy-sh/email`.
+ * Runtime code in this package throws one of these, never a plain `new Error`.
+ */
+
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface TurnstileErrorArgs {
+  /** Override the public, safe-to-expose message. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+/** The request carried no Turnstile response token where one was required. */
+export class TurnstileMissingTokenError extends PithyError {
+  constructor(args: TurnstileErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "turnstile/missing_token",
+        status: 400,
+        message: args.message ?? "A humanity-check token is required.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * The Turnstile token did not pass siteverify, or the check could not complete. The middleware fails
+ * closed — a siteverify network error or malformed response also raises this, so a bot gate never
+ * silently opens.
+ */
+export class TurnstileFailedError extends PithyError {
+  constructor(args: TurnstileErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "turnstile/failed",
+        status: 403,
+        message: args.message ?? "The humanity check did not pass.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The middleware is misconfigured — the secret-key binding is missing or empty. */
+export class TurnstileConfigError extends PithyError {
+  constructor(args: TurnstileErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "turnstile/config",
+        status: 500,
+        message: args.message ?? "Turnstile is not configured.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/http/middleware.ts

@@ -0,0 +1,306 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { workerIdentity } from "@pithy-sh/core/src/worker/identity";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import type { Context, MiddlewareHandler } from "hono";
+import { z } from "zod";
+import { DEFAULT_TOKEN_FIELD, type TurnstileMode } from "../config/config";
+import { TurnstileConfigError, TurnstileFailedError, TurnstileMissingTokenError } from "../error/errors";
+import { isTestKeyEnvironment, TEST_KEY_ENVIRONMENTS } from "../provision/testKeys";
+import { selectTurnstileSecret, TURNSTILE_SECRET_NAME, turnstileSecretsRegistry } from "../secret/registry";
+
+/** Cloudflare's server-side endpoint a Turnstile token is validated against. */
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+
+/**
+ * The siteverify error codes that name the **secret** rather than the token.
+ *
+ * The distinction is the whole point: every other code is a verdict about the caller, and these two are
+ * a verdict about the deployment. Cloudflare answers HTTP 400 for a secret it does not recognize, which
+ * the fail-closed branch used to render as `turnstile/failed` — a 403 telling an operator that a user
+ * failed a challenge, when the truth was that nobody could ever pass one here.
+ */
+const SECRET_FAULT_CODES = ["invalid-input-secret", "missing-input-secret"];
+
+/**
+ * The siteverify response, narrowed to what the gate checks. Cloudflare may add fields; Zod strips the
+ * rest. Validating the body is itself part of the security boundary — an unexpected shape is treated as
+ * a failure, never as a pass.
+ */
+export const SiteverifyResult = z
+  .object({
+    success: z.boolean().describe("Whether the token passed the humanity challenge."),
+    "error-codes": z.array(z.string()).default([]).describe("Machine-readable failure reasons; empty on success."),
+    action: z
+      .string()
+      .optional()
+      .describe("The action label baked into the token at widget render — compared against the expected action."),
+    metadata: z
+      .object({
+        result_with_testing_key: z
+          .boolean()
+          .optional()
+          .describe("Cloudflare's own flag: this verdict came from a documented test key, not a real widget."),
+      })
+      .optional()
+      .describe("Cloudflare's metadata about how the verdict was reached."),
+  })
+  .describe(
+    "The server-side Turnstile siteverify response, narrowed to the success flag, error codes, action, and test-key metadata.",
+  );
+export type SiteverifyResult = z.output<typeof SiteverifyResult>;
+
+/** Whether a verdict was produced by one of Cloudflare's documented test keys, by Cloudflare's own flag. */
+function fromTestingKey(result: SiteverifyResult): boolean {
+  return result.metadata?.result_with_testing_key === true;
+}
+
+/**
+ * A secret Cloudflare does not recognize is a deployment fault, and is reported as one.
+ *
+ * `turnstile/config` (500) rather than `turnstile/failed` (403), because the two go to different people:
+ * a 403 sends the operator looking at the user who was refused, and every such request is refused, so
+ * the search never converges. The `action` line names the command that fixes it.
+ */
+function assertSecretRecognized(codes: string[], status: number): void {
+  const fault = codes.find((code) => SECRET_FAULT_CODES.includes(code));
+  if (fault === undefined) return;
+  throw new TurnstileConfigError({
+    message: "The humanity check is not configured.",
+    action:
+      "Cloudflare does not recognize this widget's secret key. Run `pithy turnstile provision` for this environment.",
+    detail: `siteverify answered ${status} with "${fault}" — the secret, not the token, was refused.`,
+  });
+}
+
+/**
+ * The one exception to the action binding, and the only thing that made dev and staging sign-in
+ * possible: **a documented test key returns no action at all** (#374).
+ *
+ * Cloudflare's always-pass secret answers `success: true` with no `action` field, verified live against
+ * siteverify. `createAuthRoutes` stacks the gate as `turnstile({ action: "login" })`, so the binding
+ * compared `"login"` against nothing and denied every sign-in in the two environments provisioning
+ * wires that key into — a token that *was* valid, refused by a field the key never populates.
+ *
+ * Three conditions, and the exception needs all of them:
+ *
+ * 1. **Cloudflare says it is a test key** — `metadata.result_with_testing_key`, its own flag on its own
+ *    answer, not a comparison against a list of key strings we keep. A real widget's answer never
+ *    carries it, so no real deployment can reach this branch however its secret is spelled.
+ * 2. **No action came back at all.** An action that came back and *differs* is a token minted for
+ *    another action, which is exactly what the binding exists to refuse, and it is refused here too.
+ * 3. **The Worker says it is dev or staging** — {@link isTestKeyEnvironment}, off the stamped
+ *    `ENVIRONMENT` var, which nothing in a request can influence. `prod` is not in that list and an
+ *    unstamped Worker is not either, so production keeps the binding exactly as it was.
+ *
+ * The alternative was to relax the binding itself, which would have traded a real protection — a token
+ * solved for one action must not be replayable against another — for a developer's convenience.
+ */
+function testKeyCarriesNoAction(result: SiteverifyResult, environment: string | null): boolean {
+  return fromTestingKey(result) && result.action === undefined && isTestKeyEnvironment(environment);
+}
+
+/** The `error-codes` of a body we are not otherwise going to parse. Absent or unreadable reads as none. */
+async function errorCodesOf(response: Response): Promise<string[]> {
+  const raw: unknown = await response.json().catch(() => null);
+  const codes = (raw as { "error-codes"?: unknown } | null)?.["error-codes"];
+  return Array.isArray(codes) ? codes.filter((code): code is string => typeof code === "string") : [];
+}
+
+/** Options the `turnstile()` middleware accepts when a route stacks it. */
+export interface TurnstileOptions {
+  /**
+   * Which widget this route gates. Required only when the app runs both a `visible` and an `invisible`
+   * widget; with a single widget it is inferred. Selects the entry from the resolved turnstile secret.
+   */
+  mode?: TurnstileMode;
+  /** Body field carrying the token (form or JSON). Defaults to `cf-turnstile-response`. */
+  field?: string;
+  /** If set, read the token from this request header instead of the body field. */
+  header?: string;
+  /**
+   * The expected action label. Turnstile bakes the action into the token at widget render and returns it
+   * from siteverify; when set, the middleware asserts the returned action matches and denies on mismatch —
+   * binding a token to the route it was solved for (no cross-action reuse on a shared widget).
+   */
+  action?: string;
+}
+
+/**
+ * Verify a Turnstile token server-side against `/siteverify`. **Fails closed:** a transport error, a
+ * non-OK status, a non-JSON body, or an unexpected shape all raise `turnstile/failed` rather than
+ * letting the request through — a bot gate must never silently open. A well-formed response (whether the
+ * token passed or not) is returned for the caller to act on.
+ *
+ * The one failure that does **not** come back as `turnstile/failed` is a secret Cloudflare does not
+ * recognize: that is `turnstile/config`, because it is a verdict about the deployment rather than about
+ * the caller. See {@link assertSecretRecognized}. Both directions still deny.
+ */
+export async function siteverify(
+  secret: string,
+  token: string,
+  options?: { remoteIp?: string },
+): Promise<SiteverifyResult> {
+  // Note: Turnstile siteverify takes no `action` request param — the action is a *response* field the
+  // caller compares (done by the middleware). Only secret, response, and remoteip are sent.
+  const body = new URLSearchParams({ secret, response: token });
+  if (options?.remoteIp) body.set("remoteip", options.remoteIp);
+
+  let response: Response;
+  try {
+    response = await fetch(SITEVERIFY_URL, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+  } catch (cause) {
+    throw new TurnstileFailedError(
+      { detail: `siteverify request failed: ${cause instanceof Error ? cause.message : String(cause)}` },
+      { cause },
+    );
+  }
+
+  if (!response.ok) {
+    assertSecretRecognized(await errorCodesOf(response), response.status);
+    throw new TurnstileFailedError({ detail: `siteverify responded ${response.status} ${response.statusText}.` });
+  }
+
+  let raw: unknown;
+  try {
+    raw = await response.json();
+  } catch (cause) {
+    throw new TurnstileFailedError({ detail: "siteverify returned a non-JSON body." }, { cause });
+  }
+
+  const parsed = SiteverifyResult.safeParse(raw);
+  if (!parsed.success) {
+    throw new TurnstileFailedError({ detail: `siteverify response had an unexpected shape: ${parsed.error.message}` });
+  }
+  // A 200 carrying a secret-side code is not what Cloudflare answers today (it uses 400), but the
+  // classification belongs to the code rather than to the status, so both routes reach the same verdict.
+  assertSecretRecognized(parsed.data["error-codes"], response.status);
+  return parsed.data;
+}
+
+/**
+ * Read the response token from the configured header, or the body field. Form posts (the widget's own
+ * submit) parse as form data; everything else — JSON, a `+json` media type, or a request with no/odd
+ * content-type (some mobile/`fetch` clients) — is read as JSON. Any parse failure yields `null`, which the
+ * caller turns into a missing-token denial, so this stays fail-closed.
+ *
+ * **The body is read off a clone, never off the request itself.** This gate is stacked on top of a route
+ * it does not own — `@pithy-sh/auth` mounts it on the magic-link and OTP paths, which are Better Auth's,
+ * and the handler there forwards `c.req.raw` untouched. Reading through `c.req.json()`/`c.req.parseBody()`
+ * consumes that stream (Hono's body cache calls `raw.json()`), so a request that PASSED the humanity check
+ * would then fail downstream with "Body has already been read" — the gate would work only when it denied.
+ * Cloning costs one buffer copy of a token-sized body and keeps the original readable by whoever follows.
+ */
+async function readToken(c: Context, field: string, header?: string): Promise<string | null> {
+  if (header) {
+    return c.req.header(header) ?? null;
+  }
+  const contentType = (c.req.header("content-type") ?? "").toLowerCase();
+  const isForm =
+    contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data");
+  const probe = c.req.raw.clone();
+  const body = isForm
+    ? await probe
+        .formData()
+        .then((form) => Object.fromEntries(form.entries()) as Record<string, unknown>)
+        .catch(() => null)
+    : ((await probe.json().catch(() => null)) as Record<string, unknown> | null);
+  const value = body?.[field];
+  return typeof value === "string" ? value : null;
+}
+
+/**
+ * The Turnstile humanity-check middleware. Stack it on **any** route, on top of that route's real
+ * verification strategy (`public`, `bearer`, `session`, …) — it answers "is this a human?", never
+ * "who is this?", so it is never an identity strategy of its own (CLAUDE.md §HTTP).
+ *
+ * It resolves the widget secret through the one `secretsStore` reader (CLAUDE.md §secrets: every secret is
+ * declared in a registry and read through the reader; the registry — `turnstileSecretsRegistry` — decides
+ * where it lives), reads the response token from the request, verifies it against Cloudflare siteverify,
+ * and on success lets the request continue to its real strategy. The app must have the `secrets`
+ * capability (it provides whatever the read needs); the secret is the encrypted row in its `SECRETS` D1,
+ * in local dev exactly as deployed, which is what `pithy turnstile provision` writes. It
+ * **fails closed** — every failure throws a `PithyError` subclass (all carrying a `turnstile/*` code), so
+ * a bot gate never silently opens. Register `pithyErrorHandler` on the app to map these to HTTP responses.
+ *
+ * **Two failures are the deployment's, not the caller's, and say so.** A secret Cloudflare does not
+ * recognize, and a documented test key outside dev/staging, both raise `turnstile/config` — see
+ * {@link assertSecretRecognized} and {@link testKeyCarriesNoAction} for why blaming the caller for
+ * either one costs an operator an hour.
+ *
+ * @throws {@link TurnstileMissingTokenError} (`turnstile/missing_token`, 400) — no token in the request.
+ * @throws {@link TurnstileFailedError} (`turnstile/failed`, 403) — the token did not pass siteverify, its
+ *   action did not match a configured `action`, or the check could not complete (an unreachable/malformed
+ *   siteverify response also lands here, fail-closed).
+ * @throws {@link TurnstileConfigError} (`turnstile/config`, 500) — the secret is missing, malformed, has
+ *   no entry for the route's widget mode, is one Cloudflare does not recognize, or is a test key in an
+ *   environment that has no business holding one (the `secretsStore` read is rewrapped to this too, so
+ *   the gate's contract stays `turnstile/*`).
+ */
+export function turnstile(options: TurnstileOptions = {}): MiddlewareHandler {
+  const field = options.field ?? DEFAULT_TOKEN_FIELD;
+  return async (c, next) => {
+    let secret: string;
+    try {
+      const store = await sharedSecretsStore(c.env as unknown as SecretsStoreEnv, turnstileSecretsRegistry);
+      secret = selectTurnstileSecret(store.get(TURNSTILE_SECRET_NAME), options.mode);
+    } catch (cause) {
+      // selectTurnstileSecret already throws turnstile/config; the reader throws secrets/* — rewrap those
+      // so the gate fails closed under its own contract (a missing secret is a misconfig, not a 404 route).
+      if (cause instanceof TurnstileConfigError) throw cause;
+      throw new TurnstileConfigError(
+        { detail: `Could not resolve the turnstile secret: ${cause instanceof Error ? cause.message : String(cause)}` },
+        { cause },
+      );
+    }
+
+    const token = await readToken(c, field, options.header);
+    if (!token) {
+      throw new TurnstileMissingTokenError({
+        detail: options.header
+          ? `No token in the ${options.header} header.`
+          : `No "${field}" field in the request body.`,
+      });
+    }
+
+    const environment = workerIdentity(c.env).environment;
+    const result = await siteverify(secret, token, { remoteIp: c.req.header("CF-Connecting-IP") });
+
+    // A documented test key answers for everybody who asks, so where it is wired is the whole of what
+    // makes it acceptable. Outside the two environments provisioning writes one into, its presence is a
+    // misconfiguration and is reported as one — an always-pass secret on a production login page is a
+    // door, and it should be the loudest thing in the log rather than a quiet 200.
+    if (fromTestingKey(result) && !isTestKeyEnvironment(environment)) {
+      throw new TurnstileConfigError({
+        message: "The humanity check is not configured.",
+        action: `This widget secret is a Cloudflare Turnstile test key, which passes every caller. Run \`pithy turnstile provision\` for the real widget, or stamp ENVIRONMENT as ${TEST_KEY_ENVIRONMENTS.join(" or ")} in this Worker's wrangler.jsonc if that is what this deployment is.`,
+        detail: `siteverify set metadata.result_with_testing_key on environment "${environment ?? "unstamped"}".`,
+      });
+    }
+
+    if (!result.success) {
+      throw new TurnstileFailedError({
+        detail: `siteverify rejected the token: ${result["error-codes"].join(", ") || "no error codes"}.`,
+      });
+    }
+    // Bind the token to the expected action when one is configured — fail closed on mismatch so a token
+    // solved for another action on the same widget can't be replayed here.
+    if (
+      options.action !== undefined &&
+      result.action !== options.action &&
+      !testKeyCarriesNoAction(result, environment)
+    ) {
+      throw new TurnstileFailedError({
+        detail: `Turnstile action mismatch: expected "${options.action}", got "${result.action ?? "none"}".`,
+      });
+    }
+
+    await next();
+  };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add turnstile` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory plus the config types an app declares. The `turnstile()` *middleware* is
+ * imported by deep path (`@pithy-sh/turnstile/src/http/middleware`) at the route that stacks it — this is
+ * the documented contract, not a barrel over the package.
+ */
+
+export { isTurnstileCapability, type TurnstileCapability, turnstile } from "./capability";
+export { type TurnstileConfig, type TurnstileConfigInput, TurnstileMode } from "./config/config";

package/src/provision/provisionTurnstile.ts

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { resourceName } from "@pithy-sh/core/src/naming/resource";
+import type { TurnstileConfig, TurnstileMode } from "../config/config";
+import type { TurnstileSecrets } from "../secret/registry";
+import { TEST_SECRET, testSitekey } from "./testKeys";
+
+/** The widget modes a config enables, in `visible`-then-`invisible` order. */
+export function enabledModes(config: TurnstileConfig): TurnstileMode[] {
+  const modes: TurnstileMode[] = [];
+  if (config.widgets.visible) modes.push("visible");
+  if (config.widgets.invisible) modes.push("invisible");
+  return modes;
+}
+
+/** The deployed environments whose secret is written to the managed store (dev is local, via `.dev.vars`). */
+export const MANAGED_ENVIRONMENTS = ["staging", "prod"] as const;
+export type ManagedTurnstileEnv = (typeof MANAGED_ENVIRONMENTS)[number];
+
+/**
+ * The one environment a real widget is created for, named once rather than spelled at four call sites.
+ *
+ * It appears in the widget's own name, in the secret write, and in the sitekey write, and those three
+ * have to agree: a widget provisioned under one environment and a secret written under another is a
+ * production login page verifying against a key nobody holds.
+ */
+const REAL_WIDGET_ENV = "prod" satisfies ManagedTurnstileEnv;
+
+/** The Worker var the public sitekey for a mode is surfaced under, for the front-end to render with. */
+export function sitekeyVarName(mode: TurnstileMode): string {
+  return `TURNSTILE_SITEKEY_${mode.toUpperCase()}`;
+}
+
+/**
+ * The production widget's name: `<project>-prod-turnstile-<mode>` (docs/NAMING.md).
+ *
+ * Stable per project and mode, because provisioning is reuse-or-create **by name** — which is exactly
+ * why the project segment is not optional. Turnstile widgets are account-scoped and the account's widget
+ * list is flat, so an unscoped name means a second Pithy project in one account adopts the first's widget
+ * and `turnstile deprovision` deletes it out from under them.
+ *
+ * `prod` sits in the environment slot because that is the environment this widget serves, and it is the
+ * only one: dev and staging wire Cloudflare's documented test keys and create no widget at all. If a real
+ * staging widget ever lands, it takes `staging` in the same slot and nothing else moves.
+ *
+ * **The generic composer rather than the facade**, and for the one reason the facade allows: a Turnstile
+ * widget is not a namespace `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for.
+ * The facade's premise is that a kind of thing brings its own number; inventing one here would be the
+ * flaw it was built to remove. So this takes the conservative default until that namespace lands.
+ */
+export function productionWidgetName(project: string, mode: TurnstileMode): string {
+  return resourceName({ project, env: REAL_WIDGET_ENV, thing: `turnstile-${mode}` });
+}
+
+/** Build the combined secret object for the enabled modes, all set to one key value. */
+function buildSecrets(modes: TurnstileMode[], key: string): TurnstileSecrets {
+  const secrets: TurnstileSecrets = {};
+  for (const mode of modes) secrets[mode] = { key };
+  return secrets;
+}
+
+/** The public test sitekeys for the enabled modes, keyed by their Worker var name. */
+function testSitekeyVars(modes: TurnstileMode[]): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const mode of modes) vars[sitekeyVarName(mode)] = testSitekey(mode);
+  return vars;
+}
+
+/**
+ * The side-effecting steps provisioning performs, injected so the orchestration is pure and unit-testable
+ * (the live implementation lives in the CLI). The secret is the one `d1`, JSON turnstile secret read by the
+ * middleware through `@pithy-sh/secrets` (CLAUDE.md §secrets); dev gets it via `.dev.vars`, deployed
+ * environments via the manager's write Workflow. Every step is idempotent.
+ */
+export interface TurnstileProvisioner {
+  /**
+   * Refuse the run when a widget **outside this project** already claims the production domain. Cloudflare
+   * permits several widgets per domain; Pithy does not, because a second widget on one domain is almost
+   * always someone's forgotten first attempt, and the two are indistinguishable to a front-end holding one
+   * sitekey. This project's own widgets are the expected steady state and never trip it.
+   */
+  assertDomainAvailable(domain: string): Promise<void>;
+  /** dev: upsert the turnstile secret (JSON) and the public sitekey vars into `.dev.vars`. */
+  writeDev(secret: string, sitekeys: Record<string, string>): Promise<void>;
+  /** Write the turnstile secret (JSON) to a deployed environment's managed store (via the manager). */
+  writeManagedSecret(env: ManagedTurnstileEnv, secret: string): Promise<void>;
+  /** Write the public sitekey vars into a deployed environment's worker vars. */
+  writeManagedSitekeys(env: ManagedTurnstileEnv, sitekeys: Record<string, string>): Promise<void>;
+  /** Reuse the production widget by name, else create it bound to the domain. `secret` is null on reuse. */
+  ensureProductionWidget(mode: TurnstileMode, domain: string): Promise<{ sitekey: string; secret: string | null }>;
+}
+
+/** The inverse steps, for teardown — each guarded so a missing resource is a no-op. */
+export interface TurnstileDeprovisioner {
+  /** Delete the production widget for a mode if it exists. */
+  deleteProductionWidget(mode: TurnstileMode): Promise<void>;
+  /** Delete the turnstile secret from every deployed environment's managed store. */
+  deleteManagedSecret(): Promise<void>;
+  /** Clear the turnstile secret + sitekey vars from `.dev.vars`. */
+  clearDev(modes: TurnstileMode[]): Promise<void>;
+  /** Clear the sitekey vars from the deployed environments' worker vars. */
+  clearManagedSitekeys(modes: TurnstileMode[]): Promise<void>;
+}
+
+/** What provisioning resolved for one widget mode. */
+export interface ProvisionedWidget {
+  mode: TurnstileMode;
+  /** The production public sitekey. */
+  sitekey: string;
+  /** True if the production widget was created this run (false on idempotent reuse). */
+  created: boolean;
+}
+
+export interface TurnstileProvisionResult {
+  modes: TurnstileMode[];
+  widgets: ProvisionedWidget[];
+  /**
+   * Whether the production secret was (re)written this run. False on idempotent reuse — Cloudflare never
+   * returns an existing widget's secret, so it can't be recomposed; the caller should warn that an absent
+   * production secret won't be healed by re-running (a deprovision + provision is needed).
+   */
+  productionSecretWritten: boolean;
+}
+
+/** The modes to provision and the production domain the real widget binds to. */
+export interface TurnstilePlan {
+  /** The enabled widget modes (from `config.widgets`). At least one. */
+  modes: TurnstileMode[];
+  /** The production domain the real widget is bound to (resolved from per-environment config). */
+  productionDomain: string;
+  /**
+   * Provision even though a foreign widget already covers the domain (`--allow-shared-domain`). The
+   * escape hatch for the one legitimate case: an adopter who already runs a hand-made widget on that
+   * host and is not ready to retire it. Off by default — the refusal is the useful answer.
+   */
+  allowSharedDomain?: boolean;
+}
+
+/**
+ * Provision Turnstile across environments. **dev and staging** get Cloudflare's documented test secret
+ * (written per-environment — dev to `.dev.vars`, staging to its managed store); **`prod`** gets a real
+ * widget per mode, bound to the domain, its secret written to the production managed store, and its public
+ * sitekey to the production worker vars. Idempotent: a re-run reuses existing production widgets and skips
+ * the production secret write (whose value can't be recovered from Cloudflare). A *mixed* production state
+ * (some widgets new, some pre-existing) can't compose a consistent secret, so it errors with guidance
+ * rather than write a half-secret. Before anything is written, a production domain a *foreign* widget
+ * already covers is refused (`allowSharedDomain` opts out).
+ */
+export async function provisionTurnstile(
+  provisioner: TurnstileProvisioner,
+  plan: TurnstilePlan,
+): Promise<TurnstileProvisionResult> {
+  // First, before a single write: a domain already covered by a foreign widget is refused, so a refusal
+  // leaves no half-wired `.dev.vars` or staging secret behind.
+  if (!plan.allowSharedDomain) await provisioner.assertDomainAvailable(plan.productionDomain);
+
+  const testSecret = JSON.stringify(buildSecrets(plan.modes, TEST_SECRET));
+  const sitekeys = testSitekeyVars(plan.modes);
+
+  await provisioner.writeDev(testSecret, sitekeys);
+  await provisioner.writeManagedSecret("staging", testSecret);
+  await provisioner.writeManagedSitekeys("staging", sitekeys);
+
+  const widgets: ProvisionedWidget[] = [];
+  const realSecrets: TurnstileSecrets = {};
+  const prodSitekeys: Record<string, string> = {};
+  for (const mode of plan.modes) {
+    const { sitekey, secret } = await provisioner.ensureProductionWidget(mode, plan.productionDomain);
+    prodSitekeys[sitekeyVarName(mode)] = sitekey;
+    widgets.push({ mode, sitekey, created: secret !== null });
+    if (secret !== null) realSecrets[mode] = { key: secret };
+  }
+
+  const created = widgets.filter((widget) => widget.created).length;
+  if (created > 0 && created < plan.modes.length) {
+    throw new ValidationError({
+      message: "Turnstile production widgets are in a mixed state — some exist, some were just created.",
+      action: "Run `pithy turnstile deprovision`, then provision again to write a consistent production secret.",
+    });
+  }
+  // All new → write the freshly-composed production secret. All reused → Cloudflare won't return the
+  // existing widgets' secret, so it can't be recomposed and is left as-is (the caller warns).
+  const productionSecretWritten = created === plan.modes.length;
+  if (productionSecretWritten) {
+    await provisioner.writeManagedSecret(REAL_WIDGET_ENV, JSON.stringify(realSecrets));
+  }
+  await provisioner.writeManagedSitekeys(REAL_WIDGET_ENV, prodSitekeys);
+
+  return { modes: plan.modes, widgets, productionSecretWritten };
+}
+
+/** Tear down Turnstile: delete each mode's production widget, the managed secret, and all config entries. */
+export async function deprovisionTurnstile(
+  deprovisioner: TurnstileDeprovisioner,
+  modes: TurnstileMode[],
+): Promise<{ modes: TurnstileMode[] }> {
+  for (const mode of modes) {
+    await deprovisioner.deleteProductionWidget(mode);
+  }
+  await deprovisioner.deleteManagedSecret();
+  await deprovisioner.clearDev(modes);
+  await deprovisioner.clearManagedSitekeys(modes);
+  return { modes };
+}

package/src/provision/testKeys.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { TurnstileMode } from "../config/config";
+
+/**
+ * Cloudflare's documented Turnstile test keys. dev and staging wire these instead of provisioning a
+ * real widget — they need no CF round-trip and make the positive/negative/challenge paths trivially
+ * testable. The *sitekeys* are public (the front-end renders with them); the *secrets* feed siteverify.
+ * https://developers.cloudflare.com/turnstile/troubleshooting/testing/
+ */
+export const TURNSTILE_TEST_KEYS = {
+  /** Public sitekeys, by widget mode and verdict. */
+  sitekey: {
+    /** Visible (managed) widget that always passes. */
+    visiblePass: "1x00000000000000000000AA",
+    /** Visible (managed) widget that always blocks. */
+    visibleBlock: "2x00000000000000000000AB",
+    /** Invisible widget that always passes. */
+    invisiblePass: "1x00000000000000000000BB",
+    /** A widget that always forces an interactive challenge. */
+    forceChallenge: "3x00000000000000000000FF",
+  },
+  /** Secret keys for siteverify, by verdict. */
+  secret: {
+    /** Secret that makes siteverify always pass. */
+    pass: "1x0000000000000000000000000000000AA",
+    /** Secret that makes siteverify always fail. */
+    fail: "2x0000000000000000000000000000000AA",
+  },
+} as const;
+
+/** The test sitekey for a mode's always-pass widget — what dev and staging render with. */
+export function testSitekey(mode: TurnstileMode): string {
+  return mode === "visible" ? TURNSTILE_TEST_KEYS.sitekey.visiblePass : TURNSTILE_TEST_KEYS.sitekey.invisiblePass;
+}
+
+/** The always-pass test secret — what dev and staging verify against. */
+export const TEST_SECRET = TURNSTILE_TEST_KEYS.secret.pass;
+
+/**
+ * The environments a test key belongs in: the two `provisionTurnstile` writes {@link TEST_SECRET} to.
+ * `prod` gets a real widget, and everything else gets nothing.
+ *
+ * Named here rather than spelled at the gate, because the gate and the provisioner have to agree about
+ * exactly one thing: a key that passes everybody is acceptable only where somebody deliberately wired
+ * one. `packages/turnstile/src/provision/provisionTurnstile.test.ts` pins the two lists together — the
+ * provisioner names its environments itself, so that test compares two independent statements rather
+ * than one constant with itself.
+ */
+export const TEST_KEY_ENVIRONMENTS = ["dev", "staging"] as const;
+
+/**
+ * Whether a Worker's stamped `ENVIRONMENT` is one a test key belongs in.
+ *
+ * `null` — an unstamped Worker — is **not** one. The environment is the whole of what separates "a key
+ * that passes everybody, on purpose, locally" from "a production login page anybody can walk through",
+ * so a Worker that cannot say which it is gets the strict answer.
+ */
+export function isTestKeyEnvironment(environment: string | null): boolean {
+  return environment !== null && (TEST_KEY_ENVIRONMENTS as readonly string[]).includes(environment);
+}

package/src/secret/registry.ts

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
+import { z } from "zod";
+import type { TurnstileMode } from "../config/config";
+import { TurnstileConfigError } from "../error/errors";
+
+/**
+ * One widget's secret. `key` is the value siteverify checks a token against; `lastRotatedAt` is
+ * informational and exists so a future rotation can track and overlap secrets without a reshape (the
+ * issue keeps rotation out of scope, but the storage must not preclude it).
+ */
+export const TurnstileSecretEntry = z
+  .object({
+    key: z.string().min(1).describe("The widget's secret key, used server-side at Cloudflare siteverify."),
+    lastRotatedAt: z
+      .string()
+      .optional()
+      .describe("ISO-8601 timestamp of the last rotation, if any. Informational; enables future rotation."),
+  })
+  .describe("One widget's secret key plus optional rotation metadata.");
+export type TurnstileSecretEntry = z.infer<typeof TurnstileSecretEntry>;
+
+/**
+ * The decrypted value of the turnstile secret: each configured widget's secret, keyed by mode. One
+ * secret serves one *or* both widgets, so adding the second never reshapes storage. The `secretsStore`
+ * reader parses and validates this against the registry entry's `valueType: "json"` schema; the
+ * middleware then selects the entry for the route's mode via {@link selectTurnstileSecret}.
+ */
+export const TurnstileSecrets = z
+  .strictObject({
+    visible: TurnstileSecretEntry.optional().describe("The visible (managed) widget's secret, if that widget is used."),
+    invisible: TurnstileSecretEntry.optional().describe("The invisible widget's secret, if that widget is used."),
+  })
+  .describe("The turnstile secret value: each configured widget's secret, keyed by mode.");
+export type TurnstileSecrets = z.infer<typeof TurnstileSecrets>;
+
+/**
+ * The registry name (D1 row key) the turnstile secret is stored under. The secret is a `d1`-backed,
+ * per-environment, JSON value — read through the one `secretsStore` reader like every other secret
+ * (CLAUDE.md §secrets), never off a raw binding.
+ */
+export const TURNSTILE_SECRET_NAME = "turnstile-secret-keys";
+
+/**
+ * Where a widget's secret key comes from, and where it is replaced.
+ *
+ * `obtained`: a widget is created in Cloudflare's dashboard and the secret key is handed over with the
+ * sitekey. Nothing can mint one — the value only verifies because Cloudflare already knows it, which is
+ * equally why the test keys dev and staging wire are a published pair rather than a generated one.
+ *
+ * `provider`: Cloudflare's API rotates a widget's secret and returns the new value, so this secret can
+ * genuinely replace itself. That is also why `rotatable` is true: a rotation leaves tokens minted under
+ * the old secret in flight, and both versions have to verify until they drain.
+ */
+// The dashboard page, not `turnstile/get-started/`. That one is a hub: it offers three implementation
+// methods and names no console, so an operator holding an expired secret key spends the click choosing
+// between links. This one carries the dashboard URL, `Add widget`, and "copy your sitekey and secret key".
+// #332 — `documentation` says "the specific settings page, not a product homepage", and a hub is a homepage.
+const TURNSTILE_WIDGETS_PAGE = "https://developers.cloudflare.com/turnstile/get-started/widget-management/dashboard/";
+const TURNSTILE_ROTATE_SECRET =
+  "https://developers.cloudflare.com/api/resources/turnstile/subresources/widgets/methods/rotate_secret/";
+
+/** The minimal registry the turnstile middleware reads its secret through (mirrors email's signing-key registry). */
+export const turnstileSecretsRegistry = defineSecretRegistry({
+  [TURNSTILE_SECRET_NAME]: {
+    backend: "d1",
+    scope: "environment",
+    rotatable: true,
+    valueType: "json",
+    schema: TurnstileSecrets,
+    origin: { kind: "obtained", issuer: "cloudflare", documentation: TURNSTILE_WIDGETS_PAGE },
+    rotation: { kind: "provider", issuer: "cloudflare", documentation: TURNSTILE_ROTATE_SECRET },
+  },
+});
+
+/**
+ * Select the secret key for the route's widget from the resolved secrets object. With one widget
+ * configured the only entry is used; with both, `mode` chooses. A missing/ambiguous selection is a
+ * `turnstile/config` — the gate is misconfigured, never silently open.
+ */
+export function selectTurnstileSecret(secrets: TurnstileSecrets, mode?: TurnstileMode): string {
+  const present = (Object.keys(secrets) as TurnstileMode[]).filter((m) => secrets[m]);
+  if (present.length === 0) {
+    throw new TurnstileConfigError({ detail: "The turnstile secret holds no widget secrets." });
+  }
+  if (!mode && present.length > 1) {
+    throw new TurnstileConfigError({
+      detail: "Two widgets are configured; pass turnstile({ mode }) to select which one this route gates.",
+      action: 'Set mode to "visible" or "invisible" on the turnstile() middleware for this route.',
+    });
+  }
+  const chosen = mode ?? present[0];
+  const entry = chosen ? secrets[chosen] : undefined;
+  if (!entry) {
+    throw new TurnstileConfigError({ detail: `The turnstile secret has no "${chosen}" widget entry.` });
+  }
+  return entry.key;
+}

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/turnstile knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/turnstile";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";