@pithy-sh/core 0.1.1 → 0.1.3

package/dist/controlPlane/capability.js

@@ -0,0 +1,138 @@
+import { defineCapability } from "../capability/capability.js";
+import { PACKAGE_VERSION } from "../version.generated.js";
+import "../worker/identity.js";
+import { ControlPlaneConfig } from "./config/config.js";
+import { ControlPlaneConnection } from "./data/connection.js";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, controlPlaneTables } from "./data/tables.js";
+import { capabilityHealthSources } from "./discovery/health.js";
+import { createControlPlaneVerifier } from "./http/guard.js";
+import { controlPlaneRouteDescriptors, registerControlPlaneRoutes } from "./http/routes.js";
+import { controlplane_0001_init } from "./migrations/0001_init.js";
+import { d1ReplayGuard } from "./replay/d1Guard.js";
+import { CONTROL_PLANE_KV_BINDING, controlPlaneKvNamespaces, kvReplayGuard } from "./replay/kvGuard.js";
+//#region src/controlPlane/capability.ts
+/**
+* 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.
+*/
+const CONTROLPLANE_MIGRATION_ORDER = 1100;
+/** Narrow a composed capability to this one — the CLI and tests use it to find the seam's config. */
+function isControlPlaneCapability(capability) {
+	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.
+*/
+function controlplane(options = {}) {
+	const config = ControlPlaneConfig.parse(options);
+	const migrations = { "0001_init": controlplane_0001_init };
+	const requiredBindings = [{
+		type: "d1",
+		name: "DB"
+	}];
+	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) => c.var.db.app;
+	const now = () => /* @__PURE__ */ 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) => config.replayBackend === "kv" ? kvReplayGuard(c.var.kv.controlplane.jtis) : d1ReplayGuard(database(c), {
+		now,
+		ttlSeconds: config.jtiTtlSeconds
+	});
+	let composed = [];
+	let health = /* @__PURE__ */ new Map();
+	return {
+		...defineCapability({
+			name: "controlplane",
+			version: PACKAGE_VERSION,
+			requiredBindings,
+			config: ControlPlaneConfig,
+			databases: { app: {
+				binding: "DB",
+				tables: controlPlaneTables(),
+				migrationOrder: CONTROLPLANE_MIGRATION_ORDER,
+				migrations
+			} },
+			kvNamespaces: usesKvReplay ? controlPlaneKvNamespaces(config.jtiTtlSeconds) : {},
+			adminRoutes: controlPlaneRouteDescriptors(config.basePath),
+			compose: ({ capabilities }) => {
+				composed = capabilities.map((cap) => ({
+					name: cap.name,
+					version: cap.version ?? null,
+					adminRoutes: [...cap.adminRoutes ?? []],
+					healthKeys: [...cap.health?.keys ?? []],
+					configKeys: [...cap.manifestConfig?.keys ?? []],
+					config: { ...cap.manifestConfig?.values ?? {} }
+				}));
+				health = capabilityHealthSources(capabilities);
+			},
+			middleware: [(app) => {
+				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 () => {
+							return (await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).select("id").limit(1).execute()).length;
+						},
+						replay: replay(c),
+						environment: String(c.env["ENVIRONMENT"] ?? ""),
+						config,
+						now
+					}));
+					await next();
+				});
+			}],
+			routes: (app) => {
+				registerControlPlaneRoutes(app, config.basePath, {
+					config,
+					database,
+					composedCapabilities: () => composed,
+					composedHealth: () => health,
+					now
+				});
+			}
+		}),
+		controlPlaneConfig: config
+	};
+}
+//#endregion
+export { CONTROLPLANE_MIGRATION_ORDER, CONTROL_PLANE_KV_BINDING, controlplane, isControlPlaneCapability };

