@flusys/ng-auth 4.0.1 → 4.1.0

package/README.md

@@ -1,1622 +1,476 @@
-# @flusys/ng-auth Package Guide
+# @flusys/ng-auth
 
-## Overview
-
-`@flusys/ng-auth` provides complete authentication functionality including login, registration, token management, company/branch selection, user administration, and permission handling.
+> Complete authentication library for the FLUSYS Angular platform — JWT session management, HTTP-only cookie tokens, multi-company selection, and provider adapter registration.
 
-**Package:** `@flusys/ng-auth`
-**Version:** 4.0.1
-**Dependencies:** ng-core, ng-shared, ng-layout
-**Build:** `npm run build:ng-auth`
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        ng-auth                               │
-├─────────────────────────────────────────────────────────────┤
-│  Services                                                    │
-│  ├── AuthApiService      (login, register, refresh, logout) │
-│  ├── AuthStateService    (signal-based state management)    │
-│  ├── AuthInitService     (session restoration on refresh)   │
-│  ├── TokenRefreshStateService (concurrent refresh handling) │
-│  ├── UserApiService      (user CRUD)                        │
-│  ├── CompanyApiService   (company CRUD)                     │
-│  ├── BranchApiService    (branch CRUD)                      │
-│  └── UserPermissionApiService (permission assignments)      │
-├─────────────────────────────────────────────────────────────┤
-│  Guards                                                      │
-│  ├── authGuard           (requires authentication)          │
-│  ├── guestGuard          (allows only unauthenticated)      │
-│  ├── companyFeatureGuard (requires company feature enabled) │
-│  ├── emailFeatureGuard   (requires email service enabled)   │
-│  └── signUpFeatureGuard  (requires sign-up enabled)         │
-├─────────────────────────────────────────────────────────────┤
-│  Interceptors                                                │
-│  ├── authInterceptor     (adds JWT + tenant headers)        │
-│  └── tokenRefreshInterceptor (proactive + reactive refresh) │
-├─────────────────────────────────────────────────────────────┤
-│  Adapters (Provider Interface Pattern)                       │
-│  ├── AuthLayoutStateAdapter  → LAYOUT_AUTH_STATE            │
-│  ├── AuthLayoutApiAdapter    → LAYOUT_AUTH_API              │
-│  ├── AuthUserProviderAdapter → USER_PROVIDER                │
-│  ├── AuthCompanyApiProviderAdapter → COMPANY_API_PROVIDER   │
-│  ├── AuthUserPermissionProviderAdapter → USER_PERMISSION_PROVIDER │
-│  └── AuthStateProviderAdapter → AUTH_STATE_PROVIDER         │
-├─────────────────────────────────────────────────────────────┤
-│  Constants                                                   │
-│  └── AUTH_ENDPOINTS          (endpoint path definitions)    │
-└─────────────────────────────────────────────────────────────┘
-```
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-auth.svg)](https://www.npmjs.com/package/@flusys/ng-auth)
+[![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 ---
 
-## Services
-
-### AuthApiService
-
-HTTP client for authentication endpoints. Uses `getServiceUrl(appConfig, 'auth')` for base URL.
-
-```typescript
-import { AuthApiService } from '@flusys/ng-auth';
-
-const authApi = inject(AuthApiService);
-
-// Authentication
-authApi.login({ email, password });              // POST /auth/login → AuthResponse
-authApi.register({ name, email, password, ... }); // POST /auth/register → IRegistrationResponse
-authApi.refresh();                               // POST /auth/refresh → IRefreshTokenResponse
-authApi.logout();                                // POST /auth/logout → IMessageResponse
-authApi.me();                                    // POST /auth/me → IMeResponse
-
-// Company/Branch selection
-authApi.select({ companyId, branchId, sessionId });  // POST /auth/select → ILoginResponse
-authApi.switchCompany({ companyId, branchId });      // POST /auth/switch-company → ILoginResponse
-
-// Password management
-authApi.changePassword({ currentPassword, newPassword }); // POST /auth/change-password
-authApi.forgotPassword(email);                       // POST /auth/forgot-password
-authApi.resetPassword(token, newPassword);           // POST /auth/reset-password
-
-// Email verification
-authApi.verifyEmail(token);                          // POST /auth/verify-email
-authApi.resendVerification(email);                   // POST /auth/resend-verification
-```
-
-**Response Type Guards:**
-```typescript
-import {
-  isEmailVerificationRequired,
-  isCompanySelectionResponse,
-  isLoginResponse,
-  AuthResponse
-} from '@flusys/ng-auth';
-
-// AuthResponse can be ILoginResponse | ICompanySelectionResponse | ILoginRequiresEmailVerification
-const response = await firstValueFrom(authApi.login(credentials));
-
-if (isEmailVerificationRequired(response)) {
-  // Handle email not verified
-}
-if (isCompanySelectionResponse(response)) {
-  // Handle company selection step
-}
-if (isLoginResponse(response)) {
-  // Direct login success
-}
-```
-
-### AuthStateService
-
-Signal-based centralized auth state management with auto-persistence.
-
-**Security Note:** Access tokens are stored in memory only (not localStorage) to prevent XSS attacks. Only token expiry time is persisted.
-
-```typescript
-import { AuthStateService } from '@flusys/ng-auth';
-
-const authState = inject(AuthStateService);
-
-// Read-only signals
-authState.user();                    // Signal<IUserInfo | null>
-authState.accessToken();             // Signal<string> (memory-only)
-authState.tokenExpiresAt();          // Signal<number | null> (milliseconds timestamp)
-authState.company();                 // Signal<ICompanyInfo | null>
-authState.branch();                  // Signal<IBranchInfo | null>
-authState.selectionSessionId();      // Signal<string | null>
-authState.availableCompanies();      // Signal<ICompanyWithBranches[]>
-
-// Computed signals
-authState.isAuthenticated();         // Signal<boolean> - has token AND user
-authState.requiresCompanySelection(); // Signal<boolean>
-authState.userName();                // Signal<string>
-authState.companyName();             // Signal<string>
-authState.branchName();              // Signal<string>
-authState.tenantId();                // Signal<string | null>
-authState.isTokenExpired();          // Signal<boolean> - true if expired or expiring within 30s
-
-// State mutations
-authState.setLoginState(response);   // After successful login
-authState.setSelectionState(response); // After login requires selection
-authState.clearSelectionState();     // Clear pending selection
-authState.resetState();              // Full logout - clears all state + localStorage
-
-// Individual setters
-authState.setUser(user);
-authState.setAccessToken(token);     // Auto-decodes JWT to extract expiry
-authState.setCompany(company);
-authState.setBranch(branch);
-
-// Navigation helpers
-authState.navigateToLogin(returnUrl?);
-authState.navigateAfterLogin(returnUrl?); // Validates URL to prevent open redirect
-
-// Storage accessors
-authState.getStoredCompanyId();      // Get persisted company ID
-authState.getStoredBranchId();       // Get persisted branch ID
-```
-
-**Auto-persistence via effects:**
-- `tokenExpiresAt` → localStorage `tokenExpiresAt`
-- `company.id` → localStorage `selectedCompanyId`
-- `branch.id` → localStorage `selectedBranchId`
-
-### AuthInitService
-
-Handles session restoration on page refresh.
-
-```typescript
-import { AuthInitService } from '@flusys/ng-auth';
-
-const authInit = inject(AuthInitService);
-
-// Signals
-authInit.initialized();  // Signal<boolean> - true after init attempt
-authInit.loading();      // Signal<boolean>
-authInit.error();        // Signal<string | null>
-
-// Restore session (called by guards)
-authInit.initialize().subscribe({
-  next: (success) => console.log('Session restored:', success),
-  error: (err) => console.log('No session or expired')
-});
-```
-
-**Initialization Flow:**
-1. Returns immediately if already authenticated with user data
-2. Returns cached result if already initialized (prevents retry loops)
-3. Reuses in-flight initialization (shareReplay)
-4. Attempts `POST /auth/refresh` with httpOnly cookie (5s timeout)
-5. On success, calls `POST /auth/me` to get user info
-6. Updates AuthStateService with restored session
-7. Handles company assignment errors gracefully
-8. Clears cache on finalize to allow re-initialization later
-
-### TokenRefreshStateService
-
-Manages concurrent token refresh with request queuing.
-
-```typescript
-import { TokenRefreshStateService } from '@flusys/ng-auth';
-
-const refreshState = inject(TokenRefreshStateService);
-
-// Signals
-refreshState.isRefreshing();         // Signal<boolean>
-refreshState.refreshTokenSubject$;   // Observable<string | null> - for queuing
-
-// State management
-refreshState.startRefresh();         // Begin refresh, set subject to null
-refreshState.completeRefresh(token); // Complete with new token
-refreshState.failRefresh();          // Mark failed
-```
-
-### Resource API Services
-
-All extend `ApiResourceService` from ng-shared with signal-based state.
-
-```typescript
-import { UserApiService, CompanyApiService, BranchApiService } from '@flusys/ng-auth';
-
-// Common signals (from ApiResourceService)
-service.data();      // Signal<T[]>
-service.isLoading(); // Signal<boolean>
-service.error();     // Signal<string | null>
-service.total();     // Signal<number>
-
-// Common methods
-await service.insertAsync(data);
-await service.updateAsync(data);
-await service.deleteAsync({ id, type: 'delete' });
-await service.findByIdAsync(id);
-service.fetchList(search, options);
-service.reload();
-```
-
-**UserApiService** - Endpoint: `administration/users`
-```typescript
-const userApi = inject(UserApiService);
-userApi.updateProfile(data);  // POST /administration/users/profile
-```
-
-**CompanyApiService** - Endpoint: `administration/company`
-```typescript
-const companyApi = inject(CompanyApiService);
-// Standard CRUD via ApiResourceService
-```
-
-**BranchApiService** - Endpoint: `administration/branch`
-```typescript
-const branchApi = inject(BranchApiService);
-branchApi.setCurrentCompanyId(companyId);        // Set company context
-branchApi.fetchByCompany(companyId, search);     // Fetch with company filter
-```
-
-### UserPermissionApiService
-
-Manages user-to-company and user-to-branch permission assignments.
-
-```typescript
-import { UserPermissionApiService } from '@flusys/ng-auth';
-
-const permApi = inject(UserPermissionApiService);
-
-// Company Permissions
-permApi.assignUserCompanies({
-  userId: 'user-1',
-  items: [
-    { targetId: 'company-1', isAdd: true },   // Assign
-    { targetId: 'company-2', isAdd: false }   // Revoke
-  ]
-});
-permApi.getUserCompanies(userId);             // POST /administration/permissions/get-user-company
-permApi.assignUserToCompany(userId, companyId);   // Single assign
-permApi.revokeUserFromCompany(userId, companyId); // Single revoke
-
-// Branch Permissions
-permApi.assignUserBranches({
-  userId: 'user-1',
-  items: [{ targetId: 'branch-1', isAdd: true }]
-});
-permApi.getUserBranches(userId, companyId?);  // POST /administration/permissions/get-user-branch
-permApi.assignUserToBranch(userId, branchId);
-permApi.revokeUserFromBranch(userId, branchId);
-```
-
-**Backend Endpoints:**
-- `POST /administration/permissions/user-company/assign`
-- `POST /administration/permissions/get-user-company`
-- `POST /administration/permissions/user-branch/assign`
-- `POST /administration/permissions/get-user-branch`
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Module Registration](#module-registration)
+- [Session Restoration Flow](#session-restoration-flow)
+- [Auth State Service](#auth-state-service)
+- [Auth API Service](#auth-api-service)
+- [HTTP Interceptors](#http-interceptors)
+- [Guards](#guards)
+- [Pages](#pages)
+- [Provider Adapters](#provider-adapters)
+- [API Endpoints](#api-endpoints)
+- [Configuration Reference](#configuration-reference)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
-## Guards
-
-### authGuard
-
-Protects routes requiring authentication.
-
-```typescript
-import { authGuard } from '@flusys/ng-auth';
-
-{
-  path: 'dashboard',
-  canActivate: [authGuard],
-  loadComponent: () => import('./dashboard.component')
-}
-```
-
-**Checks:**
-1. User is authenticated (`isAuthenticated()`)
-2. If company feature enabled: company AND branch are selected
-3. Redirects to `/auth/login` with `returnUrl` query param if checks fail
-
-### guestGuard
-
-Protects auth routes (login, register) from authenticated users. Restores session first.
-
-```typescript
-import { guestGuard } from '@flusys/ng-auth';
-
-{
-  path: 'auth/login',
-  canActivate: [guestGuard],
-  loadComponent: () => import('./login.component')
-}
-```
-
-**Behavior:**
-1. If already initialized → check auth state immediately
-2. Otherwise → calls `AuthInitService.initialize()` first
-3. If authenticated AND company selected → redirects to home or returnUrl
-4. If selection pending → allows access (login handles Step 2)
-5. If not authenticated → allows access
-
-### companyFeatureGuard
-
-Enables/disables company management routes based on config.
-
-```typescript
-import { companyFeatureGuard } from '@flusys/ng-auth';
-
-{
-  path: 'administration/company',
-  canActivate: [authGuard, companyFeatureGuard],
-  loadComponent: () => import('./company-list.component')
-}
-```
-
-**Checks:** `enableCompanyFeature` in APP_CONFIG. Redirects to `/` if disabled.
-
-### emailFeatureGuard
-
-Protects email-related routes (forgot-password, reset-password, verify-email).
-
-```typescript
-import { emailFeatureGuard } from '@flusys/ng-auth';
-
-{
-  path: 'auth/forgot-password',
-  canActivate: [emailFeatureGuard, guestGuard],
-  loadComponent: () => import('./forgot-password.component')
-}
-```
-
-**Checks:** `services.email.enabled` in APP_CONFIG. Redirects to `/auth/login` if disabled.
-
-### signUpFeatureGuard
-
-Protects registration route when sign-up is disabled.
-
-```typescript
-import { signUpFeatureGuard } from '@flusys/ng-auth';
-
-{
-  path: 'auth/register',
-  canActivate: [signUpFeatureGuard, guestGuard],
-  loadComponent: () => import('./register.component')
-}
-```
-
-**Checks:** `enableSignUp` in APP_CONFIG (defaults to `true`). Redirects to `/auth/login` if `false`.
-
----
-
-## Interceptors
-
-### authInterceptor
-
-Adds authentication headers to HTTP requests.
-
-```typescript
-import { authInterceptor } from '@flusys/ng-auth';
-
-provideHttpClient(
-  withInterceptors([authInterceptor, ...])
-)
-```
-
-**Adds:**
-- `Authorization: Bearer {token}` if token exists
-- Tenant header (`X-Tenant-ID` by default) if multi-tenant enabled
-- `withCredentials: true` + `cookie` header for auth endpoints (cookie support)
-
-**Cookie Endpoints:**
-- `/auth/login`, `/auth/logout`, `/auth/refresh`, `/auth/register`
-- `/auth/select`, `/auth/switch-company`, `/auth/verify-email`
-
-### tokenRefreshInterceptor
-
-Handles 401 responses and proactive token refresh.
-
-```typescript
-import { tokenRefreshInterceptor } from '@flusys/ng-auth';
-
-provideHttpClient(
-  withInterceptors([authInterceptor, tokenRefreshInterceptor, ...])
-)
-```
-
-**Behavior:**
-
-1. **Skip endpoints:** `/auth/refresh`, `/auth/login`, `/auth/select`, `/auth/register`
-
-2. **Proactive refresh:** Before request, checks if `isTokenExpired()` (expired or expiring within 30s)
-   - If expired → refresh token first, then retry with new token
-
-3. **Reactive refresh:** After 401 response
-   - If refresh in progress → queue request, wait for new token
-   - If not refreshing → start refresh, then retry
-
-4. **On refresh failure:**
-   - Shows toast "Session Expired"
-   - Calls `authState.resetState()`
-   - Navigates to login
-
----
-
-## Constants
-
-### AUTH_ENDPOINTS
-
-Centralized endpoint definitions used by interceptors.
-
-```typescript
-import { AUTH_ENDPOINTS, isEndpoint } from '@flusys/ng-auth';
-
-// Endpoint constants
-AUTH_ENDPOINTS.LOGIN              // '/auth/login'
-AUTH_ENDPOINTS.LOGOUT             // '/auth/logout'
-AUTH_ENDPOINTS.REFRESH            // '/auth/refresh'
-AUTH_ENDPOINTS.REGISTER           // '/auth/register'
-AUTH_ENDPOINTS.ME                 // '/auth/me'
-AUTH_ENDPOINTS.SELECT             // '/auth/select'
-AUTH_ENDPOINTS.SWITCH_COMPANY     // '/auth/switch-company'
-AUTH_ENDPOINTS.CHANGE_PASSWORD    // '/auth/change-password'
-AUTH_ENDPOINTS.VERIFY_EMAIL       // '/auth/verify-email'
-AUTH_ENDPOINTS.FORGOT_PASSWORD    // '/auth/forgot-password'
-AUTH_ENDPOINTS.RESET_PASSWORD     // '/auth/reset-password'
-AUTH_ENDPOINTS.RESEND_VERIFICATION // '/auth/resend-verification'
-
-// Helper function
-isEndpoint(url, endpoint);         // Check if URL contains endpoint
-```
-
----
-
-## Provider Adapters
-
-ng-auth implements provider interfaces from ng-shared and ng-layout, enabling feature packages to access auth data without direct dependencies.
-
-### provideAuthProviders()
-
-Registers provider adapters for ng-shared interfaces (used by ng-iam, ng-storage, ng-form-builder).
-
-```typescript
-import { provideAuthProviders } from '@flusys/ng-auth';
-
-// app.config.ts
-providers: [
-  ...provideAuthProviders()
-]
-```
-
-**Registers:**
-- `USER_PROVIDER` → `AuthUserProviderAdapter` (user list for ng-iam)
-- `COMPANY_API_PROVIDER` → `AuthCompanyApiProviderAdapter` (company list for ng-iam)
-- `USER_PERMISSION_PROVIDER` → `AuthUserPermissionProviderAdapter` (permission queries)
-- `AUTH_STATE_PROVIDER` → `AuthStateProviderAdapter` (isAuthenticated, initialize)
-
-### provideAuthLayoutIntegration()
-
-Bridges ng-auth to ng-layout components.
-
-```typescript
-import { provideAuthLayoutIntegration } from '@flusys/ng-auth';
-
-// app.config.ts
-providers: [
-  ...provideAuthLayoutIntegration()
-]
-```
+## Overview
 
-**Registers:**
-- `LAYOUT_AUTH_STATE` → `AuthLayoutStateAdapter` (user/company/branch signals)
-- `LAYOUT_AUTH_API` → `AuthLayoutApiAdapter` (logout, switch company, etc.)
+`@flusys/ng-auth` provides end-to-end authentication for FLUSYS Angular applications. It handles the complete lifecycle: login, registration, token refresh, session restoration on page reload, email verification, profile management, password changes, and multi-company selection.
 
-**AuthLayoutStateAdapter Signals:**
-```typescript
-currentCompanyInfo: Signal<ICompanyInfo | null>;  // { id, name, slug, imageId }
-currentBranchInfo: Signal<IBranchInfo | null>;    // { id, name, slug, imageId }
-loginUserData: Signal<ILayoutUserInfo | null>;    // { id, name, email }
-```
-
-**AuthLayoutApiAdapter Methods:**
-```typescript
-logOut();                              // Logout + reset state
-navigateLogin(withUrl?: boolean);      // Navigate to login, optionally with returnUrl
-switchCompany(companyId, branchId);    // Switch + page reload
-getUserCompanies();                    // User's permitted companies
-getCompanyBranches(companyId);         // User's permitted branches in company
-```
+Tokens are stored in **HTTP-only cookies** (managed by the backend) — never in localStorage. The access token is held in memory only and automatically refreshed via a silent refresh interceptor.
 
 ---
 
-## Pages
+## Features
 
-All page components follow Angular 21 best practices:
-- Signal Forms (`@angular/forms/signals`) with validation
-- 100% responsive design (mobile-first with Tailwind)
-- Dark mode compatible (PrimeNG + Tailwind CSS variables)
-- `inject()` for dependency injection
-- `effect()` for reactive data loading
-
-### Authentication Pages
-
-**LoginPageComponent** (`/auth/login`)
-- Multi-step login flow with visual step indicator (when company feature enabled)
-- Step 1: Credentials (email/password)
-- Step 2: Company/Branch selection (if `requiresSelection: true`)
-- Email verification step (if `requiresEmailVerification: true`)
-- Auto-selects if only one company/branch available
-- Restores stored company/branch from localStorage
-- Stores returnUrl for post-login redirect
-- Support for AUTH_VALIDATION_CONFIG (custom email/password validation)
-- **Conditional UI:**
-  - "Forgot password?" link hidden when `services.email.enabled: false`
-  - "Sign Up" link hidden when `enableSignUp: false`
-
-**RegisterPageComponent** (`/auth/register`)
-- User registration with optional company creation
-- Two-column responsive grid layout
-- Email/password validation with AUTH_VALIDATION_CONFIG support
-- Company details section (when company feature enabled)
-- Support for AUTH_REGISTRATION_EXTENSION (extra fields)
-- **Default company/branch support:**
-  - When `defaultCompanySlug` is set: pre-fills company code field (readonly)
-  - When `defaultBranchSlug` is set: pre-fills branch code field (readonly)
-  - "Create new company" option hidden when defaults are configured
-- Query param support: `?companySlug=xxx`
-
-**ForgotPasswordPageComponent** (`/auth/forgot-password`)
-- Email input with validation
-- Success state showing email sent confirmation
-- Always shows success (security: don't reveal if email exists)
-
-**ResetPasswordPageComponent** (`/auth/reset-password`)
-- Password reset with token from query param `?token=xxx`
-- Password confirmation matching
-- Three states: `form`, `success`, `invalid-token`
-- Auto-detects expired/invalid token from error message
-
-**VerifyEmailPageComponent** (`/auth/verify-email`)
-- Token verification from query param `?token=xxx`
-- SSR support via TransferState (prevents duplicate API calls)
-- Four states: `verifying`, `success`, `invalid-token`, `resend`
-- Resend verification form when token invalid/expired
-
-### Profile Page
-
-**ProfilePageComponent** (`/profile`)
-- Page title with description
-- Avatar section with initials fallback
-- Profile picture upload (requires `FILE_PROVIDER` from ng-storage)
-- Update name and phone with Signal Forms
-- Extra fields support via two providers:
-  - `AUTH_PROFILE_EXTENSION` - Fields user can edit
-  - `AUTH_USER_FORM_EXTENSION` - Fields displayed as view-only ("Managed by Admin")
-- Change password section with PrimeNG password strength indicator
-- Company/branch info (if company feature enabled)
-- Roles/actions display (requires `PROFILE_PERMISSION_PROVIDER` from ng-iam)
-- Permission mode support: `rbac`, `direct`, `full`
-- Responsive two-column layout on desktop
-
-**Optional Provider Dependencies:**
-
-| Provider | Source | Feature Enabled |
-|----------|--------|-----------------|
-| `FILE_PROVIDER` | ng-storage via `provideStorageProviders()` | Profile picture upload |
-| `PROFILE_PERMISSION_PROVIDER` | ng-iam via `provideIamProviders()` | Roles/actions display |
-
-### Administration Pages
-
-**AdministrationPageComponent** (`/administration`)
-- Page title "Administration" with dynamic subtitle
-- Horizontal scrolling tabs with hidden scrollbar
-- Tabs: Users, Companies, Branches
-- Company/Branch tabs only visible when company feature enabled
-- Permission-based tab visibility (USER_PERMISSIONS.READ, etc.)
-
-**User Management:**
-- `UserListComponent` - LazyLoad datatable with Edit, Delete, View Details, Permission actions
-  - Extra columns/actions support via AUTH_USER_LIST_EXTENSION
-  - User detail view via AUTH_USER_DETAIL_CONFIG (dialog or page mode)
-- `UserFormComponent` - Create/edit user
-  - Auto-assigns new users to current company/branch when company feature enabled
-
-**Company Management:**
-- `CompanyListComponent` - Company CRUD with View Branches action
-  - readOnly companies cannot be deleted
-- `CompanyFormComponent` - Create/edit company with auto slug generation
-
-**Branch Management:**
-- `BranchListComponent` - Branch CRUD filtered by company dropdown
-  - Defaults to current company context
-  - Supports `?companyId=xxx` query param
-- `BranchFormComponent` - Create/edit branch with company selection
-
-**Table Features (all list components):**
-- Responsive header (stacked on mobile)
-- Horizontal scroll wrapper (`overflow-x-auto`)
-- Conditional pagination (`[paginator]="total() > 0"`)
-- Striped rows (`p-datatable-striped`)
-- Lazy loading for performance
+- ✅ JWT authentication with HTTP-only refresh token cookies
+- ✅ Silent token refresh on 401 responses
+- ✅ Session restoration on page reload (`AuthInitService`)
+- ✅ Multi-company selection flow
+- ✅ Email verification with OTP
+- ✅ Profile management (name, password, avatar)
+- ✅ `AuthStateService` — signal-based reactive auth state
+- ✅ `provideAuthProviders()` — registers `USER_PROVIDER`, `COMPANY_PROVIDER`
+- ✅ `provideAuthLayoutIntegration()` — bridges auth to layout
+- ✅ Guard: `appInitGuard` for session restoration before navigation
+- ✅ Guard: `AuthenticatedGuard`, `GuestGuard`, `CompanySelectedGuard`
 
 ---
 
-## Dialog Components
-
-Both dialog components use Angular 21 patterns:
-- `input.required<T>()` for required inputs
-- `output<void>()` for events
-- `effect()` for reactive data loading
-- Responsive breakpoints (`{ '960px': '90vw', '640px': '95vw' }`)
-
-### UserCompanyPermissionDialogComponent
-
-Manages user-to-company assignments with checkboxes.
-
-```typescript
-import { UserCompanyPermissionDialogComponent } from '@flusys/ng-auth';
-
-@Component({
-  imports: [UserCompanyPermissionDialogComponent],
-  template: `
-    <lib-user-company-permission-dialog
-      [visible]="showDialog()"
-      [user]="selectedUser()"
-      (closed)="showDialog.set(false)"
-      (permissionsChanged)="reloadData()" />
-  `
-})
-```
-
-**Inputs/Outputs:**
-```typescript
-readonly visible = input.required<boolean>();
-readonly user = input.required<IUser | null>();
-readonly closed = output<void>();
-readonly permissionsChanged = output<void>();
-```
+## Compatibility
 
-**Features:**
-- Shows all companies with checkboxes
-- Pre-checks assigned companies
-- Immediate save on toggle (no Save button)
-- Toast notifications for success/error
-- Loading spinner during data fetch
-- Disabled checkboxes while saving
-
-### UserBranchPermissionDialogComponent
-
-Manages user-to-branch assignments with company filtering.
-
-```typescript
-import { UserBranchPermissionDialogComponent } from '@flusys/ng-auth';
-
-@Component({
-  imports: [UserBranchPermissionDialogComponent],
-  template: `
-    <lib-user-branch-permission-dialog
-      [visible]="showDialog()"
-      [user]="selectedUser()"
-      (closed)="showDialog.set(false)"
-      (permissionsChanged)="reloadData()" />
-  `
-})
-```
-
-**Features:**
-- Company dropdown shows only user's permitted companies
-- Branch list loads on company selection
-- Immediate save on toggle
-- Contextual empty messages:
-  - "This user has no company permissions assigned" (no companies)
-  - "Please select a company to view branches" (no selection)
-  - "No branches available" (empty)
+| Package | Version |
+|---------|---------|
+| Angular | 21+ |
+| @flusys/ng-core | 4.x |
+| @flusys/ng-shared | 4.x |
 
 ---
 
-## Routes
-
-### AUTH_ROUTES
-
-Public authentication routes.
-
-```typescript
-import { AUTH_ROUTES } from '@flusys/ng-auth';
-
-// Routes: /auth/login, /auth/register, /auth/forgot-password, /auth/reset-password, /auth/verify-email
-{ path: 'auth', children: AUTH_ROUTES }
-```
-
-**Route Configuration:**
-| Path | Component | Guards |
-|------|-----------|--------|
-| `/auth/login` | LoginPageComponent | guestGuard |
-| `/auth/register` | RegisterPageComponent | signUpFeatureGuard, guestGuard |
-| `/auth/forgot-password` | ForgotPasswordPageComponent | emailFeatureGuard, guestGuard |
-| `/auth/reset-password` | ResetPasswordPageComponent | emailFeatureGuard, guestGuard |
-| `/auth/verify-email` | VerifyEmailPageComponent | emailFeatureGuard |
-
-### ADMINISTRATION_ROUTES
-
-Protected administration routes with tabbed interface.
-
-```typescript
-import { ADMINISTRATION_ROUTES } from '@flusys/ng-auth';
-
-{
-  path: 'administration',
-  children: ADMINISTRATION_ROUTES
-}
-```
-
-**Route Configuration:**
-| Path | Component | Guards |
-|------|-----------|--------|
-| `/administration` | AdministrationPageComponent | authGuard |
-| `/administration/users` | UserListComponent | permissionGuard(USER_PERMISSIONS.READ) |
-| `/administration/users/new` | UserFormComponent | |
-| `/administration/users/:id` | UserFormComponent | |
-| `/administration/company` | CompanyListComponent | companyFeatureGuard, permissionGuard(COMPANY_PERMISSIONS.READ) |
-| `/administration/company/new` | CompanyFormComponent | |
-| `/administration/company/:id` | CompanyFormComponent | |
-| `/administration/branch` | BranchListComponent | companyFeatureGuard, permissionGuard(BRANCH_PERMISSIONS.READ) |
-| `/administration/branch/new` | BranchFormComponent | |
-| `/administration/branch/:id` | BranchFormComponent | |
-
-### PROFILE_ROUTES
+## Installation
 
-User profile page routes.
-
-```typescript
-import { PROFILE_ROUTES } from '@flusys/ng-auth';
-
-{
-  path: 'profile',
-  children: PROFILE_ROUTES
-}
+```bash
+npm install @flusys/ng-auth @flusys/ng-core @flusys/ng-shared
 ```
 
 ---
 
