@payez/next-mvp 3.0.0

package/dist/edge/internal-api-url.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Internal API URL Utility for Edge Runtime
+ *
+ * INTERNAL_API_URL is REQUIRED. This is the URL for THIS application calling ITSELF.
+ * Used for middleware to call its own API routes (e.g., /api/session/viability).
+ *
+ * WHY HTTP IS REQUIRED (not optional):
+ * - This is the app calling its OWN backend within the same pod/container
+ * - NextAuth cookies are encrypted based on request protocol
+ * - TLS is terminated at ingress, so the pod receives HTTP internally
+ * - Using HTTPS here causes cookie decryption failures
+ * - This is NOT about "K8s internal traffic doesn't need TLS" - it's about
+ *   protocol consistency for cookie encryption
+ *
+ * This is NOT for calling the IDP - use IDP_URL for that.
+ *
+ * For local dev, set INTERNAL_API_URL=http://localhost:3000 (or your dev port).
+ *
+ * @module edge/internal-api-url
+ * @version 3.0.0
+ */
+import { NextRequest } from 'next/server';
+/**
+ * Get the internal API base URL for middleware to call its own API routes.
+ *
+ * THROWS if INTERNAL_API_URL is not set. No fallbacks.
+ *
+ * @param request - The Next.js request object (unused, kept for API compatibility)
+ * @returns Base URL string for constructing internal API calls
+ * @throws Error if INTERNAL_API_URL environment variable is not set
+ *
+ * @example
+ * ```typescript
+ * import { getInternalApiUrl } from '@payez/next-mvp/edge';
+ *
+ * export async function middleware(request: NextRequest) {
+ *   const baseUrl = getInternalApiUrl(request);
+ *   const apiUrl = new URL('/api/session/check', baseUrl);
+ *
+ *   const response = await fetch(apiUrl, {
+ *     headers: {
+ *       'Cookie': request.headers.get('cookie') || ''
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @environment INTERNAL_API_URL - REQUIRED. URL for this app to call ITSELF.
+ *   MUST be HTTP (not HTTPS) - see module docs for why.
+ *   K8s: http://myapp.namespace.svc.cluster.local:80
+ *   Local: http://localhost:3000
+ */
+export declare function getInternalApiUrl(request: NextRequest): string;

package/dist/edge/internal-api-url.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Internal API URL Utility for Edge Runtime
+ *
+ * INTERNAL_API_URL is REQUIRED. This is the URL for THIS application calling ITSELF.
+ * Used for middleware to call its own API routes (e.g., /api/session/viability).
+ *
+ * WHY HTTP IS REQUIRED (not optional):
+ * - This is the app calling its OWN backend within the same pod/container
+ * - NextAuth cookies are encrypted based on request protocol
+ * - TLS is terminated at ingress, so the pod receives HTTP internally
+ * - Using HTTPS here causes cookie decryption failures
+ * - This is NOT about "K8s internal traffic doesn't need TLS" - it's about
+ *   protocol consistency for cookie encryption
+ *
+ * This is NOT for calling the IDP - use IDP_URL for that.
+ *
+ * For local dev, set INTERNAL_API_URL=http://localhost:3000 (or your dev port).
+ *
+ * @module edge/internal-api-url
+ * @version 3.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInternalApiUrl = getInternalApiUrl;
+/**
+ * Get the internal API base URL for middleware to call its own API routes.
+ *
+ * THROWS if INTERNAL_API_URL is not set. No fallbacks.
+ *
+ * @param request - The Next.js request object (unused, kept for API compatibility)
+ * @returns Base URL string for constructing internal API calls
+ * @throws Error if INTERNAL_API_URL environment variable is not set
+ *
+ * @example
+ * ```typescript
+ * import { getInternalApiUrl } from '@payez/next-mvp/edge';
+ *
+ * export async function middleware(request: NextRequest) {
+ *   const baseUrl = getInternalApiUrl(request);
+ *   const apiUrl = new URL('/api/session/check', baseUrl);
+ *
+ *   const response = await fetch(apiUrl, {
+ *     headers: {
+ *       'Cookie': request.headers.get('cookie') || ''
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @environment INTERNAL_API_URL - REQUIRED. URL for this app to call ITSELF.
+ *   MUST be HTTP (not HTTPS) - see module docs for why.
+ *   K8s: http://myapp.namespace.svc.cluster.local:80
+ *   Local: http://localhost:3000
+ */
+function getInternalApiUrl(request) {
+    const internalUrl = process.env.INTERNAL_API_URL;
+    if (!internalUrl) {
+        throw new Error('[INTERNAL_API_URL] FATAL: INTERNAL_API_URL environment variable is REQUIRED. ' +
+            'This is for the app to call ITSELF. MUST be HTTP (not HTTPS). ' +
+            'Set to http://myapp.namespace.svc.cluster.local:80 (K8s) or http://localhost:3000 (local).');
+    }
+    return internalUrl;
+}

