@payez/next-mvp 4.10.0 → 4.12.0

package/dist/lib/ensure-fresh-access-token.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkRefreshEnvelope = checkRefreshEnvelope;
 exports.ensureFreshAccessToken = ensureFreshAccessToken;
 /**
  * ensureFreshAccessToken — server-side preflight refresh.
@@ -21,7 +22,32 @@ const session_store_1 = require("./session-store");
 const token_expiry_1 = require("./token-expiry");
 const token_utils_1 = require("../auth/utils/token-utils");
 const refresh_rotation_1 = require("./refresh-rotation");
-const DEFAULT_SAFETY_WINDOW_MS = 60_000;
+const refresh_window_1 = require("./refresh-window");
+const safe_trace_id_1 = require("./safe-trace-id");
+const refresh_in_doubt_1 = require("./refresh-in-doubt");
+const log_safe_1 = require("./log-safe");
+/**
+ * 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.
+ */
+function checkRefreshEnvelope(body, httpOk) {
+    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_1.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) {
     const parts = token.split('.');
@@ -45,37 +71,58 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
     // 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_${(0, crypto_1.randomUUID)()}`;
-    const traceId = options.requestId;
-    let session = await (0, session_store_1.getSession)(sessionToken);
+    // Attacker-chosen text going to the log sink: control characters stripped and length capped (PAY-2376).
+    const traceId = (0, safe_trace_id_1.sanitizeTraceId)(options.requestId);
+    const canonicalFirst = await (0, session_store_1.getSession)(sessionToken);
+    let session = canonicalFirst;
     if (!session || !session.idpRefreshToken) {
         const baSession = await (0, session_store_1.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) {
         // Card 187871: same conflation as getIdpToken (server/auth.ts) - a live
         // session with no access token and mfaVerified !== true is a user
         // mid-2FA, not dead. Only terminal once the session itself claims 2FA
         // is already done.
+        //
+        // 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) {
         return {
@@ -97,7 +144,8 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                 await new Promise(r => setTimeout(r, 200));
                 const stillLocked = await (0, session_store_1.checkRefreshLock)(sessionToken);
                 if (!stillLocked) {
-                    let after = await (0, session_store_1.getSession)(sessionToken);
+                    const canonicalAfter = await (0, session_store_1.getSession)(sessionToken);
+                    let after = canonicalAfter;
                     if (!after || !after.idpRefreshToken) {
                         const baAfter = await (0, session_store_1.getBetterAuthSession)(sessionToken);
                         if (baAfter?.idpRefreshToken)
@@ -111,8 +159,10 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                                 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,
                             };
                         }
                     }
@@ -134,7 +184,8 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
     }
     try {
         // Re-check after lock — another caller may have already refreshed.
-        let latest = await (0, session_store_1.getSession)(sessionToken);
+        const canonicalLatest = await (0, session_store_1.getSession)(sessionToken);
+        let latest = canonicalLatest;
         if (!latest || !latest.idpRefreshToken) {
             const baLatest = await (0, session_store_1.getBetterAuthSession)(sessionToken);
             if (baLatest?.idpRefreshToken)
@@ -150,11 +201,51 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                     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 = [];
         if (Array.isArray(session.authenticationMethods)) {
@@ -185,6 +276,25 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         // 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 ((0, refresh_in_doubt_1.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_in_doubt_1.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 = {
             refresh_token: sentRefreshToken,
             amr: authMethods,
@@ -196,19 +306,47 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
             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) => {
+            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_in_doubt_1.REFRESH_FETCH_TIMEOUT_MS,
+                cause: cause instanceof Error ? `${cause.name}: ${cause.message}` : undefined,
+            });
+            try {
+                await (0, session_store_1.updateSession)(sessionToken, (0, refresh_in_doubt_1.inDoubtPatch)(sentRefreshToken));
+            }
+            catch (markError) {
+                console.error('[ENSURE-FRESH] could not record the in-doubt marker', { error: (0, log_safe_1.errForLog)(markError) });
+            }
+            return {
+                ok: false,
+                code: refresh_in_doubt_1.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;
         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_in_doubt_1.REFRESH_FETCH_TIMEOUT_MS),
             });
         }
         catch (err) {
+            if (!(0, refresh_in_doubt_1.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,
             };
@@ -217,12 +355,32 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         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) {
             const idpError = responseData?.error || {};
@@ -285,7 +443,9 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                             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,
                         };
                     }
