Authentication Components

The shared authentication components at frontend/shared/src/components/Auth/ provide a complete authentication UI layer including session verification, route protection, login/registration forms, permission-based access control, and session management. All components use httpOnly cookie-based authentication.

AuthGuard

File: frontend/shared/src/components/Auth/AuthGuard.tsx

The primary authentication wrapper that verifies user sessions before rendering protected content.

Props Interface

interface AuthGuardProps {
  children: ReactNode;
  authCheckEndpoint?: string;    // Default: '/api/v1/auth/me'
  loginUrl?: string;             // Default: '/login'
  includeReturnUrl?: boolean;    // Default: true
  returnUrlParam?: string;       // Default: 'returnTo'
  loadingComponent?: ReactNode;
  onAuthError?: (error: Error) => void;
  onAuthenticated?: (user: AuthGuardUser) => void;
}

User Context

interface AuthGuardUser {
  id: string;
  email: string;
  firstName?: string;
  lastName?: string;
  avatar?: string;
  tenantId?: string;
  roles: string[];
  permissions: string[];
}
 
interface AuthGuardContextType {
  user: AuthGuardUser | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  error: string | null;
  logout: () => Promise<void>;
  refreshSession: () => Promise<void>;
}

Usage

<AuthGuard
  loginUrl="https://auth.matih.ai/login"
  onAuthenticated={(user) => initializeAnalytics(user)}
>
  <App />
</AuthGuard>

Hook

const { user, isAuthenticated, logout, refreshSession } = useAuthGuard();

HOC

const ProtectedPage = withAuthGuard(DashboardPage, {
  loginUrl: '/login',
  onAuthError: (err) => trackError(err),
});

Additional Auth Components

Component	File	Purpose
`LoginForm`	`Auth/LoginForm.tsx`	Email/password login with validation
`RegisterForm`	`Auth/RegisterForm.tsx`	New user registration
`ProtectedRoute`	`Auth/ProtectedRoute.tsx`	Route-level protection with React Router
`PermissionGuard`	`Auth/PermissionGuard.tsx`	Renders children only if user has required permissions
`RoleBasedAccess`	`Auth/RoleBasedAccess.tsx`	Role-based content rendering
`SessionManager`	`Auth/SessionManager.tsx`	Session timeout, refresh, and activity tracking
`SecuritySettings`	`Auth/SecuritySettings.tsx`	Password change, MFA setup
`ProfileManager`	`Auth/ProfileManager.tsx`	User profile editing
`APIKeyManager`	`Auth/APIKeyManager.tsx`	API key generation and management

Authentication Flow

1. User navigates to protected route
2. AuthGuard renders loading spinner
3. GET /api/v1/auth/me with credentials: 'include'
4a. 200 OK -> Parse user, provide context, render children
4b. 401/403 -> Redirect to loginUrl with returnTo parameter
4c. Error -> Call onAuthError, redirect to login

The loginUrl supports both relative paths (/login) and absolute URLs (https://auth.matih.ai/login), with return URL handling adapted for each case.

Zustand Stores Real-Time Infrastructure