@flusys/ng-auth 2.0.0-rc.0 → 3.0.0

package/README.md

@@ -5,6 +5,7 @@
 `@flusys/ng-auth` provides complete authentication functionality including login, registration, token management, company/branch selection, user administration, and permission handling.
 
 **Package:** `@flusys/ng-auth`
+**Version:** 3.0.0
 **Dependencies:** ng-core, ng-shared, ng-layout
 **Build:** `npm run build:ng-auth`
 
@@ -27,18 +28,21 @@
 │  Guards                                                      │
 │  ├── authGuard           (requires authentication)          │
 │  ├── guestGuard          (allows only unauthenticated)      │
-│  └── companyFeatureGuard (requires company feature enabled) │
+│  ├── companyFeatureGuard (requires company feature enabled) │
+│  ├── emailFeatureGuard   (requires email service enabled)   │
+│  └── signUpFeatureGuard  (requires sign-up enabled)         │
 ├─────────────────────────────────────────────────────────────┤
 │  Interceptors                                                │
 │  ├── authInterceptor     (adds JWT + tenant headers)        │
-│  └── tokenRefreshInterceptor (handles 401 + token refresh)  │
+│  └── 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 │
+│  ├── AuthUserPermissionProviderAdapter → USER_PERMISSION_PROVIDER │
+│  └── AuthStateProviderAdapter → AUTH_STATE_PROVIDER         │
 ├─────────────────────────────────────────────────────────────┤
 │  Constants                                                   │
 │  └── AUTH_ENDPOINTS          (endpoint path definitions)    │
@@ -51,7 +55,7 @@
 
 ### AuthApiService
 
-HTTP client for authentication endpoints.
+HTTP client for authentication endpoints. Uses `getServiceUrl(appConfig, 'auth')` for base URL.
 
 ```typescript
 import { AuthApiService } from '@flusys/ng-auth';
@@ -59,26 +63,55 @@ import { AuthApiService } from '@flusys/ng-auth';
 const authApi = inject(AuthApiService);
 
 // Authentication
-authApi.login({ email, password });           // POST /auth/login
-authApi.register({ name, email, password });  // POST /auth/register
-authApi.refresh();                            // POST /auth/refresh
-authApi.logout();                             // POST /auth/logout
-authApi.me();                                 // GET /auth/me
+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
-authApi.switchCompany({ companyId, branchId });      // POST /auth/switch-company
+authApi.select({ companyId, branchId, sessionId });  // POST /auth/select → ILoginResponse
+authApi.switchCompany({ companyId, branchId });      // POST /auth/switch-company → ILoginResponse
 
 // Password management
-authApi.changePassword({ currentPassword, newPassword });
-authApi.forgotPassword({ email });
-authApi.resetPassword({ token, newPassword });
+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';
 
@@ -86,30 +119,47 @@ const authState = inject(AuthStateService);
 
 // Read-only signals
 authState.user();                    // Signal<IUserInfo | null>
-authState.accessToken();             // Signal<string | 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.availableCompanies();      // Signal<ICompanyWithBranches[]>
 authState.selectionSessionId();      // Signal<string | null>
+authState.availableCompanies();      // Signal<ICompanyWithBranches[]>
 
 // Computed signals
-authState.isAuthenticated();         // Signal<boolean>
+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 company/branch selection
+authState.setSelectionState(response); // After login requires selection
 authState.clearSelectionState();     // Clear pending selection
-authState.resetState();              // Full logout
+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();
+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:** Tokens and company/branch IDs are automatically saved to localStorage via effects.
+**Auto-persistence via effects:**
+- `tokenExpiresAt` → localStorage `tokenExpiresAt`
+- `company.id` → localStorage `selectedCompanyId`
+- `branch.id` → localStorage `selectedBranchId`
 
 ### AuthInitService
 
@@ -121,22 +171,45 @@ import { AuthInitService } from '@flusys/ng-auth';
 const authInit = inject(AuthInitService);
 
 // Signals
-authInit.initialized();  // Signal<boolean>
+authInit.initialized();  // Signal<boolean> - true after init attempt
 authInit.loading();      // Signal<boolean>
 authInit.error();        // Signal<string | null>
 
-// Restore session (called by appInitGuard)
+// Restore session (called by guards)
 authInit.initialize().subscribe({
-  next: (user) => console.log('Session restored:', user),
+  next: (success) => console.log('Session restored:', success),
   error: (err) => console.log('No session or expired')
 });
 ```
 
