@pithy-sh/core 0.2.0 → 0.3.0

package/dist/test-utils/oidcFixtures.js

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/test-utils/oidcFixtures.ts
+/**
+* Mint one RSA key pair and publish its public half as a JWK.
+*
+* Real WebCrypto, not a fixture: a hand-rolled key and a hand-rolled signature would let every signature
+* assertion pass by agreeing with itself. A second minted key is what makes "signed by somebody else" a
+* real statement rather than a label — mint one, publish only the first, and the refusal is the verifier's
+* rather than the test's.
+*
+* Key generation is the slow part of any suite using this and a key is immutable, so mint in a
+* `beforeAll` and reuse.
+*/
+async function mintKey(kid) {
+	const pair = await crypto.subtle.generateKey({
+		name: "RSASSA-PKCS1-v1_5",
+		hash: "SHA-256",
+		modulusLength: 2048,
+		publicExponent: new Uint8Array([
+			1,
+			0,
+			1
+		])
+	}, true, ["sign", "verify"]);
+	const exported = await crypto.subtle.exportKey("jwk", pair.publicKey);
+	if (exported.kty === void 0 || exported.n === void 0 || exported.e === void 0) throw new Error("WebCrypto exported an RSA public key with no kty, n, or e.");
+	return {
+		kid,
+		jwk: {
+			...exported,
+			kty: exported.kty,
+			n: exported.n,
+			e: exported.e,
+			kid,
+			alg: "RS256",
+			use: "sig"
+		},
+		privateKey: pair.privateKey
+	};
+}
+/**
+* base64url without padding — how every segment of a compact JWS is encoded.
+*
+* Exported because a test that builds a token by hand needs it: the tamper case swaps a claims segment and
+* keeps the signature, and re-encoding that segment with padding or with `+`/`/` would make the token
+* refused for the wrong reason.
+*/
+function base64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+/**
+* Sign a compact JWT the way an identity provider signs an OIDC token: `RS256`, `typ: "JWT"`, and the
+* signer's `kid` in the header.
+*
+* `payload` is the claims, written as the provider writes them — `iss`, `aud`, `exp`, and whatever the
+* route's `claims` predicate reads. Nothing here defaults a claim, because a fixture that quietly supplied
+* one would be testing itself.
+*
+* `header` overrides let a test present a header no provider would — `alg: "none"`, `alg: "RS512"`, a `kid`
+* nobody published, or `kid: undefined` — which is how a route proves algorithm confusion and an
+* unpublished key are rejected, instead of trusting that the kit covers it somewhere.
+*/
+async function signToken(payload, signer, header = {}) {
+	const encoder = new TextEncoder();
+	const head = base64Url(encoder.encode(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT",
+		kid: signer.kid,
+		...header
+	})));
+	const body = base64Url(encoder.encode(JSON.stringify(payload)));
+	return `${head}.${body}.${base64Url(new Uint8Array(await crypto.subtle.sign("RSASSA-PKCS1-v1_5", signer.privateKey, encoder.encode(`${head}.${body}`))))}`;
+}
+/**
+* A JWKS transport that publishes `keys` at `jwksUrl` and nothing anywhere else, recording every URL it was
+* asked for in `seen`.
+*
+* **The response is the seam's own shape, which is the whole point of shipping this.** `text()`, never
+* `json()` — {@link OidcJwksResponse} reads the body as text deliberately, so a proxy's HTML error page is a
+* diagnosis rather than a throw. A hand-rolled transport that answers `json()` produces a 502 on every
+* delivery from a fixture that looks correct. Typed as {@link OidcJwksFetch}, that mistake will not compile.
+*
+* **The URL is a parameter rather than a wildcard.** A transport that served keys at any URL would pass a
+* route whose configured `jwksUrl` points at nothing — the one configuration mistake a test of a webhook
+* route exists to catch. Anything else gets a 404 with a body, which is what an issuer's CDN actually
+* returns and what the verifier maps to a 502.
+*
+* `seen` is an array the caller owns, so a test can assert the fetch count: one per delivery with no cache,
+* one per TTL with one, and zero when a cache is pre-seeded. Pass `publishing(url, [], seen)` to prove a
+* path never reaches the network at all — an empty key set is refused, so an unexpected fetch fails loudly.
+*/
+function publishing(jwksUrl, keys, seen = []) {
+	return async (url) => {
+		seen.push(url);
+		if (url !== jwksUrl) return {
+			ok: false,
+			status: 404,
+			text: async () => "{}"
+		};
+		return {
+			ok: true,
+			status: 200,
+			text: async () => JSON.stringify({ keys })
+		};
+	};
+}
+//#endregion
+export { base64Url, mintKey, publishing, signToken };

