@pithy-sh/core 0.1.1 → 0.1.3

package/dist/controlPlane/discovery/healthSummary.js

@@ -0,0 +1,278 @@
+import { ControlPlaneScope } from "../scope/scope.js";
+import { z } from "zod";
+//#region src/controlPlane/discovery/healthSummary.ts
+/**
+* The health vocabulary a manifest carries and a management client renders (#317, #350).
+*
+* **The count is not the expensive part. The round trip is.** A management client that wants to say
+* "3 secrets need rotating" beside a rail already read the manifest; making it call again — once per
+* capability it wants a number from, against a customer's production Worker, on every screen load —
+* spends a credential per number nobody has asked for yet.
+*
+* The manifest is the right place because it already carries `version` per capability, and a version is
+* a fact about a capability's *state* rather than about its routes. Nobody discovers anything from it;
+* it is there because a management client needs it and a second call would be wasteful. This is the
+* same argument, already accepted once.
+*
+* ## What keeps it from becoming a data API
+*
+* Three rules, and every one of them is in the type rather than in a comment:
+*
+* 1. **Scalars only.** {@link HealthSummaryValue} is `number | string` and nothing else, so a
+*    projection, a row, or a list does not compile — {@link HEALTH_SUMMARY_IS_SCALAR_ONLY} fails the
+*    build the moment somebody widens it.
+* 2. **A closed vocabulary per capability**, declared alongside its routes. A produced key nobody
+*    declared is refused; the manifest never carries a number a client cannot name.
+* 3. **Nothing that costs a query to produce.** {@link HealthValueCost} has `memory` and `indexed` and
+*    no third member, so a value that would need a table scan cannot be declared at all. A count that
+*    scans on every manifest read has moved the cost rather than removed it, and the manifest is the
+*    most frequently fetched thing this seam serves.
+*
+* ## A withheld number and a zero are different facts
+*
+* A count is less sensitive than the thing it counts, but "3 secrets need rotating" is still a fact
+* about somebody's security posture. So a key inherits a scope the capability *already* gates a read
+* with, and a caller without that scope gets no value at all rather than a zero.
+*
+* ## And a broken store is a fourth fact (#350)
+*
+* #317 got three states right and left the fourth to a reviewer, deliberately: a producer that throws
+* is neither a withheld number nor a zero, and returning null for it would have made a sick store
+* indistinguishable from one this caller may not look at. The reasoning was right. The behavior was
+* that the throw propagated, the whole manifest read failed, and one sick capability blanked Overview
+* for every capability beside it — with nothing on screen saying which one.
+*
+* So there are four, and they live on {@link CapabilityHealthReport}: `undeclared`, `withheld`,
+* `reported`, `unavailable`. The state rides on the value rather than beside it, so a consumer reaches
+* a number only by narrowing, and one that forgets the failure does not render a zero — it does not
+* compile.
+*
+* **Staleness.** These numbers are as old as the manifest a client cached. They are right for a rail
+* and must never be presented as live.
+*
+* ## Why this is not in `health.ts` (#430)
+*
+* It was, and that put the whole Workers data layer one type-only edge from a browser. `adminRoute.ts`
+* imports `healthReport` and `HealthSummaryKey` to describe a manifest entry; every capability's
+* control-plane scope declaration imports `AdminRoute` from `adminRoute.ts`; and `health.ts` imports
+* `Capability` and `PithyHonoEnv`, which reach `data/db.ts` and `kv/kv.ts`. Eight modules a browser is
+* meant to import were compiling `@cloudflare/workers-types`, `hono`, `kysely` and `kysely-d1` — 46 kit
+* files to declare five strings — and `coverage.test.ts`'s type-only rule was satisfied throughout,
+* because **the compiler follows a type-only edge exactly as it follows a value one**.
+*
+* So the seam is next door and this is the wire. This module's whole import list is `zod` and a scope,
+* and the split is along a line nothing crosses: not one symbol here needs a `Context`, a `Capability`
+* or an `InternalError`. `tooling/browser-scopes` compiles each scope declaration as a browser program
+* and fails on anything but `zod`, so the line is held by a gate rather than by this paragraph.
+*/
+/** A health key's name: one camelCase token, so it reads as a field and never as a path or an id. */
+const HEALTH_KEY_PATTERN = /^[a-z][A-Za-z0-9]*$/;
+/** What kind of scalar a key reports. */
+const HealthValueKind = z.enum(["count", "state"]).describe("What kind of scalar this key reports: a `count` (a whole non-negative number) or a `state` (one member of a closed list). There is no third kind, because a third kind is how a summary becomes a projection.");
+/**
+* What producing one value costs on a manifest read.
+*
+* **There is deliberately no member for a scan.** That is the whole constraint expressed as a
+* vocabulary: a capability whose number would need one cannot state its cost, so it cannot declare the
+* key, so the manifest stays cheap by construction rather than by everybody remembering.
+*/
+const HealthValueCost = z.enum(["memory", "indexed"]).describe("What this value costs to produce on a manifest read: `memory` for something already in the Worker's hands, `indexed` for a lookup an index answers and whose bound is a declaration rather than the adopter's data. No member names a scan, so a value that would need one cannot be declared.");
+/**
+* One value a summary may carry. A number or a member of a declared enum — never anything else.
+*
+* This is the rule the issue asked to be in the type: `number | string` has no room for a row, an id, a
+* nested object, or a collection that grows with an adopter's data.
+*/
+const HealthSummaryValue = z.union([z.number(), z.string()]).describe("One scalar: a number, or a member of the closed list its key declares. Nothing else is representable — no names, no ids, no rows, no nested objects.");
+/** The compile-time half of "scalars only". Widen the value type and this line names the file. */
+const HEALTH_SUMMARY_IS_SCALAR_ONLY = true;
+/**
+* What a count must be for its key to be nominal — a bound, in either direction or both.
+*
+* **Both are optional and at least one is required**, which is the whole of the shape. `atMost: 0` is
+* `secretsDueForRotation`, where zero is the good answer; `atLeast: 1` is a count of things that must
+* exist, where zero is the fault. A declaration carrying neither is a claim with no content, and one
+* carrying an inverted pair is a claim nothing can satisfy — both would make every value on that key
+* want attention forever, which is worse than declaring nothing.
+*
+* Inclusive at the edge. A cadence saying *no more than zero overdue* means zero is fine.
+*/
+const HealthCountNominal = z.object({
+	atMost: z.number().int().nonnegative().optional().describe("The largest nominal value, inclusive. Above it the value wants attention."),
+	atLeast: z.number().int().nonnegative().optional().describe("The smallest nominal value, inclusive. Below it the value wants attention.")
+}).describe("A count's nominal range: at least one bound, inclusive at its edge. Neither is a claim with no content; an inverted pair is one nothing can satisfy.");
+/**
+* What a key claims a nominal value is, or null where it makes no claim at all.
+*
+* **Null is the default and stays supported forever.** Some measures genuinely have no good or bad
+* value — a count of things that simply exist — and a vocabulary that forced a claim would collect
+* invented ones. What must never happen is a client reading null as *fine*; {@link standingOf} answers
+* `unknowable` for it, and that is the point of this whole field.
+*/
+const HealthNominal = z.union([HealthCountNominal, z.array(z.string().min(1))]).nullable().describe("What this key's nominal value is: a bound for a `count`, the nominal members for a `state`, or null where the capability makes no claim. Which shape applies is decided by `kind`.");
+/**
+* Whether a declared nominal fits the kind it was declared on.
+*
+* A free function rather than an inline predicate because the refine needs it before the object exists
+* and because `states` is read from the same key — a `state` key's nominal must name members that key
+* actually declares, or the claim is unverifiable: a producer can never send a value that matches it.
+*
+* Null is always suitable. That is the default, and a key that grades nothing is the common case.
+*/
+function nominalSuitsKind(kind, nominal, states) {
+	if (nominal === null) return true;
+	if (kind === "count") {
+		if (Array.isArray(nominal)) return false;
+		const { atMost, atLeast } = nominal;
+		if (atMost === void 0 && atLeast === void 0) return false;
+		return atMost === void 0 || atLeast === void 0 || atLeast <= atMost;
+	}
+	if (!Array.isArray(nominal) || nominal.length === 0) return false;
+	return states === null ? true : nominal.every((member) => states.includes(member));
+}
+/**
+* One key a capability may report, declared alongside its routes.
+*
+* `scope` is **not nullable**, unlike an admin route's. A route may need only a verified caller — the
+* seam's `ping` does — but a number about somebody's posture never may, and an optional field here is a
+* field somebody forgets.
+*/
+const HealthSummaryKey = z.object({
+	key: z.string().regex(HEALTH_KEY_PATTERN, "A health key is one camelCase token — `secretsDueForRotation`.").describe("The key this value appears under in the capability's summary. One camelCase token."),
+	kind: HealthValueKind.describe("Whether the value is a count or a member of a closed list."),
+	states: z.array(z.string().min(1)).nullable().describe("Every value a `state` key may take, so a client can render each one it knows and nothing for one it does not. Null for a `count`, and required for a `state`: an enum with no members is a string field wearing a costume."),
+	scope: ControlPlaneScope.describe("The scope this value is behind — one the capability's own admin routes already require, never a new one. A caller without it gets no value rather than a zero."),
+	cost: HealthValueCost.describe("What producing this value costs on a manifest read."),
+	summary: z.string().min(1).describe("One line saying what the number means, for a client to render beside it without knowing the key."),
+	nominal: HealthNominal.default(null).describe("What a nominal value is for this key — a bound for a `count`, the nominal members for a `state`, or null where the capability makes no claim. A client reads null as `unknowable`, never as healthy.")
+}).refine((key) => key.kind === "state" ? key.states !== null && key.states.length > 0 : key.states === null, {
+	message: "A `state` key declares a non-empty closed list; a `count` key declares none.",
+	path: ["states"]
+}).refine((key) => nominalSuitsKind(key.kind, key.nominal, key.states), {
+	message: "A `count` key's nominal is a bound with at least one satisfiable side; a `state` key's is a non-empty list of members it declares.",
+	path: ["nominal"]
+}).describe("One bounded scalar a capability contributes to its manifest entry: what it is called, what it may be, what it costs, and which scope it is behind.");
+/**
+* A capability's summary as the manifest carries it: declared key → scalar.
+*
+* A record rather than a closed object, because the vocabulary is federated the way scopes and audit
+* actions are. **Parsing tolerates a key it has never heard of on purpose** — a client reading a newer
+* Worker must render the unknown one as nothing rather than fail the whole manifest.
+*/
+const HealthSummary = z.record(z.string(), HealthSummaryValue).describe("One capability's health summary: each declared key to its scalar. Unknown keys parse rather than throw, so a client of an older build renders what it knows and nothing for the rest.");
+/**
+* What one capability's summary is, for one caller. Four states, and the value carries which.
+*
+* A discriminated union rather than a nullable record with a flag beside it, and that is the whole
+* point of #350. A flag is the same information and the opposite property: correct for whoever
+* remembered to read it, and a zero for everybody else. Here the scalars are unreachable without
+* narrowing on `state`, so forgetting the sick case is a type error rather than a screen that says
+* everything is fine.
+*
+* - `undeclared` — the capability contributes no summary. Nothing to show, and nothing wrong.
+* - `withheld` — it declares one, and this connection was not granted the scope it sits behind. Read
+*   `healthKeys` beside this and a client can say a number exists that it may not see.
+* - `reported` — the values, each one named by a declaration that travels with it. Zero is one of these.
+* - `unavailable` — producing the summary failed. Not zero, not withheld, and never both.
+*/
+const CapabilityHealthReport = z.discriminatedUnion("state", [
+	z.object({ state: z.literal("undeclared").describe("This capability contributes no summary at all.") }).describe("A capability with nothing to report. Nothing to show, and nothing wrong."),
+	z.object({ state: z.literal("withheld").describe("A summary exists that this connection was not granted.") }).describe("A declared summary this caller may not see. Read `healthKeys` beside it to say a number exists rather than to say there is none."),
+	z.object({
+		state: z.literal("reported").describe("The summary was produced and this caller may see it."),
+		values: HealthSummary.describe("Each declared key this caller is entitled to, and its scalar. Zero is one.")
+	}).describe("The numbers, each one named by a declaration that travels beside it in `healthKeys`."),
+	z.object({ state: z.literal("unavailable").describe("Producing this capability's summary failed on this read.") }).describe("A summary that could not be produced. Deliberately empty: what the producer threw may name a row or a key, so nothing derived from it travels — there is nowhere to put it.")
+]).describe("What one capability's summary is, for one caller: nothing declared, declared and withheld, reported, or failed. The state is on the value, so a scalar is unreachable without narrowing.");
+/**
+* Read the four states off a manifest entry.
+*
+* **The failure flag is checked first and wins.** A Worker that sends both a failure and values is
+* describing a producer that did not finish, and reading what it sent anyway is reading whatever the
+* failure left behind.
+*
+* A Worker deployed before #350 sends no flag, which defaults to false, and lands on the three states
+* it already had. A Worker deployed before #317 sends neither field and lands on `undeclared`.
+*/
+function healthReport(entry) {
+	if (entry.healthUnavailable) return { state: "unavailable" };
+	if (entry.health) return {
+		state: "reported",
+		values: entry.health
+	};
+	return entry.healthKeys.length === 0 ? { state: "undeclared" } : { state: "withheld" };
+}
+/**
+* Put a report back on the wire.
+*
+* The one place the two fields are written, so a handler cannot set the values and forget the flag.
+* `undeclared` and `withheld` encode alike on purpose — `healthKeys` rides in the same entry and tells
+* them apart, which is the arrangement #317 chose and this does not disturb.
+*/
+function healthWire(report) {
+	return {
+		health: report.state === "reported" ? report.values : null,
+		healthUnavailable: report.state === "unavailable"
+	};
+}
+/**
+* Pair a capability's reported values with their declarations, dropping any value nothing declares.
+*
+* This is how "an unknown summary key is renderable as nothing rather than as an error" is real rather
+* than aspirational: a client renders what this returns, so a key from a Worker newer than its
+* declaration simply is not in the list.
+*
+* **Only `reported` has values.** A withheld summary and a failed one both name nothing here, which is
+* right for a list of numbers — and it is why a surface that must say *why* there is no number reads
+* `state` rather than the length of this.
+*/
+function namedHealthValues(descriptor) {
+	const health = descriptor.health;
+	if (health.state !== "reported") return [];
+	const named = [];
+	for (const key of descriptor.healthKeys) {
+		const value = health.values[key.key];
+		if (value !== void 0) named.push({
+			key,
+			value
+		});
+	}
+	return named;
+}
+/** Where {@link HealthSummaryValue} stands against the key that declared it. See {@link HealthStanding}. */
+function standingOf(key, value) {
+	const nominal = key.nominal;
+	if (nominal == null) return "unknowable";
+	if (key.kind === "count") {
+		if (Array.isArray(nominal) || typeof value !== "number" || !Number.isInteger(value)) return "unknowable";
+		if (nominal.atMost !== void 0 && value > nominal.atMost) return "attention";
+		if (nominal.atLeast !== void 0 && value < nominal.atLeast) return "attention";
+		return "nominal";
+	}
+	if (!Array.isArray(nominal) || typeof value !== "string") return "unknowable";
+	return nominal.includes(value) ? "nominal" : "attention";
+}
+/**
+* Every value this capability reported that wants somebody's attention, in declaration order.
+*
+* `namedHealthValues` one filter later, and here rather than in every client so the filter is written
+* once. The three stateless reports answer empty: `undeclared`, `withheld` and `unavailable` are states
+* of the *report* rather than of any value, and folding one of them into a list of graded measures is
+* exactly the collapse #350 and #471 each exist to prevent — a withheld number is not a bad number, and
+* a failed read is not a finding about the thing that failed to be read.
+*
+* A value standing at `unknowable` is not here either. The list is what wants attention, and a measure
+* nobody grades cannot want it.
+*
+* **So an empty list is not a clean bill of health, and a client that renders it as one has rebuilt
+* #471 one layer up.** Five situations answer `[]`: nothing declared, withheld, unavailable, everything
+* nominal, and everything ungradeable. Three of those are *could not look* rather than *nothing is
+* wrong*. A surface that wants to tell them apart has what it needs — the report's own state separates
+* the first three, and mapping {@link namedHealthValues} through {@link standingOf} separates the last
+* two — but it has to ask, and this function deliberately does not answer it.
+*/
+function healthAttention(descriptor) {
+	return namedHealthValues(descriptor).filter((named) => standingOf(named.key, named.value) === "attention");
+}
+//#endregion
+export { CapabilityHealthReport, HEALTH_SUMMARY_IS_SCALAR_ONLY, HealthCountNominal, HealthNominal, HealthSummary, HealthSummaryKey, HealthSummaryValue, HealthValueCost, HealthValueKind, healthAttention, healthReport, healthWire, namedHealthValues, standingOf };