package/dist/edge/middleware.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Edge Runtime Compatible Exports
+ *
+ * This module exports only Edge Runtime compatible code for use in Next.js middleware.
+ * Client-side utilities that depend on browser APIs or server-only code are excluded.
+ */
+export { makeAuthDecision } from '../auth/auth-decision';
+export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig, configure2FABypassRoutes, should2FABypass, get2FABypassConfig } from '../auth/route-config';
+export type { UnauthenticatedRouteConfig, ProtectedRouteConfig } from '../auth/route-config';
+export { createMvpMiddleware } from '../middleware/create-middleware';
+export type { MvpMiddlewareOptions, CircuitBreakerProvider, MiddlewareLogger, AuthContext, AuthAction, SessionPointer, SessionStatus } from '../middleware/create-middleware';
+export { TwoFactorPresets, AMRValues, ACRLevels, validateAMR, validateACR, checkTwoFactorRequirements } from '../middleware/twofa-presets';
+export type { TwoFactorRequirements, RouteConfig } from '../middleware/twofa-presets';
+export { getInternalApiUrl } from './internal-api-url';

package/dist/edge/middleware.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Edge Runtime Compatible Exports
+ *
+ * This module exports only Edge Runtime compatible code for use in Next.js middleware.
+ * Client-side utilities that depend on browser APIs or server-only code are excluded.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInternalApiUrl = exports.checkTwoFactorRequirements = exports.validateACR = exports.validateAMR = exports.ACRLevels = exports.AMRValues = exports.TwoFactorPresets = exports.createMvpMiddleware = exports.get2FABypassConfig = exports.should2FABypass = exports.configure2FABypassRoutes = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = void 0;
+// Authentication middleware and configuration (Edge Runtime compatible)
+var auth_decision_1 = require("../auth/auth-decision");
+Object.defineProperty(exports, "makeAuthDecision", { enumerable: true, get: function () { return auth_decision_1.makeAuthDecision; } });
+var route_config_1 = require("../auth/route-config");
+Object.defineProperty(exports, "isUnauthenticatedRoute", { enumerable: true, get: function () { return route_config_1.isUnauthenticatedRoute; } });
+Object.defineProperty(exports, "configurePublicRoutes", { enumerable: true, get: function () { return route_config_1.configurePublicRoutes; } });
+Object.defineProperty(exports, "getRouteConfig", { enumerable: true, get: function () { return route_config_1.getRouteConfig; } });
+Object.defineProperty(exports, "configure2FABypassRoutes", { enumerable: true, get: function () { return route_config_1.configure2FABypassRoutes; } });
+Object.defineProperty(exports, "should2FABypass", { enumerable: true, get: function () { return route_config_1.should2FABypass; } });
+Object.defineProperty(exports, "get2FABypassConfig", { enumerable: true, get: function () { return route_config_1.get2FABypassConfig; } });
+var create_middleware_1 = require("../middleware/create-middleware");
+Object.defineProperty(exports, "createMvpMiddleware", { enumerable: true, get: function () { return create_middleware_1.createMvpMiddleware; } });
+// Two-Factor Authentication Presets (Edge Runtime compatible)
+var twofa_presets_1 = require("../middleware/twofa-presets");
+Object.defineProperty(exports, "TwoFactorPresets", { enumerable: true, get: function () { return twofa_presets_1.TwoFactorPresets; } });
+Object.defineProperty(exports, "AMRValues", { enumerable: true, get: function () { return twofa_presets_1.AMRValues; } });
+Object.defineProperty(exports, "ACRLevels", { enumerable: true, get: function () { return twofa_presets_1.ACRLevels; } });
+Object.defineProperty(exports, "validateAMR", { enumerable: true, get: function () { return twofa_presets_1.validateAMR; } });
+Object.defineProperty(exports, "validateACR", { enumerable: true, get: function () { return twofa_presets_1.validateACR; } });
+Object.defineProperty(exports, "checkTwoFactorRequirements", { enumerable: true, get: function () { return twofa_presets_1.checkTwoFactorRequirements; } });
+// Internal API URL utilities for Edge Runtime
+var internal_api_url_1 = require("./internal-api-url");
+Object.defineProperty(exports, "getInternalApiUrl", { enumerable: true, get: function () { return internal_api_url_1.getInternalApiUrl; } });

