@pithy-sh/core 0.3.1 → 0.4.0

package/dist/capability/capability.d.ts

@@ -153,6 +153,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}. */
 export type SecretRegistrySeam = Record<string, SecretRegistryEntrySeam>;
@@ -183,6 +193,34 @@ export type SecretRegistrySeam = Record<string, SecretRegistryEntrySeam>;
  * secret whose schema has no branches at all needs no declaration — every field is asked.
  */
 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
@@ -313,6 +351,12 @@ export interface Capability<Databases extends DatabaseSpecMap = DatabaseSpecMap,
      * 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/dist/capability/capability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/capability/capability.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/capability/capability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,6GAA6G;AAC7G,MAAM,WAAW,SAAS;IACxB,kGAAkG;IAClG,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB;;;;;;;OAOG;IACH,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B;;;;;;;OAOG;IACH,CAAC,EAAE,UAAU,CAAC;IACd;;;;;;;;;OASG;IACH,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC;;;;;;;;OAQG;IACH,oBAAoB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAClD;;;;;;;;;OASG;IACH,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC;;;;;OAKG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;;OAQG;IACH,YAAY,EAAE,mBAAmB,CAAC;IAClC;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,EAAE,EAAE,OAAO,CAAC;IACZ;;;;OAIG;IACH,EAAE,EAAE,OAAO,CAAC;IACZ;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,iHAAiH;AACjH,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAEvF,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,2FAA2F;AAC3F,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,uGAAuG;IACvG,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,uGAAuG;IACvG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0GAA0G;IAC1G,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,mFAAmF;AACnF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,qGAAqG;IACrG,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,OAAO,EAAE,uBAAuB,EAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,gBAAgB,KAClB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU,CACzB,SAAS,SAAS,eAAe,GAAG,eAAe,EACnD,UAAU,SAAS,kBAAkB,GAAG,kBAAkB,EAC1D,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,SAAS,SAAS,eAAe,GAAG,eAAe;IAEnD;;;;OAIG;IACH,IAAI,EAAE,IAAI,CAAC;IACX;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,wDAAwD;IACxD,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACnB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,sBAAsB,CAAC;IAC7C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;IACtD;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;IACnD,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;IAC3C,+DAA+D;IAC/D,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,gBAAgB,CAAC;IAChE;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C,yFAAyF;IACzF,gBAAgB,EAAE,WAAW,EAAE,CAAC;CACjC;AAED,mGAAmG;AACnG,MAAM,MAAM,eAAe,CACzB,SAAS,SAAS,eAAe,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACxD,UAAU,SAAS,kBAAkB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,SAAS,SAAS,eAAe,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IACtD,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,kBAAkB,CAAC,GAAG;IACjF,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;CACtC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,SAAS,SAAS,eAAe,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC9D,KAAK,CAAC,UAAU,SAAS,kBAAkB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAClE,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAClC,KAAK,CAAC,SAAS,SAAS,eAAe,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC9D,KAAK,EAAE,eAAe,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,GAAG,UAAU,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,CAKpH;AAED,sGAAsG;AACtG,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpH,kFAAkF;AAClF,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EAAE,kBAAkB,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE7G,sFAAsF;AACtF,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3G;;;;;GAKG;AACH,KAAK,gBAAgB,CAAC,CAAC,IACrB,CAAC,SAAS,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,MAAM,IAAI,EAAE,MAAM,CAAC,CAAC,GAC1E;KAAG,GAAG,IAAI,MAAM,CAAC,GAAG,MAAM,IAAI,GAAG,IAAI,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;CAAE,GAC5E,KAAK,CAAC;AAEZ;;;;GAIG;AACH,KAAK,YAAY,CAAC,MAAM,EAAE,KAAK,IAC7B,mBAAmB,CAAC,MAAM,CAAC,SAAS,MAAM,MAAM,GAAG,CAAC,MAAM,SAAS,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC;AAEpH,sFAAsF;AACtF,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI,YAAY,CAC5E,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EACzB,eAAe,CAChB,CAAC;AAEF,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI,YAAY,CAC/E,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAC1B,kBAAkB,CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI,YAAY,CACjF,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,CAAC"}

package/dist/http/oidcWebhook.d.ts

@@ -46,17 +46,20 @@ import type { PithyHonoEnv } from "../capability/capability";
  * ## 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 type { PithyHonoEnv } from "../capability/capability";
  * 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. */
 export declare 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.
