@ultimat3/auth 22.15.0 → 24.0.0

package/src/mfa-challenge.ts

@@ -0,0 +1,151 @@
+// Single responsibility: the second leg of a sign-in. The first leg ends in `X_MFA_REQUIRED`
+// carrying a sealed, short-lived challenge; `completeMfa` opens it, meters the code against the
+// same buckets a password guess spends, and only then mints the session.
+
+import { isUltimateError, openText, randomHex, type SealKeySource, seal } from '@ultimat3/core';
+import type { Auth, LoginResult } from './auth';
+import { type AuthError, mfaChallengeInvalid, mfaCodeRejected, mfaRequired } from './errors';
+import { isRecord } from './json';
+import { openLoginAttempt } from './login-attempt';
+import { recoveryCodeHash, TOTP_DIGITS, verifyTotp } from './mfa';
+import { openTotpSecret } from './mfa-secret';
+import { resolveActor } from './policy-bridge';
+import { accountKey } from './rate-limit';
+import { createSession, sessionCookie } from './session';
+
+/** Bound into the seal's tag: a value sealed for anything else does not open as a challenge. */
+export const MFA_CHALLENGE_PURPOSE = 'auth:mfa-challenge';
+
+/** Long enough to unlock a phone and read six digits; short enough that a lifted one is stale. */
+export const MFA_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+
+interface MfaChallenge {
+  readonly userId: string;
+  /** Makes two challenges for one user at one instant different values. */
+  readonly nonce: string;
+  readonly expiresAtMs: number;
+}
+
+/**
+ * The refusal `login()` and the OAuth path end their first leg with, carrying the challenge in
+ * `meta.challenge`. Sealed under the app's master key (`x secrets init`), so it needs no table and
+ * no second secret — and a deployment that enrols a second factor without one fails here, loudly,
+ * with `X_SEAL_KEY_MISSING`.
+ */
+export async function mfaChallengeRequired(
+  auth: Auth,
+  userId: string,
+  keys: SealKeySource = {},
+): Promise<AuthError> {
+  const challenge: MfaChallenge = {
+    userId,
+    nonce: randomHex(16),
+    expiresAtMs: auth.clock.now().getTime() + MFA_CHALLENGE_TTL_MS,
+  };
+  return mfaRequired(
+    await seal(JSON.stringify(challenge), { ...keys, purpose: MFA_CHALLENGE_PURPOSE }),
+  );
+}
+
+/** A seal that would not open is a bad challenge; a missing master key is a broken deployment. */
+const UNOPENABLE: ReadonlySet<string> = new Set(['X_SEAL_INVALID', 'X_SEAL_KEY_UNKNOWN']);
+
+async function openChallenge(
+  auth: Auth,
+  token: unknown,
+  keys: SealKeySource,
+): Promise<MfaChallenge> {
+  if (typeof token !== 'string' || token.length === 0) throw mfaChallengeInvalid();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await openText(token, { ...keys, purpose: MFA_CHALLENGE_PURPOSE }));
+  } catch (thrown) {
+    if (isUltimateError(thrown) && !UNOPENABLE.has(thrown.code)) throw thrown;
+    throw mfaChallengeInvalid();
+  }
+  if (!isRecord(parsed)) throw mfaChallengeInvalid();
+  const { userId, nonce, expiresAtMs } = parsed;
+  if (typeof userId !== 'string' || typeof nonce !== 'string' || typeof expiresAtMs !== 'number') {
+    throw mfaChallengeInvalid();
+  }
+  // The server's clock decides. `>=` on a number that is not one is false, so a NaN is refused
+  // by asking the question the way round that fails closed.
+  if (!(auth.clock.now().getTime() < expiresAtMs)) throw mfaChallengeInvalid();
+  return { userId, nonce, expiresAtMs };
+}
+
+export interface CompleteMfaOptions extends SealKeySource {
+  /** The caller's address: a wrong code counts against it, exactly as a wrong password does. */
+  readonly ip?: string | null | undefined;
+  readonly userAgent?: string | null | undefined;
+}
+
+/** What an authenticator app shows, once the spaces a person types are gone. */
+const TOTP_SHAPE = new RegExp(`^[0-9]{${TOTP_DIGITS}}$`);
+
+/**
+ * Finish a sign-in that stopped at `X_MFA_REQUIRED`: the challenge from `error.meta.challenge`
+ * and either the six digits or one recovery code. Answers what `login()` answers.
+ *
+ * The guess is RESERVED before the code is looked at, against the account, the address and the
+ * tenant — the buckets a password guess spends — so six digits are worth `maxAttempts` tries per
+ * window and no more, and a wrong code is followed by `X_ACCOUNT_LOCKED`. A code is good once:
+ * a TOTP step is remembered in `auth.totpReplay`, and a recovery code is consumed by the adapter
+ * in one atomic step, so two requests carrying one code cannot both finish.
+ */
+export async function completeMfa(
+  auth: Auth,
+  challengeToken: string,
+  code: string,
+  options: CompleteMfaOptions = {},
+): Promise<LoginResult> {
+  const challenge = await openChallenge(auth, challengeToken, options);
+  const user = await auth.adapter.findUserById(challenge.userId);
+  if (user === null || user.disabledAt !== null || user.mfaSecret === null) {
+    throw mfaChallengeInvalid();
+  }
+
+  // Before anything is reserved: a stored value that is not sealed is the deployment's fault,
+  // not a guess, and it is refused (`X_MFA_SECRET_UNSEALED`) rather than read.
+  const secret = await openTotpSecret(user.mfaSecret, options);
+
+  const ip = options.ip ?? null;
+  const attempt = await openLoginAttempt(auth, accountKey(user.email), ip);
+  await attempt.reserveOrg(user.orgId);
+
+  const presented = typeof code === 'string' ? code.replaceAll(' ', '') : '';
+  if (TOTP_SHAPE.test(presented)) {
+    const now = auth.clock.now();
+    const verdict = verifyTotp({ secret, code: presented, at: now });
+    // Checked and remembered with no `await` between them: two concurrent completions carrying
+    // one code cannot both find the step unspent.
+    if (!verdict.ok || verdict.step === null || auth.totpReplay.isUsed(user.id, verdict.step)) {
+      throw mfaCodeRejected();
+    }
+    auth.totpReplay.remember(user.id, verdict.step, now);
+  } else {
+    let consumed: boolean;
+    try {
+      consumed = await auth.adapter.consumeRecoveryCode(user.id, recoveryCodeHash(presented));
+    } catch (thrown) {
+      // A store that is down reached no verdict, so the guess is not counted as a wrong one.
+      await attempt.release();
+      throw thrown;
+    }
+    if (!consumed) throw mfaCodeRejected();
+  }
+  await attempt.succeed();
+
+  const issued = await createSession(auth.sessions, {
+    userId: user.id,
+    ip,
+    userAgent: options.userAgent,
+    mfaSatisfied: true,
+  });
+  return {
+    actor: resolveActor({ kind: 'user', user, session: issued.session }),
+    session: issued.session,
+    token: issued.token,
+    cookie: sessionCookie(issued.token, auth.sessions.policy),
+  };
+}

