@ultimat3/auth 1.2.0 → 2.0.0

package/src/errors.ts

@@ -3,7 +3,13 @@
 // factories here are deliberately coarse — `rate-limit.ts` owns the single login failure
 // every credential path must throw, and nothing else describes *why* a credential failed.
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import {
+  registerErrorCodes,
+  renderCauseValue,
+  renderFixLiteral,
+  UltimateError,
+} from '@ultimat3/core';
+import { oauthStartPath } from './oauth-paths';
 
 /** Codes this package declares and owns. `X_UNAUTHENTICATED` is auth's; http only borrows it. */
 export const AUTH_OWNED_ERROR_CODES = [
@@ -13,10 +19,15 @@ export const AUTH_OWNED_ERROR_CODES = [
   'X_OAUTH_STATE_INVALID',
   'X_OAUTH_EXCHANGE_FAILED',
   'X_OAUTH_TOKEN_INVALID',
+  'X_OAUTH_PROVIDER_UNKNOWN',
+  'X_OAUTH_PROVIDER_DUPLICATE',
+  'X_OAUTH_DENIED',
   'X_PASSWORD_WEAK',
   'X_ACCOUNT_LOCKED',
   'X_API_KEY_INVALID',
   'X_AUTH_WRITE_FAILED',
+  'X_AUTH_LIMITER_NOT_SHARED',
+  'X_AUTH_LIMITER_POLICY_MISMATCH',
 ] as const;
 
 /**
@@ -24,7 +35,20 @@ export const AUTH_OWNED_ERROR_CODES = [
  * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. No titles here on purpose — a second copy of a title
  * is a title that drifts, and registering one of these would be `X_ERROR_CODE_DUPLICATE`.
  */
-export const AUTH_BORROWED_ERROR_CODES = ['X_FORBIDDEN', 'X_NOT_IMPLEMENTED'] as const;
+// `X_ENV_MISSING` and `X_CONFIG_INVALID` were thrown here long before they were declared here —
+// oauth-cookie.ts and oauth-exchange.ts refuse on a missing secret, oauth-login.ts on a bad
+// config. An undeclared borrow is a code the manifest cannot attribute to the package that throws
+// it, so `x errors` could not point a reader at this file.
+// `X_OVERLOADED` is `@ultimat3/http`'s, borrowed rather than re-declared: this package is the
+// same tier and can never import http, but a refusal to start 19 MiB of argon2 work IS load
+// shedding and must read as the same thing to a client (503 + Retry-After) whichever layer shed it.
+export const AUTH_BORROWED_ERROR_CODES = [
+  'X_FORBIDDEN',
+  'X_NOT_IMPLEMENTED',
+  'X_ENV_MISSING',
+  'X_CONFIG_INVALID',
+  'X_OVERLOADED',
+] as const;
 
 /** Every code auth can throw: the ones it owns plus the ones it borrows. */
 export const AUTH_ERROR_CODES = [...AUTH_OWNED_ERROR_CODES, ...AUTH_BORROWED_ERROR_CODES] as const;
@@ -38,11 +62,16 @@ export const AUTH_ERROR_TITLES: Readonly<Record<AuthOwnedErrorCode, string>> = {
   X_MFA_REQUIRED: 'a second factor is required before this session is usable',
   X_OAUTH_STATE_INVALID: 'oauth state, nonce or pkce verifier did not match',
   X_OAUTH_EXCHANGE_FAILED: 'the oauth provider refused the exchange or returned no usable identity',
-  X_OAUTH_TOKEN_INVALID: 'id token failed its issuer, audience or expiry check',
+  X_OAUTH_TOKEN_INVALID: 'id token failed its signature, issuer, audience or expiry check',
+  X_OAUTH_PROVIDER_UNKNOWN: 'the URL named a provider this app has not enabled',
+  X_OAUTH_PROVIDER_DUPLICATE: 'two oauth providers were registered under one id',
+  X_OAUTH_DENIED: 'the user or the provider declined the authorization',
   X_PASSWORD_WEAK: 'password does not meet the configured policy',
   X_ACCOUNT_LOCKED: 'too many failed attempts; this key is locked out',
   X_API_KEY_INVALID: 'api key is unknown, revoked, expired or wrong',
   X_AUTH_WRITE_FAILED: 'an adapter write returned no row, so it cannot be confirmed',
+  X_AUTH_LIMITER_NOT_SHARED: 'the lockout is declared fleet-wide and the limiter is per-process',
+  X_AUTH_LIMITER_POLICY_MISMATCH: 'the limiter in use enforces other numbers than the app declared',
 };
 
 // Registered unconditionally, in one call: a second package claiming a code auth owns has to fail
@@ -74,11 +103,17 @@ export class AuthError extends UltimateError {
   }
 }
 
