@payez/next-mvp 4.0.1 → 4.0.3

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

@@ -0,0 +1,114 @@
+"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 auth_1 = require("../../server/auth");
+const startup_init_1 = require("../../lib/startup-init");
+const idp_client_config_1 = require("../../lib/idp-client-config");
+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 session from Better Auth
+        const betterAuthSession = await (0, auth_1.getSession)(req);
+        // Debug logging
+        if (!betterAuthSession) {
+            console.warn('[VIABILITY] getSession returned null');
+        }
+        const sessionToken = betterAuthSession?.session?.token;
+        if (betterAuthSession && 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,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+const server_1 = require("next/server");
+const auth_1 = require("../../server/auth");
+const session_store_1 = require("../../lib/session-store");
+/**
+ * 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 betterAuthSession = await (0, auth_1.getSession)(req);
+        let sessionToken = betterAuthSession?.session?.token;
+        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 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
+    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/better-auth.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Better Auth Configuration
+ *
+ * Primary auth configuration. Replaces the former NextAuth auth-options.ts.
+ *
+ * Architecture: No database adapter — Better Auth runs in stateless mode
+ * with JWE cookie cache. User management stays on IDP, sessions on Redis.
+ *
+ * @see BETTER-AUTH-MIGRATION-SPEC.md
+ */
+import 'server-only';
+import type { IDPClientConfig } from '../lib/idp-client-config';
+/**
+ * Better Auth social provider config shape.
+ */
+export interface BetterAuthSocialProvider {
+    clientId: string;
+    clientSecret: string;
+    scope?: string[];
+}
+/**
+ * Build Better Auth social providers from IDP config.
+ */
+export declare function buildBetterAuthProviders(config: IDPClientConfig): Record<string, BetterAuthSocialProvider>;
+/**
+ * Create Better Auth instance from IDP config.
+ *
+ * No database — runs in stateless mode with JWE cookie cache.
+ * Call after getIDPClientConfig() resolves.
+ */
+export declare function createBetterAuthInstance(idpConfig: IDPClientConfig): import("better-auth").Auth<{
+    secret: string;
+    socialProviders: Record<string, BetterAuthSocialProvider>;
+    trustedOrigins: string[];
+    session: {
+        cookieCache: {
+            enabled: true;
+            maxAge: number;
+            refreshCache: true;
+        };
+    };
+    plugins: [{
+        id: "next-cookies";
+        hooks: {
+            before: {
+                matcher(ctx: import("better-auth").HookEndpointContext): boolean;
+                handler: (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>;
+            }[];
+            after: {
+                matcher(ctx: import("better-auth").HookEndpointContext): true;
+                handler: (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>;
+            }[];
+        };
+    }];
+}>;
+/**
+ * Better Auth is always enabled (NextAuth removed in 4.0).
+ */
+export declare function isBetterAuthEnabled(): boolean;
+/**
+ * Get flag-gated auth handler for Next.js route.
+ *
+ * When USE_BETTER_AUTH=true, returns Better Auth handlers.
+ * Otherwise returns null (auth disabled).
+ *
+ * Usage in host app route:
+ * ```ts
+ * import { getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
+ *
+ * export async function GET(req: Request) {
+ *   const ba = await getBetterAuthHandler();
+ *   if (ba) return ba.GET(req);
+ * }
+ * ```
+ */
+export declare function getBetterAuthHandler(): Promise<{
+    GET: (req: Request) => Promise<Response>;
+    POST: (req: Request) => Promise<Response>;
+} | null>;

package/dist/auth/better-auth.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Better Auth Configuration
+ *
+ * Primary auth configuration. Replaces the former NextAuth auth-options.ts.
+ *
+ * Architecture: No database adapter — Better Auth runs in stateless mode
+ * with JWE cookie cache. User management stays on IDP, sessions on Redis.
+ *
+ * @see BETTER-AUTH-MIGRATION-SPEC.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBetterAuthProviders = buildBetterAuthProviders;
+exports.createBetterAuthInstance = createBetterAuthInstance;
+exports.isBetterAuthEnabled = isBetterAuthEnabled;
+exports.getBetterAuthHandler = getBetterAuthHandler;
+require("server-only");
+const better_auth_1 = require("better-auth");
+const next_js_1 = require("better-auth/next-js");
+const next_js_2 = require("better-auth/next-js");
+const idp_client_config_1 = require("../lib/idp-client-config");
+/**
+ * Build Better Auth social providers from IDP config.
+ */
+function buildBetterAuthProviders(config) {
+    const providers = {};
+    for (const oauth of config.oauthProviders || []) {
+        if (!oauth.enabled)
+            continue;
+        const name = oauth.provider.toLowerCase();
+        providers[name] = {
+            clientId: oauth.clientId,
+            clientSecret: oauth.clientSecret,
+            scope: oauth.scopes?.split(' '),
+        };
+    }
+    return providers;
+}
+/**
+ * Create Better Auth instance from IDP config.
+ *
+ * No database — runs in stateless mode with JWE cookie cache.
+ * Call after getIDPClientConfig() resolves.
+ */
+function createBetterAuthInstance(idpConfig) {
+    return (0, better_auth_1.betterAuth)({
+        secret: idpConfig.nextAuthSecret,
+        socialProviders: buildBetterAuthProviders(idpConfig),
+        // Trust the app's own origin + any configured base URL
+        trustedOrigins: [
+            ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
+            ...(process.env.BETTER_AUTH_URL ? [process.env.BETTER_AUTH_URL] : []),
+            'http://localhost:3000',
+            'http://localhost:3400',
+            'http://localhost:3600',
+        ],
+        // No database — stateless mode. Better Auth defaults to JWE cookie cache.
+        // Session cookie cache with refreshCache for DB-less setup.
+        session: {
+            cookieCache: {
+                enabled: true,
+                maxAge: 300,
+                refreshCache: true,
+            },
+        },
+        plugins: [
+            (0, next_js_1.nextCookies)(),
+        ],
+    });
+}
+/**
+ * Better Auth is always enabled (NextAuth removed in 4.0).
+ */
+function isBetterAuthEnabled() {
+    return true;
+}
+/**
+ * Get Better Auth Next.js route handlers (GET, POST).
+ * Initializes Better Auth from IDP config on first call, caches the instance.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let cachedInstance = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let initPromise = null;
+async function getBetterAuthInstance() {
+    if (cachedInstance)
+        return cachedInstance;
+    if (!initPromise) {
+        initPromise = (0, idp_client_config_1.getIDPClientConfig)().then(config => {
+            const instance = createBetterAuthInstance(config);
+            cachedInstance = instance;
+            console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
+            return instance;
+        });
+    }
+    return initPromise;
+}
+/**
+ * Get flag-gated auth handler for Next.js route.
+ *
+ * When USE_BETTER_AUTH=true, returns Better Auth handlers.
+ * Otherwise returns null (auth disabled).
+ *
+ * Usage in host app route:
+ * ```ts
+ * import { getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
+ *
+ * export async function GET(req: Request) {
+ *   const ba = await getBetterAuthHandler();
+ *   if (ba) return ba.GET(req);
+ * }
+ * ```
+ */
+async function getBetterAuthHandler() {
+    if (!isBetterAuthEnabled())
+        return null;
+    const auth = await getBetterAuthInstance();
+    return (0, next_js_2.toNextJsHandler)(auth);
+}

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;