@ultimat3/auth 19.2.0 → 19.3.2

package/CLAUDE.md

@@ -214,6 +214,14 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   the SESSION write is safe; caching the USER row is not — `authenticate` re-reads it on every
   request, and that is what makes a revoked role take effect on the next one with no token-expiry
   lag. Do not cache it.
+
+  **In `verifySession`'s `observed`, `null` is an ANSWER and `undefined` is silence**
+  (`As of 2026-09-06`). `observed?.ip ?? session.ip` collapsed the two, so an explicit
+  `{ ip: null }` — this request had no client address — could not clear a stale stored one: the
+  address from an earlier request was written forward on every verify, and the device list a user
+  checks for a session they do not recognise showed it as current. An observation that names
+  neither field still costs no write, because a change nobody reported would turn every
+  authenticated request back into a write on the hottest table there is.
 - A user's `scopes` column reaches `Actor.scopes`. Hardcoding `[]` there made a scope something no
   human could hold, so `hasScope(actor, 'tenancy:cross')` was satisfiable only by minting a
   `serviceActor` inside the handler — which discards the operator's identity and makes the sweep
@@ -253,6 +261,33 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   These three renders stay and are not a second path: `renderCauseValue` also QUOTES, which is what
   makes a forged `iss` legible as a value rather than as prose — the constructor is a floor under
   every field, not a replacement for saying which value is foreign.
+
+  **A `fix:` a SHELL reads takes `renderFixShellArg` instead, `As of 2026-09`.**
+  `oauth-discovery.ts` composed `curl -sS -m 5 ${url}` from `discoveryUrl(input.issuer)` at four
+  sites, and `new URL()` keeps `$`, `(`, `)` and backticks in a path — so an issuer one boot
+  mistake away from hostile wrote the command substitution into the line a reader pastes.
+  `renderFixLiteral` cannot stand in for it: it answers DOUBLE quotes, in which `$(…)` is still
+  live. The two are used side by side in that file — the shell renderer for the four `curl`/prose
+  lines, `renderFixLiteral` for the one that is a `registerOAuthProvider({ id: … })` call, where
+  quoting IS the escape and a bare `'${id}'` broke on an apostrophe.
+
+  **Every OAuth endpoint in a command position is screened, not just the discovery URL** (`As of
+  2026-09-06`). `jwks.ts` (three lines, one `probe` const), `oauth-profile.ts`'s userinfo probe and
+  `oauth-exchange.ts`'s token probe each composed `curl … ${url}` from `providerFor(id)`, and that
+  registry is filled by `discoverOAuthProvider` — the ISSUER's own document — as well as by the
+  app. `oauth-exchange.ts`'s own comment claimed `url` was "a framework constant"; it has not been
+  one since `registerOAuthProvider` opened, and the comment says so now. The value still rides in
+  the `cause` on the two legs whose detail names the host; `X_OAUTH_EXCHANGE_FAILED` carries no
+  `meta` passthrough.
+
+  **A screened value is half the contract; the LINE has to run** (`As of 2026-09-06`). A
+  placeholder is honest text and is not a command — `curl -sS -m 5 <the provider jwks_uri>` is read
+  by a shell as a redirection from a file called `the`, so the one instruction the reader was
+  handed fails, which is axiom 4 inverted. `jwks.ts`'s three lines share one `readTheKeySet(tail)`:
+  `isFixShellSafe` (core, the predicate `renderFixShellArg` is itself built on) decides, and the
+  whole fix degrades to PROSE naming the discovery document when the URI does not travel.
+  `oauth-discovery.ts` still owes the same repair and is what keeps `auth` on
+  `FIX_SHELL_ARG_PINS`.
 - `readCookie` never throws on a malformed value. The `Cookie:` header is attacker-controlled and
   `decodeURIComponent('%')` is a bare `URIError`, which would escape every coded path in this
   package — the raw value goes to the signature or hash check, which is the readable refusal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "19.2.0",