package/dist/controlPlane/error/errors.d.ts

@@ -0,0 +1,67 @@
+import { PithyError } from "../../error/pithyError";
+import type { MessageParams } from "../../i18n/catalog";
+/**
+ * The `control-plane` strategy's throw sugar. The `controlplane/*` codes live in core's closed
+ * `KitErrorPayload` union (CLAUDE.md §Errors); these subclasses are the vehicles that set one.
+ *
+ * The security posture here is stricter than elsewhere in the tree. Public `message` and `action` are
+ * written for an operator reading a management client's logs, and say nothing a caller could use to
+ * probe the seam. Throw-site context — which verification step failed, which `kid` was presented,
+ * which environment the connection is bound to — goes in `detail`, which the HTTP codec strips.
+ *
+ * {@link ControlPlaneInvalidCredentialError} in particular is deliberately one error for every
+ * failing step. Distinguishing "unknown key" from "bad signature" from "replayed token" would turn
+ * the response into an oracle that tells an attacker exactly how far they got.
+ */
+interface ControlPlaneErrorArgs {
+    message?: string;
+    action?: string;
+    detail?: string;
+    /**
+     * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+     * unlike `action` and `detail` — these cross the boundary with `message`.
+     */
+    params?: MessageParams;
+}
+/**
+ * No connection is registered for this environment. The shipped default of a Worker that composes the
+ * seam and has never been connected — present, and denying everything.
+ */
+export declare class ControlPlaneNotConnectedError extends PithyError {
+    constructor(args?: ControlPlaneErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The credential failed verification. One error for every step — pass the step in `detail` so the log
+ * can say which, and the caller cannot.
+ */
+export declare class ControlPlaneInvalidCredentialError extends PithyError {
+    constructor(args?: ControlPlaneErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** The credential verified, but nothing granted it this operation. */
+export declare class ControlPlaneInsufficientScopeError extends PithyError {
+    constructor(args?: ControlPlaneErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/** The named key is not registered on this connection. */
+export declare class ControlPlaneKeyNotFoundError extends PithyError {
+    constructor(args?: ControlPlaneErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A key operation conflicts with the connection's current state — a duplicate registration, or an
+ * expiry that would leave no live key. The second is the lockout case, and refusing it is the reason
+ * expiry is a separate call from registration.
+ */
+export declare class ControlPlaneKeyConflictError extends PithyError {
+    constructor(args?: ControlPlaneErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/controlPlane/error/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;;;;GAYG;AAEH,UAAU,qBAAqB;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,UAAU;IAC3D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF;AAED;;;GAGG;AACH,qBAAa,kCAAmC,SAAQ,UAAU;IAChE,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF;AAED,sEAAsE;AACtE,qBAAa,kCAAmC,SAAQ,UAAU;IAChE,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF;AAED,0DAA0D;AAC1D,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF"}

package/dist/controlPlane/error/errors.js

@@ -0,0 +1,79 @@
+import { PithyError } from "../../error/pithyError.js";
+//#region src/controlPlane/error/errors.ts
+/**
+* No connection is registered for this environment. The shipped default of a Worker that composes the
+* seam and has never been connected — present, and denying everything.
+*/
+var ControlPlaneNotConnectedError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "controlplane/not_connected",
+			status: 403,
+			message: args.message ?? "No management client is connected to this environment.",
+			action: args.action ?? "Run pithy dashboard connect --env <environment> to register one.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/**
+* The credential failed verification. One error for every step — pass the step in `detail` so the log
+* can say which, and the caller cannot.
+*/
+var ControlPlaneInvalidCredentialError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "controlplane/invalid_credential",
+			status: 401,
+			message: args.message ?? "That credential is not valid here.",
+			action: args.action ?? "Rotate the connection's key, or re-run pithy dashboard connect --update.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/** The credential verified, but nothing granted it this operation. */
+var ControlPlaneInsufficientScopeError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "controlplane/insufficient_scope",
+			status: 403,
+			message: args.message ?? "This connection is not scoped for that operation.",
+			action: args.action ?? "Re-run pithy dashboard connect --update and grant the scope this call needs.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/** The named key is not registered on this connection. */
+var ControlPlaneKeyNotFoundError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "controlplane/key_not_found",
+			status: 404,
+			message: args.message ?? "No registered key answers to that key id.",
+			action: args.action ?? "Read GET /control-plane/keys for the keys this connection currently trusts.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+/**
+* A key operation conflicts with the connection's current state — a duplicate registration, or an
+* expiry that would leave no live key. The second is the lockout case, and refusing it is the reason
+* expiry is a separate call from registration.
+*/
+var ControlPlaneKeyConflictError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "controlplane/key_conflict",
+			status: 409,
+			message: args.message ?? "That key operation conflicts with the connection's current state.",
+			action: args.action ?? "Register the replacement key and prove it with a ping before expiring this one.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+//#endregion
+export { ControlPlaneInsufficientScopeError, ControlPlaneInvalidCredentialError, ControlPlaneKeyConflictError, ControlPlaneKeyNotFoundError, ControlPlaneNotConnectedError };

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

@@ -0,0 +1,112 @@
+import type { Hono, MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import type { AdminRoute } from "../discovery/adminRoute";
+/**
+ * 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.
+ */
+export declare function devLoopbackAllows(env: Record<string, unknown>, origin: string): boolean;
+/**
+ * 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.
+ */
+export declare function originOf(value: string | null | undefined): string | 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.
+ */
+export declare function allowedOriginSet(config: {
+    issuer: string;
+    allowedOrigins: readonly string[];
+}): ReadonlySet<string>;
+/** One path's precomputed answer. Built once at composition; nothing here is derived per request. */
+export interface CorsSurfaceEntry {
+    /** The fully mounted path, exactly as the descriptor declares it — `:segment` params included. */
+    path: string;
+    /** `Access-Control-Allow-Methods`: every method declared on this path, plus `OPTIONS`. */
+    allowMethods: string;
+    /** `Access-Control-Allow-Headers`: the token header, plus `content-type` where a body is plausible. */
+    allowHeaders: string;
+}
+/**
+ * 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.
+ */
+export declare function corsSurface(capabilities: readonly {
+    adminRoutes?: readonly AdminRoute[];
+}[]): CorsSurfaceEntry[];
+/**
+ * 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.
+ */
+export declare function corsMiddleware(entry: CorsSurfaceEntry, origins: ReadonlySet<string>, maxAgeSeconds: number): MiddlewareHandler<PithyHonoEnv>;
+/**
+ * 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.
+ */
+export declare function registerControlPlaneCors(app: Hono<PithyHonoEnv>, surface: readonly CorsSurfaceEntry[], origins: ReadonlySet<string>, maxAgeSeconds: number): void;
+//# sourceMappingURL=cors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/http/cors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAmC1D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAOvF;AAKD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAUxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CAOnH;AAED,qGAAqG;AACrG,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,YAAY,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,SAAS;IAAE,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,EAAE,GAAG,gBAAgB,EAAE,CAoBhH;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAC5B,aAAa,EAAE,MAAM,GACpB,iBAAiB,CAAC,YAAY,CAAC,CAmCjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,EACvB,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAC5B,aAAa,EAAE,MAAM,GACpB,IAAI,CAEN"}