@flusys/ng-auth 1.1.0 → 1.2.0-rc.1

package/README.md

@@ -1,1158 +1,152 @@
-# @flusys/ng-auth Package Guide
+# @flusys/ng-auth
 
-## Overview
+JWT authentication library for FLUSYS Angular apps — login, session restore, token refresh, multi-company selection, and provider adapter registration.
 
-`@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:** 1.1.0
-**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 (handles 401 + token refresh)  │
-├─────────────────────────────────────────────────────────────┤
-│  Adapters (Provider Interface Pattern)                       │
-│  ├── AuthLayoutStateAdapter  → LAYOUT_AUTH_STATE            │
-│  ├── AuthLayoutApiAdapter    → LAYOUT_AUTH_API              │
-│  ├── AuthUserProviderAdapter → USER_PROVIDER                │
-│  ├── AuthCompanyApiProviderAdapter → COMPANY_API_PROVIDER   │
-│  └── AuthUserPermissionProviderAdapter → USER_PERMISSION_PROVIDER │
-├─────────────────────────────────────────────────────────────┤
-│  Constants                                                   │
-│  └── AUTH_ENDPOINTS          (endpoint path definitions)    │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Services
-
-### AuthApiService
-
-HTTP client for authentication endpoints.
-
-```typescript
-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
-
-// Company/Branch selection
-authApi.select({ companyId, branchId, sessionId });  // POST /auth/select
-authApi.switchCompany({ companyId, branchId });      // POST /auth/switch-company
-
-// Password management
-authApi.changePassword({ currentPassword, newPassword });
-authApi.forgotPassword({ email });
-authApi.resetPassword({ token, newPassword });
-```
-
-### AuthStateService
-
-Signal-based centralized auth state management with auto-persistence.
-
-```typescript
-import { AuthStateService } from '@flusys/ng-auth';
-
-const authState = inject(AuthStateService);
-
-// Read-only signals
-authState.user();                    // Signal<IUserInfo | null>
-authState.accessToken();             // Signal<string | null>
-authState.company();                 // Signal<ICompanyInfo | null>
-authState.branch();                  // Signal<IBranchInfo | null>
-authState.availableCompanies();      // Signal<ICompanyWithBranches[]>
-authState.selectionSessionId();      // Signal<string | null>
-
-// Computed signals
-authState.isAuthenticated();         // Signal<boolean>
-authState.requiresCompanySelection(); // Signal<boolean>
-authState.userName();                // Signal<string>
-authState.companyName();             // Signal<string>
-authState.branchName();              // Signal<string>
-authState.tenantId();                // Signal<string | null>
-
-// State mutations
-authState.setLoginState(response);   // After successful login
-authState.setSelectionState(response); // After company/branch selection
-authState.clearSelectionState();     // Clear pending selection
-authState.resetState();              // Full logout
-authState.navigateToLogin(returnUrl?);
-authState.navigateAfterLogin();
-```
-
-**Auto-persistence:** Tokens and company/branch IDs are automatically saved to localStorage via effects.
-
-### AuthInitService
-
-Handles session restoration on page refresh.
-
-```typescript
-import { AuthInitService } from '@flusys/ng-auth';
-
-const authInit = inject(AuthInitService);
-
-// Signals
-authInit.initialized();  // Signal<boolean>
-authInit.loading();      // Signal<boolean>
-authInit.error();        // Signal<string | null>
-
-// Restore session (called by appInitGuard)
-authInit.initialize().subscribe({
-  next: (user) => console.log('Session restored:', user),
-  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
-
-### 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>
-
-// 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
-```
-
-**UserApiService** - Endpoint: `administration/users`
-```typescript
-userApi.verifyEmail(userId);
-userApi.verifyPhone(userId);
-userApi.updateStatus(userId, status);
-userApi.updateProfile(data);
-```
-
-**CompanyApiService** - Endpoint: `administration/company`
-
-**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);
-```
-
-### 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);             // Get user's companies
-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);              // Get user's branches
-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/user-branch/assign`
-- `GET /administration/permissions/user-branch?userId=xxx`
-
----
-
-## 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
-2. If company feature enabled: company AND branch are selected
-3. Redirects to `/auth/login` with `returnUrl` if checks fail
-
-### guestGuard
-
-Protects auth routes (login, register) from authenticated users.
-
-```typescript
-import { guestGuard } from '@flusys/ng-auth';
-
-{
-  path: 'auth/login',
-  canActivate: [guestGuard],
-  loadComponent: () => import('./login.component')
-}
-```
-
-**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
-
-### 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 if multi-tenant enabled
-- `withCredentials: true` for auth endpoints (cookie support)
-
-### tokenRefreshInterceptor
-
-Handles 401 responses and token refresh.
-
-```typescript
-import { tokenRefreshInterceptor } from '@flusys/ng-auth';
-
-provideHttpClient(
-  withInterceptors([authInterceptor, tokenRefreshInterceptor, ...])
-)
-```
-
-**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
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-auth.svg)](https://www.npmjs.com/package/@flusys/ng-auth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
-## 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.SELECT         // '/auth/select'
-AUTH_ENDPOINTS.SWITCH_COMPANY // '/auth/switch-company'
-
-// Helper function
-isEndpoint(url, endpoint);     // Check if URL matches specific endpoint
-```
-
----
-
-## Provider Adapters
-
-ng-auth implements provider interfaces from ng-shared, enabling ng-iam and ng-storage to access auth data without direct dependencies.
-
-### provideAuthProviders()
-
-Registers provider adapters for ng-iam/ng-storage.
+## Installation
 
-```typescript
-import { provideAuthProviders } from '@flusys/ng-auth';
-
-// app.config.ts
-providers: [
-  ...provideAuthProviders()
-]
+```bash
+npm install @flusys/ng-auth @flusys/ng-core @flusys/ng-shared
 ```
 
-**Registers:**
-- `USER_PROVIDER` → `AuthUserProviderAdapter` (user list for ng-iam)
-- `COMPANY_API_PROVIDER` → `AuthCompanyApiProviderAdapter` (company list for ng-iam)
-- `USER_PERMISSION_PROVIDER` → `AuthUserPermissionProviderAdapter` (permission queries)
-
-### provideAuthLayoutIntegration()
-
-Bridges ng-auth to ng-layout components.
+## 1. Register Providers
 
 ```typescript
-import { provideAuthLayoutIntegration } from '@flusys/ng-auth';
-
 // app.config.ts
-providers: [
-  ...provideAuthLayoutIntegration()
-]
-```
-
-**Registers:**
-- `LAYOUT_AUTH_STATE` → `AuthLayoutStateAdapter` (user/company/branch signals)
-- `LAYOUT_AUTH_API` → `AuthLayoutApiAdapter` (logout, switch company, etc.)
-
-**AuthLayoutApiAdapter Methods:**
-```typescript
-logOut();
-navigateLogin(withUrl?: boolean);
-switchCompany(companyId, branchId);  // Triggers page reload
-getUserCompanies();                   // User's permitted companies
-getCompanyBranches(companyId);        // User's permitted branches
-```
-
----
-
-## Pages
-
-All page components follow Angular 21 best practices:
-- `ChangeDetectionStrategy.OnPush` for optimal performance
-- 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
-
-### 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)
-- Auto-selects if only one company/branch available
-- Stores returnUrl for post-login redirect
-- Responsive form layout with mobile padding
-- **Conditional UI based on config:**
-  - "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
-- Company details section (when company feature enabled)
-- **Default company/branch support:**
-  - When `defaultCompanySlug` is set: pre-fills company code field and makes it readonly
-  - When `defaultBranchSlug` is set: pre-fills branch code field and makes it readonly
-  - "Create new company" option hidden when defaults are configured
-
-**ForgotPasswordPageComponent** (`/auth/forgot-password`)
-- Email input with validation
-- Success state showing email sent confirmation
-
-**ResetPasswordPageComponent** (`/auth/reset-password`)
-- Password reset with token validation
-- Password confirmation matching
-- Success/invalid token states
-
-**VerifyEmailPageComponent** (`/auth/verify-email`)
-- Token verification with SSR support (TransferState)
-- Resend verification option
-- Success/failure states
-
-### 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)
-- Responsive two-column layout on desktop
-
-**Optional Provider Dependencies:**
-
-| Provider | Source | Feature Enabled |
-|----------|--------|-----------------|
-| `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)
-- Tabs: Users, Companies, Branches
-- Company/Branch tabs only visible when company feature enabled
-
-**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
-
-**Company Management:**
-- `CompanyListComponent` - Company CRUD with View Branches action
-- `CompanyFormComponent` - Create/edit company with auto slug generation
-
-**Branch Management:**
-- `BranchListComponent` - Branch CRUD filtered by company dropdown
-- `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
-
----
-
-## Dialog Components
-
-Both dialog components use Angular 21 patterns:
-- `ChangeDetectionStrategy.OnPush`
-- `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>();
-```
-
-**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 (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
-
----
-
-## Routes
-
-### AUTH_ROUTES
-
-Public authentication routes.
-
-```typescript
-import { AUTH_ROUTES } from '@flusys/ng-auth';
-
-// Routes: /auth/login, /auth/register
-{ path: 'auth', children: AUTH_ROUTES }
-```
-
-### ADMINISTRATION_ROUTES
-
-Protected administration routes.
-
-```typescript
-import { ADMINISTRATION_ROUTES } from '@flusys/ng-auth';
-
-// Routes: /administration/users/*, /administration/company/*, /administration/branch/*
-{
-  path: 'administration',
-  canActivate: [authGuard],
-  children: ADMINISTRATION_ROUTES
-}
-```
-
-### PROFILE_ROUTES
-
-User profile page routes.
-
-```typescript
-import { PROFILE_ROUTES } from '@flusys/ng-auth';
-
-// Route: /profile
-{
-  path: 'profile',
-  canActivate: [authGuard],
-  children: PROFILE_ROUTES
-}
-```
-
----
-
-## Setup
-
-### app.config.ts
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';
-import { APP_CONFIG, errorCatchingInterceptor } from '@flusys/ng-core';
-import {
-  authInterceptor,
-  tokenRefreshInterceptor,
-  provideAuthLayoutIntegration,
-  provideAuthProviders
-} from '@flusys/ng-auth';
-import { provideIamProviders } from '@flusys/ng-iam';
-import { provideStorageProviders } from '@flusys/ng-storage';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideAuthProviders, provideAuthLayoutIntegration, authInterceptor, tokenRefreshInterceptor } from '@flusys/ng-auth';
 
 export const appConfig: ApplicationConfig = {
   providers: [
     provideHttpClient(
-      withFetch(),
       withInterceptors([
-        authInterceptor,
-        tokenRefreshInterceptor,
-        errorCatchingInterceptor
+        authInterceptor,           // attaches Bearer token; sends withCredentials for cookie endpoints
+        tokenRefreshInterceptor,   // proactive + reactive refresh; queues concurrent 401s
       ])
     ),
-    { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
-    ...provideAuthLayoutIntegration(),
-    ...provideAuthProviders(),
-    ...provideIamProviders(),      // Enables permissions display on profile page
-    ...provideStorageProviders(),  // Enables profile picture upload
-  ]
+    ...provideAuthProviders(),          // USER_PROVIDER, COMPANY_API_PROVIDER, USER_PERMISSION_PROVIDER, AUTH_STATE_PROVIDER
+    ...provideAuthLayoutIntegration(),  // LAYOUT_AUTH_STATE, LAYOUT_AUTH_API
+  ],
 };
 ```
 
