@pithy-sh/core 0.1.0

package/src/controlPlane/capability.ts

@@ -0,0 +1,228 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { Migration } from "kysely/migration";
+import type { BindingSpecInput } from "../capability/bindings";
+import { type Capability, defineCapability, type PithyHonoEnv } from "../capability/capability";
+import type { DatabaseSpecMap } from "../data/databases";
+import type { KvNamespaceSpecMap, KvRegistry } from "../kv/namespaces";
+import { PACKAGE_VERSION } from "../version.generated";
+import { ENVIRONMENT_VAR } from "../worker/identity";
+import { ControlPlaneConfig, type ControlPlaneConfigInput } from "./config/config";
+import { ControlPlaneConnection } from "./data/connection";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase, controlPlaneTables } from "./data/tables";
+import type { CapabilityDeclaration } from "./discovery/adminRoute";
+import { type CapabilityHealthSource, capabilityHealthSources } from "./discovery/health";
+import { createControlPlaneVerifier } from "./http/guard";
+import { controlPlaneRouteDescriptors, registerControlPlaneRoutes } from "./http/routes";
+import { controlplane_0001_init } from "./migrations/0001_init";
+import { d1ReplayGuard } from "./replay/d1Guard";
+import type { ReplayGuard } from "./replay/guard";
+import {
+  CONTROL_PLANE_KV_BINDING,
+  type ControlPlaneKvNamespaces,
+  controlPlaneKvNamespaces,
+  kvReplayGuard,
+} from "./replay/kvGuard";
+
+/**
+ * Where the control-plane registration sorts in the app database. Composed key:
+ * `1100_controlplane_0001_init`.
+ *
+ * Taken from `NEXT_FREE_ORDER` in `packages/cli/src/migrations/orders.test.ts`, which is the one place
+ * an order may be allocated, and registered in that file's `DECLARED` table. Core used to be skipped by
+ * that scanner on the reasoning that it owns the ceiling rather than an order; that stopped being true
+ * here, and the skip was removed with this change. Stable forever — renumbering would rename the
+ * composed key and make Kysely re-run an applied migration.
+ */
+export const CONTROLPLANE_MIGRATION_ORDER = 1100;
+
+export type ControlPlaneOptions = ControlPlaneConfigInput;
+
+/** The control-plane capability, with its resolved config attached. */
+export interface ControlPlaneCapability extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "controlplane"> {
+  /** The resolved seam config. */
+  controlPlaneConfig: ControlPlaneConfig;
+}
+
+/** Narrow a composed capability to this one — the CLI and tests use it to find the seam's config. */
+export function isControlPlaneCapability(capability: Capability): capability is ControlPlaneCapability {
+  return capability.name === "controlplane";
+}
+
+/**
+ * The `control-plane` seam: inbound, adopter-authenticated M2M admin access to this Worker.
+ *
+ * **Not Cloudflare's control plane.** That is the outbound REST API `@pithy-sh/cloudflare` calls to
+ * provision D1, KV, and Workers, and it carries `cloudflare/*` codes. This is the inverse — a
+ * management client calling *in*, authenticated by a key the adopter registered. See
+ * `docs/CONTROL-PLANE.md`, whose first section exists entirely to keep the two apart.
+ *
+ * **Composing it grants nobody anything.** The capability ships present-and-denying: with no connection
+ * registered, every route it guards answers `controlplane/not_connected`, and there is no flag that
+ * changes that. `pithy dashboard connect` is the deliberate second step, and revoking is a row the
+ * adopter deletes without asking anyone.
+ *
+ * It lives in `@pithy-sh/core` rather than its own package because every capability contributing admin
+ * routes imports `requireControlPlane`, and a capability may depend on a core seam but never on a
+ * sibling package (principle 4). MIT with the rest of core, and never gated by tier: this is the code
+ * that runs in the adopter's own Worker, so restricting it would make "build your own client against
+ * your own Worker" untrue.
+ */
+export function controlplane(options: ControlPlaneOptions = {}): ControlPlaneCapability {
+  // Parsed at assembly, so a config whose replay memory is shorter than a token's life fails on deploy
+  // rather than by silently admitting a replay months later.
+  const config = ControlPlaneConfig.parse(options);
+
+  const migrations: Record<string, Migration> = {
+    "0001_init": controlplane_0001_init,
+  };
+  const requiredBindings: BindingSpecInput[] = [
+    // The app database — the connections table lives here, beside auth's and audit's. Not the secrets
+    // database: a public key is not confidential, and what it needs is a queryable, auditable lifecycle
+    // with room for two valid keys during a rotation overlap.
+    { type: "d1", name: "DB" },
+  ];
+
+  // The replay set's namespace — required only when the adopter selected the KV backend.
+  //
+  // Under the `d1` default nothing reads this namespace, and demanding it anyway would make every
+  // project provision a KV it never touches, which is exactly what "a Worker composes only what it
+  // declares" rules out. `createBackend` derives the binding from `kvNamespaces` too, so declaring it
+  // here is redundant for assembly — `dedupeBindings` ANDs `optional`, and a duplicate can only make a
+  // requirement stricter. It is declared anyway, because `requiredBindings` is also the list
+  // `pithy remove` strips from `wrangler.jsonc`: `@pithy-sh/matchmaking` and `@pithy-sh/media` both
+  // repeat their KV bindings for the same reason, and omitting it left `CONTROL_PLANE` behind after a
+  // removal, demanding a namespace nothing used.
+  const usesKvReplay = config.replayBackend === "kv";
+  if (usesKvReplay) requiredBindings.push({ type: "kv", name: CONTROL_PLANE_KV_BINDING });
+
+  /**
+   * The app database for this request, off the derived registry. `c.var.db` is `unknown` on the base
+   * seam by design — its precise type depends on which capabilities a project composed — so each
+   * capability narrows it to its own slice, the same cast every other capability makes.
+   */
+  const database = (c: Context<PithyHonoEnv>): ControlPlaneDatabase => (c.var.db as { app: ControlPlaneDatabase }).app;
+
+  const now = () => new Date();
+
+  /**
+   * The replay guard for this request, chosen once by config.
+   *
+   * `d1` is the default and claims on a primary key, so one token is spendable exactly once wherever the
+   * requests land. `kv` remains selectable and is best-effort — see `./replay/guard.ts`. The interface is
+   * what made moving the default a one-line change here rather than an edit at every call site.
+   */
+  const replay = (c: Context<PithyHonoEnv>): ReplayGuard =>
+    config.replayBackend === "kv"
+      ? kvReplayGuard((c.var.kv as KvRegistry<ControlPlaneKvNamespaces>).controlplane.jtis)
+      : d1ReplayGuard(database(c), { now, ttlSeconds: config.jtiTtlSeconds });
+
+  // What this Worker composed and what each part exposes, filled by the `compose` hook below.
+  // Assembly-time knowledge a capability has no other way to reach — `GET /control-plane/manifest`
+  // reports it, which is what lets a management client discover this Worker's surface, and how to call
+  // it, instead of being configured with both.
+  let composed: readonly CapabilityDeclaration[] = [];
+
+  // The bounded summaries those capabilities contribute, by name (#317). Captured by the same hook and
+  // checked there: a value behind a scope no admin route of its own capability requires is refused at
+  // assembly, because an adopter is never offered such a scope and the number could never be granted.
+  let health: ReadonlyMap<string, CapabilityHealthSource> = new Map();
+
+  const capability = defineCapability({
+    name: "controlplane",
+    // `@pithy-sh/core`'s version, stamped by `scripts/stampVersions.ts` — a Worker cannot read its own
+    // package.json. The seam reports itself in the manifest beside every other composed capability, so a
+    // client can see which core an adopter is on without a separate question.
+    version: PACKAGE_VERSION,
+    // No `dependsOn`. The seam must work in a Worker composing neither auth nor audit nor secrets: it
+    // holds no secret, mints no session, and emits through a seam that is a no-op when absent.
+    requiredBindings,
+    config: ControlPlaneConfig,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: controlPlaneTables(),
+        migrationOrder: CONTROLPLANE_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    // Registered only for the KV backend, and built from the resolved config so `jtiTtlSeconds` actually
+    // governs how long a spent token id is remembered. A constant here would make that setting
+    // decorative; registering it unconditionally would make every `d1` project carry a namespace nothing
+    // in the tree ever reads.
+    kvNamespaces: usesKvReplay ? controlPlaneKvNamespaces(config.jtiTtlSeconds) : {},
+    // The seam describes itself too. Built from the same resolved `basePath` the routes mount on, so a
+    // moved mount point is reported rather than becoming a lie a client believes.
+    adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+    compose: ({ capabilities }) => {
+      // Every capability, including those exposing nothing. A client rendering a capability it cannot
+      // act on is useful; a client that cannot tell "no admin surface" from "not installed" is not.
+      composed = capabilities.map((cap) => ({
+        name: cap.name,
+        // `?? null`, never undefined: the adopter's own `app` capability has a name and no package
+        // version, and that must render as an explicit null rather than vanish from the JSON.
+        version: cap.version ?? null,
+        adminRoutes: [...(cap.adminRoutes ?? [])],
+        // The vocabulary, always — a capability declaring a number this connection cannot see must be
+        // visible as a withheld number rather than as silence.
+        healthKeys: [...(cap.health?.keys ?? [])],
+        // The configured facts, read once here and the same for every caller (#422). No producer and no
+        // per-request cost: a fact is resolved config, so there is nothing to ask and nothing to fail.
+        configKeys: [...(cap.manifestConfig?.keys ?? [])],
+        config: { ...(cap.manifestConfig?.values ?? {}) },
+      }));
+      health = capabilityHealthSources(capabilities);
+    },
+    middleware: [
+      (app) => {
+        // Publish the verifier every `requireControlPlane()` in the tree consumes — including the ones
+        // in capabilities that know nothing about this config. Publishing it is all this does: no
+        // verification happens here, because a request merely carrying the header must not be rejected
+        // on a route that has nothing to do with the seam.
+        app.use("*", async (c, next) => {
+          const db = database(c);
+          c.set(
+            "controlPlaneVerifier",
+            createControlPlaneVerifier({
+              loadConnection: async (connectionId) => {
+                const row = await db
+                  .selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE)
+                  .selectAll()
+                  .where("id", "=", connectionId)
+                  .executeTakeFirst();
+                return row ? ControlPlaneConnection.parse(row) : null;
+              },
+              countConnections: async () => {
+                const rows = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).select("id").limit(1).execute();
+                return rows.length;
+              },
+              replay: replay(c),
+              // The environment a credential is bound to. Absent off-platform, where the empty string
+              // matches no stored connection and every call therefore denies — the right failure.
+              environment: String((c.env as Record<string, unknown>)[ENVIRONMENT_VAR] ?? ""),
+              config,
+              now,
+            }),
+          );
+          await next();
+        });
+      },
+    ],
+    routes: (app) => {
+      registerControlPlaneRoutes(app, config.basePath, {
+        config,
+        database,
+        composedCapabilities: () => composed,
+        composedHealth: () => health,
+        now,
+      });
+    },
+  });
+
+  return { ...capability, controlPlaneConfig: config } as ControlPlaneCapability;
+}
+
+/** Re-exported so a Worker's wrangler config and this capability cannot disagree about the binding name. */
+export { CONTROL_PLANE_KV_BINDING };