package/dist/controlPlane/config/config.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export declare const ControlPlaneConfig: z.ZodObject<{
+    basePath: z.ZodDefault<z.ZodString>;
+    issuer: z.ZodDefault<z.ZodURL>;
+    allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodURL>>;
+    corsMaxAgeSeconds: z.ZodDefault<z.ZodNumber>;
+    clockSkewSeconds: z.ZodDefault<z.ZodNumber>;
+    maxTokenLifetimeSeconds: z.ZodDefault<z.ZodNumber>;
+    jtiTtlSeconds: z.ZodDefault<z.ZodNumber>;
+    replayBackend: z.ZodDefault<z.ZodEnum<{
+        d1: "d1";
+        kv: "kv";
+    }>>;
+    keyRetentionDays: z.ZodDefault<z.ZodNumber>;
+    maxKeys: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type ControlPlaneConfig = z.output<typeof ControlPlaneConfig>;
+export type ControlPlaneConfigInput = z.input<typeof ControlPlaneConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/controlPlane/config/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/config/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0ExB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;iBAmH3B,CAAC;AACL,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AACrE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/controlPlane/config/config.js

@@ -0,0 +1,85 @@
+import "../token/claims.js";
+import { z } from "zod";
+//#region src/controlPlane/config/config.ts
+/**
+* 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) => {
+	let 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);
+};
+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(60).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(60).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(300).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) => {
+	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.`
+	});
+});
+//#endregion
+export { ControlPlaneConfig };

package/dist/controlPlane/context.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * 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 declare const ControlPlaneContext: z.ZodObject<{
+    connectionId: z.ZodString;
+    environment: z.ZodString;
+    issuer: z.ZodString;
+    subject: z.ZodString;
+    scope: z.ZodString;
+    grantedScopes: z.ZodArray<z.ZodString>;
+    keyId: z.ZodString;
+    tokenId: z.ZodString;
+}, z.core.$strip>;
+export type ControlPlaneContext = z.output<typeof ControlPlaneContext>;
+//# sourceMappingURL=context.d.ts.map

package/dist/controlPlane/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/controlPlane/context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;iBAyC7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/controlPlane/context.js

@@ -0,0 +1,29 @@
+import { ControlPlaneScope } from "./scope/scope.js";
+import { z } from "zod";
+//#region src/controlPlane/context.ts
+/**
+* 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.
+*/
+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.");
+//#endregion
+export { ControlPlaneContext };

package/dist/controlPlane/data/connection.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+/**
+ * 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 declare const Ed25519PublicJwk: z.ZodObject<{
+    kty: z.ZodLiteral<"OKP">;
+    crv: z.ZodLiteral<"Ed25519">;
+    x: z.ZodString;
+}, z.core.$strip>;
+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 declare const RegisteredKey: z.ZodObject<{
+    keyId: z.ZodString;
+    publicKey: z.ZodObject<{
+        kty: z.ZodLiteral<"OKP">;
+        crv: z.ZodLiteral<"Ed25519">;
+        x: z.ZodString;
+    }, z.core.$strip>;
+    validFrom: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+    validUntil: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+    revokedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+}, z.core.$strip>;
+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 declare const ControlPlaneConnection: z.ZodObject<{
+    id: z.ZodUUID;
+    environment: z.ZodString;
+    issuer: z.ZodURL;
+    workerUrl: z.ZodURL;
+    basePath: z.ZodDefault<z.ZodString>;
+    scopes: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodArray<z.ZodString>>;
+    keys: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodObject<{
+        keyId: z.ZodString;
+        publicKey: z.ZodObject<{
+            kty: z.ZodLiteral<"OKP">;
+            crv: z.ZodLiteral<"Ed25519">;
+            x: z.ZodString;
+        }, z.core.$strip>;
+        validFrom: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+        validUntil: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+        revokedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+    }, z.core.$strip>>]>, z.ZodArray<z.ZodObject<{
+        keyId: z.ZodString;
+        publicKey: z.ZodObject<{
+            kty: z.ZodLiteral<"OKP">;
+            crv: z.ZodLiteral<"Ed25519">;
+            x: z.ZodString;
+        }, z.core.$strip>;
+        validFrom: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+        validUntil: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+        revokedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    updatedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type ControlPlaneConnection = z.output<typeof ControlPlaneConnection>;
+export type ControlPlaneConnectionRow = z.input<typeof ControlPlaneConnection>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/controlPlane/data/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/connection.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB;;;;iBAgBoF,CAAC;AAClH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;iBAoBoF,CAAC;AAC/G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4ChC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC7E,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/controlPlane/data/connection.js

@@ -0,0 +1,55 @@
+import { ControlPlaneScope } from "../scope/scope.js";
+import { JsonDate, SQLiteDate, sqliteJson } from "../../data/codecs.js";
+import { z } from "zod";
+//#region src/controlPlane/data/connection.ts
+/**
+* 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. */
+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.");
+/**
+* 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.
+*/
+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.");
+/**
+* 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.
+*/
+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.");
+//#endregion
+export { ControlPlaneConnection, Ed25519PublicJwk, RegisteredKey };

package/dist/controlPlane/data/keyLifecycle.d.ts

@@ -0,0 +1,62 @@
+import type { RegisteredKey } from "./connection";
+/**
+ * The registered-key lifecycle: pure array logic over a connection's `keys` column.
+ *
+ * **Registering a key and expiring one are two operations, and folding them into a single `rotate()`
+ * is the one design mistake this module exists to prevent.** One call would make append-and-expire
+ * atomic, and atomic is precisely wrong here. The whole safety property is that the old key outlives
+ * the new one's first successful call: a mis-copied JWK, a private key the management client cannot
+ * actually sign with, or a Worker that never answers leaves the adopter holding a credential that
+ * still works. Fuse the two writes together and that same mistake locks them out of the seam with
+ * nothing left to authenticate the fix with. Kept apart, a broken rotation costs a stale key.
+ *
+ * So the safe ordering is enforced here rather than documented: {@link appendKey} may not touch an
+ * existing key's window, and {@link expireKey} refuses unless another key is already live.
+ *
+ * Nothing in this module reads a clock, a binding, or D1. `now` is injected on every call, which is
+ * what lets a test assert what a connection looks like a year into a failed rotation.
+ */
+/** Every key that may verify a call at `now`: not revoked, started, and not yet ended. */
+export declare function activeKeys(keys: readonly RegisteredKey[], now: Date): RegisteredKey[];
+/**
+ * The key that may verify this call, or null. Matching on `kid` alone would be the vulnerability —
+ * the window and the revocation are checked here so no caller can forget them.
+ */
+export declare function findVerifyingKey(keys: readonly RegisteredKey[], keyId: string, now: Date): RegisteredKey | null;
+/**
+ * Register a key. Appends, and appends only — no existing key's `validUntil` moves, so a connection
+ * mid-rotation always has the key it arrived with.
+ *
+ * A key that is already retired at `now` is refused rather than stored: it could never be proven by a
+ * ping, so registering it would only offer a second step that can never safely be taken.
+ */
+export declare function appendKey(keys: readonly RegisteredKey[], key: RegisteredKey, now: Date): RegisteredKey[];
+/**
+ * Close a key's window at `now`, once a replacement has proven itself.
+ *
+ * `provenKeyId` is the key that verified the request asking for this expiry — proof by use, and the
+ * reason the seam's `ping` scope is held implicitly by every connection. Two refusals guard the
+ * ordering: a prover that is not itself live has proven nothing, and an expiry that would leave no
+ * live key is the lockout, whatever the caller believes about their replacement.
+ *
+ * Re-expiring a key already closed is a no-op on its end date. The window a call was rejected under
+ * must not move retroactively.
+ */
+export declare function expireKey(keys: readonly RegisteredKey[], keyId: string, options: {
+    provenKeyId: string;
+    now: Date;
+}): RegisteredKey[];
+/**
+ * Drop keys retired longer ago than `retentionMs`, then cap the array at `maxKeys`.
+ *
+ * The column is versioned, not a log — a superseded key is kept only long enough for the audit trail
+ * and a `GET /control-plane/keys` to explain a rotation. Two keys are never dropped: a live one, and
+ * one registered ahead of its `validFrom`, which is unretired rather than dead. So the cap is a
+ * target, not a guarantee; a connection with more live keys than `maxKeys` keeps all of them.
+ */
+export declare function pruneKeys(keys: readonly RegisteredKey[], options: {
+    now: Date;
+    retentionMs: number;
+    maxKeys: number;
+}): RegisteredKey[];
+//# sourceMappingURL=keyLifecycle.d.ts.map

package/dist/controlPlane/data/keyLifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyLifecycle.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/keyLifecycle.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AAEH,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,aAAa,EAAE,CAErF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,aAAa,GAAG,IAAI,CAE/G;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,IAAI,GAAG,aAAa,EAAE,CAgBxG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAC1C,aAAa,EAAE,CAwBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,OAAO,EAAE;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3D,aAAa,EAAE,CAyBjB"}