@payez/next-mvp 4.8.0 → 4.8.2

package/src/routes/auth/viability.ts

@@ -1,520 +1,520 @@
-/**
- * Ready-to-Use Session Viability Route
- *
- * Checks if the current session is viable (valid and not expired).
- * Used by client-side code to determine if a refresh is needed.
- *
- * @example
- * ```typescript
- * // app/api/session/viability/route.ts
- * export { GET } from '@payez/next-mvp/routes/auth/viability';
- * ```
- *
- * @version 2.0.0
- * @since auth-ready-v2
- */
-
-import { revocationFields } from '../../auth/revocation-fields';
-import { NextRequest, NextResponse } from 'next/server';
-import { resolveSessionState } from '../../server/auth';
-import {
-  getSession as getRedisSession,
-  getBetterAuthSession as getBetterAuthRedisSession,
-} from '../../lib/session-store';
-import { getIDPClientConfig } from '../../lib/idp-client-config';
-import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
-import { tokenLogId } from '../../lib/token-log-id';
-import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
-
-/**
- * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
- */
-async function getTenantRequiresTwoFactor(): Promise<boolean> {
-  try {
-    const config = await getIDPClientConfig();
-    return config.authSettings?.require2FA ?? true; // Default to true for security
-  } catch {
-    console.warn('[VIABILITY] Could not get client config, defaulting tenantRequiresTwoFactor to true');
-    return true;
-  }
-}
-
-/**
- * Which 2FA methods the TENANT permits — cards 141688 + 141741.
- *
- * WHY THIS IS HERE: this endpoint answered "is 2FA required, and is it done?"
- * and said nothing about WITH WHAT. Both the middleware gate and the
- * verify-code page call this route, and NEITHER had any method data — so
- * nothing in the system asked whether the user CAN complete the challenge it
- * is about to demand. A user whose tenant allows only `totp`, with no
- * authenticator enrolled, is sent to a page that offers email and sms.
- *
- * ⚠ THIS IS NOT A COMPLETION SIGNAL AND MUST NEVER BE READ AS ONE.
- * It says what the tenant PERMITS. It says nothing about what the user has
- * enrolled, and nothing about whether they have verified. The invariant
- * (QAPert, acceptance J2/J5) is: METHOD-PRESENCE IS NOT VERIFIED. A user with
- * one method is still challenged and still gated until they actually verify.
- * `userHasCompletedTenantTwoFactorRequirements` remains the only field that
- * answers "are they through".
- *
- * STILL MISSING, deliberately not guessed here: the ENROLLED set. That lives
- * behind /api/mfa/methods and needs a call this route does not currently make.
- * Allowed-only closes the "offered a method the tenant forbids" half; it does
- * NOT close "has nothing enrolled and no way to enrol". Both halves are named
- * in the cards so neither gets lost.
- *
- * NULL MEANS UNKNOWN — IT DOES NOT MEAN "NONE", AND IT DOES NOT MEAN
- * "email and sms". If the client config cannot be read we do not know what the
- * tenant permits, and every available guess is wrong in a way that matters:
- *
- *   - guessing ['email','sms'] fails OPEN. On a totp-only tenant that offers
- *     the user two methods the tenant forbids — which is defect 141688 itself,
- *     re-created by its own fix during a config outage.
- *   - guessing [] fails CLOSED but locks the user out of a challenge they may
- *     be perfectly able to complete.
- *
- * So we report the truth (we don't know) and let the consumer decide, rather
- * than encoding a guess that reads like a measurement. Same reasoning as the
- * nullable require_2fa fix: "absent" has to be expressible, or callers cannot
- * tell a real value from a default.
- *
- * No local default. 257255 UPDATE: allowed2FAMethods is now OPTIONAL on
- * AuthSettings - the config mapper no longer substitutes ['email','sms'] when
- * the document carries no policy, because that made "no policy" and "exactly
- * these methods" indistinguishable. So absent now correctly reaches this
- * function as undefined and is reported as UNKNOWN (null), which is what this
- * function's own contract already said it wanted. Before the change it would
- * have returned the mapper's fabrication AS IF IT WERE THE TENANT'S VALUE.
- */
-async function getTenantAllowed2FAMethods(): Promise<string[] | null> {
-  try {
-    const config = await getIDPClientConfig();
-    // `?? null` is the whole point: undefined means the document carried no
-    // policy, and this function reports UNKNOWN rather than guessing.
-    return config.authSettings.allowed2FAMethods ?? null;
-  } catch {
-    console.warn('[VIABILITY] Could not get client config — reporting allowed 2FA methods as UNKNOWN (null), not guessing');
-    return null;
-  }
-}
-
-/**
- * Resolve the client id reported to the caller.
- *
- * Was: `session?.idpClientId || process.env.IDP_CLIENT_ID || ''`. Two defects,
- * both of the "report a confident value where the truth is unknown" family that
- * card 221076 was about:
- *
- * 1. `|| ''` made "we do not know this session's client" indistinguishable from
- *    "the client id is blank". Callers cannot tell absence from a known-empty
- *    value, so nothing can react to the former. Absence is now `null`, which is
- *    representable — and still falsy, so existing `if (!clientId)` guards behave
- *    exactly as before.
- *
- * 2. The env fallback SILENTLY substitutes the deployment's default client for a
- *    session whose own client is unknown. On a multi-tenant IDP that is a
- *    cross-tenant wrong answer, not a default. It is kept for single-tenant
- *    deployments that rely on it, but it now says so in the log rather than
- *    passing the substitution off as the session's own identity.
- */
-function resolveClientId(sessionClientId: string | undefined): string | null {
-  if (sessionClientId) return sessionClientId;
-
-  const envClientId = process.env.IDP_CLIENT_ID;
-  if (envClientId) {
-    console.warn(
-      '[VIABILITY_ROUTE] session carries no idpClientId - substituting IDP_CLIENT_ID ' +
-        'from the environment. On a multi-tenant deployment this is a DIFFERENT client ' +
-        'than the session belongs to.'
-    );
-    return envClientId;
-  }
-
-  return null;
-}
-
-/**
- * GET /api/session/viability - Check if session is viable
- *
- * Returns:
- * - viable: boolean - Whether the session can be used
- * - needsRefresh: boolean - Whether a refresh is recommended
- * - expiresIn: number - Seconds until token expires
- */
-export async function GET(req: NextRequest) {
-  try {
-    // PAY-2216: ask for the session's STATE, not a session-or-null. A null used to cover a store outage, a deleted
-    // session and no cookie alike, so this route answered 'No session found' to all three and the middleware could
-    // never clear a dead cookie (it must not clear on an outage). See SessionState in server/auth.
-    const sessionState = await resolveSessionState(req);
-
-    if (sessionState.state === 'unknown') {
-      // The store did not answer. NOT a statement about the session: never stale, never 'No session found'.
-      // Same shape as this route's catch (PAY-1882 step 4): 'unknown' revocation -> the middleware's fail-closed
-      // path, a non-OK answer -> service_error, which never clears cookies.
-      console.warn('[VIABILITY] Session store unavailable - session state unknown');
-      return NextResponse.json({
-        viable: false,
-        needsRefresh: false,
-        authenticated: false,
-        revocationStatus: 'unknown' as RevocationStatus,
-        unavailable: true, // PAY-2339: a reader of this JSON gets the hold signal (the response is non-OK, so the middleware holds as service_error)
-        error: 'Session store unavailable',
-        code: 'STORE_UNAVAILABLE'
-      }, { status: 500 });
-    }
-
-    if (sessionState.state === 'missing') {
-      // A VERIFIED cookie and a store that answered "not here". The existing stale shape, so the middleware's
-      // stale_session arm (PAY-2216 / 4.5.4) clears it.
-      console.warn('[VIABILITY] Stale cookie detected - verified cookie, session not in Redis');
-      return NextResponse.json({
-        viable: false,
-        needsRefresh: false,
-        authenticated: false,
-        sessionTokenId: tokenLogId(sessionState.sessionToken), // PAY-1481: a correlation id, never the token
-        reason: 'Stale session - cookie exists but session not found in Redis'
-      });
-    }
-
-    if (sessionState.state === 'none') {
-      return NextResponse.json({
-        viable: false,
-        needsRefresh: false,
-        authenticated: false,
-        reason: 'No session found'
-      });
-    }
-
-    const baSession = sessionState.session;
-
-    const token = baSession as any;
-    const sessionToken = baSession.session?.token;
-
-    // Try the canonical session-store first; fall back to the Better-Auth-keyed
-    // Redis record (`ba:{appSlug}:{token}`) when the canonical lookup misses.
-    // Without the fallback, any consumer that wrote a BA session via the OAuth
-    // callback path or dev-login and didn't separately populate the canonical
-    // store would land here with a "Stale session" verdict, even though the BA
-    // stack just resolved the cookie cleanly. Keeps the two viability impls
-    // (this route + `api-handlers/session/viability.ts`) in lockstep.
-    let session = sessionToken ? await getRedisSession(sessionToken) : null;
-    if (sessionToken && !session) {
-      session = await getBetterAuthRedisSession(sessionToken);
-      if (session) {
-        console.log('[VIABILITY] Found session in Better Auth store (fallback)');
-      }
-    }
-
-    // CRITICAL: Detect stale cookie state (cookie exists but neither store has the session)
-    if (sessionToken && !session) {
-      console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
-      return NextResponse.json({
-        viable: false,
-        needsRefresh: false,
-        authenticated: false,
-        sessionTokenId: tokenLogId(sessionToken), // PAY-1481: a correlation id, never the token; middleware only needs presence to clear the stale cookie
-        reason: 'Stale session - cookie exists but session not found in Redis'
-      });
-    }
-
-    // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
-    // See the SessionData.nextStep doc. This is the field that tells the gate
-    // whether the user CAN complete a challenge; without it both consumers were
-    // sending zero-method users to a page they had no way to act on.
-    //
-    // Declared once, here, above every return: `session` is settled by this
-    // point, and all three authenticated responses must carry the SAME value.
-    // Deriving it per-branch would let the paths drift apart silently.
-    //
-    // NO `?? null` HERE, DELIBERATELY — and this is the whole safety argument:
-    //
-    //   undefined = we never captured it. Every session minted BEFORE this
-    //               change is in that state, and there are live ones in Redis
-    //               right now. JSON.stringify omits the key, so the consumer
-    //               sees no field and knows it is uninformed.
-    //   null      = the IDP affirmatively said "nothing outstanding".
-    //
-    // Collapsing the first into the second with `?? null` would tell the gate
-    // "fully authenticated, nothing to do" about every pre-existing session —
-    // including a zero-method user who must be sent to enrol. That is a
-    // fail-open on the entire existing session population, produced by a
-    // default that reads like a measurement. Same mistake as the nullable
-    // require_2fa case: absent has to stay expressible.
-    const nextStep = session?.nextStep;
-
-    /**
-     * 266007 — port the sibling's CRITICAL override (api-handlers/session/
-     * viability.ts:82-86) into this, the impl consumers actually MOUNT.
-     * An OAuth session whose callback set mfaVerified === false because no
-     * refresh_token was issued ALWAYS needs 2FA completion, whatever the
-     * tenant config says — completing 2FA is how it obtains one.
-     *
-     * STRICT === false, deliberately: an ABSENT mfaVerified (every session
-     * minted before that field existed) is not a signal, and treating it as
-     * one would force-rechallenge the entire existing session population.
-     *
-     * *** R807 (BAPert, card 362550) - WHY THE `=== false` TEST ALONE NO LONGER
-     * CARRIES THAT INTENT, AND WHAT RESTORES IT. ***
-     *
-     * The intent above is right, but by the time a session reaches here the
-     * distinction it depends on IS ALREADY GONE: every construction site
-     * (session-store, decode-session, token-lifecycle x2, SessionModel) collapses
-     * an absent mfaVerified to `false` via `?? false`. So `=== false` had stopped
-     * meaning "the callback affirmatively said false" and had come to mean
-     * "affirmatively false OR never knew" - i.e. the exact mass re-challenge this
-     * comment says it is preventing. The guard read as strict while behaving as
-     * permissive, because the collapse happens upstream and out of sight.
-     *
-     * R807 keeps `mfaVerified` fail-closed at all five sites (removing `?? false`
-     * would be an AUTH BYPASS - a session that never proved MFA read as having
-     * proved it) and gives THIS question its own signal instead. So the test is
-     * now two parts:
-     *
-     *   mfaSignalPresent === true  -> the producer really did emit a value, so the
-     *                                 `false` below is a MEASUREMENT. Fire.
-     *   absent / false             -> LEGACY session (minted before the signal
-     *                                 existed) or a path with no IDP tokens at all.
-     *                                 NOT a signal. Do NOT force a re-challenge.
-     *
-     * That absent-means-do-not-fire read is the migration behaviour, and it is
-     * what preserves this comment's original guarantee verbatim through rollout:
-     * on the day this ships, EVERY existing session has no signal and none of them
-     * is re-challenged.
-     *
-     * *** AND IT IS SAFE ONLY BECAUSE IT IS CONFINED HERE. *** mfaSignalPresent is
-     * permissive by construction - it can only ever SUPPRESS this override. It must
-     * never reach a path that grants access; gate those on `mfaVerified`, which is
-     * still fail-closed everywhere. R807 is void if this signal escapes into an
-     * auth decision.
-     *
-     * Declared once here, like nextStep above, so the three authenticated
-     * responses cannot drift apart. Feeds the legacy `requires2FA` field the
-     * middleware actually gates on; `tenantRequiresTwoFactor` stays pure —
-     * it names TENANT policy, and this override is not tenant state.
-     */
-    const oauthSessionNeedsTwoFactor =
-      session?.mfaSignalPresent === true &&
-      session?.mfaVerified === false &&
-      !(session.idpRefreshToken || (session as any)?.refreshToken);
-
-    // --- Session revocation status (PAY-1882 step 4 producer half) ---
-    /*
-     * Resolve the four-state revocation status for this user (BAPert 66320).
-     * Read it HERE, above every authenticated return, so all three responses
-     * carry the SAME value - the same discipline as nextStep above.
-     *
-     * The middleware fails CLOSED by default on 'unknown' (a failed Vibe read)
-     * and always on 'revoked'; 'active' and 'not_configured' stay viable. A
-     * consumer that does NOT read revocationStatus is unaffected - absent is not
-     * revoked - so shipping this changes nothing for them until they opt in.
-     */
-    let revocationStatus: RevocationStatus = 'not_configured';
-    if (session) {
-      // BAPert 66480 condition 2 / ruling (ii) 66700: the numeric IdP id comes from
-      // the token's own `sub` claim FIRST (session.userId can be an email).
-      const revocationUserId = resolveNumericIdpUserId(session, (session as any).idpAccessToken);
-      if (revocationUserId > 0) {
-        try {
-          revocationStatus = await getRevocationStatus(revocationUserId, sessionToken);
-        } catch {
-          // getRevocationStatus does not throw by contract, but never let a
-          // revocation probe take down the viability answer: fail closed.
-          revocationStatus = 'unknown';
-        }
-      } else {
-        // N1 (NightHawk 66392): a session exists but carries no usable numeric
-        // IdP id, so the check could not run -> 'unknown' (could not determine),
-        // NOT 'not_configured' (no revocation source).
-        // BAPert 66480 condition 1: emit ONE WARN (shape only) so a non-numeric
-        // id surfaces as a log line, not an unexplained sign-out.
-        revocationStatus = warnNonNumericUserId(sessionToken, session.userId);
-      }
-    }
-
-    // Check access token expiry
-    const now = Math.floor(Date.now() / 1000);
-    // 240654 addendum 2: fall back to the Redis session's own expiry.
-    //
-    // The first two reads come off the Better Auth session OBJECT. A Path-B
-    // synthetic session — the shape server/auth.ts builds for a legacy JWS
-    // session — carries NEITHER: it is `{session:{token}, user:{...}}` with no
-    // accessTokenExpires and no exp. So every legacy session fell into the
-    // "no expiry info" branch below and answered needsRefresh:true on EVERY
-    // viability read from the moment of login, while the token was in fact
-    // fresh (15-minute TTL measured). Benign for the viable/authenticated
-    // verdict, but it recommends a refresh constantly, which is pure perf
-    // noise and multiplies exposure to the empty-clientId refresh path (223542).
-    //
-    // lib/session-store puts the real value on the session as
-    // idpAccessTokenExpires, in MILLISECONDS (better-auth.ts:784 sets
-    // `Date.now() + expires_in * 1000`). The other two sources are in SECONDS.
-    // Mixing units here would be a silent disaster, so note that the
-    // normalisation below (`> 1e12 ? /1000 : as-is`) already discriminates
-    // them by magnitude: a seconds timestamp is ~1.7e9, a milliseconds one
-    // ~1.7e12. This fallback is therefore safe in either unit, and that
-    // existing normaliser is load-bearing for it -- do not remove it.
-    const accessTokenExpires =
-      (token as any).accessTokenExpires ||
-      token.exp ||
-      (session as any)?.idpAccessTokenExpires;
-
-    if (!accessTokenExpires) {
-      // No expiry info, assume viable but recommend refresh
-      const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
-      // Cards 141688/141741 — see getTenantAllowed2FAMethods. NOT a completion signal.
-      const tenantAllowed2FAMethods = await getTenantAllowed2FAMethods();
-
-      // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
-      const mfaExpiresAt = session?.mfaExpiresAt || 0;
-      const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
-      // Check mfaVerified (normalized name) with fallback to twoFactorComplete for compatibility
-      const mfaVerifiedInSession = session?.mfaVerified ?? false;
-
-      // User has completed 2FA requirements if: they verified AND it hasn't expired
-      const userHasCompletedTenantTwoFactorRequirements = mfaVerifiedInSession && !mfaExpired;
-
-      // userStillNeedsTwoFactor = inverse of completed (matches session callback logic)
-      const userStillNeedsTwoFactor = !userHasCompletedTenantTwoFactorRequirements;
-
-      return NextResponse.json({
-        viable: true,
-        needsRefresh: true,
-        authenticated: true,
-        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
-        // Session revocation (PAY-1882 step 4): the four-state status, plus the
-        // boolean the middleware's existing force-invalid branch already reads.
-        revocationStatus,
-        ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
-        // Clear names for middleware decision-making
-        tenantRequiresTwoFactor,
-        userHasCompletedTenantTwoFactorRequirements,
-        userStillNeedsTwoFactor,
-        tenantAllowed2FAMethods,
-        nextStep,
-        // Legacy field names for backwards compatibility
-        requires2FA: tenantRequiresTwoFactor || oauthSessionNeedsTwoFactor,
-        twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
-        accessTokenExpired: false,
-        reason: 'No expiry information'
-      });
-    }
-
-    // Convert to seconds if needed
-    const expiryTime = accessTokenExpires > 1000000000000
-      ? Math.floor(accessTokenExpires / 1000)
-      : accessTokenExpires;
-
-    const expiresIn = expiryTime - now;
-    const isExpired = expiresIn <= 0;
-    const needsRefresh = expiresIn <= 300; // 5 minutes buffer
-
-    // Check if we have refresh capability (check normalized field name first)
-    const hasRefreshToken = !!(session?.idpRefreshToken || (session as any)?.refreshToken || (token as any).refreshToken);
-
-    // CLEAR NAMING: Tenant-wide 2FA requirement from client config
-    const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
-    // Cards 141688/141741 — see getTenantAllowed2FAMethods. NOT a completion signal.
-    const tenantAllowed2FAMethods = await getTenantAllowed2FAMethods();
-
-    // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
-    // The session may have mfaVerified=true from days ago, but if mfaExpiresAt
-    // has passed, we must treat 2FA as incomplete to force re-verification.
-    const mfaExpiresAt = session?.mfaExpiresAt || 0;
-    const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
-    // Check mfaVerified (normalized name) with fallback to twoFactorComplete for compatibility
-    const mfaVerifiedInSession = session?.mfaVerified ?? false;
-
-    // DEBUG: Log what we're reading from the session
-    console.log('[VIABILITY] Session 2FA state:', {
-      sessionToken: tokenLogId(sessionToken),
-      'session.mfaVerified': session?.mfaVerified,
-      'session.twoFactorComplete': (session as any)?.twoFactorComplete,
-      mfaVerifiedInSession,
-      mfaExpiresAt,
-      mfaExpired,
-      hasRefreshToken,
-      'session.idpRefreshToken': !!session?.idpRefreshToken,
-      'session.refreshToken': !!(session as any)?.refreshToken,
-    });
-
-    // CLEAR NAMING: User has completed 2FA requirements if: they verified AND it hasn't expired
-    const userHasCompletedTenantTwoFactorRequirements = mfaVerifiedInSession && !mfaExpired;
-
-    // userStillNeedsTwoFactor = inverse of completed (matches session callback logic)
-    const userStillNeedsTwoFactor = !userHasCompletedTenantTwoFactorRequirements;
-
-    if (mfaExpired && mfaVerifiedInSession) {
-      console.warn('[VIABILITY] MFA expired - forcing 2FA re-verification');
-    }
-
-    if (isExpired) {
-      return NextResponse.json({
-        viable: false,
-        needsRefresh: hasRefreshToken,
-        expiresIn: 0,
-        hasRefreshToken,
-        authenticated: true,
-        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
-        // Clear names
-        tenantRequiresTwoFactor,
-        userHasCompletedTenantTwoFactorRequirements,
-        userStillNeedsTwoFactor,
-        tenantAllowed2FAMethods,
-        nextStep,
-        // Legacy names for backwards compatibility
-        requires2FA: tenantRequiresTwoFactor || oauthSessionNeedsTwoFactor,
-        twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
-        accessTokenExpired: true,
-        reason: 'Token expired',
-        // Session revocation (PAY-1882 step 4) - same value on every return.
-        revocationStatus,
-        ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
-        // RBAC fields
-        roles: session?.roles || [],
-        clientId: resolveClientId(session?.idpClientId),
-      });
-    }
-
-    return NextResponse.json({
-      viable: true,
-      needsRefresh,
-      expiresIn,
-      hasRefreshToken,
-      authenticated: true,
-      sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
-      // Session revocation (PAY-1882 step 4) - same value on every return.
-      revocationStatus,
-      ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
-      // Clear names
-      tenantRequiresTwoFactor,
-      userHasCompletedTenantTwoFactorRequirements,
-      userStillNeedsTwoFactor,
-      tenantAllowed2FAMethods,
-      nextStep,
-      // Legacy names for backwards compatibility
-      requires2FA: tenantRequiresTwoFactor || oauthSessionNeedsTwoFactor,
-      twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
-      accessTokenExpired: false,
-      expiresAt: new Date(expiryTime * 1000).toISOString(),
-      // RBAC fields
-      roles: session?.roles || [],
-      clientId: resolveClientId(session?.idpClientId),
-    });
-  } catch (error) {
-    // PAY-1438: pre-auth probe - the exception text stays in the log, keyed by correlationId.
-    const correlationId = logExceptionWithCorrelation('[VIABILITY_ROUTE] Error checking session viability:', error);
-    return NextResponse.json({
-      viable: false,
-      needsRefresh: false,
-      authenticated: false,
-      // PAY-1882 step 4: an exception here means the status could not be read.
-      // Report 'unknown' (not a bare 500 with no revocation signal) so the
-      // middleware's fail-closed default applies rather than reading it as viable.
-      revocationStatus: 'unknown' as RevocationStatus,
-      error: 'Failed to check session',
-      code: 'INTERNAL_ERROR',
-      correlationId
-    }, { status: 500 });
-  }
+/**
+ * Ready-to-Use Session Viability Route
+ *
+ * Checks if the current session is viable (valid and not expired).
+ * Used by client-side code to determine if a refresh is needed.
+ *
+ * @example
+ * ```typescript
+ * // app/api/session/viability/route.ts
+ * export { GET } from '@payez/next-mvp/routes/auth/viability';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { revocationFields } from '../../auth/revocation-fields';
+import { NextRequest, NextResponse } from 'next/server';
+import { resolveSessionState } from '../../server/auth';
+import {
+  getSession as getRedisSession,
+  getBetterAuthSession as getBetterAuthRedisSession,
+} from '../../lib/session-store';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
+import { tokenLogId } from '../../lib/token-log-id';
+import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
+
+/**
+ * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
+ */
+async function getTenantRequiresTwoFactor(): Promise<boolean> {
+  try {
+    const config = await getIDPClientConfig();
+    return config.authSettings?.require2FA ?? true; // Default to true for security
+  } catch {
+    console.warn('[VIABILITY] Could not get client config, defaulting tenantRequiresTwoFactor to true');
+    return true;
+  }
+}
+
+/**
+ * Which 2FA methods the TENANT permits — cards 141688 + 141741.
+ *
+ * WHY THIS IS HERE: this endpoint answered "is 2FA required, and is it done?"
+ * and said nothing about WITH WHAT. Both the middleware gate and the
+ * verify-code page call this route, and NEITHER had any method data — so
+ * nothing in the system asked whether the user CAN complete the challenge it
+ * is about to demand. A user whose tenant allows only `totp`, with no
+ * authenticator enrolled, is sent to a page that offers email and sms.
+ *
+ * ⚠ THIS IS NOT A COMPLETION SIGNAL AND MUST NEVER BE READ AS ONE.
+ * It says what the tenant PERMITS. It says nothing about what the user has
+ * enrolled, and nothing about whether they have verified. The invariant
+ * (QAPert, acceptance J2/J5) is: METHOD-PRESENCE IS NOT VERIFIED. A user with
+ * one method is still challenged and still gated until they actually verify.
+ * `userHasCompletedTenantTwoFactorRequirements` remains the only field that
+ * answers "are they through".
+ *
+ * STILL MISSING, deliberately not guessed here: the ENROLLED set. That lives
+ * behind /api/mfa/methods and needs a call this route does not currently make.
+ * Allowed-only closes the "offered a method the tenant forbids" half; it does
+ * NOT close "has nothing enrolled and no way to enrol". Both halves are named
+ * in the cards so neither gets lost.
+ *
+ * NULL MEANS UNKNOWN — IT DOES NOT MEAN "NONE", AND IT DOES NOT MEAN
+ * "email and sms". If the client config cannot be read we do not know what the
+ * tenant permits, and every available guess is wrong in a way that matters:
+ *
+ *   - guessing ['email','sms'] fails OPEN. On a totp-only tenant that offers
+ *     the user two methods the tenant forbids — which is defect 141688 itself,
+ *     re-created by its own fix during a config outage.
+ *   - guessing [] fails CLOSED but locks the user out of a challenge they may
+ *     be perfectly able to complete.
+ *
+ * So we report the truth (we don't know) and let the consumer decide, rather
+ * than encoding a guess that reads like a measurement. Same reasoning as the
+ * nullable require_2fa fix: "absent" has to be expressible, or callers cannot
+ * tell a real value from a default.
+ *
+ * No local default. 257255 UPDATE: allowed2FAMethods is now OPTIONAL on
+ * AuthSettings - the config mapper no longer substitutes ['email','sms'] when
+ * the document carries no policy, because that made "no policy" and "exactly
+ * these methods" indistinguishable. So absent now correctly reaches this
+ * function as undefined and is reported as UNKNOWN (null), which is what this
+ * function's own contract already said it wanted. Before the change it would
+ * have returned the mapper's fabrication AS IF IT WERE THE TENANT'S VALUE.
+ */
+async function getTenantAllowed2FAMethods(): Promise<string[] | null> {
+  try {
+    const config = await getIDPClientConfig();
+    // `?? null` is the whole point: undefined means the document carried no
+    // policy, and this function reports UNKNOWN rather than guessing.
+    return config.authSettings.allowed2FAMethods ?? null;
+  } catch {
+    console.warn('[VIABILITY] Could not get client config — reporting allowed 2FA methods as UNKNOWN (null), not guessing');
+    return null;
+  }
+}
+
+/**
+ * Resolve the client id reported to the caller.
+ *
+ * Was: `session?.idpClientId || process.env.IDP_CLIENT_ID || ''`. Two defects,
+ * both of the "report a confident value where the truth is unknown" family that
+ * card 221076 was about:
+ *
+ * 1. `|| ''` made "we do not know this session's client" indistinguishable from
+ *    "the client id is blank". Callers cannot tell absence from a known-empty
+ *    value, so nothing can react to the former. Absence is now `null`, which is
+ *    representable — and still falsy, so existing `if (!clientId)` guards behave
+ *    exactly as before.
+ *
+ * 2. The env fallback SILENTLY substitutes the deployment's default client for a
+ *    session whose own client is unknown. On a multi-tenant IDP that is a
+ *    cross-tenant wrong answer, not a default. It is kept for single-tenant
+ *    deployments that rely on it, but it now says so in the log rather than
+ *    passing the substitution off as the session's own identity.
+ */
+function resolveClientId(sessionClientId: string | undefined): string | null {
+  if (sessionClientId) return sessionClientId;
+
+  const envClientId = process.env.IDP_CLIENT_ID;
+  if (envClientId) {
+    console.warn(
+      '[VIABILITY_ROUTE] session carries no idpClientId - substituting IDP_CLIENT_ID ' +
+        'from the environment. On a multi-tenant deployment this is a DIFFERENT client ' +
+        'than the session belongs to.'
+    );
+    return envClientId;
+  }
+
+  return null;
+}
+
+/**
+ * GET /api/session/viability - Check if session is viable
+ *
+ * Returns:
+ * - viable: boolean - Whether the session can be used
+ * - needsRefresh: boolean - Whether a refresh is recommended
+ * - expiresIn: number - Seconds until token expires
+ */
+export async function GET(req: NextRequest) {
+  try {
+    // PAY-2216: ask for the session's STATE, not a session-or-null. A null used to cover a store outage, a deleted
+    // session and no cookie alike, so this route answered 'No session found' to all three and the middleware could
+    // never clear a dead cookie (it must not clear on an outage). See SessionState in server/auth.
+    const sessionState = await resolveSessionState(req);
+
+    if (sessionState.state === 'unknown') {
+      // The store did not answer. NOT a statement about the session: never stale, never 'No session found'.
+      // Same shape as this route's catch (PAY-1882 step 4): 'unknown' revocation -> the middleware's fail-closed
+      // path, a non-OK answer -> service_error, which never clears cookies.
+      console.warn('[VIABILITY] Session store unavailable - session state unknown');
+      return NextResponse.json({
+        viable: false,
+        needsRefresh: false,
+        authenticated: false,
+        revocationStatus: 'unknown' as RevocationStatus,
+        unavailable: true, // PAY-2339: a reader of this JSON gets the hold signal (the response is non-OK, so the middleware holds as service_error)
+        error: 'Session store unavailable',
+        code: 'STORE_UNAVAILABLE'
+      }, { status: 500 });
+    }
+
+    if (sessionState.state === 'missing') {
+      // A VERIFIED cookie and a store that answered "not here". The existing stale shape, so the middleware's
+      // stale_session arm (PAY-2216 / 4.5.4) clears it.
+      console.warn('[VIABILITY] Stale cookie detected - verified cookie, session not in Redis');
+      return NextResponse.json({
+        viable: false,
+        needsRefresh: false,
+        authenticated: false,
+        sessionTokenId: tokenLogId(sessionState.sessionToken), // PAY-1481: a correlation id, never the token
+        reason: 'Stale session - cookie exists but session not found in Redis'
+      });
+    }
+
+    if (sessionState.state === 'none') {
+      return NextResponse.json({
+        viable: false,
+        needsRefresh: false,
+        authenticated: false,
+        reason: 'No session found'
+      });
+    }
+
+    const baSession = sessionState.session;
+
+    const token = baSession as any;
+    const sessionToken = baSession.session?.token;
+
+    // Try the canonical session-store first; fall back to the Better-Auth-keyed
+    // Redis record (`ba:{appSlug}:{token}`) when the canonical lookup misses.
+    // Without the fallback, any consumer that wrote a BA session via the OAuth
+    // callback path or dev-login and didn't separately populate the canonical
+    // store would land here with a "Stale session" verdict, even though the BA
+    // stack just resolved the cookie cleanly. Keeps the two viability impls
+    // (this route + `api-handlers/session/viability.ts`) in lockstep.
+    let session = sessionToken ? await getRedisSession(sessionToken) : null;
+    if (sessionToken && !session) {
+      session = await getBetterAuthRedisSession(sessionToken);
+      if (session) {
+        console.log('[VIABILITY] Found session in Better Auth store (fallback)');
+      }
+    }
+
+    // CRITICAL: Detect stale cookie state (cookie exists but neither store has the session)
+    if (sessionToken && !session) {
+      console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
+      return NextResponse.json({
+        viable: false,
+        needsRefresh: false,
+        authenticated: false,
+        sessionTokenId: tokenLogId(sessionToken), // PAY-1481: a correlation id, never the token; middleware only needs presence to clear the stale cookie
+        reason: 'Stale session - cookie exists but session not found in Redis'
+      });
+    }
+
+    // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
+    // See the SessionData.nextStep doc. This is the field that tells the gate
+    // whether the user CAN complete a challenge; without it both consumers were
+    // sending zero-method users to a page they had no way to act on.
+    //
+    // Declared once, here, above every return: `session` is settled by this
+    // point, and all three authenticated responses must carry the SAME value.
+    // Deriving it per-branch would let the paths drift apart silently.
+    //
+    // NO `?? null` HERE, DELIBERATELY — and this is the whole safety argument:
+    //
+    //   undefined = we never captured it. Every session minted BEFORE this
+    //               change is in that state, and there are live ones in Redis
+    //               right now. JSON.stringify omits the key, so the consumer
+    //               sees no field and knows it is uninformed.
+    //   null      = the IDP affirmatively said "nothing outstanding".
+    //
+    // Collapsing the first into the second with `?? null` would tell the gate
+    // "fully authenticated, nothing to do" about every pre-existing session —
+    // including a zero-method user who must be sent to enrol. That is a
+    // fail-open on the entire existing session population, produced by a
+    // default that reads like a measurement. Same mistake as the nullable
+    // require_2fa case: absent has to stay expressible.
+    const nextStep = session?.nextStep;
+
+    /**
+     * 266007 — port the sibling's CRITICAL override (api-handlers/session/
+     * viability.ts:82-86) into this, the impl consumers actually MOUNT.
+     * An OAuth session whose callback set mfaVerified === false because no
+     * refresh_token was issued ALWAYS needs 2FA completion, whatever the
+     * tenant config says — completing 2FA is how it obtains one.
+     *
+     * STRICT === false, deliberately: an ABSENT mfaVerified (every session
+     * minted before that field existed) is not a signal, and treating it as
+     * one would force-rechallenge the entire existing session population.
+     *
+     * *** R807 (BAPert, card 362550) - WHY THE `=== false` TEST ALONE NO LONGER
+     * CARRIES THAT INTENT, AND WHAT RESTORES IT. ***
+     *
+     * The intent above is right, but by the time a session reaches here the
+     * distinction it depends on IS ALREADY GONE: every construction site
+     * (session-store, decode-session, token-lifecycle x2, SessionModel) collapses
+     * an absent mfaVerified to `false` via `?? false`. So `=== false` had stopped
+     * meaning "the callback affirmatively said false" and had come to mean
+     * "affirmatively false OR never knew" - i.e. the exact mass re-challenge this
+     * comment says it is preventing. The guard read as strict while behaving as
+     * permissive, because the collapse happens upstream and out of sight.
+     *
+     * R807 keeps `mfaVerified` fail-closed at all five sites (removing `?? false`
+     * would be an AUTH BYPASS - a session that never proved MFA read as having
+     * proved it) and gives THIS question its own signal instead. So the test is
+     * now two parts:
+     *
+     *   mfaSignalPresent === true  -> the producer really did emit a value, so the
+     *                                 `false` below is a MEASUREMENT. Fire.
+     *   absent / false             -> LEGACY session (minted before the signal
+     *                                 existed) or a path with no IDP tokens at all.
+     *                                 NOT a signal. Do NOT force a re-challenge.
+     *
+     * That absent-means-do-not-fire read is the migration behaviour, and it is
+     * what preserves this comment's original guarantee verbatim through rollout:
+     * on the day this ships, EVERY existing session has no signal and none of them
+     * is re-challenged.
+     *
+     * *** AND IT IS SAFE ONLY BECAUSE IT IS CONFINED HERE. *** mfaSignalPresent is
+     * permissive by construction - it can only ever SUPPRESS this override. It must
+     * never reach a path that grants access; gate those on `mfaVerified`, which is
+     * still fail-closed everywhere. R807 is void if this signal escapes into an
+     * auth decision.
+     *
+     * Declared once here, like nextStep above, so the three authenticated
+     * responses cannot drift apart. Feeds the legacy `requires2FA` field the
+     * middleware actually gates on; `tenantRequiresTwoFactor` stays pure —
+     * it names TENANT policy, and this override is not tenant state.
+     */
+    const oauthSessionNeedsTwoFactor =
+      session?.mfaSignalPresent === true &&
+      session?.mfaVerified === false &&
+      !(session.idpRefreshToken || (session as any)?.refreshToken);
+
+    // --- Session revocation status (PAY-1882 step 4 producer half) ---
+    /*
+     * Resolve the four-state revocation status for this user (BAPert 66320).
+     * Read it HERE, above every authenticated return, so all three responses
+     * carry the SAME value - the same discipline as nextStep above.
+     *
+     * The middleware fails CLOSED by default on 'unknown' (a failed Vibe read)
+     * and always on 'revoked'; 'active' and 'not_configured' stay viable. A
+     * consumer that does NOT read revocationStatus is unaffected - absent is not
+     * revoked - so shipping this changes nothing for them until they opt in.
+     */
+    let revocationStatus: RevocationStatus = 'not_configured';
+    if (session) {
+      // BAPert 66480 condition 2 / ruling (ii) 66700: the numeric IdP id comes from
+      // the token's own `sub` claim FIRST (session.userId can be an email).
+      const revocationUserId = resolveNumericIdpUserId(session, (session as any).idpAccessToken);
+      if (revocationUserId > 0) {
+        try {
+          revocationStatus = await getRevocationStatus(revocationUserId, sessionToken);
+        } catch {
+          // getRevocationStatus does not throw by contract, but never let a
+          // revocation probe take down the viability answer: fail closed.
+          revocationStatus = 'unknown';
+        }
+      } else {
+        // N1 (NightHawk 66392): a session exists but carries no usable numeric
+        // IdP id, so the check could not run -> 'unknown' (could not determine),
+        // NOT 'not_configured' (no revocation source).
+        // BAPert 66480 condition 1: emit ONE WARN (shape only) so a non-numeric
+        // id surfaces as a log line, not an unexplained sign-out.
+        revocationStatus = warnNonNumericUserId(sessionToken, session.userId);
+      }
+    }
+
+    // Check access token expiry
+    const now = Math.floor(Date.now() / 1000);
+    // 240654 addendum 2: fall back to the Redis session's own expiry.
+    //
+    // The first two reads come off the Better Auth session OBJECT. A Path-B
+    // synthetic session — the shape server/auth.ts builds for a legacy JWS
+    // session — carries NEITHER: it is `{session:{token}, user:{...}}` with no
+    // accessTokenExpires and no exp. So every legacy session fell into the
+    // "no expiry info" branch below and answered needsRefresh:true on EVERY
+    // viability read from the moment of login, while the token was in fact
+    // fresh (15-minute TTL measured). Benign for the viable/authenticated
+    // verdict, but it recommends a refresh constantly, which is pure perf
+    // noise and multiplies exposure to the empty-clientId refresh path (223542).
+    //
+    // lib/session-store puts the real value on the session as
+    // idpAccessTokenExpires, in MILLISECONDS (better-auth.ts:784 sets
+    // `Date.now() + expires_in * 1000`). The other two sources are in SECONDS.
+    // Mixing units here would be a silent disaster, so note that the
+    // normalisation below (`> 1e12 ? /1000 : as-is`) already discriminates
+    // them by magnitude: a seconds timestamp is ~1.7e9, a milliseconds one
+    // ~1.7e12. This fallback is therefore safe in either unit, and that
+    // existing normaliser is load-bearing for it -- do not remove it.
+    const accessTokenExpires =
+      (token as any).accessTokenExpires ||
+      token.exp ||
+      (session as any)?.idpAccessTokenExpires;
+
+    if (!accessTokenExpires) {
+      // No expiry info, assume viable but recommend refresh
+      const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
+      // Cards 141688/141741 — see getTenantAllowed2FAMethods. NOT a completion signal.
+      const tenantAllowed2FAMethods = await getTenantAllowed2FAMethods();
+
+      // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
+      const mfaExpiresAt = session?.mfaExpiresAt || 0;
+      const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+      // Check mfaVerified (normalized name) with fallback to twoFactorComplete for compatibility
+      const mfaVerifiedInSession = session?.mfaVerified ?? false;
+
+      // User has completed 2FA requirements if: they verified AND it hasn't expired
+      const userHasCompletedTenantTwoFactorRequirements = mfaVerifiedInSession && !mfaExpired;
+
+      // userStillNeedsTwoFactor = inverse of completed (matches session callback logic)
+      const userStillNeedsTwoFactor = !userHasCompletedTenantTwoFactorRequirements;
+
+      return NextResponse.json({
+        viable: true,
+        needsRefresh: true,
+        authenticated: true,
+        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
+        // Session revocation (PAY-1882 step 4): the four-state status, plus the
+        // boolean the middleware's existing force-invalid branch already reads.
+        revocationStatus,
+        ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
+        // Clear names for middleware decision-making
+        tenantRequiresTwoFactor,
+        userHasCompletedTenantTwoFactorRequirements,
+        userStillNeedsTwoFactor,
+        tenantAllowed2FAMethods,
+        nextStep,
+        // Legacy field names for backwards compatibility
+        requires2FA: tenantRequiresTwoFactor || oauthSessionNeedsTwoFactor,
+        twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
+        accessTokenExpired: false,
+        reason: 'No expiry information'
+      });
+    }
+
+    // Convert to seconds if needed
+    const expiryTime = accessTokenExpires > 1000000000000
+      ? Math.floor(accessTokenExpires / 1000)
+      : accessTokenExpires;
+
+    const expiresIn = expiryTime - now;
+    const isExpired = expiresIn <= 0;
+    const needsRefresh = expiresIn <= 300; // 5 minutes buffer
+
+    // Check if we have refresh capability (check normalized field name first)
+    const hasRefreshToken = !!(session?.idpRefreshToken || (session as any)?.refreshToken || (token as any).refreshToken);
+
+    // CLEAR NAMING: Tenant-wide 2FA requirement from client config
+    const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
+    // Cards 141688/141741 — see getTenantAllowed2FAMethods. NOT a completion signal.
+    const tenantAllowed2FAMethods = await getTenantAllowed2FAMethods();
+
+    // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
+    // The session may have mfaVerified=true from days ago, but if mfaExpiresAt
+    // has passed, we must treat 2FA as incomplete to force re-verification.
+    const mfaExpiresAt = session?.mfaExpiresAt || 0;
+    const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+    // Check mfaVerified (normalized name) with fallback to twoFactorComplete for compatibility
+    const mfaVerifiedInSession = session?.mfaVerified ?? false;
+
+    // DEBUG: Log what we're reading from the session
+    console.log('[VIABILITY] Session 2FA state:', {
+      sessionToken: tokenLogId(sessionToken),
+      'session.mfaVerified': session?.mfaVerified,
+      'session.twoFactorComplete': (session as any)?.twoFactorComplete,
+      mfaVerifiedInSession,
+      mfaExpiresAt,
+      mfaExpired,
+      hasRefreshToken,
+      'session.idpRefreshToken': !!session?.idpRefreshToken,
+      'session.refreshToken': !!(session as any)?.refreshToken,
+    });
+
+    // CLEAR NAMING: User has completed 2FA requirements if: they verified AND it hasn't expired
+    const userHasCompletedTenantTwoFactorRequirements = mfaVerifiedInSession && !mfaExpired;
+
+    // userStillNeedsTwoFactor = inverse of completed (matches session callback logic)
+    const userStillNeedsTwoFactor = !userHasCompletedTenantTwoFactorRequirements;
+
+    if (mfaExpired && mfaVerifiedInSession) {
+      console.warn('[VIABILITY] MFA expired - forcing 2FA re-verification');
+    }
+
+    if (isExpired) {
+      return NextResponse.json({
+        viable: false,
+        needsRefresh: hasRefreshToken,
+        expiresIn: 0,
+        hasRefreshToken,
+        authenticated: true,
+        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
+        // Clear names
+        tenantRequiresTwoFactor,
+        userHasCompletedTenantTwoFactorRequirements,
+        userStillNeedsTwoFactor,
+        tenantAllowed2FAMethods,
+        nextStep,
+        // Legacy names for backwards compatibility
+        requires2FA: tenantRequiresTwoFactor || oauthSessionNeedsTwoFactor,
+        twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
+        accessTokenExpired: true,
+        reason: 'Token expired',
+        // Session revocation (PAY-1882 step 4) - same value on every return.
+        revocationStatus,
+        ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
+        // RBAC fields
+        roles: session?.roles || [],
+        clientId: resolveClientId(session?.idpClientId),
+      });
+    }
+
+    return NextResponse.json({
+      viable: true,
+      needsRefresh,
+      expiresIn,
+      hasRefreshToken,
+      authenticated: true,
+      sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
+      // Session revocation (PAY-1882 step 4) - same value on every return.
+      revocationStatus,
+      ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
+      // Clear names
+      tenantRequiresTwoFactor,
+      userHasCompletedTenantTwoFactorRequirements,
+      userStillNeedsTwoFactor,
+      tenantAllowed2FAMethods,
+      nextStep,
+      // Legacy names for backwards compatibility
+      requires2FA: tenantRequiresTwoFactor || oauthSessionNeedsTwoFactor,
+      twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
+      accessTokenExpired: false,
+      expiresAt: new Date(expiryTime * 1000).toISOString(),
+      // RBAC fields
+      roles: session?.roles || [],
+      clientId: resolveClientId(session?.idpClientId),
+    });
+  } catch (error) {
+    // PAY-1438: pre-auth probe - the exception text stays in the log, keyed by correlationId.
+    const correlationId = logExceptionWithCorrelation('[VIABILITY_ROUTE] Error checking session viability:', error);
+    return NextResponse.json({
+      viable: false,
+      needsRefresh: false,
+      authenticated: false,
+      // PAY-1882 step 4: an exception here means the status could not be read.
+      // Report 'unknown' (not a bare 500 with no revocation signal) so the
+      // middleware's fail-closed default applies rather than reading it as viable.
+      revocationStatus: 'unknown' as RevocationStatus,
+      error: 'Failed to check session',
+      code: 'INTERNAL_ERROR',
+      correlationId
+    }, { status: 500 });
+  }
 }