@@ -348,6 +508,8 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                         accessToken: postRefresh.idpAccessToken,
                         accessTokenExpires: postRefresh.idpAccessTokenExpires,
                         refreshed: true,
+                        reason: 'completed_by_concurrent_request',
+                        hasRefreshToken: !!postRefresh.idpRefreshToken,
                         persisted: true,
                     };
                 }
@@ -391,13 +553,13 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                 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 = (0, token_utils_1.extractKidFromToken)(newAccess);
         // *** CARD 320072. CAPTURE THIS RETURN. ***
@@ -407,14 +569,19 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         // 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 (0, session_store_1.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
@@ -422,9 +589,9 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
             // 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,
         });
         /**
          * 320072: DO NOT REPORT SUCCESS FOR A WRITE THAT WAS DISCARDED.
@@ -489,7 +656,7 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         // 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) {

package/dist/lib/geolocation.js

@@ -1,22 +1,4 @@
 "use strict";
-/**
- * =============================================================================
- * GEOLOCATION UTILITY
- * =============================================================================
- *
- * Server-side utility for resolving IP addresses to geographic locations.
- * Uses ip-api.com (free tier: 45 requests/minute).
- *
- * USAGE:
- * ------
- * import { getLocationFromIP, extractClientIP } from '@payez/next-mvp/lib/geolocation';
- *
- * const ip = extractClientIP(request.headers);
- * const location = await getLocationFromIP(ip);
- * console.log(location?.city); // 'Mountain View'
- *
- * =============================================================================
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPrivateIP = isPrivateIP;
 exports.getPublicIP = getPublicIP;
@@ -25,6 +7,7 @@ exports.getLocationFromIP = getLocationFromIP;
 exports.formatLocation = formatLocation;
 exports.getCountryFlag = getCountryFlag;
 exports.clearGeoCache = clearGeoCache;
+const log_safe_1 = require("./log-safe");
 // -----------------------------------------------------------------------------
 // CACHE CONFIGURATION
 // -----------------------------------------------------------------------------
@@ -90,7 +73,7 @@ async function getPublicIP() {
                 // 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;
                 }
             }
@@ -147,7 +130,7 @@ async function getLocationFromIP(ip, resolvePublicIP = true) {
         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);
             }
@@ -176,7 +159,7 @@ async function getLocationFromIP(ip, resolvePublicIP = true) {
         }
         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;
@@ -196,7 +179,7 @@ async function getLocationFromIP(ip, resolvePublicIP = true) {
         return location;
     }
     catch (error) {
-        console.error(`[geolocation] Error looking up ${ip}:`, error);
+        console.error("[geolocation] lookup failed:", (0, log_safe_1.errForLog)(error)); // no IP on a routine line (BAPert 76553 Q1)
         return null;
     }
 }

package/dist/lib/idp-client-config.js

@@ -82,6 +82,7 @@ exports.getEnabledProviders = getEnabledProviders;
 require("server-only");
 const crypto_1 = require("crypto");
 const never_in_response_1 = require("./never-in-response");
+const log_safe_1 = require("./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
@@ -276,7 +277,7 @@ async function getConfigFromRedis() {
         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:', (0, log_safe_1.errForLog)(error));
         return null;
     }
 }
@@ -293,7 +294,7 @@ async function setConfigInRedis(config) {
         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:', (0, log_safe_1.errForLog)(error));
     }
 }
 // ============================================================================
@@ -529,7 +530,7 @@ async function clearConfigRedisCache() {
         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:', (0, log_safe_1.errForLog)(error));
     }
 }
 /**

package/dist/lib/idp-fetch.d.ts

@@ -35,5 +35,16 @@ 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;
+    }>;
 }
 export declare function idpFetchJSON<T = any>(req: NextRequest, targetUrl: string, init?: RequestInit, opts?: IdpFetchOptions): Promise<IdpFetchResult<T>>;

package/dist/lib/idp-fetch.js

@@ -42,6 +42,7 @@ const idp_url_guard_1 = require("./idp-url-guard");
 Object.defineProperty(exports, "assertAbsoluteIdpUrl", { enumerable: true, get: function () { return idp_url_guard_1.assertAbsoluteIdpUrl; } });
 const retry_after_1 = require("./retry-after");
 Object.defineProperty(exports, "parseRetryAfterSeconds", { enumerable: true, get: function () { return retry_after_1.parseRetryAfterSeconds; } });
+const refresh_window_1 = require("./refresh-window");
 function buildHeaders(req, bearer, extra) {
     const headers = {
         Accept: 'application/json',
@@ -118,8 +119,8 @@ async function ensureFreshAccessToken(req) {
     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_1.REFRESH_WINDOW_MS) {
         return { sessionToken, accessToken: session.idpAccessToken, hasRefreshToken };
     }
     // Only attempt refresh when we actually have a refresh token to use.
@@ -179,7 +180,9 @@ async function idpFetchJSON(req, targetUrl, init = {}, opts = {}) {
         attemptedRefresh = true;
         try {
             // Use centralized internal API helper for server-to-server calls
-            const rf = await (0, internal_api_1.internalRefresh)(req.headers.get('cookie') || '', sessionToken);
+            const rf = opts.refreshOnAuthFailure
+                ? await opts.refreshOnAuthFailure(sessionToken)
+                : await (0, internal_api_1.internalRefresh)(req.headers.get('cookie') || '', sessionToken);
             refreshStatus = rf.status;
             if (rf.ok) {
                 const fresh = await (0, session_store_1.getSession)(sessionToken);

package/dist/lib/idp-logout.d.ts

@@ -21,4 +21,14 @@ import type { NextRequest } from 'next/server';
  * refresh token, and a body built earlier would name the old one (NightHawk 76288).
  */
 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 declare class IdpLogoutUnconfirmedError extends Error {
+    readonly grantLive: boolean;
+    readonly code = "IDP_LOGOUT_UNCONFIRMED";
+    constructor(status: number, grantLive: boolean);
+}
 export declare function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOutcome>;

package/dist/lib/idp-logout.js

@@ -1,12 +1,64 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdpLogoutUnconfirmedError = void 0;
 exports.revokeSessionAtIdp = revokeSessionAtIdp;
 const idp_fetch_1 = require("./idp-fetch");
 const session_store_1 = require("./session-store");
 const env_1 = require("../config/env");
+/**
+ * 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.
+ */
+class IdpLogoutUnconfirmedError extends Error {
+    grantLive;
+    code = 'IDP_LOGOUT_UNCONFIRMED';
+    constructor(status, grantLive) {
+        super(`IdP logout answered ${status}`);
+        this.grantLive = grantLive;
+        this.name = 'IdpLogoutUnconfirmedError';
+    }
+}
+exports.IdpLogoutUnconfirmedError = IdpLogoutUnconfirmedError;
 async function revokeSessionAtIdp(req) {
     let resolvedSession;
     const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.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 (0, session_store_1.getSession)(token);
@@ -28,7 +80,27 @@ async function revokeSessionAtIdp(req) {
         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) {
+    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 Promise.resolve().then(() => __importStar(require('./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 };
 }
 /**
  * A refresh 401 is not by itself "the grant is gone" (NightHawk 76295, BAPert 76297): refresh.ts also answers 401 for 'no session', for