@pithy-sh/core 0.1.0

package/src/controlPlane/http/verify.ts

@@ -0,0 +1,198 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ControlPlaneConfig } from "../config/config";
+import { ControlPlaneContext } from "../context";
+import type { ControlPlaneConnection } from "../data/connection";
+import { findVerifyingKey } from "../data/keyLifecycle";
+import {
+  ControlPlaneInsufficientScopeError,
+  ControlPlaneInvalidCredentialError,
+  ControlPlaneNotConnectedError,
+} from "../error/errors";
+import type { ReplayGuard } from "../replay/guard";
+import { type ControlPlaneRequirement, scopeCovers } from "../scope/scope";
+import { sha256Base64Url, timingSafeEqual } from "../token/digest";
+import { parseCompactJws, verifyEd25519 } from "../token/jws";
+
+/**
+ * The verification pipeline — the one place a control-plane call is decided.
+ *
+ * Written against a dependency object rather than a Hono context so the whole decision is testable
+ * without a Worker: every step below is exercised in `verify.test.ts` with a fake connection loader and
+ * a fake replay guard. The middleware in `guard.ts` is the thin part that reads those dependencies off
+ * the request.
+ *
+ * ## The header is not `Authorization`, and that is deliberate
+ *
+ * `@pithy-sh/auth` installs a global middleware that, for **any** request carrying an `authorization`
+ * header, builds a Better Auth instance and resolves a session against D1. A control-plane token on
+ * that header would therefore hit the auth stack on every management call — wasted work at best, and
+ * an unnecessary adjacency between two strategies that must stay separate. On {@link CONTROL_PLANE_HEADER}
+ * the seam is invisible to it: no Better Auth instance is ever constructed for a control-plane call,
+ * which is the structural fact behind "a control-plane call creates no user and no session".
+ *
+ * ## Order is a security property, not a style choice
+ *
+ * Nothing with a side effect happens before the signature verifies. In particular the `jti` is claimed
+ * **last**: claim it earlier and an unauthenticated caller could burn the ids of tokens it merely
+ * observed, denying a legitimate management client by replaying its own forgeries. Everything before
+ * step 7 is a lookup or a comparison, and grants nothing on its own.
+ *
+ * ## One error for every failure, on purpose
+ *
+ * Every step but the scope check raises the same {@link ControlPlaneInvalidCredentialError}. A caller
+ * cannot tell an unknown key from a bad signature from a replayed token, and so cannot use the response
+ * to learn how far a forgery got. The step goes in `detail`, which the HTTP codec strips and the log
+ * keeps. The scope failure is distinguished because by then the caller is proven legitimate — telling
+ * them which grant they lack is actionable and leaks nothing they do not already hold.
+ */
+
+/**
+ * The header names live in `../wire`, which imports nothing so that a browser can hold them — the far
+ * end of this seam calls the adopter's Worker directly, and importing them from here drags WebCrypto
+ * into a DOM-typed build.
+ *
+ * Re-exported because this path is already published: every caller outside the repo names
+ * `@pithy-sh/core/src/controlPlane/http/verify`, and moving a wire constant must not break the
+ * programs that speak the wire. Write new imports against `../wire`; everything in this repo already
+ * does.
+ */
+export { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire";
+
+/** What the pipeline needs from the outside world. Every one is injectable, so every step is testable. */
+export interface ControlPlaneVerifyDeps {
+  /** Load the connection a token addresses, by id. Null when no such connection exists here. */
+  loadConnection: (connectionId: string) => Promise<ControlPlaneConnection | null>;
+  /**
+   * How many connections this environment has at all. Called **only** when the lookup above missed, to
+   * separate "you have never connected anything" — worth saying plainly — from "that connection id is
+   * not one of ours", which must stay indistinguishable from every other credential failure or it
+   * becomes an oracle for enumerating connection ids.
+   */
+  countConnections: () => Promise<number>;
+  /** The single-use gate over `jti`. */
+  replay: ReplayGuard;
+  /** This Worker's environment name, checked against the connection's. */
+  environment: string;
+  /** The resolved seam config — the token and window bounds this Worker enforces. */
+  config: ControlPlaneConfig;
+  /** The clock, injected so a test can stand at any instant. */
+  now: () => Date;
+}
+
+/** One inbound call, reduced to what verification actually needs. */
+export interface ControlPlaneCall {
+  /** The compact JWS from {@link CONTROL_PLANE_HEADER}, or undefined when the caller sent none. */
+  token: string | undefined;
+  /** The raw request body bytes. Empty for a request that carries no body. */
+  body: Uint8Array;
+  /** What the route demands: one named scope, or merely a verified caller. */
+  requirement: ControlPlaneRequirement;
+}
+
+/** Raise the one credential error, naming the failing step for the log and nobody else. */
+function deny(step: string): never {
+  throw new ControlPlaneInvalidCredentialError({ detail: step });
+}
+
+/**
+ * Verify one control-plane call, or throw. Returns the context the handler runs under.
+ *
+ * The steps are numbered to match `docs/CONTROL-PLANE.md` §9.
+ */
+export async function verifyControlPlaneCall(
+  call: ControlPlaneCall,
+  deps: ControlPlaneVerifyDeps,
+): Promise<ControlPlaneContext> {
+  // 1. A credential was presented at all.
+  if (!call.token) deny("no control-plane credential presented");
+
+  // 2. Well-formed. Untrusted: a forged token parses exactly as cleanly as a genuine one.
+  const { header, claims, signingInput, signature } = parseCompactJws(call.token);
+
+  // 3. The connection the token addresses. A lookup, not a grant.
+  const connection = await deps.loadConnection(claims.aud);
+  if (!connection) {
+    if ((await deps.countConnections()) === 0) {
+      throw new ControlPlaneNotConnectedError({
+        detail: `no connection registered in environment ${deps.environment}`,
+      });
+    }
+    deny(`aud ${claims.aud} names no connection here`);
+  }
+
+  // 4. Environment. A staging credential must not reach production, and this is where that is true.
+  if (connection.environment !== deps.environment) {
+    deny(`connection ${connection.id} is bound to ${connection.environment}, not ${deps.environment}`);
+  }
+
+  // 5. Issuer. A validly-signed token minted by some other origin is still not for us.
+  if (claims.iss !== connection.issuer) {
+    deny(`iss ${claims.iss} is not the issuer connection ${connection.id} trusts`);
+  }
+
+  // 6. The key named by `kid`, if it is registered, unrevoked, and inside its window.
+  const key = findVerifyingKey(connection.keys, header.kid, deps.now());
+  if (!key) deny(`kid ${header.kid} is not a live key on connection ${connection.id}`);
+
+  // 7. The signature. Authenticity is established here and nowhere earlier.
+  if (!(await verifyEd25519(signingInput, signature, key.publicKey))) {
+    deny(`signature does not verify under kid ${header.kid}`);
+  }
+
+  // 8. The lifetime this Worker is willing to honor, whatever the token asked for.
+  const lifetime = claims.exp - claims.iat;
+  if (lifetime <= 0 || lifetime > deps.config.maxTokenLifetimeSeconds) {
+    deny(`token lifetime ${lifetime}s exceeds the ${deps.config.maxTokenLifetimeSeconds}s maximum`);
+  }
+
+  // 9. Expiry and issue time, within the configured skew.
+  const nowSeconds = Math.floor(deps.now().getTime() / 1000);
+  const skew = deps.config.clockSkewSeconds;
+  if (claims.exp <= nowSeconds - skew) deny(`token expired at ${claims.exp}, now ${nowSeconds}`);
+  if (claims.iat > nowSeconds + skew) deny(`token issued at ${claims.iat} is in the future, now ${nowSeconds}`);
+
+  // 10. The body digest. The signature covers the header and claims only, so without this a token could
+  //     be lifted onto a different body for the same route.
+  await verifyBodyDigest(call.body, claims.bodySha256);
+
+  // 11. Scope. Both sides must agree: what the adopter granted, and what this one token was minted for.
+  if (!scopeCovers(call.requirement, claims.scope, connection.scopes)) {
+    throw new ControlPlaneInsufficientScopeError({
+      detail: `required ${String(call.requirement)}; token carried ${claims.scope}; connection grants [${connection.scopes.join(", ")}]`,
+    });
+  }
+
+  // 12. Spend the token. Last, because it is the only step that writes anything.
+  if (!(await deps.replay.claim(claims.jti, connection.id))) {
+    deny(`jti ${claims.jti} was already spent`);
+  }
+
+  return ControlPlaneContext.parse({
+    connectionId: connection.id,
+    environment: connection.environment,
+    issuer: connection.issuer,
+    subject: claims.sub,
+    scope: claims.scope,
+    grantedScopes: connection.scopes,
+    keyId: key.keyId,
+    tokenId: claims.jti,
+  });
+}
+
+/**
+ * The body digest check. `bodySha256` is null exactly when the body is empty — a bijection, so there is
+ * no third state a caller could steer into. A token minted for an empty body cannot be presented with
+ * one, and a token minted for a body cannot be presented without it.
+ */
+async function verifyBodyDigest(body: Uint8Array, claimed: string | null): Promise<void> {
+  if (body.byteLength === 0) {
+    if (claimed !== null) deny("token claims a body digest but the request carries no body");
+    return;
+  }
+  if (claimed === null) deny("request carries a body but the token claims no digest");
+  // Constant-time, though both values are already public: the habit is what keeps a future digest
+  // comparison over something secret from being written the easy way.
+  if (!timingSafeEqual(await sha256Base64Url(body), claimed)) deny("body digest does not match the token");
+}

package/src/controlPlane/migrations/0001_init.ts

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * The control-plane seam's tables: which management client may call this Worker, and which of its tokens
+ * have already been spent.
+ *
+ * This is the inbound seam — the hosted dashboard calling *into* the adopter's Worker. It is not
+ * Cloudflare's control plane, which is the outbound provisioning REST API and shares nothing with these
+ * tables.
+ *
+ * camelCase identifiers; `CamelCasePlugin` snake-cases them to `pithy_controlplane_*` in the DDL. `down`
+ * drops each index before its table, and is tested.
+ *
+ * ## `pithy_controlplane_connections`
+ *
+ * Two shapes are deliberate.
+ *
+ * `id` is text, not an autoincrementing integer. It is the token's `aud`, so it leaves the Worker on
+ * every call; a sequential id would tell a caller how many connections exist and let them guess the
+ * next one.
+ *
+ * `scopes` and `keys` are JSON columns rather than child tables. Keys especially: a rotation is then
+ * one `UPDATE` that cannot half-apply, and verification is one primary-key read with no join on a
+ * Worker hot path. SQLite cannot `CHECK` inside a JSON string, so the Zod schemas on
+ * `ControlPlaneConnection` are the only gate on their contents — `NOT NULL` here is the most the
+ * database itself can say.
+ *
+ * `basePath` records where the seam is mounted on the Worker this connection addresses. It is stored
+ * beside `workerUrl` because the two together fully determine the manifest address — and it is the one
+ * part a client cannot discover, since it *is* the manifest's own address. Everything else already
+ * solves this: `AdminRoute.path` carries the fully mounted path, so no client hardcodes a capability's
+ * mount point. Without it a client must assume `/control-plane`, and an adopter who moved the mount
+ * registers cleanly, passes the `ping` — called at that same assumed path — and then 404s on every call,
+ * with the operator diagnosing the wrong problem.
+ *
+ * ## `pithy_controlplane_replays`
+ *
+ * **`jti` is the primary key, and that is the entire replay mechanism.** The claim is
+ * `INSERT … ON CONFLICT DO NOTHING RETURNING`, so SQLite's uniqueness decides which of N concurrent
+ * presentations wins — no read-then-write, no window between checking and recording. The KV guard this
+ * replaced could not offer that: KV has no compare-and-set, so two colocations could both see a miss.
+ *
+ * The key is `jti` alone, deliberately, and **not** `(jti, connectionId)`. A composite would let a token
+ * captured from one connection be spent again against another, which is the property the guard exists to
+ * deny; `connectionId` is carried as a plain column, for the incident rather than the decision.
+ *
+ * `expiresAt` exists so the table can be pruned. A replay table that only grows is a slow leak in every
+ * adopter's database — the one thing KV gave for nothing, since its entries expired themselves. Its index
+ * is what makes the prune a range scan rather than a full table scan on an administrator-paced write path.
+ */
+export const controlplane_0001_init: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyControlplaneConnections")
+      // The connection id is the token `aud`, and therefore externally exposed. Text, never a sequence.
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("environment", "text", (c) => c.notNull())
+      .addColumn("issuer", "text", (c) => c.notNull())
+      .addColumn("workerUrl", "text", (c) => c.notNull())
+      // Defaulted as well as `NOT NULL`: unlike an origin, there is no such thing as a connection with no
+      // base path — the seam is mounted somewhere, or the connection cannot be called at all.
+      .addColumn("basePath", "text", (c) => c.notNull().defaultTo("/control-plane"))
+      .addColumn("scopes", "text", (c) => c.notNull())
+      .addColumn("keys", "text", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // Verification loads by id, which is already the primary key. This index is for the other reader:
+    // the CLI and the key-listing route ask "what is connected to this environment", and there is no
+    // useful answer without a scan otherwise.
+    await db.schema
+      .createIndex("pithyControlplaneConnectionsEnvironmentIdx")
+      .on("pithyControlplaneConnections")
+      .columns(["environment"])
+      .execute();
+
+    await db.schema
+      .createTable("pithyControlplaneReplays")
+      // The token id, and the race decider. Caller-supplied, so it is bounded by the Zod schema before
+      // it ever reaches here.
+      .addColumn("jti", "text", (c) => c.primaryKey())
+      .addColumn("connectionId", "text", (c) => c.notNull())
+      .addColumn("expiresAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // The prune's only predicate. Without it, reclaiming expired rows scans every spent token the
+    // adopter has ever recorded.
+    await db.schema
+      .createIndex("pithyControlplaneReplaysExpiresAtIdx")
+      .on("pithyControlplaneReplays")
+      .columns(["expiresAt"])
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithyControlplaneReplaysExpiresAtIdx").execute();
+    await db.schema.dropTable("pithyControlplaneReplays").execute();
+    await db.schema.dropIndex("pithyControlplaneConnectionsEnvironmentIdx").execute();
+    await db.schema.dropTable("pithyControlplaneConnections").execute();
+  },
+};

package/src/controlPlane/replay/d1Guard.ts

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ControlPlaneReplay } from "../data/replay";
+import { CONTROL_PLANE_REPLAYS_TABLE, type ControlPlaneDatabase } from "../data/tables";
+import type { ReplayGuard } from "./guard";
+
+/**
+ * The D1-backed {@link ReplayGuard} — the seam's default.
+ *
+ * `INSERT … ON CONFLICT DO NOTHING RETURNING` is the whole thing. The insert either wins the `jti`
+ * primary key and returns a row, or conflicts and returns nothing; there is no read-then-write, so there
+ * is no window between deciding and recording. Of N concurrent presentations of one token, SQLite admits
+ * exactly one, and it does so identically whichever colocation each request landed in — which is
+ * precisely what the KV guard could not promise.
+ *
+ * It is the same move `@pithy-sh/auth` makes on the other side, consuming a refresh token with a
+ * conditional delete so that of N presentations exactly one wins. Single-use-by-constraint is the house
+ * pattern; KV was the outlier.
+ */
+
+/** What the guard needs from its caller. Injected, so nothing here reaches for a clock or a global. */
+export interface D1ReplayGuardOptions {
+  /** The clock. Injected so a test can stand at any instant. */
+  now: () => Date;
+  /**
+   * How long a spent `jti` is remembered — `jtiTtlSeconds` from the seam config, which is itself
+   * cross-checked at assembly to outlive the widest window a token can be accepted in. A row's
+   * `expiresAt` is stamped from it, and the prune below is the only thing that reads it back.
+   */
+  ttlSeconds: number;
+}
+
+/**
+ * Delete rows whose token could no longer be accepted under any clock this Worker honors.
+ *
+ * **Pruning is the one thing KV gave for nothing** — its entries expired themselves, and a table does
+ * not. A replay table that only grows is a slow leak in every adopter's database, so this is deliberate
+ * rather than left to a future sweep.
+ *
+ * It runs **only after a successful claim**, which is the load-bearing detail. Pruning on every call
+ * would let an attacker replaying one token in a loop drive an unbounded `DELETE` per attempt; a refused
+ * claim now costs exactly one conflicting insert and nothing else. And a successful claim is already a
+ * write, so the prune rides along on a path that was never read-only, on an administrator-paced route.
+ *
+ * A failure here is swallowed. Pruning is housekeeping: a claim that has already been decided must not
+ * be reported as failed because a cleanup that had nothing to do with the decision could not run.
+ */
+async function prune(db: ControlPlaneDatabase, now: Date): Promise<void> {
+  try {
+    await db
+      .deleteFrom(CONTROL_PLANE_REPLAYS_TABLE)
+      .where("expiresAt", "<", ControlPlaneReplay.shape.expiresAt.encode(now))
+      .execute();
+  } catch {
+    // Deliberate. See above.
+  }
+}
+
+/** A {@link ReplayGuard} over the seam's own D1 table — strongly consistent, and the default. */
+export function d1ReplayGuard(db: ControlPlaneDatabase, options: D1ReplayGuardOptions): ReplayGuard {
+  return {
+    async claim(jti: string, connectionId: string): Promise<boolean> {
+      const now = options.now();
+      const record = ControlPlaneReplay.encode({
+        jti,
+        connectionId,
+        expiresAt: new Date(now.getTime() + options.ttlSeconds * 1000),
+      });
+
+      const won = await db
+        .insertInto(CONTROL_PLANE_REPLAYS_TABLE)
+        .values(record)
+        // The conflict IS the replay. `doNothing` rather than an upsert: overwriting would refresh the
+        // row's expiry on every replay attempt and keep a spent token remembered forever, and it would
+        // also return a row, which is the answer that admits the call.
+        .onConflict((oc) => oc.column("jti").doNothing())
+        .returning("jti")
+        .executeTakeFirst();
+
+      if (won === undefined) return false;
+
+      await prune(db, now);
+      return true;
+    },
+  };
+}

