@payez/next-mvp 3.0.0

package/src/routes/auth/settings.ts

@@ -0,0 +1,75 @@
+/**
+ * Public Auth Settings Route
+ *
+ * Returns client auth settings for pre-login pages (signup, login).
+ * Does NOT require authentication - these are public client settings.
+ */
+
+import { NextResponse } from 'next/server';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+
+export interface PublicAuthSettings {
+    // OAuth providers enabled for this client
+    enabledProviders: string[];
+
+    // Registration settings
+    allowPublicRegistration: boolean;
+    allowSocialLogin: boolean;
+
+    // Password settings
+    enablePasswordReset: boolean;
+
+    // 2FA settings (public - no secrets)
+    require2FA: boolean;
+    allowed2FAMethods: string[];
+}
+
+/**
+ * GET /api/auth/settings
+ *
+ * Returns public auth settings for the current client.
+ * Used by login/signup pages to determine what options to show.
+ */
+export async function GET() {
+    try {
+        const config = await getIDPClientConfig();
+
+        const settings: PublicAuthSettings = {
+            // Get enabled OAuth provider names
+            enabledProviders: config.oauthProviders
+                ?.filter(p => p.enabled)
+                .map(p => p.provider) ?? [],
+
+            // Registration - default to true if not specified
+            allowPublicRegistration: true, // Could come from config.authSettings in future
+            allowSocialLogin: config.oauthProviders?.some(p => p.enabled) ?? false,
+
+            // Password reset
+            enablePasswordReset: true, // Could come from config.authSettings in future
+
+            // 2FA
+            require2FA: config.authSettings?.require2FA ?? true,
+            allowed2FAMethods: config.authSettings?.allowed2FAMethods ?? ['email', 'sms'],
+        };
+
+        return NextResponse.json({
+            success: true,
+            data: settings,
+        });
+    } catch (error) {
+        console.error('[AUTH_SETTINGS] Failed to get settings:', error);
+
+        // Return safe defaults on error
+        return NextResponse.json({
+            success: true,
+            data: {
+                enabledProviders: [],
+                allowPublicRegistration: true,
+                allowSocialLogin: false,
+                enablePasswordReset: true,
+                require2FA: true,
+                allowed2FAMethods: ['email', 'sms'],
+            } as PublicAuthSettings,
+        });
+    }
+}

package/src/routes/auth/viability.ts

@@ -0,0 +1,220 @@
+/**
+ * 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
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+import { getSession } from '../../lib/session-store';
+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 at module level - it may not be set yet.
+ */
+async function getNextAuthSecret(): Promise<string> {
+  const config = await getIDPClientConfig();
+  return config.nextAuthSecret || '';
+}
+
+/**
+ * Get tenant-wide 2FA requirement from cached client config (from broker handshake)
+ */
+async function getTenantRequiresTwoFactor(): Promise<boolean> {
+  try {
+    const config = await 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
+ */
+export async function GET(req: NextRequest) {
+  try {
+    const cookieName = getJwtCookieName();
+    const secret = await getNextAuthSecret();
+    const token = await getToken({ req, secret, cookieName });
+
+    if (!token) {
+      return 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 as any).sessionToken || (token as any).redisSessionId;
+    const session = sessionToken ? await 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 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 as any).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 as any)?.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 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 as any)?.refreshToken || (token as any).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 as any)?.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 as any)?.twoFactorComplete,
+      mfaVerifiedInSession,
+      mfaExpiresAt,
+      mfaExpired,
+      hasRefreshToken,
+      'session.idpRefreshToken': !!session?.idpRefreshToken,
+      'session.refreshToken': !!(session as any)?.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 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 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 NextResponse.json({
+      viable: false,
+      needsRefresh: false,
+      authenticated: false,
+      error: 'Failed to check session',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    }, { status: 500 });
+  }
+}

package/src/routes/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @payez/next-mvp Route Module Exports
+ *
+ * Ready-to-use route handlers for quick integration
+ *
+ * @version 2.3.0
+ * @since auth-ready-v2
+ */
+
+// Export auth routes
+export * from './auth';
+
+// Export account/2FA routes
+export * from './account';
+
+// Namespace exports for cleaner imports
+export * as auth from './auth';
+export * as account from './account';

package/src/routes/session/index.ts

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

package/src/routes/session/refresh-viability.ts

@@ -0,0 +1,17 @@
+/**
+ * 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/src/services/signalrActivityService.ts

@@ -0,0 +1,258 @@
+import * as signalR from '@microsoft/signalr';
+
+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
+ */
+class SignalRActivityService {
+  private connection: signalR.HubConnection | null = null;
+  private subscribers: Set<HealthStatusCallback> = new Set();
+  private currentStatus: HealthStatus = {
+    isHealthy: false,
+    message: 'Disconnected',
+    lastHeartbeat: null,
+    connectionId: null
+  };
+  private heartbeatTimeout: NodeJS.Timeout | null = null;
+  private readonly 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: string): Promise<void> {
+    // 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(): Promise<void> {
+    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: HealthStatusCallback): () => void {
+    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(): HealthStatus {
+    return { ...this.currentStatus };
+  }
+
+  private updateStatus(newStatus: HealthStatus): void {
+    this.currentStatus = newStatus;
+    this.notifySubscribers();
+  }
+
+  private notifySubscribers(): void {
+    this.subscribers.forEach(callback => {
+      try {
+        callback(this.currentStatus);
+      } catch (error) {
+        console.error('Error in health status subscriber:', error);
+      }
+    });
+  }
+
+  private resetHeartbeatTimeout(): void {
+    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);
+  }
+
+  private clearHeartbeatTimeout(): void {
+    if (this.heartbeatTimeout) {
+      clearTimeout(this.heartbeatTimeout);
+      this.heartbeatTimeout = null;
+    }
+  }
+
+}
+
+// Export singleton instance
+export const signalRActivityService = new SignalRActivityService();