@pithy-sh/core 0.1.0

package/src/controlPlane/http/handlers.ts

@@ -0,0 +1,346 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { workerVersion } from "../../worker/identity";
+import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
+import type { ControlPlaneConfig } from "../config/config";
+import type { ControlPlaneContext } from "../context";
+import { ControlPlaneConnection, type RegisteredKey } from "../data/connection";
+import { appendKey, expireKey, pruneKeys } from "../data/keyLifecycle";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase } from "../data/tables";
+import type { CapabilityDeclaration, ControlPlaneManifestWire } from "../discovery/adminRoute";
+import { type CapabilityHealthSource, readCapabilityHealth } from "../discovery/health";
+import { healthWire } from "../discovery/healthSummary";
+import { ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError } from "../error/errors";
+import type {
+  ControlPlaneKeysResponse,
+  ControlPlanePingResponse,
+  ExpireKeyResponse,
+  PublicKeyView,
+  RegisterKeyResponse,
+} from "./responses";
+import type { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas";
+
+/**
+ * The seam's own route handlers.
+ *
+ * Every one runs behind `requireControlPlane`, so `c.var.controlPlane` is set by the time any of them
+ * is entered. They read it rather than re-deriving anything: the verification decision is made once,
+ * in `verify.ts`, and a handler that second-guessed it would be a second place for the rules to drift.
+ *
+ * **Nothing here returns a key's private half, because none is ever held.** `GET /control-plane/keys`
+ * returns public keys and their windows, which is exactly what a management client needs to see that a
+ * key is ageing and exactly what an attacker learns nothing from.
+ *
+ * **Every response has an exported schema**, in `responses.ts`, and each `c.json` below is
+ * `satisfies`-checked against it. A management client imports the same object and validates with it
+ * rather than hand-writing a mirror that drifts. The check is at compile time on purpose: parsing every
+ * response would spend a validation pass on values this Worker just built, and would turn a shape
+ * mistake into a 500 in production rather than a red build.
+ */
+
+/** A day, in ms — `keyRetentionDays` is expressed in days because that is how anyone reasons about it. */
+const MS_PER_DAY = 86_400_000;
+
+/** The pieces of the composed capability a handler needs. Passed in, so nothing reaches for a global. */
+export interface ControlPlaneHandlerDeps {
+  /** The resolved seam config — pruning bounds, mostly. */
+  config: ControlPlaneConfig;
+  /** The app database, resolved per request from the `DB` binding. */
+  database: (c: Context<PithyHonoEnv>) => ControlPlaneDatabase;
+  /**
+   * The names of every capability this Worker composed, captured by the capability's `compose` hook at
+   * assembly. A thunk because that hook runs after the routes closure is built.
+   *
+   * This is assembly-time knowledge no capability has about its siblings, and it is what makes
+   * **discovery over configuration** work: a management client builds its navigation *and its calls*
+   * from what a Worker declares, so a Worker without payments simply has no purchases pane, and
+   * `pithy add support` produces a working support pane with nothing for either side to configure.
+   */
+  composedCapabilities: () => readonly CapabilityDeclaration[];
+  /**
+   * The health summary each capability contributes, by capability name — captured by the same `compose`
+   * hook, and checked there against the scopes that capability's own routes require.
+   *
+   * Separate from {@link composedCapabilities} because a declaration is the same for every caller and a
+   * value is not: the numbers are resolved per request, behind the scope each one is declared under.
+   */
+  composedHealth: () => ReadonlyMap<string, CapabilityHealthSource>;
+  /** The clock, injected so a test can stand at any instant. */
+  now: () => Date;
+}
+
+/** The verified caller. Never null here — `requireControlPlane` ran first, or this code is unreachable. */
+function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
+  const context = c.var.controlPlane;
+  if (!context) {
+    // Defense in depth against a route line assembled without the gate. It cannot happen through
+    // `registerControlPlaneRoutes`, and if it ever did the failure must be a denial rather than a
+    // handler reading `undefined` and carrying on.
+    throw new ControlPlaneInvalidCredentialError({ detail: "handler reached with no verified control-plane caller" });
+  }
+  return context;
+}
+
+/** Load the connection this call authenticated against. It verified moments ago, so it exists. */
+async function loadConnection(
+  db: ControlPlaneDatabase,
+  connectionId: string,
+): Promise<{ connection: ControlPlaneConnection }> {
+  const row = await db
+    .selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE)
+    .selectAll()
+    .where("id", "=", connectionId)
+    .executeTakeFirst();
+  if (!row) {
+    // The row was deleted between verification and here — a revocation landing mid-request. Denying is
+    // the correct answer: revocation is meant to be immediate.
+    throw new ControlPlaneInvalidCredentialError({ detail: `connection ${connectionId} disappeared mid-request` });
+  }
+  return { connection: ControlPlaneConnection.parse(row) };
+}
+
+/** Write a connection's key array back, stamping `updatedAt`. One UPDATE — a rotation cannot half-apply. */
+async function saveKeys(
+  db: ControlPlaneDatabase,
+  connectionId: string,
+  keys: readonly RegisteredKey[],
+  now: Date,
+): Promise<void> {
+  const encoded = ControlPlaneConnection.shape.keys.encode([...keys]);
+  await db
+    .updateTable(CONTROL_PLANE_CONNECTIONS_TABLE)
+    .set({ keys: encoded, updatedAt: ControlPlaneConnection.shape.updatedAt.encode(now) })
+    .where("id", "=", connectionId)
+    .execute();
+}
+
+/**
+ * The public view of one registered key. Windows and ages, never anything secret.
+ *
+ * The return type is `z.output` of the exported schema, so what this sends and what a management
+ * client validates against are one declaration rather than two that drift. It was
+ * `Record<string, unknown>`, which is not a contract at all.
+ */
+function publicKeyView(key: RegisteredKey): PublicKeyView {
+  return {
+    keyId: key.keyId,
+    publicKey: key.publicKey,
+    validFrom: key.validFrom.toISOString(),
+    validUntil: key.validUntil?.toISOString() ?? null,
+    revokedAt: key.revokedAt?.toISOString() ?? null,
+  };
+}
+
+/**
+ * `GET /control-plane/ping` — connectivity and key proof.
+ *
+ * The most important route here despite doing nothing, because it is what a management client calls to
+ * prove a newly registered key **before** the key it replaces is expired. Requires a verified caller
+ * and no scope: a connection granted nothing must still be able to prove a key, or rotation has a state
+ * it cannot get out of.
+ *
+ * It echoes the `keyId` that verified the call, so the client can confirm *which* key answered rather
+ * than inferring it from a 200.
+ */
+export function pingHandler(deps: ControlPlaneHandlerDeps) {
+  return (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    return c.json({
+      status: "ok",
+      connectionId: context.connectionId,
+      environment: context.environment,
+      keyId: context.keyId,
+      now: deps.now().toISOString(),
+    } satisfies ControlPlanePingResponse);
+  };
+}
+
+/**
+ * `GET /control-plane/manifest` — what this Worker is, what it composes, and how each part is doing.
+ *
+ * Discovery over configuration. A client builds its navigation from this rather than from settings
+ * someone maintains, so a Worker with no payments capability has no purchases pane as a matter of fact.
+ *
+ * **And the numbers a client would otherwise pay a second round trip for** (#317). Each capability's
+ * bounded summary is resolved here, behind the scope that capability's own read is behind: a connection
+ * without it gets no number rather than a zero, and never costs the adopter's Worker the query.
+ *
+ * **One capability's failure costs one capability's number** (#350). A producer that throws, or that
+ * reports something its declaration cannot name, lands on `unavailable` for that entry alone —
+ * `readCapabilityHealth` catches it, so nothing rejects, so `Promise.all` still resolves and every
+ * sibling still reports. This route is what the whole management surface is built from; a manifest that
+ * 500s takes every pane with it, and the capability at fault is the one thing the screen could not then
+ * name.
+ */
+export function manifestHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    const sources = deps.composedHealth();
+    // In parallel: each producer is bounded by its own declaration, and a Worker composing several has
+    // no reason to serialize numbers that do not depend on each other.
+    const capabilities = await Promise.all(
+      deps.composedCapabilities().map(async (declaration) => ({
+        ...declaration,
+        // Spread, so the values and the failure flag are written together or not at all. A handler that
+        // set one and forgot the other is the shape of defect the four-state value exists to prevent.
+        ...healthWire(
+          await readCapabilityHealth(sources.get(declaration.name), context.grantedScopes, (source) => source.read(c)),
+        ),
+      })),
+    );
+    return c.json({
+      environment: context.environment,
+      connectionId: context.connectionId,
+      // The build answering this call. Read per request rather than captured at assembly: it is the
+      // same binding every log record and audit event reads, and there is one reader for it.
+      version: workerVersion(c.env),
+      capabilities,
+      grantedScopes: [...context.grantedScopes],
+    } satisfies ControlPlaneManifestWire);
+  };
+}
+
+/** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
+export function listKeysHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>) => {
+    const context = caller(c);
+    const { connection } = await loadConnection(deps.database(c), context.connectionId);
+    return c.json({
+      connectionId: connection.id,
+      environment: connection.environment,
+      keys: connection.keys.map(publicKeyView),
+    } satisfies ControlPlaneKeysResponse);
+  };
+}
+
+/**
+ * `POST /control-plane/keys` — register a new public key, authenticated by the key it succeeds.
+ *
+ * This is the route the whole rotation story rests on, and its authentication is the subtle part: the
+ * request is signed with the key being replaced. That is what makes rotation self-bootstrapping —
+ * trust flows forward from existing trust, exactly as a rotated refresh token does — and what makes an
+ * unreachable Worker a deferral rather than a lockout.
+ *
+ * It appends and only appends. The new key's window opens now and no existing key's window moves.
+ */
+export function registerKeyHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, body: RegisterKeyRequest) => {
+    const context = caller(c);
+    const db = deps.database(c);
+    const now = deps.now();
+    const { connection } = await loadConnection(db, context.connectionId);
+
+    const appended = appendKey(
+      connection.keys,
+      { keyId: body.keyId, publicKey: body.publicKey, validFrom: now, validUntil: null, revokedAt: null },
+      now,
+    );
+    const pruned = pruneKeys(appended, {
+      now,
+      retentionMs: deps.config.keyRetentionDays * MS_PER_DAY,
+      maxKeys: deps.config.maxKeys,
+    });
+    await saveKeys(db, connection.id, pruned, now);
+
+    await safeEmit(
+      c.var.emit,
+      {
+        action: ControlPlaneAuditActions.keyRegistered,
+        outcome: "success",
+        severity: "warning",
+        actorType: "control-plane",
+        actorId: context.subject,
+        resourceType: "controlplane_connection",
+        resourceId: connection.id,
+        requestId: c.req.header("cf-ray"),
+        ip: c.req.header("cf-connecting-ip"),
+        userAgent: c.req.header("user-agent"),
+        // Key ids, never key material. A registered key changing in an adopter's system is exactly what
+        // looks alarming during a security review, so the trail names both sides of the handover.
+        metadata: {
+          connectionId: connection.id,
+          registeredKeyId: body.keyId,
+          signedWithKeyId: context.keyId,
+          connectionEnvironment: connection.environment,
+        },
+      },
+      c.var.log,
+    );
+
+    return c.json(
+      {
+        keyId: body.keyId,
+        validFrom: now.toISOString(),
+        keys: pruned.map(publicKeyView),
+      } satisfies RegisterKeyResponse,
+      201,
+    );
+  };
+}
+
+/**
+ * `POST /control-plane/keys/:keyId/expire` — retire a superseded key, once its replacement is proven.
+ *
+ * A separate call from registration, deliberately. Folding them into one would make append-and-expire
+ * atomic, and atomic is precisely wrong here: the point is that the old key survives until the new one
+ * has been proven against a live ping. `expireKey` enforces both halves of that — the named successor
+ * must currently verify, and the expiry must not empty the connection's live set.
+ *
+ * **And the successor must be the key that signed this very request.** That is what "proof by use"
+ * means, and checking only that `provenKeyId` names *some* live key would not deliver it: a client
+ * still signing with the old key could name a successor it has never successfully used and retire the
+ * one thing that currently works. The client asserts which key it believes proved itself, the seam
+ * compares that against which key actually did, and a client that is wrong about its own rotation gets
+ * a 409 instead of a lockout.
+ */
+export function expireKeyHandler(deps: ControlPlaneHandlerDeps) {
+  return async (c: Context<PithyHonoEnv>, params: ExpireKeyParams, body: ExpireKeyRequest) => {
+    const context = caller(c);
+    const db = deps.database(c);
+    const now = deps.now();
+    const { connection } = await loadConnection(db, context.connectionId);
+
+    if (body.provenKeyId !== context.keyId) {
+      throw new ControlPlaneKeyConflictError({
+        message: "Sign this request with the replacement key you are naming as proven.",
+        action: "Rotate to the new key, make a call with it, then expire the old one in that same call.",
+        detail: `provenKeyId ${body.provenKeyId} is not the key that signed this request (${context.keyId})`,
+      });
+    }
+
+    const expired = expireKey(connection.keys, params.keyId, { provenKeyId: body.provenKeyId, now });
+    await saveKeys(db, connection.id, expired, now);
+
+    await safeEmit(
+      c.var.emit,
+      {
+        action: ControlPlaneAuditActions.keyExpired,
+        outcome: "success",
+        severity: "warning",
+        actorType: "control-plane",
+        actorId: context.subject,
+        resourceType: "controlplane_connection",
+        resourceId: connection.id,
+        requestId: c.req.header("cf-ray"),
+        ip: c.req.header("cf-connecting-ip"),
+        userAgent: c.req.header("user-agent"),
+        metadata: {
+          connectionId: connection.id,
+          expiredKeyId: params.keyId,
+          provenKeyId: body.provenKeyId,
+          connectionEnvironment: connection.environment,
+        },
+      },
+      c.var.log,
+    );
+
+    return c.json({
+      keyId: params.keyId,
+      validUntil: now.toISOString(),
+      keys: expired.map(publicKeyView),
+    } satisfies ExpireKeyResponse);
+  };
+}