-**Flow:**
-1. Attempts `POST /auth/refresh` with httpOnly cookie
-2. On success, calls `GET /auth/me` to get user info
-3. Updates AuthStateService with restored session
-4. Caches result to prevent duplicate calls
+**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
 
@@ -149,32 +222,34 @@ import { UserApiService, CompanyApiService, BranchApiService } from '@flusys/ng-
 service.data();      // Signal<T[]>
 service.isLoading(); // Signal<boolean>
 service.error();     // Signal<string | null>
+service.total();     // Signal<number>
 
 // Common methods
-await service.insertAsync(data);        // Create
-await service.updateAsync(data);        // Update
-await service.deleteAsync(id);          // Delete
-await service.fetchByIdAsync(id);       // Get one
-service.fetchList(search, options);     // Get list with pagination
+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
-userApi.verifyEmail(userId);
-userApi.verifyPhone(userId);
-userApi.updateStatus(userId, status);
-userApi.updateProfile(data);
+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
-branchApi.currentCompanyId();     // Signal for company context
-branchApi.companyBranches();      // Computed: branches filtered by company
-branchApi.setCurrentCompanyId(id);
-branchApi.insertBranch(data);     // Auto-sets companyId
-branchApi.fetchByCompany(companyId);
+const branchApi = inject(BranchApiService);
+branchApi.setCurrentCompanyId(companyId);        // Set company context
+branchApi.fetchByCompany(companyId, search);     // Fetch with company filter
 ```
 
 ### UserPermissionApiService
@@ -186,7 +261,7 @@ import { UserPermissionApiService } from '@flusys/ng-auth';
 
 const permApi = inject(UserPermissionApiService);
 
-// Company permissions
+// Company Permissions
 permApi.assignUserCompanies({
   userId: 'user-1',
   items: [
@@ -194,27 +269,25 @@ permApi.assignUserCompanies({
     { targetId: 'company-2', isAdd: false }   // Revoke
   ]
 });
-permApi.getUserCompanies(userId);             // Get user's companies
+permApi.getUserCompanies(userId);             // POST /administration/permissions/get-user-company
 permApi.assignUserToCompany(userId, companyId);   // Single assign
 permApi.revokeUserFromCompany(userId, companyId); // Single revoke
 
-// Branch permissions
+// Branch Permissions
 permApi.assignUserBranches({
   userId: 'user-1',
-  items: [
-    { targetId: 'branch-1', isAdd: true }
-  ]
+  items: [{ targetId: 'branch-1', isAdd: true }]
 });
-permApi.getUserBranches(userId);              // Get user's branches
+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`
-- `GET /administration/permissions/user-company?userId=xxx`
+- `POST /administration/permissions/get-user-company`
 - `POST /administration/permissions/user-branch/assign`
-- `GET /administration/permissions/user-branch?userId=xxx`
+- `POST /administration/permissions/get-user-branch`
 
 ---
 
@@ -235,13 +308,13 @@ import { authGuard } from '@flusys/ng-auth';
 ```
 
 **Checks:**
-1. User is authenticated
+1. User is authenticated (`isAuthenticated()`)
 2. If company feature enabled: company AND branch are selected
-3. Redirects to `/auth/login` with `returnUrl` if checks fail
+3. Redirects to `/auth/login` with `returnUrl` query param if checks fail
 
 ### guestGuard
 
-Protects auth routes (login, register) from authenticated users.
+Protects auth routes (login, register) from authenticated users. Restores session first.
 
 ```typescript
 import { guestGuard } from '@flusys/ng-auth';
@@ -254,10 +327,11 @@ import { guestGuard } from '@flusys/ng-auth';
 ```
 
 **Behavior:**
-1. Restores session via `AuthInitService.initialize()` first
-2. If authenticated AND company selected: redirects to home or returnUrl
-3. If selection pending: allows access (login handles Step 2)
-4. If not authenticated: allows access
+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
 
@@ -273,7 +347,39 @@ import { companyFeatureGuard } from '@flusys/ng-auth';
 }
 ```
 
