@payez/next-mvp 4.8.9 → 4.10.0

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

@@ -0,0 +1,24 @@
+import type { NextRequest } from 'next/server';
+/**
+ * 4.8.10 (BAPert 76255 item 1, 76289): sign-out must end the IdP grant, not only the portal session.
+ *
+ * Core: POST /api/Account/logout, Bearer, body { refresh_token } (DotNetPert 76259). It revokes that refresh token and blacklists the
+ * presented access token. The token is ALWAYS sent: with it omitted Core revokes the caller's NEWEST session, which on a
+ * multi-device user is another device's.
+ *
+ * Outcomes (all three are a SUCCESSFUL sign-out):
+ *   '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 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.
+ *
+ * The session is the one idpFetchJSON resolves from the request cookie. The body is built by `initFor`, AFTER idpFetchJSON's own refresh and again after the refresh that follows a 401: a refresh ROTATES the
+ * refresh token, and a body built earlier would name the old one (NightHawk 76288).
+ */
+export type IdpLogoutOutcome = 'revoked' | 'nothing-to-revoke' | 'grant-already-dead';
+export declare function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOutcome>;

package/dist/lib/idp-logout.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revokeSessionAtIdp = revokeSessionAtIdp;
+const idp_fetch_1 = require("./idp-fetch");
+const session_store_1 = require("./session-store");
+const env_1 = require("../config/env");
+async function revokeSessionAtIdp(req) {
+    let resolvedSession;
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/logout`, {}, {
+        initFor: async (token) => {
+            resolvedSession = token;
+            let session = await (0, session_store_1.getSession)(token);
+            if (!session?.idpRefreshToken)
+                session = (await (0, session_store_1.getBetterAuthSession)(token)) ?? session;
+            const refreshToken = session?.idpRefreshToken;
+            if (!refreshToken)
+                return null;
+            return {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refresh_token: refreshToken }),
+            };
+        },
+    });
+    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}`);
+}
+/**
+ * A refresh 401 is not by itself "the grant is gone" (NightHawk 76295, BAPert 76297): refresh.ts also answers 401 for 'no session', for
+ * the x-session-token rejection and for NO_REFRESH_TOKEN, none of which says anything about the IdP's token. Only its IdP-401 branch
+ * DISCARDS the stored refresh token and WRITES THE MARKER refreshTokenClearedReason 'IDP_DISCARD_TOKEN:<code>'. The marker is the only
+ * proof: an EMPTY token is not (NO_REFRESH_TOKEN has an empty store, and so does a dropped persist with the grant still live at the
+ * IdP). So the grant counts as dead only when the session row exists AND carries that marker. Anything else is UNKNOWN.
+ */
+async function grantWasDiscarded(sessionToken) {
+    let session = await (0, session_store_1.getSession)(sessionToken);
+    if (!session)
+        session = await (0, session_store_1.getBetterAuthSession)(sessionToken);
+    if (!session)
+        return false;
+    return String(session.refreshTokenClearedReason ?? '').startsWith('IDP_DISCARD_TOKEN');
+}

package/dist/lib/refresh-rotation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 4.9.0 (BAPert 76359): ONE predicate for "a concurrent refresh already rotated the refresh token, and the row it left is usable", shared by
+ * all four places that decide it (api-handlers/auth/refresh.ts and lib/ensure-fresh-access-token.ts, each for the HTTP-401 branch and the
+ * 200 success:false branch). Before, two said "usable" meant PRESENT (an access token and an expiry exist) and two said UNEXPIRED, so a rotated
+ * row whose access token had already expired was answered as a successful refresh by some branches and not by others.
+ *
+ * Usable = an access token exists AND its recorded expiry is in the future. A row that is rotated but NOT usable is answered with the
+ * retryable 502, its (rotated) refresh token KEPT and NO discard marker, in every branch. The CAS that decides "rotated" (a different
+ * stored refresh token than the one we sent) is unchanged: a different token is never discarded.
+ *
+ * A leaf module: no imports.
+ */
+export declare function rotatedRowIsUsable<T extends {
+    idpAccessToken?: string | null;
+    idpAccessTokenExpires?: number | null;
+}>(session: T | null | undefined, now?: number): session is T & {
+    idpAccessToken: string;
+    idpAccessTokenExpires: number;
+};