package/src/controlPlane/http/responses.ts

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { Ed25519PublicJwk } from "../data/connection";
+
+/**
+ * What the seam's own routes return, as Zod objects a management client can validate against.
+ *
+ * `schemas.ts` bounds what a caller may send; this file states what it gets back. Both halves are
+ * runtime values for the same reason: a management client reading a customer's Worker is crossing a
+ * trust boundary and must validate what comes back, and a TypeScript interface is erased before it
+ * can help. `GET /control-plane/manifest` already had a schema — {@link ControlPlaneManifest}, in
+ * `discovery/adminRoute.ts`, because it is the discovery contract rather than a projection — and the
+ * other four routes had none at all, `publicKeyView` returning a bare `Record<string, unknown>`.
+ *
+ * **No codecs, and no transform anywhere in this file.** These describe JSON on the wire, so parsing
+ * one hands back exactly what went in — which is what lets a test compare the parsed value with a live
+ * response and fail on a field either side forgot. A `JsonDate` here would decode an ISO string into a
+ * `Date` and make that comparison meaningless.
+ *
+ * **Nothing here can carry a private key, because none is ever held.** The connection stores public
+ * halves only, so `keys` is exactly what a client needs to see a key ageing and exactly what an
+ * attacker learns nothing from.
+ */
+
+/** One registered key as a client sees it: the public half and its window. */
+export const PublicKeyView = z
+  .object({
+    keyId: z.string().describe("The key's id, matched against a token's `kid` header."),
+    publicKey: Ed25519PublicJwk.describe("The public key this id names. The private half is never held here."),
+    validFrom: z.iso.datetime().describe("When this key became valid, ISO-8601. A call signed before it is rejected."),
+    validUntil: z.iso
+      .datetime()
+      .nullable()
+      .describe("When it stops being accepted, ISO-8601, or null while open-ended. Set only by the expire route."),
+    revokedAt: z.iso
+      .datetime()
+      .nullable()
+      .describe("When it was revoked outright, ISO-8601, or null. Revocation ignores the window and is immediate."),
+  })
+  .describe("One registered public key and its validity window. Two live at once during a rotation overlap.");
+export type PublicKeyView = z.output<typeof PublicKeyView>;
+
+/**
+ * `GET /control-plane/ping`.
+ *
+ * It echoes the `keyId` that verified the call, so a client rotating a key can confirm *which* key
+ * answered rather than inferring it from a 200 — which is the whole point of the route.
+ */
+export const ControlPlanePingResponse = z
+  .object({
+    status: z.literal("ok").describe("Always `ok`. A failure is an error payload, never this shape."),
+    connectionId: z.string().describe("The connection this call authenticated as."),
+    environment: z.string().describe("The environment that connection is bound to."),
+    keyId: z.string().describe("The key that verified this call. The proof a newly registered key works."),
+    now: z.iso.datetime().describe("This Worker's clock, ISO-8601 — what a token's lifetime is judged against."),
+  })
+  .describe("Connectivity, and proof of which key answered.");
+export type ControlPlanePingResponse = z.output<typeof ControlPlanePingResponse>;
+
+/** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
+export const ControlPlaneKeysResponse = z
+  .object({
+    connectionId: z.string().describe("The connection these keys belong to."),
+    environment: z.string().describe("The environment that connection is bound to."),
+    keys: z.array(PublicKeyView).describe("Every registered key, expired and revoked ones included."),
+  })
+  .describe("Every key registered against this connection, with its window.");
+export type ControlPlaneKeysResponse = z.output<typeof ControlPlaneKeysResponse>;
+
+/** `POST /control-plane/keys` — the appended key, and the set as it now stands. */
+export const RegisterKeyResponse = z
+  .object({
+    keyId: z.string().describe("The key just registered."),
+    validFrom: z.iso.datetime().describe("When its window opened, ISO-8601 — now, by construction."),
+    keys: z
+      .array(PublicKeyView)
+      .describe("The connection's keys after the append and the prune, so a client sees what it now holds."),
+  })
+  .describe("The registered key, and the set it joined.");
+export type RegisterKeyResponse = z.output<typeof RegisterKeyResponse>;
+
+/** `POST /control-plane/keys/:keyId/expire` — the retired key, and the set as it now stands. */
+export const ExpireKeyResponse = z
+  .object({
+    keyId: z.string().describe("The key just given an end date."),
+    validUntil: z.iso.datetime().describe("When its window closed, ISO-8601 — now, by construction."),
+    keys: z.array(PublicKeyView).describe("The connection's keys after the expiry."),
+  })
+  .describe("The expired key, and the set it left behind.");
+export type ExpireKeyResponse = z.output<typeof ExpireKeyResponse>;