package/src/controlPlane/config/config.ts

@@ -0,0 +1,195 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import {
+  CONTROL_PLANE_CLOCK_SKEW_SECONDS,
+  CONTROL_PLANE_JTI_TTL_SECONDS,
+  CONTROL_PLANE_MAX_TOKEN_LIFETIME_SECONDS,
+} from "../token/claims";
+
+/**
+ * The `control-plane` seam's config — the thin, user-owned surface in a Worker's `pithy.config.ts`.
+ * Every field is `.describe()`d: the descriptions feed the self-documenting CLI (CLAUDE.md §Config).
+ *
+ * Parsed once at assembly, so a bad value fails on deploy rather than on the first management call.
+ * That matters more here than anywhere else in the tree: the failure mode of a loose setting is not a
+ * broken feature, it is an admin surface that accepts something it should have refused, and nothing
+ * observable goes wrong until someone uses it.
+ *
+ * The defaults are deliberately tight. A management token lives one minute, is accepted one minute
+ * either side of the clock, and its `jti` is remembered for three — comfortably longer than the widest
+ * window any such token can be accepted in, which is the whole point of the cross-field rule below.
+ *
+ * None of this concerns Cloudflare's control plane. That is the outbound provisioning API behind
+ * `@pithy-sh/cloudflare`; this is an inbound seam the adopter's own Worker exposes.
+ */
+
+/** A rooted path with no trailing slash — Hono mounts on exactly this string. */
+const BASE_PATH_PATTERN = /^\/[a-zA-Z0-9\-._~]+(?:\/[a-zA-Z0-9\-._~]+)*$/;
+
+/** Five minutes. The ceiling on skew and on a token's life: past it, "short-lived" stops being true. */
+const MAX_WINDOW_SECONDS = 300;
+
+/** An hour. The ceiling on replay memory — beyond it the set costs more than the risk it retires. */
+const MAX_JTI_TTL_SECONDS = 3600;
+
+/** Two hours. Chrome's own ceiling on a cached preflight; asking for more is asking for nothing. */
+const MAX_CORS_MAX_AGE_SECONDS = 7200;
+
+/**
+ * Exactly an origin — what a browser puts in `Origin`, and nothing else.
+ *
+ * `z.url()` is not this check: it accepts `https://ops.example.com/`, a path, a wildcard, and `ftp://`.
+ * Every one of those would sit in the config file looking correct and then match no browser `Origin`,
+ * which fails as a bare refusal with nothing to read. The trailing-slash form is the one to expect,
+ * because it is what an address bar shows the person copying the value.
+ */
+/** A DNS hostname, or a bracketed IP literal — `[::1]`, the address a Vite dev server binds by default. */
+const ORIGIN_HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+const IP_LITERAL = /^\[[0-9a-fA-F:.]+\]$/;
+
+/**
+ * Exactly an origin: a scheme a browser sends, a real host, and nothing after it.
+ *
+ * **It refuses a misunderstanding and forgives a spelling.** A path, a query, a fragment or a
+ * credential means the writer thinks this value scopes something it does not — `https://ops.example.com/admin`
+ * does not restrict anything to `/admin` — so those are refused at deploy, where the message can say so.
+ * A trailing slash and an explicit `:443` are the same origin written a different way, and they are what
+ * an address bar hands the person copying the value, so they are accepted and normalized by
+ * `allowedOriginSet` rather than turned into a puzzle.
+ *
+ * `z.url()` is not this check: it accepts `https://*.example.com` — a wildcard is a legal hostname to
+ * the URL parser and means nothing to a browser — and `ftp://x.com`, which has an origin too.
+ */
+const ORIGIN_ONLY = (value: string): boolean => {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+  if (url.username !== "" || url.password !== "") return false;
+  if (url.pathname !== "/" || url.search !== "" || url.hash !== "") return false;
+  return ORIGIN_HOSTNAME.test(url.hostname) || IP_LITERAL.test(url.hostname);
+};
+
+export const ControlPlaneConfig = z
+  .object({
+    basePath: z
+      .string()
+      .regex(
+        BASE_PATH_PATTERN,
+        "A base path must start with `/`, carry no trailing slash, and contain no spaces (e.g. `/control-plane`).",
+      )
+      .default("/control-plane")
+      .describe(
+        "Where the seam's own routes mount — ping, manifest, and key management. Move it to sit under an existing admin prefix; it is not a security control, since every route behind it is default-denied anyway.",
+      ),
+    issuer: z
+      .url()
+      .default("https://app.pithy.sh")
+      .describe(
+        "The management-client origin a NEW connection is registered against — trust-critical, and effectively permanent. Every registered Worker verifies the `iss` on every call, so changing this is a migration across every connection, not a config edit. Verification reads the issuer stored on the connection; this only supplies the default written at connect time. It also seeds the browser origins this Worker answers a CORS preflight for (see `allowedOrigins`), which is the one thing about this value the Worker itself reads at runtime.",
+      ),
+    allowedOrigins: z
+      .array(
+        z
+          .url()
+          .refine(
+            ORIGIN_ONLY,
+            "An allowed origin is a scheme and a host — `https://ops.example.com`, `http://localhost:5173`, `http://[::1]:5173`. A path, a query or a credential is refused, because it looks like it scopes the entry and does not.",
+          )
+          .describe("One exact browser origin, spelled the way a browser sends it in `Origin`."),
+      )
+      .default([])
+      .describe(
+        "Browser origins allowed to call this Worker's control-plane surface cross-origin, **in addition to** `issuer`. Additive by construction: an entry here never removes `issuer`, so adding your own console cannot lock out the dashboard that was already working. Read from this config alone and never from a connection row — a preflight carries no credential, so answering one must cost no database read and must reveal nothing about which origins are registered. A management client you host yourself belongs here, or in `issuer` if it is the only one.",
+      ),
+    corsMaxAgeSeconds: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_CORS_MAX_AGE_SECONDS)
+      .default(600)
+      .describe(
+        "How long a browser may cache a preflight for this Worker's admin surface, in seconds. The allow-list it caches is a compile-time constant, so ten minutes costs nothing and saves the dashboard a second round trip on every call. **Set it to 0 while you are working out an allow-list**: a browser that cached a refusal keeps refusing for the full window after you have fixed `allowedOrigins`, which reads exactly like a change that did not take. Browsers cap this themselves, so a larger number here is a request, not a guarantee.",
+      ),
+    clockSkewSeconds: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_WINDOW_SECONDS)
+      .default(CONTROL_PLANE_CLOCK_SKEW_SECONDS)
+      .describe(
+        "How far a token's `iat`/`exp` may sit outside this Worker's clock and still be accepted. It absorbs real drift between two machines; it also widens the window a captured token stays live in, which is why it is capped rather than left to taste.",
+      ),
+    maxTokenLifetimeSeconds: z
+      .number()
+      .int()
+      .positive()
+      .max(MAX_WINDOW_SECONDS)
+      .default(CONTROL_PLANE_MAX_TOKEN_LIFETIME_SECONDS)
+      .describe(
+        "The longest `exp - iat` this Worker will honor, whatever the token asks for. The adopter's ceiling, not the management client's choice: a client that mints hour-long tokens still gets one minute of them here.",
+      ),
+    jtiTtlSeconds: z
+      .number()
+      .int()
+      .positive()
+      .max(MAX_JTI_TTL_SECONDS)
+      .default(CONTROL_PLANE_JTI_TTL_SECONDS)
+      .describe(
+        "How long a spent `jti` is remembered, so the same token cannot be presented twice. It must outlive the widest window a token is accepted in (lifetime plus skew) — a shorter memory forgets a token that is still valid, which is precisely the replay this exists to stop.",
+      ),
+    replayBackend: z
+      .enum(["d1", "kv"])
+      .default("d1")
+      .describe(
+        "Where spent token ids are recorded. `d1` claims with `INSERT … ON CONFLICT DO NOTHING`, so the primary key decides the race and one token is spendable exactly once, wherever the requests land — it costs one write on a path an administrator paces. `kv` skips that write and is best-effort: Workers KV has no compare-and-set and is eventually consistent across colocations, so one token presented twice in two places inside the propagation window can pass twice. Choose `kv` only where every management operation is idempotent.",
+      ),
+    keyRetentionDays: z
+      .number()
+      .int()
+      .positive()
+      .max(365)
+      .default(30)
+      .describe(
+        "How long an expired or revoked key stays on the connection row before pruning. Long enough to read a rotation back; short enough that verification never parses a growing blob. The audit trail is the history of record — the row is working state, not an archive.",
+      ),
+    maxKeys: z
+      .number()
+      .int()
+      .min(2)
+      .max(32)
+      .default(8)
+      .describe(
+        "The most keys one connection may hold, live and superseded together. At least two, because a rotation overlap needs the new key registered while the old one still works — a ceiling of one would make safe rotation impossible.",
+      ),
+  })
+  .describe(
+    "Configuration for the inbound `control-plane` seam: where its routes mount, which management-client origin new connections trust, and the token and key-lifecycle bounds this Worker enforces.",
+  )
+  .check((ctx) => {
+    // The replay set is only a defense while it still remembers a token that is still valid. If the
+    // `jti` is forgotten first, the same signed token replays cleanly for the rest of its window — the
+    // one misconfiguration that quietly reopens exactly what the set was added to close.
+    //
+    // The window is `lifetime + 2 × skew`, not `lifetime + skew`. Skew is allowed on **both** ends:
+    // `iat` may be up to a skew in the future and `exp` is honored up to a skew after it passes, so a
+    // token minted at the earliest instant this Worker would accept it is still accepted a full
+    // `lifetime + 2 × skew` later. The check used to count one skew and was therefore satisfied by
+    // settings that still left a replay window open.
+    const widestWindow = ctx.value.maxTokenLifetimeSeconds + 2 * ctx.value.clockSkewSeconds;
+    if (ctx.value.jtiTtlSeconds <= widestWindow) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["jtiTtlSeconds"],
+        message: `jtiTtlSeconds (${ctx.value.jtiTtlSeconds}) must exceed maxTokenLifetimeSeconds + 2 × clockSkewSeconds (${widestWindow}). A token is accepted a clock skew either side of its window, so a shorter memory lets it outlive the record of it and replay.`,
+      });
+    }
+  });
+export type ControlPlaneConfig = z.output<typeof ControlPlaneConfig>;
+export type ControlPlaneConfigInput = z.input<typeof ControlPlaneConfig>;