-## Setup
+## Quick Start
 
-### app.config.ts
+### 1. Register Auth Providers
 
 ```typescript
+// app.config.ts
 import { ApplicationConfig } from '@angular/core';
-import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';
-import { APP_CONFIG, errorCatchingInterceptor } from '@flusys/ng-core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { APP_CONFIG } from '@flusys/ng-core';
 import {
+  provideAuthProviders,
+  provideAuthLayoutIntegration,
   authInterceptor,
   tokenRefreshInterceptor,
-  provideAuthLayoutIntegration,
-  provideAuthProviders
 } from '@flusys/ng-auth';
-import { provideIamProviders } from '@flusys/ng-iam';
-import { provideStorageProviders } from '@flusys/ng-storage';
+import { environment } from './environments/environment';
 
 export const appConfig: ApplicationConfig = {
   providers: [
+    { provide: APP_CONFIG, useValue: environment },
     provideHttpClient(
-      withFetch(),
       withInterceptors([
-        authInterceptor,         // First: adds token
-        tokenRefreshInterceptor, // Second: handles 401 + proactive refresh
-        errorCatchingInterceptor // Last: shows errors
+        authInterceptor,          // Attaches access token to requests
+        tokenRefreshInterceptor,  // Handles 401 → refresh → retry
       ])
     ),
-    { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
-    ...provideAuthLayoutIntegration(),
-    ...provideAuthProviders(),
-    ...provideIamProviders(),      // Enables permissions display on profile
-    ...provideStorageProviders(),  // Enables profile picture upload
-  ]
+    ...provideAuthProviders(),           // USER_PROVIDER, COMPANY_PROVIDER
+    ...provideAuthLayoutIntegration(),   // LAYOUT_AUTH_STATE, LAYOUT_AUTH_API
+  ],
 };
 ```
 