-**Checks:** `services.auth.enabled` in APP_CONFIG. Redirects to `/` if disabled.
+**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`.
 
 ---
 
@@ -293,12 +399,16 @@ provideHttpClient(
 
 **Adds:**
 - `Authorization: Bearer {token}` if token exists
-- Tenant header if multi-tenant enabled
-- `withCredentials: true` for auth endpoints (cookie support)
+- 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 token refresh.
+Handles 401 responses and proactive token refresh.
 
 ```typescript
 import { tokenRefreshInterceptor } from '@flusys/ng-auth';
@@ -309,11 +419,20 @@ provideHttpClient(
 ```
 
 **Behavior:**
-1. Intercepts 401 Unauthorized responses
-2. Skips refresh for: `/auth/refresh`, `/auth/login`, `/auth/register`, `/auth/select`
-3. Uses `TokenRefreshStateService` to queue concurrent requests during refresh
-4. On success: updates token, retries original request
-5. On failure: logs out, shows error, redirects to login
+
+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
 
 ---
 
@@ -327,26 +446,32 @@ Centralized endpoint definitions used by interceptors.
 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.SELECT         // '/auth/select'
-AUTH_ENDPOINTS.SWITCH_COMPANY // '/auth/switch-company'
+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 matches specific endpoint
+isEndpoint(url, endpoint);         // Check if URL contains endpoint
 ```
 
 ---
 
 ## Provider Adapters
 
-ng-auth implements provider interfaces from ng-shared, enabling ng-iam and ng-storage to access auth data without direct dependencies.
+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-iam/ng-storage.
+Registers provider adapters for ng-shared interfaces (used by ng-iam, ng-storage, ng-form-builder).
 
 ```typescript
 import { provideAuthProviders } from '@flusys/ng-auth';
@@ -361,6 +486,7 @@ providers: [
 - `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()
 
@@ -379,13 +505,20 @@ providers: [
 - `LAYOUT_AUTH_STATE` → `AuthLayoutStateAdapter` (user/company/branch signals)
 - `LAYOUT_AUTH_API` → `AuthLayoutApiAdapter` (logout, switch company, etc.)
 
+**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();
-navigateLogin(withUrl?: boolean);
-switchCompany(companyId, branchId);  // Triggers page reload
-getUserCompanies();                   // User's permitted companies
-getCompanyBranches(companyId);        // User's permitted branches
+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
 ```
 
 ---
@@ -398,47 +531,66 @@ All page components follow Angular 21 best practices:
 - 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: Step 1 = credentials, Step 2 = company/branch selection (if needed)
-- Visual step indicator (when company feature enabled)
-- Email verification step (when email not verified)
+- 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
-- Responsive form layout with mobile padding
+- 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 signal forms
+- 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 validation
+- Password reset with token from query param `?token=xxx`
 - Password confirmation matching
-- Success/invalid token states
+- Three states: `form`, `success`, `invalid-token`
+- Auto-detects expired/invalid token from error message
 
 **VerifyEmailPageComponent** (`/auth/verify-email`)
-- Token verification with SSR support (TransferState)
-- Resend verification option
-- Success/failure states
+- 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
-- Update name and phone
-- Upload profile picture (requires `PROFILE_UPLOAD_PROVIDER` from ng-storage)
-- Change password section with strength indicator
-- View company/branch info (if company feature enabled)
-- View roles/actions (requires `PROFILE_PERMISSION_PROVIDER` from ng-iam)
+- Profile picture upload (requires `PROFILE_UPLOAD_PROVIDER` from ng-storage)
+- Update name and phone with Signal Forms
+- Extra fields support via AUTH_PROFILE_EXTENSION
+  - Editable fields (user can modify)
+  - View-only fields (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:**
@@ -448,30 +600,31 @@ All page components follow Angular 21 best practices:
 | `PROFILE_UPLOAD_PROVIDER` | ng-storage via `provideStorageProviders()` | Profile picture upload |
 | `PROFILE_PERMISSION_PROVIDER` | ng-iam via `provideIamProviders()` | Roles/actions display |
 
-**Graceful Degradation:**
-- If provider not registered, feature shows "not enabled" message
-- If service disabled in config, section is hidden
-- No errors thrown for missing optional providers
-
 ### Administration Pages
 
 **AdministrationPageComponent** (`/administration`)
 - Page title "Administration" with dynamic subtitle
-- Horizontal scrolling tabs (hidden scrollbar on mobile)
+- 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, Permission actions
-- `UserFormComponent` - Create/edit user with auto company/branch assignment
-- Permission dialogs for company/branch assignments
+- `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):**
@@ -550,13 +703,10 @@ import { UserBranchPermissionDialogComponent } from '@flusys/ng-auth';
 - Company dropdown shows only user's permitted companies
 - Branch list loads on company selection
 - Immediate save on toggle
-- Contextual empty messages (no permissions vs no branches)
-- Scoped to user's permitted companies
-
-**Workflow:**
-1. Dialog opens → Loads user's permitted companies via effect()
-2. User selects company → Loads branches for that company
-3. User toggles branch checkboxes → Immediately assigns/revokes
+- 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)
 
 ---
 