package/src/mfa-secret.ts

@@ -0,0 +1,91 @@
+// Single responsibility: the second-factor secret at rest. A TOTP seed is symmetric — verifying a
+// code needs the seed itself — so it is sealed under the app's master key, never hashed and never
+// stored in the clear. One writer, one reader, and the one-shot that seals what predates them.
+
+import { isSealed, openText, type SealKeySource, seal } from '@ultimat3/core';
+import type { UserStore } from './adapter';
+import { authWriteFailed, mfaSecretInvalid, mfaSecretUnsealed } from './errors';
+import { base32Decode } from './mfa';
+
+/** The slice of the seam this file reads and writes — what a CLI holding only a database can supply. */
+export interface MfaSecretStore {
+  readonly adapter: Pick<UserStore, 'listUsersWithMfaSecret' | 'replaceMfaSecret' | 'updateUser'>;
+}
+
+/** Bound into the tag: a value sealed for any other column does not open as a TOTP secret. */
+export const MFA_SECRET_PURPOSE = 'auth:x_users.mfa_secret';
+
+/**
+ * Enrolment's write: the base32 secret `enrolTotp` answered, sealed, onto the user's row. The
+ * ONLY way a secret should reach `x_users.mfa_secret` — a value written past this is refused by
+ * every reader until `sealMfaSecrets` has sealed it.
+ */
+export async function saveTotpSecret(
+  auth: MfaSecretStore,
+  userId: string,
+  secret: string,
+  keys: SealKeySource = {},
+): Promise<void> {
+  // A secret nothing can derive a code from is refused before it is sealed: sealed, it would be
+  // an opaque value nobody could tell was a lockout.
+  if (typeof secret !== 'string' || base32Decode(secret).length === 0) {
+    throw mfaSecretInvalid('saveTotpSecret');
+  }
+  const sealed = await seal(secret, { ...keys, purpose: MFA_SECRET_PURPOSE });
+  const user = await auth.adapter.updateUser(userId, { mfaSecret: sealed });
+  if (user === null) throw authWriteFailed('updateUser', 'x_users');
+}
+
+/**
+ * The base32 secret behind a stored value. A value that is not sealed is REFUSED, never read as
+ * the secret it probably is: a plaintext read kept "for now" is a plaintext column forever.
+ */
+export async function openTotpSecret(stored: string, keys: SealKeySource = {}): Promise<string> {
+  if (!isSealed(stored)) throw mfaSecretUnsealed();
+  return await openText(stored, { ...keys, purpose: MFA_SECRET_PURPOSE });
+}
+
+export interface SealMfaSecretsReport {
+  /** Values that were plaintext and are now sealed. */
+  readonly sealed: number;
+  /** Values that were already sealed, and were left exactly as they were. */
+  readonly alreadySealed: number;
+  /**
+   * Rows whose secret changed between the read and the write — the user re-enrolled, or
+   * un-enrolled, mid-run — and were left alone. A new enrolment is already sealed.
+   */
+  readonly skipped: number;
+}
+
+/** How many stored secrets are still plaintext — what `x doctor` reports before a user finds out. */
+export async function countUnsealedMfaSecrets(auth: MfaSecretStore): Promise<number> {
+  const stored = await auth.adapter.listUsersWithMfaSecret();
+  return stored.filter((row) => !isSealed(row.mfaSecret)).length;
+}
+
+/**
+ * The one-shot behind `x auth seal-mfa`: every plaintext `mfa_secret` sealed in place. Idempotent
+ * — a sealed value is counted and never touched — so a run that stopped half way is finished by
+ * running it again. The master key is resolved by the first `seal`, before any row is written.
+ *
+ * Each write is a compare-and-set on the value that was read: a row that changed underneath is
+ * `skipped`, never overwritten with the secret it used to hold.
+ */
+export async function sealMfaSecrets(
+  auth: MfaSecretStore,
+  keys: SealKeySource = {},
+): Promise<SealMfaSecretsReport> {
+  let sealed = 0;
+  let alreadySealed = 0;
+  let skipped = 0;
+  for (const row of await auth.adapter.listUsersWithMfaSecret()) {
+    if (isSealed(row.mfaSecret)) {
+      alreadySealed += 1;
+      continue;
+    }
+    const value = await seal(row.mfaSecret, { ...keys, purpose: MFA_SECRET_PURPOSE });
+    if (await auth.adapter.replaceMfaSecret(row.userId, row.mfaSecret, value)) sealed += 1;
+    else skipped += 1;
+  }
+  return { sealed, alreadySealed, skipped };
+}

