@payez/next-mvp 4.9.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

@@ -24,6 +24,17 @@ import {
 } from './session-store';
 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;
@@ -32,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.)
@@ -50,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?
        *
@@ -88,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 {
@@ -116,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) {
@@ -135,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) {
@@ -175,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;
@@ -188,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,
               };
             }
           }
@@ -211,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;
@@ -226,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)) {
@@ -261,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,
@@ -270,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,
       };
@@ -291,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) {
@@ -353,16 +529,29 @@ export async function ensureFreshAccessToken(
           // 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) {
+          if (rotatedRowIsUsable(postRefresh)) {
             return {
               ok: true,
               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,
             };
           }
+          // Rotated by a concurrent refresh but the row it left is NOT usable (BAPert 76359): the retryable 502, the rotated token kept, no
+          // marker. Same meaning in every branch (lib/refresh-rotation).
+          return {
+            ok: false,
+            code,
+            message: idpError.message || 'Token refresh failed',
+            status: 502,
+            discardToken: false,
+            retryable: true,
+            resolution: idpError.resolution,
+          };
         }
       }
       return {
@@ -378,6 +567,57 @@ export async function ensureFreshAccessToken(
     }
 
     // Validate canonical envelope.
+    // 4.9.0 (BAPert 76298 (c)): ONE IdP answer, ONE meaning, in both refresh implementations (api-handlers/auth/refresh.ts has the twin of
+    // this block). A 200 envelope with success:false used to be a generic 502 here, with discard_token ignored, while the other twin
+    // honoured it. Now: success:false + discard_token discards the stored token (same CAS as the HTTP-401 branch above, same
+    // IDP_DISCARD_TOKEN marker) and answers terminal 401; success:false without discard_token is a retryable 502 and the token is KEPT.
+    if (responseData && typeof responseData === 'object' && responseData.success === false) {
+      const idpError = responseData.error || {};
+      const code = idpError.code || 'UPSTREAM_VALIDATION_ERROR';
+      if (idpError.discard_token === true) {
+        const postRefresh = await getSession(sessionToken);
+        const tokenUnchanged = !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
+        if (tokenUnchanged) {
+          await updateSession(sessionToken, {
+            idpRefreshToken: '',
+            idpRefreshTokenExpires: undefined,
+            refreshTokenClearedAt: Date.now(),
+            refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
+          });
+          return {
+            ok: false,
+            code,
+            message: idpError.message || 'Token refresh failed',
+            status: 401,
+            discardToken: true,
+            retryable: false,
+            resolution: idpError.resolution,
+            terminal: true,
+          };
+        }
+        if (rotatedRowIsUsable(postRefresh)) {
+          return {
+            ok: true,
+            accessToken: postRefresh.idpAccessToken,
+            accessTokenExpires: postRefresh.idpAccessTokenExpires,
+            refreshed: true,
+            reason: 'completed_by_concurrent_request',
+            hasRefreshToken: !!postRefresh.idpRefreshToken,
+            persisted: true,
+          };
+        }
+      }
+      return {
+        ok: false,
+        code,
+        message: idpError.message || 'Token refresh failed',
+        status: 502,
+        discardToken: false,
+        retryable: true,
+        resolution: idpError.resolution,
+      };
+    }
+
     if (
       !responseData ||
       typeof responseData !== 'object' ||
@@ -410,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);
 
@@ -426,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
@@ -441,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,
     });
 
     /**
@@ -511,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/idp-logout.ts

@@ -14,8 +14,10 @@ import { ENV_CONFIG } from '../config/env';
  *   'revoked'            the IdP answered 2xx.
  *   'nothing-to-revoke'  the session holds no IdP refresh token (a provisional pre-2FA session has none). No call is made, because
  *                        without a token Core would pick the newest session.
- *   'grant-already-dead' the revoke was refused (401/403) and the refresh that followed was answered 401: refresh.ts calls that
- *                        "definitively invalid", the token is expired or revoked, so there is nothing left to end (BAPert 76289 item 3).
+ *   'grant-already-dead' the revoke was refused AND the refresh that followed was answered 401 AND the session carries the IdP's own
+ *                        discard marker (refreshTokenClearedReason starting 'IDP_DISCARD_TOKEN'). A refresh 401 alone is NOT proof
+ *                        (refresh.ts also answers 401 for 'no session', the x-session-token rejection and NO_REFRESH_TOKEN), and neither
+ *                        is an empty token (BAPert 76297). Anything else is UNKNOWN.
  * THROWS for an UNKNOWN outcome: a transport error, a 5xx, a refresh that could not be attempted or failed some other way. The caller
  * turns that into SESSION_NOT_ENDED.
  *