+  "version": "19.3.2",
   "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": "19.2.0",
-    "@ultimat3/db": "19.2.0",
-    "@ultimat3/schema": "19.2.0"
+    "@ultimat3/core": "19.3.2",
+    "@ultimat3/db": "19.3.2",
+    "@ultimat3/schema": "19.3.2"
   }
 }

package/src/jwks.ts

@@ -7,7 +7,14 @@
 // no credential, so a signature check has to exist before those doors are opened.
 
 import type { Clock, Scheduler } from '@ultimat3/core';
-import { createFence, createSingleFlight, renderThrowable, systemClock } from '@ultimat3/core';
+import {
+  createFence,
+  createSingleFlight,
+  isFixShellSafe,
+  renderFixShellArg,
+  renderThrowable,
+  systemClock,
+} from '@ultimat3/core';
 import { decodeJwtSegment, isRecord } from './json';
 import type { OAuthProvider } from './oauth';
 import { oauthExchangeFailed, oauthTokenInvalid } from './oauth-errors';
@@ -138,6 +145,23 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
   // 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');
+  // All three refusals below put this URI in a COMMAND position, and it came out of the ISSUER's
+  // own discovery document — `jwks_uri` is remote text, and `new URL()` keeps `$`, `(`, `)` and a
+  // backtick in a path. `renderFixLiteral` is the wrong tool here, because its double quotes leave
+  // `$(…)` live. Same screen, same reason, as `oauth-discovery.ts`'s `target`.
+  //
+  // The whole line degrades rather than the value alone: a PLACEHOLDER is honest text and is not a
+  // runnable command — `curl -sS -m 5 <the provider jwks_uri>` is read by a shell as a redirection
+  // from a file called `the`, so the one instruction the reader was handed fails, which is axiom 4
+  // inverted. `isFixShellSafe` is the predicate `renderFixShellArg` is itself built on, so the two
+  // cannot disagree about which URIs travel.
+  const spellable = isFixShellSafe(options.jwksUri);
+  const probe = renderFixShellArg(options.jwksUri, '<the provider jwks_uri>');
+  /** `curl` when the URI survives being read verbatim, prose naming what to fetch when it does not. */
+  const readTheKeySet = (tail: string): string =>
+    spellable
+      ? `curl -sS -m 5 ${probe}${tail}`
+      : `fetch the jwks_uri from ${options.provider}'s discovery document by hand — this one carries shell syntax, so no pasteable command can name it${tail}`;
 
   const fetchKeys = async (): Promise<Map<string, CryptoKey>> => {
     const issued = fence.bump();
@@ -156,7 +180,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
         // `renderThrowable`: this catch is the last frame that can still answer with a code, and
         // the `kid` that got here came out of an attacker-supplied JWT header.
         detail: renderThrowable(error),
-        fix: `curl -sS -m 5 ${options.jwksUri}`,
+        fix: readTheKeySet(''),
       });
     }
     if (!response.ok) {
@@ -165,7 +189,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
         stage: 'jwks',
         detail: 'the key set could not be read, so no signature can be checked',
         status: response.status,
-        fix: `curl -sS -m 5 ${options.jwksUri}`,
+        fix: readTheKeySet(''),
       });
     }
     const body: unknown = await response.json().catch(() => undefined);
@@ -238,7 +262,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
         throw oauthTokenInvalid(
           options.provider,
           `no ${alg} key in the published set matches this token's kid`,
-          `curl -sS -m 5 ${options.jwksUri}   # then confirm the token was signed by this issuer`,
+          readTheKeySet('   # then confirm the token was signed by this issuer'),
         );
       }
       return key;

package/src/oauth-discovery.ts

@@ -3,7 +3,7 @@
 // boot, no dependency — an enterprise IdP is then three lines instead of a hand-copied table of
 // four endpoints that nobody re-checks when the vendor moves one.
 