-### app.routes.ts
+### 2. Protect Routes with Guards
 
 ```typescript
+// app.routes.ts
 import { Routes } from '@angular/router';
-import { authGuard, AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';
+import { appInitGuard } from '@flusys/ng-auth';
+import { AppLayoutComponent } from '@flusys/ng-layout';
 
 export const routes: Routes = [
-  { path: 'auth', children: AUTH_ROUTES },
   {
     path: '',
-    canActivate: [authGuard],
+    component: AppLayoutComponent,
+    canActivate: [appInitGuard],  // Restores session on page refresh
     children: [
-      { path: 'dashboard', loadComponent: () => import('./dashboard.component') },
-      { path: 'administration', children: ADMINISTRATION_ROUTES },
-      { path: 'profile', children: PROFILE_ROUTES }
-    ]
-  }
+      { path: 'dashboard', loadComponent: () => import('./pages/dashboard.component') },
+    ],
+  },
+  {
+    path: 'auth',
+    loadChildren: () => import('@flusys/ng-auth').then(m => m.AUTH_ROUTES),
+  },
 ];
 ```
 
----
-
-## Interfaces
-
-### Request DTOs
+### 3. Enable Auth in App Config
 
 ```typescript
-interface ILoginRequest {
-  email: string;
-  password: string;
-}
-
-interface IRegistrationRequest {
-  name: string;
-  email: string;
-  password: string;
-  phone?: string;
-  companySlug?: string;
-  branchSlug?: string;
-  newCompanyName?: string;
-  newCompanyPhone?: string;
-  newCompanyAddress?: string;
-  additionalFields?: Record<string, unknown>;
-}
-
-interface ISelectRequest {
-  sessionId: string;
-  companyId: string;
-  branchId: string;
-}
-
-interface ISwitchCompanyRequest {
-  companyId: string;
-  branchId: string;
-}
-
-interface IChangePasswordRequest {
-  currentPassword: string;
-  newPassword: string;
-}
-
-interface ICreateUserRequest {
-  name: string;
-  email: string;
-  password: string;
-  phone?: string;
-  profilePictureId?: string;
-  isActive?: boolean;
-  emailVerified?: boolean;
-  phoneVerified?: boolean;
-  additionalFields?: Record<string, unknown>;
-}
-
-interface IUpdateUserRequest {
-  id: string;
-  name?: string;
-  email?: string;
-  password?: string;
-  oldPassword?: string;
-  phone?: string;
-  profilePictureId?: string;
-  isActive?: boolean;
-  emailVerified?: boolean;
-  phoneVerified?: boolean;
-  additionalFields?: Record<string, unknown>;
-}
-
-interface ICreateCompanyRequest {
-  name: string;
-  slug: string;
-  logoId?: string;
-  address?: string;
-  phone?: string;
-  email?: string;
-  website?: string;
-  serial?: number;
-  isActive?: boolean;
-  settings?: Record<string, unknown>;
-  additionalFields?: Record<string, unknown>;
-}
-
-interface ICreateBranchRequest {
-  name: string;
-  slug: string;
-  companyId: string;
-  parentId?: string;
-  logoId?: string;
-  address?: string;
-  phone?: string;
-  email?: string;
-  serial?: number;
-  isActive?: boolean;
-  additionalFields?: Record<string, unknown>;
-}
+// environments/environment.ts
+export const environment = {
+  apiBaseUrl: 'http://localhost:2002',
+  services: {
+    auth: {
+      enabled: true,
+      features: {
+        signUp: true,
+        emailVerification: true,
+        companySelection: true,
+      },
+    },
+  },
+};
 ```
 
