@payez/next-mvp 4.1.11 → 4.1.20

package/src/lib/token-lifecycle.ts

@@ -1,497 +1,533 @@
-/**
- * Token Lifecycle Management for @payez/next-mvp
- *
- * Ensures tokens are fresh before making API calls.
- * Checks expiration and triggers refresh if needed.
- *
- * Pattern: Check first, refresh if needed, fail gracefully if refresh fails.
- *
- * HANDLES CONCURRENT REFRESH: When multiple API calls arrive simultaneously
- * with expired tokens, only one will actually perform the refresh. Others
- * receive 409 (conflict) and wait for the refresh to complete, then use
- * the freshly refreshed tokens.
- *
- * REQUIRED: Your app must expose the refresh route:
- * ```typescript
- * // app/api/auth/refresh/route.ts
- * export { POST } from '@payez/next-mvp/routes/auth/refresh';
- * ```
- *
- * @version 2.0.0
- */
-
-import { NextRequest } from 'next/server';
-import { getSession as getRedisSession, SessionData } from './session-store';
-import { getSession as getBetterAuthSession } from '../server/auth';
-import { getRedis } from './redis';
-import { getAppSlug } from './app-slug';
-
-// 5 minute threshold for "needs refresh" - matches refresh handler pattern
-const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
-
-// Concurrent refresh handling configuration
-const CONCURRENT_REFRESH_POLL_INTERVAL_MS = 200; // How often to poll session during concurrent refresh
-const CONCURRENT_REFRESH_MAX_WAIT_MS = 8000;     // Max time to wait for concurrent refresh to complete
-const REFRESH_RETRY_DELAY_MS = 500;               // Delay before retrying after failed concurrent refresh
-const KEY_PROPAGATION_DELAY_MS = 150;             // Delay after refresh to allow JWKS cache updates in downstream services
-
-export interface TokenResult {
-  success: true;
-  accessToken: string;
-  sessionData: SessionData;
-}
-
-export interface TokenError {
-  success: false;
-  error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
-  message: string;
-  terminal?: boolean;  // If true, don't retry - redirect to login
-  // WO-1 (genuine-dead refresh): the VERBATIM upstream reason from the IDP, preserved
-  // end-to-end so the consumer can surface an honest error + halt a futile re-auth loop
-  // (e.g. an unapproved user whose login mints a bearer but whose refresh terminally
-  // fails). `error` stays the stable category for existing consumers; `code`/`resolution`
-  // carry the real cause. Never soften — surface it.
-  code?: string;        // Upstream IDP error code (e.g. UNAUTHORIZED, USER_NOT_APPROVED)
-  resolution?: string;  // Upstream human-readable resolution hint, if any
-}
-
-export type EnsureFreshTokenResult = TokenResult | TokenError;
-
-/**
- * Check if token needs refresh based on expiration time
- */
-function needsRefresh(accessTokenExpires: number | undefined): boolean {
-  if (!accessTokenExpires) return true;
-  const timeUntilExpiry = accessTokenExpires - Date.now();
-  return timeUntilExpiry <= REFRESH_THRESHOLD_MS;
-}
-
-/**
- * Helper to delay execution
- */
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-/**
- * Wait for a concurrent refresh to complete by polling the session.
- * Returns true if session becomes fresh, false if timeout reached.
- */
-async function waitForConcurrentRefresh(
-  sessionToken: string,
-  maxWaitMs: number = CONCURRENT_REFRESH_MAX_WAIT_MS
-): Promise<{ success: boolean; sessionData?: SessionData }> {
-  const startTime = Date.now();
-
-  while (Date.now() - startTime < maxWaitMs) {
-    await delay(CONCURRENT_REFRESH_POLL_INTERVAL_MS);
-
-    const sessionData = await getRedisSession(sessionToken);
-
-    if (!sessionData) {
-      return { success: false };
-    }
-
-    // Check if token is now fresh
-    if (!needsRefresh(sessionData.idpAccessTokenExpires)) {
-      return { success: true, sessionData };
-    }
-
-    // Check if session has a new access token (even if still within threshold)
-    if (sessionData.idpAccessToken && sessionData.idpAccessTokenExpires &&
-        sessionData.idpAccessTokenExpires > Date.now()) {
-      return { success: true, sessionData };
-    }
-  }
-
-  return { success: false };
-}
-
-/**
- * Get the internal API URL for making internal service calls.
- * INTERNAL_API_URL is REQUIRED - no fallbacks.
- */
-function getInternalApiUrl(request: NextRequest): string {
-  const internalUrl = process.env.INTERNAL_API_URL;
-  if (!internalUrl) {
-    throw new Error(
-      '[INTERNAL_API_URL] FATAL: INTERNAL_API_URL environment variable is REQUIRED. ' +
-      'Set it to this app\'s internal K8s service URL (e.g., http://myapp.namespace.svc.cluster.local:80) ' +
-      'or http://localhost:3000 for local development.'
-    );
-  }
-  return internalUrl;
-}
-
-/**
- * Result of triggerRefresh - includes terminal flag for unrecoverable errors
- */
-interface RefreshResult {
-  success: boolean;
-  terminal?: boolean;  // If true, session is dead - don't retry, redirect to login
-  code?: string;       // Error code from refresh endpoint
-  message?: string;    // WO-1: verbatim human message from the refresh endpoint
-  resolution?: string; // WO-1: verbatim resolution hint from the refresh endpoint
-}
-
-/**
- * Trigger a token refresh via the refresh API endpoint.
- *
- * HANDLES CONCURRENT REFRESH (409):
- * When another request is already refreshing the token, this function
- * waits for that refresh to complete instead of failing immediately.
- * This prevents race conditions where multiple parallel API calls
- * could cause unnecessary refresh failures.
- *
- * TERMINAL STATES:
- * Returns { success: false, terminal: true } when the session cannot be
- * recovered (e.g., no refresh token). Callers should redirect to login.
- */
-async function triggerRefresh(
-  request: NextRequest,
-  sessionToken: string,
-  retryCount: number = 0
-): Promise<RefreshResult> {
-  const maxRetries = 2;
-
-  try {
-    const baseUrl = getInternalApiUrl(request);
-    const requestId = `refresh_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-
-    const response = await fetch(`${baseUrl}/api/auth/refresh`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Cookie': request.headers.get('cookie') || '',
-        'X-Session-Token': sessionToken,
-        'X-Request-Id': requestId,
-      },
-    });
-
-    // Handle 409 Conflict - another refresh is in progress
-    if (response.status === 409) {
-      // Wait for the concurrent refresh to complete
-      const waitResult = await waitForConcurrentRefresh(sessionToken);
-
-      if (waitResult.success) {
-        return { success: true };
-      }
-
-      // Concurrent refresh didn't produce a fresh token - try again if we have retries left
-      if (retryCount < maxRetries) {
-        await delay(REFRESH_RETRY_DELAY_MS);
-        return triggerRefresh(request, sessionToken, retryCount + 1);
-      }
-
-      return { success: false };
-    }
-
-    // Handle other non-OK responses
-    if (!response.ok) {
-      // Parse response body to check for terminal errors
-      let responseData: any = {};
-      try {
-        responseData = await response.json();
-      } catch {
-        // Ignore parse errors
-      }
-
-      // Log the failure for debugging
-      console.warn('[TOKEN_LIFECYCLE] Refresh request failed:', {
-        status: response.status,
-        statusText: response.statusText,
-        baseUrl,
-        retryCount,
-        code: responseData.code,
-        terminal: responseData.terminal
-      });
-
-      // CHECK FOR TERMINAL STATE: No refresh token = session is dead
-      // Don't retry - user must re-authenticate
-      if (responseData.code === 'NO_REFRESH_TOKEN' || responseData.terminal === true) {
-        console.error('[TOKEN_LIFECYCLE] TERMINAL: Session has no refresh token - user must re-login');
-        // WO-1: preserve the verbatim upstream reason. refresh.ts puts the human
-        // message in `error` and the code in `code`; carry both up so the consumer
-        // can tell the user WHY (not just "session expired") and stop a futile loop.
-        return {
-          success: false,
-          terminal: true,
-          code: responseData.code,
-          message: responseData.error,
-          resolution: responseData.resolution,
-        };
-      }
-
-      // For other 401s, check if maybe session was refreshed by another request
-      if (response.status === 401 && retryCount < maxRetries) {
-        await delay(REFRESH_RETRY_DELAY_MS);
-
-        const sessionData = await getRedisSession(sessionToken);
-        if (sessionData && !needsRefresh(sessionData.idpAccessTokenExpires)) {
-          return { success: true };
-        }
-      }
-
-      return { success: false, code: responseData.code };
-    }
-
-    const result = await response.json();
-    const success = result.refreshed === true || result.reason === 'already_fresh';
-    return { success };
-  } catch (error) {
-    // Log network errors for debugging
-    console.error('[TOKEN_LIFECYCLE] Refresh network error:', {
-      error: error instanceof Error ? error.message : String(error),
-      retryCount
-    });
-
-    // On network error, check if maybe another request refreshed the token
-    if (retryCount < maxRetries) {
-      await delay(REFRESH_RETRY_DELAY_MS);
-      const sessionData = await getRedisSession(sessionToken);
-      if (sessionData && !needsRefresh(sessionData.idpAccessTokenExpires)) {
-        return { success: true };
-      }
-    }
-
-    return { success: false };
-  }
-}
-
-/**
- * Ensures we have a fresh access token before making API calls.
- *
- * This utility checks token expiration and triggers a refresh if needed,
- * preventing 401 errors from expired tokens being sent to downstream APIs.
- *
- * @param request - The incoming NextRequest
- * @returns TokenResult with accessToken and sessionData, or TokenError
- *
- * @example
- * ```typescript
- * import { ensureFreshToken } from '@payez/next-mvp/lib/token-lifecycle';
- *
- * export async function GET(request: NextRequest) {
- *   const tokenResult = await ensureFreshToken(request);
- *   if (!tokenResult.success) {
- *     return NextResponse.json({ error: tokenResult.error }, { status: 401 });
- *   }
- *
- *   // Use tokenResult.accessToken for downstream API calls
- *   const response = await fetch('https://api.example.com/data', {
- *     headers: { 'Authorization': `Bearer ${tokenResult.accessToken}` }
- *   });
- * }
- * ```
- */
-export async function ensureFreshToken(
-  request: NextRequest
-): Promise<EnsureFreshTokenResult> {
-  try {
-    // 1. Get Better Auth session to extract sessionToken
-    const betterAuthSession = await getBetterAuthSession(request);
-
-    if (!betterAuthSession?.session?.token) {
-      console.warn('[TOKEN_LIFECYCLE] NO_SESSION - Better Auth session not found');
-      return {
-        success: false,
-        error: 'NO_SESSION',
-        message: 'No session available',
-      };
-    }
-
-    const sessionToken = betterAuthSession.session.token;
-
-    // 2. Get session data from Redis (legacy prefix), or Better Auth's secondary storage
-    let sessionData = await getRedisSession(sessionToken);
-
-    if (!sessionData) {
-      // Try Better Auth's secondaryStorage key (ba:{slug}:{token})
-      try {
-        const baKey = `ba:${getAppSlug()}:${sessionToken}`;
-        const baRaw = await getRedis().get(baKey);
-        if (baRaw) {
-          const baSession = JSON.parse(baRaw);
-          const idpTokens = baSession.idpTokens;
-
-          sessionData = {
-            userId: idpTokens?.userId || baSession.user?.id || betterAuthSession.user?.id || '',
-            email: idpTokens?.email || baSession.user?.email || betterAuthSession.user?.email || '',
-            name: idpTokens?.name || baSession.user?.name || betterAuthSession.user?.name,
-            roles: idpTokens?.roles || [],
-            idpAccessToken: idpTokens?.idpAccessToken,
-            idpRefreshToken: idpTokens?.idpRefreshToken,
-            idpAccessTokenExpires: idpTokens?.idpAccessTokenExpires
-              || (baSession.session?.expiresAt ? new Date(baSession.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
-            mfaVerified: true,
-            oauthProvider: 'google',
-            idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId ?? baSession.idpClientId,
-            merchantId: idpTokens?.merchantId ?? baSession.merchantId,
-          } as SessionData;
-        }
-      } catch { /* Redis unavailable */ }
-    }
-
-    if (!sessionData && betterAuthSession.user) {
-      // Last resort: build from Better Auth in-memory session (no IDP tokens)
-      sessionData = {
-        userId: betterAuthSession.user.id || '',
-        email: betterAuthSession.user.email || '',
-        name: betterAuthSession.user.name,
-        roles: [],
-        idpAccessTokenExpires: Date.now() + 24 * 60 * 60 * 1000,
-        mfaVerified: true,
-        oauthProvider: 'google',
-      } as SessionData;
-    }
-
-    if (!sessionData) {
-      return {
-        success: false,
-        error: 'NO_SESSION',
-        message: 'Session expired or not found',
-      };
-    }
-
-    // DEBUG: Log session data before refresh check
-    const tokenExpiresStr = sessionData.idpAccessTokenExpires
-      ? new Date(sessionData.idpAccessTokenExpires).toISOString()
-      : 'undefined';
-    let needsRefreshNow = needsRefresh(sessionData.idpAccessTokenExpires);
-
-    // VALIDATION: Check if the actual JWT token's exp matches what Redis claims
-    // This catches cases where accessTokenExpires was updated but accessToken wasn't
-    let tokenMismatch = false;
-    if (sessionData.idpAccessToken && !needsRefreshNow) {
-      try {
-        const tokenParts = sessionData.idpAccessToken.split('.');
-        if (tokenParts.length === 3) {
-          const payload = JSON.parse(Buffer.from(tokenParts[1], 'base64url').toString());
-          const jwtExpMs = (payload.exp || 0) * 1000;
-          const now = Date.now();
-
-          // If the JWT is actually expired, force a refresh regardless of what Redis says
-          if (jwtExpMs < now) {
-            console.warn('[TOKEN_LIFECYCLE] Token mismatch detected! JWT expired but Redis claims valid', {
-              jwtExp: new Date(jwtExpMs).toISOString(),
-              redisAccessTokenExpires: tokenExpiresStr,
-              now: new Date(now).toISOString(),
-              mismatchMs: sessionData.idpAccessTokenExpires ? sessionData.idpAccessTokenExpires - jwtExpMs : 'N/A'
-            });
-            needsRefreshNow = true;
-            tokenMismatch = true;
-          }
-        }
-      } catch (e) {
-        // If we can't decode, proceed with normal logic
-        console.warn('[TOKEN_LIFECYCLE] Could not validate JWT exp claim:', e);
-      }
-    }
-
-    console.log('[TOKEN_LIFECYCLE] ensureFreshToken check:', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
-      accessTokenExpires: tokenExpiresStr,
-      now: new Date().toISOString(),
-      needsRefresh: needsRefreshNow,
-      tokenMismatch,
-      hasRefreshToken: !!sessionData.idpRefreshToken
-    });
-
-    // 3. Check if token needs refresh
-    if (needsRefreshNow) {
-      // 4. Trigger refresh
-      console.log('[TOKEN_LIFECYCLE] Triggering refresh...');
-      const refreshResult = await triggerRefresh(request, sessionToken);
-
-      if (!refreshResult.success) {
-        // Check for terminal state - session cannot be recovered
-        if (refreshResult.terminal) {
-          console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired - redirect to login', {
-            code: refreshResult.code,
-            message: refreshResult.message,
-          });
-          // WO-1: keep `error` as the stable terminal category (existing consumers
-          // branch on SESSION_EXPIRED_NO_REFRESH) but surface the verbatim upstream
-          // reason via code/message/resolution so the user learns WHY and a genuinely
-          // dead session (e.g. unapproved account) doesn't loop login→bounce→login.
-          return {
-            success: false,
-            error: 'SESSION_EXPIRED_NO_REFRESH',
-            message: refreshResult.message || 'Session expired. Please sign in again.',
-            terminal: true,
-            code: refreshResult.code,
-            resolution: refreshResult.resolution,
-          };
-        }
-
-        console.warn('[TOKEN_LIFECYCLE] Refresh failed');
-        return {
-          success: false,
-          error: 'REFRESH_FAILED',
-          message: 'Token refresh failed',
-        };
-      }
-
-      // 5. Re-fetch session data after refresh
-      sessionData = await getRedisSession(sessionToken);
-      console.log('[TOKEN_LIFECYCLE] After refresh:', {
-        hasAccessToken: !!sessionData?.idpAccessToken,
-        newAccessTokenExpires: sessionData?.idpAccessTokenExpires
-          ? new Date(sessionData.idpAccessTokenExpires).toISOString()
-          : 'undefined'
-      });
-
-      if (!sessionData?.idpAccessToken) {
-        return {
-          success: false,
-          error: 'REFRESH_FAILED',
-          message: 'No access token after refresh',
-        };
-      }
-
-      // 5.5. Key propagation delay - allow downstream services (like Vibe) to cache new JWKS
-      // This is critical when IDP rotates signing keys - the new token's kid may not be
-      // immediately available in Vibe's JWKS cache
-      await delay(KEY_PROPAGATION_DELAY_MS);
-    }
-
-    // 6. Return session — accessToken may be empty for social-only OAuth sessions
-    return {
-      success: true,
-      accessToken: sessionData.idpAccessToken || '',
-      sessionData,
-    };
-  } catch (error) {
-    console.error('[TOKEN_LIFECYCLE] Error:', error);
-    return {
-      success: false,
-      error: 'NO_SESSION',
-      message: error instanceof Error ? error.message : 'Unknown error',
-    };
-  }
-}
-
-/**
- * Get authorization header from fresh token.
- * Convenience wrapper for API routes.
- *
- * @param request - The incoming NextRequest
- * @returns Authorization header string or null if token unavailable
- *
- * @example
- * ```typescript
- * const authHeader = await getFreshAuthHeader(request);
- * if (!authHeader) {
- *   return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
- * }
- * ```
- */
-export async function getFreshAuthHeader(
-  request: NextRequest
-): Promise<string | null> {
-  const result = await ensureFreshToken(request);
-  if (!result.success) {
-    return null;
-  }
-  return `Bearer ${result.accessToken}`;
-}
+/**
+ * Token Lifecycle Management for @payez/next-mvp
+ *
+ * Ensures tokens are fresh before making API calls.
+ * Checks expiration and triggers refresh if needed.
+ *
+ * Pattern: Check first, refresh if needed, fail gracefully if refresh fails.
+ *
+ * HANDLES CONCURRENT REFRESH: When multiple API calls arrive simultaneously
+ * with expired tokens, only one will actually perform the refresh. Others
+ * receive 409 (conflict) and wait for the refresh to complete, then use
+ * the freshly refreshed tokens.
+ *
+ * REQUIRED: Your app must expose the refresh route:
+ * ```typescript
+ * // app/api/auth/refresh/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/refresh';
+ * ```
+ *
+ * @version 2.0.0
+ */
+
+import { NextRequest } from 'next/server';
+import { getSession as getRedisSession, SessionData } from './session-store';
+import { getSession as getBetterAuthSession } from '../server/auth';
+import { getRedis } from './redis';
+import { getAppSlug } from './app-slug';
+
+// 5 minute threshold for "needs refresh" - matches refresh handler pattern
+const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
+
+// Concurrent refresh handling configuration
+const CONCURRENT_REFRESH_POLL_INTERVAL_MS = 200; // How often to poll session during concurrent refresh
+const CONCURRENT_REFRESH_MAX_WAIT_MS = 8000;     // Max time to wait for concurrent refresh to complete
+const REFRESH_RETRY_DELAY_MS = 500;               // Delay before retrying after failed concurrent refresh
+const KEY_PROPAGATION_DELAY_MS = 150;             // Delay after refresh to allow JWKS cache updates in downstream services
+
+export interface TokenResult {
+  success: true;
+  accessToken: string;
+  sessionData: SessionData;
+}
+
+export interface TokenError {
+  success: false;
+  error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
+  message: string;
+  terminal?: boolean;  // If true, don't retry - redirect to login
+  // WO-1 (genuine-dead refresh): the VERBATIM upstream reason from the IDP, preserved
+  // end-to-end so the consumer can surface an honest error + halt a futile re-auth loop
+  // (e.g. an unapproved user whose login mints a bearer but whose refresh terminally
+  // fails). `error` stays the stable category for existing consumers; `code`/`resolution`
+  // carry the real cause. Never soften — surface it.
+  code?: string;        // Upstream IDP error code (e.g. UNAUTHORIZED, USER_NOT_APPROVED)
+  resolution?: string;  // Upstream human-readable resolution hint, if any
+}
+
+export type EnsureFreshTokenResult = TokenResult | TokenError;
+
+/**
+ * Check if token needs refresh based on expiration time
+ */
+function needsRefresh(accessTokenExpires: number | undefined): boolean {
+  if (!accessTokenExpires) return true;
+  const timeUntilExpiry = accessTokenExpires - Date.now();
+  return timeUntilExpiry <= REFRESH_THRESHOLD_MS;
+}
+
+/**
+ * Helper to delay execution
+ */
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Wait for a concurrent refresh to complete by polling the session.
+ * Returns true if session becomes fresh, false if timeout reached.
+ */
+async function waitForConcurrentRefresh(
+  sessionToken: string,
+  maxWaitMs: number = CONCURRENT_REFRESH_MAX_WAIT_MS
+): Promise<{ success: boolean; sessionData?: SessionData }> {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < maxWaitMs) {
+    await delay(CONCURRENT_REFRESH_POLL_INTERVAL_MS);
+
+    const sessionData = await getRedisSession(sessionToken);
+
+    if (!sessionData) {
+      return { success: false };
+    }
+
+    // Check if token is now fresh
+    if (!needsRefresh(sessionData.idpAccessTokenExpires)) {
+      return { success: true, sessionData };
+    }
+
+    // Check if session has a new access token (even if still within threshold)
+    if (sessionData.idpAccessToken && sessionData.idpAccessTokenExpires &&
+        sessionData.idpAccessTokenExpires > Date.now()) {
+      return { success: true, sessionData };
+    }
+  }
+
+  return { success: false };
+}
+
+/**
+ * Get the internal API URL for making internal service calls.
+ * INTERNAL_API_URL is REQUIRED - no fallbacks.
+ */
+function getInternalApiUrl(request: NextRequest): string {
+  const internalUrl = process.env.INTERNAL_API_URL;
+  if (!internalUrl) {
+    throw new Error(
+      '[INTERNAL_API_URL] FATAL: INTERNAL_API_URL environment variable is REQUIRED. ' +
+      'Set it to this app\'s internal K8s service URL (e.g., http://myapp.namespace.svc.cluster.local:80) ' +
+      'or http://localhost:3000 for local development.'
+    );
+  }
+  return internalUrl;
+}
+
+/**
+ * Result of triggerRefresh - includes terminal flag for unrecoverable errors
+ */
+interface RefreshResult {
+  success: boolean;
+  terminal?: boolean;  // If true, session is dead - don't retry, redirect to login
+  code?: string;       // Error code from refresh endpoint
+  message?: string;    // WO-1: verbatim human message from the refresh endpoint
+  resolution?: string; // WO-1: verbatim resolution hint from the refresh endpoint
+}
+
+/**
+ * Trigger a token refresh via the refresh API endpoint.
+ *
+ * HANDLES CONCURRENT REFRESH (409):
+ * When another request is already refreshing the token, this function
+ * waits for that refresh to complete instead of failing immediately.
+ * This prevents race conditions where multiple parallel API calls
+ * could cause unnecessary refresh failures.
+ *
+ * TERMINAL STATES:
+ * Returns { success: false, terminal: true } when the session cannot be
+ * recovered (e.g., no refresh token). Callers should redirect to login.
+ */
+async function triggerRefresh(
+  request: NextRequest,
+  sessionToken: string,
+  retryCount: number = 0
+): Promise<RefreshResult> {
+  const maxRetries = 2;
+
+  try {
+    const baseUrl = getInternalApiUrl(request);
+    const requestId = `refresh_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    const response = await fetch(`${baseUrl}/api/auth/refresh`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Cookie': request.headers.get('cookie') || '',
+        'X-Session-Token': sessionToken,
+        'X-Request-Id': requestId,
+      },
+    });
+
+    // Handle 409 Conflict - another refresh is in progress
+    if (response.status === 409) {
+      // Wait for the concurrent refresh to complete
+      const waitResult = await waitForConcurrentRefresh(sessionToken);
+
+      if (waitResult.success) {
+        return { success: true };
+      }
+
+      // Concurrent refresh didn't produce a fresh token - try again if we have retries left
+      if (retryCount < maxRetries) {
+        await delay(REFRESH_RETRY_DELAY_MS);
+        return triggerRefresh(request, sessionToken, retryCount + 1);
+      }
+
+      return { success: false };
+    }
+
+    // Handle other non-OK responses
+    if (!response.ok) {
+      // Parse response body to check for terminal errors
+      let responseData: any = {};
+      try {
+        responseData = await response.json();
+      } catch {
+        // Ignore parse errors
+      }
+
+      // Log the failure for debugging
+      console.warn('[TOKEN_LIFECYCLE] Refresh request failed:', {
+        status: response.status,
+        statusText: response.statusText,
+        baseUrl,
+        retryCount,
+        code: responseData.code,
+        terminal: responseData.terminal
+      });
+
+      // CHECK FOR TERMINAL STATE: No refresh token = session is dead
+      // Don't retry - user must re-authenticate
+      if (responseData.code === 'NO_REFRESH_TOKEN' || responseData.terminal === true) {
+        console.error('[TOKEN_LIFECYCLE] TERMINAL: Session has no refresh token - user must re-login');
+        // WO-1: preserve the verbatim upstream reason. refresh.ts puts the human
+        // message in `error` and the code in `code`; carry both up so the consumer
+        // can tell the user WHY (not just "session expired") and stop a futile loop.
+        return {
+          success: false,
+          terminal: true,
+          code: responseData.code,
+          message: responseData.error,
+          resolution: responseData.resolution,
+        };
+      }
+
+      // For other 401s, check if maybe session was refreshed by another request
+      if (response.status === 401 && retryCount < maxRetries) {
+        await delay(REFRESH_RETRY_DELAY_MS);
+
+        const sessionData = await getRedisSession(sessionToken);
+        if (sessionData && !needsRefresh(sessionData.idpAccessTokenExpires)) {
+          return { success: true };
+        }
+      }
+
+      return { success: false, code: responseData.code };
+    }
+
+    const result = await response.json();
+    const success = result.refreshed === true || result.reason === 'already_fresh';
+    return { success };
+  } catch (error) {
+    // Log network errors for debugging
+    console.error('[TOKEN_LIFECYCLE] Refresh network error:', {
+      error: error instanceof Error ? error.message : String(error),
+      retryCount
+    });
+
+    // On network error, check if maybe another request refreshed the token
+    if (retryCount < maxRetries) {
+      await delay(REFRESH_RETRY_DELAY_MS);
+      const sessionData = await getRedisSession(sessionToken);
+      if (sessionData && !needsRefresh(sessionData.idpAccessTokenExpires)) {
+        return { success: true };
+      }
+    }
+
+    return { success: false };
+  }
+}
+
+/**
+ * Ensures we have a fresh access token before making API calls.
+ *
+ * This utility checks token expiration and triggers a refresh if needed,
+ * preventing 401 errors from expired tokens being sent to downstream APIs.
+ *
+ * @param request - The incoming NextRequest
+ * @returns TokenResult with accessToken and sessionData, or TokenError
+ *
+ * @example
+ * ```typescript
+ * import { ensureFreshToken } from '@payez/next-mvp/lib/token-lifecycle';
+ *
+ * export async function GET(request: NextRequest) {
+ *   const tokenResult = await ensureFreshToken(request);
+ *   if (!tokenResult.success) {
+ *     return NextResponse.json({ error: tokenResult.error }, { status: 401 });
+ *   }
+ *
+ *   // Use tokenResult.accessToken for downstream API calls
+ *   const response = await fetch('https://api.example.com/data', {
+ *     headers: { 'Authorization': `Bearer ${tokenResult.accessToken}` }
+ *   });
+ * }
+ * ```
+ */
+export async function ensureFreshToken(
+  request: NextRequest
+): Promise<EnsureFreshTokenResult> {
+  try {
+    // 1. Get Better Auth session to extract sessionToken
+    const betterAuthSession = await getBetterAuthSession(request);
+
+    if (!betterAuthSession?.session?.token) {
+      console.warn('[TOKEN_LIFECYCLE] NO_SESSION - Better Auth session not found');
+      return {
+        success: false,
+        error: 'NO_SESSION',
+        message: 'No session available',
+      };
+    }
+
+    const sessionToken = betterAuthSession.session.token;
+
+    // 2. Get session data from Redis (legacy prefix), or Better Auth's secondary storage
+    let sessionData = await getRedisSession(sessionToken);
+
+    if (!sessionData) {
+      // Try Better Auth's secondaryStorage key (ba:{slug}:{token})
+      try {
+        const baKey = `ba:${getAppSlug()}:${sessionToken}`;
+        const baRaw = await getRedis().get(baKey);
+        if (baRaw) {
+          const baSession = JSON.parse(baRaw);
+          const idpTokens = baSession.idpTokens;
+
+          sessionData = {
+            userId: idpTokens?.userId || baSession.user?.id || betterAuthSession.user?.id || '',
+            email: idpTokens?.email || baSession.user?.email || betterAuthSession.user?.email || '',
+            name: idpTokens?.name || baSession.user?.name || betterAuthSession.user?.name,
+            roles: idpTokens?.roles || [],
+            idpAccessToken: idpTokens?.idpAccessToken,
+            idpRefreshToken: idpTokens?.idpRefreshToken,
+            idpAccessTokenExpires: idpTokens?.idpAccessTokenExpires
+              || (baSession.session?.expiresAt ? new Date(baSession.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
+            /**
+             * ⚠ THESE WERE HARDCODED `true` / `'google'`. (QAPert finding #3,
+             * BAPert ruling, card 167892.)
+             *
+             * This rebuild path assumed EVERY session is a Google OAuth sign-in
+             * that completed MFA. It reads `idpTokens` for everything else —
+             * including roles, two lines up — and then IGNORED the stored
+             * mfaVerified sitting in that same object and asserted `true`.
+             *
+             * WHY IT MATTERS MORE THAN A WRONG FIELD: a passkey sign-in stores
+             * an HONEST mfaVerified derived from the token's `amr`. On any
+             * Redis miss this path OVERWROTE that false with true — so the
+             * session claimed an MFA the user never performed, and the honest
+             * derivation upstream was not weakened but VOIDED. Same defect
+             * class as the mints that assert completion they never did,
+             * arriving through a cache-miss rather than a mint.
+             *
+             * `oauthProvider: 'google'` was the second lie on the same line:
+             * a passkey session rebuilt here was relabelled a Google sign-in,
+             * destroying the provenance the sign-in path deliberately records.
+             * The IDP emits NO provider claim (DotNetPert), so the honest
+             * answer when it was not stored is UNSET — not a guess.
+             *
+             * Both now default to the SAFE direction: absent/false is
+             * fail-closed at every consumer we measured (`!!mfaVerified`,
+             * `mfaVerified || ... || false`).
+             */
+            mfaVerified: idpTokens?.mfaVerified ?? false,
+            oauthProvider: idpTokens?.oauthProvider ?? baSession.oauthProvider ?? undefined,
+            idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId ?? baSession.idpClientId,
+            merchantId: idpTokens?.merchantId ?? baSession.merchantId,
+          } as SessionData;
+        }
+      } catch { /* Redis unavailable */ }
+    }
+
+    if (!sessionData && betterAuthSession.user) {
+      // Last resort: build from Better Auth in-memory session (no IDP tokens)
+      sessionData = {
+        userId: betterAuthSession.user.id || '',
+        email: betterAuthSession.user.email || '',
+        name: betterAuthSession.user.name,
+        roles: [],
+        idpAccessTokenExpires: Date.now() + 24 * 60 * 60 * 1000,
+        /**
+         * ⚠ ALSO HARDCODED `true` / `'google'`, and this path is the worse of
+         * the two: it runs with NO IDP TOKENS AT ALL — the comment above says
+         * so — and still asserted that MFA was completed. It fabricated an
+         * assurance claim from nothing, for every consumer, not just passkey.
+         *
+         * With nothing to derive from, FALSE is the only honest value and
+         * UNSET is the only honest provider. Both are fail-closed.
+         */
+        mfaVerified: false,
+        oauthProvider: undefined,
+      } as SessionData;
+    }
+
+    if (!sessionData) {
+      return {
+        success: false,
+        error: 'NO_SESSION',
+        message: 'Session expired or not found',
+      };
+    }
+
+    // DEBUG: Log session data before refresh check
+    const tokenExpiresStr = sessionData.idpAccessTokenExpires
+      ? new Date(sessionData.idpAccessTokenExpires).toISOString()
+      : 'undefined';
+    let needsRefreshNow = needsRefresh(sessionData.idpAccessTokenExpires);
+
+    // VALIDATION: Check if the actual JWT token's exp matches what Redis claims
+    // This catches cases where accessTokenExpires was updated but accessToken wasn't
+    let tokenMismatch = false;
+    if (sessionData.idpAccessToken && !needsRefreshNow) {
+      try {
+        const tokenParts = sessionData.idpAccessToken.split('.');
+        if (tokenParts.length === 3) {
+          const payload = JSON.parse(Buffer.from(tokenParts[1], 'base64url').toString());
+          const jwtExpMs = (payload.exp || 0) * 1000;
+          const now = Date.now();
+
+          // If the JWT is actually expired, force a refresh regardless of what Redis says
+          if (jwtExpMs < now) {
+            console.warn('[TOKEN_LIFECYCLE] Token mismatch detected! JWT expired but Redis claims valid', {
+              jwtExp: new Date(jwtExpMs).toISOString(),
+              redisAccessTokenExpires: tokenExpiresStr,
+              now: new Date(now).toISOString(),
+              mismatchMs: sessionData.idpAccessTokenExpires ? sessionData.idpAccessTokenExpires - jwtExpMs : 'N/A'
+            });
+            needsRefreshNow = true;
+            tokenMismatch = true;
+          }
+        }
+      } catch (e) {
+        // If we can't decode, proceed with normal logic
+        console.warn('[TOKEN_LIFECYCLE] Could not validate JWT exp claim:', e);
+      }
+    }
+
+    console.log('[TOKEN_LIFECYCLE] ensureFreshToken check:', {
+      sessionToken: sessionToken.substring(0, 8) + '...',
+      accessTokenExpires: tokenExpiresStr,
+      now: new Date().toISOString(),
+      needsRefresh: needsRefreshNow,
+      tokenMismatch,
+      hasRefreshToken: !!sessionData.idpRefreshToken
+    });
+
+    // 3. Check if token needs refresh
+    if (needsRefreshNow) {
+      // 4. Trigger refresh
+      console.log('[TOKEN_LIFECYCLE] Triggering refresh...');
+      const refreshResult = await triggerRefresh(request, sessionToken);
+
+      if (!refreshResult.success) {
+        // Check for terminal state - session cannot be recovered
+        if (refreshResult.terminal) {
+          console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired - redirect to login', {
+            code: refreshResult.code,
+            message: refreshResult.message,
+          });
+          // WO-1: keep `error` as the stable terminal category (existing consumers
+          // branch on SESSION_EXPIRED_NO_REFRESH) but surface the verbatim upstream
+          // reason via code/message/resolution so the user learns WHY and a genuinely
+          // dead session (e.g. unapproved account) doesn't loop login→bounce→login.
+          return {
+            success: false,
+            error: 'SESSION_EXPIRED_NO_REFRESH',
+            message: refreshResult.message || 'Session expired. Please sign in again.',
+            terminal: true,
+            code: refreshResult.code,
+            resolution: refreshResult.resolution,
+          };
+        }
+
+        console.warn('[TOKEN_LIFECYCLE] Refresh failed');
+        return {
+          success: false,
+          error: 'REFRESH_FAILED',
+          message: 'Token refresh failed',
+        };
+      }
+
+      // 5. Re-fetch session data after refresh
+      sessionData = await getRedisSession(sessionToken);
+      console.log('[TOKEN_LIFECYCLE] After refresh:', {
+        hasAccessToken: !!sessionData?.idpAccessToken,
+        newAccessTokenExpires: sessionData?.idpAccessTokenExpires
+          ? new Date(sessionData.idpAccessTokenExpires).toISOString()
+          : 'undefined'
+      });
+
+      if (!sessionData?.idpAccessToken) {
+        return {
+          success: false,
+          error: 'REFRESH_FAILED',
+          message: 'No access token after refresh',
+        };
+      }
+
+      // 5.5. Key propagation delay - allow downstream services (like Vibe) to cache new JWKS
+      // This is critical when IDP rotates signing keys - the new token's kid may not be
+      // immediately available in Vibe's JWKS cache
+      await delay(KEY_PROPAGATION_DELAY_MS);
+    }
+
+    // 6. Return session — accessToken may be empty for social-only OAuth sessions
+    return {
+      success: true,
+      accessToken: sessionData.idpAccessToken || '',
+      sessionData,
+    };
+  } catch (error) {
+    console.error('[TOKEN_LIFECYCLE] Error:', error);
+    return {
+      success: false,
+      error: 'NO_SESSION',
+      message: error instanceof Error ? error.message : 'Unknown error',
+    };
+  }
+}
+
+/**
+ * Get authorization header from fresh token.
+ * Convenience wrapper for API routes.
+ *
+ * @param request - The incoming NextRequest
+ * @returns Authorization header string or null if token unavailable
+ *
+ * @example
+ * ```typescript
+ * const authHeader = await getFreshAuthHeader(request);
+ * if (!authHeader) {
+ *   return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+ * }
+ * ```
+ */
+export async function getFreshAuthHeader(
+  request: NextRequest
+): Promise<string | null> {
+  const result = await ensureFreshToken(request);
+  if (!result.success) {
+    return null;
+  }
+  return `Bearer ${result.accessToken}`;
+}