@ultimat3/auth 1.2.0 → 3.0.0

package/src/memory-adapter.ts

@@ -12,7 +12,9 @@ import type {
   CreateUserInput,
   SessionPatch,
   UserPatch,
+  UserQuery,
 } from './adapter';
+import { timingSafeEqual } from './tokens';
 
 const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
 
@@ -24,10 +26,15 @@ export class MemoryAdapter implements AuthAdapter {
   readonly #verifications = new Map<string, AuthVerification>();
   readonly #apiKeys = new Map<string, AuthApiKeyRecord>();
 
+  /**
+   * Exact match, because `BuiltinAdapter` issues `where email = $1` against a plain `text ...
+   * unique` column and nothing folds case there. Normalising here instead made this the ONE
+   * adapter that found an account Postgres would not, which is a linked account under `x dev` and
+   * a duplicate one in production. `normaliseEmail` is the caller's, above the seam.
+   */
   async findUserByEmail(email: string): Promise<AuthUser | null> {
-    const wanted = email.trim().toLowerCase();
     for (const user of this.#users.values()) {
-      if (user.email === wanted) return user;
+      if (user.email === email) return user;
     }
     return null;
   }
@@ -39,14 +46,17 @@ export class MemoryAdapter implements AuthAdapter {
   async createUser(input: CreateUserInput): Promise<AuthUser> {
     const user: AuthUser = {
       id: input.id,
-      email: input.email.trim().toLowerCase(),
+      // Stored as handed over, exactly as the `insert into x_users` binds it.
+      email: input.email,
       emailVerifiedAt: null,
       passwordHash: input.passwordHash,
       orgId: input.orgId,
       roles: [...input.roles],
       permissions: [],
+      scopes: [...(input.scopes ?? [])],
       mfaSecret: null,
       recoveryCodeHashes: [],
+      externalId: input.externalId ?? null,
       disabledAt: null,
       createdAt: input.createdAt,
     };
@@ -66,11 +76,30 @@ export class MemoryAdapter implements AuthAdapter {
       recoveryCodeHashes: patch.recoveryCodeHashes ?? user.recoveryCodeHashes,
       disabledAt: patch.disabledAt === undefined ? user.disabledAt : patch.disabledAt,
       roles: patch.roles ?? user.roles,
+      permissions: patch.permissions ?? user.permissions,
+      scopes: patch.scopes ?? user.scopes,
+      orgId: patch.orgId === undefined ? user.orgId : patch.orgId,
+      externalId: patch.externalId === undefined ? user.externalId : patch.externalId,
     };
     this.#users.set(id, next);
     return next;
   }
 
+  async findUserByExternalId(externalId: string): Promise<AuthUser | null> {
+    for (const user of this.#users.values()) {
+      if (user.externalId === externalId) return user;
+    }
+    return null;
+  }
+
+  async listUsersByOrg(orgId: string, query?: UserQuery): Promise<readonly AuthUser[]> {
+    return [...this.#users.values()]
+      .filter((user) => user.orgId === orgId)
+      .filter((user) => query?.includeDisabled === true || user.disabledAt === null)
+      .filter((user) => query?.role === undefined || user.roles.includes(query.role))
+      .sort((a, b) => a.email.localeCompare(b.email));
+  }
+
   async getSession(id: string): Promise<AuthSession | null> {
     return this.#sessions.get(id) ?? null;
   }
@@ -108,6 +137,32 @@ export class MemoryAdapter implements AuthAdapter {
     return killed;
   }
 
+  async deleteSessionsForUser(userId: string): Promise<number> {
+    return this.#deleteSessionsWhere((session) => session.userId === userId);
+  }
+
+  /** Joins through the user map, which is what the Postgres adapter's subselect does. */
+  async deleteSessionsForOrg(orgId: string): Promise<number> {
+    const members = new Set(
+      [...this.#users.values()].filter((user) => user.orgId === orgId).map((user) => user.id),
+    );
+    return this.#deleteSessionsWhere((session) => members.has(session.userId));
+  }
+
+  async deleteSessionsCreatedBefore(before: Date): Promise<number> {
+    return this.#deleteSessionsWhere((session) => session.createdAt.getTime() < before.getTime());
+  }
+
+  #deleteSessionsWhere(matches: (session: AuthSession) => boolean): number {
+    let killed = 0;
+    for (const [id, session] of this.#sessions) {
+      if (!matches(session)) continue;
+      this.#sessions.delete(id);
+      killed += 1;
+    }
+    return killed;
+  }
+
   async listSessions(userId: string): Promise<readonly AuthSession[]> {
     return [...this.#sessions.values()]
       .filter((session) => session.userId === userId)
@@ -131,10 +186,17 @@ export class MemoryAdapter implements AuthAdapter {
     this.#verifications.set(verificationKey(record.purpose, record.identifier), record);
   }
 
-  async takeVerification(purpose: string, identifier: string): Promise<AuthVerification | null> {
+  async takeVerification(
+    purpose: string,
+    identifier: string,
+    tokenHash: string,
+  ): Promise<AuthVerification | null> {
     const key = verificationKey(purpose, identifier);
     const record = this.#verifications.get(key);
     if (record === undefined || record.consumedAt !== null) return null;
+    // Before the write, never after: a wrong guess that consumed the row would be an
+    // unauthenticated way to kill the victim's live link, which is the Postgres adapter's rule too.
+    if (!timingSafeEqual(tokenHash, record.tokenHash)) return null;
     const consumed: AuthVerification = { ...record, consumedAt: new Date(record.createdAt) };
     this.#verifications.set(key, consumed);
     return consumed;

package/src/mfa.ts

@@ -3,6 +3,7 @@
 // phishing page stays valid for the rest of its 30 seconds. Recovery codes are hashed at rest
 // and single-use, so a database dump is not a permanent MFA bypass.
 
+import type { Auth } from './auth';
 import { randomBytes, sha256Hex, timingSafeEqual } from './tokens';
 
 const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
@@ -63,17 +64,28 @@ export interface TotpEnrolment {
 }
 
 export interface EnrolTotpInput {
-  readonly issuer: string;
+  /**
+   * Omitted, the issuer is `auth.mfa.issuer` — one declaration, at `defineAuth`, so the product
+   * name an authenticator app shows is not restated at every enrolment. Named here only when one
+   * call needs a different one (a separate admin console entry, say).
+   */
+  readonly issuer?: string | undefined;
   readonly account: string;
   readonly secret?: string | undefined;
 }
 
-export function enrolTotp(input: EnrolTotpInput): TotpEnrolment {
+/**
+ * Takes the `Auth` every other entry point in this package takes, and for the same reason: the
+ * issuer is configuration, and a pure function that could not read the configuration is what made
+ * `defineAuth({ mfa: { issuer } })` a string the framework wrote down and never read.
+ */
+export function enrolTotp(auth: Auth, input: EnrolTotpInput): TotpEnrolment {
   const secret = input.secret ?? generateTotpSecret();
-  const label = `${encodeURIComponent(input.issuer)}:${encodeURIComponent(input.account)}`;
+  const issuer = input.issuer ?? auth.mfa.issuer;
+  const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(input.account)}`;
   const query = new URLSearchParams({
     secret,
-    issuer: input.issuer,
+    issuer,
     algorithm: 'SHA1',
     digits: String(TOTP_DIGITS),
     period: String(TOTP_STEP_SECONDS),
@@ -148,23 +160,106 @@ export interface TotpReplayGuard {
   remember(subject: string, step: number, at: Date): void;
 }
 
+/** What `createTotpReplayGuard` returns: the interface, plus the bound it keeps, observable. */
+export interface MemoryTotpReplayGuard extends TotpReplayGuard {
+  readonly size: number;
+}
+
+/**
+ * Hard bound on tracked subjects. One entry is one user who has completed a TOTP check inside the
+ * last drift window, so the natural cardinality is far below this — the cap is the backstop, the
+ * same one `DEFAULT_MAX_AUTH_LIMIT_KEYS` is for the limiter's table.
+ */
+export const DEFAULT_MAX_TOTP_SUBJECTS = 10_000;
+
+/** An idle guard still sweeps this often, so one burst's subjects do not sit until the next. */
+const SWEEP_EVERY_STEPS = 2;
+
+/**
+ * The cap arithmetic ran on the caller's number unchecked, and the two values a misread config
+ * hands you each defeated the bound in their own way: `Infinity` makes `used.size > cap` never
+ * true, so the table is exactly as unbounded as before it was capped; `NaN` makes EVERY comparison
+ * false, so `used.size <= evictTo` never stops the eviction loop and one sweep empties the table —
+ * including the subject who just authenticated, whose step is then replayable. Anything that is
+ * not a positive finite integer is a config the caller did not mean, so it takes the default
+ * rather than a bound derived from it. A fraction still floors: `2.5` is a caller who meant 2.
+ */
+function boundedSubjects(maxSubjects: number): number {
+  if (!Number.isFinite(maxSubjects) || maxSubjects < 1) return DEFAULT_MAX_TOTP_SUBJECTS;
+  return Math.floor(maxSubjects);
+}
+
+/** The last step this subject has spent — how close their entry still is to the live window. */
+const newestStep = (steps: ReadonlySet<number>): number => {
+  let newest = Number.NEGATIVE_INFINITY;
+  for (const step of steps) newest = Math.max(newest, step);
+  return newest;
+};
+
 /**
  * In-memory by default because a single web process is the common case; a multi-process
  * deployment passes a Redis-backed guard with the same two methods. Steps older than the
  * drift window are dropped — nothing outside it can be replayed anyway.
+ *
+ * Bounded, because the subject map only ever grew: pruning happened inside one subject's `Set`
+ * and never revisited a subject who stopped signing in, so the table carried one permanent entry
+ * per user for the life of the process. Two rules keep it flat, and the ORDER is the guarantee —
+ * evicting a subject makes a step they have already spent replayable again, so it may never be
+ * the subject who just authenticated. A subject whose every step has fallen below the drift floor
+ * is *forgotten*, not evicted: `verifyTotp` only ever offers a step within ±drift of now, so that
+ * entry answers exactly as a missing one and dropping it changes no decision. Only if forgetting
+ * is not enough does the cap evict live state, furthest from the live window first — the shape
+ * `createAuthLimiter` evicts by, where a live lockout is the last bucket to go.
  */
-export function createTotpReplayGuard(drift: number = TOTP_DRIFT_STEPS): TotpReplayGuard {
+export function createTotpReplayGuard(
+  drift: number = TOTP_DRIFT_STEPS,
+  maxSubjects: number = DEFAULT_MAX_TOTP_SUBJECTS,
+): MemoryTotpReplayGuard {
   const used = new Map<string, Set<number>>();
+  const cap = boundedSubjects(maxSubjects);
+  // Batched down to 90% of the cap so the sort below is paid once per 10% of it, not per check.
+  const evictTo = Math.max(1, Math.floor(cap * 0.9));
+  let lastSweepStep = Number.NEGATIVE_INFINITY;
+
+  const prune = (steps: Set<number>, floor: number): void => {
+    for (const known of steps) {
+      if (known < floor) steps.delete(known);
+    }
+  };
+
+  const sweep = (now: number, floor: number): void => {
+    lastSweepStep = now;
+    for (const [subject, steps] of used) {
+      prune(steps, floor);
+      if (steps.size === 0) used.delete(subject);
+    }
+    if (used.size <= cap) return;
+    // Map iteration is insertion order and `remember` re-files the subject it touches, so this
+    // sort — stable by specification — breaks a tie on the newest step by least recently seen.
+    // Both keys point the same way: the subject who just proved a code is the last one out.
+    const furthest = [...used.entries()].sort((a, b) => newestStep(a[1]) - newestStep(b[1]));
+    for (const [subject] of furthest) {
+      if (used.size <= evictTo) break;
+      used.delete(subject);
+    }
+  };
+
   return {
+    get size() {
+      return used.size;
+    },
     isUsed: (subject, step) => used.get(subject)?.has(step) === true,
     remember: (subject, step, at) => {
+      const now = totpStep(at);
+      const floor = now - drift;
       const steps = used.get(subject) ?? new Set<number>();
-      const floor = totpStep(at) - drift;
-      for (const known of steps) {
-        if (known < floor) steps.delete(known);
-      }
+      prune(steps, floor);
       steps.add(step);
+      // Deleted before it is set, so this subject moves to the back of the iteration order and
+      // that order is least-recently-remembered first. Nothing else observes it.
+      used.delete(subject);
       used.set(subject, steps);
+      if (used.size > cap || now - lastSweepStep >= SWEEP_EVERY_STEPS) sweep(now, floor);
     },
   };
 }

package/src/oauth-builtins.ts

@@ -0,0 +1,77 @@
+// Single responsibility: the three consumer IdPs Ultimate ships with, as plain data. They live
+// apart from `oauth-registry.ts` so the registry can be seeded from them while `oauth.ts` reads
+// the registry — the only edge back to `oauth.ts` is the type, and a type is erased, so there is
+// no runtime cycle between the three files.
+
+import type { OAuthProvider } from './oauth';
+
+export const GITHUB_PROVIDER: OAuthProvider = {
+  id: 'github',
+  authorizeUrl: 'https://github.com/login/oauth/authorize',
+  tokenUrl: 'https://github.com/login/oauth/access_token',
+  userInfoUrl: 'https://api.github.com/user',
+  // GitHub omits a private address from the profile; the identity is still incomplete
+  // without it, so the flow asks for the verified list rather than guessing.
+  userEmailsUrl: 'https://api.github.com/user/emails',
+  issuers: [],
+  // GitHub is OAuth2 and not OIDC: no id token, therefore no key set to verify one against.
+  jwksUri: null,
+  scopes: ['read:user', 'user:email'],
+  usesPkce: true,
+  usesNonce: false,
+  clientIdEnv: 'GITHUB_CLIENT_ID',
+  clientSecretEnv: 'GITHUB_CLIENT_SECRET',
+};
+
+export const GOOGLE_PROVIDER: OAuthProvider = {
+  id: 'google',
+  authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+  tokenUrl: 'https://oauth2.googleapis.com/token',
+  // Reached only when a narrowed `scopes` leaves the id token without an email claim.
+  userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+  userEmailsUrl: null,
+  issuers: ['https://accounts.google.com', 'accounts.google.com'],
+  jwksUri: 'https://www.googleapis.com/oauth2/v3/certs',
+  scopes: ['openid', 'email', 'profile'],
+  usesPkce: true,
+  usesNonce: true,
+  clientIdEnv: 'GOOGLE_CLIENT_ID',
+  clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
+};
+
+export const APPLE_PROVIDER: OAuthProvider = {
+  id: 'apple',
+  authorizeUrl: 'https://appleid.apple.com/auth/authorize',
+  tokenUrl: 'https://appleid.apple.com/auth/token',
+  // Apple returns claims in the id token only; there is no userinfo endpoint to call.
+  userInfoUrl: null,
+  userEmailsUrl: null,
+  issuers: ['https://appleid.apple.com'],
+  jwksUri: 'https://appleid.apple.com/auth/keys',
+  scopes: ['name', 'email'],
+  usesPkce: true,
+  usesNonce: true,
+  clientIdEnv: 'APPLE_CLIENT_ID',
+  // Apple alone does not accept a static secret: `APPLE_CLIENT_SECRET` must hold the ES256
+  // client-secret JWT signed with the .p8 key, which Apple expires every six months.
+  clientSecretEnv: 'APPLE_CLIENT_SECRET',
+};
+
+/** Seeded into the registry at import, through the same call an app registers its own IdP with. */
+export const BUILTIN_OAUTH_PROVIDERS: readonly OAuthProvider[] = Object.freeze([
+  GITHUB_PROVIDER,
+  GOOGLE_PROVIDER,
+  APPLE_PROVIDER,
+]);
+
+/**
+ * The three ids, and the only list an ANONYMOUS caller is ever shown. It is a framework constant
+ * already in the docs, so naming it discloses nothing; the live registry is not, because an app
+ * that registered `acme-internal-sso` has put its own vocabulary in there. `oauth-route.ts` is the
+ * one reader in this package — every other refusal reaches a developer and gets
+ * `oauthProviderIds()` instead. Off `index.ts` too, because an app writing its own login route
+ * owes an anonymous caller the same narrow list and must not have to restate the three ids.
+ */
+export const BUILTIN_OAUTH_PROVIDER_IDS: readonly string[] = Object.freeze(
+  BUILTIN_OAUTH_PROVIDERS.map((provider) => provider.id),
+);

package/src/oauth-cookie.ts

@@ -8,7 +8,8 @@
 import type { Clock } from '@ultimat3/core';
 import { EnvMissingError, systemClock } from '@ultimat3/core';
 import { oauthStateInvalid } from './errors';
-import { OAUTH_PROVIDERS, type OAuthHandshake, type OAuthProviderId } from './oauth';
+import type { OAuthHandshake, OAuthProviderId } from './oauth';
+import { hasOAuthProvider } from './oauth-registry';
 import { type RequestLike, readCookie } from './session';
 import { base64Url, timingSafeEqual } from './tokens';
 
@@ -138,7 +139,7 @@ export function openHandshake(
   ) {
     throw oauthStateInvalid(provider, 'the stored handshake is not a handshake');
   }
-  if (!Object.hasOwn(OAUTH_PROVIDERS, sealedProvider) || sealedProvider !== provider) {
+  if (!hasOAuthProvider(sealedProvider) || sealedProvider !== provider) {
     throw oauthStateInvalid(provider, 'the stored handshake belongs to a different provider');
   }
 
@@ -157,7 +158,7 @@ export function openHandshake(
  * session cookie's: the callback is a top-level cross-site GET from the provider, which `Lax`
  * still attaches the cookie to and `Strict` would strip — leaving every login to fail its state
  * check. A provider answering with `response_mode=form_post` POSTs instead, and this cookie
- * would not reach it; no provider in `OAUTH_PROVIDERS` is configured that way.
+ * would not reach it; none of the three built-in providers is configured that way.
  */
 export function handshakeCookie(
   handshake: OAuthHandshake,

package/src/oauth-discovery.ts

@@ -0,0 +1,132 @@
+// Single responsibility: turning an OIDC issuer URL into an `OAuthProvider`, by reading the
+// discovery document every conforming OP publishes (OIDC Discovery 1.0, §4). One `fetch`, at
+// 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 { oauthExchangeFailed } from './errors';
+import { isRecord } from './json';
+import type { OAuthProvider } from './oauth';
+import type { OAuthFetch } from './oauth-exchange';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** The document lives at a fixed suffix off the issuer; the issuer keeps its own path. */
+export const discoveryUrl = (issuer: string): string =>
+  `${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration`;
+
+export interface DiscoverOAuthProviderInput {
+  /** The id the URL segment carries: `/auth/oauth/<id>`. Also names the two env vars. */
+  readonly id: string;
+  readonly issuer: string;
+  /** Defaults to the OIDC minimum this package needs to identify somebody. */
+  readonly scopes?: readonly string[] | undefined;
+  readonly clientIdEnv?: string | undefined;
+  readonly clientSecretEnv?: string | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: OAuthFetch | undefined;
+  readonly timeoutMs?: number | undefined;
+}
+
+const stringOrNull = (body: Record<string, unknown>, key: string): string | null => {
+  const value = body[key];
+  return typeof value === 'string' && value !== '' ? value : null;
+};
+
+/** `bigco-sso` → `BIGCO_SSO_CLIENT_ID`, the same shape the three built-ins use. */
+const envPrefix = (id: string): string => id.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+
+/**
+ * Reads the issuer's discovery document and returns the provider. It does **not** register:
+ * `registerOAuthProvider(await discoverOAuthProvider({ id, issuer }))` keeps one install point,
+ * and an app that wants to override one endpoint spreads the result before registering it.
+ *
+ * `issuers` is pinned to the `issuer` the document itself declares, not the URL that was asked
+ * for — a document that names a different issuer is answering for somebody else, and pinning the
+ * requested URL would let it.
+ */
+export async function discoverOAuthProvider(
+  input: DiscoverOAuthProviderInput,
+): Promise<OAuthProvider> {
+  const url = discoveryUrl(input.issuer);
+  const doFetch: OAuthFetch = input.fetch ?? ((target, init) => globalThis.fetch(target, init));
+
+  let response: Response;
+  try {
+    response = await doFetch(url, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(input.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      detail:
+        error instanceof Error ? error.message : 'the request failed before a response arrived',
+      fix: `curl -sS -m 5 ${url}`,
+    });
+  }
+
+  if (!response.ok) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      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 })`,
+    });
+  }
+
+  const body: unknown = await response.json().catch(() => undefined);
+  if (!isRecord(body)) {
+    throw oauthExchangeFailed({
+      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`,
+    });
+  }
+
+  const issuer = stringOrNull(body, 'issuer');
+  const authorizeUrl = stringOrNull(body, 'authorization_endpoint');
+  const tokenUrl = stringOrNull(body, 'token_endpoint');
+  if (issuer === null || authorizeUrl === null || tokenUrl === null) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      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}'`,
+    });
+  }
+
+  const jwksUri = stringOrNull(body, 'jwks_uri');
+  if (jwksUri === null) {
+    // Without a key set there is nothing to verify an id token against, and the only remaining
+    // trust is the TLS channel to the token endpoint — which is the exemption, not a default.
+    throw oauthExchangeFailed({
+      provider: input.id,
+      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}', ... })`,
+    });
+  }
+
+  const prefix = envPrefix(input.id);
+  return {
+    id: input.id,
+    authorizeUrl,
+    tokenUrl,
+    userInfoUrl: stringOrNull(body, 'userinfo_endpoint'),
+    userEmailsUrl: null,
+    issuers: [issuer],
+    jwksUri,
+    scopes: input.scopes ?? ['openid', 'email', 'profile'],
+    usesPkce: true,
+    usesNonce: true,
+    clientIdEnv: input.clientIdEnv ?? `${prefix}_CLIENT_ID`,
+    clientSecretEnv: input.clientSecretEnv ?? `${prefix}_CLIENT_SECRET`,
+  };
+}

package/src/oauth-exchange.ts

@@ -4,16 +4,18 @@
 // token is verified here, so no caller downstream can forget to.
 
 import type { Clock } from '@ultimat3/core';
-import { EnvMissingError, systemClock } from '@ultimat3/core';
-import { oauthExchangeFailed } from './errors';
+import { EnvMissingError, renderCauseValue, systemClock } from '@ultimat3/core';
+import { oauthExchangeFailed, restartAt } from './errors';
 import { type IdTokenClaims, verifyIdToken } from './id-token';
+import { isRecord } from './json';
+import type { IdTokenKeys } from './jwks';
 import {
   assertOAuthCallback,
-  OAUTH_PROVIDERS,
   type OAuthCallback,
   type OAuthHandshake,
   type OAuthProviderId,
 } from './oauth';
+import { providerFor } from './oauth-registry';
 
 /** Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to. */
 export type OAuthFetch = (input: string, init: RequestInit) => Promise<Response>;
@@ -45,6 +47,13 @@ export interface OAuthExchangeOptions {
   /** Injected in tests; production uses the global. */
   readonly fetch?: OAuthFetch | undefined;
   readonly timeoutMs?: number | undefined;
+  /**
+   * Defaults to `'token-endpoint-tls'`, and this is the one call site where that default is
+   * correct: the id token below was read off a TLS response from the provider's own token
+   * endpoint, which is the channel OIDC Core 3.1.3.7 exempts. An app that pins the key set anyway
+   * — a corporate egress proxy, a compliance requirement — passes `providerJwks(providerFor(id))`.
+   */
+  readonly keys?: IdTokenKeys | undefined;
 }
 
 /**
@@ -55,7 +64,7 @@ export function oauthCredentials(
   provider: OAuthProviderId,
   env: Readonly<Record<string, string | undefined>> = Bun.env,
 ): OAuthClientCredentials {
-  const { clientIdEnv, clientSecretEnv } = OAUTH_PROVIDERS[provider];
+  const { clientIdEnv, clientSecretEnv } = providerFor(provider);
   const clientId = env[clientIdEnv]?.trim() ?? '';
   const clientSecret = env[clientSecretEnv]?.trim() ?? '';
   const missing = [
@@ -72,10 +81,16 @@ export function oauthCredentials(
   return { clientId, clientSecret };
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-/** Prefers the provider's own words; falls back to raw text, capped so a login page can't flood logs. */
+/**
+ * Prefers the provider's own words; falls back to raw text, capped so a login page can't flood logs.
+ *
+ * Every branch but the empty-body sentence is a REMOTE server's bytes, and this string is spliced
+ * into an `X_OAUTH_EXCHANGE_FAILED` cause — so a token endpoint that is compromised, impersonated
+ * or merely behind a hostile proxy could otherwise write a second log line an operator reads as
+ * genuine. Rendered here rather than at the factory because `OAuthExchangeFailure.detail` is
+ * mostly prose this package authored, and quoting that would make every readable message unread-
+ * able. The rule is "remote text is rendered", and this function is where remote text is made.
+ */
 export async function providerDetail(response: Response): Promise<string> {
   const text = await response.text().catch(() => '');
   if (text === '') return 'the response body was empty';
@@ -83,21 +98,25 @@ export async function providerDetail(response: Response): Promise<string> {
     const parsed: unknown = JSON.parse(text);
     if (isRecord(parsed)) {
       const description = parsed['error_description'] ?? parsed['error'] ?? parsed['message'];
-      if (typeof description === 'string' && description !== '') return description;
+      if (typeof description === 'string' && description !== '') {
+        return renderCauseValue(description);
+      }
     }
   } catch {
     // Not JSON — fall through to the truncated raw text below.
   }
-  return text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text;
+  return renderCauseValue(
+    text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text,
+  );
 }
 
 function fixForStatus(provider: OAuthProviderId, status: number): string {
-  const { clientIdEnv, clientSecretEnv } = OAUTH_PROVIDERS[provider];
+  const { clientIdEnv, clientSecretEnv } = providerFor(provider);
   if (status === 401 || status === 403) {
     return `set ${clientIdEnv} and ${clientSecretEnv} to the current values in the ${provider} app settings`;
   }
   if (status === 400) {
-    return `register this exact redirect_uri in the ${provider} app settings, then restart the flow`;
+    return `register this exact redirect_uri in the ${provider} app settings, then ${restartAt(provider)}`;
   }
   return `retry; if it persists, check the ${provider} status page before changing anything`;
 }
@@ -108,7 +127,7 @@ async function postForm(
   options: OAuthExchangeOptions,
 ): Promise<Record<string, unknown>> {
   const doFetch: OAuthFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
-  const url = OAUTH_PROVIDERS[provider].tokenUrl;
+  const url = providerFor(provider).tokenUrl;
 
   let response: Response;
   try {
@@ -166,7 +185,7 @@ async function postForm(
       detail: typeof description === 'string' && description !== '' ? description : error,
       fix:
         error === 'bad_verification_code' || error === 'invalid_grant'
-          ? 'restart the flow — an authorization code is single-use and short-lived'
+          ? `${restartAt(provider)} — an authorization code is single-use and short-lived`
           : fixForStatus(provider, 400),
     });
   }
@@ -183,7 +202,7 @@ export async function exchangeOAuthCode(
   options: OAuthExchangeOptions,
 ): Promise<OAuthTokens> {
   assertOAuthCallback(handshake, callback);
-  const provider = OAUTH_PROVIDERS[handshake.provider];
+  const provider = providerFor(handshake.provider);
   const clock = options.clock ?? systemClock;
 
   const body = new URLSearchParams({
@@ -193,7 +212,9 @@ export async function exchangeOAuthCode(
     client_id: options.credentials.clientId,
     client_secret: options.credentials.clientSecret,
   });
-  if (provider.usesPkce) body.set('code_verifier', handshake.verifier);
+  // Unconditional: PKCE is not provider-dependent, and `OAuthProvider.usesPkce` is the type-level
+  // statement of that — there is no configuration in which this line is skipped.
+  body.set('code_verifier', handshake.verifier);
 
   const payload = await postForm(handshake.provider, body, options);
   const accessToken = payload['access_token'];
@@ -202,7 +223,7 @@ export async function exchangeOAuthCode(
       provider: provider.id,
       stage: 'token',
       detail: 'the response carried no access_token',
-      fix: `confirm the ${provider.id} app grants the scopes in OAUTH_PROVIDERS.${provider.id}.scopes`,
+      fix: `confirm the ${provider.id} app grants the scopes in providerFor('${provider.id}').scopes`,
     });
   }
 
@@ -233,12 +254,13 @@ export async function exchangeOAuthCode(
     claims:
       idToken === null
         ? null
-        : verifyIdToken({
+        : await verifyIdToken({
             provider: handshake.provider,
             idToken,
             clientId: options.credentials.clientId,
             nonce: handshake.nonce,
             clock,
+            keys: options.keys ?? 'token-endpoint-tls',
           }),
   };
 }