-### Response DTOs
-
-```typescript
-interface IUserInfo {
-  id: string;
-  email: string;
-  name?: string;
-  phone?: string | null;
-  profilePictureId?: string | null;
-  companyId?: string;
-  branchId?: string;
-  companyLogoId?: string;
-  branchLogoId?: string;
-}
-
-interface ICompanyInfo {
-  id: string;
-  name: string;
-  slug?: string;
-  logoId?: string | null;
-}
-
-interface IBranchInfo {
-  id: string;
-  name: string;
-  slug?: string;
-  logoId?: string | null;
-}
-
-interface ICompanyWithBranches {
-  id: string;
-  name: string;
-  slug: string;
-  logoId?: string | null;
-  branches: IBranchSelectionInfo[];
-}
-
-interface ILoginResponse {
-  accessToken: string;
-  refreshToken: string;
-  user: IUserInfo;
-  company?: ICompanyInfo;
-  branch?: IBranchInfo;
-}
-
-interface ICompanySelectionResponse {
-  requiresSelection: true;
-  sessionId: string;
-  expiresAt: Date | string;
-  user: IUserInfo;
-  companies: ICompanyWithBranches[];
-}
-
-interface ILoginRequiresEmailVerification {
-  requiresEmailVerification: true;
-  email: string;
-  message: string;
-}
-
-interface IMeResponse {
-  user: IUserInfo;
-  company?: ICompanyInfo;
-  branch?: IBranchInfo;
-}
+---
 
-interface IRegistrationResponse {
-  accessToken?: string;
-  refreshToken?: string;
-  user: IUserInfo;
-  company?: ICompanyInfo;
-  branch?: IBranchInfo;
-  requiresEmailVerification?: boolean;
-}
+## Module Registration
 
-interface IRefreshTokenResponse {
-  accessToken: string;
-  refreshToken?: string;
-}
+`ng-auth` uses function-based providers (not Angular modules):
 
-type AuthResponse = ILoginResponse | ICompanySelectionResponse | ILoginRequiresEmailVerification;
-```
+### `provideAuthProviders()`
 