package/dist/lib/refresh-rotation.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rotatedRowIsUsable = rotatedRowIsUsable;
+/**
+ * 4.9.0 (BAPert 76359): ONE predicate for "a concurrent refresh already rotated the refresh token, and the row it left is usable", shared by
+ * all four places that decide it (api-handlers/auth/refresh.ts and lib/ensure-fresh-access-token.ts, each for the HTTP-401 branch and the
+ * 200 success:false branch). Before, two said "usable" meant PRESENT (an access token and an expiry exist) and two said UNEXPIRED, so a rotated
+ * row whose access token had already expired was answered as a successful refresh by some branches and not by others.
+ *
+ * Usable = an access token exists AND its recorded expiry is in the future. A row that is rotated but NOT usable is answered with the
+ * retryable 502, its (rotated) refresh token KEPT and NO discard marker, in every branch. The CAS that decides "rotated" (a different
+ * stored refresh token than the one we sent) is unchanged: a different token is never discarded.
+ *
+ * A leaf module: no imports.
+ */
+function rotatedRowIsUsable(session, now = Date.now()) {
+    return !!(session && session.idpAccessToken && session.idpAccessTokenExpires && session.idpAccessTokenExpires > now);
+}

package/dist/lib/session-store.d.ts

@@ -93,11 +93,6 @@ export declare function deleteSession(sessionToken: string): Promise<void>;
  * them differently, pass appSlug explicitly.
  */
 export declare function deleteSessionEverywhere(sessionToken: string, appSlug?: string): Promise<void>;
-/**
- * Sets a session directly (for testing or migrations).
- * @param sessionToken The session token.
- * @param data The session data.
- */
 export declare function setSession(sessionToken: string, data: SessionData): Promise<void>;
 /**
  * Updates tokens within an existing session.

package/dist/lib/session-store.js

@@ -271,7 +271,24 @@ async function deleteSessionEverywhere(sessionToken, appSlug) {
  * @param sessionToken The session token.
  * @param data The session data.
  */
+/**
+ * 4.9.0 (BAPert 76308 item 2): A LEFTOVER DISCARD MARKER MUST NEVER OUTLIVE A TOKEN. A discard (`refresh.ts`, `ensure-fresh-access-token.ts`)
+ * writes `idpRefreshToken: ''` TOGETHER WITH `refreshTokenClearedReason: 'IDP_DISCARD_TOKEN:<code>'`; logout's dead-grant check reads that marker
+ * as proof the IdP's grant is gone. If a later write stores a NEW refresh token on the same row (a successful refresh, a re-sign-in into the
+ * same row) and the marker stays, a later own-auth 401 would read as "grant already dead" while the grant is live. So any write that leaves a
+ * non-empty refresh token on the row drops the marker, in the same write. No code path was found that gives a discarded row a new token
+ * today; this is the defence BAPert ruled to keep anyway.
+ */
+function dropStaleDiscardMarker(session) {
+    const s = session;
+    if (typeof s.idpRefreshToken === 'string' && s.idpRefreshToken.length > 0 && (s.refreshTokenClearedReason !== undefined || s.refreshTokenClearedAt !== undefined)) {
+        const { refreshTokenClearedReason: _reason, refreshTokenClearedAt: _at, ...rest } = s;
+        return rest;
+    }
+    return session;
+}
 async function setSession(sessionToken, data) {
+    data = dropStaleDiscardMarker(data);
     const key = getSessionKey(sessionToken);
     const versionKey = getSessionVersionKey(sessionToken);
     await redis_1.default.multi()
@@ -405,7 +422,7 @@ async function updateSession(sessionToken, updates) {
         });
     }
     // Merge current session with updates
-    const updatedSession = { ...currentSession, ...updates };
+    const updatedSession = dropStaleDiscardMarker({ ...currentSession, ...updates });
     // Write the entire updated session back to Redis with version increment
     await redis_1.default.multi()
         .setex(key, exports.SESSION_TTL, JSON.stringify(updatedSession))