package/src/controlPlane/replay/guard.ts

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The replay guard: a control-plane token is spendable exactly once.
+ *
+ * Every other check asks what the call *is* — signature, issuer, audience, environment, scope, body
+ * digest, expiry. None of them notices the same valid call arriving twice. {@link ReplayGuard.claim} is
+ * what notices: it records the token's `jti` and reports whether this caller was the first to do so. A
+ * second arrival is refused, and the caller denies.
+ *
+ * ## Two implementations, and D1 is the default
+ *
+ * `d1ReplayGuard` (`./d1Guard`) is the one the seam composes. It claims with
+ * `INSERT … ON CONFLICT DO NOTHING RETURNING`, so the primary key decides the winner and the decision is
+ * strongly consistent — of N concurrent presentations of one token, exactly one row is inserted and
+ * exactly one caller is told it won, wherever the requests landed.
+ *
+ * `kvReplayGuard` (`./kvGuard`) remains available and selectable, and is **best-effort by construction**.
+ * Workers KV has no compare-and-set and is eventually consistent across colocations, so a read-then-write
+ * claim admits a genuine race: two copies of one token presented in two PoPs inside the propagation
+ * window can both read a miss and both claim. That is why it is no longer the default. It is kept because
+ * the trade is legitimate for an adopter who would rather not pay a D1 write on this path and whose admin
+ * operations are all idempotent — but it is now an explicit choice with the cost written down, rather
+ * than the silent default it used to be.
+ *
+ * ## Why the default moved
+ *
+ * The exploitable surface is narrow: same connection, same scope, same body digest, inside a 60-second
+ * expiry. What can be replayed is *one exact call*. Most admin operations shrug that off. Not all do — a
+ * nudge sends real people a second email, a key registration appends, and anything that enqueues work
+ * enqueues it again.
+ *
+ * And the cost of closing it is close to nothing **here specifically**. A control-plane hot path is an
+ * administrator clicking something: low volume, high privilege. Trading a few milliseconds for
+ * correctness is the obvious side of that bargain, which is a different calculation from a per-request
+ * user path. The seam already owns a D1 namespace, so this is a second migration in an existing one
+ * rather than new infrastructure — and single-use-by-unique-constraint is the house pattern besides:
+ * `@pithy-sh/auth` consumes a refresh token exactly this way, and `@pithy-sh/payments` keys idempotency
+ * off a `UNIQUE`. KV was the outlier.
+ */
+
+/**
+ * The single-use gate over a token's `jti`. One method, so the storage decision behind it stays
+ * replaceable — the interface is the substitution point, and it is why moving the default from KV to D1
+ * touched no call site.
+ */
+export interface ReplayGuard {
+  /**
+   * Claim `jti` for `connectionId`. Returns true when this call was the first to spend it, and
+   * **false when it was already spent — the caller must then deny.** The false case is not an error to
+   * log and continue past; it is the replay.
+   */
+  claim(jti: string, connectionId: string): Promise<boolean>;
+}

