@payez/next-mvp 3.0.0

package/dist/auth/utils/token-utils.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Token Utilities
+ *
+ * JWT decoding and expiry checking utilities.
+ * Extracted from auth-options.ts for clarity.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractKidFromToken = exports.decodeJwtHeader = void 0;
+exports.decodeIdpAccessToken = decodeIdpAccessToken;
+exports.decodeIdpAccessTokenFull = decodeIdpAccessTokenFull;
+exports.extractEmailFromToken = extractEmailFromToken;
+exports.extractRolesFromToken = extractRolesFromToken;
+exports.extractAmrFromToken = extractAmrFromToken;
+exports.tokenNeedsRefresh = tokenNeedsRefresh;
+exports.tokenIsExpired = tokenIsExpired;
+exports.msUntilExpiry = msUntilExpiry;
+exports.expClaimToMs = expClaimToMs;
+exports.validateTokenExpiry = validateTokenExpiry;
+const jwt_decode_1 = require("../../lib/jwt-decode");
+// Re-export header utilities for consumers
+var jwt_decode_2 = require("../../lib/jwt-decode");
+Object.defineProperty(exports, "decodeJwtHeader", { enumerable: true, get: function () { return jwt_decode_2.decodeJwtHeader; } });
+Object.defineProperty(exports, "extractKidFromToken", { enumerable: true, get: function () { return jwt_decode_2.extractKidFromToken; } });
+// ============================================================================
+// TOKEN DECODING
+// ============================================================================
+/**
+ * Decode an IDP access token and extract claims.
+ *
+ * @param token - The JWT access token from IDP
+ * @returns Decoded token claims, or null if decode fails
+ */
+function decodeIdpAccessToken(token) {
+    try {
+        return (0, jwt_decode_1.jwtDecode)(token);
+    }
+    catch (error) {
+        console.error('[TOKEN_UTILS] Failed to decode access token:', error);
+        return null;
+    }
+}
+/**
+ * Decode both JWT header and payload from an IDP access token.
+ * Returns the signing key ID (kid) along with payload claims.
+ *
+ * @param token - The JWT access token from IDP
+ * @returns Object with header (including kid) and payload, or null if decode fails
+ */
+function decodeIdpAccessTokenFull(token) {
+    try {
+        const header = (0, jwt_decode_1.decodeJwtHeader)(token);
+        const payload = (0, jwt_decode_1.jwtDecode)(token);
+        if (!header || !payload) {
+            return null;
+        }
+        return {
+            header,
+            payload,
+            bearerKeyId: header.kid,
+        };
+    }
+    catch (error) {
+        console.error('[TOKEN_UTILS] Failed to decode access token (full):', error);
+        return null;
+    }
+}
+/**
+ * Extract user email from decoded token.
+ * Handles multiple possible claim names used by IDP.
+ */
+function extractEmailFromToken(decoded) {
+    return (decoded.email ||
+        decoded['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'] ||
+        '');
+}
+/**
+ * Extract roles from decoded token.
+ * Handles both 'role' and 'roles' claims, and both string and array formats.
+ */
+function extractRolesFromToken(decoded) {
+    const rolesClaim = decoded.role || decoded.roles;
+    if (!rolesClaim) {
+        return [];
+    }
+    if (Array.isArray(rolesClaim)) {
+        return rolesClaim;
+    }
+    if (typeof rolesClaim === 'string') {
+        // Could be a single role or JSON array string
+        try {
+            const parsed = JSON.parse(rolesClaim);
+            return Array.isArray(parsed) ? parsed : [rolesClaim];
+        }
+        catch {
+            return [rolesClaim];
+        }
+    }
+    return [];
+}
+/**
+ * Extract AMR (Authentication Methods References) from decoded token.
+ */
+function extractAmrFromToken(decoded) {
+    const amr = decoded.amr;
+    if (!amr) {
+        return [];
+    }
+    if (Array.isArray(amr)) {
+        return amr;
+    }
+    if (typeof amr === 'string') {
+        try {
+            const parsed = JSON.parse(amr);
+            return Array.isArray(parsed) ? parsed : [amr];
+        }
+        catch {
+            return [amr];
+        }
+    }
+    return [];
+}
+// ============================================================================
+// EXPIRY CHECKING
+// ============================================================================
+/**
+ * Check if a token expiry timestamp indicates the token needs refresh.
+ *
+ * @param expiresAt - Token expiry timestamp (Unix milliseconds)
+ * @param bufferMs - How early to trigger refresh (default 5 minutes)
+ * @returns true if token is expired or will expire within buffer period
+ */
+function tokenNeedsRefresh(expiresAt, bufferMs = 5 * 60 * 1000) {
+    if (!expiresAt) {
+        return true; // No expiry info = assume needs refresh
+    }
+    const timeUntilExpiry = expiresAt - Date.now();
+    return timeUntilExpiry <= bufferMs;
+}
+/**
+ * Check if a token is completely expired (past its exp time).
+ *
+ * @param expiresAt - Token expiry timestamp (Unix milliseconds)
+ * @returns true if token is expired
+ */
+function tokenIsExpired(expiresAt) {
+    if (!expiresAt) {
+        return true;
+    }
+    return Date.now() >= expiresAt;
+}
+/**
+ * Calculate milliseconds until token expires.
+ *
+ * @param expiresAt - Token expiry timestamp (Unix milliseconds)
+ * @returns Milliseconds until expiry, or 0 if already expired
+ */
+function msUntilExpiry(expiresAt) {
+    if (!expiresAt) {
+        return 0;
+    }
+    return Math.max(0, expiresAt - Date.now());
+}
+/**
+ * Convert Unix seconds (from JWT exp claim) to milliseconds.
+ */
+function expClaimToMs(exp) {
+    // JWT exp is in seconds, we use milliseconds internally
+    return exp * 1000;
+}
+// ============================================================================
+// TOKEN VALIDATION
+// ============================================================================
+/**
+ * Validate that an access token's actual JWT exp matches what we have cached.
+ * This catches cases where the token was refreshed but cache wasn't updated.
+ *
+ * @param accessToken - The JWT access token
+ * @param cachedExpiresAt - What we think the expiry is (Unix ms)
+ * @returns Object with validation result and actual expiry
+ */
+function validateTokenExpiry(accessToken, cachedExpiresAt) {
+    try {
+        const parts = accessToken.split('.');
+        if (parts.length !== 3) {
+            return { valid: false, actualExpiresAt: null, mismatch: false };
+        }
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+        const actualExpiresAt = payload.exp ? payload.exp * 1000 : null;
+        if (!actualExpiresAt) {
+            return { valid: false, actualExpiresAt: null, mismatch: false };
+        }
+        const now = Date.now();
+        const isExpired = actualExpiresAt < now;
+        // Check for mismatch between cached and actual expiry
+        const mismatch = cachedExpiresAt
+            ? Math.abs(actualExpiresAt - cachedExpiresAt) > 1000 // Allow 1 second tolerance
+            : false;
+        if (mismatch) {
+            console.warn('[TOKEN_UTILS] Token expiry mismatch detected:', {
+                cached: cachedExpiresAt ? new Date(cachedExpiresAt).toISOString() : 'none',
+                actual: new Date(actualExpiresAt).toISOString(),
+                diff: cachedExpiresAt ? actualExpiresAt - cachedExpiresAt : 'N/A',
+            });
+        }
+        return {
+            valid: !isExpired,
+            actualExpiresAt,
+            mismatch,
+        };
+    }
+    catch (error) {
+        console.error('[TOKEN_UTILS] Failed to validate token expiry:', error);
+        return { valid: false, actualExpiresAt: null, mismatch: false };
+    }
+}