package/dist/routes/auth/logout.d.ts

@@ -14,14 +14,28 @@
  * @since auth-ready-v2
  */
 import { NextRequest, NextResponse } from 'next/server';
-/** 4.8.9: answered (status 500) when the server-side session delete failed. The browser's cookies are cleared either way. */
+/**
+ * 4.8.9: answered (status 500) when a sign-out did not finish. 4.8.10 (BAPert 76297): TWO sentences, one per cause, each true for its
+ * cause, neither promising a retry (the local session is gone, so there is nothing to retry from). The browser's cookies and the local
+ * session are cleared either way.
+ *   SESSION_NOT_ENDED_IDP_MESSAGE    the IdP outcome is UNKNOWN (revoke refused or unreachable, and no IdP discard marker proves the grant dead)
+ *   SESSION_NOT_ENDED_LOCAL_MESSAGE  the local session-store DELETE failed (the server record is still live)
+ * Both causes at once: the LOCAL sentence, because a live server record is the worse and more actionable fact.
+ */
 export declare const SESSION_NOT_ENDED_CODE = "SESSION_NOT_ENDED";
-export declare const SESSION_NOT_ENDED_MESSAGE = "You were signed out on this device, but we could not end your session on the server. Try signing out again.";
+/**
+ * The machine-readable cause on the 500 body (Nextpert-Scout 76300): the portal never reads response text, so it picks its notice from
+ * this closed set. `code` stays SESSION_NOT_ENDED for 4.8.9 callers; `cause` is additive. Both causes at once: local_delete_failed.
+ * A dead-grant or ordinary success carries neither.
+ */
+export type SessionNotEndedCause = 'idp_unconfirmed' | 'local_delete_failed';
+export declare const SESSION_NOT_ENDED_IDP_MESSAGE = "We could not confirm the sign-out with the identity service.";
+export declare const SESSION_NOT_ENDED_LOCAL_MESSAGE = "We could not finish signing you out on this device.";
 /**
  * POST /api/auth/logout - Sign out and clean up session
  *
  * Performs complete logout:
- * 1. Revokes tokens at IDP (if refresh token available)
+ * 1. Revokes the refresh token at the IDP (POST /api/Account/logout) when the session has one; a failed revoke answers SESSION_NOT_ENDED
  * 2. Deletes session from store
  * 3. Clears session cookies
  */

package/dist/routes/auth/logout.js

@@ -15,22 +15,31 @@
  * @since auth-ready-v2
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_NOT_ENDED_MESSAGE = exports.SESSION_NOT_ENDED_CODE = void 0;
+exports.SESSION_NOT_ENDED_LOCAL_MESSAGE = exports.SESSION_NOT_ENDED_IDP_MESSAGE = exports.SESSION_NOT_ENDED_CODE = void 0;
 exports.POST = POST;
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const session_store_1 = require("../../lib/session-store");
+const idp_logout_1 = require("../../lib/idp-logout");
 const app_slug_1 = require("../../lib/app-slug");
 const site_logger_1 = require("../../lib/site-logger");
 const safe_error_response_1 = require("../../lib/safe-error-response");
-/** 4.8.9: answered (status 500) when the server-side session delete failed. The browser's cookies are cleared either way. */
+/**
+ * 4.8.9: answered (status 500) when a sign-out did not finish. 4.8.10 (BAPert 76297): TWO sentences, one per cause, each true for its
+ * cause, neither promising a retry (the local session is gone, so there is nothing to retry from). The browser's cookies and the local
+ * session are cleared either way.
+ *   SESSION_NOT_ENDED_IDP_MESSAGE    the IdP outcome is UNKNOWN (revoke refused or unreachable, and no IdP discard marker proves the grant dead)
+ *   SESSION_NOT_ENDED_LOCAL_MESSAGE  the local session-store DELETE failed (the server record is still live)
+ * Both causes at once: the LOCAL sentence, because a live server record is the worse and more actionable fact.
+ */
 exports.SESSION_NOT_ENDED_CODE = 'SESSION_NOT_ENDED';
