@pithy-sh/core 0.1.2 → 0.1.4

package/dist/controlPlane/data/keyLifecycle.js

@@ -0,0 +1,126 @@
+import { ControlPlaneKeyConflictError, ControlPlaneKeyNotFoundError } from "../error/errors.js";
+//#region src/controlPlane/data/keyLifecycle.ts
+/**
+* The registered-key lifecycle: pure array logic over a connection's `keys` column.
+*
+* **Registering a key and expiring one are two operations, and folding them into a single `rotate()`
+* is the one design mistake this module exists to prevent.** One call would make append-and-expire
+* atomic, and atomic is precisely wrong here. The whole safety property is that the old key outlives
+* the new one's first successful call: a mis-copied JWK, a private key the management client cannot
+* actually sign with, or a Worker that never answers leaves the adopter holding a credential that
+* still works. Fuse the two writes together and that same mistake locks them out of the seam with
+* nothing left to authenticate the fix with. Kept apart, a broken rotation costs a stale key.
+*
+* So the safe ordering is enforced here rather than documented: {@link appendKey} may not touch an
+* existing key's window, and {@link expireKey} refuses unless another key is already live.
+*
+* Nothing in this module reads a clock, a binding, or D1. `now` is injected on every call, which is
+* what lets a test assert what a connection looks like a year into a failed rotation.
+*/
+/** Every key that may verify a call at `now`: not revoked, started, and not yet ended. */
+function activeKeys(keys, now) {
+	return keys.filter((key) => !isRetired(key, now) && key.validFrom.getTime() <= now.getTime());
+}
+/**
+* The key that may verify this call, or null. Matching on `kid` alone would be the vulnerability —
+* the window and the revocation are checked here so no caller can forget them.
+*/
+function findVerifyingKey(keys, keyId, now) {
+	return activeKeys(keys, now).find((key) => key.keyId === keyId) ?? null;
+}
+/**
+* Register a key. Appends, and appends only — no existing key's `validUntil` moves, so a connection
+* mid-rotation always has the key it arrived with.
+*
+* A key that is already retired at `now` is refused rather than stored: it could never be proven by a
+* ping, so registering it would only offer a second step that can never safely be taken.
+*/
+function appendKey(keys, key, now) {
+	if (keys.some((existing) => existing.keyId === key.keyId)) throw new ControlPlaneKeyConflictError({
+		message: "That key id is already registered on this connection.",
+		action: "Register the replacement under a new key id.",
+		detail: `duplicate keyId ${key.keyId}`
+	});
+	if (isRetired(key, now)) throw new ControlPlaneKeyConflictError({
+		message: "That key has already expired or been revoked.",
+		action: "Register a key with an open-ended validity window.",
+		detail: `keyId ${key.keyId} is retired at registration`
+	});
+	return [...keys, key];
+}
+/**
+* Close a key's window at `now`, once a replacement has proven itself.
+*
+* `provenKeyId` is the key that verified the request asking for this expiry — proof by use, and the
+* reason the seam's `ping` scope is held implicitly by every connection. Two refusals guard the
+* ordering: a prover that is not itself live has proven nothing, and an expiry that would leave no
+* live key is the lockout, whatever the caller believes about their replacement.
+*
+* Re-expiring a key already closed is a no-op on its end date. The window a call was rejected under
+* must not move retroactively.
+*/
+function expireKey(keys, keyId, options) {
+	const { provenKeyId, now } = options;
+	if (!keys.some((key) => key.keyId === keyId)) throw new ControlPlaneKeyNotFoundError({ detail: `keyId ${keyId} is not registered on this connection` });
+	if (findVerifyingKey(keys, provenKeyId, now) === null) throw new ControlPlaneKeyConflictError({
+		message: "The replacement key has not been proven on this connection.",
+		action: "Call the ping route with the replacement key, then expire this one.",
+		detail: `provenKeyId ${provenKeyId} is not live at ${now.toISOString()}`
+	});
+	const expired = keys.map((key) => key.keyId === keyId && key.validUntil === null ? {
+		...key,
+		validUntil: now
+	} : key);
+	if (activeKeys(expired, now).length === 0) throw new ControlPlaneKeyConflictError({
+		message: "Expiring that key would leave this connection with no live key.",
+		action: "Register a replacement key and prove it before expiring this one.",
+		detail: `expiring keyId ${keyId} would empty the connection's live set`
+	});
+	return expired;
+}
+/**
+* Drop keys retired longer ago than `retentionMs`, then cap the array at `maxKeys`.
+*
+* The column is versioned, not a log — a superseded key is kept only long enough for the audit trail
+* and a `GET /control-plane/keys` to explain a rotation. Two keys are never dropped: a live one, and
+* one registered ahead of its `validFrom`, which is unretired rather than dead. So the cap is a
+* target, not a guarantee; a connection with more live keys than `maxKeys` keeps all of them.
+*/
+function pruneKeys(keys, options) {
+	const { now, retentionMs, maxKeys } = options;
+	const live = new Set(activeKeys(keys, now).map((key) => key.keyId));
+	const kept = keys.filter((key) => {
+		if (live.has(key.keyId)) return true;
+		const retired = retiredAt(key);
+		if (retired === null) return true;
+		return now.getTime() - retired.getTime() <= retentionMs;
+	});
+	if (kept.length <= maxKeys) return kept;
+	const dropped = new Set(kept.flatMap((key) => {
+		const retired = live.has(key.keyId) ? null : retiredAt(key);
+		return retired === null ? [] : [{
+			keyId: key.keyId,
+			retiredAt: retired.getTime()
+		}];
+	}).sort((a, b) => a.retiredAt - b.retiredAt).slice(0, kept.length - maxKeys).map((entry) => entry.keyId));
+	return kept.filter((key) => !dropped.has(key.keyId));
+}
+/**
+* When a key stopped being usable, or null while it is still in play. Revocation and expiry can both
+* be set; the earlier one is when the key actually went cold.
+*/
+function retiredAt(key) {
+	const ends = [key.revokedAt, key.validUntil].filter((date) => date !== null);
+	if (ends.length === 0) return null;
+	return ends.reduce((earliest, date) => date.getTime() < earliest.getTime() ? date : earliest);
+}
+/**
+* Is this key cold at `now`? Revocation counts whatever date it carries — it is the adopter's
+* unilateral control and does not wait for a window to close. A `validUntil` still ahead is not
+* retirement, and neither is a `validFrom` still ahead: that key is pending, not spent.
+*/
+function isRetired(key, now) {
+	return key.revokedAt !== null || key.validUntil !== null && key.validUntil.getTime() <= now.getTime();
+}
+//#endregion
+export { activeKeys, appendKey, expireKey, findVerifyingKey, pruneKeys };

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

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/**
+ * One spent control-plane token, as a row.
+ *
+ * The row's **existence is the whole signal** — a claim is an insert that either wins the primary key or
+ * does not. The columns beside `jti` exist for two other jobs: `expiresAt` is what lets the table be
+ * pruned rather than grow forever, and `connectionId` is for the incident, not the decision. A replay is
+ * refused whatever connection presents it, because the `jti` alone is the key: scoping the uniqueness per
+ * connection would let a token captured from one connection be spent again against another, which is
+ * exactly the property being bought.
+ */
+export declare const ControlPlaneReplay: z.ZodObject<{
+    jti: z.ZodString;
+    connectionId: z.ZodString;
+    expiresAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type ControlPlaneReplay = z.output<typeof ControlPlaneReplay>;
+//# sourceMappingURL=replay.d.ts.map

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

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

package/dist/controlPlane/data/replay.js

@@ -0,0 +1,20 @@
+import { SQLiteDate } from "../../data/codecs.js";
+import { z } from "zod";
+//#region src/controlPlane/data/replay.ts
+/**
+* One spent control-plane token, as a row.
+*
+* The row's **existence is the whole signal** — a claim is an insert that either wins the primary key or
+* does not. The columns beside `jti` exist for two other jobs: `expiresAt` is what lets the table be
+* pruned rather than grow forever, and `connectionId` is for the incident, not the decision. A replay is
+* refused whatever connection presents it, because the `jti` alone is the key: scoping the uniqueness per
+* connection would let a token captured from one connection be spent again against another, which is
+* exactly the property being bought.
+*/
+const ControlPlaneReplay = z.object({
+	jti: z.string().min(1).max(128).describe("The token's unique id, minted by the management client, and the primary key that decides the race. Bounded because it arrives from a caller and becomes a stored key — an unbounded id would be an unbounded write."),
+	connectionId: z.string().min(1).describe("The connection whose token claimed this jti. Recorded for forensics only — the claim is decided by the jti alone, so that a token cannot be replayed against a second connection."),
+	expiresAt: SQLiteDate.describe("When this record may be pruned — the instant past which no token carrying this jti could still be accepted. Rows are deleted after it, never before: forgetting a jti while its token is still live is precisely the replay this table exists to stop.")
+}).describe("A spent control-plane token id. Its presence is the refusal; the other columns are for pruning and for the incident.");
+//#endregion
+export { ControlPlaneReplay };

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

@@ -0,0 +1,34 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { type DatabaseSchema } from "../../data/db";
+import { ControlPlaneConnection } from "./connection";
+import { ControlPlaneReplay } from "./replay";
+/**
+ * The connections table. `CamelCasePlugin` snake-cases it to `pithy_controlplane_connections` — the
+ * namespace is the single word `controlplane`, matching the migration namespace and the
+ * `controlplane/*` error codes, because the prefix pattern admits no hyphen.
+ */
+export declare const CONTROL_PLANE_CONNECTIONS_TABLE = "pithyControlplaneConnections";
+/**
+ * The replay table — spent token ids. Snake-cases to `pithy_controlplane_replays`.
+ *
+ * In the same database as the connections rather than beside the sessions in KV, because that is what
+ * makes the claim a primary-key insert and therefore strongly consistent. See `../replay/guard.ts`.
+ */
+export declare const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
+/**
+ * The control-plane tables map. Both are always present: a Worker that composes the seam and has never
+ * been connected still needs somewhere for the answer "nobody is connected" to come from, and the
+ * replay table must exist before the first management call rather than on first use.
+ */
+export declare function controlPlaneTables(): Record<string, z.ZodObject>;
+/** The typed Kysely database over the control-plane tables. */
+export type ControlPlaneTables = {
+    [CONTROL_PLANE_CONNECTIONS_TABLE]: typeof ControlPlaneConnection;
+    [CONTROL_PLANE_REPLAYS_TABLE]: typeof ControlPlaneReplay;
+};
+export type ControlPlaneDatabase = Kysely<DatabaseSchema<ControlPlaneTables>>;
+/** Build the control-plane database from the `DB` binding (CamelCasePlugin installed). */
+export declare function controlPlaneDatabase(d1: D1Database): ControlPlaneDatabase;
+//# sourceMappingURL=tables.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,iCAAiC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAKhE;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,+BAA+B,CAAC,EAAE,OAAO,sBAAsB,CAAC;IACjE,CAAC,2BAA2B,CAAC,EAAE,OAAO,kBAAkB,CAAC;CAC1D,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAE9E,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,oBAAoB,CAKzE"}

package/dist/controlPlane/data/tables.js

@@ -0,0 +1,37 @@
+import { ControlPlaneConnection } from "./connection.js";
+import { createDatabase } from "../../data/db.js";
+import { ControlPlaneReplay } from "./replay.js";
+//#region src/controlPlane/data/tables.ts
+/**
+* The connections table. `CamelCasePlugin` snake-cases it to `pithy_controlplane_connections` — the
+* namespace is the single word `controlplane`, matching the migration namespace and the
+* `controlplane/*` error codes, because the prefix pattern admits no hyphen.
+*/
+const CONTROL_PLANE_CONNECTIONS_TABLE = "pithyControlplaneConnections";
+/**
+* The replay table — spent token ids. Snake-cases to `pithy_controlplane_replays`.
+*
+* In the same database as the connections rather than beside the sessions in KV, because that is what
+* makes the claim a primary-key insert and therefore strongly consistent. See `../replay/guard.ts`.
+*/
+const CONTROL_PLANE_REPLAYS_TABLE = "pithyControlplaneReplays";
+/**
+* The control-plane tables map. Both are always present: a Worker that composes the seam and has never
+* been connected still needs somewhere for the answer "nobody is connected" to come from, and the
+* replay table must exist before the first management call rather than on first use.
+*/
+function controlPlaneTables() {
+	return {
+		[CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
+		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay
+	};
+}
+/** Build the control-plane database from the `DB` binding (CamelCasePlugin installed). */
+function controlPlaneDatabase(d1) {
+	return createDatabase(d1, {
+		[CONTROL_PLANE_CONNECTIONS_TABLE]: ControlPlaneConnection,
+		[CONTROL_PLANE_REPLAYS_TABLE]: ControlPlaneReplay
+	});
+}
+//#endregion
+export { CONTROL_PLANE_CONNECTIONS_TABLE, CONTROL_PLANE_REPLAYS_TABLE, controlPlaneDatabase, controlPlaneTables };

package/dist/controlPlane/discovery/adminRoute.d.ts

@@ -0,0 +1,313 @@
+import { z } from "zod";
+/**
+ * What a capability tells a management client about its own admin surface.
+ *
+ * **This exists because knowing a capability is installed is not enough to call it.** A management
+ * client that learns only names still has to hold a route table for every capability, guess that
+ * payments is mounted at `/payments`, and know out-of-band which scope each operation needs. Every one
+ * of those is a thing that can be wrong, and `basePath` is configurable — an adopter who mounts
+ * payments at `/billing` would silently 404 a client that hardcoded the default.
+ *
+ * So the capability declares the routes it actually registered, with the paths it actually used, and
+ * `GET /control-plane/manifest` reports them. That is what makes discovery-over-configuration real
+ * rather than aspirational: a client composes its navigation *and* its calls from what the Worker says
+ * about itself, and an adopter who moves a mount point or upgrades a capability changes what the client
+ * does without either side coordinating.
+ *
+ * **The declaration is checked against the router**, not trusted — see `missingAdminRoutes`. A manifest
+ * that drifts from the routes is worse than no manifest, because a client would believe it.
+ */
+/** The HTTP methods an admin route may use. */
+export declare const AdminRouteMethod: z.ZodEnum<{
+    DELETE: "DELETE";
+    GET: "GET";
+    PATCH: "PATCH";
+    POST: "POST";
+    PUT: "PUT";
+}>;
+export type AdminRouteMethod = z.infer<typeof AdminRouteMethod>;
+/** One admin route a capability contributes behind the `control-plane` strategy. */
+export declare const AdminRoute: z.ZodObject<{
+    method: z.ZodEnum<{
+        DELETE: "DELETE";
+        GET: "GET";
+        PATCH: "PATCH";
+        POST: "POST";
+        PUT: "PUT";
+    }>;
+    path: z.ZodString;
+    scope: z.ZodNullable<z.ZodString>;
+    summary: z.ZodString;
+}, z.core.$strip>;
+export type AdminRoute = z.infer<typeof AdminRoute>;
+/**
+ * One composed capability's declaration — everything about it that is the same for every caller.
+ *
+ * Split from {@link CapabilityDescriptor} because the health *values* are the one part of a manifest
+ * entry that depends on who is asking, and the seam holds this half from assembly (`compose`) while the
+ * other half is resolved per request.
+ */
+export declare const CapabilityDeclaration: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+    adminRoutes: z.ZodArray<z.ZodObject<{
+        method: z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>;
+        path: z.ZodString;
+        scope: z.ZodNullable<z.ZodString>;
+        summary: z.ZodString;
+    }, z.core.$strip>>;
+    healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        kind: z.ZodEnum<{
+            count: "count";
+            state: "state";
+        }>;
+        states: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        scope: z.ZodString;
+        cost: z.ZodEnum<{
+            indexed: "indexed";
+            memory: "memory";
+        }>;
+        summary: z.ZodString;
+        nominal: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+            atMost: z.ZodOptional<z.ZodNumber>;
+            atLeast: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodArray<z.ZodString>]>>>;
+    }, z.core.$strip>>>;
+    configKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        choices: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        summary: z.ZodString;
+    }, z.core.$strip>>>;
+    config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, z.core.$strip>;
+export type CapabilityDeclaration = z.infer<typeof CapabilityDeclaration>;
+export declare const CapabilityDescriptor: z.ZodCodec<z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+    adminRoutes: z.ZodArray<z.ZodObject<{
+        method: z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>;
+        path: z.ZodString;
+        scope: z.ZodNullable<z.ZodString>;
+        summary: z.ZodString;
+    }, z.core.$strip>>;
+    healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        kind: z.ZodEnum<{
+            count: "count";
+            state: "state";
+        }>;
+        states: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        scope: z.ZodString;
+        cost: z.ZodEnum<{
+            indexed: "indexed";
+            memory: "memory";
+        }>;
+        summary: z.ZodString;
+        nominal: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+            atMost: z.ZodOptional<z.ZodNumber>;
+            atLeast: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodArray<z.ZodString>]>>>;
+    }, z.core.$strip>>>;
+    configKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        choices: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        summary: z.ZodString;
+    }, z.core.$strip>>>;
+    config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    health: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
+    healthUnavailable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+    adminRoutes: z.ZodArray<z.ZodObject<{
+        method: z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>;
+        path: z.ZodString;
+        scope: z.ZodNullable<z.ZodString>;
+        summary: z.ZodString;
+    }, z.core.$strip>>;
+    healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        kind: z.ZodEnum<{
+            count: "count";
+            state: "state";
+        }>;
+        states: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        scope: z.ZodString;
+        cost: z.ZodEnum<{
+            indexed: "indexed";
+            memory: "memory";
+        }>;
+        summary: z.ZodString;
+        nominal: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+            atMost: z.ZodOptional<z.ZodNumber>;
+            atLeast: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodArray<z.ZodString>]>>>;
+    }, z.core.$strip>>>;
+    configKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        choices: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        summary: z.ZodString;
+    }, z.core.$strip>>>;
+    config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    health: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"undeclared">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"withheld">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"reported">;
+        values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unavailable">;
+    }, z.core.$strip>], "state">;
+}, z.core.$strip>>;
+export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptor>;
+/**
+ * The manifest a management client reads to build itself.
+ *
+ * **There is deliberately no manifest schema version, and that is a different thing from the two build
+ * identities below.** A client dispatches on the routes described here — what this Worker declares right
+ * now — so a capability that changed its paths or its scopes reports the change directly, and a schema
+ * version would be a second source of truth to keep in sync with the first. That reasoning is unchanged.
+ *
+ * What the manifest does carry is **identity**, not schema, and it carries two of them because they
+ * answer questions neither can answer alone. `version` is Cloudflare's opaque per-deploy id: it says
+ * *exactly which build* is running, which is what forensics needs, what reproduces a report, and what
+ * pins the code an audited action ran against. It carries no version semantics, so it says nothing about
+ * features. `capabilities[].version` is the npm version of each composed package: it says *which
+ * features*, which is what answers "should this customer upgrade", "which customers are exposed to what
+ * we just fixed", and "does this project predate the capability a pane needs". Reporting only one leaves
+ * half the questions unanswerable, and they are the halves people actually ask.
+ *
+ * **And each entry carries a third thing: the configured facts that capability states** (#422). Knowing
+ * where a route is and which scope it needs is not always enough to call it — `POST
+ * {base}/entitlements/grant` names a holder, and whether this project's holders are people or
+ * organizations is a decision the adopter made in config. A client that cannot read the decision guesses
+ * it, and a guess writes a row nothing reads. See `discovery/configuration.ts` for why a fact is not a
+ * health number, despite the two fields sitting side by side.
+ */
+export declare const ControlPlaneManifest: z.ZodObject<{
+    environment: z.ZodString;
+    connectionId: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+    capabilities: z.ZodArray<z.ZodCodec<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+        adminRoutes: z.ZodArray<z.ZodObject<{
+            method: z.ZodEnum<{
+                DELETE: "DELETE";
+                GET: "GET";
+                PATCH: "PATCH";
+                POST: "POST";
+                PUT: "PUT";
+            }>;
+            path: z.ZodString;
+            scope: z.ZodNullable<z.ZodString>;
+            summary: z.ZodString;
+        }, z.core.$strip>>;
+        healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodEnum<{
+                count: "count";
+                state: "state";
+            }>;
+            states: z.ZodNullable<z.ZodArray<z.ZodString>>;
+            scope: z.ZodString;
+            cost: z.ZodEnum<{
+                indexed: "indexed";
+                memory: "memory";
+            }>;
+            summary: z.ZodString;
+            nominal: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+                atMost: z.ZodOptional<z.ZodNumber>;
+                atLeast: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodArray<z.ZodString>]>>>;
+        }, z.core.$strip>>>;
+        configKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            choices: z.ZodNullable<z.ZodArray<z.ZodString>>;
+            summary: z.ZodString;
+        }, z.core.$strip>>>;
+        config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        health: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>>;
+        healthUnavailable: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+        adminRoutes: z.ZodArray<z.ZodObject<{
+            method: z.ZodEnum<{
+                DELETE: "DELETE";
+                GET: "GET";
+                PATCH: "PATCH";
+                POST: "POST";
+                PUT: "PUT";
+            }>;
+            path: z.ZodString;
+            scope: z.ZodNullable<z.ZodString>;
+            summary: z.ZodString;
+        }, z.core.$strip>>;
+        healthKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            kind: z.ZodEnum<{
+                count: "count";
+                state: "state";
+            }>;
+            states: z.ZodNullable<z.ZodArray<z.ZodString>>;
+            scope: z.ZodString;
+            cost: z.ZodEnum<{
+                indexed: "indexed";
+                memory: "memory";
+            }>;
+            summary: z.ZodString;
+            nominal: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+                atMost: z.ZodOptional<z.ZodNumber>;
+                atLeast: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodArray<z.ZodString>]>>>;
+        }, z.core.$strip>>>;
+        configKeys: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            choices: z.ZodNullable<z.ZodArray<z.ZodString>>;
+            summary: z.ZodString;
+        }, z.core.$strip>>>;
+        config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        health: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"undeclared">;
+        }, z.core.$strip>, z.ZodObject<{
+            state: z.ZodLiteral<"withheld">;
+        }, z.core.$strip>, z.ZodObject<{
+            state: z.ZodLiteral<"reported">;
+            values: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            state: z.ZodLiteral<"unavailable">;
+        }, z.core.$strip>], "state">;
+    }, z.core.$strip>>>;
+    grantedScopes: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ControlPlaneManifest = z.infer<typeof ControlPlaneManifest>;
+/**
+ * The manifest as the Worker sends it, before a client decodes it.
+ *
+ * The handler builds this and is `satisfies`-checked against it, which keeps the response a compile-time
+ * contract rather than a validation pass over values this Worker just built. A client parses with
+ * {@link ControlPlaneManifest} and gets the four-state health value out the far side.
+ */
+export type ControlPlaneManifestWire = z.input<typeof ControlPlaneManifest>;
+//# sourceMappingURL=adminRoute.d.ts.map

package/dist/controlPlane/discovery/adminRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adminRoute.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/discovery/adminRoute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;;;;;GAiBG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB;;;;;;EAE8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,oFAAoF;AACpF,eAAO,MAAM,UAAU;;;;;;;;;;;iBAmBpB,CAAC;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2C/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAiD1E,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiC9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuBkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}