package/src/controlPlane/context.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ControlPlaneScope } from "./scope/scope";
+
+/**
+ * The verified control-plane caller, on `c.var.controlPlane`.
+ *
+ * **This is deliberately not `AuthContext`, and the two must never be conflated.** A management client
+ * is not a user of the adopter's app: it holds no session, owns no user row, and signed up for
+ * nothing. If a control-plane call populated `c.var.auth`, every `requireAuth()` in every capability
+ * would pass for it — a scope escalation across the whole tree, from one seemingly convenient
+ * assignment. So the seam gets its own request variable, and `requireControlPlane` is the only gate
+ * that reads it.
+ *
+ * Statelessness is the feature. Nothing here is persisted: the context is derived from one token,
+ * lives for one request, and is discarded. There is no session to hijack and no row to leak. Exactly
+ * two things outlive the call — the `jti` in the replay set, and the audit event.
+ */
+export const ControlPlaneContext = z
+  .object({
+    connectionId: z
+      .string()
+      .describe(
+        "The connection this call authenticated against — the token's `aud`, verified against the loaded registration. Identifies the management client, per adopter, per project, per environment.",
+      ),
+    environment: z
+      .string()
+      .describe(
+        "The environment the connection is bound to, already checked against this Worker's own. A staging credential never reaches production, so by the time this is set the two agree.",
+      ),
+    issuer: z
+      .string()
+      .describe(
+        "The `iss` this connection trusts and this token carried. Verified, not merely recorded — it is the origin the adopter agreed to accept calls from.",
+      ),
+    subject: z
+      .string()
+      .describe(
+        "The management client's own user id from the token's `sub` — who, on their side, is acting. Recorded as the audit `actorId` so the trail answers 'which person at the dashboard did this', not just 'the dashboard'.",
+      ),
+    scope: ControlPlaneScope.describe(
+      "The single scope this token was minted for. One call, one operation — a token carrying the whole grant would make every call as dangerous as the most dangerous one.",
+    ),
+    grantedScopes: z
+      .array(ControlPlaneScope)
+      .describe(
+        "Every scope the adopter granted this connection, read from their own row. The authority: a scope absent here is denied however the token is written.",
+      ),
+    keyId: z
+      .string()
+      .describe(
+        "Which registered key verified this call. Recorded so a rotation can be traced through the trail, and so a key still in use is visible before it is expired.",
+      ),
+    tokenId: z
+      .string()
+      .describe("The token's `jti`, already claimed in the replay set. Recorded to tie one audit event to one call."),
+  })
+  .describe(
+    "The verified control-plane caller for one request. Never an AuthContext: a management client is not a user of the adopter's app.",
+  );
+export type ControlPlaneContext = z.output<typeof ControlPlaneContext>;