-exports.SESSION_NOT_ENDED_MESSAGE = 'You were signed out on this device, but we could not end your session on the server. Try signing out again.';
+exports.SESSION_NOT_ENDED_IDP_MESSAGE = 'We could not confirm the sign-out with the identity service.';
+exports.SESSION_NOT_ENDED_LOCAL_MESSAGE = 'We could not finish signing you out on this device.';
 /**
  * POST /api/auth/logout - Sign out and clean up session
  *
  * Performs complete logout:
- * 1. Revokes tokens at IDP (if refresh token available)
+ * 1. Revokes the refresh token at the IDP (POST /api/Account/logout) when the session has one; a failed revoke answers SESSION_NOT_ENDED
  * 2. Deletes session from store
  * 3. Clears session cookies
  */
@@ -47,7 +56,19 @@ async function POST(req) {
         const sessionId = session.session?.token;
         // 4.8.9: a sign-out that did not end the session must not say it did. The delete below can fail (a faulting store); the
         // cookies are still cleared, but the answer is then a typed failure instead of success:true.
-        let serverDeleteFailed = false;
+        let localDeleteFailed = false;
+        let idpRevokeFailed = false;
+        // 4.8.10: end the IdP grant FIRST, while the session still holds its tokens. A failed revoke is the same typed failure as a failed
+        // delete: the IdP refresh token is still valid, so the sign-out did not end the session. The local delete below still runs.
+        if (sessionId) {
+            try {
+                await (0, idp_logout_1.revokeSessionAtIdp)(req);
+            }
+            catch (error) {
+                idpRevokeFailed = true;
+                console.error('[LOGOUT_ROUTE] IdP revoke failed - the IdP refresh token is STILL LIVE:', error);
+            }
+        }
         // Delete session from EVERY store — canonical + BA secondary (181922).
         // Canonical-only deletion let the ba: record resurrect the session.
         if (sessionId) {
@@ -56,7 +77,7 @@ async function POST(req) {
                 console.info('[LOGOUT_ROUTE] Session deleted from store');
             }
             catch (error) {
-                serverDeleteFailed = true;
+                localDeleteFailed = true;
                 console.error('[LOGOUT_ROUTE] Failed to delete session - the server session is STILL LIVE:', error);
             }
         }
@@ -73,8 +94,10 @@ async function POST(req) {
             });
         }
         // Build response that clears session cookies
