@payez/next-mvp 4.1.11 → 4.1.13

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

@@ -1,143 +1,143 @@
-/**
- * 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 { NextRequest, NextResponse } from 'next/server';
-import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
-import { getSession } from '../../server/auth';
-import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
-import { getIDPClientConfig } from '../../lib/idp-client-config';
-
-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 }
-      );
-    }
-
-    // Get session from Better Auth
-    const betterAuthSession = await getSession(req);
-
-    // 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.
-        if (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 ?? (sessionData as any).twoFactorComplete ?? false;
-        const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
-
-        console.log('[VIABILITY] Session 2FA check:', {
-          sessionToken: sessionToken.substring(0, 8) + '...',
-          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)
-          });
-        }
-
-        const response = {
-          authenticated: true,
-          sessionToken, // Include token for middleware tracking
-          // 2FA fields - critical for middleware redirect logic
-          requires2FA, // From cached client config (client-wide setting)
-          twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
-          // 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,
-        sessionToken // Include token to enable 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 { NextRequest, NextResponse } from 'next/server';
+import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
+import { getSession } from '../../server/auth';
+import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+
+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 }
+      );
+    }
+
+    // Get session from Better Auth
+    const betterAuthSession = await getSession(req);
+
+    // 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.
+        if (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 ?? (sessionData as any).twoFactorComplete ?? false;
+        const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
+
+        console.log('[VIABILITY] Session 2FA check:', {
+          sessionToken: sessionToken.substring(0, 8) + '...',
+          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)
+          });
+        }
+
+        const response = {
+          authenticated: true,
+          sessionToken, // Include token for middleware tracking
+          // 2FA fields - critical for middleware redirect logic
+          requires2FA, // From cached client config (client-wide setting)
+          twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
+          // 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,
+        sessionToken // Include token to enable 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 });
+  }
 }

package/src/auth/better-auth.ts

@@ -10,6 +10,8 @@
  */
 
 import 'server-only';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { decodeJwt } from 'jose';   // better-auth's own JWT dependency
 import { betterAuth } from 'better-auth';
 import { nextCookies } from 'better-auth/next-js';
 import { toNextJsHandler } from 'better-auth/next-js';
@@ -18,7 +20,6 @@ import type { IDPClientConfig } from '../lib/idp-client-config';
 import { getIDPClientConfig } from '../lib/idp-client-config';
 import { getAppSlug } from '../lib/app-slug';
 import { getRedis } from '../lib/redis';
-import { SESSION_TTL } from '../lib/session-store';
 
 /**
  * Better Auth social provider config shape.
@@ -35,6 +36,31 @@ export interface BetterAuthSocialProvider {
 /**
  * Build Better Auth social providers from IDP config.
  */
