@ultimat3/auth 11.1.0 → 11.2.0

package/CLAUDE.md

@@ -259,6 +259,21 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   and silently discarded a later caller's options, so an app pinning a corporate egress proxy got
   it only if it called first — the `jobs.driver` shape, with a network path as the substituted
   value. A caller that supplies options gets its own client.
+- **A wedged JWKS refresh no longer holds the shared slot for ever** (`As of 2026-08-23`).
+  `createJwksClient` single-flights its refresh through `@ultimat3/core`'s `createSingleFlight`,
+  with `deadlineMs = timeoutMs * 2` — derived, never a second invented number: `timeoutMs` bounds
+  the network leg (`AbortSignal.timeout`) and everything after it is local work on the same budget,
+  so doubling never evicts a slow-but-healthy refresh. It matters because `AbortSignal.timeout`
+  bounds only the DEFAULT transport and `options.fetch` is the app's — a `fetch` that ignores its
+  signal used to pin the slot for the life of the process, and every later `keyFor` joined a
+  promise nothing would resolve. **Eviction frees the KEY, never the work**: the wedged refresh
+  runs on and its own callers keep their promise, so the worst case is one duplicate JWKS fetch and
+  never a failed verification. `schedule` is injectable so no test waits a deadline out.
+  Its consequence is the second half and is not optional: two refreshes can now overlap and both
+  end by installing what they read, so a `createFence` generation check is what stops the one the
+  client gave up on from dropping a pre-rotation key set on top of the live one. Read
+  (`fence.generation() === issued`), never `guard` — a superseded refresh is still the honest
+  answer for the callers holding it, and only the shared cache is fenced.
 - **`verifyIdToken` checks `nbf` and `azp`.** `workload.ts` imports `ID_TOKEN_CLOCK_SKEW_MS` from
   `id-token.ts` and then enforced a bound `id-token.ts` did not: an `nbf` ten years out verified.
   `azp` is OIDC Core 3.1.3.7 step 5 — with more than one audience, `aud` naming this client says
@@ -301,8 +316,13 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   left was `http.maxInflight` (1000), about 19 GB of arenas queued. `kdf-gate.ts` bounds the width
   (8) and the waiting queue (64) and refuses past it with `X_OVERLOADED`, borrowed from http and
   listed in `AUTH_BORROWED_ERROR_CODES` — this package cannot import http, and a shed is a shed
