@payez/next-mvp 4.10.0 → 4.12.0

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

@@ -25,6 +25,17 @@ 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';
+import { errForLog } from './log-safe';
 
 export interface EnsureFreshConfig {
   idpBaseUrl: string;
@@ -33,10 +44,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 +67,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 +113,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 +159,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 +193,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 +239,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 +253,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 +278,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 +294,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 +371,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 +401,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: errForLog(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 +449,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 +536,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 +602,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 +651,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 +667,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 +687,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 +757,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/geolocation.ts

@@ -1,3 +1,4 @@
+import { errForLog } from './log-safe';
 /**
  * =============================================================================
  * GEOLOCATION UTILITY
@@ -103,7 +104,7 @@ export async function getPublicIP(): Promise<string | null> {
         // Validate it looks like an IP
         if (ip && /^[\d.]+$/.test(ip) || /^[a-f0-9:]+$/i.test(ip)) {
           cachedPublicIP = { ip, timestamp: Date.now() };
-          console.log(`[geolocation] Public IP resolved: ${ip}`);
+          console.log("[geolocation] Public IP resolved");
           return ip;
         }
       }
@@ -163,7 +164,7 @@ export async function getLocationFromIP(ip: string, resolvePublicIP: boolean = t
     if (resolvePublicIP) {
       const publicIP = await getPublicIP();
       if (publicIP && !isPrivateIP(publicIP)) {
-        console.log(`[geolocation] Private IP ${ip} -> using public IP ${publicIP}`);
+        console.log("[geolocation] Private IP -> using the resolved public IP");
         // Recursively call with public IP (but don't resolve again to prevent loops)
         return getLocationFromIP(publicIP, false);
       }
@@ -201,7 +202,7 @@ export async function getLocationFromIP(ip: string, resolvePublicIP: boolean = t
     const data = await response.json();
 
     if (data.status !== 'success') {
-      console.warn(`[geolocation] Lookup failed for ${ip}: ${data.message}`);
+      console.warn("[geolocation] Lookup failed (upstream refused)");
       // Cache the failure to avoid repeated lookups
       geoCache.set(ip, { location: null, timestamp: Date.now() });
       return null;
@@ -224,7 +225,7 @@ export async function getLocationFromIP(ip: string, resolvePublicIP: boolean = t
     return location;
 
   } catch (error) {
-    console.error(`[geolocation] Error looking up ${ip}:`, error);
+    console.error("[geolocation] lookup failed:", errForLog(error)); // no IP on a routine line (BAPert 76553 Q1)
     return null;
   }
 }

package/src/lib/idp-client-config.ts

@@ -43,6 +43,7 @@
 import 'server-only';
 import { createHash, randomUUID } from 'crypto';
 import { markNeverInResponse } from './never-in-response';
+import { errForLog } from './log-safe';
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -360,7 +361,7 @@ async function getConfigFromRedis(): Promise<IDPClientConfig | null> {
 
         return parsed.config;
     } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to read from Redis cache:', error);
+        console.warn('[IDP_CONFIG] Failed to read from Redis cache:', errForLog(error));
         return null;
     }
 }
@@ -377,7 +378,7 @@ async function setConfigInRedis(config: IDPClientConfig): Promise<void> {
         // Store with TTL slightly longer than the logical expiry to allow for clock skew
         await (await getRedis()).set(key, JSON.stringify(data), 'EX', ttlSeconds + 10);
     } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to write to Redis cache:', error);
+        console.warn('[IDP_CONFIG] Failed to write to Redis cache:', errForLog(error));
     }
 }
 
@@ -633,7 +634,7 @@ export async function clearConfigRedisCache(): Promise<void> {
         await (await getRedis()).del(key);
         console.log('[IDP_CONFIG] Redis cache cleared:', key);
     } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to clear Redis cache:', error);
+        console.warn('[IDP_CONFIG] Failed to clear Redis cache:', errForLog(error));
     }
 }
 

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
@@ -45,6 +46,14 @@ export interface IdpFetchOptions {
    * `skipped: true` without a request; null on the retry leaves the first answer standing. Absent: `init` is used as before.
    */
   initFor?: (sessionToken: string) => Promise<RequestInit | null>;
+  /**
+   * 4.12: the refresh that follows a 401/403 is done by THIS function instead of the HTTP self-call to /api/auth/refresh. Sign-out supplies one that
+   * calls `ensureFreshAccessToken` in-process with a window that cannot be "fresh": a logout 401 with a locally-fresh token usually means Core
+   * invalidated the token (password change), and only the IdP's answer to a real refresh (401 + the discard marker = the grant is dead; success =
+   * the grant is live) can say which. No header on the public refresh route, so nothing a browser sends can force a refresh (BAPert 77022).
+   * Returns the status the refresh route would have answered. Absent: `internalRefresh` as before.
+   */
+  refreshOnAuthFailure?: (sessionToken: string) => Promise<{ ok: boolean; status: number }>;
 }
 
 function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
@@ -119,8 +128,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.
@@ -183,7 +192,9 @@ export async function idpFetchJSON<T = any>(
     attemptedRefresh = true;
     try {
       // Use centralized internal API helper for server-to-server calls
-      const rf = await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+      const rf = opts.refreshOnAuthFailure
+        ? await opts.refreshOnAuthFailure(sessionToken)
+        : await internalRefresh(req.headers.get('cookie') || '', sessionToken);
       refreshStatus = rf.status;
       if (rf.ok) {
         const fresh = await getSession(sessionToken);

package/src/lib/idp-logout.ts

@@ -26,6 +26,19 @@ import { ENV_CONFIG } from '../config/env';
  */
 export type IdpLogoutOutcome = 'revoked' | 'nothing-to-revoke' | 'grant-already-dead';
 
+/**
+ * The revoke could not be confirmed. `grantLive` is true ONLY when the IdP itself showed the grant is alive: the forced refresh SUCCEEDED (it issued
+ * new tokens) and the logout still did not end it. Every other unknown (a transport error, a 5xx, a refresh that threw or answered something
+ * else) leaves it false: the grant may be live or dead, and the log must not claim either (BAPert 77013). The closed `code` is what errForLog prints.
+ */
+export class IdpLogoutUnconfirmedError extends Error {
+  readonly code = 'IDP_LOGOUT_UNCONFIRMED';
+  constructor(status: number, readonly grantLive: boolean) {
+    super(`IdP logout answered ${status}`);
+    this.name = 'IdpLogoutUnconfirmedError';
+  }
+}
+
 export async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOutcome> {
   let resolvedSession: string | undefined;
   const result = await idpFetchJSON(
@@ -33,6 +46,9 @@ export async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOut
     `${ENV_CONFIG.IDP_URL}/api/Account/logout`,
     {},
     {
+      // A logout 401 with a locally-fresh token must reach a REAL refresh, so the IdP's answer can prove the grant dead (BAPert 77013). Done
+      // in-process, not through the public refresh route, so no request header can force it (NightHawk 77021, BAPert 77022).
+      refreshOnAuthFailure: forceRefreshAtIdp,
       initFor: async (token) => {
         resolvedSession = token;
         let session = await getSession(token);
@@ -50,7 +66,26 @@ export async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOut
   if (result.skipped) return 'nothing-to-revoke';
   if (result.ok) return 'revoked';
   if (result.attemptedRefresh && result.refreshStatus === 401 && resolvedSession && (await grantWasDiscarded(resolvedSession))) return 'grant-already-dead';
-  throw new Error(`IdP logout answered ${result.status}`);
+  const refreshSucceeded = result.attemptedRefresh && typeof result.refreshStatus === 'number' && result.refreshStatus >= 200 && result.refreshStatus < 300;
+  throw new IdpLogoutUnconfirmedError(result.status, refreshSucceeded);
+}
+
+/**
+ * Refresh the session NOW, ignoring "the stored access token looks fresh", by calling `ensureFreshAccessToken` in this process (the one
+ * implementation that talks to the IdP, holds the lock and writes the discard marker). Config is read the way `oauth/resume` reads it
+ * (IDP_URL, CLIENT_ID, the default refresh endpoint). It answers with the status the refresh route would have: 200 on success, 401 for
+ * NO_SESSION / NO_REFRESH_TOKEN, 409 for a lost lock, otherwise E's own status (a discarded IdP 401 is 401 with the marker written).
+ * Missing config or a throw is an UNKNOWN outcome: the caller treats a thrown refresh as `refreshStatus: null`.
+ */
+async function forceRefreshAtIdp(sessionToken: string): Promise<{ ok: boolean; status: number }> {
+  const idpBaseUrl = process.env.IDP_URL;
+  const clientId = process.env.CLIENT_ID;
+  if (!idpBaseUrl || !clientId) throw new Error('IDP_URL and CLIENT_ID are required to prove a grant dead');
+  const { ensureFreshAccessToken } = await import('./ensure-fresh-access-token');
+  const r = await ensureFreshAccessToken(sessionToken, { idpBaseUrl, clientId }, { requireRefreshToken: true, safetyWindowMs: Number.MAX_SAFE_INTEGER });
+  if (r.ok) return { ok: true, status: 200 };
+  const status = r.code === 'NO_SESSION' || r.code === 'NO_REFRESH_TOKEN' ? 401 : r.code === 'CONFLICT' ? 409 : r.status;
+  return { ok: false, status };
 }
 
 /**

package/src/lib/jwt-decode-client.ts

@@ -3,6 +3,8 @@
  * This is a lightweight version for browser usage
  */
 
+import { errForLog } from './log-safe';
+
 // Decode base64url
 function base64urlDecode(base64url: string): string {
   try {
@@ -39,7 +41,7 @@ export function jwtDecode<T = any>(token: string): T | null {
 
     return parsedPayload;
   } catch (e) {
-    console.error('[JWT] Decode failed:', e instanceof Error ? e.message : 'Unknown error');
+    console.error('[JWT] Decode failed:', errForLog(e));
     return null;
   }
 }

package/src/lib/jwt-decode.ts

@@ -1,4 +1,5 @@
 import { jwtDecode as originalJwtDecode } from 'jwt-decode';
+import { errForLog } from './log-safe';
 
 // Define JwtPayload interface since jwt-decode v4 doesn't export it
 export interface JwtPayload {
@@ -65,7 +66,7 @@ export function decodeJwtHeader(token: string): JwtHeader | null {
 
         return JSON.parse(headerJson) as JwtHeader;
     } catch (error) {
-        console.error('[JWT_DECODE] Failed to decode JWT header:', error);
+        console.error('[JWT_DECODE] Failed to decode JWT header:', errForLog(error));
         return null;
     }
 }