@pithy-sh/core 0.2.0 → 0.3.1

package/dist/http/oidcWebhook.js

@@ -0,0 +1,414 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError, UpstreamError, WebhookUnverifiedError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/http/oidcWebhook.ts
+/**
+* The `signed-webhook` strategy for a sender that proves itself with an **OIDC token** rather than an HMAC.
+* Issuers, key endpoint, audience and a claims predicate in; the verified claims, or a `PithyError`, out.
+*
+* Two mechanisms, one declared strategy. {@link ./verification.VerificationStrategy} already says as much —
+* *"an HMAC, a signed JWS chain, an OIDC token… a rail whose sender proves it differently implements its
+* own"* — so this sits beside {@link ./signedWebhook.requireSignedWebhook} and wears its seams, rather than
+* adding a word to that union. What changes is where the proof comes from: with an HMAC both ends hold a
+* secret, and with OIDC neither end holds anything. The sender asks its identity provider for a token that
+* expires in minutes; the receiver asks the same provider for the public keys that check it.
+*
+* ## The claims check is the boundary, not the signature
+*
+* An identity provider signs tokens for **everybody** with the same handful of keys. GitHub signs one for
+* every repository on the planet; Google signs one for every Pub/Sub push subscription. So a valid signature
+* proves only *that provider minted this*, which any of their users can arrange in under a minute. What makes
+* a token **ours** is what it claims: `aud`, which the sender names when it mints the token and which is the
+* endpoint it was minted for, and whatever the {@link OidcWebhookScheme.claims} predicate asserts on top —
+* `sub === "repo:pithy-sh/pithy:environment:npm-publish"` for a release job, an issuer's service account for
+* a push subscription. Verify the signature, skip those, and the result is an endpoint every user of that
+* provider can post to.
+*
+* That is why `claims` is a **predicate the route holds** rather than a value in configuration. It is the
+* same constraint as a `ValueRotator`: the declaration is the `signed-webhook` tag on the route, and the code
+* that decides who is allowed lives with the route, where it can be read beside the handler it protects.
+*
+* ## Four steps, in this order, and the order is the security property
+*
+* 1. **Pin the algorithm before touching a key.** `alg` arrives in a header nobody has verified yet, so it is
+*    parsed against a literal `RS256` rather than looked up. That is what makes the two published confusions
+*    unreachable — `none`, which asks for the signature to be skipped, and `HS256`, which asks the verifier to
+*    HMAC with the *public* key as if it were a shared secret. Neither survives a literal.
+* 2. **Resolve the key by `kid` from the issuer's published set.** Never from the token, which is why there is
+*    no `jwk`/`x5u` handling here: a token that carries its own key is a token that verifies itself.
+* 3. **Verify the signature over the exact received segments** — `header.claims` as encoded, never a
+*    re-serialization. Key order and whitespace belong to the sender, not to us.
+* 4. **Then read the claims,** and only then. A claim from an unverified token is a claim an attacker wrote,
+*    so a verifier that reads `iss` or `sub` to decide *which key to fetch* has already trusted the forgery it
+*    is about to check. Issuer, audience, expiry, and the caller's predicate are all after the signature.
+*
+* ## What a refusal says
+*
+* `core/webhook_unverified`, 401, one code for every step a sender can fail — unreadable token, unknown key,
+* bad signature, wrong audience, expired, predicate false. 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. Values that decide something are named there (`kid`, `iss`, `aud`) because a misconfigured
+* audience is the realistic failure and an operator cannot fix what the log will not name — truncated by
+* {@link snippet}, and never the signature and never the whole token.
+*
+* Two failures are deliberately **not** the sender's. An endpoint with no issuers, no audience, no key
+* endpoint, or a clock that is not a clock is a configuration fault and takes `core/internal` — reporting it
+* as an unverified webhook sends an operator hunting a forger who is not there. And a key endpoint that
+* cannot be reached or answers nonsense is `core/upstream_failed` (502), because a 500 tells an operator to
+* read *our* logs and the thing that broke is the issuer's. Both still refuse the delivery: fail closed is
+* about what happens to the request, not about whose code goes on it.
+*
+* ## What this proves, and what it does not
+*
+* The same caveat as the HMAC scheme, for the same reason: this proves a delivery is authentic and fresh,
+* never that it is *new*. A captured token replays until it expires. A handler that grants, charges, or
+* deletes needs its own uniqueness key.
+*/
+/** How long a fetched key set is reused. Issuers rotate slowly, and an unknown `kid` forces a refresh anyway. */
+const OIDC_JWKS_TTL_SECONDS = 3600;
+/** Tolerance on `exp`, `nbf` and `iat`. A minute covers clock drift; an hour would cover a replay. */
+const OIDC_CLOCK_SKEW_SECONDS = 60;
+/**
+* The most tolerance this verifier accepts, and it refuses above rather than clamping.
+*
+* A skew is a replay window in the plainest possible units: every second of it is a second longer a captured
+* token keeps working. Five minutes is the far end of real drift between two machines that both run NTP; past
+* that a number has stopped covering drift and started covering a capture, which is what the sentence above
+* says about an hour. Refused rather than clamped because a `604800` is a typo or a misunderstanding either
+* way — clamped, it boots and nobody reads the line again; refused, it is a red boot and a two-character fix.
+*/
+const OIDC_MAX_CLOCK_SKEW_SECONDS = 300;
+/** The header a bearer token arrives in, unless a sender names another. Lower case, as Hono presents one. */
+const DEFAULT_TOKEN_HEADER = "authorization";
+/** RSASSA-PKCS1-v1_5 with SHA-256 — the one algorithm `alg: RS256` names, fixed here rather than derived. */
+const RS256 = {
+	name: "RSASSA-PKCS1-v1_5",
+	hash: "SHA-256"
+};
+/** The unpadded url alphabet (RFC 4648 §5). Whitespace, `+`, `/` and `=` are all outside it, deliberately. */
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+/** How much of a token-supplied value a refusal may quote. Enough to diagnose, too little to fill a log. */
+const SNIPPET_LENGTH = 120;
+/**
+* The header of an OIDC token, as tightly as it can be stated. `alg` is a literal for the reason in the
+* module doc; `kid` is required because a key is resolved by it and a token that names no key cannot be
+* checked against one. `.loose()` because a provider may add a field and a real token must not be refused
+* for carrying something new.
+*/
+const OidcTokenHeader = z.object({
+	alg: z.literal("RS256").describe("The signing algorithm. A literal, not a lookup: `alg` arrives in an unverified header, and accepting `none` or `HS256` from it is how JWS verifiers are bypassed."),
+	kid: z.string().min(1).describe("Which of the issuer's published keys signed the token. Resolved against the issuer's key set.")
+}).loose().describe("The header of an OIDC token, constrained to the one shape this verifier accepts.");
+/**
+* One published RSA verification key, in the shape a JWKS endpoint returns. `.loose()` because providers add
+* fields, and a key set must not be rejected for carrying something this build does not read.
+*/
+const OidcJwk = z.object({
+	kid: z.string().min(1).describe("The key id a token header names."),
+	kty: z.string().min(1).describe("The key type. Only `RSA` is accepted — an OIDC token is signed with one."),
+	n: z.string().min(1).describe("The RSA modulus, base64url."),
+	e: z.string().min(1).describe("The RSA public exponent, base64url."),
+	alg: z.string().min(1).optional().describe("The algorithm the key is published for, when stated."),
+	use: z.string().min(1).optional().describe("What the key is published for — `sig` for a signing key.")
+}).loose().describe("One published OIDC verification key, as a JWKS endpoint returns it.");
+/** A published key set. At least one key: an empty set is an endpoint that is not answering properly. */
+const OidcJwks = z.object({ keys: z.array(OidcJwk).min(1).describe("Every key the issuer currently publishes for signature verification.") }).loose().describe("The response of an issuer's JWKS endpoint.");
+/**
+* The claims an OIDC token carries, narrowed to the ones that decide anything. `.loose()` keeps the rest —
+* the predicate reads them, and a claim set must not be refused for being richer than expected.
+*
+* `aud` is a **string and only a string**, though RFC 7519 permits an array. The audience check is the
+* boundary, and an array turns an equality into a set membership — one more shape for a verifier to be wrong
+* about, on the check the whole scheme rests on. No sender the kit talks to mints one.
+*/
+const OidcClaims = z.object({
+	iss: z.string().min(1).describe("Who issued the token. Checked against the configured issuers, and nothing else."),
+	aud: z.string().min(1).describe("Who the token was minted for — the endpoint the sender named when it asked for the token. The claim that makes a token ours rather than merely the issuer's."),
+	sub: z.string().min(1).optional().describe("Which identity the issuer minted the token for — a workflow's `repo:owner/name:environment:x`, a service account. Read by the caller's `claims` predicate, never by this module."),
+	exp: z.number().int().describe("When the token expires, in seconds since the epoch."),
+	nbf: z.number().int().optional().describe("The earliest the token may be used, in seconds since the epoch."),
+	iat: z.number().int().optional().describe("When the token was issued, in seconds since the epoch.")
+}).loose().describe("The claims on an OIDC token, narrowed to the ones verification depends on.");
+/** The default transport: the runtime's own `fetch`. */
+const oidcJwksFetch = (url) => fetch(url);
+/**
+* A key cache in memory, expiring on a clock the caller owns.
+*
+* One object per call, so two callers never share one by accident and a test's cache dies with its test. The
+* clock is injected for the same reason it is everywhere else here: an expiry that depends on wall time is an
+* assertion nobody can write.
+*/
+function memoryJwksCache(options = {}) {
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const held = /* @__PURE__ */ new Map();
+	return {
+		get: async (url) => {
+			const entry = held.get(url);
+			if (entry === void 0) return void 0;
+			if (entry.expiresAt <= now().getTime()) {
+				held.delete(url);
+				return;
+			}
+			return entry.keys;
+		},
+		set: async (url, keys, ttlSeconds) => {
+			held.set(url, {
+				keys,
+				expiresAt: now().getTime() + ttlSeconds * 1e3
+			});
+		}
+	};
+}
+/**
+* Verify one OIDC token and return its claims. Throws, never reports.
+*
+* The steps run in the order the module doc gives, and that order **is** the security property: algorithm
+* pinned, key resolved by `kid` from the published set, signature checked over the received bytes, and only
+* then a single claim read. A verifier that reads a claim to decide which key to fetch has trusted the thing
+* it has not checked yet.
+*
+* @throws {@link WebhookUnverifiedError} (401) when the sender did not prove itself — unreadable token,
+*   unknown key, bad signature, wrong issuer or audience, expired, not yet valid, predicate false.
+* @throws {@link InternalError} (500) when this endpoint is not configured to verify anything.
+* @throws {@link UpstreamError} (502) when the issuer's key endpoint could not be read.
+*/
+async function verifyOidcToken(token, options) {
+	const issuers = options.issuers.filter((issuer) => issuer.length > 0);
+	if (issuers.length === 0 || options.audience.length === 0 || options.jwksUrl.length === 0) throw misconfigured("Give the OIDC webhook guard an issuer, an audience, and a JWKS URL.", "The OIDC webhook guard resolved no issuer, no audience, or no key endpoint, so it can verify nothing.");
+	const seconds = Math.floor((options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	if (!Number.isFinite(seconds)) throw misconfigured("Give the OIDC webhook guard a valid clock.", "The OIDC webhook guard was handed a clock that is not a valid Date, so no token's freshness can be judged.");
+	const skew = options.skewSeconds ?? 60;
+	if (!Number.isFinite(skew) || skew < 0 || skew > 300) throw misconfigured(`Give the OIDC webhook guard a clock skew between 0 and 300 seconds.`, `The OIDC webhook guard was given a clock skew of ${String(skew)} seconds, and a tolerance must be a number from 0 to 300.`);
+	const jwksTtlSeconds = options.jwksTtlSeconds ?? 3600;
+	if (!Number.isFinite(jwksTtlSeconds) || jwksTtlSeconds < 0) throw misconfigured("Give the OIDC webhook guard a key-set lifetime of zero seconds or more.", `The OIDC webhook guard was given a key-set lifetime of ${String(jwksTtlSeconds)} seconds, which would never expire.`);
+	const { head, body, mac } = splitCompactJws(token);
+	const header = OidcTokenHeader.safeParse(decodeJwtJson(head, "the token header"));
+	if (!header.success) throw unverified(`the token header is not one this endpoint accepts — ${issues(header.error)}.`);
+	const key = await importKey(await resolveKey(header.data.kid, options));
+	if (!await crypto.subtle.verify(RS256.name, key, new Uint8Array(decodeBase64Url(mac, "the token signature")), new TextEncoder().encode(`${head}.${body}`))) throw unverified(`the token signature does not match the signed segments under key ${snippet(header.data.kid)}.`);
+	const parsed = OidcClaims.safeParse(decodeJwtJson(body, "the token claims"));
+	if (!parsed.success) throw unverified(`the token claims are not those of an OIDC token — ${issues(parsed.error)}.`);
+	const claims = parsed.data;
+	if (!issuers.includes(claims.iss)) throw unverified(`the token issuer is ${snippet(claims.iss)}, which this endpoint does not accept.`);
+	if (claims.aud !== options.audience) throw unverified(`the token audience is ${snippet(claims.aud)}, and this endpoint expects ${snippet(options.audience)}.`);
+	if (claims.exp + skew < seconds) throw unverified(`the token expired at ${instant(claims.exp)}.`);
+	if (claims.nbf !== void 0 && claims.nbf - skew > seconds) throw unverified(`the token is not valid before ${instant(claims.nbf)}.`);
+	if (claims.iat !== void 0 && claims.iat - skew > seconds) throw unverified(`the token was issued at ${instant(claims.iat)}, which is in the future.`);
+	if (!await options.claims(claims)) throw unverified(`the token is the issuer's but its claims are not accepted by this endpoint — subject ${snippet(claims.sub ?? "none")}.`);
+	return claims;
+}
+/**
+* The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), zValidator("json", Body,
+* validationHook), handler)`.
+*
+* ## Why the header is read before anything else
+*
+* The bearer header is the cheapest thing to check and the commonest thing to be missing, so it goes first. A
+* delivery carrying no token is refused whatever the body holds, and fetching a key set before looking would
+* be unauthenticated work an anonymous POST could buy on the one route whose purpose is to refuse anonymous
+* callers.
+*
+* ## Why a cache is not optional here
+*
+* A caller that presents *something* is past that first check, and the next thing the verifier needs is the
+* issuer's key set. So the guard builds a {@link memoryJwksCache} when the route gives none — once, when the
+* middleware is constructed, never per request, which is a cache that has never held anything. A `kid` is
+* published by definition, which makes a 49-byte token naming one the cheapest thing on the internet to send,
+* and with no cache each one is a round trip to the issuer, 1:1. That is a bandwidth multiplier aimed at
+* somebody else's endpoint, and once the issuer rate-limits us {@link fetchJwks} maps it to
+* `core/upstream_failed` for the genuine deliveries too — an anonymous caller taking the boundary down by
+* asking it politely. A route wanting a harder bound (shared across isolates, or rate-limiting) passes its
+* own {@link OidcWebhookScheme.jwksCache}, and this one is never built.
+*
+* A `kid` **nobody** publishes still costs one fetch per delivery, cache or no cache, because an unknown key
+* id is how rotation announces itself and declining to look is an outage. That bound is per delivery and
+* lives in {@link resolveKey}; the cache is what collapses the other flood, the one naming a key that exists.
+*
+* ## Why nothing is published to the request
+*
+* The gate proves the caller and returns; it sets no request variable. The claims a route cares about are the
+* ones its own {@link OidcWebhookScheme.claims} predicate already asserted, and a handler that needs the
+* whole claim set calls {@link verifyOidcToken} directly rather than reading a variable it must remember to
+* null-check.
+*
+* The body is never read here — unlike the HMAC gate, whose proof covers the bytes. An OIDC token proves who
+* sent the request and says nothing about what they sent, so the route's `zValidator` is the only thing that
+* touches the body, and it sees an untouched stream.
+*/
+function requireOidcWebhook(options) {
+	const { header = DEFAULT_TOKEN_HEADER, now, ...scheme } = options;
+	const jwksCache = scheme.jwksCache ?? memoryJwksCache({ now });
+	return async (c, next) => {
+		const presented = c.req.header(header);
+		const token = presented === void 0 ? void 0 : bearerToken(presented);
+		if (token === void 0) throw unverified(`the delivery carries no ${header} header with a Bearer token.`);
+		await verifyOidcToken(token, {
+			...scheme,
+			jwksCache,
+			now: now?.() ?? /* @__PURE__ */ new Date()
+		});
+		await next();
+	};
+}
+/**
+* The key a token's `kid` names, from the cache when it holds it and from the issuer otherwise.
+*
+* A `kid` the cache does not hold triggers **exactly one** refresh, which is what makes key rotation
+* invisible: a new signing key appears in a token before anything tells us to look for it, and waiting out a
+* TTL would be an outage. Exactly one, because otherwise a stream of forged tokens naming random `kid`s is a
+* way to make us hammer the issuer — one delivery buys one fetch, whatever it claims. A caller that wants a
+* harder bound than that gives a {@link JwksCache} that rate-limits, which is the other thing injecting the
+* store buys.
+*/
+async function resolveKey(kid, options) {
+	const cached = (await options.jwksCache?.get(options.jwksUrl))?.find((key) => key.kid === kid);
+	if (cached) return cached;
+	const refreshed = await fetchJwks(options);
+	await options.jwksCache?.set(options.jwksUrl, refreshed, options.jwksTtlSeconds ?? 3600);
+	const found = refreshed.find((key) => key.kid === kid);
+	if (!found) throw unverified(`no key the issuer publishes matches the token's kid ${snippet(kid)}.`);
+	return found;
+}
+/**
+* Fetch and validate the issuer's key set.
+*
+* Every failure is `core/upstream_failed`, and every failure still refuses the delivery. The code says whose
+* system to look at — a 500 would send an operator into our logs for an outage at an endpoint we do not run,
+* and a 401 would send them after a forger. The URL is named because it is our own configuration, not
+* anything a caller supplied.
+*/
+async function fetchJwks(options) {
+	const transport = options.transport ?? oidcJwksFetch;
+	let response;
+	try {
+		response = await transport(options.jwksUrl);
+	} catch (cause) {
+		throw upstream(`The OIDC key endpoint ${options.jwksUrl} did not answer.`, cause);
+	}
+	if (!response.ok) throw upstream(`The OIDC key endpoint ${options.jwksUrl} answered ${response.status}.`);
+	let body;
+	try {
+		body = JSON.parse(await response.text());
+	} catch (cause) {
+		throw upstream(`The OIDC key endpoint ${options.jwksUrl} answered a non-JSON body.`, cause);
+	}
+	const parsed = OidcJwks.safeParse(body);
+	if (!parsed.success) throw upstream(`The OIDC key endpoint ${options.jwksUrl} answered an unexpected shape — ${issues(parsed.error)}.`);
+	return parsed.data.keys;
+}
+/** Import one published JWK as a verification key. A non-RSA key is refused rather than handed to WebCrypto. */
+async function importKey(jwk) {
+	if (jwk.kty !== "RSA") throw upstream(`Published key ${snippet(jwk.kid)} is ${snippet(jwk.kty)}, and only RSA keys sign an OIDC token.`);
+	try {
+		return await crypto.subtle.importKey("jwk", {
+			...jwk,
+			alg: "RS256"
+		}, RS256, false, ["verify"]);
+	} catch (cause) {
+		throw upstream(`Published key ${snippet(jwk.kid)} could not be imported.`, cause);
+	}
+}
+/**
+* Split a compact JWS, refusing anything that is not three non-empty segments.
+*
+* The empty-segment check is the structural half of the algorithm pin: `alg: none` produces a header, a
+* payload, and nothing after the final dot, so it is refused here before a header is even decoded.
+*/
+function splitCompactJws(token) {
+	const segments = token.split(".");
+	if (segments.length !== 3) throw unverified(`the token has ${segments.length} segments, expected 3.`);
+	const [head, body, mac] = segments;
+	if (head.length === 0 || body.length === 0 || mac.length === 0) throw unverified("a token segment is empty; an unsigned token is not accepted.");
+	return {
+		head,
+		body,
+		mac
+	};
+}
+/**
+* Bytes from one unpadded base64url segment (RFC 4648 §5), strictly.
+*
+* A token segment is attacker-supplied by definition and `atob` is famously forgiving — it digests whitespace
+* and, on some runtimes, characters that mean nothing. Silently decoding malformed input produces bytes that
+* parse into *something*, and something is exactly what a forger wants a verifier to work with. Padding is
+* refused too: RFC 7515 §2 mandates unpadded segments, and one token with two spellings is one more thing a
+* comparison can be wrong about.
+*/
+function decodeBase64Url(value, label) {
+	if (!BASE64URL_PATTERN.test(value) || value.length % 4 === 1) throw unverified(`${label} is not unpadded base64url.`);
+	const standard = value.replaceAll("-", "+").replaceAll("_", "/");
+	const padded = standard.padEnd(standard.length + (4 - standard.length % 4) % 4, "=");
+	let binary;
+	try {
+		binary = atob(padded);
+	} catch (cause) {
+		throw unverified(`${label} failed base64url decode.`, cause);
+	}
+	return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+/** One base64url JSON segment. `unknown` out — decoded bytes are not yet a known shape. */
+function decodeJwtJson(segment, label) {
+	const text = new TextDecoder().decode(decodeBase64Url(segment, label));
+	try {
+		return JSON.parse(text);
+	} catch (cause) {
+		throw unverified(`${label} is not JSON.`, cause);
+	}
+}
+/** Read `Bearer <token>` from a header value, or `undefined` when it is not one. The scheme is case-insensitive. */
+function bearerToken(value) {
+	return /^bearer +(\S+)$/i.exec(value.trim())?.[1];
+}
+/** The sender's refusal. One code for every step; the step is in `detail`, which never reaches the sender. */
+function unverified(detail, cause) {
+	return new WebhookUnverifiedError({
+		action: "Send a current OIDC token minted for this endpoint's audience.",
+		detail: `The OIDC webhook guard refused a delivery: ${detail}`
+	}, cause === void 0 ? void 0 : { cause });
+}
+/**
+* Ours, not the sender's. Every value this refuses on is one *we* wrote — an issuer list, an audience, a
+* clock, a tolerance — so it takes `core/internal` and an `action` naming the knob to turn, rather than
+* sending an operator after a forger who is not there. Still a refusal: the delivery is denied either way.
+*/
+function misconfigured(action, detail) {
+	return new InternalError({
+		message: "This webhook endpoint is not configured.",
+		action,
+		detail
+	});
+}
+/** The issuer's failure, not the sender's and not ours. Still a refusal — 502 denies the delivery. */
+function upstream(detail, cause) {
+	return new UpstreamError({
+		action: "Check that this Worker can reach the issuer's JWKS endpoint.",
+		detail
+	}, cause === void 0 ? void 0 : { cause });
+}
+/** Zod issues as `path:code` pairs — never `message` or `received`, which would echo the token. */
+function issues(error) {
+	return error.issues.map((issue) => `${issue.path.join(".") || "<root>"}:${issue.code}`).join(", ");
+}
+/**
+* One epoch-seconds claim, rendered for a refusal.
+*
+* The comparisons above are arithmetic and are right for any number `z.number().int()` admits — but
+* `toISOString()` is not: `new Date(-1e15 * 1000)` is an invalid Date and **throws a `RangeError`**, which is
+* a plain `Error` escaping a module whose every other exit is a `PithyError`. It is thrown while composing
+* the *refusal message* for a token that has already been decided against, so the token is still refused —
+* but through {@link requireOidcWebhook} the sender chooses whether they get a 401 or a 500, and a 500 sends
+* an operator into our logs over somebody else's forgery. So a claim outside `Date`'s range is quoted as the
+* number it is, and the refusal stays the refusal it already was.
+*/
+function instant(epochSeconds) {
+	const at = /* @__PURE__ */ new Date(epochSeconds * 1e3);
+	return Number.isFinite(at.getTime()) ? at.toISOString() : `epoch second ${epochSeconds}`;
+}
+/** A token-supplied value, quoted and bounded, so a refusal names what failed without becoming the log. */
+function snippet(value) {
+	const trimmed = value.length > SNIPPET_LENGTH ? `${value.slice(0, SNIPPET_LENGTH)}…` : value;
+	return JSON.stringify(trimmed);
+}
+//#endregion
+export { OIDC_CLOCK_SKEW_SECONDS, OIDC_JWKS_TTL_SECONDS, OIDC_MAX_CLOCK_SKEW_SECONDS, OidcClaims, OidcJwk, OidcJwks, memoryJwksCache, oidcJwksFetch, requireOidcWebhook, verifyOidcToken };

package/dist/http/signedWebhook.d.ts

@@ -2,68 +2,6 @@
 // SPDX-License-Identifier: MIT
 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.
  *
@@ -85,7 +23,12 @@ export interface SignedWebhookScheme {
     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}. */
+    /**
+     * The freshness window, in seconds, either side of now. Defaults to {@link SIGNED_WEBHOOK_TOLERANCE_SECONDS}
+     * and must be a finite number from 0 to {@link SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}; anything else is
+     * `core/internal`, because this is the second operand of the freshness comparison and one `NaN` does not
+     * widen the window, it removes it.
+     */
     toleranceSeconds?: number;
 }
 /**
@@ -182,8 +125,9 @@ export type SignedWebhookRefusal =
  * 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.
+ * It still throws for **our** failure: an endpoint holding no usable secret, given a tolerance that is not a
+ * window, 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. Those three are checked first, before anything the sender wrote.
  *
  * `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.

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

@@ -1 +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"}
+{"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;AAoF7D;;;;;;;;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;;;;;OAKG;IACH,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;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAmF3C;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

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { InternalError, WebhookUnverifiedError } from "../error/pithyError.js";
+import { SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS } from "./webhookWindow.js";
 //#region src/http/signedWebhook.ts
 /**
 * The `signed-webhook` strategy, for any sender. Secret, header name, tolerance and the exact received
@@ -40,6 +41,11 @@ import { InternalError, WebhookUnverifiedError } from "../error/pithyError.js";
 * 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.
 *
+* The window's own width is checked before any delivery is. `skew > tolerance` is false when `tolerance` is
+* `NaN`, so a non-finite tolerance does not widen the window — it deletes it, and every capture verifies
+* forever. A tolerance outside `0 … {@link SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}` is therefore refused as the
+* configuration fault it is, never honored and never clamped.
+*
 * ## Why the comparison is `crypto.subtle.verify`
 *
 * Comparing HMACs with `===` leaks how many leading bytes matched, and that leak is enough to forge a
@@ -62,8 +68,6 @@ import { InternalError, WebhookUnverifiedError } from "../error/pithyError.js";
 * {@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. */
@@ -130,8 +134,9 @@ function parseSignedWebhookHeader(header, timestampKey, signatureKey) {
 * 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.
+* It still throws for **our** failure: an endpoint holding no usable secret, given a tolerance that is not a
+* window, 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. Those three are checked first, before anything the sender wrote.
 *
 * `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.
@@ -143,17 +148,22 @@ async function checkSignedWebhook(body, header, options) {
 		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;
+	if (!Number.isFinite(tolerance) || tolerance < 0 || tolerance > 3600) throw new InternalError({
+		message: "This webhook endpoint is not configured.",
+		action: `Give the ${options.header} guard a tolerance between 0 and ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS} seconds.`,
+		detail: `The signed-webhook guard on ${options.header} was given a tolerance of ${String(tolerance)} seconds, and a freshness window must be a number from 0 to ${SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS}.`
+	});
 	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 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 skew = Math.abs(nowSeconds - parsed.timestamp);
 	if (skew > tolerance) return {
 		reason: "stale",
@@ -246,4 +256,4 @@ function hexBytes(value) {
 	return bytes;
 }
 //#endregion
-export { SIGNED_WEBHOOK_MAX_CANDIDATES, SIGNED_WEBHOOK_TOLERANCE_SECONDS, checkSignedWebhook, parseSignedWebhookHeader, requireSignedWebhook, verifySignedWebhook };
+export { SIGNED_WEBHOOK_MAX_CANDIDATES, checkSignedWebhook, parseSignedWebhookHeader, requireSignedWebhook, verifySignedWebhook };

package/dist/http/webhookWindow.d.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * The freshness window a signed webhook is checked against: the default, and the widest one accepted.
+ *
+ * **Two numbers in a module of their own, because of who has to read them.** They are the bounds a
+ * config schema states in its own `.describe()` — `packages/payments/src/config/config.ts` interpolates
+ * the maximum into the sentence an adopter reads — and a config schema is one half of a route contract,
+ * which a management client validates **in a browser**. `signedWebhook.ts` is a Hono middleware and
+ * reaches the whole Worker graph from `PithyHonoEnv` down; importing a number from it dragged `hono`,
+ * `kysely`, `kysely-d1` and `@cloudflare/workers-types` into `payments/src/http/schemas.ts`,
+ * `payments/src/http/responses.ts` and every module that reaches payments' config (#521).
+ *
+ * `tooling/browser-scopes` is the gate that caught it, and it is the gate that keeps this file a leaf:
+ * **nothing here may import anything.** A constant a browser-facing schema quotes belongs beside the
+ * other constants a browser may see, not inside the verifier that enforces it.
+ */
+/** 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;
+/**
+ * The widest freshness window the verifier accepts, and it refuses above rather than clamping.
+ *
+ * A tolerance is a replay window in the plainest possible units: every second of it is a second longer a
+ * captured delivery keeps working. The five minutes above is Stripe's own and covers clock drift plus ordinary
+ * delivery latency; an hour is the far end of a sender that queues a delivery and re-sends it without re-dating
+ * it. Past that a number has stopped covering latency and started covering a capture.
+ *
+ * Refused rather than clamped because an `86400` is a typo or a misunderstanding either way — clamped, the
+ * endpoint keeps working and nobody reads the line again; refused, the first delivery says which knob is wrong
+ * and it is a two-character fix.
+ */
+export declare const SIGNED_WEBHOOK_MAX_TOLERANCE_SECONDS = 3600;
+//# sourceMappingURL=webhookWindow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhookWindow.d.ts","sourceRoot":"","sources":["../../src/http/webhookWindow.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oCAAoC,OAAO,CAAC"}