@payez/next-mvp 4.8.0 → 4.8.2

package/src/lib/ensure-fresh-access-token.ts

@@ -1,509 +1,509 @@
-/**
- * ensureFreshAccessToken — server-side preflight refresh.
- *
- * Returns a non-expired IDP access token for a given session. Refreshes
- * proactively when the stored token is within the safety window of expiry,
- * using the same Redis lock and IDP wire shape as `createRefreshHandler`.
- *
- * Designed for proxy-route auth helpers that today read the stored token
- * blindly and let the backend reject it with a 401. Calling this instead of
- * `getSession(...).idpAccessToken` means a good token client never sends
- * credentials it already knows are invalid.
- *
- * Single-use refresh-token semantics are preserved via Redis-backed
- * single-flight locking (see `acquireRefreshLock`).
- */
-import {
-  getSession,
-  getBetterAuthSession,
-  updateSession,
-  acquireRefreshLock,
-  releaseRefreshLock,
-  checkRefreshLock,
-} from './session-store';
-import { computeTokenExpiries } from './token-expiry';
-import { extractKidFromToken } from '../auth/utils/token-utils';
-
-export interface EnsureFreshConfig {
-  idpBaseUrl: string;
-  clientId: string;
-  refreshEndpoint?: string;
-}
-
-export interface EnsureFreshOptions {
-  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
-  safetyWindowMs?: number;
-  /** Max wait while another caller holds the refresh lock. Default 5000. */
-  lockWaitMs?: number;
-  /** Optional caller request id for lock attribution. */
-  requestId?: string;
-}
-
-export type EnsureFreshResult =
-  | {
-      ok: true;
-      accessToken: string;
-      accessTokenExpires: number;
-      /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
-      refreshed: boolean;
-      /**
-       * CARD 320072. Is the token in THIS result actually in the session store?
-       *
-       * ON THIS BRANCH OF THE UNION IT IS ALWAYS `true`, AND THAT IS THE POINT.
-       * Every `ok: true` return either read the token back from the store or
-       * wrote it and confirmed the write. An unpersisted refresh does not reach
-       * an `ok: true` result at all — it returns `ok:false, SESSION_PERSIST_FAILED`
-       * from the other branch below.
-       *
-       * READ THIS BEFORE YOU DELETE THE FIELD. It is declared `boolean` rather
-       * than the literal `true` on purpose: it is the assertable witness that the
-       * escalation is still wired. If someone later re-weakens the persist site
-       * back to reporting success, this field is where that regression becomes
-       * visible to a test instead of invisible to everyone. Cases 2 and 7 in
-       * test/ensure-fresh-persist-failure.test.cjs assert on it.
-       *
-       * WHAT THIS COMMENT USED TO SAY, AND WHY IT IS GONE. It documented `false`
-       * as a live value on an ok:true result — "we hold a valid token that was
-       * not persisted" — because that WAS the contract before this merge, when
-       * the dropped write was reported as a success with a flag on it. Blending
-       * in the escalation made that sentence describe a state the code can no
-       * longer produce. A docblock asserting an impossible semantic is exactly
-       * the defect f5ac6dc3 was written to fix, one file over; reproducing it
-       * here while merging that fix would be absurd.
-       */
-      persisted: boolean;
-    }
-  | {
-      ok: false;
-      code: string;
-      message: string;
-      status: number;
-      terminal?: boolean;
-      discardToken?: boolean;
-      retryable?: boolean;
-      resolution?: string;
-    };
-
-const DEFAULT_SAFETY_WINDOW_MS = 60_000;
-const DEFAULT_LOCK_WAIT_MS = 5000;
-
-function decodeJwtExp(token: string): number {
-  const parts = token.split('.');
-  if (parts.length !== 3) return -1;
-  try {
-    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
-    return (payload.exp || 0) * 1000;
-  } catch {
-    return -1;
-  }
-}
-
-export async function ensureFreshAccessToken(
-  sessionToken: string,
-  config: EnsureFreshConfig,
-  options: EnsureFreshOptions = {}
-): Promise<EnsureFreshResult> {
-  const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
-  const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
-  const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
-  const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
-
-  let session = await getSession(sessionToken);
-  if (!session || !session.idpRefreshToken) {
-    const baSession = await getBetterAuthSession(sessionToken);
-    if (baSession?.idpRefreshToken) {
-      session = baSession;
-    }
-  }
-  if (!session) {
-    return { ok: false, code: 'NO_SESSION', message: 'No session for token', status: 401, terminal: true };
-  }
-
-  const storedToken = session.idpAccessToken;
-  if (!storedToken) {
-    // Card 187871: same conflation as getIdpToken (server/auth.ts) - a live
-    // session with no access token and mfaVerified !== true is a user
-    // mid-2FA, not dead. Only terminal once the session itself claims 2FA
-    // is already done.
-    if (session.mfaVerified !== true) {
-      return { ok: false, code: 'NO_TOKEN_PENDING_2FA', message: 'Two-factor authentication required', status: 401, terminal: false };
-    }
-    return { ok: false, code: 'NO_TOKEN', message: 'No IDP access token in session', status: 401, terminal: true };
-  }
-
-  const now = Date.now();
-  const redisExpires = session.idpAccessTokenExpires ?? 0;
-  const jwtExpires = decodeJwtExp(storedToken);
-  // Use the smaller of the two to be conservative — Redis can be stale, JWT exp is authoritative.
-  const effectiveExpires = jwtExpires > 0 ? Math.min(redisExpires || jwtExpires, jwtExpires) : redisExpires;
-  const msUntilExpiry = effectiveExpires - now;
-
-  if (msUntilExpiry > safetyWindowMs) {
-    // Durable by construction: this token came OUT of the store and we wrote nothing.
-    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false, persisted: true };
-  }
-
-  if (!session.idpRefreshToken) {
-    return {
-      ok: false,
-      code: 'NO_REFRESH_TOKEN',
-      message: 'Access token expired and no refresh token available',
-      status: 401,
-      terminal: true,
-      resolution: 'User must re-authenticate',
-    };
-  }
-
-  const lock = await acquireRefreshLock(sessionToken, requestId, lockWaitMs);
-  let weHoldLock = false;
-  let releaseVersion: number | undefined;
-
-  if (!lock.acquired) {
-    const existing = await checkRefreshLock(sessionToken);
-    if (!existing || existing.acquiredBy !== requestId) {
-      const startWait = Date.now();
-      while (Date.now() - startWait < lockWaitMs) {
-        await new Promise(r => setTimeout(r, 200));
-        const stillLocked = await checkRefreshLock(sessionToken);
-        if (!stillLocked) {
-          let after = await getSession(sessionToken);
-          if (!after || !after.idpRefreshToken) {
-            const baAfter = await getBetterAuthSession(sessionToken);
-            if (baAfter?.idpRefreshToken) after = baAfter;
-          }
-          if (after?.idpAccessToken && after.idpAccessTokenExpires) {
-            const remaining = after.idpAccessTokenExpires - Date.now();
-            if (remaining > safetyWindowMs) {
-              return {
-                ok: true,
-                accessToken: after.idpAccessToken,
-                accessTokenExpires: after.idpAccessTokenExpires,
-                refreshed: true,
-                // Read back from the store after the winner's refresh - durable.
-                persisted: true,
-              };
-            }
-          }
-          break;
-        }
-      }
-      return {
-        ok: false,
-        code: 'CONFLICT',
-        message: 'Refresh already in progress',
-        status: 409,
-        retryable: true,
-      };
-    }
-  } else {
-    weHoldLock = true;
-    releaseVersion = lock.lockInfo?.lockVersion;
-  }
-
-  try {
-    // Re-check after lock — another caller may have already refreshed.
-    let latest = await getSession(sessionToken);
-    if (!latest || !latest.idpRefreshToken) {
-      const baLatest = await getBetterAuthSession(sessionToken);
-      if (baLatest?.idpRefreshToken) latest = baLatest;
-    }
-    if (latest?.idpAccessToken && latest.idpAccessTokenExpires) {
-      const latestRemaining = latest.idpAccessTokenExpires - Date.now();
-      const latestJwtExp = decodeJwtExp(latest.idpAccessToken);
-      const stillStale = latestRemaining <= safetyWindowMs || (latestJwtExp > 0 && latestJwtExp <= Date.now());
-      if (!stillStale) {
-        return {
-          ok: true,
-          accessToken: latest.idpAccessToken,
-          accessTokenExpires: latest.idpAccessTokenExpires,
-          refreshed: true,
-          // Post-lock re-read: another caller already refreshed and stored this.
-          persisted: true,
-        };
-      }
-    }
-
-    // Build refresh request body — wire shape must match what the IDP expects.
-    let authMethods: string[] = [];
-    if (Array.isArray(session.authenticationMethods)) {
-      authMethods = session.authenticationMethods;
-    } else if (typeof session.authenticationMethods === 'string') {
-      try { authMethods = JSON.parse(session.authenticationMethods); } catch { /* fall through */ }
-    }
-    const isOAuthSession = !!session.oauthProvider;
-    if (authMethods.length === 0 && isOAuthSession) {
-      authMethods = ['pwd', 'mfa'];
-    }
-    const twoFactorMethod =
-      authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
-      session.mfaMethod ||
-      (isOAuthSession ? 'oauth' : null);
-
-    let acrValue = String(session.authenticationLevel ?? '1');
-    if (isOAuthSession && session.mfaVerified && acrValue === '1') {
-      acrValue = '2';
-    }
-
-    // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
-    // `session` was read before we acquired the lock; a concurrent refresh that
-    // completed while we waited rotates the token, so the pre-lock value is stale
-    // and would draw an avoidable 401 (the CAS now catches the resulting wipe, but
-    // the round-trip is wasted). `latest` is the authoritative post-lock session.
-    // Auth-context (amr/acr/2FA) intentionally still derives from `session` — it is
-    // the identity context of THIS request, unchanged by a token rotation.
-    const sentRefreshToken = latest?.idpRefreshToken ?? session.idpRefreshToken;
-    const body: Record<string, unknown> = {
-      refresh_token: sentRefreshToken,
-      amr: authMethods,
-      acr: acrValue,
-    };
-    if (session.mfaVerified) body.two_factor_verified = true;
-    if (twoFactorMethod) body.two_factor_method = twoFactorMethod;
-    if (session.mfaCompletedAt) body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
-
-    let idpResponse: Response;
-    try {
-      idpResponse = await fetch(`${idpBaseUrl}${refreshEndpoint}`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'X-Client-Id': clientId },
-        body: JSON.stringify(body),
-      });
-    } catch (err) {
-      return {
-        ok: false,
-        code: 'UPSTREAM_SERVICE_UNAVAILABLE',
-        message: err instanceof Error ? err.message : 'IDP unreachable',
-        status: 503,
-        retryable: true,
-      };
-    }
-
-    let responseData: any;
-    try {
-      const text = await idpResponse.text();
-      if (!text.trim()) {
-        return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Empty response from IDP', status: 502, retryable: true };
-      }
-      responseData = JSON.parse(text);
-    } catch (err) {
-      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Invalid JSON from IDP', status: 502, retryable: true };
-    }
-
-    if (!idpResponse.ok) {
-      const idpError = responseData?.error || {};
-      const code = idpError.code || 'UNKNOWN_ERROR';
-      let discardToken = idpResponse.status === 401 || idpError.discard_token === true;
-      const retryable = idpResponse.status !== 401 && idpError.retryable === true;
-      if (discardToken) {
-        // Race-safe discard (CAS): only clear if the refresh token we used is STILL
-        // current. A concurrent refresh may have already rotated it — our 401 is then
-        // stale/expected, and wiping here would silently log out a healthy session
-        // (the rotation-race wipe, QA 6873 site 1/2). Compare-and-skip if it changed;
-        // a concurrent rotation is NOT a terminal condition.
-        const postRefresh = await getSession(sessionToken);
-        // CAS compares against the token we ACTUALLY SENT (WO-2: sentRefreshToken,
-        // the post-lock value), not the pre-lock snapshot — otherwise a token rotated
-        // between pre-lock read and our send would be misjudged.
-        const tokenUnchanged =
-          !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
-        if (tokenUnchanged) {
-          /**
-           * 320072: this is the OTHER updateSession call in this file, and it
-           * does NOT escalate on a null return the way the persist site below
-           * does. Checked, not overlooked: reaching here requires
-           * `tokenUnchanged`, which requires `postRefresh?.idpRefreshToken` to
-           * equal the token we sent — so the CAS read three lines up already
-           * proved the row exists. A missing row makes tokenUnchanged false and
-           * routes to the else branch instead, so the dropped-write path is
-           * very nearly unreachable here.
-           *
-           * "Very nearly" is why the return IS still captured. The residual both
-           * halves of this merge identified is real: the row can expire between
-           * that CAS read and this write, in which case the dead refresh token is
-           * NOT cleared and the "we discarded it" claim in the error below is
-           * false. That costs nothing to observe and cannot be inferred from any
-           * other line, so it is warned rather than assumed — see `if (!cleared)`
-           * immediately below. The RESULT is unchanged either way: the session is
-           * unusable and we return the same non-ok payload.
-           */
-          const cleared = await updateSession(sessionToken, {
-            idpRefreshToken: '',
-            idpRefreshTokenExpires: undefined,
-            refreshTokenClearedAt: Date.now(),
-            refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
-          });
-          if (!cleared) {
-            console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
-              code,
-              requestId,
-            });
-          }
-        } else {
-          // Concurrent refresh already rotated the token — our 401 is stale. Return the
-          // freshly-rotated token directly so the loser succeeds without a retry round-trip
-          // (race-fix follow-up #1).
-          discardToken = false;
-          if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
-            return {
-              ok: true,
-              accessToken: postRefresh.idpAccessToken,
-              accessTokenExpires: postRefresh.idpAccessTokenExpires,
-              refreshed: true,
-              // `postRefresh` is a store read, so this token is by definition stored.
-              persisted: true,
-            };
-          }
-        }
-      }
-      return {
-        ok: false,
-        code,
-        message: idpError.message || 'Token refresh failed',
-        status: idpResponse.status,
-        discardToken,
-        retryable,
-        resolution: idpError.resolution,
-        terminal: discardToken,
-      };
-    }
-
-    // Validate canonical envelope.
-    if (
-      !responseData ||
-      typeof responseData !== 'object' ||
-      responseData.success !== true ||
-      !responseData.data
-    ) {
-      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Non-compliant IDP envelope', status: 502, retryable: true };
-    }
-
-    const newAccess = responseData.data.access_token;
-    const newRefresh = responseData.data.refresh_token;
-    if (!newAccess) {
-      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Missing access token in IDP response', status: 500 };
-    }
-
-    let accessTokenExpires: number;
-    let refreshTokenExpires: number | undefined;
-    let decoded: any;
-    try {
-      const r = computeTokenExpiries({ accessToken: newAccess, refreshToken: newRefresh, preferJwt: true });
-      decoded = r.decodedAccessToken;
-      accessTokenExpires = r.accessTokenExpires;
-      refreshTokenExpires = r.refreshTokenExpires;
-    } catch {
-      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Failed to decode new tokens', status: 500 };
-    }
-
-    let amrClaims: string[] = [];
-    if (decoded?.amr) {
-      try {
-        amrClaims = typeof decoded.amr === 'string' ? JSON.parse(decoded.amr) : decoded.amr;
-      } catch {
-        amrClaims = session.authenticationMethods || [];
-      }
-    } else {
-      amrClaims = session.authenticationMethods || [];
-    }
-    const acrLevel = String(decoded?.acr || session.authenticationLevel || '1');
-    const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
-    const newKid = extractKidFromToken(newAccess);
-
-    // *** CARD 320072. CAPTURE THIS RETURN. ***
-    // `updateSession` returns null - and writes nothing - when the canonical
-    // session row is missing, which happens whenever the BA fallback above is what
-    // resolved this session. Discarding the return is what let this function
-    // report `ok:true, refreshed:true` for a refresh it had just thrown away.
-    // The full rationale for what we DO about it is at the `if (!persisted)`
-    // block below; this line only makes the answer available.
-    const persisted = await updateSession(sessionToken, {
-      ...session,
-      idpAccessToken: newAccess,
-      idpAccessTokenExpires: accessTokenExpires,
-      idpRefreshToken: hasNewRefresh ? newRefresh : session.idpRefreshToken,
-      idpRefreshTokenExpires: hasNewRefresh ? refreshTokenExpires : session.idpRefreshTokenExpires,
-      decodedAccessToken: decoded,
-      bearerKeyId: newKid || session.bearerKeyId,
-      authenticationMethods: amrClaims,
-      authenticationLevel: acrLevel,
-      // 170007 rule 2 (BAPert ruling on 121350): re-derive from the token
-      // every exchange, never carry forward. See the identical fix + full
-      // rationale in api-handlers/auth/refresh.ts's sessionUpdate — this is
-      // the same defect duplicated at a second call site.
-      mfaVerified: amrClaims.includes('mfa'),
-      mfaCompletedAt: decoded?.mfa_time ? parseInt(decoded.mfa_time) * 1000 : session.mfaCompletedAt,
-      mfaExpiresAt: decoded?.mfa_expires ? parseInt(decoded.mfa_expires) * 1000 : session.mfaExpiresAt,
-      mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
-    });
-
-    /**
-     * 320072: DO NOT REPORT SUCCESS FOR A WRITE THAT WAS DISCARDED.
-     *
-     * `updateSession` returns null when the canonical session row is absent,
-     * which silently throws away EVERYTHING above — the new access token, the
-     * rotated refresh token, decodedAccessToken, authenticationMethods,
-     * mfaVerified, mfaCompletedAt, mfaExpiresAt. This return value was
-     * previously ignored, and the line below then reported
-     * `ok: true, refreshed: true`.
-     *
-     * WHY THAT IS WORSE THAN A PLAIN LOST WRITE. By this point the exchange at
-     * the IDP has ALREADY HAPPENED, so if refresh tokens are single-use the
-     * token we sent is now spent and its replacement is the thing we just
-     * dropped. The stored credential is therefore dead, and every later attempt
-     * re-sends that same dead token and fails. The user is bounced to LOGIN —
-     * not to verify-code — with nothing in the logs naming the cause.
-     *
-     * It did not even surface as a wrong answer to our one caller: server/auth.ts
-     * calls getRedisSession immediately after us, which is this same `getSession`,
-     * so it finds the same missing row and returns a generic NO_SESSION one frame
-     * later. The false `ok: true` was thus invisible AND the real cause — a
-     * dropped persist — was reported as an unrelated missing session.
-     *
-     * Naming it here is the point: the failure is reported at its true cause,
-     * with a code that says the refresh succeeded and the PERSIST is what
-     * failed. Not retryable — retrying burns another refresh token the same way.
-     *
-     * This is the card's option (b), deliberately. Option (a) — teaching
-     * updateSession to write through to whichever store holds the session,
-     * mirroring the read fallback above — is the better end state but changes
-     * write-path storage semantics for every caller, which is not this card.
-     *
-     * AND IT IS ALSO LOGGED, WHICH IS NOT THE SAME THING (BAPert R1134 §7,
-     * re-affirmed in R1145 §2c). Returning a named code tells the CALLER. §7
-     * requires that `persisted:false` reach a log A HUMAN READS, because the one
-     * caller — server/auth.ts — converts every non-ok result into the same
-     * generic 401 and keeps no record of which code produced it. Without this
-     * line the distinction we just bought at the type level is erased one frame
-     * later and no operator ever sees the word PERSIST. The escalation is the
-     * contract; the warn is the evidence.
-     */
-    if (!persisted) {
-      console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
-        requestId,
-        refreshTokenRotated: hasNewRefresh,
-        persisted: false,
-      });
-      return {
-        ok: false,
-        code: 'SESSION_PERSIST_FAILED',
-        message:
-          'Token refresh succeeded at the IDP but the session could not be persisted; the rotated tokens were discarded.',
-        status: 401,
-        terminal: true,
-        retryable: false,
-        discardToken: true,
-        resolution: 'REAUTHENTICATE',
-      };
-    }
-
-    // `persisted: true` is not decoration and not a leftover: the `if` above is
-    // the only way out for a dropped write, so by construction anything reaching
-    // this line WAS written. Keeping the field keeps the ok:true branch of
-    // EnsureFreshResult total (Cases 2 and 7 assert on it) — BAPert R1145 §2d.
-    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true, persisted: true };
-  } finally {
-    if (weHoldLock) {
-      await releaseRefreshLock(sessionToken, requestId, releaseVersion);
-    }
-  }
-}
+/**
+ * ensureFreshAccessToken — server-side preflight refresh.
+ *
+ * Returns a non-expired IDP access token for a given session. Refreshes
+ * proactively when the stored token is within the safety window of expiry,
+ * using the same Redis lock and IDP wire shape as `createRefreshHandler`.
+ *
+ * Designed for proxy-route auth helpers that today read the stored token
+ * blindly and let the backend reject it with a 401. Calling this instead of
+ * `getSession(...).idpAccessToken` means a good token client never sends
+ * credentials it already knows are invalid.
+ *
+ * Single-use refresh-token semantics are preserved via Redis-backed
+ * single-flight locking (see `acquireRefreshLock`).
+ */
+import {
+  getSession,
+  getBetterAuthSession,
+  updateSession,
+  acquireRefreshLock,
+  releaseRefreshLock,
+  checkRefreshLock,
+} from './session-store';
+import { computeTokenExpiries } from './token-expiry';
+import { extractKidFromToken } from '../auth/utils/token-utils';
+
+export interface EnsureFreshConfig {
+  idpBaseUrl: string;
+  clientId: string;
+  refreshEndpoint?: string;
+}
+
+export interface EnsureFreshOptions {
+  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
+  safetyWindowMs?: number;
+  /** Max wait while another caller holds the refresh lock. Default 5000. */
+  lockWaitMs?: number;
+  /** Optional caller request id for lock attribution. */
+  requestId?: string;
+}
+
+export type EnsureFreshResult =
+  | {
+      ok: true;
+      accessToken: string;
+      accessTokenExpires: number;
+      /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
+      refreshed: boolean;
+      /**
+       * CARD 320072. Is the token in THIS result actually in the session store?
+       *
+       * ON THIS BRANCH OF THE UNION IT IS ALWAYS `true`, AND THAT IS THE POINT.
+       * Every `ok: true` return either read the token back from the store or
+       * wrote it and confirmed the write. An unpersisted refresh does not reach
+       * an `ok: true` result at all — it returns `ok:false, SESSION_PERSIST_FAILED`
+       * from the other branch below.
+       *
+       * READ THIS BEFORE YOU DELETE THE FIELD. It is declared `boolean` rather
+       * than the literal `true` on purpose: it is the assertable witness that the
+       * escalation is still wired. If someone later re-weakens the persist site
+       * back to reporting success, this field is where that regression becomes
+       * visible to a test instead of invisible to everyone. Cases 2 and 7 in
+       * test/ensure-fresh-persist-failure.test.cjs assert on it.
+       *
+       * WHAT THIS COMMENT USED TO SAY, AND WHY IT IS GONE. It documented `false`
+       * as a live value on an ok:true result — "we hold a valid token that was
+       * not persisted" — because that WAS the contract before this merge, when
+       * the dropped write was reported as a success with a flag on it. Blending
+       * in the escalation made that sentence describe a state the code can no
+       * longer produce. A docblock asserting an impossible semantic is exactly
+       * the defect f5ac6dc3 was written to fix, one file over; reproducing it
+       * here while merging that fix would be absurd.
+       */
+      persisted: boolean;
+    }
+  | {
+      ok: false;
+      code: string;
+      message: string;
+      status: number;
+      terminal?: boolean;
+      discardToken?: boolean;
+      retryable?: boolean;
+      resolution?: string;
+    };
+
+const DEFAULT_SAFETY_WINDOW_MS = 60_000;
+const DEFAULT_LOCK_WAIT_MS = 5000;
+
+function decodeJwtExp(token: string): number {
+  const parts = token.split('.');
+  if (parts.length !== 3) return -1;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return (payload.exp || 0) * 1000;
+  } catch {
+    return -1;
+  }
+}
+
+export async function ensureFreshAccessToken(
+  sessionToken: string,
+  config: EnsureFreshConfig,
+  options: EnsureFreshOptions = {}
+): Promise<EnsureFreshResult> {
+  const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
+  const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
+  const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
+  const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
+
+  let session = await getSession(sessionToken);
+  if (!session || !session.idpRefreshToken) {
+    const baSession = await getBetterAuthSession(sessionToken);
+    if (baSession?.idpRefreshToken) {
+      session = baSession;
+    }
+  }
+  if (!session) {
+    return { ok: false, code: 'NO_SESSION', message: 'No session for token', status: 401, terminal: true };
+  }
+
+  const storedToken = session.idpAccessToken;
+  if (!storedToken) {
+    // Card 187871: same conflation as getIdpToken (server/auth.ts) - a live
+    // session with no access token and mfaVerified !== true is a user
+    // mid-2FA, not dead. Only terminal once the session itself claims 2FA
+    // is already done.
+    if (session.mfaVerified !== true) {
+      return { ok: false, code: 'NO_TOKEN_PENDING_2FA', message: 'Two-factor authentication required', status: 401, terminal: false };
+    }
+    return { ok: false, code: 'NO_TOKEN', message: 'No IDP access token in session', status: 401, terminal: true };
+  }
+
+  const now = Date.now();
+  const redisExpires = session.idpAccessTokenExpires ?? 0;
+  const jwtExpires = decodeJwtExp(storedToken);
+  // Use the smaller of the two to be conservative — Redis can be stale, JWT exp is authoritative.
+  const effectiveExpires = jwtExpires > 0 ? Math.min(redisExpires || jwtExpires, jwtExpires) : redisExpires;
+  const msUntilExpiry = effectiveExpires - now;
+
+  if (msUntilExpiry > safetyWindowMs) {
+    // Durable by construction: this token came OUT of the store and we wrote nothing.
+    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false, persisted: true };
+  }
+
+  if (!session.idpRefreshToken) {
+    return {
+      ok: false,
+      code: 'NO_REFRESH_TOKEN',
+      message: 'Access token expired and no refresh token available',
+      status: 401,
+      terminal: true,
+      resolution: 'User must re-authenticate',
+    };
+  }
+
+  const lock = await acquireRefreshLock(sessionToken, requestId, lockWaitMs);
+  let weHoldLock = false;
+  let releaseVersion: number | undefined;
+
+  if (!lock.acquired) {
+    const existing = await checkRefreshLock(sessionToken);
+    if (!existing || existing.acquiredBy !== requestId) {
+      const startWait = Date.now();
+      while (Date.now() - startWait < lockWaitMs) {
+        await new Promise(r => setTimeout(r, 200));
+        const stillLocked = await checkRefreshLock(sessionToken);
+        if (!stillLocked) {
+          let after = await getSession(sessionToken);
+          if (!after || !after.idpRefreshToken) {
+            const baAfter = await getBetterAuthSession(sessionToken);
+            if (baAfter?.idpRefreshToken) after = baAfter;
+          }
+          if (after?.idpAccessToken && after.idpAccessTokenExpires) {
+            const remaining = after.idpAccessTokenExpires - Date.now();
+            if (remaining > safetyWindowMs) {
+              return {
+                ok: true,
+                accessToken: after.idpAccessToken,
+                accessTokenExpires: after.idpAccessTokenExpires,
+                refreshed: true,
+                // Read back from the store after the winner's refresh - durable.
+                persisted: true,
+              };
+            }
+          }
+          break;
+        }
+      }
+      return {
+        ok: false,
+        code: 'CONFLICT',
+        message: 'Refresh already in progress',
+        status: 409,
+        retryable: true,
+      };
+    }
+  } else {
+    weHoldLock = true;
+    releaseVersion = lock.lockInfo?.lockVersion;
+  }
+
+  try {
+    // Re-check after lock — another caller may have already refreshed.
+    let latest = await getSession(sessionToken);
+    if (!latest || !latest.idpRefreshToken) {
+      const baLatest = await getBetterAuthSession(sessionToken);
+      if (baLatest?.idpRefreshToken) latest = baLatest;
+    }
+    if (latest?.idpAccessToken && latest.idpAccessTokenExpires) {
+      const latestRemaining = latest.idpAccessTokenExpires - Date.now();
+      const latestJwtExp = decodeJwtExp(latest.idpAccessToken);
+      const stillStale = latestRemaining <= safetyWindowMs || (latestJwtExp > 0 && latestJwtExp <= Date.now());
+      if (!stillStale) {
+        return {
+          ok: true,
+          accessToken: latest.idpAccessToken,
+          accessTokenExpires: latest.idpAccessTokenExpires,
+          refreshed: true,
+          // Post-lock re-read: another caller already refreshed and stored this.
+          persisted: true,
+        };
+      }
+    }
+
+    // Build refresh request body — wire shape must match what the IDP expects.
+    let authMethods: string[] = [];
+    if (Array.isArray(session.authenticationMethods)) {
+      authMethods = session.authenticationMethods;
+    } else if (typeof session.authenticationMethods === 'string') {
+      try { authMethods = JSON.parse(session.authenticationMethods); } catch { /* fall through */ }
+    }
+    const isOAuthSession = !!session.oauthProvider;
+    if (authMethods.length === 0 && isOAuthSession) {
+      authMethods = ['pwd', 'mfa'];
+    }
+    const twoFactorMethod =
+      authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
+      session.mfaMethod ||
+      (isOAuthSession ? 'oauth' : null);
+
+    let acrValue = String(session.authenticationLevel ?? '1');
+    if (isOAuthSession && session.mfaVerified && acrValue === '1') {
+      acrValue = '2';
+    }
+
+    // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
+    // `session` was read before we acquired the lock; a concurrent refresh that
+    // completed while we waited rotates the token, so the pre-lock value is stale
+    // and would draw an avoidable 401 (the CAS now catches the resulting wipe, but
+    // the round-trip is wasted). `latest` is the authoritative post-lock session.
+    // Auth-context (amr/acr/2FA) intentionally still derives from `session` — it is
+    // the identity context of THIS request, unchanged by a token rotation.
+    const sentRefreshToken = latest?.idpRefreshToken ?? session.idpRefreshToken;
+    const body: Record<string, unknown> = {
+      refresh_token: sentRefreshToken,
+      amr: authMethods,
+      acr: acrValue,
+    };
+    if (session.mfaVerified) body.two_factor_verified = true;
+    if (twoFactorMethod) body.two_factor_method = twoFactorMethod;
+    if (session.mfaCompletedAt) body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
+
+    let idpResponse: Response;
+    try {
+      idpResponse = await fetch(`${idpBaseUrl}${refreshEndpoint}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-Client-Id': clientId },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        code: 'UPSTREAM_SERVICE_UNAVAILABLE',
+        message: err instanceof Error ? err.message : 'IDP unreachable',
+        status: 503,
+        retryable: true,
+      };
+    }
+
+    let responseData: any;
+    try {
+      const text = await idpResponse.text();
+      if (!text.trim()) {
+        return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Empty response from IDP', status: 502, retryable: true };
+      }
+      responseData = JSON.parse(text);
+    } catch (err) {
+      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Invalid JSON from IDP', status: 502, retryable: true };
+    }
+
+    if (!idpResponse.ok) {
+      const idpError = responseData?.error || {};
+      const code = idpError.code || 'UNKNOWN_ERROR';
+      let discardToken = idpResponse.status === 401 || idpError.discard_token === true;
+      const retryable = idpResponse.status !== 401 && idpError.retryable === true;
+      if (discardToken) {
+        // Race-safe discard (CAS): only clear if the refresh token we used is STILL
+        // current. A concurrent refresh may have already rotated it — our 401 is then
+        // stale/expected, and wiping here would silently log out a healthy session
+        // (the rotation-race wipe, QA 6873 site 1/2). Compare-and-skip if it changed;
+        // a concurrent rotation is NOT a terminal condition.
+        const postRefresh = await getSession(sessionToken);
+        // CAS compares against the token we ACTUALLY SENT (WO-2: sentRefreshToken,
+        // the post-lock value), not the pre-lock snapshot — otherwise a token rotated
+        // between pre-lock read and our send would be misjudged.
+        const tokenUnchanged =
+          !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
+        if (tokenUnchanged) {
+          /**
+           * 320072: this is the OTHER updateSession call in this file, and it
+           * does NOT escalate on a null return the way the persist site below
+           * does. Checked, not overlooked: reaching here requires
+           * `tokenUnchanged`, which requires `postRefresh?.idpRefreshToken` to
+           * equal the token we sent — so the CAS read three lines up already
+           * proved the row exists. A missing row makes tokenUnchanged false and
+           * routes to the else branch instead, so the dropped-write path is
+           * very nearly unreachable here.
+           *
+           * "Very nearly" is why the return IS still captured. The residual both
+           * halves of this merge identified is real: the row can expire between
+           * that CAS read and this write, in which case the dead refresh token is
+           * NOT cleared and the "we discarded it" claim in the error below is
+           * false. That costs nothing to observe and cannot be inferred from any
+           * other line, so it is warned rather than assumed — see `if (!cleared)`
+           * immediately below. The RESULT is unchanged either way: the session is
+           * unusable and we return the same non-ok payload.
+           */
+          const cleared = await updateSession(sessionToken, {
+            idpRefreshToken: '',
+            idpRefreshTokenExpires: undefined,
+            refreshTokenClearedAt: Date.now(),
+            refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
+          });
+          if (!cleared) {
+            console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
+              code,
+              requestId,
+            });
+          }
+        } else {
+          // Concurrent refresh already rotated the token — our 401 is stale. Return the
+          // freshly-rotated token directly so the loser succeeds without a retry round-trip
+          // (race-fix follow-up #1).
+          discardToken = false;
+          if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+            return {
+              ok: true,
+              accessToken: postRefresh.idpAccessToken,
+              accessTokenExpires: postRefresh.idpAccessTokenExpires,
+              refreshed: true,
+              // `postRefresh` is a store read, so this token is by definition stored.
+              persisted: true,
+            };
+          }
+        }
+      }
+      return {
+        ok: false,
+        code,
+        message: idpError.message || 'Token refresh failed',
+        status: idpResponse.status,
+        discardToken,
+        retryable,
+        resolution: idpError.resolution,
+        terminal: discardToken,
+      };
+    }
+
+    // Validate canonical envelope.
+    if (
+      !responseData ||
+      typeof responseData !== 'object' ||
+      responseData.success !== true ||
+      !responseData.data
+    ) {
+      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Non-compliant IDP envelope', status: 502, retryable: true };
+    }
+
+    const newAccess = responseData.data.access_token;
+    const newRefresh = responseData.data.refresh_token;
+    if (!newAccess) {
+      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Missing access token in IDP response', status: 500 };
+    }
+
+    let accessTokenExpires: number;
+    let refreshTokenExpires: number | undefined;
+    let decoded: any;
+    try {
+      const r = computeTokenExpiries({ accessToken: newAccess, refreshToken: newRefresh, preferJwt: true });
+      decoded = r.decodedAccessToken;
+      accessTokenExpires = r.accessTokenExpires;
+      refreshTokenExpires = r.refreshTokenExpires;
+    } catch {
+      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Failed to decode new tokens', status: 500 };
+    }
+
+    let amrClaims: string[] = [];
+    if (decoded?.amr) {
+      try {
+        amrClaims = typeof decoded.amr === 'string' ? JSON.parse(decoded.amr) : decoded.amr;
+      } catch {
+        amrClaims = session.authenticationMethods || [];
+      }
+    } else {
+      amrClaims = session.authenticationMethods || [];
+    }
+    const acrLevel = String(decoded?.acr || session.authenticationLevel || '1');
+    const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
+    const newKid = extractKidFromToken(newAccess);
+
+    // *** CARD 320072. CAPTURE THIS RETURN. ***
+    // `updateSession` returns null - and writes nothing - when the canonical
+    // session row is missing, which happens whenever the BA fallback above is what
+    // resolved this session. Discarding the return is what let this function
+    // report `ok:true, refreshed:true` for a refresh it had just thrown away.
+    // The full rationale for what we DO about it is at the `if (!persisted)`
+    // block below; this line only makes the answer available.
+    const persisted = await updateSession(sessionToken, {
+      ...session,
+      idpAccessToken: newAccess,
+      idpAccessTokenExpires: accessTokenExpires,
+      idpRefreshToken: hasNewRefresh ? newRefresh : session.idpRefreshToken,
+      idpRefreshTokenExpires: hasNewRefresh ? refreshTokenExpires : session.idpRefreshTokenExpires,
+      decodedAccessToken: decoded,
+      bearerKeyId: newKid || session.bearerKeyId,
+      authenticationMethods: amrClaims,
+      authenticationLevel: acrLevel,
+      // 170007 rule 2 (BAPert ruling on 121350): re-derive from the token
+      // every exchange, never carry forward. See the identical fix + full
+      // rationale in api-handlers/auth/refresh.ts's sessionUpdate — this is
+      // the same defect duplicated at a second call site.
+      mfaVerified: amrClaims.includes('mfa'),
+      mfaCompletedAt: decoded?.mfa_time ? parseInt(decoded.mfa_time) * 1000 : session.mfaCompletedAt,
+      mfaExpiresAt: decoded?.mfa_expires ? parseInt(decoded.mfa_expires) * 1000 : session.mfaExpiresAt,
+      mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
+    });
+
+    /**
+     * 320072: DO NOT REPORT SUCCESS FOR A WRITE THAT WAS DISCARDED.
+     *
+     * `updateSession` returns null when the canonical session row is absent,
+     * which silently throws away EVERYTHING above — the new access token, the
+     * rotated refresh token, decodedAccessToken, authenticationMethods,
+     * mfaVerified, mfaCompletedAt, mfaExpiresAt. This return value was
+     * previously ignored, and the line below then reported
+     * `ok: true, refreshed: true`.
+     *
+     * WHY THAT IS WORSE THAN A PLAIN LOST WRITE. By this point the exchange at
+     * the IDP has ALREADY HAPPENED, so if refresh tokens are single-use the
+     * token we sent is now spent and its replacement is the thing we just
+     * dropped. The stored credential is therefore dead, and every later attempt
+     * re-sends that same dead token and fails. The user is bounced to LOGIN —
+     * not to verify-code — with nothing in the logs naming the cause.
+     *
+     * It did not even surface as a wrong answer to our one caller: server/auth.ts
+     * calls getRedisSession immediately after us, which is this same `getSession`,
+     * so it finds the same missing row and returns a generic NO_SESSION one frame
+     * later. The false `ok: true` was thus invisible AND the real cause — a
+     * dropped persist — was reported as an unrelated missing session.
+     *
+     * Naming it here is the point: the failure is reported at its true cause,
+     * with a code that says the refresh succeeded and the PERSIST is what
+     * failed. Not retryable — retrying burns another refresh token the same way.
+     *
+     * This is the card's option (b), deliberately. Option (a) — teaching
+     * updateSession to write through to whichever store holds the session,
+     * mirroring the read fallback above — is the better end state but changes
+     * write-path storage semantics for every caller, which is not this card.
+     *
+     * AND IT IS ALSO LOGGED, WHICH IS NOT THE SAME THING (BAPert R1134 §7,
+     * re-affirmed in R1145 §2c). Returning a named code tells the CALLER. §7
+     * requires that `persisted:false` reach a log A HUMAN READS, because the one
+     * caller — server/auth.ts — converts every non-ok result into the same
+     * generic 401 and keeps no record of which code produced it. Without this
+     * line the distinction we just bought at the type level is erased one frame
+     * later and no operator ever sees the word PERSIST. The escalation is the
+     * contract; the warn is the evidence.
+     */
+    if (!persisted) {
+      console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
+        requestId,
+        refreshTokenRotated: hasNewRefresh,
+        persisted: false,
+      });
+      return {
+        ok: false,
+        code: 'SESSION_PERSIST_FAILED',
+        message:
+          'Token refresh succeeded at the IDP but the session could not be persisted; the rotated tokens were discarded.',
+        status: 401,
+        terminal: true,
+        retryable: false,
+        discardToken: true,
+        resolution: 'REAUTHENTICATE',
+      };
+    }
+
+    // `persisted: true` is not decoration and not a leftover: the `if` above is
+    // the only way out for a dropped write, so by construction anything reaching
+    // this line WAS written. Keeping the field keeps the ok:true branch of
+    // EnsureFreshResult total (Cases 2 and 7 assert on it) — BAPert R1145 §2d.
+    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true, persisted: true };
+  } finally {
+    if (weHoldLock) {
+      await releaseRefreshLock(sessionToken, requestId, releaseVersion);
+    }
+  }
+}