@payez/next-mvp 4.10.0 → 4.12.0

package/dist/api-handlers/auth/refresh.js

@@ -1,50 +1,67 @@
 "use strict";
 /**
- * CRITICAL REFRESH TOKEN API HANDLER
+ * REFRESH TOKEN API HANDLER - a thin HTTP wrapper over `ensureFreshAccessToken` (R-over-E, BAPert 76449; design: docs/refresh-r-over-e-delta.md)
  *
- * ASK BEFORE EDITING - TESTED AND WORKING SYSTEM
+ * ASK BEFORE EDITING - this is the route every browser, middleware and `internalRefresh` caller reaches.
  *
- * This handler manages the server-side refresh token cycle with:
- * - Better Auth session extraction (the ONLY way a session is established here)
- * - PayEz IDP refresh token exchange
- * - Session state updates with new tokens
- * - Proper error handling and logging
- * - Single-use semantics enforcement
+ * `lib/ensure-fresh-access-token` is the ONE implementation that talks to the IdP, holds the refresh lock and writes the tokens (post-lock
+ * token, in-doubt marker, fetch timeout, envelope rule, dropped-persist and canonical-row handling all live there). This file keeps what only
+ * an HTTP request has:
+ *  - resolving the session from the request's own Better Auth cookie,
+ *  - the `x-session-token` ownership rejection (below),
+ *  - the `x-request-id` trace id (log correlation only; it is never the lock identity),
+ *  - mapping E's typed result onto this route's existing JSON bodies and status codes.
+ * The bodies did not change except where E's rules did (see CHANGELOG): the browser, `middleware/create-middleware`, `lib/token-lifecycle`
+ * (which reads `reason === 'already_fresh'`) and `lib/idp-fetch` / `lib/api-handler` (via `internalRefresh`) depend on them.
  *
  * ── 246007: THE `x-session-token` FALLBACK IS GONE. IT NOW HARD-DENIES. ────
- * This list previously advertised an x-session-token fallback for internal
- * callers as a current capability. That behaviour has been REMOVED: a request presenting `x-session-token` with
- * no cookie-resolved session of its own is rejected 401 UNAUTHORIZED, because
- * there is no session to establish ownership of the token it names. Accepting
- * it let a caller refresh a session they did not own.
+ * A request presenting `x-session-token` with no cookie-resolved session of its own is rejected 401 UNAUTHORIZED, because there is no
+ * session to establish ownership of the token it names. Accepting it let a caller refresh a session they did not own. This docstring
+ * ships (it is compiled into dist and the .d.ts), so it describes what the code does.
  *
- * The line is corrected here rather than merely deleted, and it is called out
- * rather than quietly dropped, because THIS DOCSTRING SHIPS. It is compiled
- * into dist and into the .d.ts, so it reaches every consumer's editor as hover
- * text. QAPert-NightHawk caught that the fixed build was still describing the
- * removed capability as a current feature (34973) — her verifier tests code
- * properties and reads no comments, so a correct build could have published
- * documentation asserting the opposite of what the code does.
- *
- * That matters twice over: an internal caller relying on the fallback gets a
- * silent behavioural break while the docs promise it still works, and a
- * published package that misdescribes its own auth behaviour is the same
- * amplifier that put other defects onto three surfaces — shipped code carrying
- * instructions for using it wrongly.
- *
- * @version 2.1
+ * @version 3.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.POST = void 0;
 exports.createRefreshHandler = createRefreshHandler;
 const server_1 = require("next/server");
-const crypto_1 = require("crypto");
 const auth_1 = require("../../server/auth");
-const session_store_1 = require("../../lib/session-store");
-const token_expiry_1 = require("../../lib/token-expiry");
-const token_utils_1 = require("../../auth/utils/token-utils");
-const token_log_id_1 = require("../../lib/token-log-id");
-const refresh_rotation_1 = require("../../lib/refresh-rotation");
+const ensure_fresh_access_token_1 = require("../../lib/ensure-fresh-access-token");
+const refresh_in_doubt_1 = require("../../lib/refresh-in-doubt");
+const safe_trace_id_1 = require("../../lib/safe-trace-id");
+const log_safe_1 = require("../../lib/log-safe");
+/** E's failure -> this route's body and status. Bodies for the cases the route always had are exactly as they were. */
+function failureResponse(r) {
+    switch (r.code) {
+        case 'NO_SESSION':
+            return server_1.NextResponse.json({ error: 'No session available for refresh', code: 'UNAUTHORIZED' }, { status: 401 });
+        case 'NO_REFRESH_TOKEN':
+            return server_1.NextResponse.json({
+                error: 'No refresh token available',
+                code: 'NO_REFRESH_TOKEN', // Terminal state - session cannot be refreshed
+                terminal: true, // Signal to frontend: don't retry, redirect to login
+                resolution: r.resolution ?? 'User must re-authenticate',
+            }, { status: 401 });
+        case 'CONFLICT':
+            return server_1.NextResponse.json({ error: 'Refresh already in progress', code: 'CONFLICT', retryable: true }, { status: 409 });
+        default: {
+            const body = {
+                error: r.message,
+                code: r.code,
+                retryable: r.retryable ?? false,
+                discardToken: r.discardToken ?? false,
+            };
+            if (r.terminal !== undefined)
+                body.terminal = r.terminal;
+            if (r.resolution !== undefined)
+                body.resolution = r.resolution;
+            // A timed-out refresh is outcome-UNKNOWN (BAPert 76403): say so, so a client does not treat it as a plain upstream failure.
+            if (r.code === refresh_in_doubt_1.UPSTREAM_TIMEOUT_CODE)
+                body.outcomeUnknown = true;
+            return server_1.NextResponse.json(body, { status: r.status });
+        }
+    }
+}
 /**
  * Creates a refresh token handler for Next.js API routes
  *
@@ -67,46 +84,18 @@ function createRefreshHandler(config) {
     const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
     return async function POST(req) {
         try {
-            // Extract session from Better Auth
+            // Extract session from Better Auth (the ONLY way a session is established here)
             const betterAuthSession = await (0, auth_1.getSession)(req);
-            let sessionToken = (betterAuthSession?.session?.token);
-            let userId = betterAuthSession?.user?.id;
+            const sessionToken = (betterAuthSession?.session?.token);
+            const userId = betterAuthSession?.user?.id;
             if (!sessionToken) {
-                // OWNERSHIP CHECK on the x-session-token fallback (246007). BAPert ruled
-                // 34708: ship it, accept the one-time re-login cost, do not gate on 240654.
-                //
-                // WHAT THIS CLOSED: the fallback took a session token from a CALLER-SUPPLIED
-                // header and acted on that session with no check that it belonged to the
-                // caller. /api/auth/* is in publicRoutes on the consuming surfaces, so an
-                // UNAUTHENTICATED caller who knew any session token could cause that session
-                // to be refreshed -- an identity assumption, and the precondition for the
-                // forced-logout chain via IDP reuse detection.
-                //
-                // WHY THE CHECK IS A HARD DENY RATHER THAN A COMPARISON, which is the part
-                // worth understanding before anyone "improves" it: this branch is reached
-                // ONLY when getBetterAuthSession() failed to resolve a session from the
-                // request's own cookie. The natural ownership check -- "the header may only
-                // name the session the caller's cookie already resolves to" -- therefore has
-                // nothing to compare against by construction. Any correct ownership test at
-                // this point evaluates to reject. So the check and outright removal coincide
-                // here; a more permissive version is not possible without moving the check
-                // somewhere it can actually see an authenticated identity.
-                //
-                // WHO THIS AFFECTS, and it is a deliberate accepted cost, not an oversight:
-                // internal callers (lib/internal-api internalRefresh, from api-handler and
-                // idp-fetch) forward the end user's cookie. Where that cookie resolves they
-                // never enter this branch and are unaffected. Where it does not -- sessions
-                // minted before the graft dual-write (8a5ac21) whose cookie carries only the
-                // __Secure- name, which the pre-240654 resolver could not read -- the refresh
-                // now fails and the user re-authenticates ONCE. Their next login writes both
-                // cookie names and they are permanently fine. That population cannot grow, does
-                // not age out (session TTL slides on every write), and does not self-heal on
-                // use (this handler sets no cookie) -- so the only ways out were to accept the
-                // re-login or leave the defect live. BAPert chose to accept it.
-                //
-                // If server-to-server refresh must work WITHOUT an end-user cookie, that needs
-                // real service authentication -- a shared secret, mTLS, or a network policy --
-                // never a header any client can set.
+                // OWNERSHIP CHECK on the x-session-token fallback (246007; BAPert ruled 34708: ship it, accept the one-time re-login cost).
+                // This branch is reached ONLY when getBetterAuthSession() failed to resolve a session from the request's own cookie, so the natural
+                // check ("the header may only name the session the caller's cookie already resolves to") has nothing to compare against by
+                // construction: any correct ownership test here evaluates to reject. So the check and outright removal coincide. Internal callers
+                // (lib/internal-api internalRefresh) forward the end user's cookie and never enter this branch where that cookie resolves. If
+                // server-to-server refresh must work WITHOUT an end-user cookie it needs real service authentication (a shared secret, mTLS, a network
+                // policy), never a header any client can set.
                 const headerSessionToken = req.headers.get('x-session-token');
                 if (headerSessionToken) {
                     console.warn('[AUTH_REFRESH] REJECTED x-session-token: no cookie-resolved session to own it. ' +
@@ -125,711 +114,22 @@ function createRefreshHandler(config) {
                     code: 'UNAUTHORIZED'
                 }, { status: 401 });
             }
-            // Get current session
-            const currentSession = await (0, session_store_1.getSession)(sessionToken);
-            // NOTE: Field is idpRefreshToken (not refreshToken) per normalized naming convention
-            if (!currentSession?.idpRefreshToken) {
-                console.warn('[AUTH_REFRESH] No refresh token available', { userId });
-                return server_1.NextResponse.json({
-                    error: 'No refresh token available',
-                    code: 'NO_REFRESH_TOKEN', // Terminal state - session cannot be refreshed
-                    terminal: true, // Signal to frontend: don't retry, redirect to login
-                    resolution: 'User must re-authenticate'
-                }, { status: 401 });
-            }
-            // ============================================================================
-            // HIGH VISIBILITY: PRE-FLIGHT REFRESH DIAGNOSTICS
-            // ============================================================================
-            const now = Date.now();
-            const refreshTokenAge = currentSession.idpRefreshTokenIssuedAt
-                ? Math.round((now - currentSession.idpRefreshTokenIssuedAt) / 1000)
-                : 'unknown';
-            const refreshTokenExpiresIn = currentSession.idpRefreshTokenExpires
-                ? Math.round((currentSession.idpRefreshTokenExpires - now) / 1000)
-                : 'unknown';
-            const accessTokenExpiresIn = currentSession.idpAccessTokenExpires
-                ? Math.round((currentSession.idpAccessTokenExpires - now) / 1000)
-                : 'unknown';
-            console.log('╔══════════════════════════════════════════════════════════════════════════════╗');
-            console.log('║                    REFRESH TOKEN ATTEMPT - PRE-FLIGHT                        ║');
-            console.log('╠══════════════════════════════════════════════════════════════════════════════╣');
-            console.log(`║ User: ${(userId || 'unknown').substring(0, 50).padEnd(50)}                   ║`);
-            console.log(`║ Session: ${(0, token_log_id_1.tokenLogId)(sessionToken)}                                                        ║`);
-            console.log('╠──────────────────────────────────────────────────────────────────────────────╣');
-            console.log(`║ Access Token Expires In:  ${String(accessTokenExpiresIn).padEnd(10)} seconds                            ║`);
-            console.log(`║ Refresh Token Age:        ${String(refreshTokenAge).padEnd(10)} seconds                            ║`);
-            console.log(`║ Refresh Token Expires In: ${String(refreshTokenExpiresIn).padEnd(10)} seconds                            ║`);
-            console.log(`║ Refresh Token Length:     ${String(currentSession.idpRefreshToken?.length || 0).padEnd(10)} chars                              ║`);
-            console.log(`║ 2FA Complete:             ${String(!!currentSession.mfaVerified).padEnd(10)}                                   ║`);
-            console.log(`║ Auth Level (ACR):         ${String(currentSession.authenticationLevel || '1').padEnd(10)}                                   ║`);
-            console.log('╚══════════════════════════════════════════════════════════════════════════════╝');
-            // LOCK IDENTITY IS MINTED SERVER-SIDE. It must never come from a header.
-            //
-            // This was `req.headers.get('x-request-id') ?? \`refresh_${Date.now()}\``, and the
-            // value was used as the lock's `acquiredBy`. Below it, a branch let a caller
-            // PROCEED WITHOUT THE LOCK when the existing lock's acquiredBy equalled the id
-            // they had supplied. Since the caller chose that id, the branch was a lock
-            // bypass requiring no guesswork: send N concurrent requests all carrying the
-            // same x-request-id, and every one after the first skips the wait.
-            //
-            // That completed an attacker-controlled forced logout, because the serialisation
-            // is what prevents refresh-token REUSE, and the IDP treats reuse as compromise:
-            // IdentityRefreshTokenService:166 -> RevokeDescendantTokens ->
-            // IdentityRefreshTokenRepository:142 revokes every ACTIVE token for that USER
-            // issued after the reused one -- across all devices and all client apps. So a
-            // caller who knew one session token could log a user out everywhere by sending
-            // a few requests with a header value of their own choosing.
-            //
-            // Minting server-side removes the bypass by construction: no caller can produce
-            // a value that matches an in-flight lock, so the equality branch can never be
-            // true and is deleted rather than left inert -- an unreachable branch that
-            // trusts a header is a trap for whoever edits this next.
-            //
-            // The anti-deadlock intent that branch served is preserved by the wait path
-            // below, which is the correct handling anyway: a genuine duplicate waits for the
-            // in-flight refresh and returns its result instead of starting a second one.
-            // The header is still read, for TRACING ONLY, and never influences control flow.
-            const traceId = req.headers.get('x-request-id') ?? undefined;
-            const requestId = `refresh_${(0, crypto_1.randomUUID)()}`;
-            const lockAcquired = await (0, session_store_1.acquireRefreshLock)(sessionToken, requestId, 5000);
-            let weAcquiredLock = false;
-            let releaseLockVersion;
-            if (!lockAcquired.acquired) {
-                {
-                    // Wait for the lock to release, then check if token is now fresh
-                    console.info('[AUTH_REFRESH] Refresh in progress by another request, waiting for completion...', { requestId, traceId });
-                    const maxWaitMs = 5000;
-                    const checkIntervalMs = 200;
-                    const startWait = Date.now();
-                    while (Date.now() - startWait < maxWaitMs) {
-                        await new Promise(resolve => setTimeout(resolve, checkIntervalMs));
-                        // Check if lock was released
-                        const lockCheck = await (0, session_store_1.checkRefreshLock)(sessionToken);
-                        if (!lockCheck) {
-                            // Lock released - check if token is now fresh
-                            const refreshedSession = await (0, session_store_1.getSession)(sessionToken);
-                            if (refreshedSession?.idpAccessToken && refreshedSession?.idpAccessTokenExpires) {
-                                const timeUntilExpiry = refreshedSession.idpAccessTokenExpires - Date.now();
-                                const fiveMinutes = 5 * 60 * 1000;
-                                if (timeUntilExpiry > fiveMinutes) {
-                                    console.info('[AUTH_REFRESH] Lock released, token is fresh - returning success', {
-                                        requestId,
-                                        accessTokenExpires: new Date(refreshedSession.idpAccessTokenExpires).toISOString(),
-                                        waitedMs: Date.now() - startWait,
-                                    });
-                                    return server_1.NextResponse.json({
-                                        refreshed: true,
-                                        reason: 'completed_by_concurrent_request',
-                                        accessTokenExpires: refreshedSession.idpAccessTokenExpires,
-                                        hasRefreshToken: !!refreshedSession.idpRefreshToken,
-                                    });
-                                }
-                            }
-                            // Lock released but token not fresh - try to acquire lock ourselves
-                            break;
-                        }
-                    }
-                    // Still locked after waiting - return 409
-                    console.warn('[AUTH_REFRESH] Refresh still in progress after waiting', { requestId, waitedMs: Date.now() - startWait });
-                    return server_1.NextResponse.json({
-                        error: 'Refresh already in progress',
-                        code: 'CONFLICT'
-                    }, { status: 409 });
-                }
-            }
-            else {
-                weAcquiredLock = true;
-                releaseLockVersion = lockAcquired.lockInfo?.lockVersion;
-            }
-            // Before performing network refresh, re-check if tokens are already fresh
-            const latestAfterLock = await (0, session_store_1.getSession)(sessionToken);
-            const fiveMinutes = 5 * 60 * 1000;
-            const timeUntilExpiry = latestAfterLock?.idpAccessTokenExpires
-                ? latestAfterLock.idpAccessTokenExpires - Date.now()
-                : -1;
-            // CRITICAL: Also check the actual JWT's exp claim - Redis might have stale data
-            let actualJwtExpMs = -1;
-            let tokenMismatch = false;
-            if (latestAfterLock?.idpAccessToken) {
-                try {
-                    const tokenParts = latestAfterLock.idpAccessToken.split('.');
-                    if (tokenParts.length === 3) {
-                        const payload = JSON.parse(Buffer.from(tokenParts[1], 'base64url').toString());
-                        actualJwtExpMs = (payload.exp || 0) * 1000;
-                        const now = Date.now();
-                        // If the actual JWT is expired, we MUST refresh regardless of what Redis says
-                        if (actualJwtExpMs < now) {
-                            tokenMismatch = true;
-                        }
-                    }
-                }
-                catch (e) {
-                    // If we can't decode, proceed with normal logic
-                }
-            }
-            console.log('[AUTH_REFRESH] Pre-refresh check:', {
-                userId,
-                hasAccessToken: !!latestAfterLock?.idpAccessToken,
-                accessTokenExpires: latestAfterLock?.idpAccessTokenExpires
-                    ? new Date(latestAfterLock.idpAccessTokenExpires).toISOString()
-                    : 'undefined',
-                actualJwtExp: actualJwtExpMs > 0 ? new Date(actualJwtExpMs).toISOString() : 'unknown',
-                now: new Date().toISOString(),
-                timeUntilExpiryMs: timeUntilExpiry,
-                tokenMismatch,
-                willRefresh: timeUntilExpiry <= fiveMinutes || tokenMismatch
-            });
-            // Only skip refresh if BOTH Redis says fresh AND the actual JWT is not expired
-            if (latestAfterLock?.idpAccessToken && latestAfterLock?.idpAccessTokenExpires &&
-                timeUntilExpiry > fiveMinutes && !tokenMismatch) {
-                console.info('[AUTH_REFRESH] Skipping refresh: tokens already fresh', { userId, timeUntilExpiryMs: timeUntilExpiry });
-                if (weAcquiredLock) {
-                    await (0, session_store_1.releaseRefreshLock)(sessionToken, requestId, releaseLockVersion);
-                    weAcquiredLock = false;
-                }
-                return server_1.NextResponse.json({
-                    refreshed: false,
-                    reason: 'already_fresh',
-                    accessTokenExpires: latestAfterLock.idpAccessTokenExpires,
-                    hasRefreshToken: !!latestAfterLock.idpRefreshToken,
-                });
-            }
-            // If we detected a token mismatch, log it prominently
-            if (tokenMismatch) {
-                console.warn('[AUTH_REFRESH] Token mismatch detected - forcing refresh despite Redis claiming fresh', {
-                    userId,
-                    redisExpires: latestAfterLock?.idpAccessTokenExpires ? new Date(latestAfterLock.idpAccessTokenExpires).toISOString() : 'N/A',
-                    actualJwtExp: new Date(actualJwtExpMs).toISOString()
-                });
-            }
-            // Copy refresh token for use in IDP call
-            // 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.
-            // 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 (0, session_store_1.releaseRefreshLock)(sessionToken, requestId, releaseLockVersion);
-                    weAcquiredLock = false;
-                }
-                return server_1.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 (0, session_store_1.releaseRefreshLock)(sessionToken, requestId, releaseLockVersion);
-                    weAcquiredLock = false;
-                }
-                return server_1.NextResponse.json({
-                    error: 'No refresh token available',
-                    code: 'NO_REFRESH_TOKEN',
-                    terminal: true,
-                    resolution: 'User must re-authenticate'
-                }, { status: 401 });
-            }
-            const originalRefreshToken = latestAfterLock.idpRefreshToken;
-            // 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
-                let authMethods = [];
-                if (currentSession.authenticationMethods) {
-                    if (typeof currentSession.authenticationMethods === 'string') {
-                        try {
-                            authMethods = JSON.parse(currentSession.authenticationMethods);
-                        }
-                        catch (e) {
-                            console.warn('[AUTH_REFRESH] Failed to parse authenticationMethods', { authenticationMethods: currentSession.authenticationMethods });
-                        }
-                    }
-                    else if (Array.isArray(currentSession.authenticationMethods)) {
-                        authMethods = currentSession.authenticationMethods;
-                    }
-                }
-                // For OAuth sessions with empty AMR claims, provide defaults
-                // OAuth IS a form of multi-factor auth (you authenticated with another provider)
-                let isOAuthSession = !!currentSession.oauthProvider;
-                if (authMethods.length === 0 && isOAuthSession) {
-                    // OAuth sessions get default AMR claims
-                    authMethods = ['pwd', 'mfa'];
-                    console.log('[AUTH_REFRESH] OAuth session with empty AMR - using defaults:', {
-                        oauthProvider: currentSession.oauthProvider,
-                        defaultAmr: authMethods
-                    });
-                }
-                // Check authMethods first, then fallback to twoFactorMethod field (set by transitionTo2FASession)
-                // For OAuth sessions, use 'oauth' as the 2FA method since OAuth itself is the authentication
-                const twoFactorMethod = authMethods.find(m => ['sms', 'totp', 'email'].includes(m))
-                    || currentSession.mfaMethod
-                    || (isOAuthSession ? 'oauth' : null);
-                // DEBUG: Log what we have for 2FA
-                console.log('[AUTH_REFRESH] 2FA Debug:', {
-                    authMethods,
-                    authMethodsRaw: currentSession.authenticationMethods,
-                    twoFactorMethodFromSession: currentSession.mfaMethod,
-                    twoFactorMethodResolved: twoFactorMethod,
-                    twoFactorComplete: currentSession.mfaVerified,
-                    sessionKeys: Object.keys(currentSession)
-                });
-                // Build refresh request body per PayEz wire standard (snake_case)
-                // See: 2FA-TOKEN-REFRESH-CONTEXT.md - "The Ninja Shit"
-                // For OAuth sessions with 2FA complete, use ACR level 2
-                let acrValue = String(currentSession.authenticationLevel ?? '1');
-                if (currentSession.oauthProvider && currentSession.mfaVerified && acrValue === '1') {
-                    acrValue = '2'; // OAuth with 2FA complete = full authentication
-                }
-                const refreshRequestBody = {
-                    refresh_token: originalRefreshToken,
-                    amr: authMethods,
-                    acr: acrValue
-                };
-                // DEBUG: Log exact request body
-                console.log('[AUTH_REFRESH] Request body:', JSON.stringify({
-                    refresh_token: '***REDACTED***',
-                    amr: authMethods,
-                    acr: acrValue,
-                    acrType: typeof acrValue
-                }));
-                const twoFactorVerified = !!currentSession.mfaVerified;
-                if (twoFactorVerified) {
-                    refreshRequestBody.two_factor_verified = true;
-                }
-                if (twoFactorMethod) {
-                    refreshRequestBody.two_factor_method = twoFactorMethod;
-                }
-                if (currentSession.mfaCompletedAt) {
-                    refreshRequestBody.two_factor_completed_at = new Date(currentSession.mfaCompletedAt).toISOString();
-                }
-                // Log the full request details for debugging
-                console.log('[AUTH_REFRESH] Sending refresh request:', {
-                    url: `${idpBaseUrl}${refreshEndpoint}`,
-                    clientId,
-                    hasRefreshToken: !!refreshRequestBody.refresh_token,
-                    refreshTokenLength: refreshRequestBody.refresh_token?.length,
-                    amr: refreshRequestBody.amr,
-                    acr: refreshRequestBody.acr
-                });
-                let refreshResponse;
-                try {
-                    refreshResponse = await fetch(`${idpBaseUrl}${refreshEndpoint}`, {
-                        method: 'POST',
-                        headers: {
-                            'Content-Type': 'application/json',
-                            'X-Client-Id': clientId,
-                        },
-                        body: JSON.stringify(refreshRequestBody),
-                    });
-                }
-                catch (fetchError) {
-                    // Network error - IDP unreachable
-                    // Note: Lock will be released by finally block
-                    console.error('[AUTH_REFRESH] IDP unreachable:', {
-                        error: fetchError instanceof Error ? fetchError.message : String(fetchError),
-                        idpUrl: idpBaseUrl,
-                        userId
-                    });
-                    return server_1.NextResponse.json({
-                        error: 'IDP service unavailable',
-                        code: 'UPSTREAM_SERVICE_UNAVAILABLE',
-                        retryable: true,
-                        discardToken: false
-                    }, { status: 503 });
-                }
-                // Parse response body - handle empty or invalid JSON
-                let responseData;
-                try {
-                    const responseText = await refreshResponse.text();
-                    if (!responseText || responseText.trim() === '') {
-                        // Note: Lock will be released by finally block
-                        console.error('[AUTH_REFRESH] Empty response from IDP:', {
-                            status: refreshResponse.status,
-                            statusText: refreshResponse.statusText,
-                            userId
-                        });
-                        return server_1.NextResponse.json({
-                            error: 'Empty response from IDP',
-                            code: 'UPSTREAM_SERVICE_ERROR',
-                            retryable: true,
-                            discardToken: false
-                        }, { status: 502 });
-                    }
-                    responseData = JSON.parse(responseText);
-                }
-                catch (parseError) {
-                    // Note: Lock will be released by finally block
-                    console.error('[AUTH_REFRESH] Failed to parse IDP response:', {
-                        error: parseError instanceof Error ? parseError.message : String(parseError),
-                        status: refreshResponse.status,
-                        userId
-                    });
-                    return server_1.NextResponse.json({
-                        error: 'Invalid response from IDP',
-                        code: 'UPSTREAM_SERVICE_ERROR',
-                        retryable: true,
-                        discardToken: false
-                    }, { status: 502 });
-                }
-                // Handle non-OK responses with structured error format
-                if (!refreshResponse.ok) {
-                    // Parse structured error from IDP
-                    const idpError = responseData?.error || {};
-                    const errorCode = idpError.code || 'UNKNOWN_ERROR';
-                    const errorMessage = idpError.message || 'Token refresh failed';
-                    // CRITICAL: 401 means token is definitively invalid - always discard
-                    // This prevents redirect loops where viability check keeps returning canRefresh:true
-                    let discardToken = refreshResponse.status === 401 || idpError.discard_token === true;
-                    const retryable = refreshResponse.status !== 401 && idpError.retryable === true;
-                    const resolution = idpError.resolution || null;
-                    // ============================================================================
-                    // HIGH VISIBILITY: REFRESH TOKEN FAILURE DIAGNOSTICS
-                    // ============================================================================
-                    // Translate error codes to human-readable explanations
-                    const failureReasons = {
-                        'UNAUTHORIZED': 'Token was already used (rotation) OR token is expired OR token was revoked',
-                        'INVALID_REFRESH_TOKEN': 'Token format invalid OR token not found in IDP database',
-                        'TOKEN_EXPIRED': 'Refresh token exceeded its max lifetime',
-                        'TOKEN_REVOKED': 'Token was explicitly revoked (logout, password change, admin action)',
-                        'TOKEN_REUSE_DETECTED': 'Same refresh token used twice - possible token theft, all tokens revoked',
-                        'UPSTREAM_SERVICE_ERROR': 'IDP internal error - token may have been rotated before failure',
-                        'INTERNAL_ERROR': 'IDP internal error - check IDP logs for details',
-                        'RATE_LIMITED': 'Too many refresh attempts - try again later',
-                    };
-                    const whyItFailed = failureReasons[errorCode] || 'Unknown error - check IDP logs';
-                    console.error('╔══════════════════════════════════════════════════════════════════════════════╗');
-                    console.error('║              ❌ REFRESH TOKEN FAILURE - DIAGNOSTIC REPORT                    ║');
-                    console.error('╠══════════════════════════════════════════════════════════════════════════════╣');
-                    console.error(`║ HTTP Status:    ${String(refreshResponse.status).padEnd(60)}║`);
-                    console.error(`║ Error Code:     ${errorCode.padEnd(60)}║`);
-                    console.error(`║ Discard Token:  ${String(discardToken).padEnd(60)}║`);
-                    console.error(`║ Retryable:      ${String(retryable).padEnd(60)}║`);
-                    console.error('╠──────────────────────────────────────────────────────────────────────────────╣');
-                    console.error(`║ WHY IT FAILED:                                                               ║`);
-                    console.error(`║ ${whyItFailed.substring(0, 76).padEnd(76)} ║`);
-                    console.error('╠──────────────────────────────────────────────────────────────────────────────╣');
-                    console.error(`║ User:           ${(userId || 'unknown').substring(0, 60).padEnd(60)}║`);
-                    console.error(`║ Session:        ${(0, token_log_id_1.tokenLogId)(sessionToken)}                                                     ║`);
-                    console.error(`║ Resolution:     ${(resolution || 'Check IDP logs').substring(0, 60).padEnd(60)}║`);
-                    console.error('╚══════════════════════════════════════════════════════════════════════════════╝');
-                    // NEVER the raw envelope (DotNetPert-Scout, PR 139 review / mail 58691): this used to print
-                    // a stringified dump of responseData (first 1000 chars) - the same whole IDP body the :618
-                    // "unsuccessful" branch stopped logging. The box above already carries status, code and
-                    // flags; add envelope SHAPE only (key names), never values.
-                    console.error('[AUTH_REFRESH] IDP error response shape', {
-                        bodyKeys: responseData && typeof responseData === 'object' ? Object.keys(responseData) : undefined,
-                        errorKeys: idpError && typeof idpError === 'object' ? Object.keys(idpError) : undefined,
-                        errorHasMessage: !!idpError.message,
-                    });
-                    // If IDP signals to discard token, clear it from Redis
-                    if (discardToken) {
-                        // Race-safe discard (CAS): only clear if the refresh token we sent is STILL
-                        // the current one. A concurrent refresh may have already rotated it — our 401
-                        // is then stale, and wiping here would silently log out a healthy session
-                        // (the rotation-race wipe, QA 6873 site 2). Skip the wipe + drop terminal if changed.
-                        const postRefresh = await (0, session_store_1.getSession)(sessionToken);
-                        const tokenUnchanged = !!originalRefreshToken && postRefresh?.idpRefreshToken === originalRefreshToken;
-                        if (tokenUnchanged) {
-                            console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP signaled discard_token', {
-                                reason: 'IDP_DISCARD_TOKEN',
-                                errorCode,
-                                userId,
-                                sessionToken: (0, token_log_id_1.tokenLogId)(sessionToken),
-                                hadRefreshToken: !!currentSession.idpRefreshToken,
-                                stack: new Error().stack
-                            });
-                            await (0, session_store_1.updateSession)(sessionToken, {
-                                idpRefreshToken: '',
-                                idpRefreshTokenExpires: undefined,
-                                refreshTokenClearedAt: Date.now(),
-                                refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
-                            });
-                        }
-                        else {
-                            // Concurrent refresh already rotated the token — our 401 is stale. Return the
-                            // freshly-rotated token directly so the loser succeeds without a retry
-                            // (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 ((0, refresh_rotation_1.rotatedRowIsUsable)(postRefresh)) {
-                                return server_1.NextResponse.json({
-                                    refreshed: true,
-                                    reason: 'completed_by_concurrent_request',
-                                    accessTokenExpires: postRefresh.idpAccessTokenExpires,
-                                    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 server_1.NextResponse.json({
-                                error: errorMessage,
-                                code: errorCode,
-                                discardToken: false,
-                                retryable: true,
-                                resolution,
-                                status: 502
-                            }, { status: 502 });
-                        }
-                    }
-                    return server_1.NextResponse.json({
-                        error: errorMessage,
-                        code: errorCode,
-                        discardToken,
-                        retryable,
-                        resolution,
-                        status: refreshResponse.status
-                    }, { status: refreshResponse.status });
-                }
-                // Validate PayEz canonical envelope for success responses
-                const isCompliant = responseData && typeof responseData === 'object' &&
-                    Object.prototype.hasOwnProperty.call(responseData, 'success') &&
-                    (responseData.success === true ? Object.prototype.hasOwnProperty.call(responseData, 'data') : Object.prototype.hasOwnProperty.call(responseData, 'error')) &&
-                    Object.prototype.hasOwnProperty.call(responseData, 'meta');
-                if (!isCompliant) {
-                    // NEVER the raw body (DotNetPert-Scout, mail 58678): a non-compliant response has an
-                    // UNKNOWN shape by definition, so there is no basis to assume it is free of tokens or
-                    // other IDP-side secrets. Log shape metadata only - same "kind, never value" reasoning
-                    // as the session-store.ts / refresh.ts REFRESH_TOKEN_REMOVAL fixes in PR 138.
-                    console.error('[AUTH_REFRESH] Upstream non-compliant IDP response', {
-                        bodyType: typeof responseData,
-                        bodyKeys: responseData && typeof responseData === 'object' ? Object.keys(responseData) : undefined,
-                        hasSuccessKey: !!(responseData && typeof responseData === 'object' && Object.prototype.hasOwnProperty.call(responseData, 'success')),
-                        hasMetaKey: !!(responseData && typeof responseData === 'object' && Object.prototype.hasOwnProperty.call(responseData, 'meta')),
-                    });
-                    return server_1.NextResponse.json({
-                        error: 'Upstream non-compliance',
-                        code: 'UPSTREAM_SERVICE_ERROR',
-                        retryable: true,
-                        discardToken: false
-                    }, { status: 502 });
-                }
-                if (responseData.success !== true || !responseData.data) {
-                    // Handle success:false with structured error
-                    const idpError = responseData?.error || {};
-                    const errorCode = idpError.code || 'UPSTREAM_VALIDATION_ERROR';
-                    const discardToken = idpError.discard_token === true;
-                    const retryable = idpError.retryable === true;
-                    // NEVER the raw envelope (DotNetPert-Scout, mail 58678): `responseData` here is the
-                    // WHOLE IDP response body, and its `error` sub-object's contents are not something this
-                    // handler controls or has audited - printing it wholesale would ship whatever the IDP
-                    // decided to put there straight to the log sink. Log the fields THIS handler already
-                    // extracts and acts on (retryable, plus envelope-shape flags for diagnosis) instead.
-                    console.warn('[AUTH_REFRESH] IDP refresh unsuccessful', {
-                        code: errorCode,
-                        discardToken,
-                        retryable,
-                        errorHasMessage: !!idpError.message,
-                        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) {
-                        const postRefresh = await (0, session_store_1.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: (0, token_log_id_1.tokenLogId)(sessionToken),
-                                hadRefreshToken: !!currentSession.idpRefreshToken,
-                                stack: new Error().stack
-                            });
-                            await (0, session_store_1.updateSession)(sessionToken, {
-                                idpRefreshToken: '',
-                                idpRefreshTokenExpires: undefined,
-                                refreshTokenClearedAt: Date.now(),
-                                refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
-                            });
-                            return server_1.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 ((0, refresh_rotation_1.rotatedRowIsUsable)(postRefresh)) {
-                            return server_1.NextResponse.json({
-                                refreshed: true,
-                                reason: 'completed_by_concurrent_request',
-                                accessTokenExpires: postRefresh.idpAccessTokenExpires,
-                                hasRefreshToken: !!postRefresh.idpRefreshToken,
-                            });
-                        }
-                    }
-                    return server_1.NextResponse.json({
-                        error: idpError.message || 'Token refresh failed',
-                        code: errorCode,
-                        discardToken: false,
-                        retryable: true,
-                        resolution: idpError.resolution || null,
-                        status: 502
-                    }, { status: 502 });
-                }
-                // Extract tokens from response
-                const payload = responseData.data;
-                const accessToken = payload?.access_token;
-                const refreshToken = payload?.refresh_token;
-                if (!accessToken) {
-                    console.error('[AUTH_REFRESH] Missing access token in IDP response');
-                    return server_1.NextResponse.json({
-                        error: 'Invalid token response from IDP',
-                        code: 'INTERNAL_SERVER_ERROR'
-                    }, { status: 500 });
-                }
-                // Decode and compute token expiries
-                let decodedAccessToken;
-                let accessTokenExpires;
-                let computedRefreshTokenExpires;
-                try {
-                    const result = (0, token_expiry_1.computeTokenExpiries)({ accessToken, refreshToken, preferJwt: true });
-                    decodedAccessToken = result.decodedAccessToken;
-                    accessTokenExpires = result.accessTokenExpires;
-                    computedRefreshTokenExpires = result.refreshTokenExpires;
-                    console.info('[AUTH_REFRESH] Successfully decoded new token pair', {
-                        accessTokenExpires: new Date(accessTokenExpires).toISOString(),
-                        refreshTokenExpires: computedRefreshTokenExpires ? new Date(computedRefreshTokenExpires).toISOString() : null
-                    });
-                }
-                catch (decodeError) {
-                    console.error('[AUTH_REFRESH] Failed to compute token expiries', { error: decodeError });
-                    return server_1.NextResponse.json({
-                        error: 'Failed to decode JWT tokens',
-                        code: 'INTERNAL_SERVER_ERROR'
-                    }, { status: 500 });
-                }
-                // Extract 2FA claims from the new access token
-                let amrClaims = [];
-                if (decodedAccessToken.amr) {
-                    try {
-                        amrClaims = typeof decodedAccessToken.amr === 'string'
-                            ? JSON.parse(decodedAccessToken.amr)
-                            : decodedAccessToken.amr;
-                    }
-                    catch (e) {
-                        console.warn('[AUTH_REFRESH] Failed to parse AMR claims', { amr: decodedAccessToken.amr });
-                        amrClaims = baseSession.authenticationMethods || [];
-                    }
-                }
-                else {
-                    amrClaims = baseSession.authenticationMethods || [];
-                }
-                const acrLevel = String(decodedAccessToken.acr || baseSession.authenticationLevel || '1');
-                // Extract MFA timing claims
-                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 && baseSession.idpRefreshToken) {
-                    console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: No new refresh token in IDP response', {
-                        reason: 'NO_NEW_REFRESH_TOKEN_IN_RESPONSE',
-                        userId,
-                        sessionToken: (0, token_log_id_1.tokenLogId)(sessionToken),
-                        hadRefreshToken: true,
-                        // Kind only, never the value (credential). This branch runs when refreshToken is not a
-                        // non-empty string, so the old raw value was almost always empty - but a token-shaped
-                        // non-string would have been printed. refreshTokenType below already carries the kind.
-                        refreshTokenFromResponsePresent: refreshToken !== undefined && refreshToken !== null && refreshToken !== '',
-                        refreshTokenType: typeof refreshToken,
-                        payloadKeys: Object.keys(payload || {}),
-                        stack: new Error().stack
-                    });
-                }
-                // Keep existing refresh token if IDP doesn't provide a new one
-                // Only clear if IDP explicitly signals discard_token=true (handled in error paths)
-                // NOTE: Use normalized field names (idp* prefix) per SessionData interface
-                // CRITICAL: Extract kid from JWT header - IDP may rotate keys during refresh
-                const newBearerKeyId = (0, token_utils_1.extractKidFromToken)(accessToken);
-                if (newBearerKeyId) {
-                    console.log('[AUTH_REFRESH] Extracted bearerKeyId (kid) from new JWT header:', newBearerKeyId);
-                }
-                else {
-                    console.warn('[AUTH_REFRESH] No kid found in new JWT header');
-                }
-                const sessionUpdate = {
-                    ...baseSession,
-                    idpAccessToken: accessToken,
-                    idpAccessTokenExpires: accessTokenExpires,
-                    idpRefreshToken: hasNewRefresh ? refreshToken : originalRefreshToken,
-                    idpRefreshTokenExpires: hasNewRefresh ? newRefreshTokenExpires : baseSession.idpRefreshTokenExpires,
-                    decodedAccessToken: decodedAccessToken,
-                    // Bearer key ID from JWT header (may change on key rotation)
-                    bearerKeyId: newBearerKeyId || baseSession.bearerKeyId,
-                    authenticationMethods: amrClaims,
-                    authenticationLevel: acrLevel,
-                    // 170007 rule 2 (BAPert ruling on 121350): '||' is the wrong operator
-                    // for a fact with an expiry. mfaVerified is derived from amrClaims,
-                    // which is FRESH every exchange (decoded from the token just
-                    // returned, falling back to the prior session's amr only on a
-                    // genuine decode failure a few lines up — not on "this token
-                    // doesn't currently carry mfa"). ORing in currentSession.mfaVerified
-                    // made the flag MONOTONIC against a claim that DECAYS (mfa_time,
-                    // 10 minutes): once true, it stayed true forever regardless of
-                    // what the current token actually says, silently re-opening the
-                    // 2FA bypass with no bug in the bridge. Re-derive only.
-                    mfaVerified: amrClaims.includes('mfa'),
-                    mfaCompletedAt: mfaTime,
-                    mfaExpiresAt: mfaExpires,
-                    mfaValidityHours: mfaValidityHours
-                };
-                await (0, session_store_1.updateSession)(sessionToken, sessionUpdate);
-                console.info('[AUTH_REFRESH] Token refreshed successfully', {
-                    expiresAt: new Date(accessTokenExpires).toISOString(),
-                    userId,
-                    hasNewRefreshToken: hasNewRefresh,
-                    hasAccessToken: !!accessToken // PAY-1427: was tokenPreview (first 20 chars of the new access token)
-                });
-            }
-            catch (error) {
-                console.error('[AUTH_REFRESH] Error during token refresh', { error });
-                return server_1.NextResponse.json({
-                    error: 'Token refresh error',
-                    code: 'INTERNAL_SERVER_ERROR'
-                }, { status: 500 });
-            }
-            finally {
-                if (weAcquiredLock) {
-                    await (0, session_store_1.releaseRefreshLock)(sessionToken, requestId, releaseLockVersion);
-                }
-            }
-            // Load the latest session to return basic status
-            const latest = await (0, session_store_1.getSession)(sessionToken);
-            if (!latest?.idpAccessToken) {
-                return server_1.NextResponse.json({
-                    error: 'No access token after refresh',
-                    code: 'INTERNAL_SERVER_ERROR'
-                }, { status: 500 });
-            }
+            // The caller's x-request-id is TRACE ONLY (E keeps it as `traceId` for logs); the lock identity is minted inside E.
+            const traceId = (0, safe_trace_id_1.sanitizeTraceId)(req.headers.get('x-request-id'));
+            const result = await (0, ensure_fresh_access_token_1.ensureFreshAccessToken)(sessionToken, { idpBaseUrl, clientId, refreshEndpoint }, { requestId: traceId, requireRefreshToken: true });
+            if (!result.ok)
+                return failureResponse(result);
+            // The access token is deliberately NOT in this body (E's result carries it; this route never returns it).
             return server_1.NextResponse.json({
-                refreshed: true,
-                accessTokenExpires: latest.idpAccessTokenExpires,
-                hasRefreshToken: !!latest.idpRefreshToken,
+                refreshed: result.refreshed,
+                // The route's bodies carried a `reason` for two cases only; a plain refresh had none.
+                ...(result.reason === 'refreshed' ? {} : { reason: result.reason }),
+                accessTokenExpires: result.accessTokenExpires,
+                hasRefreshToken: result.hasRefreshToken,
             });
         }
         catch (err) {
-            console.error('[AUTH_REFRESH] Unexpected error', { error: err?.message || String(err) });
+            console.error('[AUTH_REFRESH] Unexpected error', { error: (0, log_safe_1.errForLog)(err) });
             return server_1.NextResponse.json({
                 error: 'Unexpected error during refresh',
                 code: 'INTERNAL_SERVER_ERROR'