package/src/mfa.ts

@@ -1,7 +1,8 @@
 // Single responsibility: TOTP (RFC 6238) and recovery codes. The drift window is explicit and
 // small, and every accepted step is remembered: without replay rejection a code shouted over a
 // 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.
+// and single-use, so a database dump is not a permanent MFA bypass; consuming one is the
+// adapter's (`consumeRecoveryCode`), because single-use has to be one atomic step.
 
 import { finiteCount } from '@ultimat3/core';
 import type { Auth } from './auth';
@@ -308,6 +309,12 @@ export interface RecoveryCodeSet {
 const normaliseRecoveryCode = (code: string): string =>
   code.replaceAll('-', '').replaceAll(' ', '').toUpperCase();
 
+/**
+ * What a recovery code is stored and looked up as: SHA-256 of the code with the dashes and spaces
+ * a person types taken out. `AuthAdapter.consumeRecoveryCode` takes this, never the code.
+ */
+export const recoveryCodeHash = (code: string): string => sha256Hex(normaliseRecoveryCode(code));
+
 /**
  * `count` is a LOOP BOUND, so it fails in both directions and neither is a smaller set of codes.
  * `NaN` — what `Number(process.env.RECOVERY_CODES)` answers for an unset variable, and not nullish,
@@ -326,26 +333,5 @@ export function generateRecoveryCodes(count = 10): RecoveryCodeSet {
     const raw = base32Encode(randomBytes(10)).slice(0, 16);
     codes.push(`${raw.slice(0, 4)}-${raw.slice(4, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}`);
   }
-  return { codes, hashes: codes.map((code) => sha256Hex(normaliseRecoveryCode(code))) };
-}
-
-/**
- * Returns the remaining hashes with the redeemed one removed, or `null` if nothing matched.
- * The caller persists the result — that write is what makes a code single-use.
- */
-export function redeemRecoveryCode(
-  code: string,
-  hashes: readonly string[],
-): readonly string[] | null {
-  const candidate = sha256Hex(normaliseRecoveryCode(code));
-  let matched = false;
-  const remaining: string[] = [];
-  for (const hash of hashes) {
-    if (!matched && timingSafeEqual(hash, candidate)) {
-      matched = true;
-      continue;
-    }
-    remaining.push(hash);
-  }
-  return matched ? remaining : null;
+  return { codes, hashes: codes.map(recoveryCodeHash) };
 }

package/src/oauth-builtins.ts

@@ -39,6 +39,12 @@ export const GOOGLE_PROVIDER: OAuthProvider = {
   clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
 };
 
+/**
+ * UNPROVEN: this flow has never completed a sign-in against Apple, in a test or anywhere else.
+ * Apple answers a request that asks for a scope with `response_mode=form_post` — a POST to the
+ * callback — and both route descriptors in `oauth-route.ts` are GET and read the query string.
+ * Whether this entry ships or is removed is an open owner decision; do not rely on it.
+ */
 export const APPLE_PROVIDER: OAuthProvider = {
   id: 'apple',
   authorizeUrl: 'https://appleid.apple.com/auth/authorize',

package/src/oauth-cookie.ts

@@ -6,12 +6,12 @@
 // format at one trust level.
 
 import type { Clock } from '@ultimat3/core';
-import { EnvMissingError, systemClock } from '@ultimat3/core';
+import { EnvMissingError, readCookie, systemClock } from '@ultimat3/core';
 import type { OAuthHandshake, OAuthProviderId } from './oauth';
 import { oauthStateInvalid } from './oauth-errors';
 import { hasOAuthProvider } from './oauth-registry';
 import { assertFiniteAuthCount } from './policy-numbers';
-import { type RequestLike, readCookie } from './session';
+import type { RequestLike } from './session';
 import { base64Url, timingSafeEqual } from './tokens';
 
 /** `__Host-` for the same reason the session cookie carries it: no subdomain can plant one. */
@@ -67,7 +67,8 @@ export function handshakeSecret(
       cause:
         secret === ''
           ? 'SESSION_SECRET is not set, so an oauth handshake cannot be signed'
-          : `SESSION_SECRET is ${secret.length} characters and at least ${MIN_SECRET_LENGTH} are required`,
+          : // Never its length: how long the configured secret is narrows a guess at it.
+            `SESSION_SECRET is shorter than the ${MIN_SECRET_LENGTH} characters required`,
       fix: 'export SESSION_SECRET="$(openssl rand -hex 32)"',
       meta: { key: 'SESSION_SECRET', minLength: MIN_SECRET_LENGTH },
     });
@@ -208,7 +209,10 @@ export function readHandshakeCookie(
   provider: OAuthProviderId,
   options?: HandshakeCookieOptions,
 ): OAuthHandshake {
-  const sealed = readCookie(request, options?.name ?? handshakeCookieName(provider));
+  const sealed = readCookie(
+    request.headers.get('cookie'),
+    options?.name ?? handshakeCookieName(provider),
+  );
   if (sealed === null) {
     throw oauthStateInvalid(provider, 'no handshake cookie arrived with the callback');
   }

package/src/oauth-discovery.ts

@@ -3,7 +3,12 @@
 // 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 { renderFixLiteral, renderFixShellArg, renderThrowable } from '@ultimat3/core';
+import {
+  renderCauseValue,
+  renderFixLiteral,
+  renderFixShellArg,
+  renderThrowable,
+} from '@ultimat3/core';
 import { isRecord } from './json';
 import type { OAuthProvider } from './oauth';
 import { oauthExchangeFailed } from './oauth-errors';
@@ -16,9 +21,12 @@ const TIMEOUT_CONSEQUENCE =
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
+/** An issuer as it is compared and built on: its trailing slashes are not part of its identity. */
+const bareIssuer = (issuer: string): string => issuer.replace(/\/+$/, '');
+
 /** 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`;
+  `${bareIssuer(issuer)}/.well-known/openid-configuration`;
 
 export interface DiscoverOAuthProviderInput {
   /** The id the URL segment carries: `/auth/oauth/<id>`. Also names the two env vars. */
@@ -46,9 +54,9 @@ const envPrefix = (id: string): string => id.toUpperCase().replace(/[^A-Z0-9]+/g
  * `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.
+ * A document that declares a different issuer than the one asked for is answering for somebody
+ * else and is refused (OIDC Discovery 1.0 §4.3). `issuers` then carries the document's own
+ * spelling, which is what its id tokens put in `iss`; only a trailing slash may differ.
  */
 export async function discoverOAuthProvider(
   input: DiscoverOAuthProviderInput,
@@ -124,6 +132,17 @@ export async function discoverOAuthProvider(
     });
   }
 
+  if (bareIssuer(issuer) !== bareIssuer(input.issuer)) {
+    throw oauthExchangeFailed({
+      provider: input.id,
+      stage: 'discovery',
+      detail:
+        `the discovery document declares issuer ${renderCauseValue(issuer)}, and it was fetched ` +
+        `for ${renderCauseValue(input.issuer)}, so it is answering for another issuer`,
+      fix: `curl -sS -m 5 ${renderFixShellArg(url, '<issuer>/.well-known/openid-configuration')} | jq .issuer`,
+    });
+  }
+
   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

package/src/oauth-errors.ts

@@ -1,7 +1,7 @@
-// Single responsibility: the OAuth half of this package's error factories — every refusal a
-// provider handshake can produce, and the one phrase their fixes are built from.
-// Split from `errors.ts` at the 500-line ceiling; the codes, the titles and the single
-// `registerErrorCodes()` call stay there, so this file adds no code and registers nothing.
+// Single responsibility: the OAuth refusals more than one OAuth module raises, and the one phrase
+// every "start over" fix is built from. A refusal with one thrower lives beside it (`oauthDenied`
+// in `oauth-route.ts`, the linking ones in `oauth-login.ts`); the codes, titles and the single
+// `registerErrorCodes()` call stay in `errors.ts`, so this file adds no code and registers nothing.
 
 import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
 import { AuthError } from './errors';
@@ -25,30 +25,6 @@ export const oauthStateInvalid = (provider: string, part: string): AuthError =>
 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
@@ -79,19 +55,6 @@ export const oauthProviderUnknown = (provider: string, supported: readonly strin
     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;
   /**
@@ -125,49 +88,6 @@ export const oauthExchangeFailed = (failure: OAuthExchangeFailure): AuthError =>
     },
   });
 
-/**
- * The address is proven to the provider, and an account that never proved it already holds it.
- * Naming that is not account enumeration — this caller just demonstrated they own the address —
- * and staying silent would leave them with a login that fails forever and no way out.
- *
- * The address itself rides in `meta`, never in `cause`: a log pipeline can redact a field by
- * key, and cannot redact an address that was already interpolated into a sentence.
- */
-export const oauthAccountNotLinked = (provider: string, email: string): AuthError =>
-  new AuthError({
-    code: 'X_UNAUTHENTICATED',
-    cause: `an account holds this ${provider} address but never verified it, so ${provider} may not claim it`,
-    fix: `sign in with that account's password and confirm the email-verify link, then retry ${provider}`,
-    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
- * reads as unverified — the exact state `resolveUser` refuses to link a provider to — so the
- * flow fails closed on an adapter that loses the stamp instead of half-succeeding.
- */
-export const emailVerifiedNotStored = (provider: string, userId: string): AuthError =>
-  new AuthError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `the adapter returned no row for new user ${userId}, so the ${provider}-verified address was never stamped verified`,
-    fix: 'return the updated row from AuthAdapter.updateUser — MemoryAdapter.updateUser is the reference implementation',
-    meta: { provider, userId },
-  });
-
 /** The token arrived, and is not one this handshake can trust: wrong `iss`, `aud`, or expired. */
 export const oauthTokenInvalid = (provider: string, reason: string, fix: string): AuthError =>
   new AuthError({

package/src/oauth-exchange.ts

@@ -124,6 +124,13 @@ const OPAQUE_BODY =
   'the endpoint answered with a body that is not a coded OAuth error, and this leg does not quote ' +
   'one back because its request carries the client secret';
 
+/**
+ * The one way a remote endpoint's own words reach a cause: cut, then rendered. Every branch that
+ * quotes the other end goes through it — a branch that skipped it published 5 KB verbatim.
+ */
+const remoteText = (text: string): string =>
+  renderCauseValue(text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text);
+
 export async function providerDetail(
   response: Response,
   echo: DetailEcho = 'raw',
@@ -140,17 +147,13 @@ export async function providerDetail(
         parsed['error_description'] ??
         parsed['error'] ??
         (echo === 'coded-only' ? undefined : parsed['message']);
-      if (typeof description === 'string' && description !== '') {
-        return renderCauseValue(description);
-      }
+      if (typeof description === 'string' && description !== '') return remoteText(description);
     }
   } catch {
     // Not JSON — fall through to the truncated raw text below.
   }
   if (echo === 'coded-only') return OPAQUE_BODY;
-  return renderCauseValue(
-    text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text,
-  );
+  return remoteText(text);
 }
 
 function fixForStatus(provider: OAuthProviderId, status: number): string {
@@ -257,7 +260,10 @@ async function postForm(
     throw oauthExchangeFailed({
       provider,
       stage: 'token',
-      detail: typeof description === 'string' && description !== '' ? description : error,
+      // Remote text on a 200, so it is cut and rendered exactly as a non-2xx body is.
+      detail: remoteText(
+        typeof description === 'string' && description !== '' ? description : error,
+      ),
       fix:
         error === 'bad_verification_code' || error === 'invalid_grant'
           ? `${restartAt(provider)} — an authorization code is single-use and short-lived`

package/src/oauth-login.ts

@@ -7,15 +7,10 @@ import { ConfigInvalidError, logger, uuid } from '@ultimat3/core';
 import type { AuthAccount, AuthUser } from './adapter';
 import type { Auth, LoginResult } from './auth';
 import { normaliseEmail } from './email';
-import { authWriteFailed, mfaRequired } from './errors';
+import { AuthError, authWriteFailed } from './errors';
+import { mfaChallengeRequired } from './mfa-challenge';
 import type { OAuthCallback, OAuthHandshake } from './oauth';
-import {
-  emailVerifiedNotStored,
-  oauthAccountNotLinked,
-  oauthExchangeFailed,
-  oauthLinkingDisabled,
-  restartAt,
-} from './oauth-errors';
+import { oauthExchangeFailed, restartAt } from './oauth-errors';
 import {
   exchangeOAuthCode,
   type OAuthClientCredentials,
@@ -28,6 +23,52 @@ import { resolveActor } from './policy-bridge';
 import { loginFailed } from './rate-limit';
 import { createSession, sessionCookie } from './session';
 
+/**
+ * The address is proven to the provider, and an account that never proved it already holds it.
+ * Naming that is not account enumeration — this caller just demonstrated they own the address —
+ * and staying silent would leave them with a login that fails forever and no way out.
+ *
+ * The address itself rides in `meta`, never in `cause`: a log pipeline can redact a field by
+ * key, and cannot redact an address that was already interpolated into a sentence.
+ */
+export const oauthAccountNotLinked = (provider: string, email: string): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `an account holds this ${provider} address but never verified it, so ${provider} may not claim it`,
+    fix: `sign in with that account's password and confirm the email-verify link, then retry ${provider}`,
+    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
+ * reads as unverified — the exact state `resolveUser` refuses to link a provider to — so the
+ * flow fails closed on an adapter that loses the stamp instead of half-succeeding.
+ */
+export const emailVerifiedNotStored = (provider: string, userId: string): AuthError =>
+  new AuthError({
+    // `X_AUTH_WRITE_FAILED`, the code for "an adapter write returned no row". It was
+    // `X_NOT_IMPLEMENTED` — a 501 telling an operator a feature is missing, about an adapter that
+    // implements `updateUser` and lost a write it accepted.
+    code: 'X_AUTH_WRITE_FAILED',
+    cause: `the adapter returned no row for new user ${userId}, so the ${provider}-verified address was never stamped verified`,
+    fix: 'return the updated row from AuthAdapter.updateUser — MemoryAdapter.updateUser is the reference implementation',
+    meta: { provider, userId },
+  });
+
 /**
  * What the IdP's answer entitles this identity to, in the app's own vocabulary. Which group maps
  * to which role is business convention and never ships (axiom 8) — this is the seam it arrives
@@ -244,7 +285,7 @@ export async function signInWithOAuth(auth: Auth, input: OAuthSignInInput): Prom
     linked === null ? account : { ...account, id: linked.id, createdAt: linked.createdAt },
   );
 
-  if (user.mfaSecret !== null) throw mfaRequired(user.id);
+  if (user.mfaSecret !== null) throw await mfaChallengeRequired(auth, user.id);
 
   const issued = await createSession(auth.sessions, {
     userId: user.id,