@@ -569,25 +719,46 @@ Public authentication routes.
 ```typescript
 import { AUTH_ROUTES } from '@flusys/ng-auth';
 
-// Routes: /auth/login, /auth/register
+// 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.
+Protected administration routes with tabbed interface.
 
 ```typescript
 import { ADMINISTRATION_ROUTES } from '@flusys/ng-auth';
 
-// Routes: /administration/users/*, /administration/company/*, /administration/branch/*
 {
   path: 'administration',
-  canActivate: [authGuard],
   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
 
 User profile page routes.
@@ -595,10 +766,8 @@ User profile page routes.
 ```typescript
 import { PROFILE_ROUTES } from '@flusys/ng-auth';
 
-// Route: /profile
 {
   path: 'profile',
-  canActivate: [authGuard],
   children: PROFILE_ROUTES
 }
 ```
@@ -627,15 +796,15 @@ export const appConfig: ApplicationConfig = {
     provideHttpClient(
       withFetch(),
       withInterceptors([
-        authInterceptor,
-        tokenRefreshInterceptor,
-        errorCatchingInterceptor
+        authInterceptor,         // First: adds token
+        tokenRefreshInterceptor, // Second: handles 401 + proactive refresh
+        errorCatchingInterceptor // Last: shows errors
       ])
     ),
     { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
     ...provideAuthLayoutIntegration(),
     ...provideAuthProviders(),
-    ...provideIamProviders(),      // Enables permissions display on profile page
+    ...provideIamProviders(),      // Enables permissions display on profile
     ...provideStorageProviders(),  // Enables profile picture upload
   ]
 };
@@ -645,7 +814,7 @@ export const appConfig: ApplicationConfig = {
 
 ```typescript
 import { Routes } from '@angular/router';
-import { authGuard, guestGuard, AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';
+import { authGuard, AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';
 
 export const routes: Routes = [
   { path: 'auth', children: AUTH_ROUTES },
@@ -668,34 +837,175 @@ export const routes: Routes = [
 ### Request DTOs
 
 ```typescript
-interface ILoginRequest { email: string; password: string; }
-interface IRegistrationRequest { name: string; email: string; password: string; phone?: string; }
-interface ISelectRequest { companyId: string; branchId?: string; sessionId: string; }
-interface ISwitchCompanyRequest { companyId: string; branchId: string; }
-interface IChangePasswordRequest { currentPassword: string; newPassword: string; }
+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>;
+}
 ```
 
 ### 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;
-  requiresSelection?: boolean;
-  sessionId?: string;
-  companies?: ICompanyWithBranches[];
-  expiresAt?: number;
+  company?: ICompanyInfo;
+  branch?: IBranchInfo;
 }
 
 interface ICompanySelectionResponse {
-  accessToken: string;
+  requiresSelection: true;
+  sessionId: string;
+  expiresAt: Date | string;
   user: IUserInfo;
-  company: ICompanyInfo;
-  branch: IBranchInfo;
+  companies: ICompanyWithBranches[];
 }
 
-interface IMeResponse extends IUserInfo {}
-interface IRefreshTokenResponse { accessToken: string; }
+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;
+}
+
+interface IRefreshTokenResponse {
+  accessToken: string;
+  refreshToken?: string;
+}
+
+type AuthResponse = ILoginResponse | ICompanySelectionResponse | ILoginRequiresEmailVerification;
 ```
 
 ### Entity DTOs
@@ -705,28 +1015,34 @@ interface IUser {
   id: string;
   name: string;
   email: string;
-  phone?: string;
-  profilePictureId?: string;
+  phone?: string | null;
+  profilePictureId?: string | null;
   isActive: boolean;
-  isEmailVerified: boolean;
-  isPhoneVerified: boolean;
-  lastLoginAt?: Date;
-  createdAt: Date;
-  updatedAt: Date;
+  emailVerified: boolean;
+  phoneVerified: boolean;
+  lastLoginAt?: Date | string | null;
+  additionalFields?: Record<string, unknown> | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+  deletedAt?: Date | string | null;
 }
 
 interface ICompany {
   id: string;
   name: string;
   slug: string;
-  logoId?: string;
-  address?: string;
-  phone?: string;
-  email?: string;
-  website?: string;
+  logoId?: string | null;
+  address?: string | null;
+  phone?: string | null;
+  email?: string | null;
+  website?: string | null;
+  serial?: number;
   isActive: boolean;
-  createdAt: Date;
-  updatedAt: Date;
+  readOnly: boolean;
+  settings?: Record<string, unknown> | null;
+  additionalFields?: Record<string, unknown> | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
 }
 
 interface IBranch {
@@ -734,26 +1050,71 @@ interface IBranch {
   name: string;
   slug: string;
   companyId: string;
-  parentId?: string;
-  logoId?: string;
-  address?: string;
-  phone?: string;
-  email?: string;
+  parentId?: string | null;
+  logoId?: string | null;
+  address?: string | null;
+  phone?: string | null;
+  email?: string | null;
+  serial?: number;
   isActive: boolean;
-  createdAt: Date;
-  updatedAt: Date;
+  readOnly: boolean;
+  additionalFields?: Record<string, unknown> | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
 }
 ```
 
 ### Permission DTOs
 
 ```typescript
-interface IPermissionItem { targetId: string; isAdd: boolean; }
-interface IAssignUserCompanyRequest { userId: string; items: IPermissionItem[]; }
-interface IAssignUserBranchRequest { userId: string; items: IPermissionItem[]; }
-interface IBatchOperationResponse { success: boolean; message: string; }
-interface IUserCompanyPermission { id: string; userId: string; companyId: string; companyName: string; companySlug: string; }
-interface IUserBranchPermission { id: string; userId: string; branchId: string; branchName: string; branchSlug: string; companyId: string; }
+interface IPermissionItem {
+  targetId: string;
+  isAdd: boolean;
+}
+
+interface IAssignUserCompanyRequest {
+  userId: string;
+  items: IPermissionItem[];
+}
+
+interface IAssignUserBranchRequest {
+  userId: string;
+  items: IPermissionItem[];
+}
+
+interface IBatchOperationResponse {
+  success: boolean;
+  message: string;
+}
+
+interface IUserCompanyPermission {
+  id: string;
+  userId: string;
+  companyId: string;
+  companyName: string;
+  companySlug: string;
+}
+
+interface IUserBranchPermission {
+  id: string;
+  userId: string;
+  branchId: string;
+  branchName: string;
+  branchSlug: string;
+  companyId: string;
+}
+
+interface IUserCompaniesResponse {
+  success: boolean;
+  message: string;
+  data: IUserCompanyPermission[];
+}
+
+interface IUserBranchesResponse {
+  success: boolean;
+  message: string;
+  data: IUserBranchPermission[];
+}
 ```
 
 ---
@@ -762,44 +1123,18 @@ interface IUserBranchPermission { id: string; userId: string; branchId: string;
 
 ### Angular 21 Component Patterns
 
-All components in ng-auth follow these patterns:
+All components follow these patterns:
 
-```typescript
-@Component({
-  selector: 'lib-example',
-  standalone: true,
-  changeDetection: ChangeDetectionStrategy.OnPush,  // Always OnPush
-  imports: [AngularModule, PrimeModule, FormField],
-  template: `...`
-})
-export class ExampleComponent {
-  // Dependency injection via inject()
-  private readonly service = inject(MyService);
-
-  // Signal-based state
-  readonly isLoading = signal(false);
-  readonly data = signal<IData | null>(null);
-
-  // Computed signals
-  readonly isValid = computed(() => this.data() !== null);
-
-  // Signal Forms
-  readonly formModel = signal<IFormModel>({ name: '', email: '' });
-  readonly formTree = form(this.formModel, (f) => {
-    required(f.name, { message: 'Name is required' });
-  });
-
-  // Error handling with proper typing
-  async onSubmit(): Promise<void> {
-    try {
-      // ...
-    } catch (error: unknown) {
-      const err = error as { error?: { message?: string } };
-      // Handle error
-    }
-  }
-}
-```
+| Pattern | Implementation |
+|---------|---------------|
+| Change Detection | `ChangeDetectionStrategy.OnPush` |
+| 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
 
@@ -842,7 +1177,11 @@ projects/ng-auth/
 ├── services/
 ├── guards/
 ├── interceptors/
-└── adapters/
+├── adapters/
+├── providers/
+├── interfaces/
+├── constants/
+└── routes/
 ```
 
 **Rule:** Dialog components go in `components/`, page components go in `pages/`.
@@ -862,9 +1201,13 @@ const allCompanies = await companyApi.fetchList(); // Security risk
 
 ### Token Management
 
-- Use httpOnly cookies for refresh tokens (backend)
-- Access tokens stored in memory via AuthStateService
-- TokenRefreshInterceptor handles automatic refresh
+- 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
@@ -874,211 +1217,196 @@ Avoid `any` types - use explicit interfaces:
 ```typescript
 // ✅ CORRECT - Explicit response type
 .subscribe({
-  next: (result: { message?: string }) => {
-    this.messageService.add({
-      severity: 'success',
-      detail: result.message,
-    });
+  next: (response: { success: boolean; data: IUser }) => {
+    if (response.success) { ... }
   },
 });
 
 // ❌ WRONG - Using any
 .subscribe({
-  next: (result: any) => { ... },
+  next: (response: any) => { ... },
 });
 ```
 
 ### Multi-Company Flow
 
-1. Login → Check if `requiresSelection: true`
-2. If yes → Show Step 2 (company/branch selection)
-3. Auto-select if only one company/branch
-4. Save selection → Navigate to dashboard
+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
 
-### Guards Not Working
+| 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 |
 
-**Problem:** Routes accessible without authentication.
+---
 
-**Solution:** Ensure authGuard is on parent route and session is restored:
-```typescript
-{
-  path: '',
-  canActivate: [authGuard],  // Parent guard
-  children: [...]
-}
-```
+## No-IAM Mode (Bypassing Permission Guards)
 
-### Token Not Sent
+When not using `@flusys/ng-iam`, routes with `permissionGuard` will fail (no permissions loaded).
 
-**Problem:** 401 on all requests.
+**Solution:** Set wildcard permissions after login:
 
-**Solution:** Ensure interceptor order is correct:
 ```typescript
-withInterceptors([
-  authInterceptor,         // First: adds token
-  tokenRefreshInterceptor, // Second: handles 401
-  errorCatchingInterceptor // Last: shows errors
-])
-```
+// Option 1: In login flow (recommended)
+this.permissionValidator.setPermissions(['*']);
 
-### Layout Not Showing User
+// Option 2: In APP_INITIALIZER
+{ provide: APP_INITIALIZER, useFactory: (pv: PermissionValidatorService) => () => pv.setPermissions(['*']), deps: [PermissionValidatorService], multi: true }
+```
 
-**Problem:** User info missing from topbar.
+| Pattern | Meaning |
+|---------|---------|
+| `*` | Full access to everything |
+| `user.*` | All user permissions |
+| `branch.*` | All branch permissions |
 
-**Solution:** Ensure layout integration is provided:
-```typescript
-providers: [
-  ...provideAuthLayoutIntegration()
-]
-```
+---
 
-### Company Switcher Shows All Companies
+## Extension System
 
-**Problem:** Switcher shows companies user doesn't have access to.
+ng-auth provides injection tokens for extending registration, user list, and profile without modifying the core package.
 
-**Solution:** `AuthLayoutApiAdapter.getUserCompanies()` uses `UserPermissionApiService.getUserCompanies(userId)` internally - ensure user has company permissions assigned.
+### Extension Injection Tokens
 
----
+```typescript
+import {
+  AUTH_VALIDATION_CONFIG,
+  AUTH_REGISTRATION_EXTENSION,
+  AUTH_USER_LIST_EXTENSION,
+  AUTH_USER_DETAIL_CONFIG,
+  AUTH_PROFILE_EXTENSION,
+} from '@flusys/ng-auth';
+```
 
-## No-IAM Mode (Bypassing Permission Guards)
+### AUTH_VALIDATION_CONFIG
 
-When you don't use the `@flusys/ng-iam` module but your routes use `permissionGuard`, the guard will fail because no permissions are loaded.
+Customize email and password validation.
 
-**Solution:** Set wildcard permissions in `PermissionValidatorService` after login.
+| 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 |
 
-### How Permission Guard Works
+```typescript
+{ provide: AUTH_VALIDATION_CONFIG, useValue: { password: { minLength: 8, requireUppercase: true } } }
 
-```
-Route with permissionGuard('user.view')
-    ↓
-permissionGuard() → inject(PermissionValidatorService)
-    ↓
-permissionValidator.isPermissionsLoaded() → false
-    ↓
-Redirect to '/' ❌
+// Helper functions
+import { validatePassword, validateEmail } from '@flusys/ng-auth';
 ```
 
-### Fix: Set Wildcard Permissions After Login
+### AUTH_REGISTRATION_EXTENSION
 
-#### Option 1: In Login Flow (Recommended)
+Add extra fields to registration form.
 
-Update your login handling to set permissions after successful authentication:
+**IRegistrationExtraField:** `key`, `label`, `type` (text|number|select|checkbox|textarea|date|template), `placeholder?`, `required?`, `defaultValue?`, `options?`, `pattern?`, `validationMessage?`, `order?`, `containerClass?`, `template?`, `component?`
+
+**IRegistrationExtensionProvider Methods:**
+
+| 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 |
 
 ```typescript
-// login.component.ts or auth.service.ts
-import { PermissionValidatorService } from '@flusys/ng-shared';
+{ provide: AUTH_REGISTRATION_EXTENSION, useClass: MyExtension }
+// Custom component: inject(REGISTRATION_FIELD_CONTEXT) for field, value, updateValue()
+```
 
-@Component({ ... })
-export class LoginComponent {
-  private readonly permissionValidator = inject(PermissionValidatorService);
-  private readonly authApi = inject(AuthApiService);
-  private readonly authState = inject(AuthStateService);
+### AUTH_USER_LIST_EXTENSION
 
-  async onLogin(): Promise<void> {
-    const response = await firstValueFrom(this.authApi.login(credentials));
-    this.authState.setLoginState(response);
+Add extra columns and actions to user list.
 
-    // When IAM is NOT used, grant all permissions via wildcard
-    this.permissionValidator.setPermissions(['*']);
+**IUserListExtraColumn:** `key`, `header`, `field?` (dot notation: `additionalFields.employeeId`), `template?`, `styleClass?`, `width?`, `sortable?`, `order?`
 
-    // Navigate to dashboard
-    this.router.navigate(['/dashboard']);
-  }
-}
-```
+**IUserListExtraAction:** `key`, `label`, `icon`, `severity?`, `permission?`, `onClick(user)`, `isVisible?(user)`, `isDisabled?(user)`, `order?`
 
-#### Option 2: In APP_INITIALIZER
+**IUserListExtensionProvider Methods:**
 
-Set permissions at app startup:
+| Method | Purpose |
+|--------|---------|
+| `getExtraColumns()` | Return column definitions |
+| `getExtraActions()` | Return action button definitions |
+| `enrichUserData?(users)` | Transform user data (usually handled by backend enricher) |
 
 ```typescript
-// app.config.ts
-import { APP_INITIALIZER } from '@angular/core';
-import { PermissionValidatorService } from '@flusys/ng-shared';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    {
-      provide: APP_INITIALIZER,
-      useFactory: (permissionValidator: PermissionValidatorService) => {
-        return () => {
-          // Set wildcard permissions when IAM is disabled
-          permissionValidator.setPermissions(['*']);
-        };
-      },
-      deps: [PermissionValidatorService],
-      multi: true,
-    },
-    // ... other providers
-  ],
-};
+{ provide: AUTH_USER_LIST_EXTENSION, useFactory: (router, msg) => new MyExtension(router, msg), deps: [Router, MessageService] }
 ```
 
-#### Option 3: In AuthInitService (After Session Restore)
+### AUTH_USER_DETAIL_CONFIG
 
-If you restore sessions on page refresh, set permissions there:
+Configure user detail view mode.
+
+**IUserDetailViewConfig:** `viewMode` (dialog|sidebar|page), `allowEdit?`, `width?`, `component?`, `tabs?` (array: key, label, icon?, component?, template?)
 
 ```typescript