package/src/controlPlane/replay/kvGuard.ts

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { TypedKv } from "../../kv/kv";
+import type { KvNamespaceSpecMap } from "../../kv/namespaces";
+import { CONTROL_PLANE_JTI_TTL_SECONDS } from "../token/claims";
+import type { ReplayGuard } from "./guard";
+
+/**
+ * The KV-backed {@link ReplayGuard} — still selectable, no longer the default.
+ *
+ * See `./guard.ts` for what the guard is for and why D1 now holds the default. The part that belongs
+ * here is the caveat that is a property of *this* store and not of the seam:
+ *
+ * **Workers KV has no compare-and-set and is eventually consistent across colocations.** A `put` in one
+ * PoP is not immediately visible in another, so two copies of one token presented in two locations
+ * inside the propagation window can both read a miss and both claim. Read-then-write is the strongest
+ * claim KV offers; it is best-effort, not an atomic single-use gate.
+ *
+ * Three things bound the exposure for an adopter who chooses it anyway.
+ *
+ * 1. **The window is KV's propagation delay** — seconds, and independent of the 60-second token. The
+ *    write is issued the moment the first call lands; once it has converged the jti is spent for a full
+ *    {@link CONTROL_PLANE_JTI_TTL_SECONDS}, which deliberately outlives the token that carried it. So
+ *    there is no window at the end of the token's life, only at the very start of it.
+ * 2. **The token is not a general capability.** It is bound to one connection, one scope, one request
+ *    body digest, and that expiry. What can survive the window is a replay of *the exact same call* —
+ *    not a forged one, not a broader one, not a later one.
+ * 3. **`d1ReplayGuard` is one config key away**, and closes the race outright. Choosing this one is
+ *    choosing to skip a D1 write on an administrator-paced path, with the race as the stated price.
+ */
+
+/**
+ * The KV binding the seam's replay set lives in.
+ *
+ * **Not Cloudflare's control plane.** That is the outbound provisioning REST API this project reaches
+ * through `@pithy-sh/cloudflare`. This is the inbound, adopter-authenticated admin seam, and it owns
+ * its own namespace rather than sharing `SESSIONS` — a junk-drawer KV would put user sessions and
+ * management-token receipts behind one binding, and they have nothing to do with each other.
+ */
+export const CONTROL_PLANE_KV_BINDING = "CONTROL_PLANE";
+
+/**
+ * The fixed first key segment for everything the seam stores in KV.
+ *
+ * One word, no hyphen: `assertValidConfig` rejects a prefix containing the key separator, and the
+ * namespace tokens across this capability (migration namespace, table prefix, error domain) are all
+ * the single word `controlplane` for the same family of reasons. The `jti` segment below is what makes
+ * the physical key read `controlplane:jti:<id>` — a scope segment in the key, not in the prefix, so a
+ * second kind of seam entry can join the namespace without colliding.
+ */
+export const CONTROL_PLANE_KV_PREFIX = "controlplane";
+
+/** A spent token's receipt: which connection burned it, and when. */
+export const SeenJti = z
+  .object({
+    connectionId: z
+      .string()
+      .min(1)
+      .describe(
+        "The connection whose token claimed this jti. Recorded for forensics only — a replay is refused whatever connection presents it, because the jti alone is the key.",
+      ),
+    seenAt: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe(
+        "When the jti was claimed, as a ms-epoch number. A plain number rather than a date codec: nothing decodes this back into app types, and it exists to make a raw KV dump readable during an incident.",
+      ),
+  })
+  .describe(
+    "The receipt written when a control-plane token is spent. Its presence is the whole signal; the fields are for the incident, not the decision.",
+  );
+export type SeenJti = z.infer<typeof SeenJti>;
+
+/** The key for one receipt. Physical key: `controlplane:jti:<jti>`. */
+export const SeenJtiKey = z
+  .object({
+    scope: z
+      .literal("jti")
+      .describe(
+        "The fixed second key segment, naming what kind of entry this is. Carried in the key rather than the prefix so the namespace can hold another kind of seam entry later without a migration.",
+      ),
+    jti: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe(
+        "The token's unique id, minted by the management client. Bounded because it arrives from a caller and becomes a KV key — an unbounded id would be an unbounded write.",
+      ),
+  })
+  .describe("The KV key identifying one spent token: the `jti` scope segment and the token id itself.");
+export type SeenJtiKey = z.infer<typeof SeenJtiKey>;
+
+/**
+ * The KV namespaces the control-plane capability registers, served on `c.var.kv.controlplane.jtis`.
+ *
+ * The TTL is the store's, not the caller's: an entry that expired while the token that spent it was
+ * still valid would silently reopen the replay window, so it is declared once here and every write
+ * inherits it.
+ *
+ * **A function of the config, not a constant.** It used to be a module-level literal pinned to
+ * {@link CONTROL_PLANE_JTI_TTL_SECONDS}, which made `jtiTtlSeconds` dead config: an adopter who
+ * lengthened `maxTokenLifetimeSeconds` and lengthened the replay memory to match — the pairing the
+ * config's own cross-field check tells them to make — still got a 180-second store, and their tokens
+ * outlived the memory of them. The one setting that governs this store now actually reaches it.
+ */
+export function controlPlaneKvNamespaces(jtiTtlSeconds: number = CONTROL_PLANE_JTI_TTL_SECONDS) {
+  return {
+    controlplane: {
+      binding: CONTROL_PLANE_KV_BINDING,
+      stores: {
+        jtis: {
+          prefix: CONTROL_PLANE_KV_PREFIX,
+          key: SeenJtiKey,
+          value: SeenJti,
+          ttlSeconds: jtiTtlSeconds,
+        },
+      },
+    },
+  } satisfies KvNamespaceSpecMap;
+}
+
+/** The shape {@link controlPlaneKvNamespaces} produces — what `c.var.kv` is narrowed to. */
+export type ControlPlaneKvNamespaces = ReturnType<typeof controlPlaneKvNamespaces>;
+
+/**
+ * A {@link ReplayGuard} over a typed KV store — the shipped implementation.
+ *
+ * Read-then-write, because KV offers nothing better. A stored receipt that fails validation throws
+ * rather than resolving, which fails closed: a poisoned entry denies the call instead of admitting it.
+ */
+export function kvReplayGuard<M extends z.ZodType>(store: TypedKv<typeof SeenJti, typeof SeenJtiKey, M>): ReplayGuard {
+  return {
+    async claim(jti: string, connectionId: string): Promise<boolean> {
+      const key = { scope: "jti", jti } as const;
+      if ((await store.get(key)) !== null) return false;
+      await store.put(key, { connectionId, seenAt: Date.now() });
+      return true;
+    },
+  };
+}