-        const response = serverDeleteFailed
-            ? server_1.NextResponse.json({ success: false, code: exports.SESSION_NOT_ENDED_CODE, message: exports.SESSION_NOT_ENDED_MESSAGE }, { status: 500 })
+        const response = (localDeleteFailed || idpRevokeFailed)
+            ? server_1.NextResponse.json(localDeleteFailed
+                ? { success: false, code: exports.SESSION_NOT_ENDED_CODE, cause: 'local_delete_failed', message: exports.SESSION_NOT_ENDED_LOCAL_MESSAGE }
+                : { success: false, code: exports.SESSION_NOT_ENDED_CODE, cause: 'idp_unconfirmed', message: exports.SESSION_NOT_ENDED_IDP_MESSAGE }, { status: 500 })
             : server_1.NextResponse.json({
                 success: true,
                 message: 'Logged out successfully'

package/dist/routes/auth/refresh.d.ts

@@ -23,6 +23,7 @@ export declare function POST(req: NextRequest): Promise<import("next/server").Ne
     discardToken: boolean;
     retryable: boolean;
     resolution: any;
+    status: number;
 }> | import("next/server").NextResponse<{
     refreshed: boolean;
     accessTokenExpires: number;

package/dist/server/auth.js

@@ -392,7 +392,7 @@ async function getFreshIdpToken(request, config) {
         refreshEndpoint: config.refreshEndpoint,
     }, {
         safetyWindowMs: config.safetyWindowMs,
-        requestId: request?.headers?.get('x-request-id') ?? undefined,
+        // 4.8.10 (BAPert 76298 (b)): the request's x-request-id is NOT passed. It used to become the refresh lock's identity.
     });
     if (!result.ok) {
         if (result.code === 'NO_SESSION')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.8.9",
+  "version": "4.10.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,7 +8,8 @@
     "dist",
     "scripts",
     "src",
-    "POST-INSTALL.md"
+    "POST-INSTALL.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true});fs.rmSync('tsconfig.tsbuildinfo',{force:true})\" && npx tsc --project tsconfig.json",
@@ -669,16 +670,6 @@
       "require": "./dist/stores/authStore.js",
       "default": "./stores/authStore.js"
     },
-    "./api": {
-      "types": "./dist/api/index.d.ts",
-      "require": "./dist/api/index.js",
-      "default": "./dist/api/index.js"
-    },
-    "./api/auth-handler": {
-      "types": "./dist/api/auth-handler.d.ts",
-      "require": "./dist/api/auth-handler.js",
-      "default": "./dist/api/auth-handler.js"
-    },
     "./routes/auth/refresh": {
       "types": "./dist/routes/auth/refresh.d.ts",
       "require": "./dist/routes/auth/refresh.js",

package/src/api-handlers/auth/refresh.ts

@@ -41,6 +41,7 @@ import { getSession, updateSession, acquireRefreshLock, releaseRefreshLock, chec
 import { computeTokenExpiries } from '../../lib/token-expiry';
 import { extractKidFromToken } from '../../auth/utils/token-utils';
 import { tokenLogId } from '../../lib/token-log-id';
+import { rotatedRowIsUsable } from '../../lib/refresh-rotation';
 
 interface RefreshConfig {
   idpBaseUrl: string;
@@ -333,7 +334,43 @@ export function createRefreshHandler(config: RefreshConfig) {
       // Note: Token is NOT cleared preemptively - it will be replaced on success.
       // The lock mechanism prevents concurrent refresh attempts within the same session.
       // If IDP call fails, user can retry with the same token.
-      const originalRefreshToken = currentSession.idpRefreshToken as string;
+      // 4.9.0 (BAPert 76298 (b2), 76330): the token we SEND is the one read AFTER the lock was taken (`latestAfterLock`), and it is the ONLY
+      // source: there is NO fallback to `currentSession`, which was read BEFORE the lock. Between those reads another request can rotate the
+      // refresh token (sending the pre-lock value would send a SPENT token) or DISCARD it (the IdP answered 401 for it; re-sending it is a
+      // reuse). The IdP treats reuse as compromise and revokes descendants across devices. So:
+      //   - the post-lock read has NO ROW: the session vanished while we waited; it is not ours to refresh -> the 'No session' 401, no IdP call
+      //   - the row has NO refresh token: -> the same terminal NO_REFRESH_TOKEN as the pre-lock guard, no IdP call; the row is left exactly as
+      //     it is (a discard marker stays on it)
+      // (A row whose access token is still fresh was answered `already_fresh` above and never reaches here.)
+      if (!latestAfterLock) {
+        console.warn('[AUTH_REFRESH] Session vanished while waiting for the refresh lock; not refreshing', { userId });
+        if (weAcquiredLock) {
+          await releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
+          weAcquiredLock = false;
+        }
+        return NextResponse.json({
+          error: 'No session available for refresh',
+          code: 'UNAUTHORIZED'
+        }, { status: 401 });
+      }
+      if (!latestAfterLock.idpRefreshToken) {
+        console.warn('[AUTH_REFRESH] No refresh token after the lock was taken; not calling the IdP', { userId });
+        if (weAcquiredLock) {
+          await releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
+          weAcquiredLock = false;
+        }
+        return NextResponse.json({
+          error: 'No refresh token available',
+          code: 'NO_REFRESH_TOKEN',
+          terminal: true,
+          resolution: 'User must re-authenticate'
+        }, { status: 401 });
+      }
+      const originalRefreshToken = latestAfterLock.idpRefreshToken as string;
+      // The base of everything WRITTEN BACK after a successful exchange is the same post-lock read (BAPert 76318 item 4): writing
+      // `...currentSession` over a rotated row would put a SPENT token back. With no new refresh token from the IdP the stored token is the
+      // one that was SENT (`originalRefreshToken`).
+      const baseSession = latestAfterLock;
 
       try {
         // Extract 2FA claims from current session
@@ -565,7 +602,7 @@ export function createRefreshHandler(config: RefreshConfig) {
               // (race-fix follow-up #1).
               discardToken = false;
               console.warn('[AUTH_REFRESH] Discard suppressed: refresh token already rotated by a concurrent refresh — returning the fresh token (race-safe).');
-              if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+              if (rotatedRowIsUsable(postRefresh)) {
                 return NextResponse.json({
                   refreshed: true,
                   reason: 'completed_by_concurrent_request',
@@ -573,6 +610,16 @@ export function createRefreshHandler(config: RefreshConfig) {
                   hasRefreshToken: !!postRefresh.idpRefreshToken,
                 });
               }
+              // 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 NextResponse.json({
+                error: errorMessage,
+                code: errorCode,
+                discardToken: false,
+                retryable: true,
+                resolution,
+                status: 502
+              }, { status: 502 });
             }
           }
 
@@ -631,30 +678,59 @@ export function createRefreshHandler(config: RefreshConfig) {
             errorKeys: Object.keys(idpError),
           });
 
+          // 4.9.0 (BAPert 76298 (c)): ONE IdP answer, ONE meaning, in both refresh implementations. This branch used to answer the upstream
+          // status, i.e. HTTP 200, with an error body, so `internalRefresh` reported `ok` and idpFetchJSON's 401-retry trusted a refresh that
+          // had failed; and it wrote a DIFFERENT marker (IDP_SUCCESS_FALSE_DISCARD) than the IdP-401 branch, which the logout dead-grant check
+          // does not recognise. Now:
+          //   success:false + discard_token  -> the stored token is discarded (same CAS as the 401 branch) with the IDP_DISCARD_TOKEN marker, and the
+          //                                     answer is 401 (never 200 with an error body)
+          //   success:false, no discard_token -> 502 retryable, the token is KEPT
           if (discardToken) {
-            console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP success:false with discard_token', {
-              reason: 'IDP_SUCCESS_FALSE_DISCARD',
-              errorCode,
-              userId,
-              sessionToken: tokenLogId(sessionToken),
-              hadRefreshToken: !!currentSession.idpRefreshToken,
-              stack: new Error().stack
-            });
-            await updateSession(sessionToken, {
-              idpRefreshToken: '',
-              idpRefreshTokenExpires: undefined,
-              refreshTokenClearedAt: Date.now(),
-              refreshTokenClearedReason: `IDP_SUCCESS_FALSE_DISCARD:${errorCode}`
-            });
+            const postRefresh = await getSession(sessionToken);
+            const tokenUnchanged = !!originalRefreshToken && postRefresh?.idpRefreshToken === originalRefreshToken;
+            if (tokenUnchanged) {
+              console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP success:false with discard_token', {
+                reason: 'IDP_DISCARD_TOKEN',
+                errorCode,
+                userId,
+                sessionToken: tokenLogId(sessionToken),
+                hadRefreshToken: !!currentSession.idpRefreshToken,
+                stack: new Error().stack
+              });
+              await updateSession(sessionToken, {
+                idpRefreshToken: '',
+                idpRefreshTokenExpires: undefined,
+                refreshTokenClearedAt: Date.now(),
+                refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
+              });
+              return NextResponse.json({
+                error: idpError.message || 'Token refresh failed',
+                code: errorCode,
+                discardToken: true,
+                retryable: false,
+                resolution: idpError.resolution || null,
+                status: 401
+              }, { status: 401 });
+            }
+            // A concurrent refresh already rotated the token: ours is stale. Return the fresh tokens if there are any (as the 401 branch does).
+            if (rotatedRowIsUsable(postRefresh)) {
+              return NextResponse.json({
+                refreshed: true,
+                reason: 'completed_by_concurrent_request',
+                accessTokenExpires: postRefresh.idpAccessTokenExpires,
+                hasRefreshToken: !!postRefresh.idpRefreshToken,
+              });
+            }
           }
 
           return NextResponse.json({
             error: idpError.message || 'Token refresh failed',
             code: errorCode,
-            discardToken,
-            retryable,
-            resolution: idpError.resolution || null
-          }, { status: refreshResponse.status || 400 });
+            discardToken: false,
+            retryable: true,
+            resolution: idpError.resolution || null,
+            status: 502
+          }, { status: 502 });
         }
 
         // Extract tokens from response