package/dist/client/AuthContext.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { AuthConfig, AuthMode, FederatedProvider } from '@/types/auth';
+interface AuthProviderProps {
+    children: ReactNode;
+    config?: Partial<AuthConfig>;
+    /**
+     * If true, providers will be fetched dynamically from NextAuth
+     * instead of using the static providers array from config.
+     * Defaults to true for dynamic provider loading from IDP.
+     */
+    useDynamicProviders?: boolean;
+}
+export declare function AuthProvider({ children, config, useDynamicProviders }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useAuthConfig(): AuthConfig;
+export declare function useAuthMode(): AuthMode;
+export declare function useFederatedProviders(): FederatedProvider[];
+export declare function useFederatedAuthEnabled(): boolean;
+export declare function useTraditionalAuthEnabled(): boolean;
+export {};

package/dist/client/AuthContext.js

@@ -0,0 +1,112 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthProvider = AuthProvider;
+exports.useAuthConfig = useAuthConfig;
+exports.useAuthMode = useAuthMode;
+exports.useFederatedProviders = useFederatedProviders;
+exports.useFederatedAuthEnabled = useFederatedAuthEnabled;
+exports.useTraditionalAuthEnabled = useTraditionalAuthEnabled;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_2 = require("next-auth/react");
+const react_query_1 = require("@tanstack/react-query");
+const AuthContext = (0, react_1.createContext)(null);
+const defaultConfig = {
+    mode: 'traditional',
+    providers: [],
+    enableRecovery: true,
+    enableEmailSignup: true,
+    allowPasswordReset: true,
+};
+// 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',
+};
+// OAuth providers we support in UI (excludes credentials)
+const OAUTH_PROVIDER_IDS = ['google', 'apple', 'facebook', 'github', 'azure-ad', 'microsoft-entra-id'];
+function AuthProvider({ children, config, useDynamicProviders = true }) {
+    const [dynamicProviders, setDynamicProviders] = (0, react_1.useState)([]);
+    const [providersLoaded, setProvidersLoaded] = (0, react_1.useState)(!useDynamicProviders);
+    // Create QueryClient instance for React Query - used internally by MVP hooks
+    const [queryClient] = (0, react_1.useState)(() => new react_query_1.QueryClient({
+        defaultOptions: {
+            queries: {
+                staleTime: 60 * 1000, // 1 minute
+                retry: 1,
+                refetchOnWindowFocus: false,
+            },
+        },
+    }));
+    // Fetch dynamic providers from NextAuth on mount
+    (0, react_1.useEffect)(() => {
+        if (!useDynamicProviders)
+            return;
+        let mounted = true;
+        async function fetchDynamicProviders() {
+            try {
+                const result = await (0, react_2.getProviders)();
+                if (!mounted)
+                    return;
+                if (result) {
+                    // Filter to OAuth providers only and map to FederatedProvider type
+                    const oauthProviders = Object.keys(result)
+                        .filter(id => OAUTH_PROVIDER_IDS.includes(id))
+                        .map(id => PROVIDER_MAP[id])
+                        .filter((p) => p !== undefined);
+                    setDynamicProviders(oauthProviders);
+                }
+            }
+            catch (err) {
+                // Fall back to static config providers on error
+            }
+            finally {
+                if (mounted) {
+                    setProvidersLoaded(true);
+                }
+            }
+        }
+        fetchDynamicProviders();
+        return () => {
+            mounted = false;
+        };
+    }, [useDynamicProviders]);
+    // Determine final providers list
+    const providers = useDynamicProviders && providersLoaded
+        ? dynamicProviders
+        : (config?.providers ?? defaultConfig.providers);
+    const authConfig = {
+        ...defaultConfig,
+        ...config,
+        providers, // Override with dynamic providers if enabled
+    };
+    return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(AuthContext.Provider, { value: authConfig, children: children }) }));
+}
+function useAuthConfig() {
+    const context = (0, react_1.useContext)(AuthContext);
+    if (!context) {
+        return defaultConfig;
+    }
+    return context;
+}
+function useAuthMode() {
+    const config = useAuthConfig();
+    return config.mode;
+}
+function useFederatedProviders() {
+    const config = useAuthConfig();
+    return config.providers;
+}
+function useFederatedAuthEnabled() {
+    const config = useAuthConfig();
+    return config.mode === 'federated' && config.providers.length > 0;
+}
+function useTraditionalAuthEnabled() {
+    const config = useAuthConfig();
+    return config.mode === 'traditional';
+}

