@payez/next-mvp 4.8.0 → 4.8.2

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

@@ -1,829 +1,829 @@
-/**
- * CRITICAL REFRESH TOKEN API HANDLER
- *
- * ASK BEFORE EDITING - TESTED AND WORKING SYSTEM
- *
- * 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
- *
- * ── 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.
- *
- * 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
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { randomUUID } from 'crypto';
-import { getSession as getBetterAuthSession } from '../../server/auth';
-import { getSession, updateSession, acquireRefreshLock, releaseRefreshLock, checkRefreshLock } from '../../lib/session-store';
-import { computeTokenExpiries } from '../../lib/token-expiry';
-import { extractKidFromToken } from '../../auth/utils/token-utils';
-import { tokenLogId } from '../../lib/token-log-id';
-
-interface RefreshConfig {
-  idpBaseUrl: string;
-  clientId: string;
-  refreshEndpoint?: string;
-}
-
-/**
- * Creates a refresh token handler for Next.js API routes
- *
- * @param config IDP connection settings (Better Auth handles session crypto)
- * @returns Next.js POST handler function
- *
- * @example
- * ```typescript
- * // In your app's /app/api/auth/refresh/route.ts
- * import { createRefreshHandler } from '@payez/next-mvp/api-handlers/auth/refresh';
- *
- * export const POST = createRefreshHandler({
- *   idpBaseUrl: process.env.IDP_URL!,
- *   clientId: process.env.CLIENT_ID!,
- *   refreshEndpoint: '/api/ExternalAuth/refresh'
- * });
- * ```
- */
-export function createRefreshHandler(config: RefreshConfig) {
-  const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
-
-  return async function POST(req: NextRequest) {
-    try {
-      // Extract session from Better Auth
-      const betterAuthSession = await getBetterAuthSession(req);
-
-      let sessionToken = (betterAuthSession?.session?.token) as string | undefined;
-      let 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.
-        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. ' +
-              'A header-named session is not proof of ownership; the caller must present a ' +
-              'session cookie this server can resolve.',
-          );
-          return NextResponse.json(
-            {
-              error: 'Session ownership could not be established',
-              code: 'UNAUTHORIZED',
-            },
-            { status: 401 },
-          );
-        }
-      }
-
-      if (!sessionToken || !userId) {
-        console.warn('[AUTH_REFRESH] Missing sessionToken or user id on token');
-        return NextResponse.json({
-          error: 'No session available for refresh',
-          code: 'UNAUTHORIZED'
-        }, { status: 401 });
-      }
-
-      // Get current session
-      const currentSession = await 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 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: ${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_${randomUUID()}`;
-      const lockAcquired = await acquireRefreshLock(sessionToken, requestId, 5000);
-
-      let weAcquiredLock = false;
-      let releaseLockVersion: number | undefined;
-
-      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 checkRefreshLock(sessionToken);
-            if (!lockCheck) {
-              // Lock released - check if token is now fresh
-              const refreshedSession = await 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 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 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 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 releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
-          weAcquiredLock = false;
-        }
-        return 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.
-      const originalRefreshToken = currentSession.idpRefreshToken as string;
-
-      try {
-        // Extract 2FA claims from current session
-        let authMethods: string[] = [];
-        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: any = {
-          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: Response;
-        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 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: any;
-        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 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 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: Record<string, string> = {
-            '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:        ${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 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: tokenLogId(sessionToken),
-                hadRefreshToken: !!currentSession.idpRefreshToken,
-                stack: new Error().stack
-              });
-              await 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 (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
-                return NextResponse.json({
-                  refreshed: true,
-                  reason: 'completed_by_concurrent_request',
-                  accessTokenExpires: postRefresh.idpAccessTokenExpires,
-                  hasRefreshToken: !!postRefresh.idpRefreshToken,
-                });
-              }
-            }
-          }
-
-          return 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 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),
-          });
-
-          if (discardToken) {
-            console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP success:false with discard_token', {
-              reason: 'IDP_SUCCESS_FALSE_DISCARD',
-              errorCode,
-              userId,
-              sessionToken: tokenLogId(sessionToken),
-              hadRefreshToken: !!currentSession.idpRefreshToken,
-              stack: new Error().stack
-            });
-            await updateSession(sessionToken, {
-              idpRefreshToken: '',
-              idpRefreshTokenExpires: undefined,
-              refreshTokenClearedAt: Date.now(),
-              refreshTokenClearedReason: `IDP_SUCCESS_FALSE_DISCARD:${errorCode}`
-            });
-          }
-
-          return NextResponse.json({
-            error: idpError.message || 'Token refresh failed',
-            code: errorCode,
-            discardToken,
-            retryable,
-            resolution: idpError.resolution || null
-          }, { status: refreshResponse.status || 400 });
-        }
-
-        // Extract tokens from response
-        const payload = responseData.data as any;
-        const accessToken = payload?.access_token;
-        const refreshToken = payload?.refresh_token;
-
-        if (!accessToken) {
-          console.error('[AUTH_REFRESH] Missing access token in IDP response');
-          return NextResponse.json({
-            error: 'Invalid token response from IDP',
-            code: 'INTERNAL_SERVER_ERROR'
-          }, { status: 500 });
-        }
-
-        // Decode and compute token expiries
-        let decodedAccessToken: any;
-        let accessTokenExpires: number;
-        let computedRefreshTokenExpires: number | undefined;
-        try {
-          const result = 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 NextResponse.json({
-            error: 'Failed to decode JWT tokens',
-            code: 'INTERNAL_SERVER_ERROR'
-          }, { status: 500 });
-        }
-
-        // Extract 2FA claims from the new access token
-        let amrClaims: string[] = [];
-        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 = currentSession.authenticationMethods || [];
-          }
-        } else {
-          amrClaims = currentSession.authenticationMethods || [];
-        }
-        const acrLevel = String(decodedAccessToken.acr || currentSession.authenticationLevel || '1');
-
-        // Extract MFA timing claims
-        const mfaTime = decodedAccessToken.mfa_time ? parseInt(decodedAccessToken.mfa_time) * 1000 : currentSession.mfaCompletedAt;
-        const mfaExpires = decodedAccessToken.mfa_expires ? parseInt(decodedAccessToken.mfa_expires) * 1000 : currentSession.mfaExpiresAt;
-        const mfaValidityHours = decodedAccessToken.mfa_validity_hours ? parseInt(decodedAccessToken.mfa_validity_hours) : currentSession.mfaValidityHours;
-
-        // Update session with new tokens
-        const hasNewRefresh = typeof refreshToken === 'string' && refreshToken.length > 0;
-        const newRefreshTokenExpires = hasNewRefresh ? computedRefreshTokenExpires : undefined;
-
-        // CRITICAL: Log if we're about to clear the refresh token due to missing new token
-        if (!hasNewRefresh && currentSession.idpRefreshToken) {
-          console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: No new refresh token in IDP response', {
-            reason: 'NO_NEW_REFRESH_TOKEN_IN_RESPONSE',
-            userId,
-            sessionToken: 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 = 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: any = {
-          ...currentSession,
-          idpAccessToken: accessToken,
-          idpAccessTokenExpires: accessTokenExpires,
-          idpRefreshToken: hasNewRefresh ? (refreshToken as string) : currentSession.idpRefreshToken,
-          idpRefreshTokenExpires: hasNewRefresh ? newRefreshTokenExpires : currentSession.idpRefreshTokenExpires,
-          decodedAccessToken: decodedAccessToken,
-          // Bearer key ID from JWT header (may change on key rotation)
-          bearerKeyId: newBearerKeyId || currentSession.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 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 NextResponse.json({
-          error: 'Token refresh error',
-          code: 'INTERNAL_SERVER_ERROR'
-        }, { status: 500 });
-      } finally {
-        if (weAcquiredLock) {
-          await releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
-        }
-      }
-
-      // Load the latest session to return basic status
-      const latest = await getSession(sessionToken);
-      if (!latest?.idpAccessToken) {
-        return NextResponse.json({
-          error: 'No access token after refresh',
-          code: 'INTERNAL_SERVER_ERROR'
-        }, { status: 500 });
-      }
-
-      return NextResponse.json({
-        refreshed: true,
-        accessTokenExpires: latest.idpAccessTokenExpires,
-        hasRefreshToken: !!latest.idpRefreshToken,
-      });
-    } catch (err: any) {
-      console.error('[AUTH_REFRESH] Unexpected error', { error: err?.message || String(err) });
-      return NextResponse.json({
-        error: 'Unexpected error during refresh',
-        code: 'INTERNAL_SERVER_ERROR'
-      }, { status: 500 });
-    }
-  };
-}
-
-/**
- * Default POST export — drop-in for `app/api/auth/refresh/route.ts`.
- * Requires environment variables: IDP_URL, CLIENT_ID
- */
-export const POST = createRefreshHandler({
-  idpBaseUrl: process.env.IDP_URL!,
-  clientId: process.env.CLIENT_ID || 'payez_default_client',
-  refreshEndpoint: '/api/ExternalAuth/refresh'
-});
+/**
+ * CRITICAL REFRESH TOKEN API HANDLER
+ *
+ * ASK BEFORE EDITING - TESTED AND WORKING SYSTEM
+ *
+ * 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
+ *
+ * ── 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.
+ *
+ * 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
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { randomUUID } from 'crypto';
+import { getSession as getBetterAuthSession } from '../../server/auth';
+import { getSession, updateSession, acquireRefreshLock, releaseRefreshLock, checkRefreshLock } from '../../lib/session-store';
+import { computeTokenExpiries } from '../../lib/token-expiry';
+import { extractKidFromToken } from '../../auth/utils/token-utils';
+import { tokenLogId } from '../../lib/token-log-id';
+
+interface RefreshConfig {
+  idpBaseUrl: string;
+  clientId: string;
+  refreshEndpoint?: string;
+}
+
+/**
+ * Creates a refresh token handler for Next.js API routes
+ *
+ * @param config IDP connection settings (Better Auth handles session crypto)
+ * @returns Next.js POST handler function
+ *
+ * @example
+ * ```typescript
+ * // In your app's /app/api/auth/refresh/route.ts
+ * import { createRefreshHandler } from '@payez/next-mvp/api-handlers/auth/refresh';
+ *
+ * export const POST = createRefreshHandler({
+ *   idpBaseUrl: process.env.IDP_URL!,
+ *   clientId: process.env.CLIENT_ID!,
+ *   refreshEndpoint: '/api/ExternalAuth/refresh'
+ * });
+ * ```
+ */
+export function createRefreshHandler(config: RefreshConfig) {
+  const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
+
+  return async function POST(req: NextRequest) {
+    try {
+      // Extract session from Better Auth
+      const betterAuthSession = await getBetterAuthSession(req);
+
+      let sessionToken = (betterAuthSession?.session?.token) as string | undefined;
+      let 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.
+        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. ' +
+              'A header-named session is not proof of ownership; the caller must present a ' +
+              'session cookie this server can resolve.',
+          );
+          return NextResponse.json(
+            {
+              error: 'Session ownership could not be established',
+              code: 'UNAUTHORIZED',
+            },
+            { status: 401 },
+          );
+        }
+      }
+
+      if (!sessionToken || !userId) {
+        console.warn('[AUTH_REFRESH] Missing sessionToken or user id on token');
+        return NextResponse.json({
+          error: 'No session available for refresh',
+          code: 'UNAUTHORIZED'
+        }, { status: 401 });
+      }
+
+      // Get current session
+      const currentSession = await 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 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: ${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_${randomUUID()}`;
+      const lockAcquired = await acquireRefreshLock(sessionToken, requestId, 5000);
+
+      let weAcquiredLock = false;
+      let releaseLockVersion: number | undefined;
+
+      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 checkRefreshLock(sessionToken);
+            if (!lockCheck) {
+              // Lock released - check if token is now fresh
+              const refreshedSession = await 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 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 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 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 releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
+          weAcquiredLock = false;
+        }
+        return 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.
+      const originalRefreshToken = currentSession.idpRefreshToken as string;
+
+      try {
+        // Extract 2FA claims from current session
+        let authMethods: string[] = [];
+        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: any = {
+          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: Response;
+        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 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: any;
+        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 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 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: Record<string, string> = {
+            '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:        ${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 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: tokenLogId(sessionToken),
+                hadRefreshToken: !!currentSession.idpRefreshToken,
+                stack: new Error().stack
+              });
+              await 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 (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+                return NextResponse.json({
+                  refreshed: true,
+                  reason: 'completed_by_concurrent_request',
+                  accessTokenExpires: postRefresh.idpAccessTokenExpires,
+                  hasRefreshToken: !!postRefresh.idpRefreshToken,
+                });
+              }
+            }
+          }
+
+          return 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 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),
+          });
+
+          if (discardToken) {
+            console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP success:false with discard_token', {
+              reason: 'IDP_SUCCESS_FALSE_DISCARD',
+              errorCode,
+              userId,
+              sessionToken: tokenLogId(sessionToken),
+              hadRefreshToken: !!currentSession.idpRefreshToken,
+              stack: new Error().stack
+            });
+            await updateSession(sessionToken, {
+              idpRefreshToken: '',
+              idpRefreshTokenExpires: undefined,
+              refreshTokenClearedAt: Date.now(),
+              refreshTokenClearedReason: `IDP_SUCCESS_FALSE_DISCARD:${errorCode}`
+            });
+          }
+
+          return NextResponse.json({
+            error: idpError.message || 'Token refresh failed',
+            code: errorCode,
+            discardToken,
+            retryable,
+            resolution: idpError.resolution || null
+          }, { status: refreshResponse.status || 400 });
+        }
+
+        // Extract tokens from response
+        const payload = responseData.data as any;
+        const accessToken = payload?.access_token;
+        const refreshToken = payload?.refresh_token;
+
+        if (!accessToken) {
+          console.error('[AUTH_REFRESH] Missing access token in IDP response');
+          return NextResponse.json({
+            error: 'Invalid token response from IDP',
+            code: 'INTERNAL_SERVER_ERROR'
+          }, { status: 500 });
+        }
+
+        // Decode and compute token expiries
+        let decodedAccessToken: any;
+        let accessTokenExpires: number;
+        let computedRefreshTokenExpires: number | undefined;
+        try {
+          const result = 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 NextResponse.json({
+            error: 'Failed to decode JWT tokens',
+            code: 'INTERNAL_SERVER_ERROR'
+          }, { status: 500 });
+        }
+
+        // Extract 2FA claims from the new access token
+        let amrClaims: string[] = [];
+        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 = currentSession.authenticationMethods || [];
+          }
+        } else {
+          amrClaims = currentSession.authenticationMethods || [];
+        }
+        const acrLevel = String(decodedAccessToken.acr || currentSession.authenticationLevel || '1');
+
+        // Extract MFA timing claims
+        const mfaTime = decodedAccessToken.mfa_time ? parseInt(decodedAccessToken.mfa_time) * 1000 : currentSession.mfaCompletedAt;
+        const mfaExpires = decodedAccessToken.mfa_expires ? parseInt(decodedAccessToken.mfa_expires) * 1000 : currentSession.mfaExpiresAt;
+        const mfaValidityHours = decodedAccessToken.mfa_validity_hours ? parseInt(decodedAccessToken.mfa_validity_hours) : currentSession.mfaValidityHours;
+
+        // Update session with new tokens
+        const hasNewRefresh = typeof refreshToken === 'string' && refreshToken.length > 0;
+        const newRefreshTokenExpires = hasNewRefresh ? computedRefreshTokenExpires : undefined;
+
+        // CRITICAL: Log if we're about to clear the refresh token due to missing new token
+        if (!hasNewRefresh && currentSession.idpRefreshToken) {
+          console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: No new refresh token in IDP response', {
+            reason: 'NO_NEW_REFRESH_TOKEN_IN_RESPONSE',
+            userId,
+            sessionToken: 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 = 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: any = {
+          ...currentSession,
+          idpAccessToken: accessToken,
+          idpAccessTokenExpires: accessTokenExpires,
+          idpRefreshToken: hasNewRefresh ? (refreshToken as string) : currentSession.idpRefreshToken,
+          idpRefreshTokenExpires: hasNewRefresh ? newRefreshTokenExpires : currentSession.idpRefreshTokenExpires,
+          decodedAccessToken: decodedAccessToken,
+          // Bearer key ID from JWT header (may change on key rotation)
+          bearerKeyId: newBearerKeyId || currentSession.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 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 NextResponse.json({
+          error: 'Token refresh error',
+          code: 'INTERNAL_SERVER_ERROR'
+        }, { status: 500 });
+      } finally {
+        if (weAcquiredLock) {
+          await releaseRefreshLock(sessionToken, requestId, releaseLockVersion);
+        }
+      }
+
+      // Load the latest session to return basic status
+      const latest = await getSession(sessionToken);
+      if (!latest?.idpAccessToken) {
+        return NextResponse.json({
+          error: 'No access token after refresh',
+          code: 'INTERNAL_SERVER_ERROR'
+        }, { status: 500 });
+      }
+
+      return NextResponse.json({
+        refreshed: true,
+        accessTokenExpires: latest.idpAccessTokenExpires,
+        hasRefreshToken: !!latest.idpRefreshToken,
+      });
+    } catch (err: any) {
+      console.error('[AUTH_REFRESH] Unexpected error', { error: err?.message || String(err) });
+      return NextResponse.json({
+        error: 'Unexpected error during refresh',
+        code: 'INTERNAL_SERVER_ERROR'
+      }, { status: 500 });
+    }
+  };
+}
+
+/**
+ * Default POST export — drop-in for `app/api/auth/refresh/route.ts`.
+ * Requires environment variables: IDP_URL, CLIENT_ID
+ */
+export const POST = createRefreshHandler({
+  idpBaseUrl: process.env.IDP_URL!,
+  clientId: process.env.CLIENT_ID || 'payez_default_client',
+  refreshEndpoint: '/api/ExternalAuth/refresh'
+});