-### Entity DTOs
+Registers auth adapters against shared provider tokens:
 
 ```typescript
-interface IUser {
-  id: string;
-  name: string;
-  email: string;
-  phone?: string | null;
-  profilePictureId?: string | null;
-  isActive: boolean;
-  emailVerified: boolean;
-  phoneVerified: boolean;
-  lastLoginAt?: Date | string | null;
-  additionalFields?: Record<string, unknown> | null;
-  createdAt: Date | string;
-  updatedAt: Date | string;
-  deletedAt?: Date | string | null;
-}
+...provideAuthProviders()
 
-interface ICompany {
-  id: string;
-  name: string;
-  slug: string;
-  logoId?: string | null;
-  address?: string | null;
-  phone?: string | null;
-  email?: string | null;
-  website?: string | null;
-  serial?: number;
-  isActive: boolean;
-  readOnly: boolean;
-  settings?: Record<string, unknown> | null;
-  additionalFields?: Record<string, unknown> | null;
-  createdAt: Date | string;
-  updatedAt: Date | string;
-}
-
-interface IBranch {
-  id: string;
-  name: string;
-  slug: string;
-  companyId: string;
-  parentId?: string | null;
-  logoId?: string | null;
-  address?: string | null;
-  phone?: string | null;
-  email?: string | null;
-  serial?: number;
-  isActive: boolean;
-  readOnly: boolean;
-  additionalFields?: Record<string, unknown> | null;
-  createdAt: Date | string;
-  updatedAt: Date | string;
-}
+// Provides:
+// USER_PROVIDER    → AuthStateService (IUserProvider)
+// COMPANY_PROVIDER → AuthStateService (ICompanyProvider)
 ```
 
-### Permission DTOs
-
-```typescript
-interface IPermissionItem {
-  targetId: string;
-  isAdd: boolean;
-}
-
-interface IAssignUserCompanyRequest {
-  userId: string;
-  items: IPermissionItem[];
-}
-
-interface IAssignUserBranchRequest {
-  userId: string;
-  items: IPermissionItem[];
-}
+These tokens are consumed by `ng-iam`, `ng-storage`, `ng-notification` — no direct dependency on `ng-auth`.
 
-interface IBatchOperationResponse {
-  success: boolean;
-  message: string;
-}
+### `provideAuthLayoutIntegration()`
 
-interface IUserCompanyPermission {
-  id: string;
-  userId: string;
-  companyId: string;
-  companyName: string;
-  companySlug: string;
-}
+Bridges auth state and API to the layout:
 
-interface IUserBranchPermission {
-  id: string;
-  userId: string;
-  branchId: string;
-  branchName: string;
-  branchSlug: string;
-  companyId: string;
-}
-
-interface IUserCompaniesResponse {
-  success: boolean;
-  message: string;
-  data: IUserCompanyPermission[];
-}
+```typescript
+...provideAuthLayoutIntegration()
 
-interface IUserBranchesResponse {
-  success: boolean;
-  message: string;
-  data: IUserBranchPermission[];
-}
+// Provides:
+// LAYOUT_AUTH_STATE → AuthLayoutStateAdapter (profile picture, company logo)
+// LAYOUT_AUTH_API   → AuthLayoutApiAdapter (logout, select-company actions)
 ```
 
 ---
 
-## Best Practices
-
-### Angular 21 Component Patterns
-
-All components follow these patterns:
-
-| Pattern | Implementation |
-|---------|---------------|
-| Dependency Injection | `inject()` function |
-| State (private writable) | `private readonly _data = signal<T>(...)` |
-| State (public readonly) | `readonly data = this._data.asReadonly()` |
-| Computed | `readonly isValid = computed(() => ...)` |
-| Signal Forms | `form(this.formModel, (f) => { required(f.field, {...}) })` |
-| Reactive Init | `effect(() => { if (condition()) loadData(); })` |
-| Async Methods | `try/finally` with `isLoading` signal, errors handled by global interceptor |
-
-### Responsive Design Patterns
-
-```html
-<!-- Responsive container -->
-<div class="flex flex-col sm:flex-row justify-between items-start sm:items-center gap-3 p-4">
+## Session Restoration Flow
 
-<!-- Two-column form grid -->
-<form class="grid grid-cols-1 md:grid-cols-2 gap-4">
+On every page refresh, auth state is cleared from memory. The `appInitGuard` restores the session transparently:
 
-<!-- Right-aligned buttons -->
-<div class="flex justify-end gap-4 md:col-span-2 pt-4">
-
-<!-- Horizontally scrollable tabs -->
-<div class="scrollbar-hide flex gap-1 overflow-x-auto flex-nowrap">
-
-<!-- Responsive table wrapper -->
-<div class="overflow-x-auto">
-  <p-table [scrollable]="true" [paginator]="total() > 0">
 ```
-
-### Component Organization
-
+Page Refresh
+     │
+     ▼
+appInitGuard runs
+     │
+     ├─ User in memory? ──YES──► Check company → Allow navigation
+     │
+     └─ NO ──► AuthInitService.initialize()
+                    │
+                    ├─ POST /auth/refresh (HTTP-only cookie) → access token
+                    ├─ GET /auth/me → user data
+                    └─ Session restored in memory
+                         │
+                         ├─ Auth enabled? → Check company selection
+                         ├─ IAM enabled? → Load permissions
+                         └─ Allow navigation
 ```
