@pithy-sh/core 0.1.1 → 0.1.3

package/dist/controlPlane/token/mint.d.ts

@@ -0,0 +1,56 @@
+import type { Ed25519PublicJwk } from "../data/connection";
+/**
+ * Mint a control-plane token — the management client's half of the seam.
+ *
+ * **This ships because the seam is MIT and is never gated by tier.** "You can build your own client
+ * against your own Worker" has to be true, and it is not true if the only way to produce a token the
+ * Worker accepts is to reverse-engineer the verifier. So the minting side lives here, beside the
+ * verifying side, and the two are tested against each other.
+ *
+ * It is also what the hosted dashboard would use, and what every test in this package uses to sign a
+ * real token rather than assert against a fixture.
+ *
+ * **Nothing here touches a private key store.** The caller supplies an already-imported `CryptoKey`.
+ * Core holds no key material, has no opinion about where a private key lives, and this file would be
+ * the wrong place to acquire one.
+ */
+/** One token's worth of claims, minus the parts {@link mintControlPlaneToken} computes. */
+export interface MintControlPlaneToken {
+    /** The signing key, imported for `Ed25519` with `["sign"]` usage. */
+    privateKey: CryptoKey;
+    /** The `kid` naming which registered public key verifies this token. */
+    keyId: string;
+    /** The management client's origin — must equal the `issuer` stored on the connection. */
+    issuer: string;
+    /** The connection this token addresses. */
+    connectionId: string;
+    /** Who, in the management client's own id space, is acting. */
+    subject: string;
+    /** The single operation this token authorizes. One call, one scope. */
+    scope: string;
+    /** The raw request body these claims are bound to. Empty for a request that carries none. */
+    body?: Uint8Array;
+    /** Seconds this token is good for. The Worker caps it, so asking for more only wastes the request. */
+    lifetimeSeconds?: number;
+    /** The clock, injected so a caller can mint a token at a chosen instant. */
+    now?: () => Date;
+    /** The token's unique id. Generated when absent; supply one only to test a replay. */
+    tokenId?: string;
+}
+/**
+ * Build and sign a compact JWS the seam will accept.
+ *
+ * The body digest is computed here rather than accepted from the caller, so a client cannot mint a
+ * token whose digest disagrees with the bytes it is about to send. `bodySha256` is null exactly when
+ * the body is empty, which is the same bijection the verifier enforces.
+ */
+export declare function mintControlPlaneToken(input: MintControlPlaneToken): Promise<string>;
+/**
+ * Export a generated key pair's public half as the JWK the adopter registers.
+ *
+ * `crv` and `kty` are re-asserted from our own constants rather than trusted from the export, so a
+ * runtime that spelled them differently produces a key this seam still recognizes — or fails here,
+ * where it is obvious, rather than at the first verification.
+ */
+export declare function exportPublicJwk(publicKey: CryptoKey): Promise<Ed25519PublicJwk>;
+//# sourceMappingURL=mint.d.ts.map

package/dist/controlPlane/token/mint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mint.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/token/mint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAK3D;;;;;;;;;;;;;;GAcG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,UAAU,EAAE,SAAS,CAAC;IACtB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,sGAAsG;IACtG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAOD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBzF;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAIrF"}

package/dist/controlPlane/token/mint.js