+ */
+export declare const OIDC_JWKS_MIN_REFRESH_SECONDS = 60;
 /** Tolerance on `exp`, `nbf` and `iat`. A minute covers clock drift; an hour would cover a replay. */
 export declare const OIDC_CLOCK_SKEW_SECONDS = 60;
 /**
@@ -151,20 +175,43 @@ export declare const oidcJwksFetch: OidcJwksFetch;
  * over KV or the Cache API and shares it across isolates.
  *
  * **Owning the store is not the same as having none.** {@link requireOidcWebhook} builds one per guard when a
- * route gives none, because the guard is the surface anonymous traffic arrives on: with no cache, a 49-byte
- * forged token naming a published `kid` buys a round trip to the issuer, 1:1, until the issuer rate-limits us
- * and the real deliveries 502 alongside the forgeries. {@link verifyOidcToken} called directly is the other
- * case and does fetch per call — its caller holds one token it has already decided to check, so there is no
- * flood to absorb and no cache to acquire by surprise.
+ * route gives none, because the guard is the surface anonymous traffic arrives on: with no store, a 49-byte
+ * forged token buys a round trip to the issuer, 1:1, until the issuer rate-limits us and the real deliveries
+ * 502 alongside the forgeries. {@link verifyOidcToken} called directly is the other case and does fetch per
+ * call — its caller holds one token it has already decided to check, so there is no flood to absorb and no
+ * cache to acquire by surprise.
+ *
+ * **Two facts, not one, and the second is the one that bounds an attacker.** `get`/`set` hold what the issuer
+ * published, which answers a `kid` we have seen. {@link claimRefresh} holds *when we last asked*, which is
+ * what answers a `kid` we have not — and that is the whole of the miss path, where an unverified header used
+ * to buy an outbound request per delivery. Both live in the store rather than in a closure so that a store
+ * shared across isolates (KV, the Cache API) shares the bound too: one ask per window for the deployment,
+ * not one per isolate.
  *
  * Public keys, so nothing here is what CLAUDE.md's secrets rule governs: the whole point of a JWKS endpoint
- * is that anyone may read it. What the cache buys is one round trip per TTL instead of one per delivery.
+ * is that anyone may read it. What the store buys is one round trip per TTL on the hit path and one per
+ * {@link OIDC_JWKS_MIN_REFRESH_SECONDS} on the miss path, instead of one per delivery on both.
  */
 export interface JwksCache {
     /** The key set held for `url`, or `undefined` when nothing usable is held. */
     get(url: string): Promise<readonly OidcJwk[] | undefined>;
     /** Hold a freshly fetched key set for `url` for `ttlSeconds`. */
     set(url: string, keys: readonly OidcJwk[], ttlSeconds: number): Promise<void>;
+    /**
+     * **May the issuer's endpoint be asked for `url` right now?** `true` grants the ask and records it for
+     * `seconds`; `false` says somebody already asked inside that window.
+     *
+     * One call rather than a read and a write, because the question and the claim are the same act: two
+     * deliveries that both read *nobody has asked* and then both ask are the flood this exists to stop. An
+     * implementation decides and records before it yields — {@link memoryJwksCache} does it synchronously
+     * inside the promise, so concurrent deliveries in one isolate produce exactly one ask. A store over a
+     * network is best-effort about that, and best-effort is still a bound.
+     *
+     * It is about the *ask*, never about the answer, which is what keeps a failing endpoint from being a
+     * second amplifier: a refresh that ends in `core/upstream_failed` has still spent the window, so a flood
+     * arriving while the issuer is down costs one attempt per window rather than one per delivery.
+     */
+    claimRefresh(url: string, seconds: number): Promise<boolean>;
 }
 /**
  * A key cache in memory, expiring on a clock the caller owns.
@@ -205,6 +252,10 @@ export interface OidcWebhookScheme {
     /**
      * How long a fetched key set is held. Defaults to {@link OIDC_JWKS_TTL_SECONDS} and must be a finite number
      * of seconds — a `NaN` is an entry that never expires, which pins a key the issuer has rotated out.
+     *
+     * Keep it above {@link OIDC_JWKS_MIN_REFRESH_SECONDS}. Below it, a set expires while the window that
+     * governs re-asking is still spent, and every delivery in the gap is answered `core/upstream_failed`
+     * because nothing is held and nothing may be asked. An hour against a minute is not close to that line.
      */
     jwksTtlSeconds?: number;
     /**
@@ -236,9 +287,11 @@ export interface OidcWebhookGuardOptions extends OidcWebhookScheme {
  * 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.
  */
 export declare function verifyOidcToken(token: string, options: VerifyOidcTokenOptions): Promise<OidcClaims>;
 /**
@@ -252,21 +305,24 @@ export declare function verifyOidcToken(token: string, options: VerifyOidcTokenO
  * 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
  *

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

@@ -1 +1 @@
-{"version":3,"file":"oidcWebhook.d.ts","sourceRoot":"","sources":["../../src/http/oidcWebhook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oidcWebhook.d.ts","sourceRoot":"","sources":["../../src/http/oidcWebhook.ts"],"names":[],"mappings":"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"}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.3.1",
+  "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/http/oidcWebhook.ts

@@ -49,17 +49,20 @@ import { InternalError, UpstreamError, WebhookUnverifiedError } from "../error/p
  * ## 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
@@ -69,9 +72,31 @@ import { InternalError, UpstreamError, WebhookUnverifiedError } from "../error/p
  * 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. */
 export 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.