-projects/ng-auth/
-├── components/                    ← Shared dialogs
-│   ├── user-company-permission-dialog.component.ts
-│   └── user-branch-permission-dialog.component.ts
-├── pages/                         ← Route-specific pages
-│   ├── login/
-│   ├── register/
-│   ├── forgot-password/
-│   ├── reset-password/
-│   ├── verify-email/
-│   ├── profile/
-│   ├── administration/
-│   ├── users/
-│   ├── company/
-│   └── branch/
-├── services/
-├── guards/
-├── interceptors/
-├── adapters/
-├── providers/
-├── interfaces/
-├── constants/
-└── routes/
-```
-
-**Rule:** Dialog components go in `components/`, page components go in `pages/`.
-
-### Permission Filtering Pattern
 
-When building permission UI, filter by user's permitted scope:
+### Company Selection Flow
 
-```typescript
-// ✅ CORRECT - Filter by user's permitted companies
-const response = await firstValueFrom(permApi.getUserCompanies(userId));
-const userCompanies = response.data;
-
-// ❌ WRONG - Don't show all companies
-const allCompanies = await companyApi.fetchList(); // Security risk
 ```
-
-### Token Management
-
-- Access tokens stored in memory only (XSS protection)
-- Only token expiry is persisted to localStorage
-- Refresh tokens sent via httpOnly cookies
-- TokenRefreshInterceptor handles:
-  - Proactive refresh (30s before expiry)
-  - Reactive refresh (on 401)
-  - Request queuing during refresh
-- Auto-persistence for company/branch selection
-
-### Type Safety
-
-Avoid `any` types - use explicit interfaces:
-
-```typescript
-// ✅ CORRECT - Explicit response type
-.subscribe({
-  next: (response: { success: boolean; data: IUser }) => {
-    if (response.success) { ... }
-  },
-});
-
-// ❌ WRONG - Using any
-.subscribe({
-  next: (response: any) => { ... },
-});
-```
-
-### Multi-Company Flow
-
-1. Login → Check response type with type guards
-2. If `isCompanySelectionResponse` → Show Step 2 (company/branch selection)
-3. If `isEmailVerificationRequired` → Show email verification step
-4. If `isLoginResponse` → Direct login success
-5. Auto-select if only one company/branch
-6. Save selection → Navigate to dashboard
-
----
-
-## Common Issues
-
-| Problem | Solution |
-|---------|----------|
-| Routes accessible without auth | Ensure `authGuard` is on parent route |
-| 401 on all requests | Ensure interceptor order: `authInterceptor` → `tokenRefreshInterceptor` → `errorCatchingInterceptor` |
-| User info missing from topbar | Add `...provideAuthLayoutIntegration()` to providers |
-| Switcher shows all companies | Ensure user has company permissions assigned via `UserPermissionApiService` |
-| Session not restored on refresh | 1) Use `guestGuard` on auth routes 2) Check refresh cookie in DevTools 3) Verify backend refresh endpoint |
-
----
-
-## No-IAM Mode (Bypassing Permission Guards)
-
-When not using `@flusys/ng-iam`, routes with `permissionGuard` will fail (no permissions loaded).
-
-**Solution:** Set wildcard permissions after login:
-
-```typescript
-// Option 1: In login flow (recommended)
-this.permissionValidator.setPermissions(['*']);
-
-// Option 2: In APP_INITIALIZER
-{ provide: APP_INITIALIZER, useFactory: (pv: PermissionValidatorService) => () => pv.setPermissions(['*']), deps: [PermissionValidatorService], multi: true }
+User logs in
+     │
+     ├─ requiresSelection: false ──► Navigate to app
+     │
+     └─ requiresSelection: true
+           │
+           ├─ sessionId + companies[] returned
+           └─ Redirect to /auth/select-company
+                    │
+                    └─ User picks company/branch
+                              │
+                              └─ POST /auth/select { sessionId, companyId, branchId }
+                                        │
+                                        └─ Tokens + company data → Navigate to app
 ```
 
-| Pattern | Meaning |
-|---------|---------|
-| `*` | Full access to everything |
-| `user.*` | All user permissions |
-| `branch.*` | All branch permissions |
-
 ---
 
-## Extension System
-
-ng-auth provides injection tokens for extending registration, user list, and profile without modifying the core package.
-
-### Extension Injection Tokens
-
-```typescript
-import {
-  AUTH_VALIDATION_CONFIG,
-  AUTH_REGISTRATION_EXTENSION,
-  AUTH_USER_LIST_EXTENSION,
-  AUTH_USER_DETAIL_CONFIG,
-  AUTH_PROFILE_EXTENSION,
-  AUTH_USER_FORM_EXTENSION,
-} from '@flusys/ng-auth';
-```
-
-### AUTH_VALIDATION_CONFIG
-
-Customize email and password validation.
+## Auth State Service
 
-| Property | Options |
-|----------|---------|
-| `email.pattern` | Custom regex |
-| `email.message` | Error message |
-| `password.minLength/maxLength` | Length constraints |
-| `password.requireUppercase/Lowercase/Numbers/SpecialChars` | Character requirements |
-| `password.pattern` | Custom regex |
-| `password.message` | Error message |
+`AuthStateService` is the single source of truth for authentication state, powered by Angular signals.
 
 ```typescript
-{ provide: AUTH_VALIDATION_CONFIG, useValue: { password: { minLength: 8, requireUppercase: true } } }
-
-// Helper functions
-import { validatePassword, validateEmail } from '@flusys/ng-auth';
-```
-
-### AUTH_REGISTRATION_EXTENSION
-
-Add extra fields to registration form.
-
-**IRegistrationExtraField:** `key`, `label`, `type` (text|number|select|checkbox|textarea|date|template), `placeholder?`, `required?`, `defaultValue?`, `options?`, `pattern?`, `validationMessage?`, `order?`, `containerClass?`, `template?`, `component?`
+import { AuthStateService } from '@flusys/ng-auth';
 
-**IRegistrationExtensionProvider Methods:**
+@Component({ ... })
+export class MyComponent {
+  private authState = inject(AuthStateService);
 
-| Method | Purpose |
-|--------|---------|
-| `getExtraFields()` | Return field definitions |
-| `transformRegistrationData?(data)` | Transform before submission (e.g., wrap in `additionalFields`) |
-| `validateExtraFields?(data)` | Custom validation, return error message or null |
+  // Signals (read-only)
+  user = this.authState.user;                   // Signal<ICurrentUser | null>
+  company = this.authState.company;             // Signal<ICompany | null>
+  branch = this.authState.branch;               // Signal<IBranch | null>
+  isAuthenticated = this.authState.isAuthenticated; // Signal<boolean>
+  accessToken = this.authState.accessToken;     // Signal<string | null>
 
-```typescript
-{ provide: AUTH_REGISTRATION_EXTENSION, useClass: MyExtension }
-// Custom component: inject(REGISTRATION_FIELD_CONTEXT) for field, value, updateValue()
+  // Computed
+  userName = computed(() => this.authState.user()?.name ?? 'Guest');
+}
 ```
 
-### AUTH_USER_LIST_EXTENSION
-
-Add extra columns and actions to user list.
+**AuthStateService API:**
 
-**IUserListExtraColumn:** `key`, `header`, `field?` (dot notation: `additionalFields.employeeId`), `template?`, `styleClass?`, `width?`, `sortable?`, `order?`
+| Member | Type | Description |
+|--------|------|-------------|
+| `user` | `Signal<ICurrentUser \| null>` | Current authenticated user |
+| `company` | `Signal<ICompany \| null>` | Selected company |
+| `branch` | `Signal<IBranch \| null>` | Selected branch |
+| `isAuthenticated` | `Signal<boolean>` | True if user is logged in |
+| `accessToken` | `Signal<string \| null>` | In-memory JWT access token |
+| `setUser(user)` | `void` | Update user state |
+| `setTokens(tokens)` | `void` | Update access token |
+| `setCompany(company, branch)` | `void` | Update company/branch |
+| `clearAll()` | `void` | Clear all auth state (logout) |
 
-**IUserListExtraAction:** `key`, `label`, `icon`, `severity?`, `permission?`, `onClick(user)`, `isVisible?(user)`, `isDisabled?(user)`, `order?`
+---
 
-**IUserListExtensionProvider Methods:**
+## Auth API Service
 
-| Method | Purpose |
-|--------|---------|
-| `getExtraColumns()` | Return column definitions |
-| `getExtraActions()` | Return action button definitions |
-| `enrichUserData?(users)` | Transform user data (usually handled by backend enricher) |
+`AuthApiService` handles all HTTP calls to the auth backend.
 
 ```typescript
