@pithy-sh/core 0.1.1 → 0.1.3

package/dist/controlPlane/http/cors.js

@@ -0,0 +1,192 @@
+import "../../worker/identity.js";
+import { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire.js";
+import "../../naming/environment.js";
+//#region src/controlPlane/http/cors.ts
+/**
+* CORS for the control-plane surface — the one thing standing between a browser and a Worker that is
+* up, healthy, and answering.
+*
+* **Why this exists at all.** A control-plane call carries its token on {@link CONTROL_PLANE_HEADER},
+* which is not a CORS-safelisted request header, so a browser sends `OPTIONS` first and refuses to send
+* the real request until something answers it. Nothing did. The failure surfaced as a `TypeError` from
+* `fetch` naming the host, so a reachable Worker read as an unreachable one — and the browser-direct
+* path is the whole reason the seam is shaped this way, since the alternative is proxying an adopter's
+* data through a management client's origin.
+*
+* **The allow-list is static config and never a connection row.** A preflight is the one request on
+* this surface that is answered before any credential is read: there is nothing to authenticate it
+* with, because the browser sends it before it will send the token. Consulting D1 would therefore turn
+* it into an oracle over which origins are registered, answerable by anyone. So the list is
+* `[issuer, ...allowedOrigins]` off the parsed config, computed once at composition, and this module
+* reads no database.
+*
+* **An unlisted origin is refused by omission.** It gets the same `204` and the same empty body as an
+* allowed one, with no `Access-Control-Allow-Origin` — the browser blocks the read, and the response
+* says nothing about what the list contains. A `403` here would be more honest as an API and would also
+* be the oracle above, so it is deliberately not one; the caller already sees a clear console error.
+*
+* **No `hono/cors`.** `worker-safety.test.ts` freezes the import allowlist and the middleware is not on
+* it (`docs/STACK.md` notes the ReDoS advisory against it). It also cannot express either of the two
+* rules above — a refusal that is byte-identical to an acceptance, and credentials that are never
+* allowed — so hand-rolling costs about forty lines and buys the behavior the seam actually needs.
+*/
+/** The hostnames a browser reaches a developer's own machine at, and the only ones §dev will allow. */
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+/**
+* Whether this request may use the **local dev** allowance: a loopback origin, in the dev environment.
+*
+* A console an adopter runs against a local Worker sits on `http://localhost:<port>`, on a port the dev
+* port allocator picked. Nobody can write that into `allowedOrigins` and have it stay true across
+* checkouts, so in dev the seam simply allows this machine.
+*
+* **Two guards: `ENVIRONMENT` is `dev`, and the hostname is loopback.** Take the first for what it is
+* — a var the adopter stamps, and `pithy init` writes `dev` into the top-level `wrangler.jsonc` stanza
+* (`cli/src/project/workerScaffold.ts`) that a bare `pithy deploy` publishes. So this is not a claim
+* that the allowance cannot appear on a deployed Worker.
+*
+* It is a claim about what the allowance is *worth*, and that holds wherever it appears. The origins it
+* admits name the caller's **own machine**. No ambient authority crosses, because
+* `Access-Control-Allow-Credentials` is never set on this surface and the token is an explicit header.
+* And every admin route still demands a verified control-plane token. So the most this permits is a
+* local page reading a reply it could have fetched directly, which is not a capability anyone gains.
+*
+* **Do not reach for `<STEM>_ORIGIN` here.** It looks like the precise version of this and it does not
+* work: `pithy dev` publishes those into each child *process*, and the host environment does not cross
+* into workerd — `cli/src/dev/env.ts:157-165`. Only capability *hosts* are forwarded as `--var`
+* (`hostVarArgs`), deliberately (#410), and a UI worker is not one. So a Worker's `env` never carries
+* the console's address, and a version of this that read one allowed exactly the origins no browser
+* calls while reading as though it did more.
+*
+* It is a per-request read rather than part of {@link allowedOriginSet} because in Workers there is no
+* `env` until a request arrives.
+*/
+function devLoopbackAllows(env, origin) {
+	if (env["ENVIRONMENT"] !== "dev") return false;
+	try {
+		return LOOPBACK_HOSTS.has(new URL(origin).hostname);
+	} catch {
+		return false;
+	}
+}
+/** The two response headers a client must be allowed to read off an admin response, as one value. */
+const EXPOSE_HEADERS = `${CONTROL_PLANE_VERSION_HEADER}, ${CONTROL_PLANE_VERSION_CREATED_HEADER}`;
+/**
+* One origin, normalized the way a browser spells it, or `null` when the value is not one.
+*
+* Applied to both ends deliberately. `issuer` is a `z.url()` that predates this module and may legally
+* carry a path or a trailing slash, and an `Access-Control-Allow-Origin` carrying either matches no
+* browser `Origin` — so it is normalized rather than trusted. The incoming header is normalized for the
+* same reason from the other direction: it is not ours, and comparing raw strings would turn a spelling
+* difference into a refusal nobody can diagnose.
+*/
+function originOf(value) {
+	if (!value) return null;
+	try {
+		const origin = new URL(value).origin;
+		return origin === "null" ? null : origin;
+	} catch {
+		return null;
+	}
+}
+/**
+* The effective allow-list: `[issuer, ...allowedOrigins]`, normalized, then deduped.
+*
+* Additive in that order and never replacing, which is the property the whole shape rests on: an
+* adopter who adds their own console cannot silently drop the dashboard that was already working, and
+* a replacing default would have done exactly that the first time someone wrote a single entry.
+* Dedupe happens **after** normalization, so `https://app.pithy.sh` and `https://app.pithy.sh/` are one
+* entry rather than two.
+*/
+function allowedOriginSet(config) {
+	const origins = /* @__PURE__ */ new Set();
+	for (const value of [config.issuer, ...config.allowedOrigins]) {
+		const origin = originOf(value);
+		if (origin !== null) origins.add(origin);
+	}
+	return origins;
+}
+/**
+* Fold every composed capability's `adminRoutes` into one entry per distinct path.
+*
+* **The descriptors are the surface.** They already exist, a management client already navigates by
+* them, and `routeContract.test.ts` already proves they agree with the mounted router — so deriving
+* CORS from the same table means a capability that adds an admin route gets its preflight for free and
+* there is no second list to drift. The alternative considered and rejected was an app-wide
+* `app.use("*", …)`, which would attach dashboard origins to the adopter's own API — a different
+* surface, with different origins, that is not the kit's decision to make.
+*
+* **`content-type` keys on the method, not on whether the route takes a body.** {@link AdminRoute}
+* carries no body flag, and adding one is worse than the proxy it would replace: that type is read
+* across a version boundary by the management client, so a new field must be `.optional()` and an
+* absent optional says less than the method already does.
+*/
+function corsSurface(capabilities) {
+	const methodsByPath = /* @__PURE__ */ new Map();
+	for (const capability of capabilities) for (const route of capability.adminRoutes ?? []) {
+		const methods = methodsByPath.get(route.path) ?? /* @__PURE__ */ new Set();
+		methods.add(route.method);
+		methodsByPath.set(route.path, methods);
+	}
+	return [...methodsByPath.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([path, methods]) => {
+		const carriesBody = [...methods].some((method) => method !== "GET");
+		return {
+			path,
+			allowMethods: [...methods, "OPTIONS"].join(", "),
+			allowHeaders: carriesBody ? `${CONTROL_PLANE_HEADER}, content-type` : CONTROL_PLANE_HEADER
+		};
+	});
+}
+/**
+* The per-path middleware: answer the preflight, and mark the real response readable.
+*
+* Both halves are here rather than in an `app.options(…)` of their own, because a preflight that is
+* allowed and a response that cannot be read is the same failure as no preflight at all — the browser
+* blocks a `GET` whose response carries no `Access-Control-Allow-Origin`, `204` or not.
+*/
+function corsMiddleware(entry, origins, maxAgeSeconds) {
+	return async (c, next) => {
+		c.header("Vary", "Origin", { append: true });
+		const origin = originOf(c.req.raw.headers.get("origin"));
+		const allowed = origin !== null && (origins.has(origin) || devLoopbackAllows(c.env, origin));
+		if (allowed) c.header("Access-Control-Allow-Origin", origin);
+		if (c.req.method === "OPTIONS") {
+			if (allowed) {
+				c.header("Access-Control-Allow-Methods", entry.allowMethods);
+				c.header("Access-Control-Allow-Headers", entry.allowHeaders);
+				c.header("Access-Control-Max-Age", String(maxAgeSeconds));
+			}
+			return c.body(null, 204);
+		}
+		c.header("Access-Control-Expose-Headers", EXPOSE_HEADERS);
+		await next();
+	};
+}
+/**
+* Mount one `app.use(path, …)` per entry.
+*
+* **Called from the capability's `middleware` hook, never its `routes` hook, and that is load-bearing.**
+* `createBackend` runs every capability's `middleware` hook before **any** capability's `routes` hook
+* (`createBackend.ts:262-267`), which is what makes this independent of the order an adopter happens to
+* list their capabilities in.
+*
+* From `routes` it looks like it works and does not. The preflight still answers — an `OPTIONS` has no
+* route handler to lose to, so this `use` is the only thing that matches it — but a capability composed
+* *before* the seam has already registered its terminal handler, and a terminal handler never calls
+* `next()`, so the middleware after it never runs. The real response then carries no
+* `Access-Control-Allow-Origin` and the browser blocks a `200` the caller was entitled to read: a
+* preflight that passes and a read that fails, which is a worse failure than the one this fixes because
+* it looks configured. `cors.test.ts` §"the registration slot" pins it by composing the seam last.
+*
+* Exact paths, never a wildcard: `app.use` on a literal path does not match subpaths, so "nothing
+* outside the control-plane surface gains a CORS header" is structural rather than a check that could
+* be got wrong.
+*/
+function registerControlPlaneCors(app, surface, origins, maxAgeSeconds) {
+	for (const entry of surface) app.use(entry.path, corsMiddleware(entry, origins, maxAgeSeconds));
+}
+//#endregion
+export { allowedOriginSet, corsMiddleware, corsSurface, devLoopbackAllows, originOf, registerControlPlaneCors };

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

@@ -0,0 +1,77 @@
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import type { ControlPlaneContext } from "../context";
+import type { ControlPlaneRequirement } from "../scope/scope";
+import { type ControlPlaneVerifyDeps } from "./verify";
+/**
+ * `requireControlPlane(scope)` — the gate every control-plane route wears, including the ones
+ * capabilities contribute.
+ *
+ * ## Why a verifier on the request, and not a configured factory
+ *
+ * `@pithy-sh/payments` writes `requireControlPlane(PAYMENTS_ENTITLEMENT_GRANT_SCOPE)` at module scope. It cannot
+ * hold the seam's config — that is the adopter's, resolved when they compose `controlplane()` — and it
+ * must not import anything from a sibling package. So the seam contributes one middleware that puts a
+ * {@link ControlPlaneVerifier} on the request, and the gate below consumes it. A capability depends on
+ * a core seam and nothing else, which is principle 4 doing exactly what it exists for.
+ *
+ * ## It fails closed, and that is the point
+ *
+ * With no `controlplane()` composed there is no verifier, and every gate raises
+ * `controlplane/not_connected`. A capability that contributes admin routes into a Worker that never
+ * enabled the seam therefore denies them, rather than leaving them open because the thing meant to
+ * protect them is absent. **A package that imports its authorization from elsewhere must deny when
+ * that elsewhere is missing** — the same reason `requireAuth` is copied per capability rather than
+ * imported from `@pithy-sh/auth`.
+ *
+ * ## The requirement is mandatory
+ *
+ * There is no zero-argument form. An optional scope is a thing you can forget, and forgetting it on an
+ * admin route ships an unscoped one; requiring the argument means the only way to write a route with no
+ * authorization is to name `ANY_VERIFIED_CALLER` out loud, which is as deliberate as naming a scope.
+ */
+/**
+ * Verify one call against this Worker's registrations. Contributed by the seam's middleware, consumed
+ * by {@link requireControlPlane}, and absent when the seam is not composed.
+ */
+export type ControlPlaneVerifier = (request: Request, requirement: ControlPlaneRequirement) => Promise<ControlPlaneContext>;
+/**
+ * Build the verifier the seam's middleware publishes. Split out from the middleware so the wiring is
+ * testable without a Worker, and so `verify.ts` stays free of Hono.
+ */
+export declare function createControlPlaneVerifier(deps: ControlPlaneVerifyDeps): ControlPlaneVerifier;
+/**
+ * What this Worker may say about its own build, as headers — everything the binding handed it, and
+ * nothing else.
+ *
+ * A function rather than two lines in the middleware because this is where the seam's one invariant
+ * lives and one invariant wants one place to be gated: **every value here was handed to this Worker by
+ * the platform, byte for byte.** Nothing is defaulted, nothing is computed at request time, and a field
+ * the binding did not carry produces no header at all. That last clause is the load-bearing one — this
+ * pair is what a management client invalidates a rendered pane on, and an empty header is a value, so
+ * "cannot say" has to arrive as silence rather than as an empty string a client can compare.
+ *
+ * The tag stays off the wire. It is read by the identity reader and answers neither of the two
+ * questions a client asks, and this header crosses to a management client on adopter-authored text.
+ */
+export declare function workerVersionHeaders(env: unknown): Record<string, string>;
+/**
+ * Require a verified control-plane caller carrying `requirement`.
+ *
+ * Goes **before** any validator on the route line. A validator ahead of the gate turns a 401 into a
+ * 400 and tells an unauthenticated caller which requests were well-formed — on this seam that is a
+ * live oracle, letting someone with no credential at all probe the shape of key registration.
+ */
+/**
+ * The brand every {@link requireControlPlane} gate carries, so a mounted router can be read back.
+ *
+ * A middleware is an opaque function to Hono, so "which routes are control-plane routes" is knowable
+ * only if the gate says so about itself. `undeclaredAdminRoutes` needs exactly that: it walks the
+ * router looking for guarded routes nobody declared, and without a mark it would have to guess from
+ * path shape. `Symbol.for` so the check still works across duplicated copies of this module.
+ */
+export declare const CONTROL_PLANE_GUARD: unique symbol;
+/** Whether a mounted handler is a control-plane gate. */
+export declare function isControlPlaneGuard(handler: unknown): boolean;
+export declare function requireControlPlane(requirement: ControlPlaneRequirement): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAIhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,OAAO,EAAE,KAAK,sBAAsB,EAA0B,MAAM,UAAU,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,uBAAuB,KACjC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,oBAAoB,CAgB7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzE;AAED;;;;;;GAMG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,eAAwC,CAAC;AAEzE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,uBAAuB,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAkEzG"}

package/dist/controlPlane/http/guard.js

@@ -0,0 +1,142 @@
+import { PithyError } from "../../error/pithyError.js";
+import { workerVersionMetadata } from "../../worker/identity.js";
+import { ControlPlaneAuditActions, safeEmit } from "../audit/actions.js";
+import { ControlPlaneNotConnectedError } from "../error/errors.js";
+import { CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER } from "../wire.js";
+import { verifyControlPlaneCall } from "./verify.js";
+//#region src/controlPlane/http/guard.ts
+/**
+* Build the verifier the seam's middleware publishes. Split out from the middleware so the wiring is
+* testable without a Worker, and so `verify.ts` stays free of Hono.
+*/
+function createControlPlaneVerifier(deps) {
+	return async (request, requirement) => {
+		const body = new Uint8Array(await request.clone().arrayBuffer());
+		return await verifyControlPlaneCall({
+			token: request.headers.get("pithy-control-plane") ?? void 0,
+			body,
+			requirement
+		}, deps);
+	};
+}
+/**
+* What this Worker may say about its own build, as headers — everything the binding handed it, and
+* nothing else.
+*
+* A function rather than two lines in the middleware because this is where the seam's one invariant
+* lives and one invariant wants one place to be gated: **every value here was handed to this Worker by
+* the platform, byte for byte.** Nothing is defaulted, nothing is computed at request time, and a field
+* the binding did not carry produces no header at all. That last clause is the load-bearing one — this
+* pair is what a management client invalidates a rendered pane on, and an empty header is a value, so
+* "cannot say" has to arrive as silence rather than as an empty string a client can compare.
+*
+* The tag stays off the wire. It is read by the identity reader and answers neither of the two
+* questions a client asks, and this header crosses to a management client on adopter-authored text.
+*/
+function workerVersionHeaders(env) {
+	const meta = workerVersionMetadata(env);
+	const headers = {};
+	if (meta.id !== null) headers[CONTROL_PLANE_VERSION_HEADER] = meta.id;
+	if (meta.createdAt !== null) headers[CONTROL_PLANE_VERSION_CREATED_HEADER] = meta.createdAt;
+	return headers;
+}
+/**
+* Require a verified control-plane caller carrying `requirement`.
+*
+* Goes **before** any validator on the route line. A validator ahead of the gate turns a 401 into a
+* 400 and tells an unauthenticated caller which requests were well-formed — on this seam that is a
+* live oracle, letting someone with no credential at all probe the shape of key registration.
+*/
+/**
+* The brand every {@link requireControlPlane} gate carries, so a mounted router can be read back.
+*
+* A middleware is an opaque function to Hono, so "which routes are control-plane routes" is knowable
+* only if the gate says so about itself. `undeclaredAdminRoutes` needs exactly that: it walks the
+* router looking for guarded routes nobody declared, and without a mark it would have to guess from
+* path shape. `Symbol.for` so the check still works across duplicated copies of this module.
+*/
+const CONTROL_PLANE_GUARD = Symbol.for("pithy.controlPlaneGuard");
+/** Whether a mounted handler is a control-plane gate. */
+function isControlPlaneGuard(handler) {
+	return typeof handler === "function" && handler[CONTROL_PLANE_GUARD] === true;
+}
+function requireControlPlane(requirement) {
+	const guard = async (c, next) => {
+		for (const [name, value] of Object.entries(workerVersionHeaders(c.env))) c.header(name, value);
+		const verify = c.var.controlPlaneVerifier;
+		if (!verify) {
+			const denial = new ControlPlaneNotConnectedError({
+				message: "This deployment does not accept management-client calls.",
+				action: "Add `controlplane()` to this Worker's pithy.config.ts, then run pithy dashboard connect.",
+				detail: "no control-plane verifier on the request — the controlplane capability is not composed"
+			});
+			await auditDenial(c, requirement, denial);
+			throw denial;
+		}
+		let context;
+		try {
+			context = await verify(c.req.raw, requirement);
+		} catch (cause) {
+			await auditDenial(c, requirement, cause);
+			throw cause;
+		}
+		c.set("controlPlane", context);
+		await safeEmit(c.var.emit, {
+			action: ControlPlaneAuditActions.callAllowed,
+			outcome: "success",
+			actorType: "control-plane",
+			actorId: context.subject,
+			resourceType: "controlplane_connection",
+			resourceId: context.connectionId,
+			requestId: c.req.header("cf-ray"),
+			ip: c.req.header("cf-connecting-ip"),
+			userAgent: c.req.header("user-agent"),
+			metadata: {
+				connectionId: context.connectionId,
+				connectionEnvironment: context.environment,
+				scope: context.scope,
+				keyId: context.keyId,
+				method: c.req.method,
+				path: c.req.path
+			}
+		}, c.var.log);
+		await next();
+	};
+	guard[CONTROL_PLANE_GUARD] = true;
+	return guard;
+}
+/**
+* Record a refused call.
+*
+* **Denials are audited, not only successes.** `denied` is a first-class outcome precisely for this, and
+* this is the surface where an unaudited blocked attempt is least acceptable — a run of them is what a
+* credential being probed looks like, and it is invisible if only the successes are written down.
+*
+* The reason lands in `metadata.reason` from the error's `code`, never from its `detail`: `detail` names
+* the exact verification step, and the audit trail is queryable and long-lived. The step belongs in the
+* log, which is bounded and already carries the whole payload.
+*
+* Nothing here can turn a correct denial into a 500 — `safeEmit` swallows, and the caller rethrows the
+* original error regardless.
+*/
+async function auditDenial(c, requirement, cause) {
+	const code = cause instanceof PithyError ? cause.payload.code : "core/internal";
+	await safeEmit(c.var.emit, {
+		action: ControlPlaneAuditActions.callDenied,
+		outcome: "denied",
+		severity: "warning",
+		actorType: "control-plane",
+		actorId: null,
+		requestId: c.req.header("cf-ray"),
+		ip: c.req.header("cf-connecting-ip"),
+		userAgent: c.req.header("user-agent"),
+		metadata: {
+			reason: code,
+			required: String(requirement),
+			method: c.req.method,
+			path: c.req.path
+		}
+	}, c.var.log);
+}
+//#endregion
+export { CONTROL_PLANE_GUARD, createControlPlaneVerifier, isControlPlaneGuard, requireControlPlane, workerVersionHeaders };

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

@@ -0,0 +1,179 @@
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import type { ControlPlaneConfig } from "../config/config";
+import { type ControlPlaneDatabase } from "../data/tables";
+import type { CapabilityDeclaration } from "../discovery/adminRoute";
+import { type CapabilityHealthSource } from "../discovery/health";
+import type { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas";
+/** 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;
+}
+/**
+ * `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 declare function pingHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>) => Response & import("hono").TypedResponse<{
+    status: "ok";
+    connectionId: string;
+    environment: string;
+    keyId: string;
+    now: string;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">;
+/**
+ * `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 declare function manifestHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>) => Promise<Response & import("hono").TypedResponse<{
+    environment: string;
+    connectionId: string;
+    version: string | null;
+    capabilities: {
+        health: import("../..").HealthSummary | null;
+        healthUnavailable: boolean;
+        name: string;
+        version: string | null;
+        adminRoutes: {
+            method: "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+            path: string;
+            scope: string | null;
+            summary: string;
+        }[];
+        healthKeys: {
+            key: string;
+            kind: "count" | "state";
+            states: string[] | null;
+            scope: string;
+            cost: "indexed" | "memory";
+            summary: string;
+            nominal: string[] | {
+                atMost?: number | undefined;
+                atLeast?: number | undefined;
+            } | null;
+        }[];
+        configKeys: {
+            key: string;
+            choices: string[] | null;
+            summary: string;
+        }[];
+        config: {
+            [x: string]: string | number | boolean;
+        };
+    }[];
+    grantedScopes: string[];
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+/** `GET /control-plane/keys` — the registration state, so a client can surface a stale key. */
+export declare function listKeysHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>) => Promise<Response & import("hono").TypedResponse<{
+    connectionId: string;
+    environment: string;
+    keys: {
+        keyId: string;
+        publicKey: {
+            kty: "OKP";
+            crv: "Ed25519";
+            x: string;
+        };
+        validFrom: string;
+        validUntil: string | null;
+        revokedAt: string | null;
+    }[];
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+/**
+ * `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 declare function registerKeyHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>, body: RegisterKeyRequest) => Promise<Response & import("hono").TypedResponse<{
+    keyId: string;
+    validFrom: string;
+    keys: {
+        keyId: string;
+        publicKey: {
+            kty: "OKP";
+            crv: "Ed25519";
+            x: string;
+        };
+        validFrom: string;
+        validUntil: string | null;
+        revokedAt: string | null;
+    }[];
+}, 201, "json">>;
+/**
+ * `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 declare function expireKeyHandler(deps: ControlPlaneHandlerDeps): (c: Context<PithyHonoEnv>, params: ExpireKeyParams, body: ExpireKeyRequest) => Promise<Response & import("hono").TypedResponse<{
+    keyId: string;
+    validUntil: string;
+    keys: {
+        keyId: string;
+        publicKey: {
+            kty: "OKP";
+            crv: "Ed25519";
+            x: string;
+        };
+        validFrom: string;
+        validUntil: string | null;
+        revokedAt: string | null;
+    }[];
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+//# sourceMappingURL=handlers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/handlers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,OAAO,EAAmC,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,KAAK,EAAE,qBAAqB,EAA4B,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EAAE,KAAK,sBAAsB,EAAwB,MAAM,qBAAqB,CAAC;AAUxF,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAuBvF,yGAAyG;AACzG,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,MAAM,EAAE,kBAAkB,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,oBAAoB,CAAC;IAC7D;;;;;;;;OAQG;IACH,oBAAoB,EAAE,MAAM,SAAS,qBAAqB,EAAE,CAAC;IAC7D;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAClE,8DAA8D;IAC9D,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAgED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,uBAAuB,OAC5C,OAAO,CAAC,YAAY,CAAC;;;;;;kEAUjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,OAC1C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAyBvC;AAED,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,OAC1C,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;mEASvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,uBAAuB,OAC7C,OAAO,CAAC,YAAY,CAAC,QAAQ,kBAAkB;;;;;;;;;;;;;;iBAoDjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,OAC3C,OAAO,CAAC,YAAY,CAAC,UAAU,eAAe,QAAQ,gBAAgB;;;;;;;;;;;;;;mEA8CxF"}