+ */
+export const OIDC_JWKS_MIN_REFRESH_SECONDS = 60;
+
 /** Tolerance on `exp`, `nbf` and `iat`. A minute covers clock drift; an hour would cover a replay. */
 export const OIDC_CLOCK_SKEW_SECONDS = 60;
 
@@ -210,20 +235,43 @@ export const oidcJwksFetch: OidcJwksFetch = (url) => fetch(url) as unknown as Pr
  * over KV or the Cache API and shares it across isolates.
  *
  * **Owning the store is not the same as having none.** {@link requireOidcWebhook} builds one per guard when a
- * route gives none, because the guard is the surface anonymous traffic arrives on: with no cache, a 49-byte
- * forged token naming a published `kid` buys a round trip to the issuer, 1:1, until the issuer rate-limits us
- * and the real deliveries 502 alongside the forgeries. {@link verifyOidcToken} called directly is the other
- * case and does fetch per call — its caller holds one token it has already decided to check, so there is no
- * flood to absorb and no cache to acquire by surprise.
+ * route gives none, because the guard is the surface anonymous traffic arrives on: with no store, a 49-byte
+ * forged token buys a round trip to the issuer, 1:1, until the issuer rate-limits us and the real deliveries
+ * 502 alongside the forgeries. {@link verifyOidcToken} called directly is the other case and does fetch per
+ * call — its caller holds one token it has already decided to check, so there is no flood to absorb and no
+ * cache to acquire by surprise.
+ *
+ * **Two facts, not one, and the second is the one that bounds an attacker.** `get`/`set` hold what the issuer
+ * published, which answers a `kid` we have seen. {@link claimRefresh} holds *when we last asked*, which is
+ * what answers a `kid` we have not — and that is the whole of the miss path, where an unverified header used
+ * to buy an outbound request per delivery. Both live in the store rather than in a closure so that a store
+ * shared across isolates (KV, the Cache API) shares the bound too: one ask per window for the deployment,
+ * not one per isolate.
  *
  * Public keys, so nothing here is what CLAUDE.md's secrets rule governs: the whole point of a JWKS endpoint