-// After successful /auth/me response
-authInit.initialize().subscribe({
-  next: (user) => {
-    // Session restored, set wildcard permissions
-    permissionValidator.setPermissions(['*']);
-  },
-});
+{ provide: AUTH_USER_DETAIL_CONFIG, useValue: { viewMode: 'dialog', allowEdit: true, width: '800px' } }
 ```
 
-### Wildcard Permission Syntax
+### AUTH_PROFILE_EXTENSION
 
-The `permissionGuard` utilities support these patterns:
+Add extra fields and sections to profile page.
 
-| Pattern | Meaning |
-|---------|---------|
-| `*` | Full access to everything |
-| `user.*` | All user permissions |
-| `branch.*` | All branch permissions |
+**IProfileExtraField:** `key`, `label`, `type` (text|number|select|checkbox|textarea|date|template), `placeholder?`, `editable?` (false=view-only), `required?`, `options?`, `pattern?`, `validationMessage?`, `order?`, `sectionKey?`, `template?`, `component?`, `injector?`
+
+**IProfileExtraSection:** `key`, `title`, `icon?`, `order?`, `component?`, `template?`, `collapsible?`, `collapsed?`, `editPermission?`
 
-### For Jest Tests
+**IProfileExtensionProvider Methods:**
 
-Mock `PermissionValidatorService` in your test setup:
+| Method | Purpose |
+|--------|---------|
+| `getExtraFields?()` | Return field definitions |
+| `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 |
 
 ```typescript
-import { PermissionValidatorService } from '@flusys/ng-shared';
-
-describe('MyComponent', () => {
-  beforeEach(async () => {
-    await TestBed.configureTestingModule({
-      imports: [MyComponent],
-      providers: [
-        {
-          provide: PermissionValidatorService,
-          useValue: {
-            permissions: () => ['*'],
-            isPermissionsLoaded: () => true,
-            hasPermission: () => true,
-            setPermissions: jest.fn(),
-            clearPermissions: jest.fn(),
-          },
-        },
-      ],
-    }).compileComponents();
-  });
-});
+{ provide: AUTH_PROFILE_EXTENSION, useClass: MyProfileExtension }
+// Custom component: inject(PROFILE_FIELD_CONTEXT) for field, value, updateValue()
 ```
 