package/src/controlPlane/http/routes.ts

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { Hono } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { validationHook } from "../../http/validation";
+import type { AdminRoute } from "../discovery/adminRoute";
+import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE } from "../scope/scope";
+import { requireControlPlane } from "./guard";
+import {
+  type ControlPlaneHandlerDeps,
+  expireKeyHandler,
+  listKeysHandler,
+  manifestHandler,
+  pingHandler,
+  registerKeyHandler,
+} from "./handlers";
+import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas";
+
+/**
+ * The seam's own routes, distinct from the admin routes capabilities contribute.
+ *
+ *   GET  /control-plane/ping                  → connectivity and key proof   (any verified caller)
+ *   GET  /control-plane/manifest              → what this Worker composes    (manifest:read)
+ *   GET  /control-plane/keys                  → the registration state       (keys:rotate)
+ *   POST /control-plane/keys                  → register a key               (keys:rotate)
+ *   POST /control-plane/keys/:keyId/expire    → retire a superseded key      (keys:rotate)
+ *
+ * Every one is `control-plane` and default-denied — with no connection registered they all answer 403,
+ * and that is the shipped state of a Worker nobody has connected.
+ *
+ * **Guards precede validators on every line.** A validator first would turn a 401 into a 400 and tell a
+ * caller with no credential which request shapes were well-formed. On these routes that is a live
+ * oracle over key registration, which is the last thing that should be probeable.
+ *
+ * The three key routes share one scope. Reading which keys are live, registering the next one, and
+ * retiring the last are one lifecycle, and an adopter deciding whether a management client may touch
+ * their keys is making one decision, not three.
+ *
+ * The table is declared twice on purpose — once as descriptors a client can read, once as the
+ * registrations themselves — and `routeContract.test.ts` proves the two agree.
+ */
+
+/**
+ * The seam's own routes, described for `GET /control-plane/manifest`.
+ *
+ * Derived from the same `basePath` the routes below mount on, so the two cannot disagree — and the
+ * seam holds itself to the rule it imposes on every capability: `controlPlaneRouteDescriptors` is
+ * checked against the mounted router by `missingAdminRoutes` in `routeContract.test.ts`.
+ *
+ * `ping` carries a null scope. It requires a verified caller and no authorization, and saying so is
+ * how a client knows it can always prove a key — including on a connection granted nothing at all.
+ */
+export function controlPlaneRouteDescriptors(basePath: string): AdminRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${basePath}/ping`,
+      scope: null,
+      summary: "Prove connectivity and which key answered. Always available to a verified caller.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/manifest`,
+      scope: MANIFEST_READ_SCOPE,
+      summary: "What this Worker composes, and how to call each capability's admin surface.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/keys`,
+      scope: KEYS_ROTATE_SCOPE,
+      summary: "The registered keys, their validity windows, and their ages.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/keys`,
+      scope: KEYS_ROTATE_SCOPE,
+      summary: "Register a successor public key. Signed with the key it replaces; appends only.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/keys/:keyId/expire`,
+      scope: KEYS_ROTATE_SCOPE,
+      summary: "Retire a superseded key. Must be signed with the successor it names as proven.",
+    },
+  ];
+}
+
+export function registerControlPlaneRoutes(
+  app: Hono<PithyHonoEnv>,
+  basePath: string,
+  deps: ControlPlaneHandlerDeps,
+): void {
+  app.get(`${basePath}/ping`, requireControlPlane(ANY_VERIFIED_CALLER), pingHandler(deps));
+
+  app.get(`${basePath}/manifest`, requireControlPlane(MANIFEST_READ_SCOPE), manifestHandler(deps));
+
+  app.get(`${basePath}/keys`, requireControlPlane(KEYS_ROTATE_SCOPE), listKeysHandler(deps));
+
+  app.post(
+    `${basePath}/keys`,
+    requireControlPlane(KEYS_ROTATE_SCOPE),
+    zValidator("json", RegisterKeyRequest, validationHook),
+    (c) => registerKeyHandler(deps)(c, c.req.valid("json")),
+  );
+
+  app.post(
+    `${basePath}/keys/:keyId/expire`,
+    requireControlPlane(KEYS_ROTATE_SCOPE),
+    zValidator("param", ExpireKeyParams, validationHook),
+    zValidator("json", ExpireKeyRequest, validationHook),
+    (c) => expireKeyHandler(deps)(c, c.req.valid("param"), c.req.valid("json")),
+  );
+}