package/src/controlPlane/data/connection.ts

@@ -0,0 +1,123 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { JsonDate, SQLiteDate, sqliteJson } from "../../data/codecs";
+import { ControlPlaneScope } from "../scope/scope";
+
+/**
+ * The registration record: who may call this Worker's control-plane routes, from where, with what
+ * keys, for which operations.
+ *
+ * **This lives in D1, not the Secrets Store.** A public key is not confidential — but it *is*
+ * integrity-critical, because whoever can change it owns the seam. D1 gives it a queryable lifecycle,
+ * an audit trail, and room for two valid keys during a rotation overlap. Writes come only from the CLI
+ * provisioning path or from a route authenticated by the key being replaced; no runtime route with a
+ * lesser credential can touch it.
+ */
+
+/** An Ed25519 public key in JWK form — the only key type this seam accepts. */
+export const Ed25519PublicJwk = z
+  .object({
+    kty: z.literal("OKP").describe("Key type. Ed25519 is an octet key pair, so this is always `OKP` (RFC 8037)."),
+    crv: z
+      .literal("Ed25519")
+      .describe(
+        "The curve, pinned to Ed25519. Pinned rather than accepted from the key so a weaker curve cannot be smuggled in at registration and honored at verification.",
+      ),
+    x: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe(
+        "The base64url-encoded public key point. Public by definition — safe to store, and safe to return from `GET /control-plane/keys`.",
+      ),
+  })
+  .describe("An Ed25519 public key as a JWK: what a management client registers, and what verification imports.");
+export type Ed25519PublicJwk = z.output<typeof Ed25519PublicJwk>;
+
+/**
+ * One registered public key and its validity window — an element of the connection's versioned array.
+ *
+ * Several keys are valid at once during a rotation overlap. That is a normal state, not an exception:
+ * the new key is appended and proven *before* the old one is given an end date, so there is always a
+ * live key to authenticate the next step with.
+ */
+export const RegisteredKey = z
+  .object({
+    keyId: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe("The key's id, matched against a token's `kid` header. Opaque, and minted by the management client."),
+    publicKey: Ed25519PublicJwk.describe(
+      "The public key this id names. Imported per request to verify a signature; nothing secret is stored here.",
+    ),
+    validFrom: JsonDate.describe(
+      "When this key became valid. A call signed before it is rejected, so a key registered ahead of time cannot be used early.",
+    ),
+    validUntil: JsonDate.nullable().describe(
+      "When this key stops being accepted, or null while it is open-ended. Set only by the expire route, never at registration — the open-ended overlap is what keeps a failed rotation from locking anyone out.",
+    ),
+    revokedAt: JsonDate.nullable().describe(
+      "When this key was revoked outright, or null. Revocation ignores `validUntil` and takes effect immediately — it is the adopter's unilateral control, and it must not wait for a window to close.",
+    ),
+  })
+  .describe("One registered public key with its validity window. Two live at once during a rotation overlap.");
+export type RegisteredKey = z.output<typeof RegisteredKey>;
+
+/**
+ * One management-client connection — the row in `pithy_controlplane_connections`.
+ *
+ * Keys are a versioned JSON column rather than a child table for two reasons. **Rotation becomes one
+ * atomic `UPDATE`**: appending the new key and expiring the old cannot half-apply, where separate rows
+ * would need a batch. And **verification stays a single read** with no join on a Worker hot path —
+ * scanning two or three keys for a matching `kid` is free.
+ */
+export const ControlPlaneConnection = z
+  .object({
+    id: z
+      .uuid()
+      .describe(
+        "The connection id — a UUID because it is the token `aud` and therefore externally exposed. Text rather than an autoincrementing integer, so connections cannot be enumerated.",
+      ),
+    environment: z
+      .string()
+      .min(1)
+      .max(32)
+      .describe(
+        "The environment this connection is valid in (`dev`, `staging`, `production`). Checked against the Worker's own on every call, so a staging credential cannot reach production.",
+      ),
+    issuer: z
+      .url()
+      .describe(
+        "The exact `iss` this connection accepts. Verified on every call, and effectively permanent — changing the management client's origin is a migration across every registered connection, not a DNS change.",
+      ),
+    workerUrl: z
+      .url()
+      .describe(
+        "This environment's deployed Worker URL, captured at connect. The address the management client calls; re-pointed by `pithy dashboard connect --update` when a custom domain or a rename moves it.",
+      ),
+    basePath: z
+      .string()
+      .min(1)
+      .default("/control-plane")
+      .describe(
+        "Where this Worker mounts the control-plane seam, captured at connect from its resolved config. Stored beside `workerUrl` because the two together fully determine the manifest address — and this is the one part of it a client cannot discover, since it *is* the manifest's own address. Defaulted rather than required so a connection registered before the column existed still parses, reading as the default it was necessarily using.",
+      ),
+    scopes: sqliteJson(z.array(ControlPlaneScope)).describe(
+      "The operations this connection was granted, stored and enforced on the adopter's side. Enforced only by the caller, a scope would not be a limit at all.",
+    ),
+    keys: sqliteJson(z.array(RegisteredKey)).describe(
+      "Every key this connection may sign with, current and superseded. One JSON column rather than a child table, so a rotation is one atomic UPDATE and verification is one read.",
+    ),
+    createdAt: SQLiteDate.describe("When the connection was registered. Ms-epoch in SQLite, a Date in TypeScript."),
+    updatedAt: SQLiteDate.describe(
+      "When the row last changed — a key registered or expired, or the Worker URL re-pointed.",
+    ),
+  })
+  .describe(
+    "One management-client connection: its identity, the environment and URL it is bound to, the operations it was granted, and its versioned public keys.",
+  );
+export type ControlPlaneConnection = z.output<typeof ControlPlaneConnection>;
+export type ControlPlaneConnectionRow = z.input<typeof ControlPlaneConnection>;