package/dist/client/fetch-with-auth.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A wrapper for the `fetch` API that automatically injects the session's
+ * accessToken into the Authorization header and handles 401 Unauthorized
+ * responses by redirecting the user to the login page.
+ *
+ * @param url The URL to fetch.
+ * @param options The standard `fetch` options.
+ * @returns A `Promise` that resolves to the `Response` object.
+ * @throws An 'UNAUTHORIZED_REDIRECT' error after initiating the redirect to halt further execution.
+ */
+export declare function fetchWithAuth(url: string, options?: RequestInit): Promise<Response>;

package/dist/client/fetch-with-auth.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWithAuth = fetchWithAuth;
+// src/client/fetch-with-auth.ts
+const react_1 = require("next-auth/react");
+/**
+ * A wrapper for the `fetch` API that automatically injects the session's
+ * accessToken into the Authorization header and handles 401 Unauthorized
+ * responses by redirecting the user to the login page.
+ *
+ * @param url The URL to fetch.
+ * @param options The standard `fetch` options.
+ * @returns A `Promise` that resolves to the `Response` object.
+ * @throws An 'UNAUTHORIZED_REDIRECT' error after initiating the redirect to halt further execution.
+ */
+async function fetchWithAuth(url, options = {}) {
+    // 1. Retrieve the client-side session to get the accessToken.
+    const session = await (0, react_1.getSession)();
+    // 2. Inject the accessToken into the Authorization header.
+    const headers = new Headers(options.headers);
+    if (session?.accessToken) {
+        headers.set('Authorization', `Bearer ${session.accessToken}`);
+    }
+    options.headers = headers;
+    const response = await fetch(url, options);
+    // 3. Handle the 401 response intelligently.
+    if (response.status === 401) {
+        // If we have a valid session, this is likely a claim/permission error, not an auth error
+        if (session?.accessToken) {
+            console.warn('API returned 401 despite valid session. Likely insufficient claims or permissions.');
+            // Don't redirect - let the calling code handle the error gracefully
+            return response;
+        }
+        // No valid session - this is a real authentication failure
+        console.error('Unauthorized API call (no valid session). Redirecting to login.');
+        // SAFEGUARD: Never use auth pages as callback URLs to prevent redirect loops
+        const pathname = window.location.pathname;
+        const safeCallbackUrl = pathname.startsWith('/account-auth/') ? '/' : pathname;
+        window.location.href = `/account-auth/login?callbackUrl=${encodeURIComponent(safeCallbackUrl)}`;
+        // Throw a specific error to signal that a redirect has been initiated.
+        throw new Error('UNAUTHORIZED_REDIRECT');
+    }
+    return response;
+}