package/dist/version.generated.d.ts

@@ -3,5 +3,5 @@
 /** This package's npm name — the join key against a release feed. */
 export declare const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-export declare const PACKAGE_VERSION = "0.2.0";
+export declare const PACKAGE_VERSION = "0.3.0";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -4,6 +4,6 @@
 /** This package's npm name — the join key against a release feed. */
 const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-const PACKAGE_VERSION = "0.2.0";
+const PACKAGE_VERSION = "0.3.0";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/workflow/naming.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { NAME_SEGMENT } from "../naming/segment.js";
 import { InternalError } from "../error/pithyError.js";
+import { NAME_SEGMENT } from "../naming/segment.js";
 import { NAMESPACE_LIMITS } from "../naming/limits.js";
 import { assertValidProjectName, kebab } from "../naming/resource.js";
 //#region src/workflow/naming.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/capability/bindings.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { FEATURE_RESOURCE_KINDS } from "../naming/feature";
 import { NAME_SEGMENT } from "../naming/segment";
 
 export const BindingType = z
@@ -100,6 +101,19 @@ const CLASS_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
  */
 const CLASS_MODULE = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*(\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)*$/;
 
+/**
+ * The kinds whose resource Pithy names and creates — the only kinds `scope` and `resource` mean anything
+ * for.
+ *
+ * {@link FEATURE_RESOURCE_KINDS} rather than a fresh literal, because it is already the repo's answer to
+ * "which bindings does a provisioning run compose a `<project>-<scope>-<thing>` name for": it is the
+ * domain of `ProvisionScope.resource`, and the CLI's own `PROVISIONABLE` map is the same three. Every
+ * other kind's name is composed by a different rule with no `<thing>` slot to fill — a Workflow's from
+ * the capability and the job, a Worker script's by wrangler — and a `secret` already states its scope in
+ * `defineSecretRegistry`, where the value it names lives.
+ */
+const NAMED_RESOURCE_KINDS = new Set<string>(FEATURE_RESOURCE_KINDS);
+
 /**
  * Declares a Cloudflare binding a capability requires in the Worker env. The authoring
  * shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
@@ -151,6 +165,24 @@ export const BindingSpec = z
       .describe(
         "Reach the real Cloudflare resource during local development instead of a local emulation. Set it for a binding that has none — Vectorize and Workers AI both lack local simulation — so `wrangler dev` and any Workflow host, which always runs locally, still work. Left unset rather than defaulting to false, so a spec that does not care emits no flag at all. Ignored in a deployed Worker.",
       ),
+    scope: z
+      .enum(["environment", "global"])
+      .optional()
+      .describe(
+        "Whether the resource behind this binding is one per environment (absent, the default) or one for the whole project. A `global` resource takes the literal `global` where the environment segment goes — `<project>-global-<thing>` — so every environment's stanza names the identical resource and provisioning creates it once. Declare it where the data is not an environment-local fact: `@pithy-sh/email`'s suppression list is one per project, because an unsubscribe recorded through a staging Worker has to be honored by a production one, and three per-environment databases meant it was not (#513). Say nothing where it is: a session store, a cache, and `@pithy-sh/secrets`' own database are per environment, and one line apart in the same env there is no convention to tell them apart by — which is why this is declared rather than inferred. Meaningful only for a `d1`, `kv` or `r2` binding.",
+      ),
+    resource: z
+      .string()
+      .min(1)
+      // The same rule the composed name answers to, asserted here rather than only where the name is
+      // built: a manifest is third-party data read out of `node_modules`, and this string is the last
+      // segment of a Cloudflare resource name. A manifest stating something a provisioning run would
+      // refuse is refused at parse instead, attributed to the capability, before anything is created.
+      .regex(NAME_SEGMENT, "A resource is one name segment: lowercase letters, digits, and single hyphens.")
+      .optional()
+      .describe(
+        "The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv` or `r2` binding.",
+      ),
   })
   .describe("Declares a Cloudflare binding a capability requires in the Worker env.")
   .check((ctx) => {
@@ -189,6 +221,23 @@ export const BindingSpec = z
         message: `Service binding "${ctx.value.name}" needs a service — the Worker it calls, as named in apps/.`,
       });
     }
+    // `scope` and `resource` are the two halves of a *provisioned resource's name*, and only
+    // {@link NAMED_RESOURCE_KINDS} have one Pithy composes. On anything else they are inert — a Workflow
+    // would keep its `<capability>-<job>` name, a `secret` its registry's scope — so a manifest that
+    // states one is not describing a resource that exists. Refused rather than ignored, and refused here
+    // rather than in the writer, because a silently-dropped `scope: "global"` reads, in the manifest, as
+    // exactly the declaration #513 exists to make true.
+    if (!NAMED_RESOURCE_KINDS.has(ctx.value.type)) {
+      for (const field of ["scope", "resource"] as const) {
+        if (ctx.value[field] === undefined) continue;
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: [field],
+          message: `Binding "${ctx.value.name}" declares a ${field}, which only a d1, kv or r2 binding has — this one is a ${ctx.value.type}.`,
+        });
+      }
+    }
   });
 export type BindingSpec = z.infer<typeof BindingSpec>;
 

package/src/capability/capability.ts

@@ -160,6 +160,34 @@ export interface SecretRegistryEntrySeam {
 /** A capability's secret-registry slice: secret name → {@link SecretRegistryEntrySeam}. */
 export type SecretRegistrySeam = Record<string, SecretRegistryEntrySeam>;
 