@@ -701,24 +777,24 @@ export function createRefreshHandler(config: RefreshConfig) {
               : decodedAccessToken.amr;
           } catch (e) {
             console.warn('[AUTH_REFRESH] Failed to parse AMR claims', { amr: decodedAccessToken.amr });
-            amrClaims = currentSession.authenticationMethods || [];
+            amrClaims = baseSession.authenticationMethods || [];
           }
         } else {
-          amrClaims = currentSession.authenticationMethods || [];
+          amrClaims = baseSession.authenticationMethods || [];
         }
-        const acrLevel = String(decodedAccessToken.acr || currentSession.authenticationLevel || '1');
+        const acrLevel = String(decodedAccessToken.acr || baseSession.authenticationLevel || '1');
 
         // Extract MFA timing claims
-        const mfaTime = decodedAccessToken.mfa_time ? parseInt(decodedAccessToken.mfa_time) * 1000 : currentSession.mfaCompletedAt;
-        const mfaExpires = decodedAccessToken.mfa_expires ? parseInt(decodedAccessToken.mfa_expires) * 1000 : currentSession.mfaExpiresAt;
-        const mfaValidityHours = decodedAccessToken.mfa_validity_hours ? parseInt(decodedAccessToken.mfa_validity_hours) : currentSession.mfaValidityHours;
+        const mfaTime = decodedAccessToken.mfa_time ? parseInt(decodedAccessToken.mfa_time) * 1000 : baseSession.mfaCompletedAt;
+        const mfaExpires = decodedAccessToken.mfa_expires ? parseInt(decodedAccessToken.mfa_expires) * 1000 : baseSession.mfaExpiresAt;
+        const mfaValidityHours = decodedAccessToken.mfa_validity_hours ? parseInt(decodedAccessToken.mfa_validity_hours) : baseSession.mfaValidityHours;
 
         // Update session with new tokens
         const hasNewRefresh = typeof refreshToken === 'string' && refreshToken.length > 0;
         const newRefreshTokenExpires = hasNewRefresh ? computedRefreshTokenExpires : undefined;
 
         // CRITICAL: Log if we're about to clear the refresh token due to missing new token
