@payez/next-mvp 3.0.0

package/src/auth/events/signout.ts

@@ -0,0 +1,33 @@
+/**
+ * SignOut Event Handler
+ *
+ * Cleans up Redis session when user signs out.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+
+import type { JWT } from 'next-auth/jwt';
+import { deleteSession } from '../../lib/session-store';
+
+// ============================================================================
+// SIGNOUT EVENT
+// ============================================================================
+
+/**
+ * Handle user sign out by deleting Redis session.
+ *
+ * @param token - The JWT token containing the session ID
+ */
+export async function handleSignOut({ token }: { token: JWT | null }): Promise<void> {
+  // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+  const redisSessionId = (token as any)?.sessionToken || (token as any)?.redisSessionId;
+
+  if (redisSessionId) {
+    try {
+      await deleteSession(redisSessionId);
+    } catch (error) {
+      console.error('[SIGNOUT_EVENT] Failed to delete session:', error);
+    }
+  }
+}

package/src/auth/providers/credentials.ts

@@ -0,0 +1,256 @@
+/**
+ * Credentials Provider
+ *
+ * Handles email/password authentication via PayEz IDP.
+ * Creates Redis session and returns minimal user object to NextAuth.
+ *
+ * FLOW:
+ * 1. User submits email/password
+ * 2. We call IDP /api/ExternalAuth/login
+ * 3. IDP returns tokens if credentials valid
+ * 4. We create Redis session with tokens
+ * 5. Return user object with redisSessionId to NextAuth
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+
+import CredentialsProvider from 'next-auth/providers/credentials';
+import { createSession } from '../../lib/session-store';
+import { idpLogin } from '../utils/idp-client';
+import {
+  decodeIdpAccessToken,
+  extractEmailFromToken,
+  extractRolesFromToken,
+  extractAmrFromToken,
+  expClaimToMs,
+  extractKidFromToken,
+} from '../utils/token-utils';
+import type { AuthorizeResult, LoginCredentials } from '../types/auth-types';
+import { toRedisSessionId } from '../types/auth-types';
+// NOTE: Using any for sessionData until Phase 3 normalizes types
+
+// ============================================================================
+// CREDENTIALS PROVIDER
+// ============================================================================
+
+/**
+ * Create the CredentialsProvider for NextAuth.
+ *
+ * This provider handles email/password login. The authorize function
+ * is called when a user submits the login form.
+ */
+export function createCredentialsProvider() {
+  return CredentialsProvider({
+    id: 'credentials',
+    name: 'Credentials',
+    credentials: {
+      email: { label: 'Email', type: 'email' },
+      password: { label: 'Password', type: 'password' },
+    },
+    authorize: authorizeCredentials,
+  });
+}
+
+/**
+ * Authorize user with email/password.
+ *
+ * This is the core authentication function. It:
+ * 1. Validates credentials with IDP
+ * 2. Decodes the returned tokens
+ * 3. Creates a Redis session
+ * 4. Returns user info for NextAuth JWT
+ *
+ * @param credentials - Email and password from login form
+ * @param req - The incoming request (for IP/UA forwarding)
+ * @returns User object for NextAuth, or null/throws on failure
+ */
+async function authorizeCredentials(
+  credentials: Record<'email' | 'password', string> | undefined,
+  req: any
+): Promise<AuthorizeResult | null> {
+  // -------------------------------------------------------------------------
+  // Validate Input
+  // -------------------------------------------------------------------------
+
+  if (!credentials?.email || !credentials?.password) {
+    throw new Error('Email and password required');
+  }
+
+  const loginCredentials: LoginCredentials = {
+    email: credentials.email,
+    password: credentials.password,
+  };
+
+  // Extract client info for audit logging
+  const clientHeaders = extractClientHeaders(req);
+
+  // -------------------------------------------------------------------------
+  // Call IDP
+  // -------------------------------------------------------------------------
+
+  const loginResult = await idpLogin(loginCredentials, clientHeaders);
+
+  if (!loginResult.success || !loginResult.result) {
+    // Build structured error for frontend
+    const errorResponse = buildAuthError(loginResult.error);
+    throw new Error(JSON.stringify(errorResponse));
+  }
+
+  const { access_token, refresh_token, user: idpUser } = loginResult.result;
+
+  // -------------------------------------------------------------------------
+  // Decode Token
+  // -------------------------------------------------------------------------
+
+  const decoded = decodeIdpAccessToken(access_token);
+  if (!decoded) {
+    throw new Error('Failed to decode token');
+  }
+
+  // Extract kid from JWT header (CRITICAL: this is different from client_id in payload)
+  const bearerKeyId = extractKidFromToken(access_token);
+  if (bearerKeyId) {
+    console.log('[CREDENTIALS] Extracted bearerKeyId (kid) from JWT header:', bearerKeyId);
+  } else {
+    console.warn('[CREDENTIALS] No kid found in JWT header - token may be unsigned or malformed');
+  }
+
+  // Extract claims from token
+  const email = extractEmailFromToken(decoded);
+  const roles = extractRolesFromToken(decoded);
+  const amrClaims = extractAmrFromToken(decoded);
+  const acrLevel = decoded.acr || '1';
+  const userId = decoded.sub;
+
+  // Check if 2FA is complete based on ACR level
+  // ACR=1: Provisional token (requires 2FA)
+  // ACR=2: Full authentication (2FA complete)
+  const mfaVerified = acrLevel === '2';
+
+  // Decode refresh token expiry if available
+  let refreshTokenExpires: number | undefined;
+  try {
+    const refreshDecoded = decodeIdpAccessToken(refresh_token);
+    if (refreshDecoded?.exp) {
+      refreshTokenExpires = expClaimToMs(refreshDecoded.exp);
+    }
+  } catch {
+    // Ignore - will use default expiry
+  }
+
+  // -------------------------------------------------------------------------
+  // Create Redis Session
+  // -------------------------------------------------------------------------
+
+  // Using normalized field names (session-store handles backward compatibility)
+  const sessionData: any = {
+    userId,
+    email,
+    roles,
+    // IDP tokens (normalized names)
+    idpAccessToken: access_token,
+    idpRefreshToken: refresh_token,
+    idpAccessTokenExpires: expClaimToMs(decoded.exp),
+    idpRefreshTokenExpires: refreshTokenExpires,
+    decodedAccessToken: decoded,
+    // Bearer key ID from JWT header (NOT client_id from payload)
+    bearerKeyId,
+    // MFA state (normalized names)
+    mfaVerified,
+    authenticationMethods: amrClaims,
+    authenticationLevel: acrLevel,
+    // MFA timing info from token
+    mfaCompletedAt: decoded.mfa_time ? expClaimToMs(decoded.mfa_time) : undefined,
+    mfaExpiresAt: decoded.mfa_expires ? expClaimToMs(decoded.mfa_expires) : undefined,
+    mfaValidityHours: decoded.mfa_validity_hours,
+  };
+
+  // Determine MFA method from IDP user info
+  let mfaMethod: 'email' | 'sms' | 'totp' | undefined;
+  if (idpUser?.isEmailConfirmed) {
+    mfaMethod = 'email';
+  } else if (idpUser?.isSmsConfirmed) {
+    mfaMethod = 'sms';
+  }
+
+  if (mfaMethod) {
+    sessionData.mfaMethod = mfaMethod;
+  }
+
+  // Create the Redis session
+  const redisSessionId = await createSession(sessionData);
+
+  // -------------------------------------------------------------------------
+  // Return User Object for NextAuth
+  // -------------------------------------------------------------------------
+
+  // NextAuth requires 'id' field - we use userId from IDP
+  // The redisSessionId is passed through to the JWT callback
+  return {
+    id: userId,
+    email,
+    roles,
+    redisSessionId: toRedisSessionId(redisSessionId),
+    mfaRequired: !mfaVerified,
+    mfaMethod,
+  };
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Extract client headers from request for audit logging.
+ */
+function extractClientHeaders(req: any): { ip?: string; userAgent?: string } {
+  const headers: { ip?: string; userAgent?: string } = {};
+
+  // Extract client IP
+  const forwardedFor = req?.headers?.['x-forwarded-for'];
+  const realIp = req?.headers?.['x-real-ip'];
+
+  if (forwardedFor) {
+    const ip = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor.split(',')[0].trim();
+    headers.ip = ip;
+  } else if (realIp) {
+    headers.ip = Array.isArray(realIp) ? realIp[0] : realIp;
+  }
+
+  // Extract User-Agent
+  const userAgent = req?.headers?.['user-agent'];
+  if (userAgent) {
+    headers.userAgent = Array.isArray(userAgent) ? userAgent[0] : userAgent;
+  }
+
+  return headers;
+}
+
+/**
+ * Build structured error response for frontend.
+ *
+ * The frontend expects a specific error structure to display
+ * appropriate messages and handle things like lockout.
+ */
+function buildAuthError(error?: { code: string; message: string; details?: any }): object {
+  if (!error) {
+    return {
+      success: false,
+      error: {
+        code: 'AUTH_ERROR',
+        message: 'Authentication failed',
+        details: {},
+      },
+    };
+  }
+
+  return {
+    success: false,
+    error: {
+      code: error.code || 'AUTH_ERROR',
+      message: error.message || 'Authentication failed',
+      details: error.details || {},
+    },
+  };
+}

package/src/auth/providers/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Auth Providers - Public Exports
+ */
+
+export * from './credentials';
+export * from './oauth';

package/src/auth/providers/oauth.ts

@@ -0,0 +1,114 @@
+/**
+ * OAuth Provider Builder
+ *
+ * Dynamically builds NextAuth OAuth providers from IDP configuration.
+ * Supports Google, Apple, Facebook, GitHub, and Microsoft/Azure AD.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+
+import type { Provider } from 'next-auth/providers/index';
+import GoogleProvider from 'next-auth/providers/google';
+import AppleProvider from 'next-auth/providers/apple';
+import FacebookProvider from 'next-auth/providers/facebook';
+import GitHubProvider from 'next-auth/providers/github';
+import AzureADProvider from 'next-auth/providers/azure-ad';
+import type { IDPClientConfig, OAuthProviderConfig } from '../../lib/idp-client-config';
+
+// ============================================================================
+// PROVIDER BUILDER
+// ============================================================================
+
+/**
+ * Build NextAuth OAuth providers from IDP configuration.
+ *
+ * The IDP returns a list of enabled OAuth providers with their credentials.
+ * This function maps them to NextAuth provider instances.
+ *
+ * @param config - IDP client configuration containing OAuth provider list
+ * @returns Array of NextAuth Provider instances
+ */
+export function buildOAuthProviders(config: IDPClientConfig): Provider[] {
+  const providers: Provider[] = [];
+
+  for (const oauth of config.oauthProviders || []) {
+    if (!oauth.enabled) {
+      continue;
+    }
+
+    const provider = createOAuthProvider(oauth);
+    if (provider) {
+      providers.push(provider);
+    }
+  }
+
+  return providers;
+}
+
+/**
+ * Create a single OAuth provider instance from config.
+ */
+function createOAuthProvider(oauth: OAuthProviderConfig): Provider | null {
+  const providerName = oauth.provider.toLowerCase();
+
+  switch (providerName) {
+    case 'google':
+      return GoogleProvider({
+        clientId: oauth.clientId,
+        clientSecret: oauth.clientSecret,
+        authorization: {
+          params: {
+            scope: oauth.scopes || 'openid email profile',
+          },
+        },
+      });
+
+    case 'apple':
+      return AppleProvider({
+        clientId: oauth.clientId,
+        clientSecret: oauth.clientSecret,
+        authorization: {
+          params: {
+            scope: oauth.scopes || 'name email',
+          },
+        },
+      });
+
+    case 'facebook':
+      return FacebookProvider({
+        clientId: oauth.clientId,
+        clientSecret: oauth.clientSecret,
+      });
+
+    case 'github':
+      return GitHubProvider({
+        clientId: oauth.clientId,
+        clientSecret: oauth.clientSecret,
+      });
+
+    case 'microsoft':
+    case 'azure_ad':
+    case 'azure-ad':
+    case 'azuread':
+      return AzureADProvider({
+        clientId: oauth.clientId,
+        clientSecret: oauth.clientSecret,
+        tenantId: oauth.additionalParams?.tenantId || 'common',
+      });
+
+    default:
+      console.warn(`[OAUTH_PROVIDERS] Unknown OAuth provider: ${oauth.provider}`);
+      return null;
+  }
+}
+
+/**
+ * Get list of enabled provider names from config.
+ * Useful for logging and debugging.
+ */
+export function getEnabledProviderNames(config: IDPClientConfig): string[] {
+  return (config.oauthProviders || [])
+    .filter((p) => p.enabled)
+    .map((p) => p.provider);
+}

package/src/auth/route-config.ts

@@ -0,0 +1,220 @@
+/**
+ * Advanced Route Configuration for `@payez/next-mvp`
+ *
+ * This module provides a robust, pattern-based mechanism for defining
+ * unauthenticated (public) routes, including wildcard support.
+ * It is designed to be easily configurable by host applications.
+ */
+
+import { TwoFactorRequirements, TwoFactorPresets } from '../middleware/twofa-presets';
+
+export interface UnauthenticatedRouteConfig {
+  /** The route pattern (supports wildcards with *) */
+  pattern: string;
+  /** Description of what this route is for */
+  description: string;
+  /** Whether this route should be accessible during circuit breaker open state */
+  allowDuringCircuitBreakerOpen?: boolean;
+  /** Whether this route requires rate limiting even when unauthenticated */
+  requiresRateLimit?: boolean;
+}
+
+/**
+ * Protected route configuration with 2FA requirements
+ */
+export interface ProtectedRouteConfig {
+  /** The route pattern (supports wildcards with *) */
+  pattern: string;
+  /** Description of what this route is for */
+  description?: string;
+  /** 2FA requirements for this route (default: requires 2FA if site requires it) */
+  twoFactorRequirements: TwoFactorRequirements;
+}
+
+// Default public routes provided by the MVP package
+const defaultUnauthenticatedRoutes: UnauthenticatedRouteConfig[] = [
+  {
+    pattern: '/',
+    description: 'Homepage',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/login',
+    description: 'Login page',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/register',
+    description: 'Registration page',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/forgot-password',
+    description: 'Forgot password page',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/account-auth/*',
+    description: 'All authentication pages (login, register, forgot password, etc.)',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/api/auth/*',
+    description: 'NextAuth.js authentication API endpoints',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: true
+  },
+  {
+    pattern: '/api/session/viability',
+    description: 'Session viability check endpoint',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/api/health/*',
+    description: 'Health check endpoints',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: true
+  },
+  {
+    pattern: '/service-unavailable',
+    description: 'Service unavailable error page',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/_next/*',
+    description: 'Next.js static assets',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/favicon.ico',
+    description: 'Favicon',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+];
+
+let configuredRoutes: UnauthenticatedRouteConfig[] = [...defaultUnauthenticatedRoutes];
+
+// Default routes that require auth but NOT 2FA (for 2FA onboarding flow)
+// NOTE: Only the bare minimum routes needed for 2FA completion - no welcome screens
+const default2FABypassRoutes: ProtectedRouteConfig[] = [
+  {
+    pattern: '/api/auth/*',
+    description: 'NextAuth.js API routes - must be accessible during 2FA flow for session management',
+    twoFactorRequirements: TwoFactorPresets.NONE
+  },
+  {
+    pattern: '/api/account/*',
+    description: '2FA verification APIs (send-code, verify-email, verify-sms, update-phone, masked-info)',
+    twoFactorRequirements: TwoFactorPresets.NONE
+  },
+  {
+    pattern: '/api/session/*',
+    description: 'Session management APIs (viability, refresh-viability)',
+    twoFactorRequirements: TwoFactorPresets.NONE
+  },
+  {
+    pattern: '/account-auth/verify-code',
+    description: '2FA verification page',
+    twoFactorRequirements: TwoFactorPresets.NONE
+  },
+  {
+    pattern: '/test-env/*',
+    description: 'Test/debug pages (emergency-logout, jwt-inspect, refresh-token) - must bypass 2FA',
+    twoFactorRequirements: TwoFactorPresets.NONE
+  },
+  // NOTE: /onboarding/two-factor intentionally NOT included - go straight to 2FA, no welcome page
+];
+
+let configured2FABypassRoutes: ProtectedRouteConfig[] = [...default2FABypassRoutes];
+
+/**
+ * Configures additional public routes for the application.
+ * This function should be called once during application initialization.
+ * @param appRoutes An array of route patterns or UnauthenticatedRouteConfig objects.
+ */
+export function configurePublicRoutes(appRoutes: (string | UnauthenticatedRouteConfig)[] = []) {
+  const newRoutes = appRoutes.map(route =>
+    typeof route === 'string'
+      ? { pattern: route, description: `Application-defined public route: ${route}` }
+      : route
+  );
+  configuredRoutes = [...defaultUnauthenticatedRoutes, ...newRoutes];
+}
+
+/**
+ * Configures routes that require authentication but bypass 2FA requirements.
+ * Essential for 2FA onboarding flows where user is authenticated but hasn't completed 2FA yet.
+ * @param routes An array of route patterns or ProtectedRouteConfig objects.
+ */
+export function configure2FABypassRoutes(routes: (string | ProtectedRouteConfig)[] = []) {
+  const newRoutes = routes.map(route =>
+    typeof route === 'string'
+      ? { pattern: route, description: `2FA bypass route: ${route}`, twoFactorRequirements: TwoFactorPresets.NONE }
+      : route
+  );
+  configured2FABypassRoutes = [...default2FABypassRoutes, ...newRoutes];
+}
+
+/**
+ * Checks if a route should bypass 2FA requirements (but still requires auth).
+ * @param pathname The URL pathname to check.
+ * @returns The ProtectedRouteConfig if found, otherwise undefined.
+ */
+export function get2FABypassConfig(pathname: string): ProtectedRouteConfig | undefined {
+  return configured2FABypassRoutes.find(route => {
+    if (route.pattern.endsWith('*')) {
+      const basePattern = route.pattern.slice(0, -1);
+      return pathname.startsWith(basePattern);
+    }
+    return pathname === route.pattern;
+  });
+}
+
+/**
+ * Checks if a route should bypass 2FA requirements.
+ * @param pathname The URL pathname to check.
+ * @returns true if 2FA should be bypassed for this route.
+ */
+export function should2FABypass(pathname: string): boolean {
+  return get2FABypassConfig(pathname) !== undefined;
+}
+
+/**
+ * Checks if a given pathname matches any of the configured unauthenticated routes.
+ * Supports wildcard matching (e.g., '/api/*').
+ * @param pathname The URL pathname to check.
+ * @returns `true` if the route is unauthenticated, `false` otherwise.
+ */
+export function isUnauthenticatedRoute(pathname: string): boolean {
+  return configuredRoutes.some(route => {
+    if (route.pattern.endsWith('*')) {
+      const basePattern = route.pattern.slice(0, -1);
+      return pathname.startsWith(basePattern);
+    }
+    return pathname === route.pattern;
+  });
+}
+
+/**
+ * Retrieves the configuration for a specific route.
+ * @param pathname The URL pathname to get the configuration for.
+ * @returns The `UnauthenticatedRouteConfig` object if found, otherwise `undefined`.
+ */
+export function getRouteConfig(pathname: string): UnauthenticatedRouteConfig | undefined {
+  return configuredRoutes.find(route => {
+    if (route.pattern.endsWith('*')) {
+      const basePattern = route.pattern.slice(0, -1);
+      return pathname.startsWith(basePattern);
+    }
+    return pathname === route.pattern;
+  });
+}