package/dist/client/fetchWithSession.d.ts

@@ -0,0 +1,3 @@
+export declare function fetchWithSession(input: RequestInfo | URL, init?: RequestInit, opts?: {
+    retry?: number;
+}): Promise<Response>;

package/dist/client/fetchWithSession.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchWithSession = fetchWithSession;
+async function fetchWithSession(input, init = {}, opts = {}) {
+    const retry = opts.retry ?? 1;
+    const doFetch = async () => {
+        const res = await fetch(input, { ...init, credentials: 'include' });
+        if (res.ok)
+            return res;
+        if (res.status === 401 && retry > 0) {
+            const rf = await fetch('/api/auth/refresh', { method: 'POST', headers: { 'Accept': 'application/json' }, credentials: 'include' });
+            if (rf.ok)
+                return fetchWithSession(input, init, { retry: retry - 1 });
+        }
+        if ((res.status === 409 || res.status === 503) && retry > 0) {
+            const retryAfter = res.headers.get('Retry-After');
+            const waitMs = retryAfter ? parseInt(retryAfter) * 1000 : 1000;
+            await new Promise(r => setTimeout(r, Math.min(waitMs, 3000)));
+            return fetchWithSession(input, init, { retry: retry - 1 });
+        }
+        return res;
+    };
+    return doFetch();
+}

package/dist/client/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Client-Side Exports
+ *
+ * This module exports only client-safe code for use in browser environments.
+ * Server-only utilities and Node.js dependencies are excluded.
+ */
+export { fetchWithAuth } from './fetch-with-auth';
+export { AuthProvider, useAuthConfig, useAuthMode, useFederatedProviders, useFederatedAuthEnabled, useTraditionalAuthEnabled } from './AuthContext';
+export type { AuthConfig } from '../types/auth';

package/dist/client/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Client-Side Exports
+ *
+ * This module exports only client-safe code for use in browser environments.
+ * Server-only utilities and Node.js dependencies are excluded.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.fetchWithAuth = void 0;
+// Client-side fetch utility
+var fetch_with_auth_1 = require("./fetch-with-auth");
+Object.defineProperty(exports, "fetchWithAuth", { enumerable: true, get: function () { return fetch_with_auth_1.fetchWithAuth; } });
+// Authentication context and hooks
+var AuthContext_1 = require("./AuthContext");
+Object.defineProperty(exports, "AuthProvider", { enumerable: true, get: function () { return AuthContext_1.AuthProvider; } });
+Object.defineProperty(exports, "useAuthConfig", { enumerable: true, get: function () { return AuthContext_1.useAuthConfig; } });
+Object.defineProperty(exports, "useAuthMode", { enumerable: true, get: function () { return AuthContext_1.useAuthMode; } });
+Object.defineProperty(exports, "useFederatedProviders", { enumerable: true, get: function () { return AuthContext_1.useFederatedProviders; } });
+Object.defineProperty(exports, "useFederatedAuthEnabled", { enumerable: true, get: function () { return AuthContext_1.useFederatedAuthEnabled; } });
+Object.defineProperty(exports, "useTraditionalAuthEnabled", { enumerable: true, get: function () { return AuthContext_1.useTraditionalAuthEnabled; } });

