@pithy-sh/core 0.3.0 → 0.4.0

package/dist/http/oidcWebhook.js

@@ -46,17 +46,20 @@ import { z } from "zod";
 * ## 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
+* a key that cannot verify an `RS256` signature, bad signature, wrong audience, expired, predicate false. A
+* `kid` selects the key, and a `kid` is a value the sender chose, so *every* answer the key leads to is the
+* sender's. 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
+* Two failures are deliberately **not** the sender's, and the test for both is whether the sender could have
+* chosen them. 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; no `kid` decides whether that happens. 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
@@ -65,8 +68,29 @@ import { z } from "zod";
 * 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. */
+/** How long a fetched key set is reused. Issuers rotate slowly, so an hour of it is one round trip an hour. */
 const OIDC_JWKS_TTL_SECONDS = 3600;
+/**
+* **The most often the issuer's key endpoint is asked, whatever a token's `kid` claims.**
+*
+* The TTL above bounds the *hit* path and bounds nothing else. A `kid` the held set does not name is a miss,
+* a miss is a reason to refresh — that is what makes rotation invisible — and `kid` arrives in a header
+* nobody has verified yet. So the miss path was the whole amplifier: `Bearer <jwt with kid: random-uuid>` is
+* exactly as cheap to mint as one naming a published key, and each one bought a round trip to the issuer,
+* 1:1, from an anonymous caller. The cache answered only the forger who bothered to name a real `kid`.
+*
+* A window closes it, and it closes it for every `kid` at once because it is not about the `kid`: at most one
+* ask per window per key endpoint, and a miss inside the window is refused on what we already hold rather
+* than on a fresh look. A random `kid` therefore costs a lookup in memory, and the outbound rate is a
+* constant an attacker cannot move.
+*
+* **A minute, and the number is a rotation delay.** It is how long a genuinely new signing key can be refused
+* before we look again — an issuer publishes the key before the first token names it, and every one of them
+* overlaps rotations by hours, so a minute is inside the overlap and a refusal inside it is a redelivery
+* rather than a loss. Wider trades rotation latency for nothing much: one ask a minute is already too little
+* traffic for any issuer to rate-limit.
+*/
+const OIDC_JWKS_MIN_REFRESH_SECONDS = 60;
 /** Tolerance on `exp`, `nbf` and `iat`. A minute covers clock drift; an hour would cover a replay. */
 const OIDC_CLOCK_SKEW_SECONDS = 60;
 /**
@@ -142,6 +166,8 @@ const oidcJwksFetch = (url) => fetch(url);
 function memoryJwksCache(options = {}) {
 	const now = options.now ?? (() => /* @__PURE__ */ new Date());
 	const held = /* @__PURE__ */ new Map();
+	/** When the endpoint behind each url may be asked again. The miss path's whole state. */
+	const askedUntil = /* @__PURE__ */ new Map();
 	return {
 		get: async (url) => {
 			const entry = held.get(url);
@@ -157,6 +183,13 @@ function memoryJwksCache(options = {}) {
 				keys,
 				expiresAt: now().getTime() + ttlSeconds * 1e3
 			});
+		},
+		claimRefresh: async (url, seconds) => {
+			const at = now().getTime();
+			const until = askedUntil.get(url);
+			if (until !== void 0 && until > at) return false;
+			askedUntil.set(url, at + seconds * 1e3);
+			return true;
 		}
 	};
 }