+/**
+ * **Which branches of a `json` secret's schema this Worker's configuration actually uses** — secret
+ * name → the top-level keys that apply, in the order they should be offered.
+ *
+ * A `json` secret is often a bundle of independent blocks: `payments-provider-credentials` is five
+ * optional rail blocks, `turnstile-secret-keys` is two optional widgets. The schema says which blocks
+ * are *possible*; only the composed config says which are *real*, and a credential for a rail that is
+ * off is a value nothing will ever read. So `pithy secrets create` asks per field for the blocks named
+ * here, and never offers — never writes — one that is not.
+ *
+ * **It is declared, not matched by name.** `PaymentsRailToggles.paddle` and
+ * `PaymentsProviderCredentials.paddle` happen to be spelled the same today, and a CLI that keyed off
+ * that would be right by coincidence: nothing makes a config flag and a schema key the same thing, and
+ * two of them one line apart cannot be told apart by convention (#513). The capability already knows
+ * the answer at construction — it has both halves in hand — so it states it, and the CLI reads a fact
+ * instead of inferring one.
+ *
+ * **It lives on the capability rather than on the entry** because a registry entry is plain data,
+ * shared by every Worker that declares the name and projected into `pithy.manifest.json`. This answer
+ * is per composition — the same secret, two Workers, two configs — so it belongs where the config is.
+ *
+ * An absent declaration is not an empty one. A capability that says nothing leaves the CLI with no way
+ * to know which blocks apply, and it falls back to asking for the whole document rather than guessing;
+ * an empty array says *none of them apply*, which is the same fallback for a different reason. A
+ * secret whose schema has no branches at all needs no declaration — every field is asked.
+ */
+export type SecretBranchSeam = Record<string, readonly string[]>;
+
 /**
  * The structural seam for one capability's token-profile slice — profile name → the scoped CF API
  * token that capability's code needs. Declared next to the code that uses it (alongside
@@ -298,6 +326,12 @@ export interface Capability<
    * every declared secret in one batch — and no capability needs to know another's secrets.
    */
   secretRegistry?: SecretRegistrySeam;
