@pithy-sh/core 0.1.1 → 0.1.3

package/dist/http/sameOrigin.js

@@ -0,0 +1,24 @@
+import { ForbiddenError } from "../error/pithyError.js";
+//#region src/http/sameOrigin.ts
+/**
+* Require this request to come from an origin the Worker trusts — the CSRF gate a cookie-authenticated
+* mutating route wears, beside the strategy that says who the caller is.
+*
+*   app.post("/organizations", requireAuth(), requireSameOrigin(), zValidator(…), handler)
+*
+* A bearer request carries no ambient credential and is CSRF-exempt; that exemption belongs to the
+* published gate, since the capability that owns the credential model is the one that knows.
+*/
+function requireSameOrigin() {
+	return async (c, next) => {
+		const gate = c.var.sameOrigin;
+		if (!gate) throw new ForbiddenError({
+			message: "Cross-origin request rejected.",
+			action: "Compose a capability that resolves this Worker's trusted origins (auth), then retry.",
+			detail: "no same-origin policy on the request — no composed capability published one"
+		});
+		return await gate(c, next);
+	};
+}
+//#endregion
+export { requireSameOrigin };

package/dist/http/signedWebhook.d.ts

@@ -0,0 +1,225 @@
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+/**
+ * The `signed-webhook` strategy, for any sender. Secret, header name, tolerance and the exact received
+ * bytes in; verified, or a `PithyError`, out.
+ *
+ * `signed-webhook` has been a first-class strategy in {@link ./verification.VerificationStrategy} since the
+ * contract landed, but the only implementation was `@pithy-sh/payments`' webhook guard — welded to a rail
+ * catalog, a D1 table and a dedup insert, because it also records deliveries. So an adopter declaring the
+ * strategy on their own route had the word and nothing to put behind it. This is the word's implementation,
+ * and `@pithy-sh/payments`' Stripe rail is now one of its callers rather than a second copy of it.
+ *
+ * **Dedup and persistence stay the caller's**: at-least-once delivery is a property of the sender, not of the
+ * signature, and a verifier that also owned a table could not be composed by anyone whose table differs. Say
+ * the consequence plainly, because it is a security property and not only an availability one: this proves a
+ * delivery is authentic and fresh, never that it is *new*. Inside the tolerance a captured delivery replays
+ * as many times as it is sent. A handler that grants, charges, or deletes needs its own uniqueness key —
+ * payments spends a `UNIQUE (rail, providerEventId)` insert on exactly this.
+ *
+ * ## The scheme
+ *
+ * One header carries both halves of the proof: `<header>: t=1785931200,v1=5257a8…` — the timestamp the
+ * delivery claims, then one hex HMAC-SHA256 per signature, each computed over `<timestamp>.<body>`. Stripe's
+ * format, deliberately, because it is the one every other sender copied and because it gets the four things
+ * below right. The key names are options — a sender writing `v0` costs one line — but the signed payload is
+ * fixed. A caller-supplied template would be the one part of the scheme that must be byte-identical at both
+ * ends, and getting it wrong yields a verifier that verifies nothing while still returning.
+ *
+ * ## Why the timestamp is inside the signed payload
+ *
+ * A signature with no freshness window is valid forever: whoever captures one delivery can replay it for as
+ * long as the secret lives. The window only closes that if it cannot be stepped around — and it cannot,
+ * because the timestamp is part of what was signed. Re-dating a captured delivery to escape the window
+ * invalidates its own signature. A timestamp in a second header, or alongside the signature but outside it,
+ * would be a suggestion.
+ *
+ * The window is checked in **both** directions. A delivery dated far in the future is a clock problem or a
+ * crafted one, and neither is a delivery to act on; accepting it would also hand a forger an unbounded replay
+ * window the moment a secret leaks.
+ *
+ * ## Why the comparison is `crypto.subtle.verify`
+ *
+ * Comparing HMACs with `===` leaks how many leading bytes matched, and that leak is enough to forge a
+ * signature one byte at a time given enough attempts. WebCrypto's `verify` does the comparison itself, in
+ * constant time, in the platform — so the requirement is met by not hand-writing the compare at all.
+ * (`timingSafeEqual` in `../controlPlane/token/digest` is the string equivalent, for values WebCrypto will
+ * not compare for you.) Every listed signature is tried, because a sender rotating its secret signs with each
+ * active one, and refusing a delivery whose second signature matched would drop every delivery for the length
+ * of the rotation.
+ *
+ * ## What a refusal says
+ *
+ * `core/webhook_unverified`, 401, one code for every failing step. The step goes in `detail`, which the HTTP
+ * codec strips — so an operator reading a log learns which check refused it and the sender learns only that
+ * something did. **Never the secret, never a signature, never the body.** A refusal is the one message a
+ * hostile caller is guaranteed to receive, so it is the last place to echo anything it supplied or anything
+ * it is trying to guess.
+ *
+ * A caller that must word its own refusal — a rail whose own code is part of its contract — calls
+ * {@link checkSignedWebhook}, which reports rather than throws. {@link verifySignedWebhook} is that plus the
+ * kit's error.
+ */
+/** How far a delivery's own timestamp may be from now. Stripe's default, and generous against clock skew. */
+export declare const SIGNED_WEBHOOK_TOLERANCE_SECONDS = 300;
+/**
+ * How many candidate signatures one delivery may spend, after the unusable ones are dropped.
+ *
+ * The list is written by whoever sent the request, and every entry on it costs a full HMAC over the whole
+ * body, once per configured secret. Uncapped, a 16 KiB header holds a few hundred well-formed candidates and
+ * one anonymous POST buys hundreds of times the CPU a real delivery does — billed CPU, on a runtime with a
+ * burst limit. A sender rotating its secret lists two, occasionally three. Eight is far past generous and
+ * turns an unbounded multiplier into a constant.
+ */
+export declare const SIGNED_WEBHOOK_MAX_CANDIDATES = 8;
+/** What the two ends of the scheme must agree on, beyond the secret. */
+export interface SignedWebhookScheme {
+    /**
+     * The header carrying the proof, lower case — that is how Hono presents a header name. Required and
+     * never defaulted: a default would be a header some sender happens not to use, read silently.
+     */
+    header: string;
+    /** The header key holding the timestamp. Defaults to `t`. */
+    timestampKey?: string;
+    /** The header key holding a signature. Defaults to `v1`. */
+    signatureKey?: string;
+    /** The freshness window, in seconds, either side of now. Defaults to {@link SIGNED_WEBHOOK_TOLERANCE_SECONDS}. */
+    toleranceSeconds?: number;
+}
+/**
+ * The secret(s) this endpoint accepts. An array is the receiver's own rotation overlap: both the outgoing and
+ * the incoming secret verify until the sender is switched over. `secretsStore(…).getVersions(NAME)` is what
+ * feeds it, through `Object.values(secret.versions)` — it returns `{ currentVersion, versions }`, not an array,
+ * and only a `valueType: "text"` secret yields strings to pass here. (The sender's rotation is the other
+ * axis — several signatures in one header — and needs nothing from the caller.)
+ *
+ * An entry that resolved to nothing is dropped rather than tried: a blank version is a configuration fault,
+ * and WebCrypto refuses a zero-length key with a `DOMException` that would otherwise escape as a 500 whose
+ * text names nothing. An endpoint left with no usable secret is reported as the configuration fault it is.
+ */
+export type SignedWebhookSecret = string | readonly string[];
+/** Everything {@link verifySignedWebhook} needs beyond the bytes and the header value. */
+export interface VerifySignedWebhookOptions extends SignedWebhookScheme {
+    /** The signing secret, or every secret still honored during a rotation. */
+    secret: SignedWebhookSecret;
+    /** The clock. Injectable so the freshness window is deterministic in tests rather than wall-clock dependent. */
+    now?: Date;
+}
+/** Everything {@link requireSignedWebhook} needs, as a route wears it. */
+export interface SignedWebhookGuardOptions extends SignedWebhookScheme {
+    /**
+     * The secret, or a resolver reading it from the Worker env at the point of need. A guard is built at
+     * module scope and `env` only exists per request, so a secret read through `@pithy-sh/secrets` can only
+     * arrive as the second form — and reading it per request is also what makes a rotation take effect
+     * without a deploy.
+     */
+    secret: SignedWebhookSecret | ((env: Record<string, unknown>) => SignedWebhookSecret | Promise<SignedWebhookSecret>);
+    /** The clock, for the freshness window. Injected so tests are deterministic. */
+    now?: () => Date;
+}
+/** A parsed proof header: when the delivery says it was signed, and with what. */
+export interface SignedWebhookHeader {
+    /** The timestamp value, in seconds since the epoch. Part of the signed payload as well as of the header. */
+    timestamp: number;
+    /** Every signature value, in the order listed. One per secret the sender currently signs with. */
+    signatures: readonly string[];
+}
+/**
+ * Read a proof header, or `undefined` when it is not one.
+ *
+ * Undefined rather than a throw per unreadable shape, because the caller turns them all into one refusal:
+ * distinguishing "no timestamp" from "no signature" would describe our parser to a sender, and neither is
+ * actionable by anyone but an operator reading the endpoint's configuration.
+ *
+ * Unknown keys are dropped rather than refused. A sender may list a scheme this build does not know — Stripe
+ * sends `v0` beside `v1` — and a delivery whose known signature is good is authentic whatever else it
+ * carries. A header carrying *only* unknown keys has proved nothing, so it yields undefined.
+ *
+ * The timestamp is the exception: it is read strictly, once, and only in the exact spelling it was signed in.
+ * Two of them is a header that has not said when it was signed, and taking the last is how a parser and a
+ * sender come to disagree about what was covered. A non-canonical one (`00178…`) could never verify either,
+ * because the bytes signed are the digits the sender wrote — refusing it here names the digit rather than
+ * sending an operator after a rotated secret.
+ */
+export declare function parseSignedWebhookHeader(header: string, timestampKey: string, signatureKey: string): SignedWebhookHeader | undefined;
+/**
+ * Why a delivery did not verify, for a caller that words its own refusal.
+ *
+ * Three reasons, because there are three checks. They are for the caller's `detail` and an operator's log,
+ * never for the response body: a sender that learns which check refused it learns how close it got.
+ */
+export type SignedWebhookRefusal = 
+/** No header, or one carrying no timestamp and signature this scheme can read. */
+{
+    reason: "unreadable";
+}
+/** Read, but dated outside the freshness window — a clock, or a replay. */
+ | {
+    reason: "stale";
+    skew: number;
+    tolerance: number;
+}
+/**
+ * Read and fresh, and nothing in it verified.
+ *
+ * `compared` is how many listed values were actually put to a secret — the candidates left after the ones
+ * that cannot be an HMAC-SHA256 are dropped and the cap is applied. Zero is a different finding from the
+ * rest: no comparison ran at all, so the answer is the sender's signature format, not the endpoint's
+ * secret. A refusal that does not carry the number cannot tell an operator which of the two it is.
+ */
+ | {
+    reason: "unmatched";
+    compared: number;
+};
+/**
+ * Check one delivery, and **report** rather than throw: `undefined` when a holder of the secret signed these
+ * exact bytes inside the window, a {@link SignedWebhookRefusal} when nobody did.
+ *
+ * This is the seam a rail composes. `@pithy-sh/payments` must keep raising `payments/verification_failed`
+ * with its own Stripe-worded `detail`, and that is a contract of its own — so the scheme lives here once and
+ * each caller keeps its vocabulary, rather than the whole verifier existing twice with two sets of comments
+ * to keep in step. Most callers want {@link verifySignedWebhook}.
+ *
+ * It still throws for **our** failure: an endpoint holding no usable secret, or handed a clock that is not a
+ * clock, is a configuration fault rather than a refusal, and every caller reports that the same way.
+ *
+ * `body` must be the **exact received bytes**. A parsed-and-re-serialized object is different bytes — key
+ * order alone changes it — and would never verify.
+ */
+export declare function checkSignedWebhook(body: string, header: string | null, options: VerifySignedWebhookOptions): Promise<SignedWebhookRefusal | undefined>;
+/**
+ * Verify one delivery. Resolves when a holder of the secret signed these exact bytes inside the window, and
+ * throws `core/webhook_unverified` otherwise.
+ */
+export declare function verifySignedWebhook(body: string, header: string | null, options: VerifySignedWebhookOptions): Promise<void>;
+/**
+ * The `signed-webhook` gate, as a route wears it: `app.post(path, requireSignedWebhook({…}), zValidator("json",
+ * Body, validationHook), handler)`.
+ *
+ * ## Why the header is read before anything else
+ *
+ * The proof header is the cheapest thing to check and the commonest thing to be missing, so it is checked
+ * first. A delivery carrying no readable one is refused whatever the body holds — so resolving the secret (a
+ * D1 read and a decrypt) and buffering the body before looking would be unauthenticated work bought by an
+ * anonymous POST, on the one route whose whole purpose is to refuse unauthenticated callers.
+ *
+ * The header is then parsed a second time inside the full check rather than threaded through it. Parsing a
+ * short header twice costs nothing; two entry points into the verification, one of them holding a
+ * half-verified state, would cost the property that there is exactly one way through this scheme.
+ *
+ * One consequence, and it is the right one: an endpoint whose secret never resolved answers a proof-less POST
+ * with the same 401 every other endpoint gives it, and reports the configuration fault to the first delivery
+ * that actually carries a proof. A caller with nothing to verify learns nothing about our configuration.
+ *
+ * ## Why it reads the body itself, and with `c.req.text()`
+ *
+ * The proof covers the exact received bytes, so the gate must see what arrived rather than a reconstruction.
+ * That is the sanctioned use the Biome plugin leaves open under `src/http/**`: `c.req.json()` is banned,
+ * `c.req.text()` is not.
+ *
+ * `c.req.text()` rather than `c.req.raw.text()`, and the distinction is load-bearing. Hono caches its own
+ * body reads and serves `c.req.json()` out of the cached text, so a `zValidator("json", …)` after this gate
+ * parses identical bytes. Reading `c.req.raw` would consume the stream and leave the validator with nothing.
+ */
+export declare function requireSignedWebhook(options: SignedWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=signedWebhook.d.ts.map

package/dist/http/signedWebhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signedWebhook.d.ts","sourceRoot":"","sources":["../../src/http/signedWebhook.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAcpD;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kHAAkH;IAClH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,WAAW,0BAA2B,SAAQ,mBAAmB;IACrE,2EAA2E;IAC3E,MAAM,EAAE,mBAAmB,CAAC;IAC5B,gHAAgH;IAChH,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,0EAA0E;AAC1E,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE;;;;;OAKG;IACH,MAAM,EAAE,mBAAmB,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACrH,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,4GAA4G;IAC5G,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,mBAAmB,GAAG,SAAS,CAuBjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB;AAC9B,kFAAkF;AAChF;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE;AAC1B,2EAA2E;GACzE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AACtD;;;;;;;GAOG;GACD;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAkE3C;AAkCD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,yBAAyB,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAyBxG"}

package/dist/http/signedWebhook.js

@@ -0,0 +1,247 @@
+import { InternalError, WebhookUnverifiedError } from "../error/pithyError.js";
+//#region src/http/signedWebhook.ts
+/**
+* The `signed-webhook` strategy, for any sender. Secret, header name, tolerance and the exact received
+* bytes in; verified, or a `PithyError`, out.
+*
+* `signed-webhook` has been a first-class strategy in {@link ./verification.VerificationStrategy} since the
+* contract landed, but the only implementation was `@pithy-sh/payments`' webhook guard — welded to a rail
+* catalog, a D1 table and a dedup insert, because it also records deliveries. So an adopter declaring the
+* strategy on their own route had the word and nothing to put behind it. This is the word's implementation,
+* and `@pithy-sh/payments`' Stripe rail is now one of its callers rather than a second copy of it.
+*
+* **Dedup and persistence stay the caller's**: at-least-once delivery is a property of the sender, not of the
+* signature, and a verifier that also owned a table could not be composed by anyone whose table differs. Say
+* the consequence plainly, because it is a security property and not only an availability one: this proves a
+* delivery is authentic and fresh, never that it is *new*. Inside the tolerance a captured delivery replays
+* as many times as it is sent. A handler that grants, charges, or deletes needs its own uniqueness key —
+* payments spends a `UNIQUE (rail, providerEventId)` insert on exactly this.
+*
+* ## The scheme
+*
+* One header carries both halves of the proof: `<header>: t=1785931200,v1=5257a8…` — the timestamp the
+* delivery claims, then one hex HMAC-SHA256 per signature, each computed over `<timestamp>.<body>`. Stripe's
+* format, deliberately, because it is the one every other sender copied and because it gets the four things
+* below right. The key names are options — a sender writing `v0` costs one line — but the signed payload is
+* fixed. A caller-supplied template would be the one part of the scheme that must be byte-identical at both
+* ends, and getting it wrong yields a verifier that verifies nothing while still returning.
+*
+* ## Why the timestamp is inside the signed payload
+*
+* A signature with no freshness window is valid forever: whoever captures one delivery can replay it for as
+* long as the secret lives. The window only closes that if it cannot be stepped around — and it cannot,
+* because the timestamp is part of what was signed. Re-dating a captured delivery to escape the window
+* invalidates its own signature. A timestamp in a second header, or alongside the signature but outside it,
+* would be a suggestion.
+*
+* The window is checked in **both** directions. A delivery dated far in the future is a clock problem or a
+* crafted one, and neither is a delivery to act on; accepting it would also hand a forger an unbounded replay
+* window the moment a secret leaks.
+*
+* ## Why the comparison is `crypto.subtle.verify`
+*
+* Comparing HMACs with `===` leaks how many leading bytes matched, and that leak is enough to forge a
+* signature one byte at a time given enough attempts. WebCrypto's `verify` does the comparison itself, in
+* constant time, in the platform — so the requirement is met by not hand-writing the compare at all.
+* (`timingSafeEqual` in `../controlPlane/token/digest` is the string equivalent, for values WebCrypto will
+* not compare for you.) Every listed signature is tried, because a sender rotating its secret signs with each
+* active one, and refusing a delivery whose second signature matched would drop every delivery for the length
+* of the rotation.
+*
+* ## What a refusal says
+*
+* `core/webhook_unverified`, 401, one code for every failing step. The step goes in `detail`, which the HTTP
+* codec strips — so an operator reading a log learns which check refused it and the sender learns only that
+* something did. **Never the secret, never a signature, never the body.** A refusal is the one message a
+* hostile caller is guaranteed to receive, so it is the last place to echo anything it supplied or anything
+* it is trying to guess.
+*
+* A caller that must word its own refusal — a rail whose own code is part of its contract — calls
+* {@link checkSignedWebhook}, which reports rather than throws. {@link verifySignedWebhook} is that plus the
+* kit's error.
+*/
+/** How far a delivery's own timestamp may be from now. Stripe's default, and generous against clock skew. */
+const SIGNED_WEBHOOK_TOLERANCE_SECONDS = 300;
+/** The header key naming the timestamp, unless a sender names it otherwise. */
+const DEFAULT_TIMESTAMP_KEY = "t";
+/** The header key naming a signature, unless a sender names it otherwise. */
+const DEFAULT_SIGNATURE_KEY = "v1";
+/** HMAC-SHA256 — the algorithm this scheme is. Pinned as a literal, never read from the delivery. */
+const HMAC_SHA256 = {
+	name: "HMAC",
+	hash: "SHA-256"
+};
+/** The byte length of an HMAC-SHA256 signature. A candidate of any other length cannot be one. */
+const SIGNATURE_BYTES = 32;
+/**
+* How many candidate signatures one delivery may spend, after the unusable ones are dropped.
+*
+* The list is written by whoever sent the request, and every entry on it costs a full HMAC over the whole
+* body, once per configured secret. Uncapped, a 16 KiB header holds a few hundred well-formed candidates and
+* one anonymous POST buys hundreds of times the CPU a real delivery does — billed CPU, on a runtime with a
+* burst limit. A sender rotating its secret lists two, occasionally three. Eight is far past generous and
+* turns an unbounded multiplier into a constant.
+*/
+const SIGNED_WEBHOOK_MAX_CANDIDATES = 8;
+/**
+* Read a proof header, or `undefined` when it is not one.
+*
+* Undefined rather than a throw per unreadable shape, because the caller turns them all into one refusal:
+* distinguishing "no timestamp" from "no signature" would describe our parser to a sender, and neither is
+* actionable by anyone but an operator reading the endpoint's configuration.
+*
+* Unknown keys are dropped rather than refused. A sender may list a scheme this build does not know — Stripe
+* sends `v0` beside `v1` — and a delivery whose known signature is good is authentic whatever else it
+* carries. A header carrying *only* unknown keys has proved nothing, so it yields undefined.
+*
+* The timestamp is the exception: it is read strictly, once, and only in the exact spelling it was signed in.
+* Two of them is a header that has not said when it was signed, and taking the last is how a parser and a
+* sender come to disagree about what was covered. A non-canonical one (`00178…`) could never verify either,
+* because the bytes signed are the digits the sender wrote — refusing it here names the digit rather than
+* sending an operator after a rotated secret.
+*/
+function parseSignedWebhookHeader(header, timestampKey, signatureKey) {
+	let timestamp;
+	const signatures = [];
+	for (const part of header.split(",")) {
+		const separator = part.indexOf("=");
+		if (separator < 0) continue;
+		const key = part.slice(0, separator).trim();
+		const value = part.slice(separator + 1).trim();
+		if (key === timestampKey) {
+			if (timestamp !== void 0 || !/^(?:0|[1-9]\d*)$/.test(value)) return void 0;
+			timestamp = Number(value);
+		} else if (key === signatureKey) signatures.push(value);
+	}
+	if (timestamp === void 0 || signatures.length === 0) return void 0;
+	return {
+		timestamp,
+		signatures
+	};
+}
+/**
+* Check one delivery, and **report** rather than throw: `undefined` when a holder of the secret signed these
+* exact bytes inside the window, a {@link SignedWebhookRefusal} when nobody did.
+*
+* This is the seam a rail composes. `@pithy-sh/payments` must keep raising `payments/verification_failed`
+* with its own Stripe-worded `detail`, and that is a contract of its own — so the scheme lives here once and
+* each caller keeps its vocabulary, rather than the whole verifier existing twice with two sets of comments
+* to keep in step. Most callers want {@link verifySignedWebhook}.
+*
+* It still throws for **our** failure: an endpoint holding no usable secret, or handed a clock that is not a
+* clock, is a configuration fault rather than a refusal, and every caller reports that the same way.
+*
+* `body` must be the **exact received bytes**. A parsed-and-re-serialized object is different bytes — key
+* order alone changes it — and would never verify.
+*/
+async function checkSignedWebhook(body, header, options) {
+	const secrets = (typeof options.secret === "string" ? [options.secret] : options.secret).filter((secret) => secret.length > 0);
+	if (secrets.length === 0) throw new InternalError({
+		message: "This webhook endpoint is not configured.",
+		action: `Give the ${options.header} guard a signing secret.`,
+		detail: `The signed-webhook guard on ${options.header} resolved no signing secret, so it can verify nothing.`
+	});
+	const timestampKey = options.timestampKey ?? DEFAULT_TIMESTAMP_KEY;
+	const signatureKey = options.signatureKey ?? DEFAULT_SIGNATURE_KEY;
+	const parsed = header === null ? void 0 : parseSignedWebhookHeader(header, timestampKey, signatureKey);
+	if (parsed === void 0) return { reason: "unreadable" };
+	const tolerance = options.toleranceSeconds ?? 300;
+	const nowSeconds = Math.floor((options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	if (!Number.isFinite(nowSeconds)) throw new InternalError({
+		message: "This webhook endpoint is not configured.",
+		action: `Give the ${options.header} guard a valid clock.`,
+		detail: `The signed-webhook guard on ${options.header} was handed a clock that is not a valid Date, so no delivery's freshness can be judged.`
+	});
+	const skew = Math.abs(nowSeconds - parsed.timestamp);
+	if (skew > tolerance) return {
+		reason: "stale",
+		skew,
+		tolerance
+	};
+	const signed = new TextEncoder().encode(`${parsed.timestamp}.${body}`);
+	const candidates = parsed.signatures.map(hexBytes).filter((bytes) => bytes !== void 0 && bytes.length === SIGNATURE_BYTES).slice(0, 8);
+	for (const secret of secrets) {
+		const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), HMAC_SHA256, false, ["verify"]);
+		for (const candidate of candidates) if (await crypto.subtle.verify(HMAC_SHA256.name, key, candidate, signed)) return;
+	}
+	return {
+		reason: "unmatched",
+		compared: candidates.length
+	};
+}
+/**
+* The kit's wording for each refusal, in one place — so the guard's early exit says exactly what the full
+* check would have said, rather than a second sentence about the same finding.
+*
+* Every string states what was actually determined and nothing more. `detail` is what an operator reads to
+* decide where to look, and a refusal that asserts a comparison it never ran sends them somewhere else.
+*/
+function webhookRefusal(refusal, scheme) {
+	const timestampKey = scheme.timestampKey ?? DEFAULT_TIMESTAMP_KEY;
+	const signatureKey = scheme.signatureKey ?? DEFAULT_SIGNATURE_KEY;
+	switch (refusal.reason) {
+		case "unreadable": return new WebhookUnverifiedError({ detail: `The delivery carries no readable ${scheme.header} header with a ${timestampKey}= timestamp and a ${signatureKey}= HMAC.` });
+		case "stale": return new WebhookUnverifiedError({ detail: `The delivery is dated ${refusal.skew}s from now, outside the ${refusal.tolerance}s tolerance. Check this Worker's clock, or a replayed delivery.` });
+		case "unmatched": return new WebhookUnverifiedError({ detail: refusal.compared === 0 ? `No ${signatureKey}= value in the ${scheme.header} header is 32 bytes of hex, so no signature was compared. Check the sender's signature format.` : `Compared ${refusal.compared} signature${refusal.compared === 1 ? "" : "s"} from the ${scheme.header} header against every configured signing secret; none matches these bytes. Check that the secret belongs to this endpoint and this environment.` });
+	}
+}
+/**
+* Verify one delivery. Resolves when a holder of the secret signed these exact bytes inside the window, and
+* throws `core/webhook_unverified` otherwise.
+*/
+async function verifySignedWebhook(body, header, options) {
+	const refusal = await checkSignedWebhook(body, header, options);
+	if (refusal !== void 0) throw webhookRefusal(refusal, options);
+}
+/**
+* The `signed-webhook` gate, as a route wears it: `app.post(path, requireSignedWebhook({…}), zValidator("json",
+* Body, validationHook), handler)`.
+*
+* ## Why the header is read before anything else
+*
+* The proof header is the cheapest thing to check and the commonest thing to be missing, so it is checked
+* first. A delivery carrying no readable one is refused whatever the body holds — so resolving the secret (a
+* D1 read and a decrypt) and buffering the body before looking would be unauthenticated work bought by an
+* anonymous POST, on the one route whose whole purpose is to refuse unauthenticated callers.
+*
+* The header is then parsed a second time inside the full check rather than threaded through it. Parsing a
+* short header twice costs nothing; two entry points into the verification, one of them holding a
+* half-verified state, would cost the property that there is exactly one way through this scheme.
+*
+* One consequence, and it is the right one: an endpoint whose secret never resolved answers a proof-less POST
+* with the same 401 every other endpoint gives it, and reports the configuration fault to the first delivery
+* that actually carries a proof. A caller with nothing to verify learns nothing about our configuration.
+*
+* ## Why it reads the body itself, and with `c.req.text()`
+*
+* The proof covers the exact received bytes, so the gate must see what arrived rather than a reconstruction.
+* That is the sanctioned use the Biome plugin leaves open under `src/http/**`: `c.req.json()` is banned,
+* `c.req.text()` is not.
+*
+* `c.req.text()` rather than `c.req.raw.text()`, and the distinction is load-bearing. Hono caches its own
+* body reads and serves `c.req.json()` out of the cached text, so a `zValidator("json", …)` after this gate
+* parses identical bytes. Reading `c.req.raw` would consume the stream and leave the validator with nothing.
+*/
+function requireSignedWebhook(options) {
+	return async (c, next) => {
+		const { secret: declared, now, ...scheme } = options;
+		const proof = c.req.header(scheme.header) ?? null;
+		if (!(proof !== null && parseSignedWebhookHeader(proof, scheme.timestampKey ?? DEFAULT_TIMESTAMP_KEY, scheme.signatureKey ?? DEFAULT_SIGNATURE_KEY) !== void 0)) throw webhookRefusal({ reason: "unreadable" }, scheme);
+		const secret = typeof declared === "function" ? await declared(c.env) : declared;
+		await verifySignedWebhook(await c.req.text(), proof, {
+			...scheme,
+			secret,
+			now: now?.() ?? /* @__PURE__ */ new Date()
+		});
+		await next();
+	};
+}
+/** Decode lower- or upper-case hex, or `undefined` when it is not hex at all. */
+function hexBytes(value) {
+	if (value.length === 0 || value.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(value)) return void 0;
+	const bytes = new Uint8Array(value.length / 2);
+	for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+	return bytes;
+}
+//#endregion
+export { SIGNED_WEBHOOK_MAX_CANDIDATES, SIGNED_WEBHOOK_TOLERANCE_SECONDS, checkSignedWebhook, parseSignedWebhookHeader, requireSignedWebhook, verifySignedWebhook };

package/dist/http/validation.d.ts

@@ -0,0 +1,37 @@
+import type { z } from "zod";
+/**
+ * How a route declares what it accepts. Its sibling {@link ./verification.VerificationStrategy}
+ * declares how a caller is verified; this declares the shape the caller may send. Both are
+ * mandatory, and both belong on the route line — reading a route tells you what it takes without
+ * opening the handler.
+ *
+ * Routes use `zValidator(target, Schema, validationHook)` from `@hono/zod-validator`. The library
+ * owns the middleware and the `c.req.valid(target)` typing; this file owns exactly one thing —
+ * what happens when the parse fails. Without the hook, zod-validator answers with its own JSON
+ * body, which is neither a `PithyError` payload nor routed through `pithyErrorHandler`. With it,
+ * a malformed request is indistinguishable from every other failure the app can produce.
+ *
+ * The hook is deliberately not a wrapper around `zValidator`. A wrapper would be a second name for
+ * a library we do not re-export (CLAUDE.md §Toolchain), and it would hide the target from the route
+ * line — the one thing the migration exists to make visible.
+ */
+/**
+ * The outcome `@hono/zod-validator` hands a hook. Declared structurally rather than by importing
+ * the library's `Hook` generic: `Hook` is parameterized by env, path, target and schema, so a
+ * single shared hook value could not name it without pinning all four. Every real outcome is
+ * assignable to this.
+ */
+export type ValidationOutcome = {
+    success: true;
+} | {
+    success: false;
+    error: z.core.$ZodError;
+};
+/**
+ * The one validation-failure hook every provided route passes to `zValidator`. Maps the `ZodError`
+ * through `fromZodError`, so the client sees the same `validation/invalid_input` 400 with the same
+ * `issues[]` that the hand-rolled parse helpers produced before — the migration changes where
+ * validation is declared, not what a caller sees when it fails.
+ */
+export declare function validationHook(outcome: ValidationOutcome): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/http/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/http/validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,SAAS,CAAA;CAAE,CAAC;AAEhG;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAG/D"}

package/dist/http/validation.js

@@ -0,0 +1,14 @@
+import { fromZodError } from "../error/pithyError.js";
+//#region src/http/validation.ts
+/**
+* The one validation-failure hook every provided route passes to `zValidator`. Maps the `ZodError`
+* through `fromZodError`, so the client sees the same `validation/invalid_input` 400 with the same
+* `issues[]` that the hand-rolled parse helpers produced before — the migration changes where
+* validation is declared, not what a caller sees when it fails.
+*/
+function validationHook(outcome) {
+	if (outcome.success) return;
+	throw fromZodError(outcome.error);
+}
+//#endregion
+export { validationHook };

package/dist/http/verification.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/**
+ * How a route verifies the caller's identity/authenticity. Every route declares one —
+ * there is no implicit auth. `@pithy-sh/auth` implements `bearer`/`session`; others map to
+ * their own checks. (Turnstile is a humanity check applied as middleware, not an identity
+ * strategy, so it is deliberately not listed here.)
+ */
+export declare const VerificationStrategy: z.ZodUnion<readonly [z.ZodLiteral<"bearer">, z.ZodLiteral<"session">, z.ZodLiteral<"signed-webhook">, z.ZodLiteral<"control-plane">, z.ZodLiteral<"public">]>;
+export type VerificationStrategy = z.infer<typeof VerificationStrategy>;
+//# sourceMappingURL=verification.d.ts.map

package/dist/http/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../../src/http/verification.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,+JAYiE,CAAC;AACnG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/http/verification.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+//#region src/http/verification.ts
+/**
+* How a route verifies the caller's identity/authenticity. Every route declares one —
+* there is no implicit auth. `@pithy-sh/auth` implements `bearer`/`session`; others map to
+* their own checks. (Turnstile is a humanity check applied as middleware, not an identity
+* strategy, so it is deliberately not listed here.)
+*/
+const VerificationStrategy = z.union([
+	z.literal("bearer").describe("Short-lived access token via Authorization: Bearer; validated by @pithy-sh/auth."),
+	z.literal("session").describe("Cookie-based web session, CSRF-protected; validated by @pithy-sh/auth."),
+	z.literal("signed-webhook").describe("Inbound webhook, authenticated by the sender's own proof over the exact received bytes — one name over several mechanisms (an HMAC, a signed JWS chain, an OIDC token), because the sender chooses it. `requireSignedWebhook` (./signedWebhook) implements the timestamped-HMAC form; a rail whose sender proves it differently implements its own."),
+	z.literal("control-plane").describe("M2M admin via a customer-issued scoped credential; default-denied."),
+	z.literal("public").describe("No authentication — the route is open. Must be a deliberate choice.")
+]).describe("How a route verifies the caller's identity/authenticity. There is no implicit auth.");
+//#endregion
+export { VerificationStrategy };

package/dist/i18n/acceptLanguage.d.ts

@@ -0,0 +1,22 @@
+/** One entry of an `Accept-Language` header: the tag the caller asked for, and how much they meant it. */
+export interface LanguageRange {
+    /** The language range, lower-cased. `*` survives as itself — it is a valid range, not a tag. */
+    readonly range: string;
+    /** The entry's q-weight, `0` through `1`. Absent weights are `1`, per RFC 9110. */
+    readonly quality: number;
+}
+/**
+ * An `Accept-Language` header as q-weighted ranges, most-wanted first.
+ *
+ * **Tokenize, strip q-weights, then validate — in that order, and all of it before anything reaches
+ * `Intl`.** The header is caller-supplied and its real-world contents include `*`, `en_US`, empty
+ * tokens, and tags still carrying `;q=0.9`; `new Intl.Locale()` throws a `RangeError` on every one of
+ * them. A header that cannot be read is an empty list, never a throw, so the resolver chain falls
+ * through to its next link instead of 500-ing.
+ *
+ * The **full** weighted list is returned, not the first entry: `pt-PT;q=1.0, es;q=0.8, en;q=0.5` from a
+ * reader who has no Portuguese is a request for Spanish, and reading only the head answers English.
+ * Equal weights keep header order, which is what a browser means by listing them that way.
+ */
+export declare function parseAcceptLanguage(header: string | null | undefined): LanguageRange[];
+//# sourceMappingURL=acceptLanguage.d.ts.map

package/dist/i18n/acceptLanguage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptLanguage.d.ts","sourceRoot":"","sources":["../../src/i18n/acceptLanguage.ts"],"names":[],"mappings":"AAiBA,0GAA0G;AAC1G,MAAM,WAAW,aAAa;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,EAAE,CAuBtF"}