@payez/next-mvp 3.0.0

package/dist/api-handlers/session/viability.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = GET;
+const server_1 = require("next/server");
+const session_store_1 = require("../../lib/session-store");
+const jwt_1 = require("next-auth/jwt");
+const startup_init_1 = require("../../lib/startup-init");
+const app_slug_1 = require("../../lib/app-slug");
+const idp_client_config_1 = require("../../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() {
+    const config = await (0, idp_client_config_1.getIDPClientConfig)();
+    return config.nextAuthSecret || '';
+}
+async function GET(req) {
+    try {
+        // Ensure initialization is complete
+        if (!process.env.NEXTAUTH_SECRET) {
+            try {
+                await (0, startup_init_1.ensureInitialized)();
+            }
+            catch (error) {
+                // Initialization failed - return 503
+                console.error('[API Viability] Initialization failed - returning 503');
+                return server_1.NextResponse.json({
+                    error: 'Service Unavailable',
+                    message: 'Authentication service is not properly configured',
+                    code: 'AUTH_NOT_INITIALIZED'
+                }, { status: 503 });
+            }
+        }
+        // Double-check after initialization attempt
+        if ((0, startup_init_1.isInitializationFailed)()) {
+            console.error('[API Viability] Initialization failed - returning 503');
+            return server_1.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 server_1.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 = (0, app_slug_1.getJwtCookieName)();
+        const token = await (0, jwt_1.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);
+        if (token && sessionToken) {
+            const sessionData = await (0, session_store_1.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 (0, idp_client_config_1.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.twoFactorComplete ?? false;
+                const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
+                console.log('[VIABILITY] Session 2FA check:', {
+                    sessionToken: sessionToken.substring(0, 8) + '...',
+                    mfaVerified: sessionData.mfaVerified,
+                    twoFactorComplete: sessionData.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 server_1.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 server_1.NextResponse.json({
+                authenticated: false,
+                sessionToken // Include token to enable stale cookie detection
+            });
+        }
+        // If there's no token at all, it's not authenticated
+        return server_1.NextResponse.json({ authenticated: false });
+    }
+    catch (error) {
+        console.error('[API Viability] Error checking session viability:', error);
+        return server_1.NextResponse.json({ authenticated: false }, { status: 500 });
+    }
+}

package/dist/api-handlers/test/force-expire.d.ts

@@ -0,0 +1,23 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * 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 declare const POST: (req: NextRequest) => Promise<NextResponse<{
+    success: boolean;
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    previous: number | null;
+    previousIso: string | null;
+    newExpiry: number;
+    newExpiryIso: string;
+}>>;

package/dist/api-handlers/test/force-expire.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+const server_1 = require("next/server");
+const jwt_1 = require("next-auth/jwt");
+const session_store_1 = require("../../lib/session-store");
+const app_slug_1 = require("../../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';
+ * ```
+ */
+const POST = async (req) => {
+    try {
+        const secret = process.env.NEXTAUTH_SECRET;
+        if (!secret) {
+            return server_1.NextResponse.json({ success: false, error: 'NEXTAUTH_SECRET not configured' }, { status: 500 });
+        }
+        const cookieName = (0, app_slug_1.getJwtCookieName)();
+        const token = await (0, jwt_1.getToken)({ req, secret, cookieName });
+        let sessionToken = token?.redisSessionId;
+        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 server_1.NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
+            }
+        }
+        const session = await (0, session_store_1.getSession)(sessionToken);
+        if (!session) {
+            return server_1.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 (0, session_store_1.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 server_1.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 server_1.NextResponse.json({ success: false, error: e instanceof Error ? e.message : String(e) }, { status: 500 });
+    }
+};
+exports.POST = POST;

package/dist/auth/auth-decision.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+export interface AuthContext {
+    pathname: string;
+    isPublicRoute: boolean;
+    isLoginPage: boolean;
+    searchParams: URLSearchParams;
+    sessionPointer: {
+        exists: boolean;
+        sessionToken?: string;
+        expired?: boolean;
+    };
+    sessionStatus: {
+        exists: boolean | null;
+        forceInvalid: boolean | null;
+        requires2FA: boolean;
+        twoFactorComplete: boolean;
+    };
+    circuitBreakerOpen: boolean;
+}
+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 declare function makeAuthDecision(context: AuthContext): AuthAction;

package/dist/auth/auth-decision.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeAuthDecision = makeAuthDecision;
+/**
+ * Main decision function - pure, testable, deterministic
+ */
+function makeAuthDecision(context) {
+    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/dist/auth/auth-options.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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';
+/**
+ * Base NextAuth configuration.
+ * Use getAuthOptions() for dynamic provider loading from IDP.
+ */
+export declare const authOptions: NextAuthOptions;
+/**
+ * Get auth options with dynamically loaded OAuth providers from IDP.
+ * Uses caching to avoid rebuilding on every request.
+ */
+export declare function getAuthOptions(): Promise<NextAuthOptions>;
+/**
+ * Clear cached auth options (when IDP config changes).
+ */
+export declare function clearAuthOptionsCache(): void;