package/dist/hooks/useAuth.d.ts

@@ -0,0 +1,23 @@
+import { ApiResult } from '../lib/standardized-client-api';
+export interface CustomSession {
+    user: {
+        id: string;
+        email: string;
+        roles?: string[];
+        twoFactorMethod?: string;
+        twoFactorSessionVerified?: boolean;
+        requiresTwoFactor?: boolean;
+    };
+    accessToken?: string;
+    refreshToken?: string;
+    expires: string;
+    error?: string;
+}
+export interface UseAuthResult {
+    session: CustomSession | null;
+    status: 'loading' | 'authenticated' | 'unauthenticated';
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    apiCall: <T>(url: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', data?: any) => Promise<ApiResult<T>>;
+}
+export declare function useAuth(): UseAuthResult;

package/dist/hooks/useAuth.js

@@ -0,0 +1,81 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAuth = useAuth;
+/**
+ * ⚠️ WARNING: This hook cannot be used directly from the @payez/next-mvp package!
+ *
+ * @deprecated Import this hook from your local app instead
+ *
+ * **Why?** React Context (SessionProvider) cannot cross package boundaries in file:// linked packages.
+ *
+ * **Solution:** Create a local version in your app (e.g., src/hooks/useAuth.ts) that imports standardizedApi:
+ *
+ * @example
+ * ```typescript
+ * // src/hooks/useAuth.ts (YOUR APP)
+ * 'use client';
+ * import { useSession } from 'next-auth/react';
+ * import { standardizedApi } from '@payez/next-mvp/lib/standardized-client-api';
+ *
+ * export function useAuth() {
+ *   const { data: session } = useSession(); // Works in your app context
+ *   // ... implementation
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/payez/next-mvp/blob/main/docs/centralized-auth-api-pattern.md#why-local-hooks-for-auth Complete documentation}
+ */
+const react_1 = require("next-auth/react");
+const react_2 = require("react");
+const navigation_1 = require("next/navigation");
+const standardized_client_api_1 = require("../lib/standardized-client-api");
+function useAuth() {
+    const { data: session, status } = (0, react_1.useSession)();
+    const router = (0, navigation_1.useRouter)();
+    const isLoading = status === 'loading';
+    const isAuthenticated = status === 'authenticated' && !!session?.accessToken;
+    // Handle sign out with redirect
+    const handleSignOut = (0, react_2.useCallback)(async () => {
+        await (0, react_1.signOut)({ redirect: false });
+        router.push('/account-auth/login?error=SessionExpired');
+    }, [router]);
+    // API helper that automatically includes the auth token and uses standardized API
+    const apiCall = (0, react_2.useCallback)(async (url, method = 'GET', data) => {
+        if (!session?.accessToken) {
+            console.error('[useAuth] No access token available');
+            throw new Error('Not authenticated');
+        }
+        try {
+            // Use standardized API which handles token refresh and validates response format
+            switch (method) {
+                case 'GET':
+                    return await standardized_client_api_1.standardizedApi.get(url, session.accessToken);
+                case 'POST':
+                    return await standardized_client_api_1.standardizedApi.post(url, data, session.accessToken);
+                case 'PUT':
+                    return await standardized_client_api_1.standardizedApi.put(url, data);
+                case 'DELETE':
+                    return await standardized_client_api_1.standardizedApi.delete(url);
+                default:
+                    throw new Error(`Unsupported method: ${method}`);
+            }
+        }
+        catch (error) {
+            console.error('[useAuth] API call failed:', error);
+            // standardizedApi handles token refresh internally, but if we still get auth errors, sign out
+            if (error instanceof Error && error.message.includes('Authentication failed')) {
+                console.warn('[useAuth] Authentication failed, signing out...');
+                await handleSignOut();
+            }
+            throw error;
+        }
+    }, [session?.accessToken, handleSignOut]);
+    return {
+        session: session,
+        status,
+        isLoading,
+        isAuthenticated,
+        apiCall
+    };
+}

package/dist/hooks/useAuthSettings.d.ts

@@ -0,0 +1,59 @@
+/**
+ * useAuthSettings Hook
+ *
+ * Client-side hook to access auth settings from the IDP config.
+ * Settings are passed through the session from server-side config.
+ */
+import type { AuthSettings } from '../lib/idp-client-config';
+/**
+ * Hook to access auth settings from the session.
+ *
+ * Auth settings are populated from IDP config on the server side
+ * and included in the session for client-side access.
+ *
+ * @returns AuthSettings or null if not available
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const authSettings = useAuthSettings();
+ *
+ *   if (authSettings?.require2FA) {
+ *     return <TwoFactorPrompt />;
+ *   }
+ *
+ *   return <Dashboard />;
+ * }
+ * ```
+ */
+export declare function useAuthSettings(): AuthSettings | null;
+/**
+ * Hook to check if 2FA is required based on auth settings.
+ *
+ * @returns boolean indicating if 2FA is required
+ */
+export declare function useRequires2FA(): boolean;
+/**
+ * Hook to get allowed 2FA methods.
+ *
+ * @returns Array of allowed 2FA method strings (e.g., ['email', 'sms', 'totp'])
+ */
+export declare function useAllowed2FAMethods(): string[];
+/**
+ * Hook to get session timeout settings.
+ *
+ * @returns Object with session and idle timeout minutes
+ */
+export declare function useSessionTimeouts(): {
+    sessionTimeoutMinutes: number;
+    idleTimeoutMinutes: number;
+};
+/**
+ * Hook to check if remember me is allowed.
+ *
+ * @returns Object with allowRememberMe flag and rememberMeDays
+ */
+export declare function useRememberMeSettings(): {
+    allowRememberMe: boolean;
+    rememberMeDays: number;
+};

package/dist/hooks/useAuthSettings.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * useAuthSettings Hook
+ *
+ * Client-side hook to access auth settings from the IDP config.
+ * Settings are passed through the session from server-side config.
+ */
+'use client';
+/**
+ * useAuthSettings Hook
+ *
+ * Client-side hook to access auth settings from the IDP config.
+ * Settings are passed through the session from server-side config.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAuthSettings = useAuthSettings;
+exports.useRequires2FA = useRequires2FA;
+exports.useAllowed2FAMethods = useAllowed2FAMethods;
+exports.useSessionTimeouts = useSessionTimeouts;
+exports.useRememberMeSettings = useRememberMeSettings;
+const react_1 = require("next-auth/react");
+/**
+ * Hook to access auth settings from the session.
+ *
+ * Auth settings are populated from IDP config on the server side
+ * and included in the session for client-side access.
+ *
+ * @returns AuthSettings or null if not available
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const authSettings = useAuthSettings();
+ *
+ *   if (authSettings?.require2FA) {
+ *     return <TwoFactorPrompt />;
+ *   }
+ *
+ *   return <Dashboard />;
+ * }
+ * ```
+ */
+function useAuthSettings() {
+    const { data: session } = (0, react_1.useSession)();
+    if (!session) {
+        return null;
+    }
+    // Auth settings are included in the session from server-side config
+    const sessionWithSettings = session;
+    return sessionWithSettings.authSettings || null;
+}
+/**
+ * Hook to check if 2FA is required based on auth settings.
+ *
+ * @returns boolean indicating if 2FA is required
+ */
+function useRequires2FA() {
+    const authSettings = useAuthSettings();
+    return authSettings?.require2FA ?? true; // Default to true for security
+}
+/**
+ * Hook to get allowed 2FA methods.
+ *
+ * @returns Array of allowed 2FA method strings (e.g., ['email', 'sms', 'totp'])
+ */
+function useAllowed2FAMethods() {
+    const authSettings = useAuthSettings();
+    return authSettings?.allowed2FAMethods ?? ['email', 'sms'];
+}
+/**
+ * Hook to get session timeout settings.
+ *
+ * @returns Object with session and idle timeout minutes
+ */
+function useSessionTimeouts() {
+    const authSettings = useAuthSettings();
+    return {
+        sessionTimeoutMinutes: authSettings?.sessionTimeoutMinutes ?? 60,
+        idleTimeoutMinutes: authSettings?.idleTimeoutMinutes ?? 15,
+    };
+}
+/**
+ * Hook to check if remember me is allowed.
+ *
+ * @returns Object with allowRememberMe flag and rememberMeDays
+ */
+function useRememberMeSettings() {
+    const authSettings = useAuthSettings();
+    return {
+        allowRememberMe: authSettings?.allowRememberMe ?? true,
+        rememberMeDays: authSettings?.rememberMeDays ?? 30,
+    };
+}

package/dist/hooks/useAvailableProviders.d.ts

@@ -0,0 +1,45 @@
+/**
+ * useAvailableProviders Hook
+ *
+ * Fetches the list of OAuth providers actually configured in NextAuth.
+ * This ensures UI only shows buttons for providers that are enabled in IDP.
+ */
+import { LiteralUnion, ClientSafeProvider } from 'next-auth/react';
+import { BuiltInProviderType } from 'next-auth/providers/index';
+import type { FederatedProvider } from '../types/auth';
+export interface UseAvailableProvidersResult {
+    providers: FederatedProvider[];
+    isLoading: boolean;
+    error: Error | null;
+    rawProviders: Record<LiteralUnion<BuiltInProviderType>, ClientSafeProvider> | null;
+}
+/**
+ * Hook to get available OAuth providers from NextAuth.
+ *
+ * Returns only the providers that are actually configured in auth-options,
+ * which reflects what's enabled in IDP config.
+ *
+ * @example
+ * ```tsx
+ * function SignupPage() {
+ *   const { providers, isLoading } = useAvailableProviders();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <FederatedAuthSection
+ *       providers={providers}
+ *       onProviderClick={handleClick}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useAvailableProviders(): UseAvailableProvidersResult;
+/**
+ * Check if a specific provider is available.
+ *
+ * @param provider The provider to check
+ * @returns boolean indicating if provider is configured
+ */
+export declare function useIsProviderAvailable(provider: FederatedProvider): boolean;

package/dist/hooks/useAvailableProviders.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * useAvailableProviders Hook
+ *
+ * Fetches the list of OAuth providers actually configured in NextAuth.
+ * This ensures UI only shows buttons for providers that are enabled in IDP.
+ */
+'use client';
+/**
+ * useAvailableProviders Hook
+ *
+ * Fetches the list of OAuth providers actually configured in NextAuth.
+ * This ensures UI only shows buttons for providers that are enabled in IDP.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAvailableProviders = useAvailableProviders;
+exports.useIsProviderAvailable = useIsProviderAvailable;
+const react_1 = require("react");
+const react_2 = require("next-auth/react");
+// Map NextAuth provider IDs to our FederatedProvider type
+const PROVIDER_MAP = {
+    'google': 'google',
+    'apple': 'apple',
+    'facebook': 'facebook',
+    'github': 'github',
+    'azure-ad': 'microsoft',
+    'microsoft-entra-id': 'microsoft',
+};
+// Providers we support in UI (excludes credentials)
+const OAUTH_PROVIDERS = ['google', 'apple', 'facebook', 'github', 'azure-ad', 'microsoft-entra-id'];
+/**
+ * Hook to get available OAuth providers from NextAuth.
+ *
+ * Returns only the providers that are actually configured in auth-options,
+ * which reflects what's enabled in IDP config.
+ *
+ * @example
+ * ```tsx
+ * function SignupPage() {
+ *   const { providers, isLoading } = useAvailableProviders();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <FederatedAuthSection
+ *       providers={providers}
+ *       onProviderClick={handleClick}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+function useAvailableProviders() {
+    const [providers, setProviders] = (0, react_1.useState)([]);
+    const [rawProviders, setRawProviders] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        let mounted = true;
+        async function fetchProviders() {
+            try {
+                const result = await (0, react_2.getProviders)();
+                if (!mounted)
+                    return;
+                setRawProviders(result);
+                if (result) {
+                    // Filter to OAuth providers only (exclude credentials)
+                    // Map to our FederatedProvider type
+                    const oauthProviders = Object.keys(result)
+                        .filter(id => OAUTH_PROVIDERS.includes(id))
+                        .map(id => PROVIDER_MAP[id])
+                        .filter((p) => p !== undefined);
+                    setProviders(oauthProviders);
+                }
+                else {
+                    setProviders([]);
+                }
+                setError(null);
+            }
+            catch (err) {
+                if (!mounted)
+                    return;
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setProviders([]);
+            }
+            finally {
+                if (mounted) {
+                    setIsLoading(false);
+                }
+            }
+        }
+        fetchProviders();
+        return () => {
+            mounted = false;
+        };
+    }, []);
+    return { providers, isLoading, error, rawProviders };
+}
+/**
+ * Check if a specific provider is available.
+ *
+ * @param provider The provider to check
+ * @returns boolean indicating if provider is configured
+ */
+function useIsProviderAvailable(provider) {
+    const { providers } = useAvailableProviders();
+    return providers.includes(provider);
+}

package/dist/hooks/usePasswordValidation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Password Validation Hook for @payez/next-mvp
+ *
+ * Provides real-time password validation against IDP password policy.
+ * Uses debounced API calls to validate password strength.
+ */
+interface PasswordPolicy {
+    min_length?: number;
+    require_uppercase?: boolean;
+    require_lowercase?: boolean;
+    require_digit?: boolean;
+    require_special?: boolean;
+    min_strength_score?: number;
+}
+interface UsePasswordValidationOptions {
+    debounceMs?: number;
+}
+export declare function usePasswordValidation(options?: UsePasswordValidationOptions): {
+    setPassword: (password: string) => void;
+    isValid: boolean;
+    score: number;
+    failedRequirements: string[];
+    tip: string | undefined;
+    policy: PasswordPolicy | undefined;
+    isValidating: boolean;
+};
+export {};