@payez/next-mvp 3.0.0

package/dist/routes/auth/viability.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Ready-to-Use Session Viability Route
+ *
+ * Checks if the current session is viable (valid and not expired).
+ * Used by client-side code to determine if a refresh is needed.
+ *
+ * @example
+ * ```typescript
+ * // app/api/session/viability/route.ts
+ * export { GET } from '@payez/next-mvp/routes/auth/viability';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = GET;
+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");
+const idp_client_config_1 = require("../../lib/idp-client-config");
+/**
+ * Get NextAuth secret from IDP config (cached).
+ * NEVER use process.env.NEXTAUTH_SECRET at module level - it may not be set yet.
+ */
+async function getNextAuthSecret() {
+    const config = await (0, idp_client_config_1.getIDPClientConfig)();
+    return config.nextAuthSecret || '';
+}
+/**
+ * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
+ */
+async function getTenantRequiresTwoFactor() {
+    try {
+        const config = await (0, idp_client_config_1.getIDPClientConfig)();
+        return config.authSettings?.require2FA ?? true; // Default to true for security
+    }
+    catch {
+        console.warn('[VIABILITY] Could not get client config, defaulting tenantRequiresTwoFactor to true');
+        return true;
+    }
+}
+/**
+ * GET /api/session/viability - Check if session is viable
+ *
+ * Returns:
+ * - viable: boolean - Whether the session can be used
+ * - needsRefresh: boolean - Whether a refresh is recommended
+ * - expiresIn: number - Seconds until token expires
+ */
+async function GET(req) {
+    try {
+        const cookieName = (0, app_slug_1.getJwtCookieName)();
+        const secret = await getNextAuthSecret();
+        const token = await (0, jwt_1.getToken)({ req, secret, cookieName });
+        if (!token) {
+            return server_1.NextResponse.json({
+                viable: false,
+                needsRefresh: false,
+                authenticated: false,
+                reason: 'No session found'
+            });
+        }
+        // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+        const sessionToken = token.sessionToken || token.redisSessionId;
+        const session = sessionToken ? await (0, session_store_1.getSession)(sessionToken) : null;
+        // CRITICAL: Detect stale cookie state (JWT exists but Redis session missing)
+        if (sessionToken && !session) {
+            console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
+            return server_1.NextResponse.json({
+                viable: false,
+                needsRefresh: false,
+                authenticated: false,
+                sessionToken, // Return sessionToken so middleware can detect and clear stale cookie
+                reason: 'Stale session - cookie exists but session not found in Redis'
+            });
+        }
+        // Check access token expiry
+        const now = Math.floor(Date.now() / 1000);
+        const accessTokenExpires = token.accessTokenExpires || token.exp;
+        if (!accessTokenExpires) {
+            // No expiry info, assume viable but recommend refresh
+            const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
+            // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
+            const mfaExpiresAt = session?.mfaExpiresAt || 0;
+            const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+            // Check mfaVerified (normalized name) with fallback to twoFactorComplete for compatibility
+            const mfaVerifiedInSession = session?.mfaVerified ?? session?.twoFactorComplete ?? false;
+            // User has completed 2FA requirements if: they verified AND it hasn't expired
+            const userHasCompletedTenantTwoFactorRequirements = mfaVerifiedInSession && !mfaExpired;
+            // userStillNeedsTwoFactor = inverse of completed (matches session callback logic)
+            const userStillNeedsTwoFactor = !userHasCompletedTenantTwoFactorRequirements;
+            return server_1.NextResponse.json({
+                viable: true,
+                needsRefresh: true,
+                authenticated: true,
+                sessionToken,
+                // Clear names for middleware decision-making
+                tenantRequiresTwoFactor,
+                userHasCompletedTenantTwoFactorRequirements,
+                userStillNeedsTwoFactor,
+                // Legacy field names for backwards compatibility
+                requires2FA: tenantRequiresTwoFactor,
+                twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
+                accessTokenExpired: false,
+                reason: 'No expiry information'
+            });
+        }
+        // Convert to seconds if needed
+        const expiryTime = accessTokenExpires > 1000000000000
+            ? Math.floor(accessTokenExpires / 1000)
+            : accessTokenExpires;
+        const expiresIn = expiryTime - now;
+        const isExpired = expiresIn <= 0;
+        const needsRefresh = expiresIn <= 300; // 5 minutes buffer
+        // Check if we have refresh capability (check normalized field name first)
+        const hasRefreshToken = !!(session?.idpRefreshToken || session?.refreshToken || token.refreshToken);
+        // CLEAR NAMING: Tenant-wide 2FA requirement from client config
+        const tenantRequiresTwoFactor = await getTenantRequiresTwoFactor();
+        // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
+        // The session may have mfaVerified=true from days ago, but if mfaExpiresAt
+        // has passed, we must treat 2FA as incomplete to force re-verification.
+        const mfaExpiresAt = session?.mfaExpiresAt || 0;
+        const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+        // Check mfaVerified (normalized name) with fallback to twoFactorComplete for compatibility
+        const mfaVerifiedInSession = session?.mfaVerified ?? session?.twoFactorComplete ?? false;
+        // DEBUG: Log what we're reading from the session
+        console.log('[VIABILITY] Session 2FA state:', {
+            sessionToken: sessionToken?.substring(0, 8) + '...',
+            'session.mfaVerified': session?.mfaVerified,
+            'session.twoFactorComplete': session?.twoFactorComplete,
+            mfaVerifiedInSession,
+            mfaExpiresAt,
+            mfaExpired,
+            hasRefreshToken,
+            'session.idpRefreshToken': !!session?.idpRefreshToken,
+            'session.refreshToken': !!session?.refreshToken,
+        });
+        // CLEAR NAMING: User has completed 2FA requirements if: they verified AND it hasn't expired
+        const userHasCompletedTenantTwoFactorRequirements = mfaVerifiedInSession && !mfaExpired;
+        // userStillNeedsTwoFactor = inverse of completed (matches session callback logic)
+        const userStillNeedsTwoFactor = !userHasCompletedTenantTwoFactorRequirements;
+        if (mfaExpired && mfaVerifiedInSession) {
+            console.warn('[VIABILITY] MFA expired - forcing 2FA re-verification');
+        }
+        if (isExpired) {
+            return server_1.NextResponse.json({
+                viable: false,
+                needsRefresh: hasRefreshToken,
+                expiresIn: 0,
+                hasRefreshToken,
+                authenticated: true,
+                sessionToken,
+                // Clear names
+                tenantRequiresTwoFactor,
+                userHasCompletedTenantTwoFactorRequirements,
+                userStillNeedsTwoFactor,
+                // Legacy names for backwards compatibility
+                requires2FA: tenantRequiresTwoFactor,
+                twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
+                accessTokenExpired: true,
+                reason: 'Token expired',
+                // RBAC fields
+                roles: session?.roles || [],
+                clientId: session?.idpClientId || process.env.IDP_CLIENT_ID || '',
+            });
+        }
+        return server_1.NextResponse.json({
+            viable: true,
+            needsRefresh,
+            expiresIn,
+            hasRefreshToken,
+            authenticated: true,
+            sessionToken,
+            // Clear names
+            tenantRequiresTwoFactor,
+            userHasCompletedTenantTwoFactorRequirements,
+            userStillNeedsTwoFactor,
+            // Legacy names for backwards compatibility
+            requires2FA: tenantRequiresTwoFactor,
+            twoFactorComplete: userHasCompletedTenantTwoFactorRequirements,
+            accessTokenExpired: false,
+            expiresAt: new Date(expiryTime * 1000).toISOString(),
+            // RBAC fields
+            roles: session?.roles || [],
+            clientId: session?.idpClientId || process.env.IDP_CLIENT_ID || '',
+        });
+    }
+    catch (error) {
+        console.error('[VIABILITY_ROUTE] Error checking session viability:', error);
+        return server_1.NextResponse.json({
+            viable: false,
+            needsRefresh: false,
+            authenticated: false,
+            error: 'Failed to check session',
+            details: error instanceof Error ? error.message : 'Unknown error'
+        }, { status: 500 });
+    }
+}

package/dist/routes/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @payez/next-mvp Route Module Exports
+ *
+ * Ready-to-use route handlers for quick integration
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+export * from './auth';
+export * from './account';
+export * as auth from './auth';
+export * as account from './account';

package/dist/routes/index.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * @payez/next-mvp Route Module Exports
+ *
+ * Ready-to-use route handlers for quick integration
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.account = exports.auth = void 0;
+// Export auth routes
+__exportStar(require("./auth"), exports);
+// Export account/2FA routes
+__exportStar(require("./account"), exports);
+// Namespace exports for cleaner imports
+exports.auth = __importStar(require("./auth"));
+exports.account = __importStar(require("./account"));

package/dist/routes/session/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Session Routes Index
+ *
+ * Re-exports all session-related route handlers for easy importing.
+ */
+export { GET as refreshViabilityGET } from './refresh-viability';

package/dist/routes/session/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Session Routes Index
+ *
+ * Re-exports all session-related route handlers for easy importing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshViabilityGET = void 0;
+var refresh_viability_1 = require("./refresh-viability");
+Object.defineProperty(exports, "refreshViabilityGET", { enumerable: true, get: function () { return refresh_viability_1.GET; } });

package/dist/routes/session/refresh-viability.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ready-to-Use Refresh Viability Route
+ *
+ * Checks if a session has a valid refresh token for automatic refresh.
+ * Used by middleware to decide whether to attempt refresh or redirect to login.
+ *
+ * @example
+ * ```typescript
+ * // app/api/session/refresh-viability/route.ts
+ * export { GET } from '@payez/next-mvp/routes/session/refresh-viability';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+export { GET } from '../../api-handlers/session/refresh-viability';

