@payez/next-mvp 4.8.9 → 4.9.0

package/README.md

@@ -548,7 +548,7 @@ import { POST as logout } from '@payez/next-mvp/routes/auth/logout';
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `CLIENT_ID` | ✅ Yes | Your PayEz IDP client ID (string slug, e.g., `payez_idp_admin_web`) |
-| `IDP_URL` | ✅ Yes | PayEz IDP base URL (e.g., `https://idp.payez.net` or `http://localhost:32785`). **No default in code.** Call `requireIdpUrl()` from `@payez/next-mvp/lib/require-idp-url` in your `instrumentation.ts` (4.8.8) and the server refuses to start, with one fixed sentence, when it is missing or not a full http(s) address. The quickstart generator writes the production address into `.env.local` and adds that file for you. |
+| `IDP_URL` | ✅ Yes | PayEz IDP base URL (e.g., `https://idp.payez.net` or `http://localhost:32785`). **No default in code.** Call `requireIdpUrl()` from `@payez/next-mvp/lib/require-idp-url` in your `instrumentation.ts` (4.8.8) and the server refuses to start, with one fixed sentence, when it is missing or not a full http(s) address. `npx @payez/create-next-app` writes the production address (`https://idp.payez.net`) into `.env.local` when it provisions your dev key; an `IDP_URL` in the environment when you run it overrides that address. If provisioning does not complete, it writes `IDP_URL=` EMPTY, and the app then refuses to start with the sentence above until you set it. |
 | `AUTH_TRUST_HOST` | ✅ Yes | Must be `true` - NextAuth derives OAuth URLs from request headers |
 | `NEXTAUTH_SECRET` | 🔄 Broker | **Do NOT set** - fetched automatically from IDP at startup (see below) |
 | `CLIENT_SECRET` | ⚠️ Legacy | Not needed with broker mode - IDP handles signing |

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

