@pithy-sh/core 0.1.2 → 0.1.3

package/dist/controlPlane/http/handlers.js

@@ -0,0 +1,245 @@
+import { workerVersion } from "../../worker/identity.js";
+import { ControlPlaneConnection } from "../data/connection.js";
+import { CONTROL_PLANE_CONNECTIONS_TABLE } from "../data/tables.js";
+import { healthWire } from "../discovery/healthSummary.js";
+import { readCapabilityHealth } from "../discovery/health.js";
+import { ControlPlaneAuditActions, safeEmit } from "../audit/actions.js";
+import { ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError } from "../error/errors.js";
+import { appendKey, expireKey, pruneKeys } from "../data/keyLifecycle.js";
+//#region src/controlPlane/http/handlers.ts
+/**
+* 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 = 864e5;
+/** The verified caller. Never null here — `requireControlPlane` ran first, or this code is unreachable. */
+function caller(c) {
+	const context = c.var.controlPlane;
+	if (!context) 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, connectionId) {
+	const row = await db.selectFrom(CONTROL_PLANE_CONNECTIONS_TABLE).selectAll().where("id", "=", connectionId).executeTakeFirst();
+	if (!row) 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, connectionId, keys, now) {
+	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) {
+	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.
+*/
+function pingHandler(deps) {
+	return (c) => {
+		const context = caller(c);
+		return c.json({
+			status: "ok",
+			connectionId: context.connectionId,
+			environment: context.environment,
+			keyId: context.keyId,
+			now: deps.now().toISOString()
+		});
+	};
+}
+/**
+* `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.
+*/
+function manifestHandler(deps) {
+	return async (c) => {
+		const context = caller(c);
+		const sources = deps.composedHealth();
+		const capabilities = await Promise.all(deps.composedCapabilities().map(async (declaration) => ({
+			...declaration,
+			...healthWire(await readCapabilityHealth(sources.get(declaration.name), context.grantedScopes, (source) => source.read(c)))
+		})));
+		return c.json({
+			environment: context.environment,
+			connectionId: context.connectionId,
+			version: workerVersion(c.env),
+			capabilities,
+			grantedScopes: [...context.grantedScopes]
+		});
+	};
+}
+/** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
+function listKeysHandler(deps) {
+	return async (c) => {
+		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)
+		});
+	};
+}
+/**
+* `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.
+*/
+function registerKeyHandler(deps) {
+	return async (c, body) => {
+		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"),
+			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)
+		}, 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.
+*/
+function expireKeyHandler(deps) {
+	return async (c, params, body) => {
+		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)
+		});
+	};
+}
+//#endregion
+export { expireKeyHandler, listKeysHandler, manifestHandler, pingHandler, registerKeyHandler };