package/src/controlPlane/http/schemas.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { Ed25519PublicJwk } from "../data/connection";
+
+/**
+ * The request contract for the seam's own routes. Every input surface is validated here and read in a
+ * handler through `c.req.valid(target)` — a handler never parses input (CLAUDE.md §HTTP).
+ *
+ * These are the highest-risk routes in the product, so two of the choices below are deliberate and
+ * would be wrong to "tighten" later:
+ *
+ * **`keyId` is a bounded string, not a `z.uuid()`.** A key id is opaque and minted by the management
+ * client, so its format is not ours to constrain. More importantly, an unknown-but-well-formed key id
+ * must reach the handler and answer `controlplane/key_not_found` rather than bouncing off a 400 — a
+ * validator that rejected unfamiliar shapes would turn the route into an enumeration oracle telling a
+ * caller which ids exist.
+ *
+ * **Nothing here validates a scope or a connection id.** Those arrive in the signed token, not the
+ * request, and are verified against the adopter's own row before a handler runs. A body that could
+ * name its own scope would be a body that could grant itself one.
+ */
+
+/** `POST /control-plane/keys` — register a new public key, signed by the key it succeeds. */
+export const RegisterKeyRequest = z
+  .object({
+    keyId: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe("The new key's id, which a later token names in its `kid` header. Must not already be registered."),
+    publicKey: Ed25519PublicJwk.describe(
+      "The Ed25519 public key to trust. Only the public half ever crosses the wire — the management client keeps the private key and the adopter never holds anything worth stealing.",
+    ),
+  })
+  .describe(
+    "A request to append one public key to this connection. Appends only: it never touches an existing key's validity, which is what makes a failed rotation harmless.",
+  );
+export type RegisterKeyRequest = z.infer<typeof RegisterKeyRequest>;
+
+/** `POST /control-plane/keys/:keyId/expire` — the path segment naming the key to retire. */
+export const ExpireKeyParams = z
+  .object({
+    keyId: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe(
+        "The key to give an end date. Bounded but unconstrained in shape — an unknown id answers 404, not 400.",
+      ),
+  })
+  .describe("The path parameters of the key-expiry route.");
+export type ExpireKeyParams = z.infer<typeof ExpireKeyParams>;
+
+/** `POST /control-plane/keys/:keyId/expire` — the body, carrying the proof that a successor works. */
+export const ExpireKeyRequest = z
+  .object({
+    provenKeyId: z
+      .string()
+      .min(1)
+      .max(64)
+      .describe(
+        "The replacement key that has already been proven against a live `ping`. Required, and checked to be currently active: expiring a key without naming a working successor is the one failure mode with no recovery path, so the route refuses rather than trusting the caller to have checked.",
+      ),
+  })
+  .describe(
+    "A request to expire one superseded key. The successor must be named and must already be live — append, verify, then expire, never replace.",
+  );
+export type ExpireKeyRequest = z.infer<typeof ExpireKeyRequest>;