+/**
+ * The two things that produce an anonymous actor on a surface that needs one, so the fix names
+ * both: the request carried no `__Host-x_session` cookie, or it did and nothing resolved it.
+ * `authenticate()` returns the anonymous actor for a missing cookie rather than throwing, which
+ * is correct — and is exactly why the failure surfaces here, one layer later, instead of there.
+ */
 export const unauthenticated = (surface: string): AuthError =>
   new AuthError({
     code: 'X_UNAUTHENTICATED',
     cause: `${surface} needs an actor but ctx.actor is anonymous`,
-    fix: 'x auth whoami --json   # confirm the request carries the __Host-x_session cookie',
+    fix: 'send the __Host-x_session cookie with this request, and resolve it once at the boundary: authenticate(auth, readSessionCookie(request, auth.sessions.policy))',
   });
 
 export const forbidden = (surface: string, reason: string): AuthError =>
@@ -100,27 +135,138 @@ export const sessionUnknown = (): AuthError =>
   new AuthError({
     code: 'X_UNAUTHENTICATED',
     cause: 'the session cookie does not match any live session',
-    fix: 'x auth sessions list --json   # then sign in again to mint a fresh session',
+    // No lookup by cookie is offered, and that is deliberate: a forged id and a deleted session
+    // are indistinguishable here by design. The reader signs in again; a developer holding a
+    // user id can see what is still live without the cookie telling them anything.
+    fix: 'sign in again to mint a fresh session — listDevices(auth.sessions, userId) lists the sessions still live for a user',
+  });
+
+/**
+ * Shed BEFORE the KDF runs, the same decision `@ultimat3/http`'s `admit` stage makes for a whole
+ * request. `retryAfterSeconds` rides in `meta` because this package cannot reach an HTTP header;
+ * the host reads it onto `Retry-After`.
+ */
+export const kdfOverloaded = (active: number, queued: number): AuthError =>
+  new AuthError({
+    code: 'X_OVERLOADED',
+    cause: `${active} password hashes are already running and ${queued} more are queued`,
+    fix: 'retry after the Retry-After header; widen the ceiling with configureKdfGate({ maxConcurrent, maxQueued }) only if the box has the memory — every argon2id hash holds ~19 MiB while it runs',
+    meta: { active, queued, retryAfterSeconds: 1 },
   });
 
+/**
+ * The second leg is the APP's, and this line says so — it named `POST /auth/mfa/verify` for a
+ * release while no such route, no `completeMfa()` and no pending-MFA credential existed anywhere,
+ * the same dead-`fix:` defect `oauth-paths.ts` exists to stop. Shipping that route from here would
+ * be worse than saying nothing: the only correlation value this error carries is a user id, so the
+ * route would be unauthenticated by construction and MFA would become the ONLY factor. The design
+ * constraint for the real second leg is in `packages/auth/CLAUDE.md`.
+ *
+ * `userId` is `meta`, never `cause`: both surfaces that render this code to an anonymous caller
+ * (`oauth-route.ts`'s `publicBody`, `@ultimat3/http`'s problem document) publish `cause` and drop
+ * `meta`, and a user id handed to whoever typed the URL is what feeds the attack above.
+ */
 export const mfaRequired = (userId: string): AuthError =>
   new AuthError({
     code: 'X_MFA_REQUIRED',
-    cause: `user ${userId} has TOTP enrolled and this session has not satisfied it`,
-    fix: 'POST /auth/mfa/verify { code } with the 6-digit code, then retry',
+    cause: 'this account has TOTP enrolled and the second factor has not been satisfied',
+    fix: 'no second-factor route ships yet — catch X_MFA_REQUIRED in your sign-in handler, check the code with verifyTotp({ secret: user.mfaSecret, code, at }), then mint the session with createSession(auth.sessions, { userId, mfaSatisfied: true })',
+    meta: { userId },
   });
 