@@ -8,7 +8,10 @@ export interface EnsureFreshOptions {
     safetyWindowMs?: number;
     /** Max wait while another caller holds the refresh lock. Default 5000. */
     lockWaitMs?: number;
-    /** Optional caller request id for lock attribution. */
+    /**
+     * 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.)
+     */
     requestId?: string;
 }
 export type EnsureFreshResult = {

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

@@ -16,6 +16,7 @@ exports.ensureFreshAccessToken = ensureFreshAccessToken;
  * Single-use refresh-token semantics are preserved via Redis-backed
  * single-flight locking (see `acquireRefreshLock`).
  */
+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");
@@ -37,7 +38,13 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
     const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
     const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
     const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
-    const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
+    // LOCK IDENTITY IS MINTED SERVER-SIDE (BAPert 76298 (b)), exactly as api-handlers/auth/refresh.ts does. It used to be
+    // `options.requestId ?? ensure_fresh_${Date.now()}`, and server/auth.ts passed the request's x-request-id header, so a caller chose the
+    // value that the branch below compared against the lock holder's id. A lock that protects against refresh-token REUSE (the IdP treats
+    // 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);
     if (!session || !session.idpRefreshToken) {
         const baSession = await (0, session_store_1.getBetterAuthSession)(sessionToken);
@@ -83,8 +90,7 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
     let weHoldLock = false;
     let releaseVersion;
     if (!lock.acquired) {
-        const existing = await (0, session_store_1.checkRefreshLock)(sessionToken);
-        if (!existing || existing.acquiredBy !== requestId) {
+        {
             const startWait = Date.now();
             while (Date.now() - startWait < lockWaitMs) {
                 await new Promise(r => setTimeout(r, 200));
@@ -263,6 +269,7 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                         console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
                             code,
                             requestId,
+                            traceId,
                         });
                     }
                 }
@@ -403,6 +410,7 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         if (!persisted) {
             console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
                 requestId,
+                traceId,
                 refreshTokenRotated: hasNewRefresh,
                 persisted: false,
             });

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

@@ -19,5 +19,21 @@ export interface IdpFetchResult<T = any> {
      * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
      */
     retryAfterSeconds?: number;
+    /** 4.8.10: set when `opts.initFor` returned null for the FIRST call: no request was made. */
+    skipped?: true;
+    /**
+     * 4.8.10: how the refresh that followed a 401/403 ended: the status the internal refresh answered, or null when it threw. Absent
+     * when no refresh was attempted. refresh.ts treats a 401 as "definitively invalid - always discard", i.e. the grant is gone.
+     */
+    refreshStatus?: number | null;
+}
+export interface IdpFetchOptions {
+    /**
+     * 4.8.10: a call whose BODY names a token that a refresh ROTATES (logout names the refresh token) cannot be built before the
+     * refresh. Called with the session token AFTER the pre-call refresh, for the first call, and again AFTER the refresh that follows a
+     * 401/403, for the retry. It returns the init to send, or null for "nothing to send": null on the first call returns
+     * `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>;
 }
-export declare function idpFetchJSON<T = any>(req: NextRequest, targetUrl: string, init?: RequestInit): Promise<IdpFetchResult<T>>;
+export declare function idpFetchJSON<T = any>(req: NextRequest, targetUrl: string, init?: RequestInit, opts?: IdpFetchOptions): Promise<IdpFetchResult<T>>;

package/dist/lib/idp-fetch.js

@@ -134,11 +134,19 @@ async function ensureFreshAccessToken(req) {
     }
     return { sessionToken, accessToken: session.idpAccessToken, hasRefreshToken };
 }
-async function idpFetchJSON(req, targetUrl, init = {}) {
+async function idpFetchJSON(req, targetUrl, init = {}, opts = {}) {
     let attemptedRefresh = false;
+    let refreshStatus;
     let { accessToken, sessionToken, hasRefreshToken } = await ensureFreshAccessToken(req);
     (0, idp_url_guard_1.assertAbsoluteIdpUrl)(targetUrl);
-    const makeCall = async (bearer) => {
+    let firstInit = init;
+    if (opts.initFor) {
+        const built = sessionToken ? await opts.initFor(sessionToken) : null;
+        if (!built)
+            return { ok: false, status: 0, json: null, attemptedRefresh: false, skipped: true };
+        firstInit = built;
+    }
+    const makeCall = async (bearer, callInit = firstInit) => {
         // NOTE (307290): this fetch is UNGUARDED, and so is the first call to it at
         // the "First attempt" below. Only the JSON PARSE (try/catch immediately
         // after) and the RETRY are guarded. A transport-level failure - DNS, refused,
@@ -151,8 +159,8 @@ async function idpFetchJSON(req, targetUrl, init = {}) {
         // carve-out. Correcting b4b8ffae's message, which wrongly said every risky
         // branch here is try/caught.
         const res = await fetch(targetUrl, {
-            ...init,
-            headers: buildHeaders(req, bearer, init.headers),
+            ...callInit,
+            headers: buildHeaders(req, bearer, callInit.headers),
         });
         let json = null;
         try {
@@ -172,13 +180,19 @@ async function idpFetchJSON(req, targetUrl, init = {}) {
         try {
             // Use centralized internal API helper for server-to-server calls
             const rf = 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);
-                ({ res, json } = await makeCall(fresh?.idpAccessToken));
+                const retryInit = opts.initFor ? await opts.initFor(sessionToken) : firstInit;
+                if (retryInit)
+                    ({ res, json } = await makeCall(fresh?.idpAccessToken, retryInit));
             }
         }
-        catch { }
+        catch {
+            if (refreshStatus === undefined)
+                refreshStatus = null;
+        }
     }
     const retryAfterSeconds = (0, retry_after_1.parseRetryAfterSeconds)(res.headers?.get?.('Retry-After'));
-    return { ok: res.ok, status: res.status, json: json, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
+    return { ok: res.ok, status: res.status, json: json, attemptedRefresh, ...(refreshStatus !== undefined ? { refreshStatus } : {}), ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

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

@@ -0,0 +1,22 @@
+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 (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).
+ * 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/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/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.9.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -13,6 +13,7 @@
  * Single-use refresh-token semantics are preserved via Redis-backed
  * single-flight locking (see `acquireRefreshLock`).
  */
+import { randomUUID } from 'crypto';
 import {
   getSession,
   getBetterAuthSession,
@@ -35,7 +36,10 @@ export interface EnsureFreshOptions {
   safetyWindowMs?: number;
   /** Max wait while another caller holds the refresh lock. Default 5000. */
   lockWaitMs?: number;
-  /** Optional caller request id for lock attribution. */
+  /**
+   * 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.)
+   */
   requestId?: string;
 }
 
@@ -106,7 +110,13 @@ export async function ensureFreshAccessToken(
   const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
   const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
   const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
-  const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
+  // LOCK IDENTITY IS MINTED SERVER-SIDE (BAPert 76298 (b)), exactly as api-handlers/auth/refresh.ts does. It used to be
+  // `options.requestId ?? ensure_fresh_${Date.now()}`, and server/auth.ts passed the request's x-request-id header, so a caller chose the
+  // value that the branch below compared against the lock holder's id. A lock that protects against refresh-token REUSE (the IdP treats
+  // reuse as compromise and revokes descendants across devices) must not be bypassable by an id the caller picks. Date.now() also
+  // collided for two calls in the same millisecond. The caller's id is kept as `traceId`, for logs only.
+  const requestId = `ensure_fresh_${randomUUID()}`;
+  const traceId = options.requestId;
 
   let session = await getSession(sessionToken);
   if (!session || !session.idpRefreshToken) {
@@ -159,8 +169,7 @@ export async function ensureFreshAccessToken(
   let releaseVersion: number | undefined;
 
   if (!lock.acquired) {
-    const existing = await checkRefreshLock(sessionToken);
-    if (!existing || existing.acquiredBy !== requestId) {
+    {
       const startWait = Date.now();
       while (Date.now() - startWait < lockWaitMs) {
         await new Promise(r => setTimeout(r, 200));
@@ -336,6 +345,7 @@ export async function ensureFreshAccessToken(
             console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
               code,
               requestId,
+              traceId,
             });
           }
         } else {
@@ -480,6 +490,7 @@ export async function ensureFreshAccessToken(
     if (!persisted) {
       console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
         requestId,
+        traceId,
         refreshTokenRotated: hasNewRefresh,
         persisted: false,
       });

package/src/lib/idp-fetch.ts

@@ -28,6 +28,23 @@ export interface IdpFetchResult<T = any> {
    * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
    */
   retryAfterSeconds?: number;
+  /** 4.8.10: set when `opts.initFor` returned null for the FIRST call: no request was made. */
+  skipped?: true;
+  /**
+   * 4.8.10: how the refresh that followed a 401/403 ended: the status the internal refresh answered, or null when it threw. Absent
+   * when no refresh was attempted. refresh.ts treats a 401 as "definitively invalid - always discard", i.e. the grant is gone.
+   */
+  refreshStatus?: number | null;
+}
+
+export interface IdpFetchOptions {
+  /**
+   * 4.8.10: a call whose BODY names a token that a refresh ROTATES (logout names the refresh token) cannot be built before the
+   * refresh. Called with the session token AFTER the pre-call refresh, for the first call, and again AFTER the refresh that follows a
+   * 401/403, for the retry. It returns the init to send, or null for "nothing to send": null on the first call returns
+   * `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>;
 }
 
 function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
@@ -121,14 +138,23 @@ async function ensureFreshAccessToken(req: NextRequest): Promise<{ sessionToken?
 export async function idpFetchJSON<T = any>(
   req: NextRequest,
   targetUrl: string,
-  init: RequestInit = {}
+  init: RequestInit = {},
+  opts: IdpFetchOptions = {}
 ): Promise<IdpFetchResult<T>> {
   let attemptedRefresh = false;
+  let refreshStatus: number | null | undefined;
   let { accessToken, sessionToken, hasRefreshToken } = await ensureFreshAccessToken(req);
 
   assertAbsoluteIdpUrl(targetUrl);
 
-  const makeCall = async (bearer?: string) => {
+  let firstInit: RequestInit = init;
+  if (opts.initFor) {
+    const built = sessionToken ? await opts.initFor(sessionToken) : null;
+    if (!built) return { ok: false, status: 0, json: null, attemptedRefresh: false, skipped: true };
+    firstInit = built;
+  }
+
+  const makeCall = async (bearer?: string, callInit: RequestInit = firstInit) => {
     // NOTE (307290): this fetch is UNGUARDED, and so is the first call to it at
     // the "First attempt" below. Only the JSON PARSE (try/catch immediately
     // after) and the RETRY are guarded. A transport-level failure - DNS, refused,
@@ -141,8 +167,8 @@ export async function idpFetchJSON<T = any>(
     // carve-out. Correcting b4b8ffae's message, which wrongly said every risky
     // branch here is try/caught.
     const res = await fetch(targetUrl, {
-      ...init,
-      headers: buildHeaders(req, bearer, init.headers as any),
+      ...callInit,
+      headers: buildHeaders(req, bearer, callInit.headers as any),
     });
     let json: any = null;
     try { json = await res.json(); } catch { json = null; }
@@ -158,13 +184,15 @@ export async function idpFetchJSON<T = any>(
     try {
       // Use centralized internal API helper for server-to-server calls
       const rf = await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+      refreshStatus = rf.status;
       if (rf.ok) {
         const fresh = await getSession(sessionToken);
-        ({ res, json } = await makeCall(fresh?.idpAccessToken));
+        const retryInit = opts.initFor ? await opts.initFor(sessionToken) : firstInit;
+        if (retryInit) ({ res, json } = await makeCall(fresh?.idpAccessToken, retryInit));
       }
-    } catch {}
+    } catch { if (refreshStatus === undefined) refreshStatus = null; }
   }
 
   const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.('Retry-After'));
-  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
+  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(refreshStatus !== undefined ? { refreshStatus } : {}), ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

package/src/lib/idp-logout.ts

@@ -0,0 +1,66 @@
+import type { NextRequest } from 'next/server';
+import { idpFetchJSON } from './idp-fetch';
+import { getSession, getBetterAuthSession } from './session-store';
+import { ENV_CONFIG } from '../config/env';
+
+/**
+ * 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 (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).
+ * 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 async function revokeSessionAtIdp(req: NextRequest): Promise<IdpLogoutOutcome> {
+  let resolvedSession: string | undefined;
+  const result = await idpFetchJSON(
+    req,
+    `${ENV_CONFIG.IDP_URL}/api/Account/logout`,
+    {},
+    {
+      initFor: async (token) => {
+        resolvedSession = token;
+        let session = await getSession(token);
+        if (!session?.idpRefreshToken) session = (await 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: string): Promise<boolean> {
+  let session = await getSession(sessionToken);
+  if (!session) session = await getBetterAuthSession(sessionToken);
+  if (!session) return false;
+  return String((session as any).refreshTokenClearedReason ?? '').startsWith('IDP_DISCARD_TOKEN');
+}

package/src/routes/auth/logout.ts

@@ -17,6 +17,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
 import { deleteSessionEverywhere } from '../../lib/session-store';
+import { revokeSessionAtIdp } from '../../lib/idp-logout';
 import {
   getSessionCookieName,
   getSecureSessionCookieName,
@@ -27,15 +28,29 @@ import {
 import { siteEvents, getClientIp } from '../../lib/site-logger';
 import { logExceptionWithCorrelation } from '../../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.
+ */
 export const SESSION_NOT_ENDED_CODE = 'SESSION_NOT_ENDED';
-export 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 const SESSION_NOT_ENDED_IDP_MESSAGE = 'We could not confirm the sign-out with the identity service.';
+export 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
  */
@@ -54,7 +69,19 @@ export async function POST(req: NextRequest) {
     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 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.
@@ -63,7 +90,7 @@ export async function POST(req: NextRequest) {
         await deleteSessionEverywhere(sessionId);
         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);
       }
     }
@@ -82,8 +109,13 @@ export async function POST(req: NextRequest) {
     }
 
     // Build response that clears session cookies
-    const response = serverDeleteFailed
-      ? NextResponse.json({ success: false, code: SESSION_NOT_ENDED_CODE, message: SESSION_NOT_ENDED_MESSAGE }, { status: 500 })
+    const response = (localDeleteFailed || idpRevokeFailed)
+      ? NextResponse.json(
+          localDeleteFailed
+            ? { success: false, code: SESSION_NOT_ENDED_CODE, cause: 'local_delete_failed' as SessionNotEndedCause, message: SESSION_NOT_ENDED_LOCAL_MESSAGE }
+            : { success: false, code: SESSION_NOT_ENDED_CODE, cause: 'idp_unconfirmed' as SessionNotEndedCause, message: SESSION_NOT_ENDED_IDP_MESSAGE },
+          { status: 500 },
+        )
       : NextResponse.json({
           success: true,
           message: 'Logged out successfully'

package/src/server/auth.ts

@@ -442,7 +442,7 @@ export async function getFreshIdpToken(
     },
     {
       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.
     }
   );