-{ provide: AUTH_USER_LIST_EXTENSION, useFactory: (router, msg) => new MyExtension(router, msg), deps: [Router, MessageService] }
-```
-
-### AUTH_USER_DETAIL_CONFIG
-
-Configure user detail view mode.
-
-**IUserDetailViewConfig:** `viewMode` (dialog|sidebar|page), `allowEdit?`, `width?`, `component?`, `tabs?` (array: key, label, icon?, component?, template?)
+import { AuthApiService } from '@flusys/ng-auth';
 
-```typescript
-{ provide: AUTH_USER_DETAIL_CONFIG, useValue: { viewMode: 'dialog', allowEdit: true, width: '800px' } }
+@Component({ ... })
+export class LoginPageComponent {
+  private authApi = inject(AuthApiService);
+
+  login(email: string, password: string): void {
+    this.authApi.login({ email, password }).subscribe(response => {
+      if (response.requiresSelection) {
+        // Redirect to company selection
+      }
+      // Navigate to app
+    });
+  }
+}
 ```
 
-### AUTH_PROFILE_EXTENSION
+**AuthApiService Methods:**
 
-Add extra fields that **users can edit** on their own profile page.
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `login(dto)` | `POST /auth/login` | Authenticate user |
+| `register(dto)` | `POST /auth/register` | Self-register |
+| `logout()` | `POST /auth/logout` | Invalidate tokens |
+| `refresh()` | `POST /auth/refresh` | Refresh access token |
+| `me()` | `GET /auth/me` | Get current user info |
+| `selectCompany(dto)` | `POST /auth/select` | Select company after login |
+| `verifyEmail(dto)` | `POST /auth/verify-email` | Verify OTP |
+| `resendVerification()` | `POST /auth/resend-verification` | Resend OTP email |
+| `changePassword(dto)` | `POST /auth/change-password` | Update password |
+| `updateProfile(dto)` | `POST /auth/update-profile` | Update name/avatar |
 
-**IProfileExtraField:** `key`, `label`, `type` (text|number|select|checkbox|textarea|date|template), `placeholder?`, `required?`, `options?`, `pattern?`, `validationMessage?`, `order?`, `sectionKey?`, `template?`, `component?`, `injector?`
+---
 
-**IProfileExtraSection:** `key`, `title`, `icon?`, `order?`, `component?`, `template?`, `collapsible?`, `collapsed?`, `editPermission?`
+## HTTP Interceptors
 
-**IProfileExtensionProvider Methods:**
+### authInterceptor
 
-| Method | Purpose |
-|--------|---------|
-| `getExtraFields?()` | Return field definitions (user-editable) |
-| `getExtraSections?()` | Return section definitions |
-| `getExtraFieldValues?(userId)` | Fetch values from custom API |
-| `saveExtraFieldValues?(userId, data)` | Save values to custom API |
-| `validateExtraFields?(data)` | Custom validation, return error message or null |
+Attaches the in-memory access token as `Authorization: Bearer <token>` header to every outgoing request (except public endpoints).
 
 ```typescript
-{ provide: AUTH_PROFILE_EXTENSION, useClass: MyProfileExtension }
-// Custom component: inject(PROFILE_FIELD_CONTEXT) for field, value, updateValue()
+provideHttpClient(
+  withInterceptors([authInterceptor])
+)
 ```
 
-### AUTH_USER_FORM_EXTENSION
-
-Add extra fields that **admins can edit** on the user management form (`/administration/users/:id`).
-These fields appear as **view-only** on the user's profile page with "Managed by Admin" label.
-
-**IUserFormExtraField:** `key`, `label`, `type` (text|number|select|checkbox|textarea|date|template), `placeholder?`, `required?`, `options?`, `pattern?`, `validationMessage?`, `order?`, `template?`, `component?`, `injector?`
+### tokenRefreshInterceptor
 
-**IUserFormExtensionProvider Methods:**
+On 401 responses, automatically:
+1. Calls `POST /auth/refresh`
+2. Updates `AuthStateService` with new token
+3. Retries the original failed request
 
-| Method | Purpose |
-|--------|---------|
-| `getExtraFields?()` | Return field definitions (admin-editable) |
-| `getExtraFieldValues?(userId)` | Fetch values from custom API |
-| `saveExtraFieldValues?(userId, data)` | Save values to custom API |
-| `validateExtraFields?(data)` | Custom validation, return error message or null |
+All concurrent 401s are queued — only one refresh call is made.
 
 ```typescript
-{ provide: AUTH_USER_FORM_EXTENSION, useClass: MyUserFormExtension }
-// Custom component: inject(USER_FORM_FIELD_CONTEXT) for field, value, updateValue()
+provideHttpClient(
+  withInterceptors([tokenRefreshInterceptor])
+)
 ```
 
-**Profile vs Admin Form Pattern:**
-
-| Provider | Used In | Who Edits | Profile Display |
-|----------|---------|-----------|-----------------|
-| `AUTH_PROFILE_EXTENSION` | Profile page | User | Editable fields |
-| `AUTH_USER_FORM_EXTENSION` | Admin user form | Admin | View-only ("Managed by Admin") |
-
-### Provider Factory Example
-
-Combine all extensions in a single provider function for app.config.ts:
+**Interceptor Order Matters:**
 
 ```typescript
-export function provideAuthExtensions(): Provider[] {
-  return [
-    { provide: AUTH_VALIDATION_CONFIG, useValue: myValidationConfig },
-    { provide: AUTH_REGISTRATION_EXTENSION, useClass: MyRegistrationExtension },
-    { provide: AUTH_USER_LIST_EXTENSION, useFactory: (r, m) => new MyUserListExtension(r, m), deps: [Router, MessageService] },
-    { provide: AUTH_USER_DETAIL_CONFIG, useValue: { viewMode: 'dialog', allowEdit: true } },
-    { provide: AUTH_PROFILE_EXTENSION, useClass: MyProfileExtension },      // User-editable fields
-    { provide: AUTH_USER_FORM_EXTENSION, useClass: MyUserFormExtension },   // Admin-editable fields
-  ];
-}
-// Usage: providers: [...provideAuthExtensions()]
+withInterceptors([
+  authInterceptor,          // Must be FIRST (attaches token)
+  tokenRefreshInterceptor,  // Must be SECOND (handles 401)
+])
 ```
 
-### additionalFields Flow
-
-When using extensions, registration data flows as:
-
-1. **Frontend:** `transformRegistrationData()` converts extra fields to `additionalFields`
-2. **Backend:** Registration stores `additionalFields` in PendingRegistration (email flow) or passes to `USER_ENRICHER.onUserCreated`
-3. **Backend:** `USER_ENRICHER.onUserCreated(userId, additionalFields, queryRunner)` creates related entities (e.g., UserProfileInfo) within the same transaction
-4. **Error handling:** If `onUserCreated` throws, the entire registration rolls back
-
 ---
 
-## Translation System (v4.0.0+)
-
-### Smart Translation Pattern with Fallback
+## Guards
 
-All text fields (labels, placeholders, headers, titles) now support intelligent translation fallback:
+| Guard | Usage | Behavior |
+|-------|-------|---------|
+| `appInitGuard` | `canActivate` | Restores session from cookie on page refresh |
+| `AuthenticatedGuard` | `canActivate` | Redirects to `/auth/login` if not authenticated |
+| `GuestGuard` | `canActivate` | Redirects to `/` if already authenticated |
+| `CompanySelectedGuard` | `canActivate` | Redirects to `/auth/select-company` if company not chosen |
 
 ```typescript