+/**
+ * The `fix:` quotes `oauthStartPath` rather than a hand-written path. That is not tidiness: this
+ * line shipped naming `GET /auth/oauth/<provider>` while `@ultimat3/auth` mounted no route at all,
+ * so every caller who followed it hit a 404. One declaration, read by the mount and by the fix,
+ * is what stops that recurring — `oauthLogin()` cannot move without moving this sentence.
+ */
 export const oauthStateInvalid = (provider: string, part: string): AuthError =>
   new AuthError({
     code: 'X_OAUTH_STATE_INVALID',
     cause: `${provider} callback rejected: ${part}`,
-    fix: `restart the flow at GET /auth/oauth/${provider} — a callback URL is single-use`,
+    fix: `${restartAt(provider)} — a callback URL is single-use`,
+    meta: { provider },
+  });
+
+/** The one phrase every "start over" fix is built from, so none of them can name a dead route. */
+export const restartAt = (provider: string): string =>
+  `restart the flow at GET ${oauthStartPath(provider)}`;
+
+/**
+ * The provider came back with `error=` and no code — almost always the user pressing Cancel.
+ * A separate code from `X_OAUTH_EXCHANGE_FAILED` on purpose: nothing was exchanged, nothing is
+ * misconfigured, and folding the single commonest non-success outcome of a login into the code
+ * that means "the client secret is wrong" makes both unreadable in a log and pages the wrong person.
+ */
+export const oauthDenied = (
+  provider: string,
+  reason: string,
+  description: string | null,
+): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_DENIED',
+    // `reason` and `description` are query parameters off the callback URL — whatever the browser
+    // was redirected with, newlines and quotes included. `renderCauseValue` renders them as JSON
+    // string literals, so a forged `error_description` cannot forge a second log line or break the
+    // sentence around it. Both are already `string` by type: this is escaping, not throw-safety.
+    cause: `${provider} declined the authorization: ${renderCauseValue(reason)}${
+      description === null ? '' : ` (${renderCauseValue(description)})`
+    }`,
+    fix: `${restartAt(provider)} and approve the ${provider} consent screen`,
+    meta: { provider, reason },
+  });
+
+/**
+ * A URL segment naming a provider no `registerOAuthProvider` call has claimed, or one that is but
+ * was left out of `defineAuth({ providers })`. One refusal for both: which of the two it is
+ * describes the app's configuration to an unauthenticated caller, and the fix is the same sentence
+ * either way.
+ *
+ * **`supported` is the CALLER's to scope, because the two callers have two audiences.**
+ * `oauth-route.ts` passes `BUILTIN_OAUTH_PROVIDER_IDS` — its reader is an anonymous stranger who
+ * typed a URL, and the three built-ins are a framework constant already in the public docs, while
+ * the live registry holds whatever internal OP this deployment registered. `providerFor()` passes
+ * `oauthProviderIds()` — its reader is a developer holding a stack trace, and there the full list
+ * is exactly what makes the fix runnable. Neither ever passes `defineAuth({ providers })`: naming
+ * what this deployment turned on is the disclosure the shared refusal exists to prevent.
+ *
+ * The fix names `registerOAuthProvider` first so it stays executable for the branch the narrowed
+ * list cannot cover — a segment nothing registered cannot be added to `providers` at all, so
+ * "add it" alone was an instruction that could not be followed.
+ *
+ * The segment itself is a URL path the caller typed, so it goes through `renderCauseValue` in the
+ * sentence and `renderFixLiteral` in the command — a fix has to parse after a hostile value lands
+ * in it.
+ */
+export const oauthProviderUnknown = (provider: string, supported: readonly string[]): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_PROVIDER_UNKNOWN',
+    cause: `no oauth provider is mounted at ${renderCauseValue(oauthStartPath(provider))}`,
+    fix: `registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')} }) if it is not built in, then add that id to defineAuth({ providers: [...] }) — known here: ${supported.map((id) => `'${id}'`).join(', ')}`,
+    meta: { provider },
+  });
+
+/**
+ * Two `registerOAuthProvider` calls claiming one id. A silent replacement would let whichever
+ * module imported second decide where every login for that id goes — including which `issuers`
+ * an id token may claim — so the second registration refuses at boot instead.
+ */
+export const oauthProviderDuplicate = (provider: string): AuthError =>
+  new AuthError({
+    code: 'X_OAUTH_PROVIDER_DUPLICATE',
+    cause: `an oauth provider is already registered as ${renderCauseValue(provider)}, so the second registration would silently replace the first`,
+    fix: `give one of them a different id, or delete the duplicate registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')} }) call`,
+    meta: { provider },
   });
 
 export interface OAuthExchangeFailure {
   readonly provider: string;
-  /** Which leg of the server-to-server conversation failed. */
-  readonly stage: 'token' | 'userinfo';
+  /**
+   * Which leg of the server-to-server conversation failed. `discovery` and `jwks` are the two
+   * boot/verification legs an enterprise OP adds: reading `/.well-known/openid-configuration`,
+   * and reading the key set an id token's signature is checked against.
+   */
+  readonly stage: 'token' | 'userinfo' | 'discovery' | 'jwks';
   readonly detail: string;
   readonly status?: number | undefined;
   readonly fix: string;
@@ -162,6 +308,19 @@ export const oauthAccountNotLinked = (provider: string, email: string): AuthErro
     meta: { provider, email },
   });
 