package/dist/client/useAnonSession.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useAnonSession - React hook for anonymous session management
+ *
+ * Provides access to anonymous session preferences stored in Redis.
+ * Works before user logs in, preferences persist across visits.
+ */
+export interface AnonPreferences {
+    theme?: string;
+    locale?: string;
+    [key: string]: any;
+}
+export interface AnonMetrics {
+    resumeGenerationCount?: number;
+    firstVisit?: number;
+    lastVisit?: number;
+    visitCount?: number;
+    [key: string]: any;
+}
+export interface AnonSession {
+    id: string;
+    preferences: AnonPreferences;
+    metrics: AnonMetrics;
+}
+export interface UseAnonSessionReturn {
+    session: AnonSession | null;
+    isLoading: boolean;
+    error: string | null;
+    updatePreferences: (preferences: Partial<AnonPreferences>) => Promise<void>;
+    setTheme: (theme: string) => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook to manage anonymous session state
+ */
+export declare function useAnonSession(): UseAnonSessionReturn;
+export default useAnonSession;

package/dist/client/useAnonSession.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * useAnonSession - React hook for anonymous session management
+ *
+ * Provides access to anonymous session preferences stored in Redis.
+ * Works before user logs in, preferences persist across visits.
+ */
+'use client';
+/**
+ * useAnonSession - React hook for anonymous session management
+ *
+ * Provides access to anonymous session preferences stored in Redis.
+ * Works before user logs in, preferences persist across visits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAnonSession = useAnonSession;
+const react_1 = require("react");
+/**
+ * Hook to manage anonymous session state
+ */
+function useAnonSession() {
+    const [session, setSession] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    // Fetch session on mount
+    const fetchSession = (0, react_1.useCallback)(async () => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const response = await fetch('/api/anon/preferences', {
+                method: 'GET',
+                credentials: 'include', // Important for cookies
+            });
+            if (!response.ok) {
+                throw new Error('Failed to fetch preferences');
+            }
+            const data = await response.json();
+            if (data.success && data.data) {
+                setSession({
+                    id: data.data.id,
+                    preferences: data.data.preferences || {},
+                    metrics: data.data.metrics || {},
+                });
+            }
+        }
+        catch (err) {
+            console.error('[useAnonSession] Error fetching session:', err);
+            setError(err instanceof Error ? err.message : 'Unknown error');
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, []);
+    (0, react_1.useEffect)(() => {
+        fetchSession();
+    }, [fetchSession]);
+    // Update preferences
+    const updatePreferences = (0, react_1.useCallback)(async (preferences) => {
+        try {
+            setError(null);
+            const response = await fetch('/api/anon/preferences', {
+                method: 'POST',
+                credentials: 'include',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ preferences }),
+            });
+            if (!response.ok) {
+                throw new Error('Failed to update preferences');
+            }
+            const data = await response.json();
+            if (data.success && data.data) {
+                setSession(prev => prev ? {
+                    ...prev,
+                    preferences: data.data.preferences,
+                } : null);
+            }
+        }
+        catch (err) {
+            console.error('[useAnonSession] Error updating preferences:', err);
+            setError(err instanceof Error ? err.message : 'Unknown error');
+            throw err;
+        }
+    }, []);
+    // Convenience method to set theme
+    const setTheme = (0, react_1.useCallback)(async (theme) => {
+        await updatePreferences({ theme });
+    }, [updatePreferences]);
+    return {
+        session,
+        isLoading,
+        error,
+        updatePreferences,
+        setTheme,
+        refresh: fetchSession,
+    };
+}
+exports.default = useAnonSession;

package/dist/components/SessionSync.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SessionSync - Bridges NextAuth session with Zustand auth store
+ *
+ * CRITICAL: This component enforces strict session validation. If NextAuth
+ * reports an authenticated status but the session data is invalid (empty user ID,
+ * empty email, or missing access token), it forces a sign-out to prevent
+ * contradictory state like "hasSession: true, userId: ''"
+ *
+ * This ensures the app NEVER shows authenticated UI with empty/invalid session data.
+ */
+export declare function SessionSync({ children }: {
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;