-### app.routes.ts
+Interceptor order matters: `authInterceptor` must come before `tokenRefreshInterceptor`.
+
+## 2. Add Routes
 
 ```typescript
-import { Routes } from '@angular/router';
-import { authGuard, guestGuard, AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';
+// app.routes.ts
+import { AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';
 
 export const routes: Routes = [
-  { path: 'auth', children: AUTH_ROUTES },
   {
-    path: '',
-    canActivate: [authGuard],
-    children: [
-      { path: 'dashboard', loadComponent: () => import('./dashboard.component') },
-      { path: 'administration', children: ADMINISTRATION_ROUTES },
-      { path: 'profile', children: PROFILE_ROUTES }
-    ]
-  }
+    path: 'auth',
+    loadChildren: () => AUTH_ROUTES,        // login, register, forgot-password, reset-password, verify-email
+  },
+  {
+    path: 'administration',
+    loadChildren: () => ADMINISTRATION_ROUTES, // users, company, branch (protected by authGuard)
+  },
+  {
+    path: 'profile',
+    loadChildren: () => PROFILE_ROUTES,     // profile page (protected by authGuard)
+  },
 ];
 ```
 
----
-
-## Interfaces
-
-### 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; }
-```
-
-### Response DTOs
+## 3. Protect Routes with Guards
 
 ```typescript