+/**
+ * `link: 'never'` and a local account already holds the address. Same code and same disclosure
+ * rule as `oauthAccountNotLinked` — the caller proved to the provider that the address is theirs,
+ * so naming the collision is not enumeration — and the address rides in `meta`, never in `cause`.
+ */
+export const oauthLinkingDisabled = (provider: string, email: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `an account already holds this address and defineAuth({ link: 'never' }) forbids ${provider} from claiming it`,
+    fix: "sign in with that account's own credentials, or set link: 'verified-email' in defineAuth to let a provider-verified address claim a locally-verified account",
+    meta: { provider, email },
+  });
+
 /**
  * `CreateUserInput` carries no `emailVerifiedAt`, so a provider-verified address takes a second
  * write. Falling back to the unstamped row would mint a session for a user every later login
@@ -192,11 +351,24 @@ export const passwordWeak = (reasons: readonly string[]): AuthError =>
     fix: 'choose a longer, uncommon password — or relax defineAuth({ password: { minLength } })',
   });
 
+/**
+ * The escape is `recordSuccess(key)`, which is what a successful login already calls: it deletes
+ * the bucket, so it clears exactly this one key and nothing else. `reset()` exists too and is the
+ * wrong reach — it drops every bucket in the table, including the spray this lockout is holding.
+ *
+ * `key` carries an address or an email the caller chose, so it goes through `renderFixLiteral`:
+ * a fix line has to still parse after a hostile value lands in it.
+ */
 export const accountLocked = (key: string, retryAfterSeconds: number): AuthError =>
   new AuthError({
     code: 'X_ACCOUNT_LOCKED',
-    cause: `${key} is locked out for another ${retryAfterSeconds}s after repeated failures`,
-    fix: `wait ${retryAfterSeconds}s, or run: x auth unlock ${key}`,
+    // `renderCauseValue`, matching `oauthDenied`: `ipKey(ip)` builds this key from whatever address
+    // string its caller passed, so a newline in it writes a second log line an operator reads as
+    // genuine. The value is `string` by type — the static scan only sees `unknown`/`any`, so this
+    // one was never going to be caught for us — and rendering it as a JSON string literal is
+    // escaping, not throw-safety.
+    cause: `${renderCauseValue(key)} is locked out for another ${retryAfterSeconds}s after repeated failures`,
+    fix: `wait ${retryAfterSeconds}s — or clear this one bucket: auth.limiter.recordSuccess(${renderFixLiteral(key, '<key>')}), auth.orgLimiter for an org: key — or raise defineAuth({ rateLimit })`,
   });
 
 /** One shape for every api-key rejection: unknown, revoked, expired and wrong all look alike. */