@@ -0,0 +1,55 @@
+import { ControlPlaneClaims } from "./claims.js";
+import { base64UrlEncode } from "./base64url.js";
+import { sha256Base64Url } from "./digest.js";
+//#region src/controlPlane/token/mint.ts
+/** Base64url a UTF-8 JSON serialization — the encoding both JWS segments use. */
+function encodeSegment(value) {
+	return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+/**
+* Build and sign a compact JWS the seam will accept.
+*
+* The body digest is computed here rather than accepted from the caller, so a client cannot mint a
+* token whose digest disagrees with the bytes it is about to send. `bodySha256` is null exactly when
+* the body is empty, which is the same bijection the verifier enforces.
+*/
+async function mintControlPlaneToken(input) {
+	const body = input.body ?? /* @__PURE__ */ new Uint8Array(0);
+	const issuedAt = Math.floor((input.now?.() ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	const header = {
+		alg: "EdDSA",
+		typ: "JWT",
+		kid: input.keyId
+	};
+	const claims = ControlPlaneClaims.parse({
+		iss: input.issuer,
+		aud: input.connectionId,
+		sub: input.subject,
+		scope: input.scope,
+		jti: input.tokenId ?? crypto.randomUUID(),
+		iat: issuedAt,
+		exp: issuedAt + (input.lifetimeSeconds ?? 60),
+		bodySha256: body.byteLength === 0 ? null : await sha256Base64Url(body)
+	});
+	const signingInput = `${encodeSegment(header)}.${encodeSegment(claims)}`;
+	const signature = await crypto.subtle.sign("Ed25519", input.privateKey, new TextEncoder().encode(signingInput));
+	return `${signingInput}.${base64UrlEncode(new Uint8Array(signature))}`;
+}
+/**
+* Export a generated key pair's public half as the JWK the adopter registers.
+*
+* `crv` and `kty` are re-asserted from our own constants rather than trusted from the export, so a
+* runtime that spelled them differently produces a key this seam still recognizes — or fails here,
+* where it is obvious, rather than at the first verification.
+*/
+async function exportPublicJwk(publicKey) {
+	const exported = await crypto.subtle.exportKey("jwk", publicKey);
+	if (!exported.x) throw new TypeError("Ed25519 public key export carried no `x` coordinate.");
+	return {
+		kty: "OKP",
+		crv: "Ed25519",
+		x: exported.x
+	};
+}
+//#endregion
+export { exportPublicJwk, mintControlPlaneToken };

package/dist/controlPlane/wire.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The control-plane wire contract: the names both ends of the seam must spell identically, and the one
+ * rule for reading what they carry.
+ *
+ * **This module imports nothing, and that is its whole job.** Per `docs/CONTROL-PLANE.md` §4 a browser
+ * calls the adopter's Worker *directly* — the management client's server mints the token, the browser
+ * sends it — so a DOM-typed module has to name the request header, and has to read the version header
+ * off the response to notice a customer deploying mid-session. Reaching these constants through
+ * `http/verify` drags the verifier in with them: WebCrypto, the replay guard, the seam config. A
+ * program compiled against `lib.dom` then fails on `token/digest.ts` and `token/jws.ts`, where a
+ * `Uint8Array<ArrayBufferLike>` is not the `BufferSource` the DOM lib declares — the Workers and DOM
+ * type libraries meeting, which no amount of care at the call site resolves.
+ *
+ * The alternative was to let each client re-declare the strings. That is what the dashboard did, with
+ * a comment and an assertion holding the copy honest, and two copies of a wire constant is exactly the
+ * drift a constant exists to prevent. `wire.test.ts` asserts the module graph here stays empty, because
+ * the property is only true until someone adds the first convenient import.
+ *
+ * {@link workerBuildChanged} is here for the same reason one level up. The dashboard did not only copy
+ * the header name — it wrote its own rule for reading the value, "invalidate when the id differs", and
+ * that rule was wrong in a way a copied constant could never have caught. A rule both ends must agree on
+ * belongs beside the names both ends must spell.
+ */
+/**
+ * The header a control-plane token is presented on.
+ *
+ * Not `Authorization`, deliberately: `@pithy-sh/auth` builds a Better Auth instance for any request
+ * carrying that header, so a management call would drag the whole auth stack in. See `http/verify.ts`.
+ */
+export declare const CONTROL_PLANE_HEADER = "pithy-control-plane";
+/**
+ * The response header carrying the build that answered a control-plane call.
+ *
+ * Set on every control-plane response — allowed and denied alike, and on every capability's admin
+ * routes rather than only the seam's own. A management client reads it to pin each recorded action to
+ * the exact build it hit, and to notice a version changing mid-session, which is the moment a rendered
+ * pane has quietly gone out of date. Absent where the `CF_VERSION_METADATA` binding is, which reads as
+ * "this Worker cannot say" rather than as a value to trust.
+ *
+ * **Carries the id and nothing else, permanently.** Its companion below is a second header rather than
+ * a second field in this one for one reason: a client already deployed compares this whole string. Fold
+ * anything into it and the day the adopter upgrades the kit reads as a version change that never
+ * happened — a false invalidation, which is the failure the pair exists to prevent, arriving from the
+ * fix for it.
+ */
+export declare const CONTROL_PLANE_VERSION_HEADER = "pithy-worker-version";
+/**
+ * The response header carrying **when the running version was uploaded** — ISO-8601, verbatim, off the
+ * same `CF_VERSION_METADATA` binding as the id.
+ *
+ * Read beside {@link CONTROL_PLANE_VERSION_HEADER}, never folded into it, so a client can compare two
+ * values separately. {@link workerBuildChanged} is the rule; do not hand-write one.
+ *
+ * **Cloudflare has two objects, and this is the first of them.** A *version* is an immutable upload of
+ * code and config — id, created timestamp, tag, fixed at upload and never again. A *deployment* points
+ * at one or more versions with traffic percentages, and is its own object with its own id and time. The
+ * `CF_VERSION_METADATA` binding reports the version, and **the runtime hands a Worker no binding for the
+ * deployment**. So this header is the upload moment, and it is fixed for as long as that version exists.
+ *
+ * That mechanism predicts the behavior rather than merely recording it: **a rollback creates a new
+ * deployment aimed at an existing version, so nothing here moves** — the binding is not stale and not
+ * ambiguous, the thing that changed was a different object. It answers the next question too. A traffic
+ * split, a gradual rollout, which deployment is serving: none of it is visible from inside a Worker.
+ *
+ * Measured on a real account, 2026-08-10, which is what made it a fact rather than a reading of the
+ * docs: version `A` uploaded at `22:28:56.762349Z`, `B` four seconds later, `wrangler rollback` to `A`
+ * at ~`22:29:20`. Reading at `22:31:37` returned `A`'s id **and `A`'s original timestamp**, unmoved,
+ * while wrangler's own output named the new deployment's version list. Two details from the same run
+ * that a client will meet:
+ *
+ * - **Every `wrangler deploy` mints a new version**, even for a one-character change — that is why `B`
+ *   exists. An ordinary redeploy therefore always moves the id, and is never invisible.
+ * - **Propagation lags.** Twenty seconds after wrangler reported the rollback at 100%, the URL still
+ *   answered from the older version. A client watching closely sees the pair flip and settle; that is
+ *   the platform converging, not two deploys.
+ */
+export declare const CONTROL_PLANE_VERSION_CREATED_HEADER = "pithy-worker-version-created";
+/**
+ * The pair a client reads off one control-plane response: two `headers.get()` calls, each `string | null`.
+ */
+export interface WorkerBuild {
+    /** {@link CONTROL_PLANE_VERSION_HEADER}, or `null` where the response carried none. */
+    version: string | null;
+    /** {@link CONTROL_PLANE_VERSION_CREATED_HEADER}, or `null` where the response carried none. */
+    createdAt: string | null;
+}
+/**
+ * Did the Worker answering now differ from the Worker that answered before?
+ *
+ * **The rule, total over the pair.** A client compares field by field and only where both sides carried
+ * a value; anything that differs is a change. Four states:
+ *
+ * 1. nothing differs — the same build, still answering. Say nothing.
+ * 2. `version` differs — a different build is live, and what is rendered came from one that no longer
+ *    serves.
+ * 3. `version` the same, `createdAt` differs — **the same build was deployed again.** Same consequence.
+ * 4. either side silent on a field — that field says nothing.
+ *
+ * **State 3 is not reachable on today's platform, and it stays anyway.** A version's timestamp
+ * is fixed at upload and a rollback only makes a new deployment, so the pair cannot show a moved time
+ * against an unmoved id (see {@link CONTROL_PLANE_VERSION_CREATED_HEADER}). It is here because a total
+ * comparison over the pair is the correct shape, not because a rollback was expected to trip it — **a
+ * comparison that enumerates which fields are allowed to move is wrong the day the platform moves a
+ * different one**, and it is wrong silently, as "nothing changed". It costs one branch.
+ *
+ * Direction is *not* interpreted. A time that moved is a fact; "it moved backwards, therefore a
+ * rollback" is not, and would be wrong twice over — a rollback moves neither field, and propagation lag
+ * makes an older version answer for a while after a deploy.
+ *
+ * **What no state here reaches: a deployment.** Rollbacks, traffic splits, gradual rollouts — a Worker
+ * has no binding for the object that carries them, so this is a boundary of what the runtime exposes
+ * rather than a gap in the seam. A client that needs a deployment reads Cloudflare's deployments API.
+ *
+ * **Absence is never change**, in every direction: a Worker that declares no `version_metadata` sends
+ * neither header, a call that failed before its headers were read has none, and a client that has not
+ * looked yet holds nulls. A blank value counts as absent too — the seam never sends one, but a proxy in
+ * between can blank a header it does not understand, and an empty string differs from every real id. The
+ * failure this shape refuses is the one that costs an adopter trust: invalidating a rendered pane on a
+ * deploy that never happened.
+ */
+export declare function workerBuildChanged(before: WorkerBuild, after: WorkerBuild): boolean;
+//# sourceMappingURL=wire.d.ts.map

package/dist/controlPlane/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/controlPlane/wire.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,yBAAyB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,oCAAoC,iCAAiC,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,+FAA+F;IAC/F,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAEnF"}

package/dist/controlPlane/wire.js

@@ -0,0 +1,123 @@
+//#region src/controlPlane/wire.ts
+/**
+* The control-plane wire contract: the names both ends of the seam must spell identically, and the one
+* rule for reading what they carry.
+*
+* **This module imports nothing, and that is its whole job.** Per `docs/CONTROL-PLANE.md` §4 a browser
+* calls the adopter's Worker *directly* — the management client's server mints the token, the browser
+* sends it — so a DOM-typed module has to name the request header, and has to read the version header
+* off the response to notice a customer deploying mid-session. Reaching these constants through
+* `http/verify` drags the verifier in with them: WebCrypto, the replay guard, the seam config. A
+* program compiled against `lib.dom` then fails on `token/digest.ts` and `token/jws.ts`, where a
+* `Uint8Array<ArrayBufferLike>` is not the `BufferSource` the DOM lib declares — the Workers and DOM
+* type libraries meeting, which no amount of care at the call site resolves.
+*
+* The alternative was to let each client re-declare the strings. That is what the dashboard did, with
+* a comment and an assertion holding the copy honest, and two copies of a wire constant is exactly the
+* drift a constant exists to prevent. `wire.test.ts` asserts the module graph here stays empty, because
+* the property is only true until someone adds the first convenient import.
+*
+* {@link workerBuildChanged} is here for the same reason one level up. The dashboard did not only copy
+* the header name — it wrote its own rule for reading the value, "invalidate when the id differs", and
+* that rule was wrong in a way a copied constant could never have caught. A rule both ends must agree on
+* belongs beside the names both ends must spell.
+*/
+/**
+* The header a control-plane token is presented on.
+*
+* Not `Authorization`, deliberately: `@pithy-sh/auth` builds a Better Auth instance for any request
+* carrying that header, so a management call would drag the whole auth stack in. See `http/verify.ts`.
+*/
+const CONTROL_PLANE_HEADER = "pithy-control-plane";
+/**
+* The response header carrying the build that answered a control-plane call.
+*
+* Set on every control-plane response — allowed and denied alike, and on every capability's admin
+* routes rather than only the seam's own. A management client reads it to pin each recorded action to
+* the exact build it hit, and to notice a version changing mid-session, which is the moment a rendered
+* pane has quietly gone out of date. Absent where the `CF_VERSION_METADATA` binding is, which reads as
+* "this Worker cannot say" rather than as a value to trust.
+*
+* **Carries the id and nothing else, permanently.** Its companion below is a second header rather than
+* a second field in this one for one reason: a client already deployed compares this whole string. Fold
+* anything into it and the day the adopter upgrades the kit reads as a version change that never
+* happened — a false invalidation, which is the failure the pair exists to prevent, arriving from the
+* fix for it.
+*/
+const CONTROL_PLANE_VERSION_HEADER = "pithy-worker-version";
+/**
+* The response header carrying **when the running version was uploaded** — ISO-8601, verbatim, off the
+* same `CF_VERSION_METADATA` binding as the id.
+*
+* Read beside {@link CONTROL_PLANE_VERSION_HEADER}, never folded into it, so a client can compare two
+* values separately. {@link workerBuildChanged} is the rule; do not hand-write one.
+*
+* **Cloudflare has two objects, and this is the first of them.** A *version* is an immutable upload of
+* code and config — id, created timestamp, tag, fixed at upload and never again. A *deployment* points
+* at one or more versions with traffic percentages, and is its own object with its own id and time. The
+* `CF_VERSION_METADATA` binding reports the version, and **the runtime hands a Worker no binding for the
+* deployment**. So this header is the upload moment, and it is fixed for as long as that version exists.
+*
+* That mechanism predicts the behavior rather than merely recording it: **a rollback creates a new
+* deployment aimed at an existing version, so nothing here moves** — the binding is not stale and not
+* ambiguous, the thing that changed was a different object. It answers the next question too. A traffic
+* split, a gradual rollout, which deployment is serving: none of it is visible from inside a Worker.
+*
+* Measured on a real account, 2026-08-10, which is what made it a fact rather than a reading of the
+* docs: version `A` uploaded at `22:28:56.762349Z`, `B` four seconds later, `wrangler rollback` to `A`
+* at ~`22:29:20`. Reading at `22:31:37` returned `A`'s id **and `A`'s original timestamp**, unmoved,
+* while wrangler's own output named the new deployment's version list. Two details from the same run
+* that a client will meet:
+*
+* - **Every `wrangler deploy` mints a new version**, even for a one-character change — that is why `B`
+*   exists. An ordinary redeploy therefore always moves the id, and is never invisible.
+* - **Propagation lags.** Twenty seconds after wrangler reported the rollback at 100%, the URL still
+*   answered from the older version. A client watching closely sees the pair flip and settle; that is
+*   the platform converging, not two deploys.
+*/
+const CONTROL_PLANE_VERSION_CREATED_HEADER = "pithy-worker-version-created";
+/**
+* Did the Worker answering now differ from the Worker that answered before?
+*
+* **The rule, total over the pair.** A client compares field by field and only where both sides carried
+* a value; anything that differs is a change. Four states:
+*
+* 1. nothing differs — the same build, still answering. Say nothing.
+* 2. `version` differs — a different build is live, and what is rendered came from one that no longer
+*    serves.
+* 3. `version` the same, `createdAt` differs — **the same build was deployed again.** Same consequence.
+* 4. either side silent on a field — that field says nothing.
+*
+* **State 3 is not reachable on today's platform, and it stays anyway.** A version's timestamp
+* is fixed at upload and a rollback only makes a new deployment, so the pair cannot show a moved time
+* against an unmoved id (see {@link CONTROL_PLANE_VERSION_CREATED_HEADER}). It is here because a total
+* comparison over the pair is the correct shape, not because a rollback was expected to trip it — **a
+* comparison that enumerates which fields are allowed to move is wrong the day the platform moves a
+* different one**, and it is wrong silently, as "nothing changed". It costs one branch.
+*
+* Direction is *not* interpreted. A time that moved is a fact; "it moved backwards, therefore a
+* rollback" is not, and would be wrong twice over — a rollback moves neither field, and propagation lag
+* makes an older version answer for a while after a deploy.
+*
+* **What no state here reaches: a deployment.** Rollbacks, traffic splits, gradual rollouts — a Worker
+* has no binding for the object that carries them, so this is a boundary of what the runtime exposes
+* rather than a gap in the seam. A client that needs a deployment reads Cloudflare's deployments API.
+*
+* **Absence is never change**, in every direction: a Worker that declares no `version_metadata` sends
+* neither header, a call that failed before its headers were read has none, and a client that has not
+* looked yet holds nulls. A blank value counts as absent too — the seam never sends one, but a proxy in
+* between can blank a header it does not understand, and an empty string differs from every real id. The
+* failure this shape refuses is the one that costs an adopter trust: invalidating a rendered pane on a
+* deploy that never happened.
+*/
+function workerBuildChanged(before, after) {
+	return differs(before.version, after.version) || differs(before.createdAt, after.createdAt);
+}
+/** One field of the pair: a difference only where both sides actually said something. */
+function differs(before, after) {
+	if (typeof before !== "string" || before.trim() === "") return false;
+	if (typeof after !== "string" || after.trim() === "") return false;
+	return before !== after;
+}
+//#endregion
+export { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER, workerBuildChanged };

package/dist/createBackend.d.ts

@@ -0,0 +1,58 @@
+import { Hono } from "hono";
+import type { Capability, MergedDatabases, MergedKvNamespaces, MergedWorkflowParams, PithyVars } from "./capability/capability";
+import { type DbRegistry } from "./data/databases";
+import { type KvRegistry } from "./kv/namespaces";
+import type { Logger } from "./logger/logger";
+import { type WorkflowDispatcher } from "./workflow/dispatch";
+/** Inputs to {@link createBackend}: the capabilities to assemble, plus the app's own capability. */
+export interface CreateBackendOptions<Caps extends readonly Capability[], App extends Capability> {
+    /** Library capabilities (core + each `@pithy-sh/*`), composed in order. */
+    capabilities: Caps;
+    /**
+     * The app itself, as a `Capability` — principle 4: the app is just another capability. Its
+     * databases, KV namespaces, middleware, routes, and bindings compose with the rest; routes last.
+     */
+    app?: App;
+    /**
+     * The base logger bound to `c.var.log`, set **once** here at assembly (the per-request `env`
+     * constraint is honored: correlation fields are bound per request, not at module load). Defaults to
+     * the CF-native Mode 2 worker logger (`info`, structured records to Workers Logs). Pass a configured
+     * one to change the level or attach a tail/Logpush transport.
+     */
+    logger?: Logger;
+    /**
+     * Fallback environment name (`dev` | `staging` | `production`) for the log correlation `env` field.
+     * The primary signal is the per-request `ENVIRONMENT` var (the convention `@pithy-sh/secrets` and
+     * `@pithy-sh/email` already stamp into each deployed Worker); this is only used where that var is
+     * absent — e.g. a non-provisioned local run. Falls through to `unknown` when neither is present.
+     */
+    env?: string;
+}
+/** The Hono env `createBackend` returns — `db`/`kv`/`workflows` typed precisely from the merged capabilities. */
+type BackendEnv<Caps extends readonly Capability[]> = {
+    Bindings: Record<string, unknown>;
+    Variables: Omit<PithyVars, "db" | "kv" | "workflows"> & {
+        db: DbRegistry<MergedDatabases<Caps>>;
+        kv: KvRegistry<MergedKvNamespaces<Caps>>;
+        workflows: WorkflowDispatcher<MergedWorkflowParams<Caps>>;
+    };
+};
+/**
+ * Assemble capabilities into a deployable Hono app — a valid Worker `fetch` handler.
+ *
+ * Serves `GET /health`; merges every capability's `databases` and `kvNamespaces` into registries
+ * (tables/stores unioned per group); validates that every required binding is present; composes
+ * each capability's middleware; and mounts the capability (then app) routes. On every request
+ * `c.var.db` is the typed database registry — one `Kysely` per named database (`c.var.db.app`) —
+ * and `c.var.kv` the typed namespace registry — one `TypedKv` per store (`c.var.kv.cms.pages`).
+ * `PithyError`s become their declared HTTP status via {@link pithyErrorHandler}.
+ *
+ * Binding validation runs **once on the first request**, not at module load: in Workers `env` is
+ * per-request, so there is no env to check until a request arrives. The result is memoized.
+ *
+ * The return is typed precisely from the capabilities array — `createBackend({ capabilities }).get(
+ * "/x", (c) => c.var.db.app.selectFrom("…"))` gets autocomplete on every registered table.
+ */
+export declare function createBackend<const Caps extends readonly Capability[], const App extends Capability = Capability<Record<never, never>, Record<never, never>>>(options: CreateBackendOptions<Caps, App>): Hono<BackendEnv<readonly [...Caps, App]>>;
+export {};
+//# sourceMappingURL=createBackend.d.ts.map

package/dist/createBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBackend.d.ts","sourceRoot":"","sources":["../src/createBackend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAG5B,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EAEpB,SAAS,EACV,MAAM,yBAAyB,CAAC;AAKjC,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMtF,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAK9C,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,oGAAoG;AACpG,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EAAE,GAAG,SAAS,UAAU;IAC9F,2EAA2E;IAC3E,YAAY,EAAE,IAAI,CAAC;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IACV;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,iHAAiH;AACjH,KAAK,UAAU,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI;IACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,CAAC,GAAG;QACtD,EAAE,EAAE,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,EAAE,EAAE,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,SAAS,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;KAC3D,CAAC;CACH,CAAC;AAuCF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAuKrF"}

package/dist/createBackend.js

@@ -0,0 +1,170 @@
+import { noopEmit } from "./audit/recorder.js";
+import { BindingSpec } from "./capability/bindings.js";
+import { ValidationError } from "./error/pithyError.js";
+import { recordComposition } from "./capability/composition.js";
+import { validateBindings } from "./capability/validateBindings.js";
+import { workerVersion } from "./worker/identity.js";
+import { isControlPlaneCapability } from "./controlPlane/capability.js";
+import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors.js";
+import { buildDbRegistry, composeDatabases } from "./data/databases.js";
+import { noEntitlementProvider } from "./entitlement/entitlement.js";
+import { pithyErrorHandler } from "./error/http.js";
+import { bakedTranslator } from "./i18n/translator.js";
+import { catalogFor, composeMessages } from "./i18n/registry.js";
+import { buildKvRegistry, composeKv } from "./kv/namespaces.js";
+import { bindRequestContext, createWorkerLogger } from "./logger/worker.js";
+import { HEALTH_PATH } from "./worker/health.js";
+import { registeredWorkflowBinding } from "./workflow/bindings.js";
+import { buildWorkflowDispatcher } from "./workflow/dispatch.js";
+import { composeWorkflows } from "./workflow/register.js";
+import { Hono } from "hono";
+//#region src/createBackend.ts
+/**
+* Collapse duplicate bindings (same `type:name`) — capability and derived specs overlap. A binding
+* required by **any** source stays required: a derived database/namespace binding (structurally
+* required — the request context builds a handle on it) must not be masked by an author marking the
+* same binding `optional`. So `optional` is the AND of every occurrence.
+*/
+function dedupeBindings(specs) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const spec of specs) {
+		const key = `${spec.type}:${spec.name}`;
+		const existing = byKey.get(key);
+		if (!existing) byKey.set(key, { ...spec });
+		else if (!spec.optional) existing.optional = false;
+	}
+	return [...byKey.values()];
+}
+/**
+* The deployed Worker version id, for the log record's `version` correlation field.
+*
+* Delegates to `workerVersion` rather than re-reading the binding: this used to be a private copy here,
+* and a second reader of one binding is how the name and the declaration drift apart. `undefined` rather
+* than `null` because the logger omits an undefined field.
+*/
+function versionOf(env) {
+	return workerVersion(env) ?? void 0;
+}
+/**
+* The environment name for log correlation, resolved from context: the per-request `ENVIRONMENT` var
+* (the signal `@pithy-sh/secrets`/`@pithy-sh/email` stamp into each deployed Worker), else the explicit
+* `createBackend({ env })` fallback, else `unknown`. No caller effort where `ENVIRONMENT` is present.
+*/
+function envNameOf(env, fallback) {
+	return typeof env.ENVIRONMENT === "string" && env.ENVIRONMENT.length > 0 ? env.ENVIRONMENT : fallback ?? "unknown";
+}
+/**
+* Assemble capabilities into a deployable Hono app — a valid Worker `fetch` handler.
+*
+* Serves `GET /health`; merges every capability's `databases` and `kvNamespaces` into registries
+* (tables/stores unioned per group); validates that every required binding is present; composes
+* each capability's middleware; and mounts the capability (then app) routes. On every request
+* `c.var.db` is the typed database registry — one `Kysely` per named database (`c.var.db.app`) —
+* and `c.var.kv` the typed namespace registry — one `TypedKv` per store (`c.var.kv.cms.pages`).
+* `PithyError`s become their declared HTTP status via {@link pithyErrorHandler}.
+*
+* Binding validation runs **once on the first request**, not at module load: in Workers `env` is
+* per-request, so there is no env to check until a request arrives. The result is memoized.
+*
+* The return is typed precisely from the capabilities array — `createBackend({ capabilities }).get(
+* "/x", (c) => c.var.db.app.selectFrom("…"))` gets autocomplete on every registered table.
+*/
+function createBackend(options) {
+	const all = options.app ? [...options.capabilities, options.app] : [...options.capabilities];
+	const present = new Set(all.map((cap) => cap.name));
+	for (const cap of all) for (const dep of cap.dependsOn ?? []) if (!present.has(dep)) throw new ValidationError({
+		message: `Capability "${cap.name}" requires the "${dep}" capability, which is not composed.`,
+		action: `Add ${dep}() to createBackend's capabilities (run \`pithy add ${dep}\`).`
+	});
+	for (const cap of all) cap.compose?.({ capabilities: all });
+	recordComposition(all);
+	const databases = composeDatabases(all);
+	const messages = composeMessages(all);
+	const defaultTranslator = bakedTranslator(catalogFor(messages, "en"));
+	const namespaces = composeKv(all);
+	const workflows = composeWorkflows(all);
+	const required = dedupeBindings([
+		...all.flatMap((cap) => cap.requiredBindings),
+		...Object.values(databases).map((db) => BindingSpec.parse({
+			type: "d1",
+			name: db.binding
+		})),
+		...Object.values(namespaces).map((ns) => BindingSpec.parse({
+			type: "kv",
+			name: ns.binding
+		})),
+		...Object.values(workflows).map((entry) => BindingSpec.parse(registeredWorkflowBinding(entry)))
+	]);
+	const app = new Hono();
+	app.onError(pithyErrorHandler);
+	const baseLogger = options.logger ?? createWorkerLogger();
+	const controlPlane = all.find(isControlPlaneCapability);
+	if (controlPlane) {
+		const cors = controlPlane.controlPlaneConfig;
+		registerControlPlaneCors(app, corsSurface(all), allowedOriginSet(cors), cors.corsMaxAgeSeconds);
+	}
+	let validated = false;
+	app.use("*", async (c, next) => {
+		const env = c.env;
+		if (!validated) {
+			validateBindings(env, required);
+			validated = true;
+		}
+		if (c.get("auth") === void 0) c.set("auth", null);
+		if (c.get("locale") === void 0) c.set("locale", null);
+		if (c.get("t") === void 0) c.set("t", defaultTranslator);
+		if (c.get("controlPlane") === void 0) c.set("controlPlane", null);
+		if (c.get("controlPlaneVerifier") === void 0) c.set("controlPlaneVerifier", null);
+		if (c.get("sameOrigin") === void 0) c.set("sameOrigin", null);
+		if (c.get("emit") === void 0) c.set("emit", noopEmit);
+		if (c.get("entitlements") === void 0) c.set("entitlements", noEntitlementProvider);
+		if (c.get("log") === void 0) c.set("log", bindRequestContext(baseLogger, {
+			request: c.req.header("cf-ray") ?? crypto.randomUUID(),
+			method: c.req.method,
+			path: c.req.path,
+			env: envNameOf(env, options.env),
+			version: versionOf(env)
+		}));
+		if (c.get("db") === void 0) c.set("db", buildDbRegistry(env, databases));
+		if (c.get("kv") === void 0) c.set("kv", buildKvRegistry(env, namespaces, c.var.log));
+		if (c.get("workflows") === void 0) c.set("workflows", buildWorkflowDispatcher(env, workflows, c.var.log));
+		const start = Date.now();
+		await next();
+		c.var.log.info("request", {
+			status: c.res.status,
+			elapsed: Date.now() - start
+		});
+	});
+	/**
+	* `GET {@link HEALTH_PATH}` — liveness, and **which build is answering**.
+	*
+	* The path is `worker/health.ts`'s, not a literal here. Three other sites need the same string — the
+	* CLI's route allowlist, `pithy deploy`'s post-deploy probe, and the bare home screen a no-auth
+	* scaffold seeds — and that last one is in somebody else's repository, rendering nothing but this
+	* request's answer (#400).
+	*
+	* The version is what turns `pithy deploy`'s post-deploy check from a liveness probe into an
+	* assertion. `status: "ok"` at the declared domain proves *a* Worker is there; it does not prove it is
+	* the one just shipped, and the old version answering happily is exactly the failure worth catching —
+	* a deploy that landed somewhere else while the declared domain kept serving what was already on it.
+	* With the id here, `deploy` compares what it shipped against what replies.
+	*
+	* **Public, deliberately.** A Cloudflare version id is an opaque UUID carrying no version semantics
+	* and no exploitable detail, and most platforms expose a build identifier. The alternative — reporting
+	* it only through the authenticated control-plane manifest — is better for privacy and useless for
+	* deploy verification, since `deploy` holds no control-plane credential.
+	*
+	* `null` where the binding is absent, which is honest rather than misleading: a project scaffolded
+	* before `version_metadata` was declared reports "I cannot tell you", and `deploy` reports the check
+	* as inconclusive instead of failing it.
+	*/
+	app.get(HEALTH_PATH, (c) => c.json({
+		status: "ok",
+		version: workerVersion(c.env)
+	}));
+	for (const cap of all) for (const middleware of cap.middleware ?? []) middleware(app);
+	for (const cap of all) cap.routes?.(app);
+	return app;
+}
+//#endregion
+export { createBackend };