@payez/next-mvp 4.8.0 → 4.8.2

package/src/api-handlers/session/viability.ts

@@ -1,239 +1,239 @@
-/**
- * Session Viability Check API Handler for `@payez/next-mvp`
- *
- * This API route is called by the middleware to securely check if a session is valid.
- */
-
-import { revocationFields } from '../../auth/revocation-fields';
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
-import { resolveSessionState } from '../../server/auth';
-import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
-import { getIDPClientConfig } from '../../lib/idp-client-config';
-import { tokenLogId } from '../../lib/token-log-id';
-import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
-
-export async function GET(req: NextRequest) {
-  try {
-    // Ensure initialization is complete (auth signing secret resolved from IDP)
-    if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
-      try {
-        await ensureInitialized();
-      } catch (error) {
-        // Initialization failed - return 503
-        console.error('[API Viability] Initialization failed - returning 503');
-        return NextResponse.json(
-          {
-            error: 'Service Unavailable',
-            message: 'Authentication service is not properly configured',
-            code: 'AUTH_NOT_INITIALIZED'
-          },
-          { status: 503 }
-        );
-      }
-    }
-
-    // Double-check after initialization attempt
-    if (isInitializationFailed()) {
-      console.error('[API Viability] Initialization failed - returning 503');
-      return NextResponse.json(
-        {
-          error: 'Service Unavailable',
-          message: 'Authentication service is not properly configured',
-          code: 'AUTH_NOT_INITIALIZED'
-        },
-        { status: 503 }
-      );
-    }
-
-    // PAY-2216: the TWIN of routes/auth/viability.ts - same tri-state, same answers, or an app mounting this export
-    // keeps the defect. 'unknown' (store did not answer) is a 5xx and never stale; 'missing' (verified cookie, store
-    // answered "not here") is the stale shape with a token id; 'none' stays { authenticated: false }.
-    const sessionState = await resolveSessionState(req);
-    if (sessionState.state === 'unknown') {
-      console.warn('[VIABILITY] Session store unavailable - session state unknown');
-      return NextResponse.json(
-        { authenticated: false, revocationStatus: 'unknown' as RevocationStatus, unavailable: true, error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' },
-        { status: 500 }
-      );
-    }
-    if (sessionState.state === 'missing') {
-      console.warn('[VIABILITY] Stale cookie detected - verified cookie, session not in Redis');
-      return NextResponse.json({
-        authenticated: false,
-        sessionTokenId: tokenLogId(sessionState.sessionToken) // PAY-1481: correlation id, never the token
-      });
-    }
-    const betterAuthSession = sessionState.state === 'live' ? sessionState.session : null;
-
-    // Debug logging
-    if (!betterAuthSession) {
-      console.warn('[VIABILITY] getSession returned null');
-    }
-
-    const sessionToken = betterAuthSession?.session?.token as string | undefined;
-    if (betterAuthSession && sessionToken) {
-      // Try legacy session store first, then Better Auth format
-      let sessionData = await getRedisSession(sessionToken);
-      if (!sessionData) {
-        // Better Auth stores sessions with ba:{appSlug}:{token} prefix
-        sessionData = await getBetterAuthSession(sessionToken);
-        if (sessionData) {
-          console.log('[VIABILITY] Found session in Better Auth store');
-        }
-      }
-      if (sessionData) {
-        // The session exists in Redis
-
-        // Check if access token is expired (for middleware decision-making)
-        const accessTokenExpires = sessionData.idpAccessTokenExpires || 0;
-        const accessTokenExpired = accessTokenExpires < Date.now();
-
-        // Get requires2FA from cached client config (client-wide setting)
-        let requires2FA = true; // Default to true for security
-        try {
-          const cachedConfig = await getIDPClientConfig();
-          requires2FA = cachedConfig.authSettings?.require2FA ?? true;
-        } catch (e) {
-          console.warn('[API Viability] Could not get client config, defaulting requires2FA to true');
-        }
-
-        // CRITICAL: OAuth sessions without refresh token always need 2FA completion
-        // to obtain a refresh token from the IDP. The OAuth callback sets mfaVerified=false
-        // when no refresh_token is present. This must override the client config.
-        //
-        // *** R807 (BAPert, card 362550) — SECOND OF THE TWO SITES THE SIGNAL IS FOR. ***
-        // The `=== false` below reads as strict but had stopped behaving strictly: every
-        // construction site collapses an ABSENT mfaVerified to `false` (`?? false`), so by
-        // the time it is read here "the callback said false" and "we never knew" are the
-        // same value. This override therefore fired on EVERY session, not on OAuth sessions
-        // that genuinely lack a refresh token.
-        //
-        // The comment at line ~122 of this file already warned that fixing only ONE of the
-        // two viability implementations leaves an app mounting the other one blind. That
-        // applies here verbatim: routes/auth/viability.ts carries the same guard, and both
-        // are publicly exported entry points, so both must gate on the signal or the defect
-        // survives one export over.
-        //
-        // mfaSignalPresent === true -> the producer really emitted a value, so the `false`
-        //                              is a MEASUREMENT. Override.
-        // absent / false            -> LEGACY session (minted before the signal existed) or
-        //                              a path with no IDP tokens. NOT a signal. Do not
-        //                              force a re-challenge.
-        //
-        // *** CONFINED, BY RULING. *** This signal is permissive by construction — it can
-        // only ever SUPPRESS this override, never grant access. Anything that GRANTS must
-        // keep gating on `mfaVerified`, which stays fail-closed at all five sites. R807 is
-        // void if this signal reaches an auth decision.
-        if (
-          sessionData.mfaSignalPresent === true &&
-          sessionData.mfaVerified === false &&
-          !sessionData.idpRefreshToken
-        ) {
-          requires2FA = true;
-        }
-
-        // 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 = sessionData.mfaExpiresAt || 0;
-        const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
-        // Check both field names for compatibility (mfaVerified is the normalized name)
-        const sessionMfaComplete = sessionData.mfaVerified ?? false;
-        const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
-
-        console.log('[VIABILITY] Session 2FA check:', {
-          sessionToken: tokenLogId(sessionToken),
-          mfaVerified: sessionData.mfaVerified,
-          twoFactorComplete: (sessionData as any).twoFactorComplete,
-          sessionMfaComplete,
-          mfaExpired,
-          effectiveTwoFactorComplete,
-        });
-
-        if (mfaExpired && sessionMfaComplete) {
-          console.warn('[API Viability] MFA expired - forcing 2FA re-verification', {
-            mfaExpiresAt: new Date(mfaExpiresAt).toISOString(),
-            now: new Date().toISOString(),
-            hoursExpiredAgo: ((Date.now() - mfaExpiresAt) / (1000 * 60 * 60)).toFixed(1)
-          });
-        }
-
-        // --- Session revocation status (PAY-1882 step 4 producer half) ---
-        // The four-state status (BAPert 66320). 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.
-        let revocationStatus: RevocationStatus = 'not_configured';
-        // 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(sessionData, (sessionData as any).idpAccessToken);
-        if (revocationUserId > 0) {
-          try {
-            revocationStatus = await getRevocationStatus(revocationUserId, sessionToken);
-          } catch {
-            // getRevocationStatus does not throw by contract; fail closed if it ever does.
-            revocationStatus = 'unknown';
-          }
-        } else {
-          // N1 (NightHawk 66392): a session EXISTS but its userId is not a usable
-          // numeric IdP id, so the check could not be run. That is 'unknown'
-          // (could not determine), NOT 'not_configured' (no revocation source) -
-          // the two must not be conflated.
-          // BAPert 66480 condition 1: emit ONE WARN (shape only) per session.
-          revocationStatus = warnNonNumericUserId(sessionToken, sessionData.userId);
-        }
-
-        const response = {
-          authenticated: true,
-          sessionTokenId: tokenLogId(sessionToken), // PAY-1481: correlation id for middleware tracking, never the token
-          // 2FA fields - critical for middleware redirect logic
-          requires2FA, // From cached client config (client-wide setting)
-          twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
-          // 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'
-          // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
-          //
-          // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is
-          // routes/auth/viability.ts, which is what the admin graft mounts.
-          // Both are publicly exported entry points, so both can be a consumer's
-          // only source of this answer. Adding the relay to just one would leave
-          // an app that mounts THIS one still blind to enroll_mfa — the exact
-          // seam these cards are about, reopened one export over.
-          //
-          // 'enroll_mfa' = no USABLE method, the user cannot complete a
-          // challenge. 'mfa_verify' = usable method exists. null = nothing due.
-          // NOT a completion signal: twoFactorComplete still owns that.
-          //
-          // No `?? null`: undefined (never captured — every session minted
-          // before this change) must stay distinguishable from null (the IDP
-          // said nothing is outstanding). Defaulting to null would tell the
-          // gate that every pre-existing session is fully authenticated,
-          // including zero-method users who must be routed to enrol.
-          nextStep: sessionData.nextStep,
-          // Token status for refresh decisions
-          accessTokenExpired,
-          hasRefreshToken: !!sessionData.idpRefreshToken
-        };
-        return NextResponse.json(response);
-      }
-
-      // CRITICAL: Cookie exists but Redis session is missing (stale cookie state)
-      // Return sessionToken so middleware can detect this and clear the stale cookie
-      console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
-      return NextResponse.json({
-        authenticated: false,
-        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null // PAY-1481: presence + correlation for stale cookie detection
-      });
-    }
-
-    // If there's no token at all, it's not authenticated
-    return NextResponse.json({ authenticated: false });
-
-  } catch (error) {
-    console.error('[API Viability] Error checking session viability:', error);
-    return NextResponse.json({ authenticated: false }, { status: 500 });
-  }
+/**
+ * Session Viability Check API Handler for `@payez/next-mvp`
+ *
+ * This API route is called by the middleware to securely check if a session is valid.
+ */
+
+import { revocationFields } from '../../auth/revocation-fields';
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
+import { resolveSessionState } from '../../server/auth';
+import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { tokenLogId } from '../../lib/token-log-id';
+import { getRevocationStatus, warnNonNumericUserId, resolveNumericIdpUserId, type RevocationStatus } from '../../vibe/sessions';
+
+export async function GET(req: NextRequest) {
+  try {
+    // Ensure initialization is complete (auth signing secret resolved from IDP)
+    if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
+      try {
+        await ensureInitialized();
+      } catch (error) {
+        // Initialization failed - return 503
+        console.error('[API Viability] Initialization failed - returning 503');
+        return NextResponse.json(
+          {
+            error: 'Service Unavailable',
+            message: 'Authentication service is not properly configured',
+            code: 'AUTH_NOT_INITIALIZED'
+          },
+          { status: 503 }
+        );
+      }
+    }
+
+    // Double-check after initialization attempt
+    if (isInitializationFailed()) {
+      console.error('[API Viability] Initialization failed - returning 503');
+      return NextResponse.json(
+        {
+          error: 'Service Unavailable',
+          message: 'Authentication service is not properly configured',
+          code: 'AUTH_NOT_INITIALIZED'
+        },
+        { status: 503 }
+      );
+    }
+
+    // PAY-2216: the TWIN of routes/auth/viability.ts - same tri-state, same answers, or an app mounting this export
+    // keeps the defect. 'unknown' (store did not answer) is a 5xx and never stale; 'missing' (verified cookie, store
+    // answered "not here") is the stale shape with a token id; 'none' stays { authenticated: false }.
+    const sessionState = await resolveSessionState(req);
+    if (sessionState.state === 'unknown') {
+      console.warn('[VIABILITY] Session store unavailable - session state unknown');
+      return NextResponse.json(
+        { authenticated: false, revocationStatus: 'unknown' as RevocationStatus, unavailable: true, error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' },
+        { status: 500 }
+      );
+    }
+    if (sessionState.state === 'missing') {
+      console.warn('[VIABILITY] Stale cookie detected - verified cookie, session not in Redis');
+      return NextResponse.json({
+        authenticated: false,
+        sessionTokenId: tokenLogId(sessionState.sessionToken) // PAY-1481: correlation id, never the token
+      });
+    }
+    const betterAuthSession = sessionState.state === 'live' ? sessionState.session : null;
+
+    // Debug logging
+    if (!betterAuthSession) {
+      console.warn('[VIABILITY] getSession returned null');
+    }
+
+    const sessionToken = betterAuthSession?.session?.token as string | undefined;
+    if (betterAuthSession && sessionToken) {
+      // Try legacy session store first, then Better Auth format
+      let sessionData = await getRedisSession(sessionToken);
+      if (!sessionData) {
+        // Better Auth stores sessions with ba:{appSlug}:{token} prefix
+        sessionData = await getBetterAuthSession(sessionToken);
+        if (sessionData) {
+          console.log('[VIABILITY] Found session in Better Auth store');
+        }
+      }
+      if (sessionData) {
+        // The session exists in Redis
+
+        // Check if access token is expired (for middleware decision-making)
+        const accessTokenExpires = sessionData.idpAccessTokenExpires || 0;
+        const accessTokenExpired = accessTokenExpires < Date.now();
+
+        // Get requires2FA from cached client config (client-wide setting)
+        let requires2FA = true; // Default to true for security
+        try {
+          const cachedConfig = await getIDPClientConfig();
+          requires2FA = cachedConfig.authSettings?.require2FA ?? true;
+        } catch (e) {
+          console.warn('[API Viability] Could not get client config, defaulting requires2FA to true');
+        }
+
+        // CRITICAL: OAuth sessions without refresh token always need 2FA completion
+        // to obtain a refresh token from the IDP. The OAuth callback sets mfaVerified=false
+        // when no refresh_token is present. This must override the client config.
+        //
+        // *** R807 (BAPert, card 362550) — SECOND OF THE TWO SITES THE SIGNAL IS FOR. ***
+        // The `=== false` below reads as strict but had stopped behaving strictly: every
+        // construction site collapses an ABSENT mfaVerified to `false` (`?? false`), so by
+        // the time it is read here "the callback said false" and "we never knew" are the
+        // same value. This override therefore fired on EVERY session, not on OAuth sessions
+        // that genuinely lack a refresh token.
+        //
+        // The comment at line ~122 of this file already warned that fixing only ONE of the
+        // two viability implementations leaves an app mounting the other one blind. That
+        // applies here verbatim: routes/auth/viability.ts carries the same guard, and both
+        // are publicly exported entry points, so both must gate on the signal or the defect
+        // survives one export over.
+        //
+        // mfaSignalPresent === true -> the producer really emitted a value, so the `false`
+        //                              is a MEASUREMENT. Override.
+        // absent / false            -> LEGACY session (minted before the signal existed) or
+        //                              a path with no IDP tokens. NOT a signal. Do not
+        //                              force a re-challenge.
+        //
+        // *** CONFINED, BY RULING. *** This signal is permissive by construction — it can
+        // only ever SUPPRESS this override, never grant access. Anything that GRANTS must
+        // keep gating on `mfaVerified`, which stays fail-closed at all five sites. R807 is
+        // void if this signal reaches an auth decision.
+        if (
+          sessionData.mfaSignalPresent === true &&
+          sessionData.mfaVerified === false &&
+          !sessionData.idpRefreshToken
+        ) {
+          requires2FA = true;
+        }
+
+        // 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 = sessionData.mfaExpiresAt || 0;
+        const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+        // Check both field names for compatibility (mfaVerified is the normalized name)
+        const sessionMfaComplete = sessionData.mfaVerified ?? false;
+        const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
+
+        console.log('[VIABILITY] Session 2FA check:', {
+          sessionToken: tokenLogId(sessionToken),
+          mfaVerified: sessionData.mfaVerified,
+          twoFactorComplete: (sessionData as any).twoFactorComplete,
+          sessionMfaComplete,
+          mfaExpired,
+          effectiveTwoFactorComplete,
+        });
+
+        if (mfaExpired && sessionMfaComplete) {
+          console.warn('[API Viability] MFA expired - forcing 2FA re-verification', {
+            mfaExpiresAt: new Date(mfaExpiresAt).toISOString(),
+            now: new Date().toISOString(),
+            hoursExpiredAgo: ((Date.now() - mfaExpiresAt) / (1000 * 60 * 60)).toFixed(1)
+          });
+        }
+
+        // --- Session revocation status (PAY-1882 step 4 producer half) ---
+        // The four-state status (BAPert 66320). 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.
+        let revocationStatus: RevocationStatus = 'not_configured';
+        // 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(sessionData, (sessionData as any).idpAccessToken);
+        if (revocationUserId > 0) {
+          try {
+            revocationStatus = await getRevocationStatus(revocationUserId, sessionToken);
+          } catch {
+            // getRevocationStatus does not throw by contract; fail closed if it ever does.
+            revocationStatus = 'unknown';
+          }
+        } else {
+          // N1 (NightHawk 66392): a session EXISTS but its userId is not a usable
+          // numeric IdP id, so the check could not be run. That is 'unknown'
+          // (could not determine), NOT 'not_configured' (no revocation source) -
+          // the two must not be conflated.
+          // BAPert 66480 condition 1: emit ONE WARN (shape only) per session.
+          revocationStatus = warnNonNumericUserId(sessionToken, sessionData.userId);
+        }
+
+        const response = {
+          authenticated: true,
+          sessionTokenId: tokenLogId(sessionToken), // PAY-1481: correlation id for middleware tracking, never the token
+          // 2FA fields - critical for middleware redirect logic
+          requires2FA, // From cached client config (client-wide setting)
+          twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
+          // 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'
+          // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
+          //
+          // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is
+          // routes/auth/viability.ts, which is what the admin graft mounts.
+          // Both are publicly exported entry points, so both can be a consumer's
+          // only source of this answer. Adding the relay to just one would leave
+          // an app that mounts THIS one still blind to enroll_mfa — the exact
+          // seam these cards are about, reopened one export over.
+          //
+          // 'enroll_mfa' = no USABLE method, the user cannot complete a
+          // challenge. 'mfa_verify' = usable method exists. null = nothing due.
+          // NOT a completion signal: twoFactorComplete still owns that.
+          //
+          // No `?? null`: undefined (never captured — every session minted
+          // before this change) must stay distinguishable from null (the IDP
+          // said nothing is outstanding). Defaulting to null would tell the
+          // gate that every pre-existing session is fully authenticated,
+          // including zero-method users who must be routed to enrol.
+          nextStep: sessionData.nextStep,
+          // Token status for refresh decisions
+          accessTokenExpired,
+          hasRefreshToken: !!sessionData.idpRefreshToken
+        };
+        return NextResponse.json(response);
+      }
+
+      // CRITICAL: Cookie exists but Redis session is missing (stale cookie state)
+      // Return sessionToken so middleware can detect this and clear the stale cookie
+      console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
+      return NextResponse.json({
+        authenticated: false,
+        sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null // PAY-1481: presence + correlation for stale cookie detection
+      });
+    }
+
+    // If there's no token at all, it's not authenticated
+    return NextResponse.json({ authenticated: false });
+
+  } catch (error) {
+    console.error('[API Viability] Error checking session viability:', error);
+    return NextResponse.json({ authenticated: false }, { status: 500 });
+  }
 }