@@ -169,9 +202,11 @@ function memoryJwksCache(options = {}) {
 * 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.
+*   unknown key, a key that cannot verify an `RS256` signature, 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.
+* @throws {@link UpstreamError} (502) when the issuer's key endpoint could not be read — either because the
+*   ask failed, or because it was asked inside {@link OIDC_JWKS_MIN_REFRESH_SECONDS} and nothing is held.
 */
 async function verifyOidcToken(token, options) {
 	const issuers = options.issuers.filter((issuer) => issuer.length > 0);
@@ -209,21 +244,24 @@ async function verifyOidcToken(token, options) {
 * 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
+* ## Why a store 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.
+* middleware is constructed, never per request, which is a store that has never held anything. A 49-byte
+* token is the cheapest thing on the internet to send, and with no store 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.
+*
+* **Both halves of the flood, not one.** A token naming a `kid` the issuer really publishes is answered out
+* of what the store holds. A token naming a `kid` nobody has ever published is answered by
+* {@link JwksCache.claimRefresh}: one ask per {@link OIDC_JWKS_MIN_REFRESH_SECONDS} per key endpoint, for
+* every `kid` at once, so a `kid` an attacker invents costs a map lookup and no outbound request. The first
+* round of this fix had only the first half, which meant the cache helped exactly against a forger who
+* bothered to copy a real `kid` and not at all against one who did not. A route wanting the bound shared
+* across isolates rather than held per isolate passes its own {@link OidcWebhookScheme.jwksCache} — over KV
+* or the Cache API — and this one is never built.
 *
 * ## Why nothing is published to the request
 *
@@ -252,20 +290,44 @@ function requireOidcWebhook(options) {
 	};
 }
 /**
-* 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.
+* The key a token's `kid` names, from the store when it holds it and from the issuer otherwise.
+*
+* ## The miss path is the one an anonymous caller reaches
+*
+* A `kid` the store does not hold is a reason to refresh, and it has to be: a new signing key appears in a
+* token before anything tells us to look for it, so waiting out a TTL would be an outage. But `kid` is read
+* out of a header nobody has verified yet, and the two things it can mean — *the issuer rotated* and *I made
+* this up* — are indistinguishable until after the fetch it costs. That is the whole amplifier, and it is why
+* a store keyed only on what the issuer published answered the wrong half of it: the forger who names a
+* published `kid` was collapsed onto one fetch, and the one who names `crypto.randomUUID()` bought a round
+* trip per delivery, from an endpoint whose purpose is refusing anonymous callers.
+*
+* So the ask is claimed before it is made — {@link JwksCache.claimRefresh}, one per
+* {@link OIDC_JWKS_MIN_REFRESH_SECONDS} per key endpoint, for every `kid` together rather than per `kid`.
+* Per `kid` would be no bound at all: an attacker has as many of those as they care to type.
+*
+* ## What a miss inside the window answers, and why it is two different codes
+*
+* Whatever we hold is what the issuer published a moment ago, so a `kid` outside it is a `kid` the issuer
+* does not publish — the sender's failure, 401, audited, and not worth retrying. **Unless we hold nothing**,
+* which means the last ask inside this window failed or has not come back: then the honest answer is that we
+* could not look, and that is the issuer's 502. Neither answer costs an outbound request, which is the point.
+*
+* With no store at all there is nothing to claim and nothing to hold, so every call fetches. That is
+* {@link verifyOidcToken}'s direct-call shape — one caller, one token it already decided to check — and
+* never the guard's, which builds a store precisely so this paragraph does not describe it.
 */
 async function resolveKey(kid, options) {
-	const cached = (await options.jwksCache?.get(options.jwksUrl))?.find((key) => key.kid === kid);
+	const cache = options.jwksCache;
+	const held = await cache?.get(options.jwksUrl);
+	const cached = held?.find((key) => key.kid === kid);
 	if (cached) return cached;
+	if (cache !== void 0 && !await cache.claimRefresh(options.jwksUrl, 60)) {
+		if (held === void 0 || held.length === 0) throw upstream(`The OIDC key endpoint ${options.jwksUrl} was asked within the last 60 seconds and nothing is held, so the token's kid could not be looked up.`);
+		throw unverified(`no key the issuer publishes matches the token's kid ${snippet(kid)}, and the published set was read within the last 60 seconds.`);
+	}
 	const refreshed = await fetchJwks(options);
-	await options.jwksCache?.set(options.jwksUrl, refreshed, options.jwksTtlSeconds ?? 3600);
+	await cache?.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;
@@ -297,16 +359,30 @@ async function fetchJwks(options) {
 	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. */
+/**
+* Import one published JWK as a verification key. A non-RSA key is refused rather than handed to WebCrypto.
+*
+* **Both refusals are the sender's, 401, and the reason is who chose the key.** A published key that cannot
+* verify an `RS256` signature looks like the issuer's fact, and as a fact about the key set it is — but the
+* key reached here because a `kid` in an unverified header selected it, so as an *answer* it is attacker-
+* chosen. A 502 hands that caller three things it must not have: a code the webhook guard passes through
+* untouched, so the refusal never reaches the audit trail that exists to show a rail being probed; a status
+* a sender is invited to retry, which for Pub/Sub means forever; and a lever for picking which of those two
+* an endpoint answers. The narrower reading is also the true one — a token naming a key that cannot check its
+* own algorithm is a token nothing can verify, which is what `core/webhook_unverified` says.
+*
+* The issuer's own failures stay the issuer's: {@link fetchJwks} is 502 for every one of them, and no `kid`
+* decides whether they happen.
+*/
 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.`);
+	if (jwk.kty !== "RSA") throw unverified(`the token's kid ${snippet(jwk.kid)} names a ${snippet(jwk.kty)} key, 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);
+		throw unverified(`the key the token's kid ${snippet(jwk.kid)} names could not be imported.`, cause);
 	}
 }
 /**
@@ -411,4 +487,4 @@ function snippet(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 };
+export { OIDC_CLOCK_SKEW_SECONDS, OIDC_JWKS_MIN_REFRESH_SECONDS, OIDC_JWKS_TTL_SECONDS, OIDC_MAX_CLOCK_SKEW_SECONDS, OidcClaims, OidcJwk, OidcJwks, memoryJwksCache, oidcJwksFetch, requireOidcWebhook, verifyOidcToken };

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.3.0";
+export declare const PACKAGE_VERSION = "0.4.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.3.0";
+const PACKAGE_VERSION = "0.4.0";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/workflow/stepMessage.d.ts

@@ -68,6 +68,21 @@
  * `message`, throw-site context in `detail`, and a durable boundary is not a reason to move the line.
  * `action` crosses because `action` is already operator-facing — the CLI prints it and `operatorError`
  * includes it. This stops losing a field that was always meant for this reader.
+ *
+ * ## The encoder owns producing something the reader accepts
+ *
+ * The reader is strict, and it has to be: text the kit did not write must not become an operator's
+ * sentence. The consequence is that a *writer* handing it a shape it declines loses the whole channel —
+ * the code, the sentence and the remedy at once — and the operator is handed `core/workflow_failed` 500
+ * with the platform's prose about durable execution. That is not a hypothetical. #534 put an upstream's
+ * `errors[]` into a multi-line `message`, and every Cloudflare refusal raised inside a `classifiedSteps`
+ * step stopped crossing this boundary at all: the first newline read as the code/action separator and
+ * the second as a shape this never writes, so the read returned `null` and the refusal died at the step.
+ *
+ * So {@link encodeWorkflowStepMessage} is **total**: whatever fields it is handed, what it writes decodes
+ * back. Each half is flattened to one line and, past the bound, truncated with an ellipsis rather than
+ * dropped. The asymmetry with the reader is deliberate and is the whole point — the writer owns text the
+ * kit authored and may reshape it; the reader is handed text from a Worker we did not write and may not.
  */
 /**
  * The separator between the step's sentence and its action. One newline, stated once.
@@ -107,9 +122,19 @@ export declare function splitWorkflowStepCode(text: string): {
 /**
  * The text a terminal step throws. The inverse of {@link decodeWorkflowStepMessage}, and tested as one.
  *
- * An action is appended only when there is one to append and it is a single line. An action carrying a
- * break would encode a shape the reader declines, taking the sentence down with it — so the sentence
- * is kept and the action dropped. Losing the remedy is a worse day; losing both is a worse one still.
+ * **What this writes, that reads back — for a well-formed code and a sentence there is one.** Each half
+ * goes through {@link encodable}, so a multi-line sentence is flattened rather than fatal and an overlong
+ * one is truncated rather than declined. An action is appended only when there is one left after that —
+ * a remedy that was empty or only whitespace leaves no trailing separator, because a dangling separator
+ * is a field the reader would have to decline.
+ *
+ * **Two inputs it deliberately cannot represent, so "total" is not the whole word for it.** An empty
+ * `message` encodes to text {@link decodeWorkflowStepMessage} declines, and so does a `code` that does
+ * not match `CODE_PREFIX`. Both refusals are the boundary working: a step that failed without a sentence
+ * has none to promote — the caller's own `fallbackMessage` is what the operator should see — and a code
+ * the reader cannot recognize is exactly the foreign text this encoding exists to keep out of an
+ * operator's sentence. Neither is reachable from a kit throw site; an adopter code declared through
+ * `defineErrorPayload` is checked against the same shape.
  */
 export declare function encodeWorkflowStepMessage(fields: WorkflowStepMessage): string;
 /**

package/dist/workflow/stepMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stepMessage.d.ts","sourceRoot":"","sources":["../../src/workflow/stepMessage.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAc1C,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAInF;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAK7E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAYlF"}
+{"version":3,"file":"stepMessage.d.ts","sourceRoot":"","sources":["../../src/workflow/stepMessage.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAc1C,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAInF;AAuBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAK7E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAYlF"}

package/dist/workflow/stepMessage.js

@@ -69,6 +69,21 @@
 * `message`, throw-site context in `detail`, and a durable boundary is not a reason to move the line.
 * `action` crosses because `action` is already operator-facing — the CLI prints it and `operatorError`
 * includes it. This stops losing a field that was always meant for this reader.
+*
+* ## The encoder owns producing something the reader accepts
+*
+* The reader is strict, and it has to be: text the kit did not write must not become an operator's
+* sentence. The consequence is that a *writer* handing it a shape it declines loses the whole channel —
+* the code, the sentence and the remedy at once — and the operator is handed `core/workflow_failed` 500
+* with the platform's prose about durable execution. That is not a hypothetical. #534 put an upstream's
+* `errors[]` into a multi-line `message`, and every Cloudflare refusal raised inside a `classifiedSteps`
+* step stopped crossing this boundary at all: the first newline read as the code/action separator and
+* the second as a shape this never writes, so the read returned `null` and the refusal died at the step.
+*
+* So {@link encodeWorkflowStepMessage} is **total**: whatever fields it is handed, what it writes decodes
+* back. Each half is flattened to one line and, past the bound, truncated with an ellipsis rather than
+* dropped. The asymmetry with the reader is deliberate and is the whole point — the writer owns text the
+* kit authored and may reshape it; the reader is handed text from a Worker we did not write and may not.
 */
 /**
 * The separator between the step's sentence and its action. One newline, stated once.
@@ -111,16 +126,43 @@ function splitWorkflowStepCode(text) {
 	};
 }
 /**
+* One half as this encoding can carry it: a single line, within the bound.
+*
+* Both reshapes exist because the alternative is losing the field, and the two ways a half can be
+* unreadable are the two ways a writer actually gets it wrong. A line break would encode a shape the
+* reader declines — the sentence would take the remedy down with it, or the remedy would forge a
+* second field — so every break collapses to a space, exactly as `@pithy-sh/cloudflare` flattens an
+* upstream's own text before it lands in `message`. Length is the same argument with a different
+* cause: half a sentence naming its code and its remedy beats the platform's prose about durable
+* execution, so the tail is spent rather than the field. The whole of it was never here anyway —
+* `detail` holds the raw text, on the far side of a boundary it does not cross.
+*/
+function encodable(text) {
+	const flattened = text.replace(/\s*[\n\r]+\s*/g, " ").trim();
+	if (flattened.length <= 512) return flattened;
+	return `${flattened.slice(0, 511).trimEnd()}…`;
+}
+/**
 * The text a terminal step throws. The inverse of {@link decodeWorkflowStepMessage}, and tested as one.
 *
-* An action is appended only when there is one to append and it is a single line. An action carrying a
-* break would encode a shape the reader declines, taking the sentence down with it — so the sentence
-* is kept and the action dropped. Losing the remedy is a worse day; losing both is a worse one still.
+* **What this writes, that reads back — for a well-formed code and a sentence there is one.** Each half
+* goes through {@link encodable}, so a multi-line sentence is flattened rather than fatal and an overlong
+* one is truncated rather than declined. An action is appended only when there is one left after that —
+* a remedy that was empty or only whitespace leaves no trailing separator, because a dangling separator
+* is a field the reader would have to decline.
+*
+* **Two inputs it deliberately cannot represent, so "total" is not the whole word for it.** An empty
+* `message` encodes to text {@link decodeWorkflowStepMessage} declines, and so does a `code` that does
+* not match `CODE_PREFIX`. Both refusals are the boundary working: a step that failed without a sentence
+* has none to promote — the caller's own `fallbackMessage` is what the operator should see — and a code
+* the reader cannot recognize is exactly the foreign text this encoding exists to keep out of an
+* operator's sentence. Neither is reachable from a kit throw site; an adopter code declared through
+* `defineErrorPayload` is checked against the same shape.
 */
 function encodeWorkflowStepMessage(fields) {
-	const stated = `${fields.code}: ${fields.message}`;
-	const action = fields.action?.trim();
-	if (action === void 0 || action === "" || LINE_BREAK.test(action)) return stated;
+	const stated = `${fields.code}: ${encodable(fields.message)}`;
+	const action = encodable(fields.action ?? "");
+	if (action === "") return stated;
 	return `${stated}
 ${action}`;
 }

package/package.json

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

package/src/capability/capability.ts

@@ -155,6 +155,16 @@ export interface SecretRegistryEntrySeam {
    * which it can do without executing the package.
    */
   readonly devValue?: string;
+  /**
+   * The Worker binding this value exists to reach, or absent when it reaches none — the constant half
+   * of *can this composition use this secret* (#541).
+   *
+   * Read here and never interpreted, exactly like {@link devValue}: the CLI joins it against a Worker's
+   * `declinedBindings` so a credential whose bucket the project declined stops being listed as
+   * outstanding work. `@pithy-sh/secrets` owns the concrete field; core needs it on the seam so a
+   * reporting surface can read a capability's declared slice off this contract.
+   */
+  readonly binding?: string;
 }
 
 /** A capability's secret-registry slice: secret name → {@link SecretRegistryEntrySeam}. */
@@ -188,6 +198,35 @@ export type SecretRegistrySeam = Record<string, SecretRegistryEntrySeam>;
  */
 export type SecretBranchSeam = Record<string, readonly string[]>;
 
+/**
+ * **Which of this capability's secrets this Worker's configuration cannot reach** — secret name → the
+ * reason, in an operator's words.
+ *
+ * The neighbor of {@link SecretBranchSeam}, one level up. That one says which *blocks* of a bundle
+ * apply when the bundle itself does; this says that a whole secret does not. `@pithy-sh/auth` declares
+ * one credential per OAuth provider, so a project running Google and GitHub has two secrets that no
+ * code path will ever read — and until #541 `pithy doctor` listed both as outstanding work under
+ * *"fine to leave until you need it"*, which is not true of a credential the configuration has refused.
+ *
+ * **Declared, never inferred**, for {@link SecretBranchSeam}'s reason: `auth-apple-credentials` and
+ * `providers.apple` are spelled alike today and nothing makes a secret name and a config key the same
+ * thing. The capability holds both halves at construction; a CLI matching them by substring would be
+ * right by luck.
+ *
+ * **Per composition, which is why it is here and not on the registry entry.** A registry entry is plain
+ * data shared by every Worker that declares the name; whether a provider is enabled is one Worker's
+ * configuration. The constant half of the same question — *which binding does this credential exist to
+ * reach* — is on the entry, as `binding`, because it does not change between compositions.
+ *
+ * **The reason reaches a terminal, so it is a sentence and not a code.** Name the configuration that
+ * decided it, the way an operator would have to edit it: `providers.apple is not enabled in
+ * pithy.config.ts`. It answers *what would I have to do to turn this on* as well as *why is this here*.
+ *
+ * Declaring nothing is the ordinary case and means every declared secret applies. It is descriptive
+ * only: nothing in the runtime reads it, and no command acts on it beyond reporting.
+ */
+export type InapplicableSecretSeam = Record<string, 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
@@ -332,6 +371,12 @@ export interface Capability<
    * no `json` secret at all, declares nothing.
    */
   secretBranches?: SecretBranchSeam;
+  /**
+   * Which of this capability's secrets this Worker's configuration cannot reach, and why — see
+   * {@link InapplicableSecretSeam}. Additive and optional: a capability whose secrets all apply
+   * whenever it is composed declares nothing, which is the ordinary case.
+   */
+  inapplicableSecrets?: InapplicableSecretSeam;
   /**
    * 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/error/messageParams.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { KitErrorCode } from "./payload";
+
+/**
+ * The `params` a throw site **guarantees** for a kit error code — and therefore the only names a
+ * locale may write as a `{placeholder}` in that code's sentence.
+ *
+ * **Why a declaration exists at all.** `params` crosses the wire with `message` so a translating
+ * client can render its own wording for a code (CLAUDE.md §Errors), and `interpolate` leaves a
+ * placeholder nobody supplied written out as `{apiAnswer}`. So a locale writing a placeholder is
+ * making a claim about a *call site*, and a call is not a declaration — there was nothing in this
+ * repository for a catalog test to read, which is why `@pithy-sh/i18n` could only pin the absence of
+ * placeholders. This is that missing half: one table, in `core`, that both sides import.
+ *
+ * **Guaranteed means every throw, not most.** A name belongs here only when the code's throw sites
+ * pass it on **every** path, including the degraded one — a Cloudflare call that never reached
+ * Cloudflare still supplies `apiAnswer`, as the empty string. A param a throw site passes only
+ * sometimes is still useful to a client reading `payload.params` directly, and is still stripped from
+ * nothing; it simply may not be written into a sentence, because the sentence has to render on the
+ * path where it is missing.
+ *
+ * A code absent from this table guarantees nothing, which is the honest default and the state of all
+ * but one of them.
+ */
+export const GUARANTEED_ERROR_PARAMS: Partial<Record<KitErrorCode, readonly string[]>> = {
+  // `@pithy-sh/cloudflare`'s `cloudflareRefusal` composes every Cloudflare refusal and always passes
+  // `apiAnswer`: Cloudflare's own code and sentence, punctuated to append (`": 10000 Authentication
+  // error"`), or `""` when the call failed without an answer. The value carries its own separator so
+  // one sentence renders correctly both ways — a locale cannot write an `if`.
+  "cloudflare/request_failed": ["apiAnswer"],
+};
+
+/** The names a locale may interpolate into `code`'s sentence. Empty when the code guarantees none. */
+export function guaranteedErrorParams(code: string): readonly string[] {
+  return GUARANTEED_ERROR_PARAMS[code as KitErrorCode] ?? [];
+}

package/src/error/terminal.ts

@@ -5,11 +5,22 @@ import type { ErrorPayload } from "./payload";
 import { PublicErrorPayload } from "./payload";
 
 /**
- * Render an error for the terminal: the public `message` becomes the problem line and the
- * optional `action` the action line — the two-line brand-voice shape `docs/CLI.md` §3.3 specifies.
- * This unifies the CLI's error output into the one `PithyError` family: the CLI catches a
- * `PithyError`, colorizes the first line via its `style.ts`, and prints this. `detail` is internal
- * and never rendered. The same payload that encodes to HTTP renders here — one error, two surfaces.
+ * Render an error for the terminal: the public `message` on top and the optional `action` last — the
+ * brand-voice shape `docs/CLI.md` §3.3 specifies. This unifies the CLI's error output into the one
+ * `PithyError` family: the CLI catches a `PithyError`, colorizes via its `style.ts`, and prints this.
+ * `detail` is internal and never rendered. The same payload that encodes to HTTP renders here — one
+ * error, two surfaces.
+ *
+ * **`message` is one line, and the newline this adds is the only one in the rendering.** #534 tried
+ * the other way — a problem line with an upstream's `errors[]` indented beneath it, which reads
+ * beautifully in a terminal and is unencodable everywhere else. The newline is a *field separator* in
+ * two places that matter more than the indent does. `../workflow/stepMessage` uses it to carry a
+ * terminal step's remedy across a durable boundary, so a multi-line `message` raised inside a Workflow
+ * step was declined whole and the operator got the platform's prose about durable execution instead of
+ * the refusal. And here, the action line is the one line after the message, so a `message` carrying a
+ * break puts upstream text where the remedy goes — a forged action line, from text a Worker we did not
+ * write can choose. Upstream words are marked with a word (`Cloudflare said:`), never with a line: a
+ * word survives a step record, a `--json` line and a browser.
  */
 export function renderTerminal(payload: ErrorPayload): string {
   return payload.action ? `${payload.message}\n${payload.action}` : payload.message;