@payez/next-mvp 3.0.0

package/src/client/AuthContext.tsx

@@ -0,0 +1,140 @@
+'use client';
+
+import React, { createContext, useContext, ReactNode, useState, useEffect } from 'react';
+import { getProviders } from 'next-auth/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { AuthConfig, AuthMode, FederatedProvider } from '@/types/auth';
+
+const AuthContext = createContext<AuthConfig | null>(null);
+
+const defaultConfig: AuthConfig = {
+  mode: 'traditional',
+  providers: [],
+  enableRecovery: true,
+  enableEmailSignup: true,
+  allowPasswordReset: true,
+};
+
+// Map NextAuth provider IDs to our FederatedProvider type
+const PROVIDER_MAP: Record<string, FederatedProvider> = {
+  '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'];
+
+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 function AuthProvider({ children, config, useDynamicProviders = true }: AuthProviderProps) {
+  const [dynamicProviders, setDynamicProviders] = useState<FederatedProvider[]>([]);
+  const [providersLoaded, setProvidersLoaded] = useState(!useDynamicProviders);
+
+  // Create QueryClient instance for React Query - used internally by MVP hooks
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // 1 minute
+        retry: 1,
+        refetchOnWindowFocus: false,
+      },
+    },
+  }));
+
+  // Fetch dynamic providers from NextAuth on mount
+  useEffect(() => {
+    if (!useDynamicProviders) return;
+
+    let mounted = true;
+
+    async function fetchDynamicProviders() {
+      try {
+        const result = await 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 is FederatedProvider => 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: AuthConfig = {
+    ...defaultConfig,
+    ...config,
+    providers, // Override with dynamic providers if enabled
+  };
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <AuthContext.Provider value={authConfig}>
+        {children}
+      </AuthContext.Provider>
+    </QueryClientProvider>
+  );
+}
+
+export function useAuthConfig(): AuthConfig {
+  const context = useContext(AuthContext);
+  if (!context) {
+    return defaultConfig;
+  }
+  return context;
+}
+
+export function useAuthMode(): AuthMode {
+  const config = useAuthConfig();
+  return config.mode;
+}
+
+export function useFederatedProviders(): FederatedProvider[] {
+  const config = useAuthConfig();
+  return config.providers;
+}
+
+export function useFederatedAuthEnabled(): boolean {
+  const config = useAuthConfig();
+  return config.mode === 'federated' && config.providers.length > 0;
+}
+
+export function useTraditionalAuthEnabled(): boolean {
+  const config = useAuthConfig();
+  return config.mode === 'traditional';
+}

package/src/client/fetch-with-auth.ts

@@ -0,0 +1,48 @@
+// src/client/fetch-with-auth.ts
+import { getSession } from '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.
+ */
+export async function fetchWithAuth(url: string, options: RequestInit = {}): Promise<Response> {
+  // 1. Retrieve the client-side session to get the accessToken.
+  const session = await 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/src/client/fetchWithSession.ts

@@ -0,0 +1,21 @@
+import { useRef } from 'react';
+
+export async function fetchWithSession(input: RequestInfo | URL, init: RequestInit = {}, opts: { retry?: number } = {}): Promise<Response> {
+  const retry = opts.retry ?? 1;
+  const doFetch = async (): Promise<Response> => {
+    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/src/client/index.ts

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

package/src/client/useAnonSession.ts

@@ -0,0 +1,131 @@
+/**
+ * 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';
+
+import { useState, useEffect, useCallback } from 'react';
+
+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 function useAnonSession(): UseAnonSessionReturn {
+  const [session, setSession] = useState<AnonSession | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Fetch session on mount
+  const fetchSession = 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);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchSession();
+  }, [fetchSession]);
+
+  // Update preferences
+  const updatePreferences = useCallback(async (preferences: Partial<AnonPreferences>) => {
+    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 = useCallback(async (theme: string) => {
+    await updatePreferences({ theme });
+  }, [updatePreferences]);
+
+  return {
+    session,
+    isLoading,
+    error,
+    updatePreferences,
+    setTheme,
+    refresh: fetchSession,
+  };
+}
+
+export default useAnonSession;

package/src/components/SessionSync.tsx

@@ -0,0 +1,137 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { useSession, signOut } from 'next-auth/react';
+import type { Session } from 'next-auth';
+import { useAuthStore } from '../stores/authStore';
+import { isValidSession } from '../lib/session';
+import {
+  getSecureSessionCookieName,
+  getSecureCsrfCookieName,
+  getCallbackUrlCookieName
+} from '../lib/app-slug';
+
+/**
+ * Sanitize sensitive data for logging
+ * Never log full user IDs or emails in any environment
+ */
+function sanitizeForLog(value: string | undefined, type: 'email' | 'userId'): string {
+  if (!value) return '(empty)';
+  
+  if (type === 'email') {
+    return '***@***'; // Never log emails
+  }
+  
+  if (type === 'userId') {
+    // Only show first 8 chars in development
+    if (process.env.NODE_ENV === 'development') {
+      return value.substring(0, 8) + '...';
+    }
+    return '***'; // Fully redact in production
+  }
+  
+  return '***';
+}
+
+/**
+ * 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 function SessionSync({ children }: { children: React.ReactNode }) {
+  const { data: session, status } = useSession();
+  const { setSession, clearSession } = useAuthStore();
+  
+  // Guard against duplicate sign-out calls
+  const isSigningOutRef = useRef(false);
+
+  useEffect(() => {
+    let isMounted = true;
+    
+    // Only process when NextAuth has finished loading
+    if (status === 'loading') {
+      return;
+    }
+
+    // Strict validation: Check if session is actually valid
+    const isValid = isValidSession(session);
+
+    // CRITICAL FIX: If NextAuth says "authenticated" but session is invalid,
+    // this is a broken state that must be fixed immediately
+    if (status === 'authenticated' && !isValid) {
+      // GUARD: Prevent duplicate sign-out
+      if (isSigningOutRef.current) {
+        console.warn('[SessionSync] Sign-out already in progress, skipping');
+        return;
+      }
+      isSigningOutRef.current = true;
+      
+      console.error('[SessionSync] CRITICAL: Invalid session detected despite authenticated status!');
+      console.error('[SessionSync] This indicates a session with empty user data - forcing sign-out');
+      
+      // Log diagnostic info with PII redaction
+      // Note: session is typed as Session | null from NextAuth, but may have invalid/partial data
+      const sessionData = session as any; // Explicit cast needed for error logging
+      console.error('[SessionSync] Session data:', {
+        hasSessionObject: !!sessionData,
+        hasUser: !!sessionData?.user,
+        userId: sanitizeForLog(sessionData?.user?.id, 'userId'),
+        userEmail: sanitizeForLog(sessionData?.user?.email, 'email'),
+        hasAccessToken: !!sessionData?.accessToken,
+      });
+      
+      // Clear the auth store immediately
+      clearSession();
+
+      // FIX: Force clear all auth cookies including stale provisional tokens (app-slug prefixed)
+      // This prevents infinite loop when provisional token exists but session is invalid
+      // Root cause: OAuth creates provisional token before Redis session exists
+      try {
+        const secureSession = getSecureSessionCookieName();
+        const secureCsrf = getSecureCsrfCookieName();
+        const callbackUrl = getCallbackUrlCookieName();
+        document.cookie = `${secureSession}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 UTC; Secure; SameSite=Lax`;
+        document.cookie = `${secureCsrf}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 UTC; SameSite=Lax`;
+        document.cookie = `__Secure-${callbackUrl}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 UTC; Secure; SameSite=Lax`;
+      } catch (e) {
+        // Cookie clearing failed - non-critical, continue with signout
+      }
+
+      // Force NextAuth to sign out (this will clear cookies and trigger redirect)
+      signOut({ redirect: false })
+        .then(() => {
+          if (isMounted) {
+            // Use generic error code instead of implementation details
+            window.location.href = '/account-auth/login?error=SessionExpired&code=1001';
+          }
+        })
+        .catch((err) => {
+          console.error('[SessionSync] Error during forced signout:', err);
+          if (isMounted) {
+            window.location.href = '/account-auth/login?error=SessionExpired&code=1001';
+          }
+        });
+      
+      return;
+    }
+
+    // Normal flow: Update store based on valid session status
+    if (status === 'authenticated' && isValid) {
+      setSession(session);
+    } else if (status === 'unauthenticated') {
+      clearSession();
+    }
+    
+    // Cleanup function to prevent post-unmount updates
+    return () => {
+      isMounted = false;
+    };
+  }, [session, status, setSession, clearSession]);
+
+  return <>{children}</>;
+}

package/src/components/SignalRHealthCheck.tsx

@@ -0,0 +1,131 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { signalRActivityService, type HealthStatus } from '../services/signalrActivityService';
+
+interface SignalRHealthCheckProps {
+  className?: string;
+  idpBaseUrl: string;
+}
+
+/**
+ * Simple health check component using SignalR connection state
+ * Following Occam's Razor: Connection alive = Service healthy, Connection dead = Service unhealthy
+ */
+export default function SignalRHealthCheck({ className = '', idpBaseUrl }: SignalRHealthCheckProps) {
+  // Allow disabling via env for noisy environments (e.g., production demos)
+  if (process.env.NEXT_PUBLIC_DISABLE_HEALTH_MONITOR === 'true') {
+    return null;
+  }
+
+  const [healthStatus, setHealthStatus] = useState<HealthStatus>({
+    isHealthy: false,
+    message: 'Initializing...',
+    lastHeartbeat: null,
+    connectionId: null
+  });
+  const [isInitializing, setIsInitializing] = useState(true);
+
+  useEffect(() => {
+    let unsubscribe: (() => void) | null = null;
+
+    const initializeHealthService = async () => {
+      try {
+        // Subscribe to health status changes
+        unsubscribe = signalRActivityService.subscribe((status) => {
+          setHealthStatus(status);
+          setIsInitializing(false);
+        });
+
+        // Start the health monitoring
+        await signalRActivityService.start(idpBaseUrl);
+      } catch (error) {
+        // Handle service unavailable gracefully without console spam
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const isServiceDown = errorMessage.includes('ERR_CONNECTION_REFUSED') ||
+                             errorMessage.includes('Failed to fetch');
+
+        if (isServiceDown) {
+          console.info('Health monitoring: Backend service unavailable');
+          setHealthStatus({
+            isHealthy: false,
+            message: 'Backend service offline',
+            lastHeartbeat: null,
+            connectionId: null
+          });
+        } else {
+          console.error('Failed to initialize SignalR health service:', error);
+          setHealthStatus({
+            isHealthy: false,
+            message: 'Failed to initialize health monitoring',
+            lastHeartbeat: null,
+            connectionId: null
+          });
+        }
+        setIsInitializing(false);
+      }
+    };
+
+    initializeHealthService();
+
+    // Cleanup on unmount
+    return () => {
+      if (unsubscribe) {
+        unsubscribe();
+      }
+    };
+  }, [idpBaseUrl]);
+
+  const getStatusColor = () => {
+    if (isInitializing) return 'text-yellow-600';
+    return healthStatus.isHealthy ? 'text-green-600' : 'text-orange-600'; // Orange instead of alarming red
+  };
+
+  const getStatusIcon = () => {
+    if (isInitializing) return '🔄';
+    return healthStatus.isHealthy ? '✅' : '🔶'; // Orange diamond instead of scary red X
+  };
+
+  const getStatusMessage = () => {
+    if (isInitializing) return 'Connecting to service...';
+    return healthStatus.message;
+  };
+
+  const formatLastHeartbeat = () => {
+    if (!healthStatus.lastHeartbeat) return null;
+    const now = new Date();
+    const diff = Math.floor((now.getTime() - healthStatus.lastHeartbeat.getTime()) / 1000);
+
+    if (diff < 60) return `${diff}s ago`;
+    if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+    return `${Math.floor(diff / 3600)}h ago`;
+  };
+
+  return (
+    <div className={`flex items-center space-x-2 ${className}`}>
+      <span className="text-lg" role="img" aria-label="status">
+        {getStatusIcon()}
+      </span>
+
+      <div className="flex flex-col">
+        <span className={`text-sm font-medium ${getStatusColor()}`}>
+          {getStatusMessage()}
+        </span>
+
+        {healthStatus.lastHeartbeat && (
+          <span className="text-xs text-gray-500">
+            Last heartbeat: {formatLastHeartbeat()}
+          </span>
+        )}
+
+        {/* Uncomment for SignalR debugging:
+        {process.env.NODE_ENV === 'development' && healthStatus.connectionId && (
+          <span className="text-xs text-gray-400 font-mono">
+            Connection: {healthStatus.connectionId.substring(0, 8)}...
+          </span>
+        )}
+        */}
+      </div>
+    </div>
+  );
+}