+  /**
+   * Which branches of this capability's `json` secrets this Worker's configuration uses — see
+   * {@link SecretBranchSeam}. Additive and optional: a capability whose secrets are flat, or which has
+   * no `json` secret at all, declares nothing.
+   */
+  secretBranches?: SecretBranchSeam;
   /**
    * The scoped CF API tokens this capability's code needs, as a token-profile slice (profile name →
    * {@link TokenProfileSeam}). Additive and optional, and declared next to {@link Capability.secretRegistry}

package/src/createBackend.ts

@@ -18,11 +18,11 @@ import { isControlPlaneCapability } from "./controlPlane/capability";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors";
 import { buildDbRegistry, composeDatabases, type DbRegistry } from "./data/databases";
 import { noEntitlementProvider } from "./entitlement/entitlement";
-import { pithyErrorHandler } from "./error/http";
 import { ValidationError } from "./error/pithyError";
 import { catalogFor, composeMessages } from "./i18n/registry";
 import { bakedTranslator, DEFAULT_LOCALE } from "./i18n/translator";
 import { buildKvRegistry, composeKv, type KvRegistry } from "./kv/namespaces";
+import { loggingErrorHandler } from "./logger/errorHandler";
 import type { Logger } from "./logger/logger";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker";
 import { HEALTH_PATH } from "./worker/health";
@@ -111,7 +111,8 @@ function envNameOf(env: Record<string, unknown>, fallback: string | undefined):
  * 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}.
+ * `PithyError`s become their declared HTTP status via {@link loggingErrorHandler}, which also writes
+ * each fault to the request logger with its `action` and `detail` — the fields the wire body strips.
  *
  * 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.
@@ -178,7 +179,10 @@ export function createBackend<
   // Build internally against the loose base env (db/kv are `unknown`, so `c.set` accepts the merged
   // registries); the precise types ride on the return below.
   const app = new Hono<PithyHonoEnv>();
-  app.onError(pithyErrorHandler);
+  // The logging handler, not the bare encoder: a fault's `action` names the var or command an operator
+  // must fix, `clientError` strips it on the way to the wire (correctly), and without this the remedy
+  // reached no surface at all in a deployed Worker — one access log line reading `status: 500` (#521).
+  app.onError(loggingErrorHandler);
 
   // Set once at assembly (the per-request `env` constraint holds: correlation binds per request below,
   // not here). Defaults to the CF-native Mode 2 logger — structured records to Workers Logs, zero-config.

package/src/error/http.ts

@@ -73,20 +73,44 @@ function fromHttpException(error: HTTPException): PithyError | null {
 }
 
 /**
- * Hono `onError` handler. Register once on the root app (`app.onError(pithyErrorHandler)`): any
- * `PithyError` becomes `{ error: <public payload> }` at its declared status; a Hono `HTTPException`
- * 400 becomes `validation/invalid_input`; any other throw is wrapped as a `core/internal` 500
- * carrying the original as `cause` (kept internal) and a generic public message — mirroring the
- * CLI's "unexpected crash" path.
+ * Whatever was thrown, as the `PithyError` the response will be rendered from.
+ *
+ * A `PithyError` is itself; a Hono `HTTPException` 400 becomes `validation/invalid_input`; anything
+ * else is wrapped as a `core/internal` 500 carrying the original as `cause` (kept internal) and a
+ * generic public message — mirroring the CLI's "unexpected crash" path.
+ *
+ * Split out from {@link pithyErrorHandler} so a caller that wants to **read** the fault before it is
+ * encoded — the logging handler in `logger/errorHandler.ts` — works from the same object the response
+ * is built from, rather than translating a second time and logging a different instance of it. The
+ * split is what keeps this module free of the logger: the translation is exported, the log is written
+ * on the other side of the boundary. See `logger/boundary.test.ts`.
  */
-export function pithyErrorHandler(err: Error, c: Context): Response {
+export function toPithyError(err: Error): PithyError {
+  if (err instanceof PithyError) return err;
   const translated = err instanceof HTTPException ? fromHttpException(err) : null;
-  const pithy =
-    err instanceof PithyError
-      ? err
-      : (translated ?? new InternalError({ detail: err instanceof Error ? err.message : String(err) }, { cause: err }));
+  return translated ?? new InternalError({ detail: err instanceof Error ? err.message : String(err) }, { cause: err });
+}
+
+/** Render an already-translated fault as its HTTP response — the client half, and only that. */
+export function renderPithyError(pithy: PithyError, c: Context): Response {
   // A kit member pins a literal status; an adopter's carries a `number` the schema has already
   // bounded to 400–599. Hono types the argument as its own literal union, and that is the one gap
   // between the two — the value is validated, so the assertion narrows rather than trusts.
   return c.json({ error: HttpError.encode(pithy.payload) }, pithy.payload.status as ContentfulStatusCode);
 }
+
+/**
+ * Hono `onError` handler — the **encoder**, with no log of its own.
+ *
+ * Any `PithyError` becomes `{ error: <public payload> }` at its declared status; a Hono
+ * `HTTPException` 400 becomes `validation/invalid_input`; any other throw is wrapped as a
+ * `core/internal` 500.
+ *
+ * **Prefer `loggingErrorHandler` from `logger/errorHandler.ts`** — `createBackend` registers that one,
+ * and it is what makes a misconfiguration's `action` reach an operator instead of dying at the wire
+ * (#521). This one stays exported for an app assembled without the logger seam, and it stays here,
+ * logger-free, because this module is on the client side of the logger boundary.
+ */
+export function pithyErrorHandler(err: Error, c: Context): Response {
+  return renderPithyError(toPithyError(err), c);
+}