-  whichever layer performs it. `configureKdfGate()` is the ONE install point and is deliberately
-  not a `defineAuth` key: the ceiling is a property of the machine, not of the app's auth policy.
+  whichever layer performs it. **The pool itself is `@ultimat3/core`'s `createFlightGate` since
+  2026-08-23** — the same hand-over-on-release rule, the same numbers — and the refusal stays this
+  package's through core's `overflow:` seam, so `kdfOverloaded` is still what a caller catches and
+  core's `X_FLIGHT_GATE_OVERLOADED` never leaves auth. No `subject:` is passed: it feeds only
+  `gateOverloaded`'s prose, which this gate never reaches. `configureKdfGate()` is the ONE install
+  point and is deliberately not a `defineAuth` key: the ceiling is a property of the machine, not
+  of the app's auth policy.
 - **MFA has a first leg and no second one, and the second one is not a route you can just add.**
   `login()` and `completeOAuthLogin()` throw `X_MFA_REQUIRED` before any session exists; nothing is
   written, so the only value handed over is a user id in `meta`. A `POST /auth/mfa/verify
@@ -385,7 +405,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `oauth-builtins.ts` | the three shipped IdPs, as data. Imports only the type, so no cycle |
 | `oauth-registry.ts` | the registry: `registerOAuthProvider`, `providerFor`, `oauthProviderIds` |
 | `oauth-discovery.ts` | `/.well-known/openid-configuration` → an `OAuthProvider`. One `fetch` |
-| `jwks.ts` | `crypto.subtle` signature verification, cached by `kid`. No dependency |
+| `jwks.ts` | `crypto.subtle` signature verification, cached by `kid`, one shared in-flight refresh. No dependency |
 | `workload.ts` | a workload JWT (K8s SA / SPIFFE / IMDS / RFC 8693) → a `ServiceIdentity` |
 | `revocation.ts` | per-user, per-org and before-an-instant sweeps; `disableUser` |
 | `directory.ts` | `describeUser` (allow-list projection), `listOrgUsers`, external-id lookup |
@@ -401,7 +421,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
 | `errors.ts` | the codes this package owns and borrows, their titles, the one `registerErrorCodes()` call, `AuthError`, and every non-OAuth factory |
 | `oauth-errors.ts` | the OAuth half of those factories, and `restartAt`. Split off at the 500-line ceiling; declares no code and registers nothing |
 | `oauth-route.ts` | `oauthLogin(auth)` — the redirect out and the callback back |
-| `kdf-gate.ts` | the one bound on concurrent argon2 work, and the `X_OVERLOADED` past it |
+| `kdf-gate.ts` | the one bound on concurrent argon2 work, and the `X_OVERLOADED` past it — core's `createFlightGate` with auth's own refusal injected |
 | `email.ts` | `normaliseEmail` — the one normalisation an address gets before it is an identity key |
 | `json.ts` | reading untrusted JSON: `isRecord`, and a base64url JWT segment as an object or `null` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "11.1.0",
+  "version": "11.2.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.1.0",
-    "@ultimat3/db": "11.1.0",
-    "@ultimat3/schema": "11.1.0"
+    "@ultimat3/core": "11.2.0",
+    "@ultimat3/db": "11.2.0",
+    "@ultimat3/schema": "11.2.0"
   }
 }

package/src/jwks.ts

@@ -6,8 +6,8 @@
 // unverified JWT with the right `iss`, `aud` and a victim's `sub` is a full account takeover with
 // no credential, so a signature check has to exist before those doors are opened.
 
-import type { Clock } from '@ultimat3/core';
-import { renderThrowable, systemClock } from '@ultimat3/core';
+import type { Clock, Scheduler } from '@ultimat3/core';
+import { createFence, createSingleFlight, renderThrowable, systemClock } from '@ultimat3/core';
 import { decodeJwtSegment, isRecord } from './json';
 import type { OAuthProvider } from './oauth';
 import { oauthExchangeFailed, oauthTokenInvalid } from './oauth-errors';
@@ -43,8 +43,24 @@ export type IdTokenKeys = 'token-endpoint-tls' | JwksKeySource;
 /** Short enough that a rotated key set is picked up on its own; a new `kid` refreshes early. */
 export const DEFAULT_JWKS_TTL_MS = 10 * 60 * 1000;
 
+/** One client is one key set, so the flight has exactly one key and its name is never read. */
+const REFRESH_KEY = 'jwks';
+
 const DEFAULT_TIMEOUT_MS = 10_000;
 
+/**
+ * How much longer than the TRANSPORT's own bound one refresh may hold the shared slot, before a
+ * later caller is allowed to start its own instead of joining it.
+ *
+ * Derived from `timeoutMs` rather than a second unrelated number, because the two answer the same
+ * question at two layers: `timeoutMs` is the network leg (`AbortSignal.timeout` below), and
+ * everything after it — reading the body, importing one `CryptoKey` per published JWK — is local
+ * work on the same budget. Doubling gives that second half as much wall clock as the first, so a
+ * slow-but-healthy refresh is never evicted, while a `fetch` that IGNORES its signal (which
+ * `options.fetch` is app-supplied and free to do) is let go of at twice its own stated bound.
+ */
+const JWKS_DEADLINE_FACTOR = 2;
+
 export interface JwksClientOptions {
   /** Named in every refusal this client throws. */
   readonly provider: string;
@@ -55,6 +71,8 @@ export interface JwksClientOptions {
   readonly clock?: Clock | undefined;
   readonly ttlMs?: number | undefined;
   readonly timeoutMs?: number | undefined;
+  /** Injected so the refresh deadline is provable without a test waiting one out. */
+  readonly schedule?: Scheduler | undefined;
 }
 
 const importParams = (alg: JwtAlgorithm): RsaHashedImportParams | EcKeyImportParams =>
@@ -94,22 +112,29 @@ const algorithmOf = (jwk: Record<string, unknown>): JwtAlgorithm | null => {
 export function createJwksClient(options: JwksClientOptions): JwksKeySource {
   const clock = options.clock ?? systemClock;
   const ttlMs = options.ttlMs ?? DEFAULT_JWKS_TTL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   let keys = new Map<string, CryptoKey>();
   let fetchedAtMs = Number.NEGATIVE_INFINITY;
   // When the last UNKNOWN-`kid` refresh ran, tracked apart from `fetchedAtMs` because that field
   // is reset by every fetch, ordinary ones included — so gating the early refresh on it would let
   // an attacker's own refresh authorise the next one.
   let lastMissRefreshMs = Number.NEGATIVE_INFINITY;
-  let inflight: Promise<Map<string, CryptoKey>> | null = null;
+  // Two refreshes can overlap once the deadline below can evict one, and BOTH end by installing
+  // what they read. Without this, the later-settling of the two wins — so a refresh the client
+  // already gave up on could drop a pre-rotation key set on top of the live one, and every login
+  // against the new `kid` would start missing again. Read, never `guard`: a superseded refresh is
+  // still the honest answer for the callers holding it, and only the shared cache is fenced.
+  const fence = createFence('the published jwks key set');
 
   const fetchKeys = async (): Promise<Map<string, CryptoKey>> => {
+    const issued = fence.bump();
     const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     let response: Response;
     try {
       response = await doFetch(options.jwksUri, {
         method: 'GET',
         headers: { Accept: 'application/json' },
-        signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        signal: AbortSignal.timeout(timeoutMs),
       });
     } catch (error) {
       throw oauthExchangeFailed({
@@ -145,19 +170,30 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
         .catch(() => null);
       if (key !== null) next.set(`${kid}:${alg}`, key);
     }
-    keys = next;
-    fetchedAtMs = clock.now().getTime();
+    if (fence.generation() === issued) {
+      keys = next;
+      fetchedAtMs = clock.now().getTime();
+    }
     return next;
   };
 
   // One in-flight refresh shared by every concurrent caller: a cold cache under load is otherwise
   // one outbound request per request in flight, against the IdP, at exactly the worst moment.
-  const load = async (): Promise<Map<string, CryptoKey>> => {
-    inflight ??= fetchKeys().finally(() => {
-      inflight = null;
-    });
-    return await inflight;
-  };
+  //
+  // The deadline is why this is `@ultimat3/core`'s and not a local `inflight ??=`. A refresh that
+  // never settles used to hold the slot for the life of the process, and every later caller joined
+  // a promise nothing would resolve — `AbortSignal.timeout` bounds only the DEFAULT transport, and
+  // `options.fetch` is the app's. Eviction frees the KEY and nothing else: the wedged refresh keeps
+  // running, its own callers keep their promise, and the fence above stops its late answer from
+  // landing in the cache. So the worst case is one duplicate JWKS fetch, never a failed
+  // verification — which is what makes a deadline here a fix rather than a risk.
+  const flight = createSingleFlight({
+    deadlineMs: timeoutMs * JWKS_DEADLINE_FACTOR,
+    schedule: options.schedule,
+  });
+
+  const load = async (): Promise<Map<string, CryptoKey>> =>
+    await flight.run(REFRESH_KEY, fetchKeys);
 
   const lookup = (current: Map<string, CryptoKey>, kid: string | null, alg: JwtAlgorithm) => {
     if (kid !== null) return current.get(`${kid}:${alg}`) ?? null;
@@ -180,7 +216,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
       // cannot shed it, because `auth` is pipeline stage 6 and `rate-limit` is stage 7. So the
       // early refresh is rate-limited by the same TTL as the ordinary one — which is what the
       // docstring above always promised. Set BEFORE the await so concurrent callers that pass the
-      // gate together still coalesce into the one `inflight` fetch.
+      // gate together still coalesce into the one shared refresh.
       const earlyRefresh = !known && !stale && nowMs >= lastMissRefreshMs + ttlMs;
       if (earlyRefresh) lastMissRefreshMs = nowMs;
       if (stale || earlyRefresh) current = await load();

package/src/kdf-gate.ts

@@ -6,6 +6,7 @@
 // what argon2id costs is MEMORY — 19 MiB per hash at the OWASP floor. The only remaining backstop
 // was `http.maxInflight` (1000), i.e. roughly 19 GB of arenas queued on one box.
 
+import { createFlightGate } from '@ultimat3/core';
 import { kdfOverloaded } from './errors';
 
 export interface KdfLimits {
@@ -27,42 +28,24 @@ export interface KdfGate {
 }
 
 /**
- * A slot is HANDED OVER on release rather than released and re-acquired: decrementing first would
- * let a caller arriving in the same tick past the ceiling while a waiter's continuation is still
- * a queued microtask, which is how a "bounded" pool goes over its bound under exactly the load it
- * exists for.
+ * The mechanism is `@ultimat3/core`'s — including the rule that made this file worth having: a
+ * slot is HANDED OVER on release rather than released and re-acquired, because decrementing first
+ * would let a caller arriving in the same tick past the ceiling while a waiter's continuation is
+ * still a queued microtask.
+ *
+ * `overflow:` is why delegating costs this package nothing: the shed stays `kdfOverloaded`, so the
+ * code an HTTP client already reads as a 503 is still `X_OVERLOADED` and core's own
+ * `X_FLIGHT_GATE_OVERLOADED` never leaves this package. `subject:` is deliberately not passed —
+ * it feeds only `gateOverloaded`'s prose, which this gate never reaches, and an option nothing
+ * reads is the defect this repo keeps re-shipping.
+ *
+ * The declared return type stays `KdfGate` rather than core's `FlightGate`: `active` and `queued`
+ * are observations no caller here has ever had, and widening a public signature is not a refactor.
  */
 export function createKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
-  let active = 0;
-  const waiters: Array<() => void> = [];
-
-  const acquire = async (): Promise<void> => {
-    if (active < limits.maxConcurrent) {
-      active += 1;
-      return;
-    }
-    if (waiters.length >= limits.maxQueued) throw kdfOverloaded(active, waiters.length);
-    await new Promise<void>((resolve) => {
-      waiters.push(resolve);
-    });
-  };
-
-  const release = (): void => {
-    const next = waiters.shift();
-    if (next === undefined) active -= 1;
-    else next();
-  };
-
-  return {
-    async run<T>(work: () => Promise<T>): Promise<T> {
-      await acquire();
-      try {
-        return await work();
-      } finally {
-        release();
-      }
-    },
-  };
+  return createFlightGate(limits, {
+    overflow: (state) => kdfOverloaded(state.active, state.queued),
+  });
 }
 
 let gate = createKdfGate();