- * is that anyone may read it. What the cache buys is one round trip per TTL instead of one per delivery.
+ * is that anyone may read it. What the store buys is one round trip per TTL on the hit path and one per
+ * {@link OIDC_JWKS_MIN_REFRESH_SECONDS} on the miss path, instead of one per delivery on both.
  */
 export interface JwksCache {
   /** The key set held for `url`, or `undefined` when nothing usable is held. */
   get(url: string): Promise<readonly OidcJwk[] | undefined>;
   /** Hold a freshly fetched key set for `url` for `ttlSeconds`. */
   set(url: string, keys: readonly OidcJwk[], ttlSeconds: number): Promise<void>;
+  /**
+   * **May the issuer's endpoint be asked for `url` right now?** `true` grants the ask and records it for
+   * `seconds`; `false` says somebody already asked inside that window.
+   *
+   * One call rather than a read and a write, because the question and the claim are the same act: two
+   * deliveries that both read *nobody has asked* and then both ask are the flood this exists to stop. An
+   * implementation decides and records before it yields — {@link memoryJwksCache} does it synchronously
+   * inside the promise, so concurrent deliveries in one isolate produce exactly one ask. A store over a
+   * network is best-effort about that, and best-effort is still a bound.
+   *
+   * It is about the *ask*, never about the answer, which is what keeps a failing endpoint from being a
+   * second amplifier: a refresh that ends in `core/upstream_failed` has still spent the window, so a flood
+   * arriving while the issuer is down costs one attempt per window rather than one per delivery.
+   */
+  claimRefresh(url: string, seconds: number): Promise<boolean>;
 }
 
 /**
@@ -236,6 +284,8 @@ export interface JwksCache {
 export function memoryJwksCache(options: { now?: () => Date } = {}): JwksCache {
   const now = options.now ?? (() => new Date());
   const held = new Map<string, { keys: readonly OidcJwk[]; expiresAt: number }>();
+  /** When the endpoint behind each url may be asked again. The miss path's whole state. */
+  const askedUntil = new Map<string, number>();
   return {
     get: async (url) => {
       const entry = held.get(url);
@@ -249,6 +299,16 @@ export function memoryJwksCache(options: { now?: () => Date } = {}): JwksCache {
     set: async (url, keys, ttlSeconds) => {
       held.set(url, { keys, expiresAt: now().getTime() + ttlSeconds * 1000 });
     },
+    // Decided and recorded with no `await` between the read and the write, which is what makes this a claim
+    // rather than a check: an isolate handling a thousand concurrent forgeries runs this body a thousand
+    // times and grants it once. The async signature is the seam's, for the stores that do reach a network.
+    claimRefresh: async (url, seconds) => {
+      const at = now().getTime();
+      const until = askedUntil.get(url);
+      if (until !== undefined && until > at) return false;
+      askedUntil.set(url, at + seconds * 1000);
+      return true;
+    },
   };
 }
 
@@ -281,6 +341,10 @@ export interface OidcWebhookScheme {
   /**
    * How long a fetched key set is held. Defaults to {@link OIDC_JWKS_TTL_SECONDS} and must be a finite number
    * of seconds — a `NaN` is an entry that never expires, which pins a key the issuer has rotated out.
+   *
+   * Keep it above {@link OIDC_JWKS_MIN_REFRESH_SECONDS}. Below it, a set expires while the window that
+   * governs re-asking is still spent, and every delivery in the gap is answered `core/upstream_failed`
+   * because nothing is held and nothing may be asked. An hour against a minute is not close to that line.
    */
   jwksTtlSeconds?: number;
   /**
@@ -315,9 +379,11 @@ export interface OidcWebhookGuardOptions extends OidcWebhookScheme {
  * 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.
  */
 export async function verifyOidcToken(token: string, options: VerifyOidcTokenOptions): Promise<OidcClaims> {
   // Ours before theirs. An endpoint with nothing to check against refuses every delivery, and calling that an
@@ -435,21 +501,24 @@ export async function verifyOidcToken(token: string, options: VerifyOidcTokenOpt
  * 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
  *
@@ -482,22 +551,52 @@ export function requireOidcWebhook(options: OidcWebhookGuardOptions): Middleware
 }
 
 /**
- * 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: string, options: VerifyOidcTokenOptions): Promise<OidcJwk> {
-  const held = await options.jwksCache?.get(options.jwksUrl);
+  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 !== undefined && !(await cache.claimRefresh(options.jwksUrl, OIDC_JWKS_MIN_REFRESH_SECONDS))) {
+    if (held === undefined || held.length === 0) {
+      throw upstream(
+        `The OIDC key endpoint ${options.jwksUrl} was asked within the last ${OIDC_JWKS_MIN_REFRESH_SECONDS} 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 ${OIDC_JWKS_MIN_REFRESH_SECONDS} seconds.`,
+    );
+  }
+
   const refreshed = await fetchJwks(options);
-  await options.jwksCache?.set(options.jwksUrl, refreshed, options.jwksTtlSeconds ?? OIDC_JWKS_TTL_SECONDS);
+  await cache?.set(options.jwksUrl, refreshed, options.jwksTtlSeconds ?? OIDC_JWKS_TTL_SECONDS);
   const found = refreshed.find((key) => key.kid === kid);
   if (!found) {
     throw unverified(`no key the issuer publishes matches the token's kid ${snippet(kid)}.`);
@@ -541,17 +640,33 @@ async function fetchJwks(options: VerifyOidcTokenOptions): Promise<OidcJwk[]> {
   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: OidcJwk): Promise<CryptoKey> {
   if (jwk.kty !== "RSA") {
-    throw upstream(`Published key ${snippet(jwk.kid)} is ${snippet(jwk.kty)}, and only RSA keys sign an OIDC token.`);
+    throw unverified(
+      `the token's kid ${snippet(jwk.kid)} names a ${snippet(jwk.kty)} key, and only RSA keys sign an OIDC token.`,
+    );
   }
   try {
     // `alg` is forced to `RS256` rather than taken from the published key: the algorithm is already pinned by
     // the header literal, and a key set that published a different one would otherwise decide it for us.
     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);
   }
 }
 

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/core";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.3.1";
+export const PACKAGE_VERSION = "0.4.0";