-interface ILoginResponse {
-  accessToken: string;
-  user: IUserInfo;
-  requiresSelection?: boolean;
-  sessionId?: string;
-  companies?: ICompanyWithBranches[];
-  expiresAt?: number;
-}
-
-interface ICompanySelectionResponse {
-  accessToken: string;
-  user: IUserInfo;
-  company: ICompanyInfo;
-  branch: IBranchInfo;
-}
-
-interface IMeResponse extends IUserInfo {}
-interface IRefreshTokenResponse { accessToken: string; }
-```
-
-### Entity DTOs
-
-```typescript
-interface IUser {
-  id: string;
-  name: string;
-  email: string;
-  phone?: string;
-  profilePictureId?: string;
-  isActive: boolean;
-  isEmailVerified: boolean;
-  isPhoneVerified: boolean;
-  lastLoginAt?: Date;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-interface ICompany {
-  id: string;
-  name: string;
-  slug: string;
-  logoId?: string;
-  address?: string;
-  phone?: string;
-  email?: string;
-  website?: string;
-  isActive: boolean;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-interface IBranch {
-  id: string;
-  name: string;
-  slug: string;
-  companyId: string;
-  parentId?: string;
-  logoId?: string;
-  address?: string;
-  phone?: string;
-  email?: string;
-  isActive: boolean;
-  createdAt: Date;
-  updatedAt: Date;
-}
-```
+import { authGuard, guestGuard, companyFeatureGuard } from '@flusys/ng-auth';
 
-### 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; }
+const routes: Routes = [
+  {
+    path: 'dashboard',
+    canActivate: [authGuard],          // redirects to /auth/login if not authenticated
+    loadComponent: () => import('./dashboard.component'),
+  },
+  {
+    path: 'auth/login',
+    canActivate: [guestGuard],         // redirects to '/' if already authenticated; restores session first
+    loadComponent: () => import('./login.component'),
+  },
+];
 ```
 
----
-
-## Best Practices
+| Guard | Exported name | Behavior |
+|---|---|---|
+| Require auth | `authGuard` | Redirects to `/auth/login`; checks company if `enableCompanyFeature` is on |
+| Require guest | `guestGuard` | Redirects to `/` (or `returnUrl`) if authenticated; calls `AuthInitService.initialize()` |
+| Require company feature | `companyFeatureGuard` | Redirects to `/` if company feature is disabled in config |
 
-### Angular 21 Component Patterns
+## 4. Read Auth State
 
-All components in ng-auth follow these patterns:
+`AuthStateService` holds all auth state as read-only signals. The access token is memory-only (never persisted).
 
 ```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);
+import { AuthStateService } from '@flusys/ng-auth';
 
-  // Signal Forms
-  readonly formModel = signal<IFormModel>({ name: '', email: '' });
-  readonly formTree = form(this.formModel, (f) => {
-    required(f.name, { message: 'Name is required' });
-  });
+@Component({ ... })
+export class MyComponent {
+  private readonly authState = inject(AuthStateService);
 
-  // Error handling with proper typing
-  async onSubmit(): Promise<void> {
-    try {
-      // ...
-    } catch (error: unknown) {
-      const err = error as { error?: { message?: string } };
-      // Handle error
-    }
-  }
+  readonly user        = this.authState.user;           // Signal<IUserInfo | null>
+  readonly company     = this.authState.company;        // Signal<ICompanyInfo | null>
+  readonly branch      = this.authState.branch;         // Signal<IBranchInfo | null>
+  readonly isAuth      = this.authState.isAuthenticated; // Signal<boolean>
+  readonly tokenExpired = this.authState.isTokenExpired; // Signal<boolean>
 }
 ```
 
-### 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">
-
-<!-- Two-column form grid -->
-<form class="grid grid-cols-1 md:grid-cols-2 gap-4">
-
-<!-- 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
-
-```
-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/
-```
-
-**Rule:** Dialog components go in `components/`, page components go in `pages/`.
-
-### Permission Filtering Pattern
-
-When building permission UI, filter by user's permitted scope:
+Key state methods:
 
 ```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
+authState.setLoginState(data);          // sets user + token + company + branch
+authState.setSelectionState(data);      // multi-company selection flow
+authState.resetState();                 // logout — clears all state + localStorage
+authState.navigateToLogin(returnUrl?);  // safe redirect (rejects external URLs)
 ```
 
-### Token Management
-
-- Use httpOnly cookies for refresh tokens (backend)
-- Access tokens stored in memory via AuthStateService
-- TokenRefreshInterceptor handles automatic refresh
-- Auto-persistence for company/branch selection
+## 6. Session Restore
 
-### Type Safety
-
-Avoid `any` types - use explicit interfaces:
+`AuthInitService.initialize()` runs `POST /auth/refresh` (HTTP-only cookie) then `POST /auth/me` to restore session in memory. It is called automatically by `guestGuard`. Call it manually if needed:
 
 ```typescript
-// ✅ CORRECT - Explicit response type
-.subscribe({
-  next: (result: { message?: string }) => {
-    this.messageService.add({
-      severity: 'success',
-      detail: result.message,
-    });
-  },
-});
+import { AuthInitService } from '@flusys/ng-auth';
+
+const authInit = inject(AuthInitService);
 
-// ❌ WRONG - Using any
-.subscribe({
-  next: (result: any) => { ... },
+authInit.initialize().subscribe(isAuthenticated => {
+  // safe to read authState signals now
 });
 ```
 
-### Multi-Company Flow
+The `initialized` signal is `true` after the first call completes (success or failure).
 
-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
+## 7. Extend Registration / Profile (Optional)
 
----
-
-## Common Issues
-
-### Guards Not Working
+Inject custom fields and sections via extension tokens:
 
-**Problem:** Routes accessible without authentication.
-
-**Solution:** Ensure authGuard is on parent route and session is restored:
 ```typescript
-{
-  path: '',
-  canActivate: [authGuard],  // Parent guard
-  children: [...]
-}
-```
-
-### Token Not Sent
-
-**Problem:** 401 on all requests.
-
-**Solution:** Ensure interceptor order is correct:
-```typescript
-withInterceptors([
-  authInterceptor,         // First: adds token
-  tokenRefreshInterceptor, // Second: handles 401
-  errorCatchingInterceptor // Last: shows errors
-])
-```
+import { AUTH_REGISTRATION_EXTENSION, AUTH_PROFILE_EXTENSION, AUTH_USER_LIST_EXTENSION, AUTH_VALIDATION_CONFIG } from '@flusys/ng-auth';
 
-### Layout Not Showing User
-
-**Problem:** User info missing from topbar.
-
-**Solution:** Ensure layout integration is provided:
-```typescript
 providers: [
-  ...provideAuthLayoutIntegration()
-]
-```
-
-### Company Switcher Shows All Companies
-
-**Problem:** Switcher shows companies user doesn't have access to.
-
-**Solution:** `AuthLayoutApiAdapter.getUserCompanies()` uses `UserPermissionApiService.getUserCompanies(userId)` internally - ensure user has company permissions assigned.
-
----
-
-## No-IAM Mode (Bypassing Permission Guards)
-
-When you don't use the `@flusys/ng-iam` module but your routes use `permissionGuard`, the guard will fail because no permissions are loaded.
-
-**Solution:** Set wildcard permissions in `PermissionValidatorService` after login.
-
-### How Permission Guard Works
-
-```
-Route with permissionGuard('user.view')
-    ↓
-permissionGuard() → inject(PermissionValidatorService)
-    ↓
-permissionValidator.isPermissionsLoaded() → false
-    ↓
-Redirect to '/' ❌
-```
-
-### Fix: Set Wildcard Permissions After Login
-
-#### Option 1: In Login Flow (Recommended)
-
-Update your login handling to set permissions after successful authentication:
-
-```typescript
-// login.component.ts or auth.service.ts
-import { PermissionValidatorService } from '@flusys/ng-shared';
-
-@Component({ ... })
-export class LoginComponent {
-  private readonly permissionValidator = inject(PermissionValidatorService);
-  private readonly authApi = inject(AuthApiService);
-  private readonly authState = inject(AuthStateService);
-
-  async onLogin(): Promise<void> {
-    const response = await firstValueFrom(this.authApi.login(credentials));
-    this.authState.setLoginState(response);
-
-    // When IAM is NOT used, grant all permissions via wildcard
-    this.permissionValidator.setPermissions(['*']);
-
-    // Navigate to dashboard
-    this.router.navigate(['/dashboard']);
-  }
-}
-```
-
-#### Option 2: In APP_INITIALIZER
-
-Set permissions at app startup:
-
-```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,
+  { provide: AUTH_REGISTRATION_EXTENSION, useClass: MyRegistrationExtension }, // extra fields on register form
+  { provide: AUTH_PROFILE_EXTENSION, useClass: MyProfileExtension },            // extra sections on profile page
+  { provide: AUTH_USER_LIST_EXTENSION, useClass: MyUserListExtension },         // extra columns/actions on user list
+  {
+    provide: AUTH_VALIDATION_CONFIG,
+    useValue: {
+      password: { minLength: 10, requireUppercase: true, requireSpecialChars: true },
     },
-    // ... other providers
-  ],
-};
-```
-
-#### Option 3: In AuthInitService (After Session Restore)
-
-If you restore sessions on page refresh, set permissions there:
-
-```typescript
-// After successful /auth/me response
-authInit.initialize().subscribe({
-  next: (user) => {
-    // Session restored, set wildcard permissions
-    permissionValidator.setPermissions(['*']);
   },
-});
-```
-
-### Wildcard Permission Syntax
-
-The `permissionGuard` utilities support these patterns:
-
-| Pattern | Meaning |
-|---------|---------|
-| `*` | Full access to everything |
-| `user.*` | All user permissions |
-| `branch.*` | All branch permissions |
-
-### For Jest Tests
-
-Mock `PermissionValidatorService` in your test setup:
-
-```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();
-  });
-});
-```
-
-### For Template Permission Checks
-
-If using `*hasPermission` directive, it will also respect wildcard:
-
-```html
-<!-- This will show when permissions include '*' -->
-<button *hasPermission="'user.delete'">Delete User</button>
+]
 ```
 
----
-
-## See Also
-
-- [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
-
----
-
-**Last Updated:** 2026-02-23
-**Version:** 1.1.0
-**Angular Version:** 21
-
-## Component Checklist
+## License
 
-| 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 | ✅ | ✅ |
+MIT © FLUSYS