-import { renderThrowable } from '@ultimat3/core';
+import { renderFixLiteral, renderFixShellArg, renderThrowable } from '@ultimat3/core';
 import { isRecord } from './json';
 import type { OAuthProvider } from './oauth';
 import { oauthExchangeFailed } from './oauth-errors';
@@ -54,6 +54,13 @@ export async function discoverOAuthProvider(
   input: DiscoverOAuthProviderInput,
 ): Promise<OAuthProvider> {
   const url = discoveryUrl(input.issuer);
+  // Every `fix:` below puts this URL in a COMMAND position, and `new URL()` keeps `$`, `(`, `)`
+  // and backticks in a path — so an issuer one boot mistake away from hostile composes the shell
+  // line the framework tells its reader to paste. `renderFixShellArg` passes an ordinary issuer
+  // through untouched and substitutes the shape to fill in for anything a shell would read;
+  // `renderFixLiteral` is the wrong tool for a command, because its double quotes leave `$(…)`
+  // live.
+  const target = renderFixShellArg(url, '<issuer>/.well-known/openid-configuration');
   const doFetch: OAuthFetch = input.fetch ?? ((target, init) => globalThis.fetch(target, init));
   // Screened OUTSIDE the try below, deliberately: `AbortSignal.timeout(NaN)` throws, and the
   // catch around this fetch renders every throw as a provider failure — so a typo in the app's
@@ -79,7 +86,7 @@ export async function discoverOAuthProvider(
       // `renderThrowable`: an injected `fetch` may reject with anything, `instanceof` throws on a
       // value that traps `getPrototypeOf`, and a bare `TypeError` here is an uncoded crash.
       detail: renderThrowable(error),
-      fix: `curl -sS -m 5 ${url}`,
+      fix: `curl -sS -m 5 ${target}`,
     });
   }
 
@@ -89,7 +96,7 @@ export async function discoverOAuthProvider(
       stage: 'discovery',
       detail: 'the issuer published no discovery document at the well-known path',
       status: response.status,
-      fix: `curl -sS -m 5 ${url}   # then pass the real issuer URL to discoverOAuthProvider({ issuer })`,
+      fix: `curl -sS -m 5 ${target}   # then pass the real issuer URL to discoverOAuthProvider({ issuer })`,
     });
   }
 
@@ -99,7 +106,7 @@ export async function discoverOAuthProvider(
       provider: input.id,
       stage: 'discovery',
       detail: 'the discovery document is not a JSON object',
-      fix: `confirm ${url} is the OP's own discovery document and not a login page`,
+      fix: `confirm ${target} is the OP's own discovery document and not a login page`,
     });
   }
 
@@ -113,7 +120,7 @@ export async function discoverOAuthProvider(
       detail:
         'the discovery document is missing issuer, authorization_endpoint or token_endpoint, ' +
         'so no handshake can be built from it',
-      fix: `curl -sS -m 5 ${url} | jq '{issuer, authorization_endpoint, token_endpoint}'`,
+      fix: `curl -sS -m 5 ${target} | jq '{issuer, authorization_endpoint, token_endpoint}'`,
     });
   }
 
@@ -126,7 +133,10 @@ export async function discoverOAuthProvider(
       stage: 'discovery',
       detail:
         'the discovery document publishes no jwks_uri, so no id token from it can be verified',
-      fix: `register this provider by hand with an explicit jwksUri: registerOAuthProvider({ id: '${input.id}', ... })`,
+      // `renderFixLiteral` and not the shell renderer: this fix is a JS call, where quoting IS
+      // the escape. A bare interpolation inside the single quotes it used to carry meant an id
+      // holding an apostrophe closed the literal and printed a fix that does not parse.
+      fix: `register this provider by hand with an explicit jwksUri: registerOAuthProvider({ id: ${renderFixLiteral(input.id, "'<id>'")}, ... })`,
     });
   }
 

package/src/oauth-exchange.ts

