# Authentication Feature Module

This module provides a consolidated authentication system with cohesive architecture following the feature-driven design principles.

## Structure

```
features/auth/
├── components/          # Reusable auth form components
│   ├── LoginForm/      # Login form with validation
│   ├── SignupForm/     # Multi-step signup form
│   ├── PasswordResetForm/ # Password reset functionality
│   └── SetPasswordForm/   # WHMCS password setup
├── hooks/              # Authentication hooks
│   └── use-auth.ts     # Main auth hook with specialized variants
├── services/           # Business logic and state management
│   ├── auth.service.ts # Authentication API service
│   └── auth.store.ts   # Zustand store with session management
├── types/              # Feature-specific types
├── utils/              # Authentication utilities
│   ├── auth-guard.tsx  # Route protection components
│   └── route-protection.ts # Redirect and route utilities
└── index.ts            # Public API exports
```

## Features

### ✅ Consolidated State Management

- Centralized Zustand store with persistence
- Automatic session timeout detection
- Token refresh logic
- Consistent error handling

### ✅ Reusable Form Components

- LoginForm with validation and error handling
- Multi-step SignupForm with progress indication
- PasswordResetForm for both request and reset modes
- SetPasswordForm for WHMCS account linking

### ✅ Authentication Hooks

- `useAuth()` - Main authentication hook
- `useLogin()` - Login-specific functionality
- `useSignup()` - Signup-specific functionality
- `usePasswordReset()` - Password reset functionality
- `useWhmcsLink()` - WHMCS linking functionality
- `useSession()` - Session management
- `useUser()` - User profile information
- `usePermissions()` - Role and permission checking

### ✅ Route Protection

- `AuthGuard` - General authentication guard
- `ProtectedRoute` - Wrapper for protected routes
- `PublicRoute` - Wrapper for public routes
- `RoleGuard` - Role-based access control
- `PermissionGuard` - Permission-based access control

### ✅ Session Management

- Automatic token validation
- Session timeout detection
- Periodic session refresh
- Secure token storage with persistence

## Usage

### Basic Authentication

```tsx
import { useAuth } from "@/features/auth";

function MyComponent() {
  const { isAuthenticated, user, login, logout } = useAuth();

  if (!isAuthenticated) {
    return <LoginForm onSuccess={() => console.log("Logged in!")} />;
  }

  return (
    <div>
      <p>Welcome, {user?.firstName}!</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}
```

### Route Protection

```tsx
import { ProtectedRoute, RoleGuard } from "@/features/auth";

function AdminPage() {
  return (
    <ProtectedRoute>
      <RoleGuard roles={["admin"]}>
        <AdminContent />
      </RoleGuard>
    </ProtectedRoute>
  );
}
```

### Form Components

```tsx
import { LoginForm, SignupForm } from "@/features/auth";

function AuthPage() {
  return (
    <div>
      <LoginForm
        onSuccess={() => router.push("/dashboard")}
        onError={error => toast.error(error)}
      />

      <SignupForm onSuccess={() => router.push("/dashboard")} showLoginLink={true} />
    </div>
  );
}
```

## Requirements Satisfied

This implementation satisfies the following requirements:

- **4.1**: Feature-based organization with self-contained modules
- **4.2**: Co-located components with related business logic
- **3.2**: Centralized state management with consistent patterns
- **1.4**: Reusable form components with shared validation
- **2.4**: Consistent page layouts and behavior patterns
- **5.3**: Proper TypeScript interfaces and validation

## Migration Notes

- All auth forms now use the new consolidated auth store
- Session management is automatic with timeout detection
- Route protection is handled by guard components
- Type safety is maintained with shared interfaces
- Error handling is consistent across all auth operations
