@payez/next-mvp 3.0.0

package/src/hooks/usePublicAuthSettings.ts

@@ -0,0 +1,149 @@
+/**
+ * usePublicAuthSettings Hook
+ *
+ * Fetches public auth settings for pre-login pages (signup, login).
+ * Does NOT require authentication - settings are fetched via API.
+ */
+
+'use client';
+
+import { useState, useEffect } from 'react';
+import type { FederatedProvider } from '../types/auth';
+
+export interface PublicAuthSettings {
+    enabledProviders: FederatedProvider[];
+    allowPublicRegistration: boolean;
+    allowSocialLogin: boolean;
+    enablePasswordReset: boolean;
+    require2FA: boolean;
+    allowed2FAMethods: string[];
+}
+
+export interface UsePublicAuthSettingsResult {
+    settings: PublicAuthSettings | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+
+// Map provider strings to FederatedProvider type
+const PROVIDER_MAP: Record<string, FederatedProvider> = {
+    'google': 'google',
+    'apple': 'apple',
+    'facebook': 'facebook',
+    'github': 'github',
+    'microsoft': 'microsoft',
+    'azure-ad': 'microsoft',
+};
+
+const DEFAULT_SETTINGS: PublicAuthSettings = {
+    enabledProviders: [],
+    allowPublicRegistration: true,
+    allowSocialLogin: false,
+    enablePasswordReset: true,
+    require2FA: true,
+    allowed2FAMethods: ['email', 'sms'],
+};
+
+/**
+ * Hook to fetch public auth settings for login/signup pages.
+ *
+ * @example
+ * ```tsx
+ * function SignupPage() {
+ *   const { settings, isLoading } = usePublicAuthSettings();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <>
+ *       {settings?.allowSocialLogin && (
+ *         <FederatedAuthSection providers={settings.enabledProviders} />
+ *       )}
+ *       {settings?.allowPublicRegistration && (
+ *         <EmailSignupForm />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function usePublicAuthSettings(): UsePublicAuthSettingsResult {
+    const [settings, setSettings] = useState<PublicAuthSettings | null>(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState<Error | null>(null);
+
+    useEffect(() => {
+        let mounted = true;
+
+        async function fetchSettings() {
+            try {
+                const response = await fetch('/api/auth/settings');
+
+                if (!mounted) return;
+
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch auth settings: ${response.status}`);
+                }
+
+                const data = await response.json();
+
+                if (data.success && data.data) {
+                    // Map provider strings to FederatedProvider type
+                    const providers = (data.data.enabledProviders || [])
+                        .map((p: string) => PROVIDER_MAP[p.toLowerCase()])
+                        .filter((p: FederatedProvider | undefined): p is FederatedProvider => p !== undefined);
+
+                    setSettings({
+                        ...data.data,
+                        enabledProviders: providers,
+                    });
+                } else {
+                    setSettings(DEFAULT_SETTINGS);
+                }
+
+                setError(null);
+            } catch (err) {
+                if (!mounted) return;
+                console.warn('[usePublicAuthSettings] Failed to fetch settings:', err);
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setSettings(DEFAULT_SETTINGS);
+            } finally {
+                if (mounted) {
+                    setIsLoading(false);
+                }
+            }
+        }
+
+        fetchSettings();
+
+        return () => {
+            mounted = false;
+        };
+    }, []);
+
+    return { settings, isLoading, error };
+}
+
+/**
+ * Hook to check if social login is enabled.
+ */
+export function useSocialLoginEnabled(): boolean {
+    const { settings } = usePublicAuthSettings();
+    return settings?.allowSocialLogin ?? false;
+}
+
+/**
+ * Hook to check if public registration is enabled.
+ */
+export function usePublicRegistrationEnabled(): boolean {
+    const { settings } = usePublicAuthSettings();
+    return settings?.allowPublicRegistration ?? true;
+}
+
+/**
+ * Hook to check if password reset is enabled.
+ */
+export function usePasswordResetEnabled(): boolean {
+    const { settings } = usePublicAuthSettings();
+    return settings?.enablePasswordReset ?? true;
+}

package/src/hooks/useSessionExpiration.ts

@@ -0,0 +1,102 @@
+/**
+ * Hook to detect and handle stale/expired sessions during 2FA flow
+ *
+ * Use this in verify-code pages to automatically redirect to login
+ * when the provisional bearer token has expired.
+ *
+ * @example
+ * ```tsx
+ * import { useSessionExpiration } from '@payez/next-mvp/hooks/useSessionExpiration';
+ *
+ * function VerifyCodePage() {
+ *   const { data: session } = useSession();
+ *   const router = useRouter();
+ *   const searchParams = useSearchParams();
+ *   const [error, setError] = useState<string | null>(null);
+ *
+ *   const callbackUrl = searchParams?.get('callbackUrl') || '/dashboard';
+ *
+ *   // Automatically handles session expiration
+ *   const sessionValid = useSessionExpiration({
+ *     session,
+ *     router,
+ *     callbackUrl,
+ *     onExpired: (message) => setError(message)
+ *   });
+ *
+ *   if (!sessionValid) return null; // Will redirect
+ *   // ... rest of component
+ * }
+ * ```
+ */
+
+import { useEffect } from 'react';
+import { signOut } from 'next-auth/react';
+import type { Session } from 'next-auth';
+
+export interface UseSessionExpirationOptions {
+  /** NextAuth session object */
+  session: Session | null | undefined;
+  /** Next.js router for navigation */
+  router: {
+    push: (url: string) => void;
+  };
+  /** URL to redirect to after login */
+  callbackUrl?: string;
+  /** Callback when session expires - use to set error state */
+  onExpired?: (message: string) => void;
+  /** Delay before redirect in milliseconds (default: 1500) */
+  redirectDelay?: number;
+  /** Custom redirect URL (default: /account-auth/login) */
+  loginUrl?: string;
+}
+
+/**
+ * Detects stale sessions and redirects to login
+ *
+ * Returns:
+ * - `true` if session is valid (has accessToken)
+ * - `false` if session is loading (no session yet)
+ * - `null` if session is stale (will trigger redirect)
+ */
+export function useSessionExpiration({
+  session,
+  router,
+  callbackUrl = '/dashboard',
+  onExpired,
+  redirectDelay = 1500,
+  loginUrl = '/account-auth/login'
+}: UseSessionExpirationOptions): boolean | null {
+  useEffect(() => {
+    // If session exists but no accessToken, the token is stale/expired
+    if (session && !(session as any).accessToken) {
+      const message = 'Your session has expired. Redirecting to login...';
+      if (onExpired) {
+        onExpired(message);
+      }
+
+      setTimeout(async () => {
+        // Clear the session before redirecting
+        await signOut({ redirect: false });
+
+        const params = new URLSearchParams({
+          callbackUrl,
+          error: 'SessionExpired'
+        });
+
+        router.push(`${loginUrl}?${params.toString()}`);
+      }, redirectDelay);
+    }
+  }, [session, router, callbackUrl, onExpired, redirectDelay, loginUrl]);
+
+  // Return session validity state
+  if (session && !(session as any).accessToken) {
+    return null; // Stale session - will redirect
+  }
+
+  if ((session as any)?.accessToken) {
+    return true; // Valid session
+  }
+
+  return false; // No session yet - loading
+}

package/src/hooks/useViabilitySession.ts

@@ -0,0 +1,335 @@
+/**
+ * useViabilitySession - Redis-backed session state hook
+ *
+ * This hook provides the REAL session state by consulting Redis via /api/session/viability
+ * instead of relying on the potentially stale NextAuth JWT cookie.
+ *
+ * Redis is the single source of truth. This hook:
+ * 1. Polls /api/session/viability to get actual session state from Redis
+ * 2. Returns consistent auth state across all components
+ * 3. Triggers callback when session state changes unexpectedly
+ *
+ * Usage:
+ * ```tsx
+ * const { isAuthenticated, isLoading } = useViabilitySession();
+ * ```
+ */
+
+'use client';
+
+import { useState, useEffect, useRef } from 'react';
+import { useSession } from 'next-auth/react';
+
+export interface ViabilityState {
+  /** Whether the user is authenticated according to Redis */
+  isAuthenticated: boolean;
+  /** Whether the viability check is in progress */
+  isLoading: boolean;
+  /** Whether 2FA is required for this client */
+  requires2FA: boolean;
+  /** Whether 2FA has been completed for this session */
+  twoFactorComplete: boolean;
+  /** Whether the access token has expired (refresh may be needed) */
+  accessTokenExpired: boolean;
+  /** Whether a refresh token is available */
+  hasRefreshToken: boolean;
+  /** Error message if viability check failed */
+  error: string | null;
+  /** Timestamp of last successful viability check */
+  lastChecked: number | null;
+  /** Force a viability check now */
+  refresh: () => void;
+}
+
+interface ViabilityResponse {
+  authenticated: boolean;
+  sessionToken?: string;
+  requires2FA?: boolean;
+  twoFactorComplete?: boolean;
+  accessTokenExpired?: boolean;
+  hasRefreshToken?: boolean;
+}
+
+export interface UseViabilitySessionOptions {
+  /** Polling interval in milliseconds (default: 30000 = 30 seconds) */
+  pollInterval?: number;
+  /** Whether to poll automatically (default: true) */
+  enablePolling?: boolean;
+  /** Callback when session becomes invalid */
+  onSessionInvalid?: () => void;
+}
+
+// Use window to persist state across HMR in development
+declare global {
+  interface Window {
+    __viabilitySessionState?: {
+      isAuthenticated: boolean;
+      isLoading: boolean;
+      requires2FA: boolean;
+      twoFactorComplete: boolean;
+      accessTokenExpired: boolean;
+      hasRefreshToken: boolean;
+      error: string | null;
+      lastChecked: number | null;
+      checkInProgress: boolean;
+      prevAuth: boolean | null;
+      intervalId: ReturnType<typeof setInterval> | null;
+      listeners: Set<() => void>;
+      onSessionInvalidCallbacks: Set<() => void>;
+    };
+  }
+}
+
+function getGlobalState() {
+  if (typeof window === 'undefined') {
+    // SSR - return default state
+    return {
+      isAuthenticated: false,
+      isLoading: true,
+      requires2FA: false,
+      twoFactorComplete: false,
+      accessTokenExpired: false,
+      hasRefreshToken: false,
+      error: null,
+      lastChecked: null,
+      checkInProgress: false,
+      prevAuth: null,
+      intervalId: null,
+      listeners: new Set<() => void>(),
+      onSessionInvalidCallbacks: new Set<() => void>()
+    };
+  }
+
+  // Initialize global state on window if not present
+  if (!window.__viabilitySessionState) {
+    window.__viabilitySessionState = {
+      isAuthenticated: false,
+      isLoading: true,
+      requires2FA: false,
+      twoFactorComplete: false,
+      accessTokenExpired: false,
+      hasRefreshToken: false,
+      error: null,
+      lastChecked: null,
+      checkInProgress: false,
+      prevAuth: null,
+      intervalId: null,
+      listeners: new Set<() => void>(),
+      onSessionInvalidCallbacks: new Set<() => void>()
+    };
+  }
+
+  return window.__viabilitySessionState;
+}
+
+async function doViabilityCheck(): Promise<void> {
+  const state = getGlobalState();
+
+  // Prevent concurrent checks
+  if (state.checkInProgress) return;
+  state.checkInProgress = true;
+
+  try {
+    const response = await fetch('/api/session/viability', {
+      method: 'GET',
+      headers: {
+        'Accept': 'application/json',
+        'Cache-Control': 'no-store'
+      },
+      credentials: 'include'
+    });
+
+    if (!response.ok) {
+      state.isLoading = false;
+      state.error = `Viability check failed: ${response.status}`;
+      state.lastChecked = Date.now();
+      notifyListeners();
+      return;
+    }
+
+    const data: ViabilityResponse = await response.json();
+
+    // Detect auth state change
+    if (state.prevAuth !== null && state.prevAuth !== data.authenticated) {
+      console.log('[useViabilitySession] Auth state changed:', {
+        was: state.prevAuth,
+        now: data.authenticated
+      });
+
+      if (!data.authenticated) {
+        // Notify all callbacks
+        state.onSessionInvalidCallbacks.forEach(cb => {
+          try { cb(); } catch (e) { console.error('[useViabilitySession] onSessionInvalid error:', e); }
+        });
+      }
+    }
+
+    state.prevAuth = data.authenticated;
+    state.isAuthenticated = data.authenticated;
+    state.isLoading = false;
+    state.requires2FA = data.requires2FA ?? false;
+    state.twoFactorComplete = data.twoFactorComplete ?? false;
+    state.accessTokenExpired = data.accessTokenExpired ?? false;
+    state.hasRefreshToken = data.hasRefreshToken ?? false;
+    state.error = null;
+    state.lastChecked = Date.now();
+
+    notifyListeners();
+
+  } catch (error) {
+    console.error('[useViabilitySession] Error checking viability:', error);
+    const state = getGlobalState();
+    state.isLoading = false;
+    state.error = error instanceof Error ? error.message : 'Unknown error';
+    state.lastChecked = Date.now();
+    notifyListeners();
+  } finally {
+    getGlobalState().checkInProgress = false;
+  }
+}
+
+function notifyListeners() {
+  const state = getGlobalState();
+  state.listeners.forEach(listener => {
+    try { listener(); } catch (e) { /* ignore */ }
+  });
+}
+
+function startPolling(interval: number) {
+  const state = getGlobalState();
+  if (state.intervalId !== null) return; // Already polling
+
+  state.intervalId = setInterval(() => {
+    doViabilityCheck();
+  }, interval);
+}
+
+function stopPolling() {
+  const state = getGlobalState();
+  if (state.intervalId !== null) {
+    clearInterval(state.intervalId);
+    state.intervalId = null;
+  }
+}
+
+/**
+ * Hook that provides Redis-backed session state
+ */
+export function useViabilitySession(options: UseViabilitySessionOptions = {}): ViabilityState {
+  const {
+    pollInterval = 30000,
+    enablePolling = true,
+    onSessionInvalid
+  } = options;
+
+  const { status: nextAuthStatus } = useSession();
+  const [, forceUpdate] = useState(0);
+  const mountedRef = useRef(true);
+  const initializedRef = useRef(false);
+
+  // Register this component's onSessionInvalid callback
+  useEffect(() => {
+    if (onSessionInvalid) {
+      const state = getGlobalState();
+      state.onSessionInvalidCallbacks.add(onSessionInvalid);
+      return () => {
+        state.onSessionInvalidCallbacks.delete(onSessionInvalid);
+      };
+    }
+  }, [onSessionInvalid]);
+
+  // Subscribe to global state changes
+  useEffect(() => {
+    mountedRef.current = true;
+    const listener = () => {
+      if (mountedRef.current) {
+        forceUpdate(n => n + 1);
+      }
+    };
+    const state = getGlobalState();
+    state.listeners.add(listener);
+
+    return () => {
+      mountedRef.current = false;
+      state.listeners.delete(listener);
+    };
+  }, []);
+
+  // Initial check when NextAuth status is determined - only once!
+  useEffect(() => {
+    if (nextAuthStatus === 'loading') {
+      return;
+    }
+
+    const state = getGlobalState();
+
+    // Only do initial check once globally
+    if (!initializedRef.current && state.lastChecked === null) {
+      initializedRef.current = true;
+      doViabilityCheck();
+    }
+  }, [nextAuthStatus]);
+
+  // Manage polling - only one interval for all hook instances
+  useEffect(() => {
+    if (!enablePolling || nextAuthStatus === 'loading') {
+      return;
+    }
+
+    // Start polling if not already started
+    startPolling(pollInterval);
+
+    // Cleanup: only stop if this is the last listener
+    return () => {
+      const state = getGlobalState();
+      // Small delay to allow other components to register
+      setTimeout(() => {
+        if (state.listeners.size === 0) {
+          stopPolling();
+        }
+      }, 100);
+    };
+  }, [enablePolling, pollInterval, nextAuthStatus]);
+
+  // Check viability on focus (user returns to tab) - with debounce
+  useEffect(() => {
+    const handleFocus = () => {
+      const state = getGlobalState();
+      // Debounce: only check if last check was > 10 seconds ago
+      if (state.lastChecked !== null &&
+          Date.now() - state.lastChecked > 10000) {
+        doViabilityCheck();
+      }
+    };
+
+    window.addEventListener('focus', handleFocus);
+    return () => window.removeEventListener('focus', handleFocus);
+  }, []);
+
+  // Return current state
+  const state = getGlobalState();
+  return {
+    isAuthenticated: state.isAuthenticated,
+    isLoading: state.isLoading,
+    requires2FA: state.requires2FA,
+    twoFactorComplete: state.twoFactorComplete,
+    accessTokenExpired: state.accessTokenExpired,
+    hasRefreshToken: state.hasRefreshToken,
+    error: state.error,
+    lastChecked: state.lastChecked,
+    refresh: doViabilityCheck
+  };
+}
+
+/**
+ * Simplified hook that just returns authentication status
+ * Use this in components that only need to know if user is logged in
+ */
+export function useIsAuthenticated(): { isAuthenticated: boolean; isLoading: boolean } {
+  const { isAuthenticated, isLoading } = useViabilitySession({
+    pollInterval: 60000, // Less frequent polling for simple status
+    enablePolling: true
+  });
+
+  return { isAuthenticated, isLoading };
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+// Type augmentation for NextAuth - included via ambient module declaration
+// Note: Type declarations are picked up automatically via tsconfig.json, no explicit import needed
+
+// NOTE: Server-only exports are NOT exported from the root to prevent bundling Node.js modules in client code.
+// Server-side code should import from subpath exports:
+// - Session management: import { sessionStore } from '@payez/next-mvp/lib/session-store'
+// - Redis client: import { redis } from '@payez/next-mvp/lib/redis'
+// - Token expiry: import { computeTokenExpiries } from '@payez/next-mvp/lib/token-expiry'
+// - Refresh validation: import { validateRefreshToken } from '@payez/next-mvp/lib/refresh-token-validator'
+// - Auth options: import { authOptions } from '@payez/next-mvp/auth/auth-options'
+// - Auth handler: import { createAuthHandler } from '@payez/next-mvp/api/auth-handler'
+
+// Client-safe exports only
+
+// Client-side utilities
+export { fetchWithAuth } from './client/fetch-with-auth';
+
+// Anonymous session hook (for pre-login preferences like theme)
+export { useAnonSession } from './client/useAnonSession';
+export type { AnonPreferences, AnonMetrics, AnonSession, UseAnonSessionReturn } from './client/useAnonSession';
+
+// Authentication Context and Hooks
+export { AuthProvider, useAuthConfig, useAuthMode, useFederatedProviders, useFederatedAuthEnabled, useTraditionalAuthEnabled } from './client/AuthContext';
+export type { AuthConfig } from './types/auth';
+
+// Route configuration (client-safe)
+export { makeAuthDecision } from './auth/auth-decision';
+export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from './auth/route-config';
+export { createMvpMiddleware } from './middleware/create-middleware';
+
+// Account Components
+export { UserAvatarMenu } from './components/account';
+export type { UserAvatarMenuProps } from './components/account';
+
+// Admin Logging & Analytics (client-side components and hooks)
+export {
+  ErrorMetricsCard,
+  HealthMetricsCard,
+  AuditLogViewer,
+  AdminAnalyticsLayout,
+  useErrorMetrics,
+  useHealthMetrics,
+  useAuditLog,
+  useAdminAnalytics,
+  getErrorMetrics,
+  getHealthMetrics,
+  writeAuditLog,
+  queryAuditLog,
+} from './logging';
+export type {
+  ErrorMetrics,
+  HealthMetrics,
+  AuditLogEntry,
+  AuditLogQuery,
+  AuditLogResponse,
+  TimeRange,
+  RouteError,
+  LevelCount,
+  CategoryCount,
+  ErrorDetail,
+  EndpointHealth,
+  SlowRequest,
+} from './logging';