@payez/next-mvp 3.0.0

package/dist/auth/providers/oauth.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * 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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOAuthProviders = buildOAuthProviders;
+exports.getEnabledProviderNames = getEnabledProviderNames;
+const google_1 = __importDefault(require("next-auth/providers/google"));
+const apple_1 = __importDefault(require("next-auth/providers/apple"));
+const facebook_1 = __importDefault(require("next-auth/providers/facebook"));
+const github_1 = __importDefault(require("next-auth/providers/github"));
+const azure_ad_1 = __importDefault(require("next-auth/providers/azure-ad"));
+// ============================================================================
+// 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
+ */
+function buildOAuthProviders(config) {
+    const providers = [];
+    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) {
+    const providerName = oauth.provider.toLowerCase();
+    switch (providerName) {
+        case 'google':
+            return (0, google_1.default)({
+                clientId: oauth.clientId,
+                clientSecret: oauth.clientSecret,
+                authorization: {
+                    params: {
+                        scope: oauth.scopes || 'openid email profile',
+                    },
+                },
+            });
+        case 'apple':
+            return (0, apple_1.default)({
+                clientId: oauth.clientId,
+                clientSecret: oauth.clientSecret,
+                authorization: {
+                    params: {
+                        scope: oauth.scopes || 'name email',
+                    },
+                },
+            });
+        case 'facebook':
+            return (0, facebook_1.default)({
+                clientId: oauth.clientId,
+                clientSecret: oauth.clientSecret,
+            });
+        case 'github':
+            return (0, github_1.default)({
+                clientId: oauth.clientId,
+                clientSecret: oauth.clientSecret,
+            });
+        case 'microsoft':
+        case 'azure_ad':
+        case 'azure-ad':
+        case 'azuread':
+            return (0, azure_ad_1.default)({
+                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.
+ */
+function getEnabledProviderNames(config) {
+    return (config.oauthProviders || [])
+        .filter((p) => p.enabled)
+        .map((p) => p.provider);
+}

package/dist/auth/route-config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 } 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;
+}
+/**
+ * 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 declare function configurePublicRoutes(appRoutes?: (string | UnauthenticatedRouteConfig)[]): void;
+/**
+ * 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 declare function configure2FABypassRoutes(routes?: (string | ProtectedRouteConfig)[]): void;
+/**
+ * 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 declare function get2FABypassConfig(pathname: string): ProtectedRouteConfig | undefined;
+/**
+ * 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 declare function should2FABypass(pathname: string): boolean;
+/**
+ * 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 declare function isUnauthenticatedRoute(pathname: string): boolean;
+/**
+ * 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 declare function getRouteConfig(pathname: string): UnauthenticatedRouteConfig | undefined;

package/dist/auth/route-config.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configurePublicRoutes = configurePublicRoutes;
+exports.configure2FABypassRoutes = configure2FABypassRoutes;
+exports.get2FABypassConfig = get2FABypassConfig;
+exports.should2FABypass = should2FABypass;
+exports.isUnauthenticatedRoute = isUnauthenticatedRoute;
+exports.getRouteConfig = getRouteConfig;
+const twofa_presets_1 = require("../middleware/twofa-presets");
+// Default public routes provided by the MVP package
+const defaultUnauthenticatedRoutes = [
+    {
+        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 = [...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 = [
+    {
+        pattern: '/api/auth/*',
+        description: 'NextAuth.js API routes - must be accessible during 2FA flow for session management',
+        twoFactorRequirements: twofa_presets_1.TwoFactorPresets.NONE
+    },
+    {
+        pattern: '/api/account/*',
+        description: '2FA verification APIs (send-code, verify-email, verify-sms, update-phone, masked-info)',
+        twoFactorRequirements: twofa_presets_1.TwoFactorPresets.NONE
+    },
+    {
+        pattern: '/api/session/*',
+        description: 'Session management APIs (viability, refresh-viability)',
+        twoFactorRequirements: twofa_presets_1.TwoFactorPresets.NONE
+    },
+    {
+        pattern: '/account-auth/verify-code',
+        description: '2FA verification page',
+        twoFactorRequirements: twofa_presets_1.TwoFactorPresets.NONE
+    },
+    {
+        pattern: '/test-env/*',
+        description: 'Test/debug pages (emergency-logout, jwt-inspect, refresh-token) - must bypass 2FA',
+        twoFactorRequirements: twofa_presets_1.TwoFactorPresets.NONE
+    },
+    // NOTE: /onboarding/two-factor intentionally NOT included - go straight to 2FA, no welcome page
+];
+let configured2FABypassRoutes = [...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.
+ */
+function configurePublicRoutes(appRoutes = []) {
+    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.
+ */
+function configure2FABypassRoutes(routes = []) {
+    const newRoutes = routes.map(route => typeof route === 'string'
+        ? { pattern: route, description: `2FA bypass route: ${route}`, twoFactorRequirements: twofa_presets_1.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.
+ */
+function get2FABypassConfig(pathname) {
+    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.
+ */
+function should2FABypass(pathname) {
+    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.
+ */
+function isUnauthenticatedRoute(pathname) {
+    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`.
+ */
+function getRouteConfig(pathname) {
+    return configuredRoutes.find(route => {
+        if (route.pattern.endsWith('*')) {
+            const basePattern = route.pattern.slice(0, -1);
+            return pathname.startsWith(basePattern);
+        }
+        return pathname === route.pattern;
+    });
+}