-// Interface Pattern
-interface IField {
-  label: string;           // Fallback text (always required)
-  labelKey?: string;       // Translation key (optional)
-  placeholder?: string;    // Fallback text (optional)
-  placeholderKey?: string; // Translation key (optional)
+// Route with all guards
+{
+  path: '',
+  canActivate: [appInitGuard],
+  children: [
+    {
+      path: 'dashboard',
+      canActivate: [AuthenticatedGuard, CompanySelectedGuard],
+      loadComponent: () => import('./dashboard.component'),
+    },
+  ],
 }
 ```
 
-### Message/Validation Parameter Support
+---
 
-Validation messages and custom messages now support parameter interpolation:
+## Pages
 
-```typescript
-// Interface Pattern
-interface IValidationConfig {
-  message?: string;                                      // Fallback message
-  messageKey?: string;                                   // Translation key
-  messageParam?: Record<string, string | number>;       // Interpolation params
-}
+`ng-auth` exports pre-built page components routable via `AUTH_ROUTES`:
 
-interface IField {
-  validationMessage?: string;
-  validationMessageKey?: string;
-  validationMessageParam?: Record<string, string | number>;
-}
-```
-
-**Usage Example:**
 ```typescript
-// Provider configuration
-validationConfig: {
-  message: "Password must be at least {{min}} characters",
-  messageKey: "auth.validation.password.min.length",
-  messageParam: { min: 8 }
-}
+import { AUTH_ROUTES } from '@flusys/ng-auth';
 
-// Field configuration
-{
-  label: "Company Name",
-  labelKey: "admin.company.name",
-  placeholder: "Enter company name",
-  placeholderKey: "admin.company.name.placeholder",
-  validationMessage: "Company name is required",
-  validationMessageKey: "admin.company.name.required",
-  validationMessageParam: {}
-}
+// app.routes.ts
+{ path: 'auth', loadChildren: () => AUTH_ROUTES }
 ```
 
-### safeTranslate() Method
+| Route | Component | Description |
+|-------|-----------|-------------|
+| `/auth/login` | `LoginPageComponent` | Email + password login form |
+| `/auth/register` | `RegisterPageComponent` | Self-registration form |
+| `/auth/verify-email` | `VerifyEmailPageComponent` | OTP verification |
+| `/auth/select-company` | `SelectCompanyPageComponent` | Company/branch picker |
+| `/auth/profile` | `ProfilePageComponent` | User profile editor |
 
-All form components have a protected `safeTranslate()` helper method that intelligently falls back when translations are missing:
+All pages support full i18n via `TranslatePipe`.
 
-```typescript
-/** Translate with fallback: if key returns unchanged, use fallback instead */
-safeTranslate(key: string | undefined, fallback: string): string {
-  if (!key) return fallback;
-  const translated = this.translate(key);
-  return translated === key ? fallback : translated;  // Smart fallback!
-}
-```
+---
 
-**Behavior:**
-```
-safeTranslate(undefined, "Name")
-→ Returns: "Name" (no key, use fallback)
+## Provider Adapters
 
-safeTranslate("auth.profile.name", "Name")
-→ Returns: "Nome" (translated)
+### AUTH_EMAIL_PROVIDER
 
-safeTranslate("auth.new.feature", "Name")
-→ Returns: "Name" (no translation, use fallback)
-```
+`ng-auth` requires an email adapter for verification emails. Register this in your NestJS backend (not Angular). On the Angular side, this is handled automatically by the backend.
 
-### Template Usage Patterns
+### User Enricher
 
-**Pattern 1: Simple Label**
-```html
-{{ safeTranslate(field.labelKey, field.label) }}
-```
-
-**Pattern 2: Placeholder with Default**
-```html
-{{ safeTranslate(field.placeholderKey, field.placeholder ?? '') }}
-```
+You can inject additional user data at login time:
 
-**Pattern 3: Fallback Translation Chain**
-```html
-{{ safeTranslate(field.placeholderKey, field.placeholder ?? ('shared.select' | translate)) }}
-```
+```typescript
+// Custom enricher (rare — usually not needed)
+import { USER_ENRICHER } from '@flusys/ng-auth';
 
-**Pattern 4: Complex Nested Fallback**
-```html
-{{ safeTranslate(
-  field.placeholderKey,
-  field.placeholder ?? safeTranslate(field.labelKey, field.label)
-) }}
+providers: [
+  {
+    provide: USER_ENRICHER,
+    useClass: MyUserEnricher,
+  },
+]
 ```
 
-### Components Using safeTranslate()
+---
 
-- **RegisterPageComponent** - Registration extra fields
-- **ProfilePageComponent** - User editable + admin view-only fields
-- **UserFormComponent** - Admin user form fields
-- **UserListComponent** - Custom columns and action labels
+## API Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| POST | `/auth/login` | Public | Login with email/password |
+| POST | `/auth/register` | Public | Self-registration |
+| POST | `/auth/logout` | Bearer | Logout and clear cookie |
+| POST | `/auth/refresh` | Cookie | Refresh access token |
+| GET | `/auth/me` | Bearer | Get current user |
+| POST | `/auth/select` | Session | Select company after login |
+| POST | `/auth/verify-email` | Bearer | Verify email OTP |
+| POST | `/auth/resend-verification` | Bearer | Resend OTP |
+| POST | `/auth/change-password` | Bearer | Change password |
+| POST | `/auth/update-profile` | Bearer | Update profile |
 
-### Translation File Integration
+---
 
-When translations exist, they are automatically used:
+## Configuration Reference
 
-**Translation file (en.json):**
-```json
-{
-  "auth.profile.name": "User Name",
-  "auth.phone.placeholder": "Enter phone number",
-  "admin.company.name": "Company",
-  "shared.select": "Select an option"
-}
-```
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `services.auth.enabled` | `boolean` | `false` | Enable auth module |
+| `services.auth.features.signUp` | `boolean` | `false` | Allow self-registration |
+| `services.auth.features.emailVerification` | `boolean` | `false` | Require email OTP |
+| `services.auth.features.companySelection` | `boolean` | `false` | Enable multi-company |
 
-**When key exists in translations:** Shows translated value
-**When key missing from translations:** Shows fallback text (label/placeholder/message)
-**When key undefined:** Shows fallback text directly
+---
 
-### Corner Cases Handled
+## Troubleshooting
 
-| Scenario | Result |
-|----------|--------|
-| Key undefined | Returns fallback ✅ |
-| Translation missing | Returns fallback ✅ |
-| No TRANSLATE_ADAPTER | Returns fallback ✅ |
-| Fallback is empty string | Displays empty string (valid) ✅ |
-| Parameter interpolation | Supported via messageParam ✅ |
-| Nested safeTranslate calls | Works correctly ✅ |
+**Token refresh loop (endless 401 cycle)**
 
-### Migration from v3.0.x
+This happens when the refresh endpoint itself returns 401. Ensure the refresh token cookie hasn't expired. Also verify that `tokenRefreshInterceptor` skips the `/auth/refresh` endpoint:
 
-**Removed fields** (no longer needed):
 ```typescript
-❌ labelFallback    → Use label directly
-❌ placeholderFallback → Use placeholder directly
-❌ titleFallback    → Use title directly
-❌ headerFallback   → Use header directly
-❌ messageFallback  → Use message directly
+// The interceptor automatically skips /auth/refresh to prevent loops
 ```
 
-**Removed:** `labelFallback`, `placeholderFallback`, `titleFallback`, `headerFallback`, `messageFallback`
+**`appInitGuard` redirects to login on every refresh**
 
-**Added:** `messageParam`, `validationMessageParam` for parameter interpolation
+Ensure your backend sets the refresh token cookie with `httpOnly: true`, `sameSite: 'lax'`, and the correct `domain`/`path`. The browser must send the cookie automatically with `POST /auth/refresh`.
 
-**No breaking changes:** Existing implementations still work due to smart fallback logic.
+**Company selection page shown even after selecting**
 
----
+Verify that `POST /auth/select` returns both tokens AND the company/branch data. `AuthStateService.setCompany()` must be called with the response.
 
-## See Also
+**User profile picture doesn't load**
 
-- [CORE-GUIDE.md](./CORE-GUIDE.md) - APP_CONFIG configuration
-- [SHARED-GUIDE.md](./SHARED-GUIDE.md) - Provider interfaces
-- [LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md) - Layout integration
-- [IAM-GUIDE.md](./IAM-GUIDE.md) - Permission management
-- [../FLUSYS_NEST/docs/AUTH-GUIDE.md](../../FLUSYS_NEST/docs/AUTH-GUIDE.md) - Backend auth module
+Profile pictures are fetched via `FileUrlService`, not by constructing URLs. Ensure `ng-storage` providers are registered and `services.storage.enabled: true`.
 
----
+**Login form validation errors not translated**
 
-**Last Updated:** 2026-03-03
-**Version:** 4.0.0-rc
-**Angular Version:** 21
+Provide `TRANSLATE_ADAPTER` via `provideLocalization()`. The fallback text (non-translated) is always shown if the adapter is absent.
 
-## Key Changes in v4.0.0-rc
+---
 
-- ✅ Smart translation fallback system with `safeTranslate()` helper
-- ✅ Message parameter support (`messageParam`, `validationMessageParam`)
-- ✅ Removed redundant `*Fallback` interface fields
-- ✅ All 4 form pages use safe translation pattern
-- ✅ Type-safe, TypeScript enforced
+## License
 
-All 15 components use responsive design and dark mode support. Form components use Signal Forms.
+MIT © FLUSYS