package/dist/routes/session/refresh-viability.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Ready-to-Use Refresh Viability Route
+ *
+ * Checks if a session has a valid refresh token for automatic refresh.
+ * Used by middleware to decide whether to attempt refresh or redirect to login.
+ *
+ * @example
+ * ```typescript
+ * // app/api/session/refresh-viability/route.ts
+ * export { GET } from '@payez/next-mvp/routes/session/refresh-viability';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = void 0;
+var refresh_viability_1 = require("../../api-handlers/session/refresh-viability");
+Object.defineProperty(exports, "GET", { enumerable: true, get: function () { return refresh_viability_1.GET; } });

package/dist/services/signalrActivityService.d.ts

@@ -0,0 +1,44 @@
+export interface HealthStatus {
+    isHealthy: boolean;
+    message: string;
+    lastHeartbeat: Date | null;
+    connectionId: string | null | undefined;
+    responseTime?: string;
+}
+export type HealthStatusCallback = (status: HealthStatus) => void;
+/**
+ * SignalR-based health service following Occam's Razor principle:
+ * - If SignalR connection is alive = Service is working
+ * - If SignalR connection is dead = Service is not working
+ * - No complex orchestration, just connection state monitoring
+ */
+declare class SignalRActivityService {
+    private connection;
+    private subscribers;
+    private currentStatus;
+    private heartbeatTimeout;
+    private readonly heartbeatTimeoutMs;
+    /**
+     * Start the health monitoring connection
+     * @param idpBaseUrl - The base URL of the IDP server (e.g., 'http://localhost:32785')
+     */
+    start(idpBaseUrl: string): Promise<void>;
+    /**
+     * Stop the health monitoring connection
+     */
+    stop(): Promise<void>;
+    /**
+     * Subscribe to health status changes
+     */
+    subscribe(callback: HealthStatusCallback): () => void;
+    /**
+     * Get current health status
+     */
+    getCurrentStatus(): HealthStatus;
+    private updateStatus;
+    private notifySubscribers;
+    private resetHeartbeatTimeout;
+    private clearHeartbeatTimeout;
+}
+export declare const signalRActivityService: SignalRActivityService;
+export {};

package/dist/services/signalrActivityService.js

@@ -0,0 +1,257 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signalRActivityService = void 0;
+const signalR = __importStar(require("@microsoft/signalr"));
+/**
+ * SignalR-based health service following Occam's Razor principle:
+ * - If SignalR connection is alive = Service is working
+ * - If SignalR connection is dead = Service is not working
+ * - No complex orchestration, just connection state monitoring
+ */
+class SignalRActivityService {
+    connection = null;
+    subscribers = new Set();
+    currentStatus = {
+        isHealthy: false,
+        message: 'Disconnected',
+        lastHeartbeat: null,
+        connectionId: null
+    };
+    heartbeatTimeout = null;
+    heartbeatTimeoutMs = 45000; // 45 seconds (server sends every 30s)
+    /**
+     * Start the health monitoring connection
+     * @param idpBaseUrl - The base URL of the IDP server (e.g., 'http://localhost:32785')
+     */
+    async start(idpBaseUrl) {
+        // If we already have a connected or connecting connection, don't start again
+        if (this.connection &&
+            (this.connection.state === signalR.HubConnectionState.Connected ||
+                this.connection.state === signalR.HubConnectionState.Connecting)) {
+            console.info('[SignalRHealth] Connection already active, skipping start');
+            return;
+        }
+        // Stop existing connection if it exists
+        if (this.connection) {
+            await this.stop();
+        }
+        try {
+            if (!idpBaseUrl) {
+                throw new Error('IDP base URL is required for health monitoring');
+            }
+            // Construct absolute hub URL safely
+            const activityHubUrl = new URL('/healthHub', idpBaseUrl).toString();
+            console.info('[SignalRHealth] Using hub URL:', activityHubUrl);
+            this.connection = new signalR.HubConnectionBuilder()
+                .withUrl(activityHubUrl, {
+                withCredentials: false,
+                transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.ServerSentEvents | signalR.HttpTransportType.LongPolling,
+            })
+                .withAutomaticReconnect({
+                nextRetryDelayInMilliseconds: (retryContext) => {
+                    // More conservative backoff: 5s, 15s, 45s, then stop trying
+                    const delays = [5000, 15000, 45000];
+                    if (retryContext.previousRetryCount >= delays.length) {
+                        return null; // Stop automatic reconnection
+                    }
+                    return delays[retryContext.previousRetryCount];
+                }
+            })
+                .configureLogging(signalR.LogLevel.Critical) // Only critical errors, hide connection noise
+                .build();
+            // Handle connection events
+            this.connection.onclose(() => {
+                this.updateStatus({
+                    isHealthy: false,
+                    message: 'Service unavailable',
+                    lastHeartbeat: null,
+                    connectionId: null
+                });
+                this.clearHeartbeatTimeout();
+            });
+            this.connection.onreconnecting(() => {
+                this.updateStatus({
+                    isHealthy: false,
+                    message: 'Service unavailable',
+                    lastHeartbeat: this.currentStatus.lastHeartbeat,
+                    connectionId: null
+                });
+            });
+            this.connection.onreconnected((connectionId) => {
+                this.updateStatus({
+                    isHealthy: true,
+                    message: 'Service operational',
+                    lastHeartbeat: new Date(),
+                    connectionId
+                });
+                this.resetHeartbeatTimeout();
+            });
+            // Handle heartbeat messages - this is the core health indicator
+            this.connection.on('Heartbeat', (data) => {
+                this.updateStatus({
+                    isHealthy: true,
+                    message: 'Service operational',
+                    lastHeartbeat: new Date(),
+                    connectionId: this.connection?.connectionId || null
+                });
+                this.resetHeartbeatTimeout();
+            });
+            // Handle initial health status
+            this.connection.on('HealthStatus', (data) => {
+                this.updateStatus({
+                    isHealthy: data.status === 'healthy',
+                    message: data.message || 'Service connected',
+                    lastHeartbeat: new Date(),
+                    connectionId: this.connection?.connectionId || null
+                });
+                this.resetHeartbeatTimeout();
+            });
+            // Start the connection
+            await this.connection.start();
+            console.info('[SignalRHealth] Connection started, connectionId:', this.connection.connectionId);
+            this.updateStatus({
+                isHealthy: true,
+                message: 'Service connected',
+                lastHeartbeat: new Date(),
+                connectionId: this.connection.connectionId
+            });
+            this.resetHeartbeatTimeout();
+        }
+        catch (error) {
+            // Reduce console noise for expected connection failures
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            console.warn('[SignalRHealth] Connection start failed:', errorMessage);
+            const isConnectionRefused = errorMessage.includes('ERR_CONNECTION_REFUSED') ||
+                errorMessage.includes('Failed to fetch') ||
+                errorMessage.includes('Failed to complete negotiation');
+            if (isConnectionRefused) {
+                // Service is down - this is expected, log at info level
+                console.info('SignalR Health Service: Backend service unavailable');
+            }
+            else {
+                // Unexpected error - log as error
+                console.error('SignalR Health Service failed to start:', error);
+            }
+            this.updateStatus({
+                isHealthy: false,
+                message: 'Service unavailable',
+                lastHeartbeat: null,
+                connectionId: null
+            });
+        }
+    }
+    /**
+     * Stop the health monitoring connection
+     */
+    async stop() {
+        this.clearHeartbeatTimeout();
+        if (this.connection) {
+            try {
+                // Check if connection is in a state that can be stopped
+                if (this.connection.state !== signalR.HubConnectionState.Disconnected) {
+                    await this.connection.stop();
+                }
+            }
+            catch (error) {
+                // Ignore "connection was stopped before the hub handshake could complete" errors
+                // as these are expected during rapid start/stop cycles
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (!errorMessage.includes('stopped before the hub handshake could complete')) {
+                    console.error('Error stopping SignalR health connection:', error);
+                }
+            }
+            this.connection = null;
+        }
+        this.updateStatus({
+            isHealthy: false,
+            message: 'Disconnected',
+            lastHeartbeat: null,
+            connectionId: null
+        });
+    }
+    /**
+     * Subscribe to health status changes
+     */
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        // Immediately notify with current status
+        callback(this.currentStatus);
+        // Return unsubscribe function
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+    /**
+     * Get current health status
+     */
+    getCurrentStatus() {
+        return { ...this.currentStatus };
+    }
+    updateStatus(newStatus) {
+        this.currentStatus = newStatus;
+        this.notifySubscribers();
+    }
+    notifySubscribers() {
+        this.subscribers.forEach(callback => {
+            try {
+                callback(this.currentStatus);
+            }
+            catch (error) {
+                console.error('Error in health status subscriber:', error);
+            }
+        });
+    }
+    resetHeartbeatTimeout() {
+        this.clearHeartbeatTimeout();
+        // If we don't receive a heartbeat within the timeout period, consider service unhealthy
+        this.heartbeatTimeout = setTimeout(() => {
+            this.updateStatus({
+                isHealthy: false,
+                message: 'Service unavailable',
+                lastHeartbeat: this.currentStatus.lastHeartbeat,
+                connectionId: this.currentStatus.connectionId
+            });
+        }, this.heartbeatTimeoutMs);
+    }
+    clearHeartbeatTimeout() {
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = null;
+        }
+    }
+}
+// Export singleton instance
+exports.signalRActivityService = new SignalRActivityService();