-        if (!hasNewRefresh && currentSession.idpRefreshToken) {
+        if (!hasNewRefresh && baseSession.idpRefreshToken) {
           console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: No new refresh token in IDP response', {
             reason: 'NO_NEW_REFRESH_TOKEN_IN_RESPONSE',
             userId,
@@ -747,14 +823,14 @@ export function createRefreshHandler(config: RefreshConfig) {
         }
 
         const sessionUpdate: any = {
-          ...currentSession,
+          ...baseSession,
           idpAccessToken: accessToken,
           idpAccessTokenExpires: accessTokenExpires,
-          idpRefreshToken: hasNewRefresh ? (refreshToken as string) : currentSession.idpRefreshToken,
-          idpRefreshTokenExpires: hasNewRefresh ? newRefreshTokenExpires : currentSession.idpRefreshTokenExpires,
+          idpRefreshToken: hasNewRefresh ? (refreshToken as string) : originalRefreshToken,
+          idpRefreshTokenExpires: hasNewRefresh ? newRefreshTokenExpires : baseSession.idpRefreshTokenExpires,
           decodedAccessToken: decodedAccessToken,
           // Bearer key ID from JWT header (may change on key rotation)
-          bearerKeyId: newBearerKeyId || currentSession.bearerKeyId,
+          bearerKeyId: newBearerKeyId || baseSession.bearerKeyId,
           authenticationMethods: amrClaims,
           authenticationLevel: acrLevel,
           // 170007 rule 2 (BAPert ruling on 121350): '||' is the wrong operator