+/**
+ * REQUEST-SCOPED carrier for the provider's raw id_token. Card 138635.
+ *
+ * WHY THIS EXISTS: /api/ExternalAuth/oauth-callback mints an IDP bearer for any
+ * ASSERTED email — we send {provider, email} and nothing verifiable. The fix is
+ * for the IDP to require a provider-signed id_token and verify it itself. This
+ * is the client half: capture the token Better Auth already receives, and
+ * forward it. Additive — the IDP ignores it until its gate flips.
+ *
+ * WHY AsyncLocalStorage AND NOT REDIS (BAPert's ruling: forward, do not persist):
+ * an id_token is credential material. Writing it to the session record would put
+ * it one allow-list edit away from leaking out of /api/internal/session-data,
+ * and it would outlive the request that needed it. ALS scopes it to the single
+ * request, and it is gone when the request ends — nothing to expire, nothing to
+ * scrub, nothing to leak.
+ *
+ * SAFE BY CONSTRUCTION: getUserInfo (which fills this) and the post-callback
+ * exchange (which reads it) both run inside createAuthGetHandler's own request.
+ * VERIFIED, not assumed: better-auth.ts:452 awaits ba.GET(request) — the call
+ * that invokes getUserInfo — and the exchange follows at :465 in the SAME
+ * function. Outside that scope the store is undefined and the body simply omits
+ * id_token, which is the correct additive behaviour.
+ */
+const idTokenScope = new AsyncLocalStorage<{ idToken?: string }>();
+
 export function buildBetterAuthProviders(
   config: IDPClientConfig
 ): Record<string, BetterAuthSocialProvider> {
@@ -68,6 +94,66 @@ export function buildBetterAuthProviders(
       accessType: rawAccessType === 'online' ? 'online' : rawAccessType === 'offline' ? 'offline' : undefined,
       hd: typeof rawHostedDomain === 'string' ? rawHostedDomain : undefined,
     };
+
+    /**
+     * CAPTURE THE RAW id_token — card 138635, client half.
+     *
+     * getUserInfo is the ONLY provider hook that receives the token set.
+     * mapProfileToUser cannot do this: it is handed the DECODED claims, and a
+     * signed JWT cannot be reconstructed from them. We need the raw token
+     * because the IDP must verify the signature ITSELF — a client-decoded
+     * claim is just another assertable field, which is the defect restated.
+     *
+     * ⚠ THIS REPLACES THE DEFAULT google getUserInfo ENTIRELY. Upstream calls
+     * `if (options.getUserInfo) return options.getUserInfo(token)` FIRST and
+     * returns our result verbatim, so everything the default did is now ours to
+     * do — including the `hd` hosted-domain restriction.
+     *
+     * `hd` IS NOT HYPOTHETICAL: it is wired from additionalParams.hd four lines
+     * above, so a client can restrict sign-in to a Google Workspace domain.
+     * Silently dropping it would let ANY Google account into a client that had
+     * restricted itself — a security regression introduced by a security fix.
+     * (Measured on 93: zero clients set it today. That is a reason to be
+     * careful, not a reason to skip it — it is configurable and unused, which
+     * is exactly the state in which a regression goes unnoticed.)
+     *
+     * SO WE DO NOT OVERRIDE AT ALL WHEN `hd` IS SET. We take the hook over
+     * ONLY where upstream's check is PROVABLY VACUOUS — its own first line is
+     * `if (!configuredHostedDomain) return true`. With no hd configured the
+     * default would return true unconditionally, so omitting it is equivalent
+     * by the library's own definition rather than by our judgement.
+     *
+     * A client that DOES set hd keeps the stock provider, keeps its domain
+     * restriction, and simply does not contribute an id_token yet. Losing a
+     * capability is an acceptable cost; silently losing a security control is
+     * not. (better-auth does not re-export the predicate through its public
+     * types, and reimplementing a security check is how two copies drift — so
+     * the honest move is to not need it.)
+     */
+    if (name === 'google' && !providers[name].hd) {
+      (providers[name] as unknown as Record<string, unknown>).getUserInfo = async (token: { idToken?: string }) => {
+        if (!token?.idToken) return null;
+
+        // The only new behaviour: hand the raw token to this request's scope.
+        const scope = idTokenScope.getStore();
+        if (scope) scope.idToken = token.idToken;
+
+        // Mirrors the upstream default (google.mjs) verbatim, minus the hd
+        // branch that cannot fire here — so overriding the hook changes WHAT WE
+        // KEEP, never what we ACCEPT.
+        const claims = decodeJwt(token.idToken) as Record<string, any>;
+        return {
+          user: {
+            id: claims.sub,
+            name: claims.name,
+            email: claims.email,
+            image: claims.picture,
+            emailVerified: claims.email_verified,
+          },
+          data: claims,
+        };
+      };
+    }
   }
 
   return providers;
