@payez/next-mvp 4.1.9 → 4.1.11

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

@@ -1,335 +1,369 @@
-/**
- * ensureFreshAccessToken — server-side preflight refresh.
- *
- * Returns a non-expired IDP access token for a given session. Refreshes
- * proactively when the stored token is within the safety window of expiry,
- * using the same Redis lock and IDP wire shape as `createRefreshHandler`.
- *
- * Designed for proxy-route auth helpers that today read the stored token
- * blindly and let the backend reject it with a 401. Calling this instead of
- * `getSession(...).idpAccessToken` means a good token client never sends
- * credentials it already knows are invalid.
- *
- * Single-use refresh-token semantics are preserved via Redis-backed
- * single-flight locking (see `acquireRefreshLock`).
- */
-import {
-  getSession,
-  getBetterAuthSession,
-  updateSession,
-  acquireRefreshLock,
-  releaseRefreshLock,
-  checkRefreshLock,
-} from './session-store';
-import { computeTokenExpiries } from './token-expiry';
-import { extractKidFromToken } from '../auth/utils/token-utils';
-
-export interface EnsureFreshConfig {
-  idpBaseUrl: string;
-  clientId: string;
-  refreshEndpoint?: string;
-}
-
-export interface EnsureFreshOptions {
-  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
-  safetyWindowMs?: number;
-  /** Max wait while another caller holds the refresh lock. Default 5000. */
-  lockWaitMs?: number;
-  /** Optional caller request id for lock attribution. */
-  requestId?: string;
-}
-
-export type EnsureFreshResult =
-  | {
-      ok: true;
-      accessToken: string;
-      accessTokenExpires: number;
-      /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
-      refreshed: boolean;
-    }
-  | {
-      ok: false;
-      code: string;
-      message: string;
-      status: number;
-      terminal?: boolean;
-      discardToken?: boolean;
-      retryable?: boolean;
-      resolution?: string;
-    };
-
-const DEFAULT_SAFETY_WINDOW_MS = 60_000;
-const DEFAULT_LOCK_WAIT_MS = 5000;
-
-function decodeJwtExp(token: string): number {
-  const parts = token.split('.');
-  if (parts.length !== 3) return -1;
-  try {
-    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
-    return (payload.exp || 0) * 1000;
-  } catch {
-    return -1;
-  }
-}
-
-export async function ensureFreshAccessToken(
-  sessionToken: string,
-  config: EnsureFreshConfig,
-  options: EnsureFreshOptions = {}
-): Promise<EnsureFreshResult> {
-  const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
-  const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
-  const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
-  const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
-
-  let session = await getSession(sessionToken);
-  if (!session || !session.idpRefreshToken) {
-    const baSession = await getBetterAuthSession(sessionToken);
-    if (baSession?.idpRefreshToken) {
-      session = baSession;
-    }
-  }
-  if (!session) {
-    return { ok: false, code: 'NO_SESSION', message: 'No session for token', status: 401, terminal: true };
-  }
-
-  const storedToken = session.idpAccessToken;
-  if (!storedToken) {
-    return { ok: false, code: 'NO_TOKEN', message: 'No IDP access token in session', status: 401, terminal: true };
-  }
-
-  const now = Date.now();
-  const redisExpires = session.idpAccessTokenExpires ?? 0;
-  const jwtExpires = decodeJwtExp(storedToken);
-  // Use the smaller of the two to be conservative — Redis can be stale, JWT exp is authoritative.
-  const effectiveExpires = jwtExpires > 0 ? Math.min(redisExpires || jwtExpires, jwtExpires) : redisExpires;
-  const msUntilExpiry = effectiveExpires - now;
-
-  if (msUntilExpiry > safetyWindowMs) {
-    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false };
-  }
-
-  if (!session.idpRefreshToken) {
-    return {
-      ok: false,
-      code: 'NO_REFRESH_TOKEN',
-      message: 'Access token expired and no refresh token available',
-      status: 401,
-      terminal: true,
-      resolution: 'User must re-authenticate',
-    };
-  }
-
-  const lock = await acquireRefreshLock(sessionToken, requestId, lockWaitMs);
-  let weHoldLock = false;
-  let releaseVersion: number | undefined;
-
-  if (!lock.acquired) {
-    const existing = await checkRefreshLock(sessionToken);
-    if (!existing || existing.acquiredBy !== requestId) {
-      const startWait = Date.now();
-      while (Date.now() - startWait < lockWaitMs) {
-        await new Promise(r => setTimeout(r, 200));
-        const stillLocked = await checkRefreshLock(sessionToken);
-        if (!stillLocked) {
-          let after = await getSession(sessionToken);
-          if (!after || !after.idpRefreshToken) {
-            const baAfter = await getBetterAuthSession(sessionToken);
-            if (baAfter?.idpRefreshToken) after = baAfter;
-          }
-          if (after?.idpAccessToken && after.idpAccessTokenExpires) {
-            const remaining = after.idpAccessTokenExpires - Date.now();
-            if (remaining > safetyWindowMs) {
-              return {
-                ok: true,
-                accessToken: after.idpAccessToken,
-                accessTokenExpires: after.idpAccessTokenExpires,
-                refreshed: true,
-              };
-            }
-          }
-          break;
-        }
-      }
-      return {
-        ok: false,
-        code: 'CONFLICT',
-        message: 'Refresh already in progress',
-        status: 409,
-        retryable: true,
-      };
-    }
-  } else {
-    weHoldLock = true;
-    releaseVersion = lock.lockInfo?.lockVersion;
-  }
-
-  try {
-    // Re-check after lock — another caller may have already refreshed.
-    let latest = await getSession(sessionToken);
-    if (!latest || !latest.idpRefreshToken) {
-      const baLatest = await getBetterAuthSession(sessionToken);
-      if (baLatest?.idpRefreshToken) latest = baLatest;
-    }
-    if (latest?.idpAccessToken && latest.idpAccessTokenExpires) {
-      const latestRemaining = latest.idpAccessTokenExpires - Date.now();
-      const latestJwtExp = decodeJwtExp(latest.idpAccessToken);
-      const stillStale = latestRemaining <= safetyWindowMs || (latestJwtExp > 0 && latestJwtExp <= Date.now());
-      if (!stillStale) {
-        return {
-          ok: true,
-          accessToken: latest.idpAccessToken,
-          accessTokenExpires: latest.idpAccessTokenExpires,
-          refreshed: true,
-        };
-      }
-    }
-
-    // Build refresh request body — wire shape must match what the IDP expects.
-    let authMethods: string[] = [];
-    if (Array.isArray(session.authenticationMethods)) {
-      authMethods = session.authenticationMethods;
-    } else if (typeof session.authenticationMethods === 'string') {
-      try { authMethods = JSON.parse(session.authenticationMethods); } catch { /* fall through */ }
-    }
-    const isOAuthSession = !!session.oauthProvider;
-    if (authMethods.length === 0 && isOAuthSession) {
-      authMethods = ['pwd', 'mfa'];
-    }
-    const twoFactorMethod =
-      authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
-      session.mfaMethod ||
-      (isOAuthSession ? 'oauth' : null);
-
-    let acrValue = String(session.authenticationLevel ?? '1');
-    if (isOAuthSession && session.mfaVerified && acrValue === '1') {
-      acrValue = '2';
-    }
-
-    const body: Record<string, unknown> = {
-      refresh_token: session.idpRefreshToken,
-      amr: authMethods,
-      acr: acrValue,
-    };
-    if (session.mfaVerified) body.two_factor_verified = true;
-    if (twoFactorMethod) body.two_factor_method = twoFactorMethod;
-    if (session.mfaCompletedAt) body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
-
-    let idpResponse: Response;
-    try {
-      idpResponse = await fetch(`${idpBaseUrl}${refreshEndpoint}`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'X-Client-Id': clientId },
-        body: JSON.stringify(body),
-      });
-    } catch (err) {
-      return {
-        ok: false,
-        code: 'UPSTREAM_SERVICE_UNAVAILABLE',
-        message: err instanceof Error ? err.message : 'IDP unreachable',
-        status: 503,
-        retryable: true,
-      };
-    }
-
-    let responseData: any;
-    try {
-      const text = await idpResponse.text();
-      if (!text.trim()) {
-        return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Empty response from IDP', status: 502, retryable: true };
-      }
-      responseData = JSON.parse(text);
-    } catch (err) {
-      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Invalid JSON from IDP', status: 502, retryable: true };
-    }
-
-    if (!idpResponse.ok) {
-      const idpError = responseData?.error || {};
-      const code = idpError.code || 'UNKNOWN_ERROR';
-      const discardToken = idpResponse.status === 401 || idpError.discard_token === true;
-      const retryable = idpResponse.status !== 401 && idpError.retryable === true;
-      if (discardToken) {
-        await updateSession(sessionToken, {
-          idpRefreshToken: '',
-          idpRefreshTokenExpires: undefined,
-          refreshTokenClearedAt: Date.now(),
-          refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
-        });
-      }
-      return {
-        ok: false,
-        code,
-        message: idpError.message || 'Token refresh failed',
-        status: idpResponse.status,
-        discardToken,
-        retryable,
-        resolution: idpError.resolution,
-        terminal: discardToken,
-      };
-    }
-
-    // Validate canonical envelope.
-    if (
-      !responseData ||
-      typeof responseData !== 'object' ||
-      responseData.success !== true ||
-      !responseData.data
-    ) {
-      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Non-compliant IDP envelope', status: 502, retryable: true };
-    }
-
-    const newAccess = responseData.data.access_token;
-    const newRefresh = responseData.data.refresh_token;
-    if (!newAccess) {
-      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Missing access token in IDP response', status: 500 };
-    }
-
-    let accessTokenExpires: number;
-    let refreshTokenExpires: number | undefined;
-    let decoded: any;
-    try {
-      const r = computeTokenExpiries({ accessToken: newAccess, refreshToken: newRefresh, preferJwt: true });
-      decoded = r.decodedAccessToken;
-      accessTokenExpires = r.accessTokenExpires;
-      refreshTokenExpires = r.refreshTokenExpires;
-    } catch {
-      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Failed to decode new tokens', status: 500 };
-    }
-
-    let amrClaims: string[] = [];
-    if (decoded?.amr) {
-      try {
-        amrClaims = typeof decoded.amr === 'string' ? JSON.parse(decoded.amr) : decoded.amr;
-      } catch {
-        amrClaims = session.authenticationMethods || [];
-      }
-    } else {
-      amrClaims = session.authenticationMethods || [];
-    }
-    const acrLevel = String(decoded?.acr || session.authenticationLevel || '1');
-    const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
-    const newKid = extractKidFromToken(newAccess);
-
-    await updateSession(sessionToken, {
-      ...session,
-      idpAccessToken: newAccess,
-      idpAccessTokenExpires: accessTokenExpires,
-      idpRefreshToken: hasNewRefresh ? newRefresh : session.idpRefreshToken,
-      idpRefreshTokenExpires: hasNewRefresh ? refreshTokenExpires : session.idpRefreshTokenExpires,
-      decodedAccessToken: decoded,
-      bearerKeyId: newKid || session.bearerKeyId,
-      authenticationMethods: amrClaims,
-      authenticationLevel: acrLevel,
-      mfaVerified: amrClaims.includes('mfa') || session.mfaVerified,
-      mfaCompletedAt: decoded?.mfa_time ? parseInt(decoded.mfa_time) * 1000 : session.mfaCompletedAt,
-      mfaExpiresAt: decoded?.mfa_expires ? parseInt(decoded.mfa_expires) * 1000 : session.mfaExpiresAt,
-      mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
-    });
-
-    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true };
-  } finally {
-    if (weHoldLock) {
-      await releaseRefreshLock(sessionToken, requestId, releaseVersion);
-    }
-  }
-}
+/**
+ * ensureFreshAccessToken — server-side preflight refresh.
+ *
+ * Returns a non-expired IDP access token for a given session. Refreshes
+ * proactively when the stored token is within the safety window of expiry,
+ * using the same Redis lock and IDP wire shape as `createRefreshHandler`.
+ *
+ * Designed for proxy-route auth helpers that today read the stored token
+ * blindly and let the backend reject it with a 401. Calling this instead of
+ * `getSession(...).idpAccessToken` means a good token client never sends
+ * credentials it already knows are invalid.
+ *
+ * Single-use refresh-token semantics are preserved via Redis-backed
+ * single-flight locking (see `acquireRefreshLock`).
+ */
+import {
+  getSession,
+  getBetterAuthSession,
+  updateSession,
+  acquireRefreshLock,
+  releaseRefreshLock,
+  checkRefreshLock,
+} from './session-store';
+import { computeTokenExpiries } from './token-expiry';
+import { extractKidFromToken } from '../auth/utils/token-utils';
+
+export interface EnsureFreshConfig {
+  idpBaseUrl: string;
+  clientId: string;
+  refreshEndpoint?: string;
+}
+
+export interface EnsureFreshOptions {
+  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
+  safetyWindowMs?: number;
+  /** Max wait while another caller holds the refresh lock. Default 5000. */
+  lockWaitMs?: number;
+  /** Optional caller request id for lock attribution. */
+  requestId?: string;
+}
+
+export type EnsureFreshResult =
+  | {
+      ok: true;
+      accessToken: string;
+      accessTokenExpires: number;
+      /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
+      refreshed: boolean;
+    }
+  | {
+      ok: false;
+      code: string;
+      message: string;
+      status: number;
+      terminal?: boolean;
+      discardToken?: boolean;
+      retryable?: boolean;
+      resolution?: string;
+    };
+
+const DEFAULT_SAFETY_WINDOW_MS = 60_000;
+const DEFAULT_LOCK_WAIT_MS = 5000;
+
+function decodeJwtExp(token: string): number {
+  const parts = token.split('.');
+  if (parts.length !== 3) return -1;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return (payload.exp || 0) * 1000;
+  } catch {
+    return -1;
+  }
+}
+
+export async function ensureFreshAccessToken(
+  sessionToken: string,
+  config: EnsureFreshConfig,
+  options: EnsureFreshOptions = {}
+): Promise<EnsureFreshResult> {
+  const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
+  const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
+  const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
+  const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
+
+  let session = await getSession(sessionToken);
+  if (!session || !session.idpRefreshToken) {
+    const baSession = await getBetterAuthSession(sessionToken);
+    if (baSession?.idpRefreshToken) {
+      session = baSession;
+    }
+  }
+  if (!session) {
+    return { ok: false, code: 'NO_SESSION', message: 'No session for token', status: 401, terminal: true };
+  }
+
+  const storedToken = session.idpAccessToken;
+  if (!storedToken) {
+    return { ok: false, code: 'NO_TOKEN', message: 'No IDP access token in session', status: 401, terminal: true };
+  }
+
+  const now = Date.now();
+  const redisExpires = session.idpAccessTokenExpires ?? 0;
+  const jwtExpires = decodeJwtExp(storedToken);
+  // Use the smaller of the two to be conservative — Redis can be stale, JWT exp is authoritative.
+  const effectiveExpires = jwtExpires > 0 ? Math.min(redisExpires || jwtExpires, jwtExpires) : redisExpires;
+  const msUntilExpiry = effectiveExpires - now;
+
+  if (msUntilExpiry > safetyWindowMs) {
+    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false };
+  }
+
+  if (!session.idpRefreshToken) {
+    return {
+      ok: false,
+      code: 'NO_REFRESH_TOKEN',
+      message: 'Access token expired and no refresh token available',
+      status: 401,
+      terminal: true,
+      resolution: 'User must re-authenticate',
+    };
+  }
+
+  const lock = await acquireRefreshLock(sessionToken, requestId, lockWaitMs);
+  let weHoldLock = false;
+  let releaseVersion: number | undefined;
+
+  if (!lock.acquired) {
+    const existing = await checkRefreshLock(sessionToken);
+    if (!existing || existing.acquiredBy !== requestId) {
+      const startWait = Date.now();
+      while (Date.now() - startWait < lockWaitMs) {
+        await new Promise(r => setTimeout(r, 200));
+        const stillLocked = await checkRefreshLock(sessionToken);
+        if (!stillLocked) {
+          let after = await getSession(sessionToken);
+          if (!after || !after.idpRefreshToken) {
+            const baAfter = await getBetterAuthSession(sessionToken);
+            if (baAfter?.idpRefreshToken) after = baAfter;
+          }
+          if (after?.idpAccessToken && after.idpAccessTokenExpires) {
+            const remaining = after.idpAccessTokenExpires - Date.now();
+            if (remaining > safetyWindowMs) {
+              return {
+                ok: true,
+                accessToken: after.idpAccessToken,
+                accessTokenExpires: after.idpAccessTokenExpires,
+                refreshed: true,
+              };
+            }
+          }
+          break;
+        }
+      }
+      return {
+        ok: false,
+        code: 'CONFLICT',
+        message: 'Refresh already in progress',
+        status: 409,
+        retryable: true,
+      };
+    }
+  } else {
+    weHoldLock = true;
+    releaseVersion = lock.lockInfo?.lockVersion;
+  }
+
+  try {
+    // Re-check after lock — another caller may have already refreshed.
+    let latest = await getSession(sessionToken);
+    if (!latest || !latest.idpRefreshToken) {
+      const baLatest = await getBetterAuthSession(sessionToken);
+      if (baLatest?.idpRefreshToken) latest = baLatest;
+    }
+    if (latest?.idpAccessToken && latest.idpAccessTokenExpires) {
+      const latestRemaining = latest.idpAccessTokenExpires - Date.now();
+      const latestJwtExp = decodeJwtExp(latest.idpAccessToken);
+      const stillStale = latestRemaining <= safetyWindowMs || (latestJwtExp > 0 && latestJwtExp <= Date.now());
+      if (!stillStale) {
+        return {
+          ok: true,
+          accessToken: latest.idpAccessToken,
+          accessTokenExpires: latest.idpAccessTokenExpires,
+          refreshed: true,
+        };
+      }
+    }
+
+    // Build refresh request body — wire shape must match what the IDP expects.
+    let authMethods: string[] = [];
+    if (Array.isArray(session.authenticationMethods)) {
+      authMethods = session.authenticationMethods;
+    } else if (typeof session.authenticationMethods === 'string') {
+      try { authMethods = JSON.parse(session.authenticationMethods); } catch { /* fall through */ }
+    }
+    const isOAuthSession = !!session.oauthProvider;
+    if (authMethods.length === 0 && isOAuthSession) {
+      authMethods = ['pwd', 'mfa'];
+    }
+    const twoFactorMethod =
+      authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
+      session.mfaMethod ||
+      (isOAuthSession ? 'oauth' : null);
+
+    let acrValue = String(session.authenticationLevel ?? '1');
+    if (isOAuthSession && session.mfaVerified && acrValue === '1') {
+      acrValue = '2';
+    }
+
+    // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
+    // `session` was read before we acquired the lock; a concurrent refresh that
+    // completed while we waited rotates the token, so the pre-lock value is stale
+    // and would draw an avoidable 401 (the CAS now catches the resulting wipe, but
+    // the round-trip is wasted). `latest` is the authoritative post-lock session.
+    // Auth-context (amr/acr/2FA) intentionally still derives from `session` — it is
+    // the identity context of THIS request, unchanged by a token rotation.
+    const sentRefreshToken = latest?.idpRefreshToken ?? session.idpRefreshToken;
+    const body: Record<string, unknown> = {
+      refresh_token: sentRefreshToken,
+      amr: authMethods,
+      acr: acrValue,
+    };
+    if (session.mfaVerified) body.two_factor_verified = true;
+    if (twoFactorMethod) body.two_factor_method = twoFactorMethod;
+    if (session.mfaCompletedAt) body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
+
+    let idpResponse: Response;
+    try {
+      idpResponse = await fetch(`${idpBaseUrl}${refreshEndpoint}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-Client-Id': clientId },
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        code: 'UPSTREAM_SERVICE_UNAVAILABLE',
+        message: err instanceof Error ? err.message : 'IDP unreachable',
+        status: 503,
+        retryable: true,
+      };
+    }
+
+    let responseData: any;
+    try {
+      const text = await idpResponse.text();
+      if (!text.trim()) {
+        return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Empty response from IDP', status: 502, retryable: true };
+      }
+      responseData = JSON.parse(text);
+    } catch (err) {
+      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Invalid JSON from IDP', status: 502, retryable: true };
+    }
+
+    if (!idpResponse.ok) {
+      const idpError = responseData?.error || {};
+      const code = idpError.code || 'UNKNOWN_ERROR';
+      let discardToken = idpResponse.status === 401 || idpError.discard_token === true;
+      const retryable = idpResponse.status !== 401 && idpError.retryable === true;
+      if (discardToken) {
+        // Race-safe discard (CAS): only clear if the refresh token we used is STILL
+        // current. A concurrent refresh may have already rotated it — our 401 is then
+        // stale/expected, and wiping here would silently log out a healthy session
+        // (the rotation-race wipe, QA 6873 site 1/2). Compare-and-skip if it changed;
+        // a concurrent rotation is NOT a terminal condition.
+        const postRefresh = await getSession(sessionToken);
+        // CAS compares against the token we ACTUALLY SENT (WO-2: sentRefreshToken,
+        // the post-lock value), not the pre-lock snapshot — otherwise a token rotated
+        // between pre-lock read and our send would be misjudged.
+        const tokenUnchanged =
+          !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
+        if (tokenUnchanged) {
+          await updateSession(sessionToken, {
+            idpRefreshToken: '',
+            idpRefreshTokenExpires: undefined,
+            refreshTokenClearedAt: Date.now(),
+            refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
+          });
+        } else {
+          // Concurrent refresh already rotated the token — our 401 is stale. Return the
+          // freshly-rotated token directly so the loser succeeds without a retry round-trip
+          // (race-fix follow-up #1).
+          discardToken = false;
+          if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+            return {
+              ok: true,
+              accessToken: postRefresh.idpAccessToken,
+              accessTokenExpires: postRefresh.idpAccessTokenExpires,
+              refreshed: true,
+            };
+          }
+        }
+      }
+      return {
+        ok: false,
+        code,
+        message: idpError.message || 'Token refresh failed',
+        status: idpResponse.status,
+        discardToken,
+        retryable,
+        resolution: idpError.resolution,
+        terminal: discardToken,
+      };
+    }
+
+    // Validate canonical envelope.
+    if (
+      !responseData ||
+      typeof responseData !== 'object' ||
+      responseData.success !== true ||
+      !responseData.data
+    ) {
+      return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Non-compliant IDP envelope', status: 502, retryable: true };
+    }
+
+    const newAccess = responseData.data.access_token;
+    const newRefresh = responseData.data.refresh_token;
+    if (!newAccess) {
+      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Missing access token in IDP response', status: 500 };
+    }
+
+    let accessTokenExpires: number;
+    let refreshTokenExpires: number | undefined;
+    let decoded: any;
+    try {
+      const r = computeTokenExpiries({ accessToken: newAccess, refreshToken: newRefresh, preferJwt: true });
+      decoded = r.decodedAccessToken;
+      accessTokenExpires = r.accessTokenExpires;
+      refreshTokenExpires = r.refreshTokenExpires;
+    } catch {
+      return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Failed to decode new tokens', status: 500 };
+    }
+
+    let amrClaims: string[] = [];
+    if (decoded?.amr) {
+      try {
+        amrClaims = typeof decoded.amr === 'string' ? JSON.parse(decoded.amr) : decoded.amr;
+      } catch {
+        amrClaims = session.authenticationMethods || [];
+      }
+    } else {
+      amrClaims = session.authenticationMethods || [];
+    }
+    const acrLevel = String(decoded?.acr || session.authenticationLevel || '1');
+    const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
+    const newKid = extractKidFromToken(newAccess);
+
+    await updateSession(sessionToken, {
+      ...session,
+      idpAccessToken: newAccess,
+      idpAccessTokenExpires: accessTokenExpires,
+      idpRefreshToken: hasNewRefresh ? newRefresh : session.idpRefreshToken,
+      idpRefreshTokenExpires: hasNewRefresh ? refreshTokenExpires : session.idpRefreshTokenExpires,
+      decodedAccessToken: decoded,
+      bearerKeyId: newKid || session.bearerKeyId,
+      authenticationMethods: amrClaims,
+      authenticationLevel: acrLevel,
+      mfaVerified: amrClaims.includes('mfa') || session.mfaVerified,
+      mfaCompletedAt: decoded?.mfa_time ? parseInt(decoded.mfa_time) * 1000 : session.mfaCompletedAt,
+      mfaExpiresAt: decoded?.mfa_expires ? parseInt(decoded.mfa_expires) * 1000 : session.mfaExpiresAt,
+      mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
+    });
+
+    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true };
+  } finally {
+    if (weHoldLock) {
+      await releaseRefreshLock(sessionToken, requestId, releaseVersion);
+    }
+  }
+}