-### For Template Permission Checks
+### Provider Factory Example
 
-If using `*hasPermission` directive, it will also respect wildcard:
+Combine all extensions in a single provider function for app.config.ts:
 
-```html
-<!-- This will show when permissions include '*' -->
-<button *hasPermission="'user.delete'">Delete User</button>
+```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 },
+  ];
+}
+// Usage: providers: [...provideAuthExtensions()]
 ```
 
+### 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
+
 ---
 
 ## See Also
@@ -1091,25 +1419,8 @@ If using `*hasPermission` directive, it will also respect wildcard:
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25
+**Version:** 3.0.0
 **Angular Version:** 21
 
-## Component Checklist
-
-| Component | OnPush | Signal Forms | Responsive | Dark Mode |
-|-----------|--------|--------------|------------|-----------|
-| LoginPageComponent | ✅ | ✅ | ✅ | ✅ |
-| RegisterPageComponent | ✅ | ✅ | ✅ | ✅ |
-| ForgotPasswordPageComponent | ✅ | ✅ | ✅ | ✅ |
-| ResetPasswordPageComponent | ✅ | ✅ | ✅ | ✅ |
-| VerifyEmailPageComponent | ✅ | ✅ | ✅ | ✅ |
-| ProfilePageComponent | ✅ | ✅ | ✅ | ✅ |
-| AdministrationPageComponent | ✅ | N/A | ✅ | ✅ |
-| UserListComponent | ✅ | N/A | ✅ | ✅ |
-| UserFormComponent | ✅ | ✅ | ✅ | ✅ |
-| CompanyListComponent | ✅ | N/A | ✅ | ✅ |
-| CompanyFormComponent | ✅ | ✅ | ✅ | ✅ |
-| BranchListComponent | ✅ | N/A | ✅ | ✅ |
-| BranchFormComponent | ✅ | ✅ | ✅ | ✅ |
-| UserCompanyPermissionDialogComponent | ✅ | N/A | ✅ | ✅ |
-| UserBranchPermissionDialogComponent | ✅ | N/A | ✅ | ✅ |
+All 15 components use `ChangeDetectionStrategy.OnPush`, responsive design, and dark mode support. Form components use Signal Forms.