@payez/next-mvp 4.10.0 → 4.11.0

package/src/auth/utils/token-utils.ts

@@ -9,6 +9,7 @@
 
 import { jwtDecode, decodeJwtHeader, extractKidFromToken, JwtHeader } from '../../lib/jwt-decode';
 import type { DecodedIdpAccessToken } from '../types/auth-types';
+import { REFRESH_WINDOW_MS } from '../../lib/refresh-window';
 
 // Re-export header utilities for consumers
 export { decodeJwtHeader, extractKidFromToken, type JwtHeader } from '../../lib/jwt-decode';
@@ -137,12 +138,12 @@ export function extractAmrFromToken(decoded: DecodedIdpAccessToken): string[] {
  * Check if a token expiry timestamp indicates the token needs refresh.
  *
  * @param expiresAt - Token expiry timestamp (Unix milliseconds)
- * @param bufferMs - How early to trigger refresh (default 5 minutes)
+ * @param bufferMs - How early to trigger refresh (default: the one refresh window, `REFRESH_WINDOW_MS`, 5 minutes)
  * @returns true if token is expired or will expire within buffer period
  */
 export function tokenNeedsRefresh(
   expiresAt: number | undefined,
-  bufferMs: number = 5 * 60 * 1000
+  bufferMs: number = REFRESH_WINDOW_MS
 ): boolean {
   if (!expiresAt) {
     return true; // No expiry info = assume needs refresh

package/src/lib/api-handler.ts

@@ -26,6 +26,7 @@ import {
 import { getJwtCookieName } from './app-slug';
 import { getTokenTestAware } from './test-aware-get-token';
 import { internalRefresh } from './internal-api';
+import { REFRESH_WINDOW_MS } from './refresh-window';
 
 // ============================================================================
 // Types
@@ -284,7 +285,7 @@ export class ApiHandler {
       // Skip the optimization (hasRefreshToken check) when access token is missing —
       // some session shapes store the refresh token under different field names,
       // and we still want a refresh attempt to populate the access token.
-      const thresholdMs = 5 * 60 * 1000;
+      const thresholdMs = REFRESH_WINDOW_MS;
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const expires = sessionData.idpAccessTokenExpires || (sessionData as any).accessTokenExpires || 0;
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -426,7 +427,7 @@ export class ApiHandler {
     try {
       // Double-check if still needs refresh
       const latest = await getSession(sessionToken);
-      const thresholdMs = 5 * 60 * 1000;
+      const thresholdMs = REFRESH_WINDOW_MS;
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const latestAny = latest as any;
       // Sessions may store the access token under either `accessToken` or `idpAccessToken`,
@@ -481,7 +482,7 @@ export class ApiHandler {
         const session = await getSession(sessionToken);
         if (session?.accessToken) {
           const expires = session.accessTokenExpires || 0;
-          if ((expires - Date.now()) > (5 * 60 * 1000)) {
+          if ((expires - Date.now()) > REFRESH_WINDOW_MS) {
             return { success: true };
           }
         }

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

@@ -25,6 +25,16 @@ import {
 import { computeTokenExpiries } from './token-expiry';
 import { extractKidFromToken } from '../auth/utils/token-utils';
 import { rotatedRowIsUsable } from './refresh-rotation';
+import { REFRESH_WINDOW_MS } from './refresh-window';
+import { sanitizeTraceId } from './safe-trace-id';
+import {
+  REFRESH_FETCH_TIMEOUT_MS,
+  REFRESH_OUTCOME_UNKNOWN_CODE,
+  UPSTREAM_TIMEOUT_CODE,
+  inDoubtPatch,
+  isRefreshInDoubt,
+  requestNeverLeft,
+} from './refresh-in-doubt';
 
 export interface EnsureFreshConfig {
   idpBaseUrl: string;
@@ -33,10 +43,15 @@ export interface EnsureFreshConfig {
 }
 
 export interface EnsureFreshOptions {
-  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
+  /** Refresh if the access token is within this many ms of expiry. Default REFRESH_WINDOW_MS (5 min, lib/refresh-window). */
   safetyWindowMs?: number;
   /** Max wait while another caller holds the refresh lock. Default 5000. */
   lockWaitMs?: number;
+  /**
+   * The refresh ROUTE sets this (BAPert 76449, R-over-E PR 2): a session with no refresh token is refused with the terminal NO_REFRESH_TOKEN
+   * even when its access token is still fresh, as the route always did. Other callers leave it unset and get `already_fresh` for a fresh token.
+   */
+  requireRefreshToken?: boolean;
   /**
    * Optional caller request id, for LOG CORRELATION ONLY. It is never the lock identity: the lock id is minted here with
    * crypto.randomUUID(). (BAPert 76298 (b): the lock id used to be this value, taken from the request's x-request-id header.)
@@ -51,6 +66,14 @@ export type EnsureFreshResult =
       accessTokenExpires: number;
       /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
       refreshed: boolean;
+      /**
+       * WHY this result is ok (BAPert 76449, additive; `api-handlers/auth/refresh` reproduces its bodies from it and `lib/token-lifecycle` reads
+       * `already_fresh`): 'already_fresh' = nothing was needed; 'completed_by_concurrent_request' = another request refreshed and we returned
+       * its result; 'refreshed' = THIS call refreshed.
+       */
+      reason: 'refreshed' | 'already_fresh' | 'completed_by_concurrent_request';
+      /** Whether the stored session holds a refresh token (the refresh route reports it in its body). */
+      hasRefreshToken: boolean;
       /**
        * CARD 320072. Is the token in THIS result actually in the session store?
        *
@@ -89,7 +112,25 @@ export type EnsureFreshResult =
       resolution?: string;
     };
 
-const DEFAULT_SAFETY_WINDOW_MS = 60_000;
+/**
+ * The refresh envelope rule (BAPert 76455 (B)): `success` is a boolean; `success:true` needs a `data` object holding a string `access_token`;
+ * `success:false` needs `error.code` as a string; `meta`, `request_id` and `time_stamp` are optional; a non-2xx can not say success:true.
+ */
+export function checkRefreshEnvelope(body: any, httpOk: boolean): { ok: true } | { ok: false; why: string } {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return { ok: false, why: 'body is not an object' };
+  if (typeof body.success !== 'boolean') return { ok: false, why: 'success is not a boolean' };
+  if (body.success === true) {
+    if (!httpOk) return { ok: false, why: 'success:true on a non-2xx' };
+    if (!body.data || typeof body.data !== 'object' || typeof body.data.access_token !== 'string' || !body.data.access_token) {
+      return { ok: false, why: 'success:true without data.access_token' };
+    }
+  } else if (!body.error || typeof body.error !== 'object' || typeof body.error.code !== 'string' || !body.error.code) {
+    return { ok: false, why: 'success:false without error.code' };
+  }
+  return { ok: true };
+}
+
+const DEFAULT_SAFETY_WINDOW_MS = REFRESH_WINDOW_MS; // was 60_000; one window for R, E and idp-fetch (BAPert 76397 decision 1)
 const DEFAULT_LOCK_WAIT_MS = 5000;
 
 function decodeJwtExp(token: string): number {
@@ -117,18 +158,33 @@ export async function ensureFreshAccessToken(
   // reuse as compromise and revokes descendants across devices) must not be bypassable by an id the caller picks. Date.now() also
   // collided for two calls in the same millisecond. The caller's id is kept as `traceId`, for logs only.
   const requestId = `ensure_fresh_${randomUUID()}`;
-  const traceId = options.requestId;
+  // Attacker-chosen text going to the log sink: control characters stripped and length capped (PAY-2376).
+  const traceId = sanitizeTraceId(options.requestId);
 
-  let session = await getSession(sessionToken);
+  const canonicalFirst = await getSession(sessionToken);
+  let session = canonicalFirst;
   if (!session || !session.idpRefreshToken) {
     const baSession = await getBetterAuthSession(sessionToken);
     if (baSession?.idpRefreshToken) {
       session = baSession;
     }
   }
+  // `persisted` means the CANONICAL row (BAPert 76449): a token served from the Better Auth fallback record is not stored where the
+  // persist writes.
+  const sessionIsCanonical = !!canonicalFirst && session === canonicalFirst;
   if (!session) {
     return { ok: false, code: 'NO_SESSION', message: 'No session for token', status: 401, terminal: true };
   }
+  if (options.requireRefreshToken && !session.idpRefreshToken) {
+    return {
+      ok: false,
+      code: 'NO_REFRESH_TOKEN',
+      message: 'No refresh token available',
+      status: 401,
+      terminal: true,
+      resolution: 'User must re-authenticate',
+    };
+  }
 
   const storedToken = session.idpAccessToken;
   if (!storedToken) {
@@ -136,22 +192,28 @@ export async function ensureFreshAccessToken(
     // 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.
+    //
+    // BAPert 76449 (A): a pending-2FA row keeps NO_TOKEN_PENDING_2FA EVEN WITH a refresh token: refresh must never be a way around 2FA.
+    // A row that is NOT pending 2FA and has a refresh token is refreshed below (a missing access token is the reason to refresh, as the
+    // refresh route always did); with no refresh token it is NO_TOKEN as before.
     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 };
+    if (!session.idpRefreshToken) {
+      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);
+  const jwtExpires = storedToken ? decodeJwtExp(storedToken) : 0;
   // 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 (storedToken && msUntilExpiry > safetyWindowMs) {
+    // This token came OUT of the store and we wrote nothing; `persisted` is true only when that store row is the canonical one.
+    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false, reason: 'already_fresh', hasRefreshToken: !!session.idpRefreshToken, persisted: sessionIsCanonical };
   }
 
   if (!session.idpRefreshToken) {
@@ -176,7 +238,8 @@ export async function ensureFreshAccessToken(
         await new Promise(r => setTimeout(r, 200));
         const stillLocked = await checkRefreshLock(sessionToken);
         if (!stillLocked) {
-          let after = await getSession(sessionToken);
+          const canonicalAfter = await getSession(sessionToken);
+          let after = canonicalAfter;
           if (!after || !after.idpRefreshToken) {
             const baAfter = await getBetterAuthSession(sessionToken);
             if (baAfter?.idpRefreshToken) after = baAfter;
@@ -189,8 +252,10 @@ export async function ensureFreshAccessToken(
                 accessToken: after.idpAccessToken,
                 accessTokenExpires: after.idpAccessTokenExpires,
                 refreshed: true,
-                // Read back from the store after the winner's refresh - durable.
-                persisted: true,
+                reason: 'completed_by_concurrent_request',
+                hasRefreshToken: !!after.idpRefreshToken,
+                // Read back from the store after the winner's refresh; `persisted` only when that row is the canonical one.
+                persisted: !!canonicalAfter && after === canonicalAfter,
               };
             }
           }
@@ -212,7 +277,8 @@ export async function ensureFreshAccessToken(
 
   try {
     // Re-check after lock — another caller may have already refreshed.
-    let latest = await getSession(sessionToken);
+    const canonicalLatest = await getSession(sessionToken);
+    let latest = canonicalLatest;
     if (!latest || !latest.idpRefreshToken) {
       const baLatest = await getBetterAuthSession(sessionToken);
       if (baLatest?.idpRefreshToken) latest = baLatest;
@@ -227,12 +293,54 @@ export async function ensureFreshAccessToken(
           accessToken: latest.idpAccessToken,
           accessTokenExpires: latest.idpAccessTokenExpires,
           refreshed: true,
-          // Post-lock re-read: another caller already refreshed and stored this.
-          persisted: true,
+          reason: 'completed_by_concurrent_request',
+          hasRefreshToken: !!latest.idpRefreshToken,
+          // Post-lock re-read: another caller already refreshed and stored this; `persisted` only when the row read is the canonical one.
+          persisted: !!canonicalLatest && latest === canonicalLatest,
         };
       }
     }
 
+    // R-over-E (BAPert 76318 item 4 / 1432 (b2), now E's own): the token SENT is the one in the POST-lock read, so that read must still hold
+    // one. A row that VANISHED while we waited for the lock is 'no session'; a row whose refresh token was DISCARDED meanwhile (token cleared,
+    // marker written by a concurrent request) is the terminal NO_REFRESH_TOKEN. Neither reaches the IdP, and an empty token is never sent.
+    if (!latest) {
+      return { ok: false, code: 'NO_SESSION', message: 'No session for token', status: 401, terminal: true };
+    }
+    if (!latest.idpRefreshToken) {
+      return {
+        ok: false,
+        code: 'NO_REFRESH_TOKEN',
+        message: 'No refresh token available',
+        status: 401,
+        terminal: true,
+        resolution: 'User must re-authenticate',
+      };
+    }
+
+    // BAPert 76397 Finding 1: the persist below writes ONLY to the canonical row (updateSession merges into it and returns null when it is
+    // absent). A session that lives only under the Better Auth key can be READ above through the fallback, but the rotated tokens would have
+    // nowhere to go: the IdP would spend the refresh token and we would lose its replacement (SESSION_PERSIST_FAILED, after the fact). So
+    // refuse BEFORE the IdP call. Nothing is spent, nothing is discarded, the Better Auth record is left alone; the session has to be
+    // re-established.
+    if (!canonicalLatest) {
+      console.warn('[ENSURE-FRESH] refresh refused before the IDP call - no canonical session row to persist into', {
+        requestId,
+        traceId,
+        betterAuthOnly: !!latest,
+      });
+      return {
+        ok: false,
+        code: 'NO_CANONICAL_SESSION',
+        message: 'The session has no canonical record to store a refreshed token in; no refresh was attempted.',
+        status: 401,
+        terminal: true,
+        retryable: false,
+        discardToken: false,
+        resolution: 'REAUTHENTICATE',
+      };
+    }
+
     // Build refresh request body — wire shape must match what the IDP expects.
     let authMethods: string[] = [];
     if (Array.isArray(session.authenticationMethods)) {
@@ -262,6 +370,27 @@ export async function ensureFreshAccessToken(
     // 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;
+
+    // BAPert 76403: an earlier attempt for THIS token timed out, so Core may already have consumed it; re-sending it is a replay, and a
+    // replay revokes every newer token the user holds. Refuse WITHOUT calling the IdP; one fresh login instead.
+    if (isRefreshInDoubt(canonicalLatest, sentRefreshToken)) {
+      console.error('[ENSURE-FRESH] refusing to re-send a refresh token whose earlier attempt timed out (outcome unknown)', {
+        requestId,
+        traceId,
+        inDoubtSince: canonicalLatest.refreshInDoubtAt,
+      });
+      return {
+        ok: false,
+        code: REFRESH_OUTCOME_UNKNOWN_CODE,
+        message: 'An earlier refresh for this session did not complete and its outcome is unknown; the session must be re-established.',
+        status: 401,
+        terminal: true,
+        retryable: false,
+        discardToken: false,
+        resolution: 'REAUTHENTICATE',
+      };
+    }
+
     const body: Record<string, unknown> = {
       refresh_token: sentRefreshToken,
       amr: authMethods,
@@ -271,18 +400,45 @@ export async function ensureFreshAccessToken(
     if (twoFactorMethod) body.two_factor_method = twoFactorMethod;
     if (session.mfaCompletedAt) body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
 
+    // BAPert 76403: a timeout is OUTCOME-UNKNOWN. Record the identity of the token we sent (a hash) so the next attempt refuses instead of
+    // replaying it, and answer 504. `retryable` is false on purpose: the retry would be refused with REFRESH_OUTCOME_UNKNOWN.
+    const answerTimedOut = async (cause?: unknown): Promise<EnsureFreshResult> => {
+      console.error('[ENSURE-FRESH] IDP did not answer (timeout or a transport failure that does not prove the request never left) - outcome unknown, marking the refresh in doubt', {
+        requestId,
+        traceId,
+        timeoutMs: REFRESH_FETCH_TIMEOUT_MS,
+        cause: cause instanceof Error ? `${cause.name}: ${cause.message}` : undefined,
+      });
+      try {
+        await updateSession(sessionToken, inDoubtPatch(sentRefreshToken as string));
+      } catch (markError) {
+        console.error('[ENSURE-FRESH] could not record the in-doubt marker', { error: markError instanceof Error ? markError.message : String(markError) });
+      }
+      return {
+        ok: false,
+        code: UPSTREAM_TIMEOUT_CODE,
+        message: 'The identity service did not answer in time; the outcome of this refresh is unknown.',
+        status: 504,
+        terminal: false,
+        retryable: false,
+        discardToken: false,
+      };
+    };
+
     let idpResponse: Response;
     try {
       idpResponse = await fetch(`${idpBaseUrl}${refreshEndpoint}`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'X-Client-Id': clientId },
         body: JSON.stringify(body),
+        signal: AbortSignal.timeout(REFRESH_FETCH_TIMEOUT_MS),
       });
     } catch (err) {
+      if (!requestNeverLeft(err)) return await answerTimedOut(err); // timeout or ANY transport failure that does not prove the request never left (BAPert 76433)
       return {
         ok: false,
         code: 'UPSTREAM_SERVICE_UNAVAILABLE',
-        message: err instanceof Error ? err.message : 'IDP unreachable',
+        message: 'IDP service unavailable', // BAPert 76449: R's wording; the raw error text (host names, socket details) is not returned
         status: 503,
         retryable: true,
       };
@@ -292,11 +448,30 @@ export async function ensureFreshAccessToken(
     try {
       const text = await idpResponse.text();
       if (!text.trim()) {
+        if (idpResponse.ok) return await answerTimedOut(new Error('empty 2xx body')); // a 2xx with no body: the replacement is lost (BAPert 76441)
         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 (!(err instanceof SyntaxError) || idpResponse.ok) return await answerTimedOut(err); // BAPert 76441: a body-READ failure is in doubt; so is a 2xx whose body does not parse (Core processed the grant, i.e. consumed the token, and the replacement is lost). A non-2xx unparseable body (a gateway HTML 502/503) did not mint: a completed failure, no marker.
+      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Invalid response from IDP', status: 502, retryable: true };
+    }
+
+    // BAPert 76455 (B): ONE envelope rule for both refresh implementations. `meta` is NOT required: Core's four hint-carrying error returns on
+    // POST /api/ExternalAuth/refresh (ExternalAuthController :3708, :3778, :3805, :3822) are hand-built { success:false, error:{ code,
+    // message, discard_token, retryable, resolution } } objects with no meta, no data, no request_id, no time_stamp, and they are exactly the
+    // answers whose code and flags matter. Requiring meta would turn them into a 502 and lose both.
+    const envelope = checkRefreshEnvelope(responseData, idpResponse.ok);
+    if (!envelope.ok) {
+      console.warn('[ENSURE-FRESH] non-compliant IDP envelope', {
+        requestId,
+        traceId,
+        // the response header if Core sent one, otherwise our own generated id - never a made-up Core request_id
+        idpRequestId: idpResponse.headers?.get?.('x-request-id') ?? requestId,
+        status: idpResponse.status,
+        why: envelope.why,
+      });
+      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Non-compliant IDP envelope', status: 502, retryable: true };
     }
 
     if (!idpResponse.ok) {
@@ -360,7 +535,9 @@ export async function ensureFreshAccessToken(
               accessToken: postRefresh.idpAccessToken,
               accessTokenExpires: postRefresh.idpAccessTokenExpires,
               refreshed: true,
-              // `postRefresh` is a store read, so this token is by definition stored.
+              reason: 'completed_by_concurrent_request',
+              hasRefreshToken: !!postRefresh.idpRefreshToken,
+              // `postRefresh` is a canonical store read (getSession), so this token is stored where the persist writes.
               persisted: true,
             };
           }
@@ -424,6 +601,8 @@ export async function ensureFreshAccessToken(
             accessToken: postRefresh.idpAccessToken,
             accessTokenExpires: postRefresh.idpAccessTokenExpires,
             refreshed: true,
+            reason: 'completed_by_concurrent_request',
+            hasRefreshToken: !!postRefresh.idpRefreshToken,
             persisted: true,
           };
         }
@@ -471,12 +650,12 @@ export async function ensureFreshAccessToken(
       try {
         amrClaims = typeof decoded.amr === 'string' ? JSON.parse(decoded.amr) : decoded.amr;
       } catch {
-        amrClaims = session.authenticationMethods || [];
+        amrClaims = canonicalLatest.authenticationMethods || [];
       }
     } else {
-      amrClaims = session.authenticationMethods || [];
+      amrClaims = canonicalLatest.authenticationMethods || [];
     }
-    const acrLevel = String(decoded?.acr || session.authenticationLevel || '1');
+    const acrLevel = String(decoded?.acr || canonicalLatest.authenticationLevel || '1');
     const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
     const newKid = extractKidFromToken(newAccess);
 
@@ -487,14 +666,19 @@ export async function ensureFreshAccessToken(
     // 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.
+    //
+    // BAPert 76449 item 11 (the twin of 1432 (b2)): every FALLBACK below reads the POST-lock canonical row (`canonicalLatest`), never the
+    // pre-lock `session`. With no new refresh token from the IdP the store must keep the token that was SENT (`sentRefreshToken`); the
+    // pre-lock value is spent whenever a concurrent request rotated the token while this one waited for the lock. The old `...session`
+    // spread (the whole PRE-lock row) is gone too: updateSession merges into the current row, so only the fields below are written and a
+    // concurrent writer's change to anything else survives.
     const persisted = await updateSession(sessionToken, {
-      ...session,
       idpAccessToken: newAccess,
       idpAccessTokenExpires: accessTokenExpires,
-      idpRefreshToken: hasNewRefresh ? newRefresh : session.idpRefreshToken,
-      idpRefreshTokenExpires: hasNewRefresh ? refreshTokenExpires : session.idpRefreshTokenExpires,
+      idpRefreshToken: hasNewRefresh ? newRefresh : sentRefreshToken,
+      idpRefreshTokenExpires: hasNewRefresh ? refreshTokenExpires : canonicalLatest.idpRefreshTokenExpires,
       decodedAccessToken: decoded,
-      bearerKeyId: newKid || session.bearerKeyId,
+      bearerKeyId: newKid || canonicalLatest.bearerKeyId,
       authenticationMethods: amrClaims,
       authenticationLevel: acrLevel,
       // 170007 rule 2 (BAPert ruling on 121350): re-derive from the token
@@ -502,9 +686,9 @@ export async function ensureFreshAccessToken(
       // 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,
+      mfaCompletedAt: decoded?.mfa_time ? parseInt(decoded.mfa_time) * 1000 : canonicalLatest.mfaCompletedAt,
+      mfaExpiresAt: decoded?.mfa_expires ? parseInt(decoded.mfa_expires) * 1000 : canonicalLatest.mfaExpiresAt,
+      mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : canonicalLatest.mfaValidityHours,
     });
 
     /**
@@ -572,7 +756,7 @@ export async function ensureFreshAccessToken(
     // 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 };
+    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true, reason: 'refreshed', hasRefreshToken: true, persisted: true };
   } finally {
     if (weHoldLock) {
       await releaseRefreshLock(sessionToken, requestId, releaseVersion);

package/src/lib/idp-fetch.ts

@@ -4,6 +4,7 @@ import { getSession } from './session-store';
 import { internalRefresh } from './internal-api';
 import { assertAbsoluteIdpUrl } from './idp-url-guard';
 import { parseRetryAfterSeconds } from './retry-after';
+import { REFRESH_WINDOW_MS } from './refresh-window';
 
 // Re-exported so `idp-fetch` remains the single obvious import for IDP calling
 // concerns; the implementation lives in a dependency-free leaf so the three
@@ -119,8 +120,8 @@ async function ensureFreshAccessToken(req: NextRequest): Promise<{ sessionToken?
   const hasRefreshToken = !!session.idpRefreshToken;
   const now = Date.now();
   const timeLeft = (session.idpAccessTokenExpires ?? now) - now;
-  // Treat tokens as effectively expired if within 5 minutes of expiry
-  if (timeLeft > 5 * 60 * 1000) {
+  // Treat tokens as effectively expired if within REFRESH_WINDOW_MS of expiry (lib/refresh-window: the one window)
+  if (timeLeft > REFRESH_WINDOW_MS) {
     return { sessionToken, accessToken: session.idpAccessToken, hasRefreshToken };
   }
   // Only attempt refresh when we actually have a refresh token to use.

package/src/lib/refresh-in-doubt.ts

@@ -0,0 +1,79 @@
+/**
+ * The IdP fetch timeout and the "refresh in doubt" marker (BAPert 76397 decision 3, corrected by 76403; Core facts DotNetPert 76400).
+ *
+ * THE PROBLEM. Core consumes a refresh token with one atomic UPDATE and has NO reuse grace: re-presenting a used token revokes every newer
+ * refresh token the USER holds, on every device (RevokeDescendantTokens). So when OUR fetch to the IdP times out, we do not know whether Core
+ * consumed the token and minted a replacement whose answer we never saw. The store still holds the token we SENT (nothing was persisted).
+ * Holding the refresh lock only delays the next request by its 60 s TTL; after that the next request re-reads the same token and replays it.
+ *
+ * THE RULE. A timed-out refresh answers 504 UPSTREAM_TIMEOUT and records, on the session row, an IDENTITY (a SHA-256, never the token and
+ * never a prefix of it) of the token that was sent. Any later attempt whose token-to-send matches that identity refuses WITHOUT calling the
+ * IdP: terminal REFRESH_OUTCOME_UNKNOWN / REAUTHENTICATE. One login on one session is better than a user-wide revocation. The marker is
+ * dropped by the same write that stores a DIFFERENT refresh token (session-store `dropStaleDiscardMarker`); nothing tries to resolve the doubt
+ * without a login.
+ *
+ * Leaf module: no imports from the rest of the package, so session-store can use it without a cycle.
+ */
+import { createHash } from 'crypto';
+
+/** How long a refresh fetch (connect, response and body) may take. 5 s lock wait + this + the persist stays well inside the 60 s lock TTL. */
+export const REFRESH_FETCH_TIMEOUT_MS = 10_000;
+
+/** The typed terminal answer for an attempt that would re-send an in-doubt token. */
+export const REFRESH_OUTCOME_UNKNOWN_CODE = 'REFRESH_OUTCOME_UNKNOWN';
+
+/** The typed answer for the timed-out call itself. */
+export const UPSTREAM_TIMEOUT_CODE = 'UPSTREAM_TIMEOUT';
+
+/** A one-way identity for a refresh token. Not reversible and not a prefix. */
+export function refreshTokenIdentity(token: string): string {
+  return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+
+/** The row fields recorded at a timeout. */
+export function inDoubtPatch(sentToken: string): { refreshInDoubtTokenHash: string; refreshInDoubtAt: number } {
+  return { refreshInDoubtTokenHash: refreshTokenIdentity(sentToken), refreshInDoubtAt: Date.now() };
+}
+
+/** True when the token we are about to send is the one a previous attempt left in doubt. */
+export function isRefreshInDoubt(
+  session: { refreshInDoubtTokenHash?: string | null } | null | undefined,
+  tokenToSend: string | null | undefined,
+): boolean {
+  if (!session || typeof session.refreshInDoubtTokenHash !== 'string' || !session.refreshInDoubtTokenHash) return false;
+  if (typeof tokenToSend !== 'string' || tokenToSend.length === 0) return false;
+  return refreshTokenIdentity(tokenToSend) === session.refreshInDoubtTokenHash;
+}
+
+/** True for the error `AbortSignal.timeout` produces (a DOMException named TimeoutError); AbortError is treated the same. */
+export function isTimeoutError(err: unknown): boolean {
+  const name = (err as { name?: string } | null | undefined)?.name;
+  return name === 'TimeoutError' || name === 'AbortError';
+}
+
+/**
+ * The ONLY transport error codes that PROVE the request never left this process (BAPert 76433 item 4): the connection was refused, or the
+ * name did not resolve. Anything else (ECONNRESET, UND_ERR_SOCKET, a timeout, an error with no code) may have happened AFTER the request was
+ * written, so the IdP may have consumed the token: outcome unknown. The cost is lopsided on purpose: a false in-doubt costs one re-login, a
+ * missed one costs a user-wide revocation. Do NOT add a code here without proof it can only occur before the request is sent.
+ */
+export const REQUEST_NEVER_LEFT_CODES: ReadonlySet<string> = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN']);
+
+/** Every `code` on the error, its `cause`, and the members of an AggregateError (undici wraps the socket error in `cause`). */
+function transportCodes(err: unknown, depth = 0, out: string[] = []): string[] {
+  if (!err || typeof err !== 'object' || depth > 4) return out;
+  const e = err as { code?: unknown; cause?: unknown; errors?: unknown };
+  if (typeof e.code === 'string' && e.code) out.push(e.code);
+  if (e.cause) transportCodes(e.cause, depth + 1, out);
+  if (Array.isArray(e.errors)) for (const inner of e.errors) transportCodes(inner, depth + 1, out);
+  return out;
+}
+
+/**
+ * True only when the error carries at least one cause code and EVERY code it carries is in the never-left allowlist. An error with no code
+ * is NOT proof, so it is in-doubt.
+ */
+export function requestNeverLeft(err: unknown): boolean {
+  const codes = transportCodes(err);
+  return codes.length > 0 && codes.every((c) => REQUEST_NEVER_LEFT_CODES.has(c));
+}

package/src/lib/refresh-token-validator.ts

@@ -1,5 +1,6 @@
 import { jwtDecode } from './jwt-decode';
 import { tokenRefreshLogger } from '../config/logger';
+import { REFRESH_WINDOW_MS } from './refresh-window';
 
 interface RefreshTokenPayload { exp: number; iat: number; jti: string; user_id: string; token_type: string; binding: string; }
 
@@ -38,7 +39,7 @@ export function checkRefreshViability(sessionData: any): RefreshViabilityCheck {
     if (typeof expiresAtMs === 'string') expiresAtMs = parseInt(expiresAtMs, 10);
     if (expiresAtMs < 1000000000000) expiresAtMs = expiresAtMs * 1000;
     accessTokenTimeRemaining = Math.floor((expiresAtMs - now) / 1000);
-    const bufferSec = 5 * 60; // 5 minutes pre-expiry buffer
+    const bufferSec = REFRESH_WINDOW_MS / 1000; // the one refresh window (lib/refresh-window), in seconds
     accessTokenExpired = accessTokenTimeRemaining <= bufferSec;
     tokenRefreshLogger.debug('[REFRESH_VIABILITY] Access token expiration check', { now, expiresAtMs, accessTokenTimeRemaining, bufferSec, accessTokenExpired });
   }

package/src/lib/refresh-window.ts

@@ -0,0 +1,16 @@
+/**
+ * THE freshness window for an IdP access token (BAPert 76397 decision 1; Core facts DotNetPert 76400).
+ *
+ * An access token with this much life left or less is treated as stale and refreshed; with more, it is served as it is. One value for
+ * every path that decides: the mounted refresh route (`api-handlers/auth/refresh`), `ensureFreshAccessToken`, and `lib/idp-fetch`'s own
+ * pre-check. They used to disagree (5 min, 60 s, 5 min), so the same session was "stale" to one path and "fresh" to another, which is how
+ * two callers each rotated a token the other had just rotated.
+ *
+ * WHY 5 MINUTES: Core mints access tokens with a fixed 15-minute lifetime (a code constant, not configuration: Core
+ * `TokenConstants.ACCESS_TOKEN_LIFETIME_MINUTES = 15`, read-only in `TokenSettings`). The ruling is 5 minutes when the lifetime is at least 15
+ * minutes, and lifetime / 3 otherwise. If Core ever shortens the lifetime, this value MUST be revisited: a window at or above the lifetime
+ * makes every request refresh.
+ *
+ * A caller that needs another value passes it explicitly (`ensureFreshAccessToken`'s `safetyWindowMs` option still exists and still wins).
+ */
+export const REFRESH_WINDOW_MS = 5 * 60 * 1000;

package/src/lib/safe-trace-id.ts

@@ -0,0 +1,21 @@
+/**
+ * A caller-supplied trace id (the `x-request-id` header) is attacker-chosen text, and it goes to the log sink (PAY-2376; BAPert 76321 item 4,
+ * NightHawk 76316). Two problems if it is logged as it arrives: a value with a newline forges a log line, and an unbounded value is a log
+ * flood. This is the one place that makes it safe to log: control characters are removed, the length is capped, and anything that is not a
+ * non-empty string becomes `undefined` (so the log carries no trace id rather than a forged one).
+ *
+ * It is for LOG CORRELATION ONLY. It is never a lock identity and never a security decision (the lock id is minted server-side).
+ */
+
+/** Longest trace id that is logged. 64 covers a UUID (36) and common trace formats; longer input is cut, not rejected. */
+export const MAX_TRACE_ID_LENGTH = 64;
+
+// C0 controls (incl. CR, LF, TAB, ESC), DEL, C1 controls (incl. NEL U+0085), and the Unicode line/paragraph separators U+2028 / U+2029.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+
+export function sanitizeTraceId(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const cleaned = value.replace(CONTROL_CHARS, '').slice(0, MAX_TRACE_ID_LENGTH);
+  return cleaned.length > 0 ? cleaned : undefined;
+}