@payez/next-mvp 3.0.0

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

@@ -0,0 +1,166 @@
+/**
+ * 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 } from '../../lib/session-store';
+import { getToken } from 'next-auth/jwt';
+import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
+import { getJwtCookieName } from '../../lib/app-slug';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+
+/**
+ * Get NextAuth secret from IDP config (cached).
+ * NEVER use process.env.NEXTAUTH_SECRET directly - it may not be set.
+ */
+async function getNextAuthSecret(): Promise<string> {
+  const config = await getIDPClientConfig();
+  return config.nextAuthSecret || '';
+}
+
+export async function GET(req: NextRequest) {
+  try {
+    // Ensure initialization is complete
+    if (!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 secret from IDP config (same source as session.ts and token-lifecycle.ts)
+    const secret = await getNextAuthSecret();
+    if (!secret) {
+      console.error('[API Viability] NEXTAUTH_SECRET not available from IDP config');
+      return NextResponse.json(
+        {
+          error: 'Service Unavailable',
+          message: 'Authentication service is not properly configured',
+          code: 'AUTH_NOT_INITIALIZED'
+        },
+        { status: 503 }
+      );
+    }
+
+    // getToken is the recommended way to get the JWT from a request
+    const cookieName = getJwtCookieName();
+    const token = await getToken({ req, secret, cookieName });
+
+    // Debug logging to diagnose AKS-specific issues
+    if (!token) {
+      const cookieHeader = req.headers.get('cookie') || '';
+      const hasCookie = cookieHeader.includes(cookieName);
+      const cookieMatch = cookieHeader.match(new RegExp(`${cookieName}=([^;]*)`));
+      const cookieValue = cookieMatch ? cookieMatch[1] : null;
+      console.warn('[VIABILITY] getToken returned null:', {
+        cookieName,
+        hasCookie,
+        cookieValueLength: cookieValue?.length || 0,
+        cookieValuePreview: cookieValue ? cookieValue.substring(0, 30) + '...' : 'EMPTY',
+        secretLength: secret.length,
+        secretPreview: secret ? secret.substring(0, 10) + '...' : 'EMPTY',
+      });
+    }
+
+    // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+    const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
+    if (token && sessionToken) {
+      const sessionData = await getSession(sessionToken);
+      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 (not session)
+        // This is a client-wide setting from the broker handshake
+        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: 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/api-handlers/test/force-expire.ts

@@ -0,0 +1,67 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+import { getSession, updateSession } from '../../lib/session-store';
+import { getJwtCookieName } from '../../lib/app-slug';
+
+/**
+ * Force-expire access token for testing refresh flow.
+ *
+ * Sets the access token expiry to 2 minutes in the past,
+ * which will trigger a refresh on the next API call.
+ *
+ * Usage in consuming app:
+ * ```typescript
+ * // app/api/test/force-expire/route.ts
+ * export { POST } from '@payez/next-mvp/api-handlers/test/force-expire';
+ * ```
+ */
+export const POST = async (req: NextRequest) => {
+  try {
+    const secret = process.env.NEXTAUTH_SECRET;
+    if (!secret) {
+      return NextResponse.json({ success: false, error: 'NEXTAUTH_SECRET not configured' }, { status: 500 });
+    }
+
+    const cookieName = getJwtCookieName();
+    const token = await getToken({ req, secret, cookieName });
+
+    let sessionToken = token?.redisSessionId as string | undefined;
+    if (!sessionToken) {
+      const headerSessionToken = req.headers.get('x-session-token') || req.headers.get('X-Session-Token');
+      if (headerSessionToken) {
+        sessionToken = headerSessionToken;
+      } else {
+        console.warn('[TEST_EXPIRE] No session token in JWT cookie or X-Session-Token header');
+        return NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
+      }
+    }
+
+    const session = await getSession(sessionToken);
+    if (!session) {
+      return NextResponse.json({ success: false, error: 'Session not found' }, { status: 404 });
+    }
+
+    const now = Date.now();
+    const forced = now - (2 * 60 * 1000); // two minutes ago
+    const prev = session.idpAccessTokenExpires || null;
+
+    await updateSession(sessionToken, { idpAccessTokenExpires: forced });
+
+    console.log('[TEST_EXPIRE] Forced access token expiry for session', {
+      sessionToken: sessionToken.substring(0, 8) + '...',
+      previous: prev ? new Date(prev).toISOString() : null,
+      newExpiry: new Date(forced).toISOString()
+    });
+
+    return NextResponse.json({
+      success: true,
+      previous: prev,
+      previousIso: prev ? new Date(prev).toISOString() : null,
+      newExpiry: forced,
+      newExpiryIso: new Date(forced).toISOString()
+    });
+  } catch (e) {
+    console.error('[TEST_EXPIRE] Error:', e);
+    return NextResponse.json({ success: false, error: e instanceof Error ? e.message : String(e) }, { status: 500 });
+  }
+};

package/src/auth/auth-decision.ts

@@ -0,0 +1,230 @@
+/**
+ * Auth Decision Engine - Pure function for middleware auth flow
+ * 
+ * This module provides a deterministic decision tree for authentication middleware.
+ * All auth flow logic is centralized here for testability and maintainability.
+ */
+
+// Input types for the decision engine
+export interface AuthContext {
+  pathname: string;
+  isPublicRoute: boolean;
+  isLoginPage: boolean;
+  searchParams: URLSearchParams;
+  sessionPointer: {
+    exists: boolean;
+    sessionToken?: string;
+    expired?: boolean;
+  };
+  sessionStatus: {
+    exists: boolean | null; // null = check failed/timeout
+    forceInvalid: boolean | null; // null = check failed/timeout
+    requires2FA: boolean;
+    twoFactorComplete: boolean;
+  };
+  circuitBreakerOpen: boolean;
+}
+
+// Output types for the decision engine
+export type AuthAction = 
+  | { type: 'allow' }
+  | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
+  | { type: 'service_error'; reason: string };
+
+/**
+ * Main decision function - pure, testable, deterministic
+ */
+export function makeAuthDecision(context: AuthContext): AuthAction {
+  const {
+    pathname,
+    isPublicRoute,
+    isLoginPage,
+    searchParams,
+    sessionPointer,
+    sessionStatus,
+    circuitBreakerOpen
+  } = context;
+
+  // SAFEGUARD: Never use auth pages as callback URLs to prevent redirect loops
+  const safeCallbackUrl = pathname.startsWith('/account-auth/') ? '/' : pathname;
+
+  // Public routes are allowed, but we need to check login page separately
+  if (isPublicRoute && !isLoginPage) {
+    // For non-login public routes, check if authenticated user needs 2FA
+    if (sessionPointer.exists && sessionStatus.exists && sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
+      // Skip redirect for verify-code page
+      if (pathname === '/account-auth/verify-code') {
+        return { type: 'allow' };
+      }
+    }
+    return { type: 'allow' };
+  }
+
+  // Circuit breaker open - redirect to login with service unavailable
+  if (circuitBreakerOpen) {
+    if (isLoginPage) {
+      return { type: 'allow' }; // Let them see login page
+    }
+    return {
+      type: 'redirect',
+      location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen',
+      reason: 'CircuitBreakerOpen',
+      clearCookies: true
+    };
+  }
+
+  // No session pointer (JWT cookie) - need to login
+  if (!sessionPointer.exists) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    // Redirect root to configured URL for unauthenticated users
+    if (pathname === '/') {
+      const unauthUrl = process.env.UNAUTHENTICATED_REDIRECT_URL || '/account-auth/login';
+      return {
+        type: 'redirect',
+        location: unauthUrl,
+        reason: 'unauthenticated_root_redirect'
+      };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
+      reason: 'no_session_pointer'
+    };
+  }
+
+  // Redis/service errors - can't verify session
+  if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
+    return { 
+      type: 'service_error', 
+      reason: 'redis_unavailable' 
+    };
+  }
+
+  // Session force invalidated - need fresh login
+  if (sessionStatus.forceInvalid) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=force_invalidated`,
+      reason: 'force_invalidated',
+      clearCookies: true
+    };
+  }
+
+  // Stale session (cookie exists but not in Redis) - need fresh login
+  if (!sessionStatus.exists) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&reason=stale_session`,
+      reason: 'stale_session',
+      clearCookies: true
+    };
+  }
+
+  // PRIORITIZE 2FA: If session exists and 2FA is required but not complete, handle this before token-expired logic
+  if (sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
+    console.log('[MIDDLEWARE-DECISION] 2FA required but not complete', {
+      pathname,
+      isLoginPage,
+      sessionExists: sessionStatus.exists,
+      sessionToken: sessionPointer.sessionToken?.substring(0, 8) + '...'
+    });
+    
+    // Already on the 2FA page
+    if (pathname === '/account-auth/verify-code') {
+      console.log('[MIDDLEWARE-DECISION] Already on verify-code page, allowing');
+      return { type: 'allow' };
+    }
+    // If user is on the login page, send them to verify-code with the original callback
+    if (isLoginPage) {
+      const callbackUrl = searchParams.get('callbackUrl') || '/';
+      // CRITICAL FIX: Never use auth pages as callback URLs
+      const safeCallbackUrl = callbackUrl.startsWith('/account-auth/') ? '/' : callbackUrl;
+      console.log('[MIDDLEWARE-DECISION] On login page with 2FA incomplete, redirecting to verify-code', {
+        originalCallback: callbackUrl,
+        safeCallback: safeCallbackUrl,
+        originalUrl: pathname
+      });
+      return {
+        type: 'redirect',
+        location: `/account-auth/verify-code?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
+        reason: '2fa_required_login_redirect'
+      };
+    }
+    // For protected routes, allow middleware to proceed (it may refresh tokens); pages will enforce 2FA
+    console.log('[MIDDLEWARE-DECISION] Protected route with incomplete 2FA, allowing middleware to handle');
+    return { type: 'allow' };
+  }
+
+  // Token expired - redirect to login (let NextAuth handle refresh)
+  if (sessionPointer.expired) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return {
+      type: 'redirect',
+      location: `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}&error=SessionExpired`,
+      reason: 'token_expired'
+    };
+  }
+
+  // Authenticated root path should land on dashboards
+  if (pathname === '/') {
+    return {
+      type: 'redirect',
+      location: '/',
+      reason: 'authenticated_root_redirect'
+    };
+  }
+
+  // Valid session but 2FA required and not complete - more intelligent handling
+  if (sessionStatus.requires2FA && !sessionStatus.twoFactorComplete) {
+    if (pathname === '/account-auth/verify-code') {
+      return { type: 'allow' }; // Already on 2FA page
+    }
+
+    // For login page, redirect to 2FA with original callback
+    if (isLoginPage) {
+      const callbackUrl = searchParams.get('callbackUrl') || '/';
+      // CRITICAL FIX: Never use auth pages as callback URLs
+      const safeCallbackUrl = callbackUrl.startsWith('/account-auth/') ? '/' : callbackUrl;
+      return {
+        type: 'redirect',
+        location: `/account-auth/verify-code?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`,
+        reason: '2fa_required'
+      };
+    }
+
+    // For protected routes:
+    // - If access token is expired and we have a valid refresh token, let middleware handle refresh first
+    // - Only redirect to verify-code if access token is still valid or refresh failed
+    // - Allow middleware to pass - it will either refresh successfully or handle redirect appropriately
+    return { type: 'allow' };
+  }
+
+  // Authenticated user on login page - redirect to dashboard or callback
+  if (isLoginPage) {
+    const callbackUrl = searchParams.get('callbackUrl') || '/';
+    // CRITICAL FIX: Never redirect back to login page (prevents infinite loop)
+    const safeCallbackUrl = callbackUrl.startsWith('/account-auth/') ? '/' : callbackUrl;
+    console.log('[MIDDLEWARE-DECISION] Authenticated user on login page, redirecting', {
+      originalCallback: callbackUrl,
+      safeCallback: safeCallbackUrl
+    });
+    return {
+      type: 'redirect',
+      location: safeCallbackUrl,
+      reason: 'already_authenticated'
+    };
+  }
+
+  // All checks passed - allow access
+  return { type: 'allow' };
+}

package/src/auth/auth-options.ts

@@ -0,0 +1,237 @@
+/**
+ * NextAuth Configuration (Refactored)
+ *
+ * This is the composition layer that wires together all auth modules.
+ * Individual logic lives in dedicated modules:
+ * - providers/ - Credentials and OAuth provider builders
+ * - callbacks/ - JWT, session, signIn callbacks
+ * - events/ - SignOut event handler
+ * - utils/ - Token utilities, IDP client
+ * - types/ - Type definitions
+ *
+ * CARGO CULT PATTERNS REMOVED:
+ * ============================
+ * The original auth-options.ts (1186 lines) had several anti-patterns that
+ * added complexity without benefit:
+ *
+ * 1. CALLBACK CONCURRENCY PROTECTION (removed)
+ *    - shouldExecuteCallback() / markCallbackComplete()
+ *    - A debouncing mechanism that tried to prevent callbacks from running
+ *      too frequently. NextAuth already handles this properly.
+ *    - Added complexity, caused race condition bugs, and leaked memory
+ *      (Map entries never cleaned up).
+ *
+ * 2. SESSION RESTORATION (removed)
+ *    - attemptSessionRestoration()
+ *    - Tried to restore sessions by calling refresh endpoint from JWT callback.
+ *    - Created circular dependencies and made debugging impossible.
+ *    - Clean approach: Session missing = user re-authenticates. Simple.
+ *
+ * 3. VARIABLE NAME SOUP (normalized in Phase 3)
+ *    - accessToken vs idpAccessToken vs oauthAccessToken
+ *    - twoFactorComplete vs mfaVerified vs requiresTwoFactor
+ *    - sessionToken vs redisSessionId
+ *    - Now: Clear prefixes (idp*, oauth*, mfa*) with documented meanings.
+ *
+ * 4. INLINE EVERYTHING (modularized in Phase 2)
+ *    - All logic was in one giant file with no separation of concerns.
+ *    - Now: Each module has one job and can be tested independently.
+ *
+ * @version 2.0.0
+ * @since auth-refactor-2026-01
+ */
+
+import type { NextAuthOptions } from 'next-auth';
+import type { Provider } from 'next-auth/providers/index';
+import { encode as defaultEncode, decode as defaultDecode } from 'next-auth/jwt';
+import { getIDPClientConfig, type IDPClientConfig } from '../lib/idp-client-config';
+import {
+  getSessionCookieName,
+  getSecureSessionCookieName,
+  getCsrfCookieName,
+  getSecureCsrfCookieName,
+  getCallbackUrlCookieName,
+} from '../lib/app-slug';
+
+// Module imports
+import { createCredentialsProvider, buildOAuthProviders } from './providers';
+import { jwtCallback, sessionCallback, signInCallback } from './callbacks';
+import { handleSignOut } from './events';
+
+// ============================================================================
+// ENVIRONMENT HELPERS
+// ============================================================================
+
+/**
+ * Get AUTH_ISSUER_URL for JWT issuer claim.
+ * Required for SSO across apps.
+ */
+function getAuthIssuerUrl(): string {
+  const url = process.env.AUTH_ISSUER_URL;
+  if (!url) {
+    throw new Error('AUTH_ISSUER_URL environment variable is REQUIRED');
+  }
+  return url;
+}
+
+// ============================================================================
+// BASE AUTH OPTIONS
+// ============================================================================
+
+/**
+ * Base NextAuth configuration.
+ * Use getAuthOptions() for dynamic provider loading from IDP.
+ */
+export const authOptions: NextAuthOptions = {
+  // Session uses JWT strategy - JWT contains only redisSessionId
+  session: {
+    strategy: 'jwt',
+    maxAge: 30 * 24 * 60 * 60, // 30 days default, overridden by IDP config
+  },
+
+  // Custom JWT handling for SSO issuer
+  jwt: {
+    encode: async (params) => {
+      try {
+        const issuer = getAuthIssuerUrl();
+        console.log('[JWT_ENCODE] Encoding token:', {
+          hasToken: !!params.token,
+          hasSecret: !!params.secret,
+          secretLength: params.secret?.length || 0,
+          issuer,
+          tokenKeys: params.token ? Object.keys(params.token) : [],
+        });
+        const encoded = await defaultEncode({
+          ...params,
+          secret: params.secret,
+          token: {
+            ...params.token,
+            iss: issuer,
+          },
+        });
+        console.log('[JWT_ENCODE] Success, encoded length:', encoded?.length || 0);
+        return encoded;
+      } catch (error) {
+        console.error('[JWT_ENCODE] FAILED:', error);
+        throw error;
+      }
+    },
+    decode: async (params) => {
+      const decoded = await defaultDecode(params);
+      if (decoded?.iss && decoded.iss !== getAuthIssuerUrl()) {
+        console.error('[JWT] Invalid issuer. Expected:', getAuthIssuerUrl(), 'Got:', decoded.iss);
+        return null; // Hard enforcement - reject mismatched issuers
+      }
+      return decoded;
+    },
+  },
+
+  // Cookie configuration for multi-app support
+  // In production, use __Secure- prefixed cookie names for enhanced security
+  cookies: {
+    sessionToken: {
+      name: process.env.NODE_ENV === 'production' ? getSecureSessionCookieName() : getSessionCookieName(),
+      options: {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        secure: process.env.NODE_ENV === 'production',
+      },
+    },
+    csrfToken: {
+      name: process.env.NODE_ENV === 'production' ? getSecureCsrfCookieName() : getCsrfCookieName(),
+      options: {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        secure: process.env.NODE_ENV === 'production',
+      },
+    },
+    callbackUrl: {
+      name: getCallbackUrlCookieName(),
+      options: {
+        sameSite: 'lax',
+        path: '/',
+        secure: process.env.NODE_ENV === 'production',
+      },
+    },
+  },
+
+  // Providers - credentials only in base, OAuth added dynamically
+  providers: [createCredentialsProvider()],
+
+  // Callbacks wired to modular implementations
+  callbacks: {
+    jwt: jwtCallback,
+    session: sessionCallback as any, // Type cast needed for NextAuth compatibility
+    signIn: signInCallback,
+  },
+
+  // Events
+  events: {
+    signOut: handleSignOut,
+  },
+
+  // Custom pages
+  pages: {
+    signIn: '/account-auth/login',
+    error: '/account-auth/login',
+  },
+
+  debug: false,
+};
+
+// ============================================================================
+// DYNAMIC AUTH OPTIONS (WITH IDP OAUTH PROVIDERS)
+// ============================================================================
+
+let cachedAuthOptions: NextAuthOptions | null = null;
+let authOptionsPromise: Promise<NextAuthOptions> | null = null;
+
+/**
+ * Get auth options with dynamically loaded OAuth providers from IDP.
+ * Uses caching to avoid rebuilding on every request.
+ */
+export async function getAuthOptions(): Promise<NextAuthOptions> {
+  if (cachedAuthOptions) {
+    return cachedAuthOptions;
+  }
+
+  if (authOptionsPromise) {
+    return authOptionsPromise;
+  }
+
+  authOptionsPromise = buildDynamicAuthOptions();
+  cachedAuthOptions = await authOptionsPromise;
+  authOptionsPromise = null;
+
+  return cachedAuthOptions;
+}
+
+/**
+ * Build auth options with dynamic OAuth providers from IDP.
+ */
+async function buildDynamicAuthOptions(): Promise<NextAuthOptions> {
+  const idpConfig = await getIDPClientConfig();
+  const oauthProviders = buildOAuthProviders(idpConfig);
+
+  return {
+    ...authOptions,
+    secret: idpConfig.nextAuthSecret || process.env.NEXTAUTH_SECRET,
+    session: {
+      ...authOptions.session,
+      maxAge: idpConfig.authSettings?.rememberMeDays
+        ? idpConfig.authSettings.rememberMeDays * 24 * 60 * 60
+        : 30 * 24 * 60 * 60,
+    },
+    providers: [createCredentialsProvider(), ...oauthProviders],
+  };
+}
+
+/**
+ * Clear cached auth options (when IDP config changes).
+ */
+export function clearAuthOptionsCache(): void {
+  cachedAuthOptions = null;
+  authOptionsPromise = null;
+}