@@ -8,6 +8,7 @@ import {
   EnvMissingError,
   logger,
   renderCauseValue,
+  renderFixShellArg,
   renderThrowable,
   systemClock,
 } from '@ultimat3/core';
@@ -199,8 +200,11 @@ async function postForm(
     //
     // `renderThrowable`, never `error.message` behind an `instanceof`: `instanceof` itself throws
     // on a value whose `getPrototypeOf` trap does, losing the one refusal that tells a caller the
-    // code is already spent. What stays in the sentence is `url` and the remedy, both framework
-    // constants, so the failure is still fixable without quoting anything this package does not own.
+    // code is already spent. What stays in the sentence is `url` and the remedy, so the failure is
+    // still fixable without quoting anything this package does not own — but `url` is NOT a
+    // framework constant, which this comment claimed until 2026-09: `registerOAuthProvider` is open
+    // to any app and `discoverOAuthProvider` fills `tokenUrl` from the OP's own document, so the
+    // `fix:` below screens it (a `cause` is read, a `fix:` is pasted).
     logger.error('auth.oauth.token_fetch_failed', {
       provider,
       url,
@@ -213,7 +217,7 @@ async function postForm(
         `nothing left this host for ${url} (egress, DNS or TLS); the reason is in this process ` +
         'log under auth.oauth.token_fetch_failed. Restart the flow once it does, since the code ' +
         'is already spent',
-      fix: `curl -sS -m 5 -o /dev/null ${url}`,
+      fix: `curl -sS -m 5 -o /dev/null ${renderFixShellArg(url, '<the token endpoint the cause names>')}`,
     });
   }
 

package/src/oauth-profile.ts

@@ -3,7 +3,7 @@
 // when there is not. `emailVerified` is carried honestly rather than assumed — it is what
 // decides whether this login may attach itself to an existing account by address.
 
-import { logger, renderThrowable } from '@ultimat3/core';
+import { logger, renderFixShellArg, renderThrowable } from '@ultimat3/core';
 import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
 import { isRecord } from './json';
 import type { OAuthProviderId } from './oauth';
@@ -86,7 +86,12 @@ async function getJson(
       detail:
         `${reason} — nothing left this host for ${url} (egress, DNS or TLS); restart the ` +
         'flow once it does',
-      fix: `curl -sS -m 5 -o /dev/null ${url}`,
+      // The endpoint reaches the registry from `discoverOAuthProvider` — the OP's own document —
+      // so it is REMOTE text, and this line is a command a reader pastes: `$(…)` and a backtick
+      // substitute before `curl` is reached. `renderFixShellArg` passes an ordinary endpoint
+      // through and substitutes the shape for anything a shell would read; the URL itself is in
+      // the `detail` above, which is prose nobody pastes.
+      fix: `curl -sS -m 5 -o /dev/null ${renderFixShellArg(url, '<the userinfo endpoint the cause names>')}`,
     });
   }
   if (!response.ok) {

package/src/session.ts

@@ -156,8 +156,16 @@ export async function verifySession(
     throw sessionExpired(expiry.absoluteExpired ? 'absolute' : 'idle', session.id);
   }
 
-  const ip = observed?.ip ?? session.ip;
-  const userAgent = observed?.userAgent ?? session.userAgent;
+  // `??` collapsed two different statements. `null` is an OBSERVATION — this request had no
+  // client address, or no user agent — and `undefined` is silence, so an explicit null could
+  // never clear a stale stored value: the address from an earlier request was written forward on
+  // every verify, and the device list a user checks for a session they do not recognise showed it
+  // as current. Absent still keeps what the row holds; only silence does.
+  const ip = observed === undefined || observed.ip === undefined ? session.ip : observed.ip;
+  const userAgent =
+    observed === undefined || observed.userAgent === undefined
+      ? session.userAgent
+      : observed.userAgent;
   // The window slides only when it has actually moved. A second request inside the slide issues
   // no write at all — the read path stays a read — while a changed address or user agent is
   // written immediately, because that is the row a device list and an incident review read.