@payez/next-mvp 4.9.0 → 4.11.0

package/dist/auth/utils/token-utils.d.ts

@@ -46,7 +46,7 @@ export declare function extractAmrFromToken(decoded: DecodedIdpAccessToken): str
  * 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 declare function tokenNeedsRefresh(expiresAt: number | undefined, bufferMs?: number): boolean;

package/dist/auth/utils/token-utils.js

@@ -20,6 +20,7 @@ exports.msUntilExpiry = msUntilExpiry;
 exports.expClaimToMs = expClaimToMs;
 exports.validateTokenExpiry = validateTokenExpiry;
 const jwt_decode_1 = require("../../lib/jwt-decode");
+const refresh_window_1 = require("../../lib/refresh-window");
 // Re-export header utilities for consumers
 var jwt_decode_2 = require("../../lib/jwt-decode");
 Object.defineProperty(exports, "decodeJwtHeader", { enumerable: true, get: function () { return jwt_decode_2.decodeJwtHeader; } });
@@ -129,10 +130,10 @@ function extractAmrFromToken(decoded) {
  * 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
  */
-function tokenNeedsRefresh(expiresAt, bufferMs = 5 * 60 * 1000) {
+function tokenNeedsRefresh(expiresAt, bufferMs = refresh_window_1.REFRESH_WINDOW_MS) {
     if (!expiresAt) {
         return true; // No expiry info = assume needs refresh
     }

package/dist/lib/api-handler.js

@@ -21,6 +21,7 @@ const nanoid_1 = require("nanoid");
 const session_store_1 = require("./session-store");
 const test_aware_get_token_1 = require("./test-aware-get-token");
 const internal_api_1 = require("./internal-api");
+const refresh_window_1 = require("./refresh-window");
 // ============================================================================
 // API Response Builder (for backward compatibility)
 // ============================================================================
@@ -189,7 +190,7 @@ 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_1.REFRESH_WINDOW_MS;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const expires = sessionData.idpAccessTokenExpires || sessionData.accessTokenExpires || 0;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -305,7 +306,7 @@ class ApiHandler {
         try {
             // Double-check if still needs refresh
             const latest = await (0, session_store_1.getSession)(sessionToken);
-            const thresholdMs = 5 * 60 * 1000;
+            const thresholdMs = refresh_window_1.REFRESH_WINDOW_MS;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const latestAny = latest;
             // Sessions may store the access token under either `accessToken` or `idpAccessToken`,
@@ -348,7 +349,7 @@ class ApiHandler {
                 const session = await (0, session_store_1.getSession)(sessionToken);
                 if (session?.accessToken) {
                     const expires = session.accessTokenExpires || 0;
-                    if ((expires - Date.now()) > (5 * 60 * 1000)) {
+                    if ((expires - Date.now()) > refresh_window_1.REFRESH_WINDOW_MS) {
                         return { success: true };
                     }
                 }

package/dist/lib/ensure-fresh-access-token.d.ts

@@ -4,10 +4,15 @@ export interface EnsureFreshConfig {
     refreshEndpoint?: string;
 }
 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.)
@@ -20,6 +25,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?
      *
@@ -56,4 +69,14 @@ export type EnsureFreshResult = {
     retryable?: boolean;
     resolution?: string;
 };
+/**
+ * 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 declare function checkRefreshEnvelope(body: any, httpOk: boolean): {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
 export declare function ensureFreshAccessToken(sessionToken: string, config: EnsureFreshConfig, options?: EnsureFreshOptions): Promise<EnsureFreshResult>;

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.
@@ -20,7 +21,32 @@ const crypto_1 = require("crypto");
 const session_store_1 = require("./session-store");
 const token_expiry_1 = require("./token-expiry");
 const token_utils_1 = require("../auth/utils/token-utils");
-const DEFAULT_SAFETY_WINDOW_MS = 60_000;
+const refresh_rotation_1 = require("./refresh-rotation");
+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");
+/**
+ * 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('.');
@@ -44,37 +70,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 {
@@ -96,7 +143,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)
@@ -110,8 +158,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,
                             };
                         }
                     }
@@ -133,7 +183,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)
@@ -149,11 +200,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)) {
@@ -184,6 +275,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,
@@ -195,19 +305,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: markError instanceof Error ? markError.message : String(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,
             };
@@ -216,12 +354,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 || {};
@@ -278,16 +436,29 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                     // 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 ((0, refresh_rotation_1.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 {
@@ -302,6 +473,56 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
             };
         }
         // 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 (0, session_store_1.getSession)(sessionToken);
+                const tokenUnchanged = !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
+                if (tokenUnchanged) {
+                    await (0, session_store_1.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 ((0, refresh_rotation_1.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' ||
             responseData.success !== true ||
@@ -331,13 +552,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. ***
@@ -347,14 +568,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
@@ -362,9 +588,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.
@@ -429,7 +655,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/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.

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

@@ -10,8 +10,10 @@ import type { NextRequest } from 'next/server';
  *   '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.
  *

package/dist/lib/refresh-in-doubt.d.ts

@@ -0,0 +1,31 @@
+/** How long a refresh fetch (connect, response and body) may take. 5 s lock wait + this + the persist stays well inside the 60 s lock TTL. */
+export declare const REFRESH_FETCH_TIMEOUT_MS = 10000;
+/** The typed terminal answer for an attempt that would re-send an in-doubt token. */
+export declare const REFRESH_OUTCOME_UNKNOWN_CODE = "REFRESH_OUTCOME_UNKNOWN";
+/** The typed answer for the timed-out call itself. */
+export declare const UPSTREAM_TIMEOUT_CODE = "UPSTREAM_TIMEOUT";
+/** A one-way identity for a refresh token. Not reversible and not a prefix. */
+export declare function refreshTokenIdentity(token: string): string;
+/** The row fields recorded at a timeout. */
+export declare function inDoubtPatch(sentToken: string): {
+    refreshInDoubtTokenHash: string;
+    refreshInDoubtAt: number;
+};
+/** True when the token we are about to send is the one a previous attempt left in doubt. */
+export declare function isRefreshInDoubt(session: {
+    refreshInDoubtTokenHash?: string | null;
+} | null | undefined, tokenToSend: string | null | undefined): boolean;
+/** True for the error `AbortSignal.timeout` produces (a DOMException named TimeoutError); AbortError is treated the same. */
+export declare function isTimeoutError(err: unknown): boolean;
+/**
+ * The ONLY transport error codes that PROVE the request never left this process (BAPert 76433 item 4): the connection was refused, or the
+ * name did not resolve. Anything else (ECONNRESET, UND_ERR_SOCKET, a timeout, an error with no code) may have happened AFTER the request was
+ * written, so the IdP may have consumed the token: outcome unknown. The cost is lopsided on purpose: a false in-doubt costs one re-login, a
+ * missed one costs a user-wide revocation. Do NOT add a code here without proof it can only occur before the request is sent.
+ */
+export declare const REQUEST_NEVER_LEFT_CODES: ReadonlySet<string>;
+/**
+ * True only when the error carries at least one cause code and EVERY code it carries is in the never-left allowlist. An error with no code
+ * is NOT proof, so it is in-doubt.
+ */
+export declare function requestNeverLeft(err: unknown): boolean;