@@ -124,19 +210,15 @@ export function createBetterAuthInstance(
     // Redis-backed session storage via secondaryStorage
     secondaryStorage: {
       get: async (key: string) => {
-        try {
-          return await getRedis().get(`ba:${appSlug}:${key}`);
-        } catch { return null; }
+        return await getRedis().get(`ba:${appSlug}:${key}`);
       },
       set: async (key: string, value: string, ttl?: number) => {
-        try {
-          const redis = getRedis();
-          if (ttl) {
-            await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
-          } else {
-            await redis.setex(`ba:${appSlug}:${key}`, SESSION_TTL, value);
-          }
-        } catch { /* Redis unavailable — cookie cache still works */ }
+        const redis = getRedis();
+        if (ttl) {
+          await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
+        } else {
+          await redis.setex(`ba:${appSlug}:${key}`, 7 * 24 * 60 * 60, value);
+        }
       },
       delete: async (key: string) => {
         try {
@@ -322,6 +404,30 @@ export async function exchangeOAuthForIdpTokens(
         name,
         image,
         client_id: config.clientSlug || String(config.clientId),
+        /**
+         * Card 138635 — the RAW provider id_token, forwarded verbatim.
+         *
+         * Every other field in this body is an ASSERTION. The endpoint mints an
+         * IDP bearer from them today with no cryptographic check of any kind,
+         * which is why it is a complete authentication bypass and why it has
+         * been publicly reachable for 488 days.
+         *
+         * This field is the only one the IDP can VERIFY: signature against
+         * Google's JWKS, plus iss / exp / aud, and then read email_verified
+         * from the verified claims. Additive — the IDP ignores it until its
+         * gate flips, so this cannot break a login on its own.
+         *
+         * RAW, AND NOTHING DERIVED FROM IT (BAPert's ruling). We do NOT send a
+         * decoded email_verified. A client-computed verification flag is a body
+         * field with a better story: an attacker posts email_verified:true and
+         * the defect is rebuilt one layer up. The IDP verifies for itself or
+         * the fix is theatre.
+         *
+         * Absent when this runs outside the OAuth callback scope — the key is
+         * simply omitted rather than sent null, so "we never captured one" stays
+         * distinguishable from "the provider issued none".
+         */
+        ...(idTokenScope.getStore()?.idToken ? { id_token: idTokenScope.getStore()!.idToken } : {}),
       }),
     });
 
@@ -343,20 +449,8 @@ export async function exchangeOAuthForIdpTokens(
     }
 
     // Build IDP token data
-    // ORIGINAL INTENT: IDP withholds refresh_token until 2FA is complete, so
-    // !hasRefreshToken was a reliable "2FA required" signal.
-    //
-    // BUG [IDP-2FA-BUG]: IDP is currently returning refresh_token on the initial
-    // oauth-callback even for require_2fa tenants that haven't done 2FA yet.
-    // This made !hasRefreshToken=false → requiresTwoFactor=false → mfaVerified=true,
-    // bypassing the 2FA gate entirely.
-    //
-    // FIX: Always set mfaVerified=false on the initial OAuth exchange.
-    // The tenant's require_2fa setting is enforced by the viability endpoint
-    // (tenantRequiresTwoFactor=true), which redirects to verify-code whenever
-    // mfaVerified=false. After real 2FA, transitionTo2FASession() sets it true.
-    // Revert this comment + restore `mfaVerified: !requiresTwoFactor` once the
-    // IDP correctly withholds refresh_token until post-2FA.
+    // CRITICAL: If the IDP withholds refresh_token without setting requiresTwoFactor,
+    // treat missing refresh token as "2FA required" so middleware redirects to verify-code.
     const hasRefreshToken = !!result.refresh_token;
     const requiresTwoFactor = result.user?.requiresTwoFactor ?? result.requiresTwoFactor ?? !hasRefreshToken;
     const idpTokenData = {
@@ -370,21 +464,21 @@ export async function exchangeOAuthForIdpTokens(
       name: result.user?.full_name || result.user?.name || result.name || name,
       image: image,
       roles: result.user?.roles || result.roles || [],
-      mfaVerified: false, // Always false post-OAuth — see IDP-2FA-BUG note above
+      mfaVerified: !requiresTwoFactor,
       idpClientId: result.client_id ? String(result.client_id) : undefined,
       merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
     };
 
     // Store in BA Redis session (for decodeSession)
     baData.idpTokens = idpTokenData;
-    await getRedis().setex(baKey, SESSION_TTL, JSON.stringify(baData));
+    await getRedis().setex(baKey, 7 * 24 * 60 * 60, JSON.stringify(baData));
 
     // Write to canonical session store so refresh handler and token lifecycle can find the tokens.
     // Key format: {sessionPrefix}{token} — same key that getSession() reads from.
     try {
       const { getSessionPrefix } = await import('../lib/app-slug');
       const canonicalKey = `${getSessionPrefix()}${sessionToken}`;
-      await getRedis().setex(canonicalKey, SESSION_TTL, JSON.stringify({
+      await getRedis().setex(canonicalKey, 7 * 24 * 60 * 60, JSON.stringify({
         ...idpTokenData,
         oauthProvider: provider,
       }));
@@ -419,6 +513,12 @@ export async function exchangeOAuthForIdpTokens(
  */
 export function createAuthGetHandler(loginPath: string = '/account-auth/login') {
   return async function GET(request: Request): Promise<Response> {
+    // Card 138635: establish the request-scoped carrier for the provider's raw
+    // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
+    // hook that sees the token) and the exchange below (which forwards it).
+    // Wrapping the whole handler is what makes "never persisted" achievable —
+    // the token exists only for the life of this request.
+    return idTokenScope.run({}, async () => {
     const ba = await getBetterAuthHandler();
     if (!ba) {
       return new Response('Auth handler not configured', { status: 500 });
@@ -463,5 +563,6 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
     }
 
     return response;
+    });
   };
 }

package/src/auth/unauthenticated-routes.ts

@@ -1,3 +1,3 @@
-// src/auth/unauthenticated-routes.ts
-// Re-exporting from route-config for backward compatibility
+// src/auth/unauthenticated-routes.ts
+// Re-exporting from route-config for backward compatibility
 export * from './route-config';