@@ -204,7 +376,9 @@ export const apiKeyInvalid = (): AuthError =>
   new AuthError({
     code: 'X_API_KEY_INVALID',
     cause: 'the presented api key is unknown, revoked, expired or does not match its hash',
-    fix: 'x auth keys list --json   # then: x auth keys issue --scopes "<scope>"',
+    // Which of the four it was is not named here and never will be — see the factory's contract
+    // above — so the fix is the one action that resolves all four: issue a replacement.
+    fix: 'issue a replacement: const { plaintext, record } = issueApiKey({ env, scopes }); await auth.adapter.putApiKey(record) — auth.adapter.listApiKeys(ownerId) through describeApiKey() shows which keys are still live',
   });
 
 /**
@@ -216,10 +390,41 @@ export const authWriteFailed = (operation: string, table: string): AuthError =>
   new AuthError({
     code: 'X_AUTH_WRITE_FAILED',
     cause: `${operation} returned no row from ${table}, so the write cannot be confirmed`,
-    fix: `x db migrate   # then: x db query "select 1 from ${table} limit 1" --json`,
+    fix: `x db migrate   # then, if ${table} is already there: x dev, and read it in the db panel at /_x`,
     meta: { operation, table },
   });
 
+/**
+ * At `defineAuth`, never at a login. `replicas: 3` behind one policy means each process counts
+ * failures on its own, so the account survives `maxAttempts × 3` guesses and a lockout established
+ * on one replica is invisible to the other two — a throttle that reads as configured and is not.
+ */
+export const authLimiterNotShared = (found: string): AuthError =>
+  new AuthError({
+    code: 'X_AUTH_LIMITER_NOT_SHARED',
+    cause: `rateLimit.scope is 'shared' but the limiter in use is ${found}, so every replica would grant the full maxAttempts on its own`,
+    fix: "pass a limiter whose scope is 'shared' — defineAuth({ adapter, limiter }) — or set rateLimit.scope: 'process' in defineAuth to accept per-replica lockouts",
+    meta: { scope: found },
+  });
+
+/**
+ * At `defineAuth`, never at a login. `Auth.rateLimit` is what an operator reads as "what this
+ * deployment enforces", and an injected limiter counting to its own numbers makes that field a
+ * claim nothing backs — five attempts declared, fifty granted, and every surface reporting five.
+ * The policy is the app's single statement of the limits; this is what keeps it true.
+ */
+export const authLimiterPolicyMismatch = (
+  field: string,
+  declared: number,
+  enforced: number,
+): AuthError =>
+  new AuthError({
+    code: 'X_AUTH_LIMITER_POLICY_MISMATCH',
+    cause: `defineAuth declares rateLimit.${field} = ${declared} but the limiter passed to it enforces ${enforced}; if ${enforced} is the number this deployment means to enforce, then the declaration is the half that is wrong`,
+    fix: `construct the limiter with ${field}: ${declared} — defineAuth({ rateLimit, limiter }) compares the two, and the declaration is what Auth.rateLimit reports`,
+    meta: { field, declared, enforced },
+  });
+
 /** For a custom `AuthAdapter` that implements part of the seam. Nothing shipped throws it. */
 export const authNotImplemented = (feature: string, fix: string): AuthError =>
   new AuthError({

package/src/guards.ts

@@ -1,11 +1,11 @@
-// Single responsibility: the assertions the http pipeline's auth stage runs. They read the
-// ambient actor from core's context and assert on it — they never evaluate a policy, never
-// load a row and never look at a session. `@ultimat3/policy` is the only authz evaluator;
-// duplicating even a little of it here would be the second authz system the framework forbids.
+// Single responsibility: whether somebody is signed in. Both read the ambient actor from core's
+// context and assert on it — they never evaluate a policy, never load a row and never look at a
+// session. `@ultimat3/policy` is the only authz evaluator, so a role or scope decision does not
+// live here: it is a `Policy`, which `x routes`, the manifest and `x policy list` can all see.
 
 import type { Actor } from '@ultimat3/core';
-import { hasRole, hasScope, isAnonymous, useContext } from '@ultimat3/core';
-import { forbidden, unauthenticated } from './errors';
+import { isAnonymous, useContext } from '@ultimat3/core';
+import { unauthenticated } from './errors';
 
 const DEFAULT_SURFACE = 'this request';
 
@@ -16,26 +16,6 @@ export function requireActor(surface: string = DEFAULT_SURFACE): Actor {
   return actor;
 }
 
-/**
- * A coarse role gate for routes that are role-shaped rather than permission-shaped (an admin
- * area). Anything finer belongs in a policy — `can('post:publish')`, evaluated by policy.
- */
-export function requireRole(role: string, surface: string = DEFAULT_SURFACE): Actor {
-  const actor = requireActor(surface);
-  if (!hasRole(actor, role)) throw forbidden(surface, `actor lacks role "${role}"`);
-  return actor;
-}
-
-/**
- * The api-key path: an agent's scopes are exactly its key's scopes, so a scope check is a
- * credential check, not an authorization decision.
- */
-export function requireScope(scope: string, surface: string = DEFAULT_SURFACE): Actor {
-  const actor = requireActor(surface);
-  if (!hasScope(actor, scope)) throw forbidden(surface, `actor lacks scope "${scope}"`);
-  return actor;
-}
-
 /** Non-throwing form for a route that renders differently when signed out. */
 export function currentActor(): Actor | null {
   const { actor } = useContext();

package/src/id-token.ts

@@ -1,11 +1,17 @@
 // Single responsibility: turning a provider's id token into claims this handshake is allowed to
-// believe. Signature verification is deliberately absent: this token is read only where it was
-// fetched over TLS directly from the provider's token endpoint, which is the one case OIDC Core
-// 3.1.3.7 exempts — a token that reaches the browser instead must never be parsed here.
+// believe. Every caller must say where its trust comes from: `keys: 'token-endpoint-tls'` is the
+// one channel OIDC Core 3.1.3.7 exempts from a signature check, and anything else — IdP-initiated
+// login, `response_mode=form_post`, back-channel logout, token exchange — passes a `JwksKeySource`
+// and gets the signature verified. The argument is required rather than defaulted because a
+// default is what silently makes the second door as trusting as the first.
 
 import type { Clock } from '@ultimat3/core';
-import { oauthStateInvalid, oauthTokenInvalid } from './errors';
-import { OAUTH_PROVIDERS, type OAuthProvider, type OAuthProviderId } from './oauth';
+import { renderCauseValue } from '@ultimat3/core';
+import { oauthStateInvalid, oauthTokenInvalid, restartAt } from './errors';
+import { decodeJwtSegment } from './json';
+import { type IdTokenKeys, verifyJwtSignature } from './jwks';
+import type { OAuthProvider, OAuthProviderId } from './oauth';
+import { providerFor } from './oauth-registry';
 import { timingSafeEqual } from './tokens';
 
 /** The subset of OIDC claims this package acts on. Provider-specific extras are ignored. */
@@ -25,26 +31,18 @@ export interface IdTokenClaims {
 /** Two servers rarely agree on the second. Anything wider hides a genuinely expired token. */
 export const ID_TOKEN_CLOCK_SKEW_MS = 60_000;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
 const stringOrUndefined = (value: unknown): string | undefined =>
   typeof value === 'string' ? value : undefined;
 
 function decodeSegment(provider: string, segment: string, fix: string): Record<string, unknown> {
-  const padded = segment
-    .replace(/-/g, '+')
-    .replace(/_/g, '/')
-    .padEnd(Math.ceil(segment.length / 4) * 4, '=');
-  let parsed: unknown;
-  try {
-    const binary = atob(padded);
-    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
-    parsed = JSON.parse(new TextDecoder().decode(bytes));
-  } catch {
-    throw oauthTokenInvalid(provider, 'the payload segment is not base64url-encoded JSON', fix);
+  const parsed = decodeJwtSegment(segment);
+  if (parsed === null) {
+    throw oauthTokenInvalid(
+      provider,
+      'the payload segment is not base64url-encoded JSON describing an object',
+      fix,
+    );
   }
-  if (!isRecord(parsed)) throw oauthTokenInvalid(provider, 'the payload is not an object', fix);
   return parsed;
 }
 
@@ -53,7 +51,7 @@ function decodeSegment(provider: string, segment: string, fix: string): Record<s
  * point every flow uses; this one exists because the two halves are worth reading apart.
  */
 export function decodeIdToken(provider: OAuthProviderId, idToken: string): IdTokenClaims {
-  const fix = `check that ${OAUTH_PROVIDERS[provider].clientIdEnv} names an app whose id token is a JWT`;
+  const fix = `check that ${providerFor(provider).clientIdEnv} names an app whose id token is a JWT`;
   const segments = idToken.split('.');
   if (segments.length !== 3 || segments[1] === undefined || segments[1] === '') {
     throw oauthTokenInvalid(provider, 'the token is not a three-segment JWT', fix);
@@ -115,23 +113,47 @@ export interface VerifyIdTokenInput {
   /** `OAuthHandshake.nonce`. Checked whenever the provider was asked for one. */
   readonly nonce: string;
   readonly clock: Clock;
+  /**
+   * Required, and there is deliberately no default. `'token-endpoint-tls'` asserts this token was
+   * read off a TLS response from the provider's own token endpoint — the OIDC Core 3.1.3.7 case,
+   * and the only one where an unverified JWT is safe. Every other channel passes a key source:
+   * `providerJwks(providerFor(id))`, or a `createJwksClient({ jwksUri })` of its own.
+   */
+  readonly keys: IdTokenKeys;
 }
 
 /**
- * Issuer, audience, expiry and nonce, in that order. A nonce mismatch is
+ * Signature, issuer, audience, expiry and nonce, in that order — signature first, because every
+ * claim below it is only worth reading once something proved who wrote them. A nonce mismatch is
  * `X_OAUTH_STATE_INVALID` rather than a token error on purpose: it is the same class of event
  * as a forged `state` — a token minted for another browser being replayed into this one.
  */
-export function verifyIdToken(input: VerifyIdTokenInput): IdTokenClaims {
+export async function verifyIdToken(input: VerifyIdTokenInput): Promise<IdTokenClaims> {
   // Widened on purpose: `issuers` is a literal `readonly []` for a provider that issues no id
   // token, and `[].includes(string)` does not typecheck against `never`.
-  const provider: OAuthProvider = OAUTH_PROVIDERS[input.provider];
+  const provider: OAuthProvider = providerFor(input.provider);
   const claims = decodeIdToken(input.provider, input.idToken);
 
+  if (
+    input.keys !== 'token-endpoint-tls' &&
+    !(await verifyJwtSignature(input.idToken, input.keys))
+  ) {
+    throw oauthTokenInvalid(
+      provider.id,
+      'the signature does not verify against the published key set for this issuer',
+      `confirm the token came from ${provider.tokenUrl} and was not minted by whoever posted it here`,
+    );
+  }
+
   if (!provider.issuers.includes(claims.iss)) {
     throw oauthTokenInvalid(
       provider.id,
-      `iss was "${claims.iss}", expected one of ${provider.issuers.join(', ')}`,
+      // `claims.iss` is a field of the JWT the caller just presented — whatever they put in it,
+      // newlines and quotes included. Hand-written quotes around it did not escape either, so a
+      // forged `iss` could close the sentence and write a second log line an operator reads as
+      // genuine. `renderCauseValue` renders it as a JSON string literal, quotes included, which
+      // is why the manual pair is gone. `issuers` is registered config and needs no rendering.
+      `iss was ${renderCauseValue(claims.iss)}, expected one of ${provider.issuers.join(', ')}`,
       `confirm the token came from ${provider.tokenUrl} and not from a proxy that re-signs it`,
     );
   }
@@ -149,7 +171,7 @@ export function verifyIdToken(input: VerifyIdTokenInput): IdTokenClaims {
     throw oauthTokenInvalid(
       provider.id,
       'the token is already expired',
-      "sync this host's clock (`timedatectl status`), then restart the flow",
+      `sync this host's clock (\`timedatectl status\`), then ${restartAt(provider.id)}`,
     );
   }