@flusys/ng-auth 1.1.1-beta → 1.2.0-rc.1

package/README.md

@@ -1,815 +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`
-**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) │
-├─────────────────────────────────────────────────────────────┤
-│  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)    │
-└─────────────────────────────────────────────────────────────┘
-```
+[![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)
 
 ---
 
-## 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
-```
+## Installation
 
-**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);
+```bash
+npm install @flusys/ng-auth @flusys/ng-core @flusys/ng-shared
 ```
 
-### UserPermissionApiService
-
-Manages user-to-company and user-to-branch permission assignments.
+## 1. Register Providers
 
 ```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:** `services.auth.enabled` in APP_CONFIG. Redirects to `/` if disabled.
-
----
-
-## 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
-
----
-
-## Constants
-
-### AUTH_ENDPOINTS
-
-Centralized endpoint definitions used by interceptors.
-
-```typescript
-import { AUTH_ENDPOINTS, isAuthEndpoint, 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 functions
-isAuthEndpoint(url);           // Check if URL is any auth endpoint
-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.
-
-```typescript
-import { provideAuthProviders } from '@flusys/ng-auth';
-
 // app.config.ts
-providers: [
-  ...provideAuthProviders()
-]
-```
-
-**Registers:**
-- `USER_PROVIDER` → `AuthUserProviderAdapter` (user list for ng-iam)
-- `COMPANY_API_PROVIDER` → `AuthCompanyApiProviderAdapter` (company list for ng-iam)
-- `USER_PERMISSION_PROVIDER` → `AuthUserPermissionProviderAdapter` (permission queries)
-
-### provideAuthLayoutIntegration()
-
-Bridges ng-auth to ng-layout components.
-
-```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
-
-### Authentication Pages
-
-**LoginPageComponent** (`/auth/login`)
-- Multi-step login: Step 1 = credentials, Step 2 = company/branch selection (if needed)
-- Visual step indicator
-- Auto-selects if only one company/branch available
-- Stores returnUrl for post-login redirect
-
-**RegisterPageComponent** (`/auth/register`)
-- User registration with optional company creation
-- Email/password validation
-- Terms acceptance
-
-### Profile Page
-
-**ProfilePageComponent** (`/profile`)
-- Update name and phone
-- Upload profile picture (requires `PROFILE_UPLOAD_PROVIDER` from ng-storage)
-- Change password
-- View company/branch info (if company feature enabled)
-- View roles/actions (requires `PROFILE_PERMISSION_PROVIDER` from ng-iam)
-
-**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`)
-- Tabbed interface: Users, Companies, Branches
-- Company/Branch tabs require company feature enabled
-
-**User Management:**
-- `UserListComponent` - LazyLoad datatable with Edit, Delete, Permission actions
-- `UserFormComponent` - Create/edit user form
-
-**Company Management:**
-- `CompanyListComponent` - Company CRUD
-- `CompanyFormComponent` - Create/edit company
-
-**Branch Management:**
-- `BranchListComponent` - Branch CRUD filtered by company
-- `BranchFormComponent` - Create/edit branch
-
----
-
-## Dialog Components
-
-### 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()" />
-  `
-})
-```
-
-**Features:**
-- Shows all companies with checkboxes
-- Pre-checks assigned companies
-- Immediate save on toggle (no Save button)
-- Toast notifications for success/error
-
-### 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:**
-- Shows only companies where user has company-level permissions
-- User selects company → branches load
-- Immediate save on toggle
-- Scoped to user's permitted companies
-
-**Workflow:**
-1. Dialog opens → Loads user's permitted companies
-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
+## 3. Protect Routes with Guards
 
 ```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; }
-```
+import { authGuard, guestGuard, companyFeatureGuard } from '@flusys/ng-auth';
 
-### Response DTOs
-
-```typescript
-interface ILoginResponse {
-  accessToken: string;
-  user: IUserInfo;
-  requiresSelection?: boolean;
-  sessionId?: string;
-  companies?: ICompanyWithBranches[];
-  expiresAt?: number;
-}
+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'),
+  },
+];
+```
 
-interface ICompanySelectionResponse {
-  accessToken: string;
-  user: IUserInfo;
-  company: ICompanyInfo;
-  branch: IBranchInfo;
-}
+| 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 |
 
-interface IMeResponse extends IUserInfo {}
-interface IRefreshTokenResponse { accessToken: string; }
-```
+## 4. Read Auth State
 
-### Entity DTOs
+`AuthStateService` holds all auth state as read-only signals. The access token is memory-only (never persisted).
 
 ```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;
-}
+import { AuthStateService } from '@flusys/ng-auth';
 
-interface ICompany {
-  id: string;
-  name: string;
-  slug: string;
-  logoId?: string;
-  address?: string;
-  phone?: string;
-  email?: string;
-  website?: string;
-  isActive: boolean;
-  createdAt: Date;
-  updatedAt: Date;
-}
+@Component({ ... })
+export class MyComponent {
+  private readonly authState = inject(AuthStateService);
 
-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;
+  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>
 }
 ```
 
-### Permission DTOs
+Key state methods:
 
 ```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; }
-```
-
----
-
-## Best Practices
-
-### 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/
-│   └── users/
-├── services/
-├── guards/
-├── interceptors/
-└── adapters/
+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)
 ```
 
-**Rule:** Dialog components go in `components/`, page components go in `pages/`.
+## 6. Session Restore
 
-### Permission Filtering Pattern
-
-When building permission UI, filter by user's permitted scope:
+`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 - Filter by user's permitted companies
-const response = await firstValueFrom(permApi.getUserCompanies(userId));
-const userCompanies = response.data;
-
-// ❌ WRONG - Don't show all companies
-const allCompanies = await companyApi.fetchList(); // Security risk
-```
-
-### Token Management
-
-- Use httpOnly cookies for refresh tokens (backend)
-- Access tokens stored in memory via AuthStateService
-- TokenRefreshInterceptor handles automatic refresh
-- Auto-persistence for company/branch selection
-
-### 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
-
----
-
-## Common Issues
-
-### Guards Not Working
+import { AuthInitService } from '@flusys/ng-auth';
 
-**Problem:** Routes accessible without authentication.
+const authInit = inject(AuthInitService);
 
-**Solution:** Ensure authGuard is on parent route and session is restored:
-```typescript
-{
-  path: '',
-  canActivate: [authGuard],  // Parent guard
-  children: [...]
-}
+authInit.initialize().subscribe(isAuthenticated => {
+  // safe to read authState signals now
+});
 ```
 
-### 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
-])
-```
+The `initialized` signal is `true` after the first call completes (success or failure).
 
-### Layout Not Showing User
+## 7. Extend Registration / Profile (Optional)
 
-**Problem:** User info missing from topbar.
+Inject custom fields and sections via extension tokens:
 
-**Solution:** Ensure layout integration is provided:
 ```typescript
+import { AUTH_REGISTRATION_EXTENSION, AUTH_PROFILE_EXTENSION, AUTH_USER_LIST_EXTENSION, AUTH_VALIDATION_CONFIG } from '@flusys/ng-auth';
+
 providers: [
-  ...provideAuthLayoutIntegration()
+  { 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 },
+    },
+  },
 ]
 ```
 
-### 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.
-
----
-
-## 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
-
----
+## License
 
-**Last Updated:** 2026-02-16
-**Angular Version:** 21
+MIT © FLUSYS