package/dist/controlPlane/http/responses.d.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+/**
+ * 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 declare const PublicKeyView: z.ZodObject<{
+    keyId: z.ZodString;
+    publicKey: z.ZodObject<{
+        kty: z.ZodLiteral<"OKP">;
+        crv: z.ZodLiteral<"Ed25519">;
+        x: z.ZodString;
+    }, z.core.$strip>;
+    validFrom: z.ZodISODateTime;
+    validUntil: z.ZodNullable<z.ZodISODateTime>;
+    revokedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+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 declare const ControlPlanePingResponse: z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    connectionId: z.ZodString;
+    environment: z.ZodString;
+    keyId: z.ZodString;
+    now: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ControlPlanePingResponse = z.output<typeof ControlPlanePingResponse>;
+/** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
+export declare const ControlPlaneKeysResponse: z.ZodObject<{
+    connectionId: z.ZodString;
+    environment: z.ZodString;
+    keys: 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.ZodISODateTime;
+        validUntil: z.ZodNullable<z.ZodISODateTime>;
+        revokedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ControlPlaneKeysResponse = z.output<typeof ControlPlaneKeysResponse>;
+/** `POST /control-plane/keys` — the appended key, and the set as it now stands. */
+export declare const RegisterKeyResponse: z.ZodObject<{
+    keyId: z.ZodString;
+    validFrom: z.ZodISODateTime;
+    keys: 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.ZodISODateTime;
+        validUntil: z.ZodNullable<z.ZodISODateTime>;
+        revokedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RegisterKeyResponse = z.output<typeof RegisterKeyResponse>;
+/** `POST /control-plane/keys/:keyId/expire` — the retired key, and the set as it now stands. */
+export declare const ExpireKeyResponse: z.ZodObject<{
+    keyId: z.ZodString;
+    validUntil: z.ZodISODateTime;
+    keys: 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.ZodISODateTime;
+        validUntil: z.ZodNullable<z.ZodISODateTime>;
+        revokedAt: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExpireKeyResponse = z.output<typeof ExpireKeyResponse>;
+//# sourceMappingURL=responses.d.ts.map

package/dist/controlPlane/http/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/responses.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,aAAa;;;;;;;;;;iBAcmF,CAAC;AAC9G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;iBAQwB,CAAC;AAC9D,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,+FAA+F;AAC/F,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;iBAMwC,CAAC;AAC9E,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,mFAAmF;AACnF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAQyB,CAAC;AAC1D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,gGAAgG;AAChG,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAM6B,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/controlPlane/http/responses.js

@@ -0,0 +1,63 @@
+import { Ed25519PublicJwk } from "../data/connection.js";
+import { z } from "zod";
+//#region src/controlPlane/http/responses.ts
+/**
+* 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. */
+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.");
+/**
+* `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.
+*/
+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.");
+/** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
+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.");
+/** `POST /control-plane/keys` — the appended key, and the set as it now stands. */
+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.");
+/** `POST /control-plane/keys/:keyId/expire` — the retired key, and the set as it now stands. */
+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.");
+//#endregion
+export { ControlPlaneKeysResponse, ControlPlanePingResponse, ExpireKeyResponse, PublicKeyView, RegisterKeyResponse };

package/dist/controlPlane/http/routes.d.ts

@@ -0,0 +1,40 @@
+import type { Hono } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import type { AdminRoute } from "../discovery/adminRoute";
+import { type ControlPlaneHandlerDeps } from "./handlers";
+/**
+ * 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 declare function controlPlaneRouteDescriptors(basePath: string): AdminRoute[];
+export declare function registerControlPlaneRoutes(app: Hono<PithyHonoEnv>, basePath: string, deps: ControlPlaneHandlerDeps): void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/controlPlane/http/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/routes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,EACL,KAAK,uBAAuB,EAM7B,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAiC3E;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,uBAAuB,GAC5B,IAAI,CAqBN"}

package/dist/controlPlane/http/routes.js

@@ -0,0 +1,83 @@
+import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE } from "../scope/scope.js";
+import { requireControlPlane } from "./guard.js";
+import { validationHook } from "../../http/validation.js";
+import { expireKeyHandler, listKeysHandler, manifestHandler, pingHandler, registerKeyHandler } from "./handlers.js";
+import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas.js";
+import { zValidator } from "@hono/zod-validator";
+//#region src/controlPlane/http/routes.ts
+/**
+* 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.
+*/
+function controlPlaneRouteDescriptors(basePath) {
+	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."
+		}
+	];
+}
+function registerControlPlaneRoutes(app, basePath, deps) {
+	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")));
+}
+//#endregion
+export { controlPlaneRouteDescriptors, registerControlPlaneRoutes };

package/dist/controlPlane/http/schemas.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/**
+ * 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 declare const RegisterKeyRequest: z.ZodObject<{
+    keyId: z.ZodString;
+    publicKey: z.ZodObject<{
+        kty: z.ZodLiteral<"OKP">;
+        crv: z.ZodLiteral<"Ed25519">;
+        x: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RegisterKeyRequest = z.infer<typeof RegisterKeyRequest>;
+/** `POST /control-plane/keys/:keyId/expire` — the path segment naming the key to retire. */
+export declare const ExpireKeyParams: z.ZodObject<{
+    keyId: z.ZodString;
+}, z.core.$strip>;
+export type ExpireKeyParams = z.infer<typeof ExpireKeyParams>;
+/** `POST /control-plane/keys/:keyId/expire` — the body, carrying the proof that a successor works. */
+export declare const ExpireKeyRequest: z.ZodObject<{
+    provenKeyId: z.ZodString;
+}, z.core.$strip>;
+export type ExpireKeyRequest = z.infer<typeof ExpireKeyRequest>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/controlPlane/http/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/schemas.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;GAgBG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB;;;;;;;iBAa5B,CAAC;AACJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,4FAA4F;AAC5F,eAAO,MAAM,eAAe;;iBAU+B,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,sGAAsG;AACtG,eAAO,MAAM,gBAAgB;;iBAY1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/controlPlane/http/schemas.js

@@ -0,0 +1,31 @@
+import { Ed25519PublicJwk } from "../data/connection.js";
+import { z } from "zod";
+//#region src/controlPlane/http/schemas.ts
+/**
+* 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. */
+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.");
+/** `POST /control-plane/keys/:keyId/expire` — the path segment naming the key to retire. */
+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.");
+/** `POST /control-plane/keys/:keyId/expire` — the body, carrying the proof that a successor works. */
+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.");
+//#endregion
+export { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest };