@flusys/ng-auth 4.1.1 → 5.0.0

package/README.md

@@ -1,67 +1,9 @@
 # @flusys/ng-auth
 
-> Complete authentication library for the FLUSYS Angular platform — JWT session management, HTTP-only cookie tokens, multi-company selection, and provider adapter registration.
+JWT authentication library for FLUSYS Angular apps — login, session restore, token refresh, multi-company selection, and provider adapter registration.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/ng-auth.svg)](https://www.npmjs.com/package/@flusys/ng-auth)
-[![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.io)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Module Registration](#module-registration)
-- [Session Restoration Flow](#session-restoration-flow)
-- [Auth State Service](#auth-state-service)
-- [Auth API Service](#auth-api-service)
-- [HTTP Interceptors](#http-interceptors)
-- [Guards](#guards)
-- [Pages](#pages)
-- [Provider Adapters](#provider-adapters)
-- [API Endpoints](#api-endpoints)
-- [Configuration Reference](#configuration-reference)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/ng-auth` provides end-to-end authentication for FLUSYS Angular applications. It handles the complete lifecycle: login, registration, token refresh, session restoration on page reload, email verification, profile management, password changes, and multi-company selection.
-
-Tokens are stored in **HTTP-only cookies** (managed by the backend) — never in localStorage. The access token is held in memory only and automatically refreshed via a silent refresh interceptor.
-
----
-
-## Features
-
-- ✅ JWT authentication with HTTP-only refresh token cookies
-- ✅ Silent token refresh on 401 responses
-- ✅ Session restoration on page reload (`AuthInitService`)
-- ✅ Multi-company selection flow
-- ✅ Email verification with OTP
-- ✅ Profile management (name, password, avatar)
-- ✅ `AuthStateService` — signal-based reactive auth state
-- ✅ `provideAuthProviders()` — registers `USER_PROVIDER`, `COMPANY_PROVIDER`
-- ✅ `provideAuthLayoutIntegration()` — bridges auth to layout
-- ✅ Guard: `appInitGuard` for session restoration before navigation
-- ✅ Guard: `AuthenticatedGuard`, `GuestGuard`, `CompanySelectedGuard`
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| Angular | 21+ |
-| @flusys/ng-core | 4.x |
-| @flusys/ng-shared | 4.x |
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
@@ -71,406 +13,140 @@ Tokens are stored in **HTTP-only cookies** (managed by the backend) — never in
 npm install @flusys/ng-auth @flusys/ng-core @flusys/ng-shared
 ```
 
----
-
-## Quick Start
-
-### 1. Register Auth Providers
+## 1. Register Providers
 
 ```typescript
 // app.config.ts
-import { ApplicationConfig } from '@angular/core';
 import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { APP_CONFIG } from '@flusys/ng-core';
-import {
-  provideAuthProviders,
-  provideAuthLayoutIntegration,
-  authInterceptor,
-  tokenRefreshInterceptor,
-} from '@flusys/ng-auth';
-import { environment } from './environments/environment';
+import { provideAuthProviders, provideAuthLayoutIntegration, authInterceptor, tokenRefreshInterceptor } from '@flusys/ng-auth';
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    { provide: APP_CONFIG, useValue: environment },
     provideHttpClient(
       withInterceptors([
-        authInterceptor,          // Attaches access token to requests
-        tokenRefreshInterceptor,  // Handles 401 → refresh → retry
+        authInterceptor,           // attaches Bearer token; sends withCredentials for cookie endpoints
+        tokenRefreshInterceptor,   // proactive + reactive refresh; queues concurrent 401s
       ])
     ),
-    ...provideAuthProviders(),           // USER_PROVIDER, COMPANY_PROVIDER
-    ...provideAuthLayoutIntegration(),   // LAYOUT_AUTH_STATE, LAYOUT_AUTH_API
+    ...provideAuthProviders(),          // USER_PROVIDER, COMPANY_API_PROVIDER, USER_PERMISSION_PROVIDER, AUTH_STATE_PROVIDER
+    ...provideAuthLayoutIntegration(),  // LAYOUT_AUTH_STATE, LAYOUT_AUTH_API
   ],
 };
 ```
 
-### 2. Protect Routes with Guards
+Interceptor order matters: `authInterceptor` must come before `tokenRefreshInterceptor`.
+
+## 2. Add Routes
 
 ```typescript
 // app.routes.ts
-import { Routes } from '@angular/router';
-import { appInitGuard } from '@flusys/ng-auth';
-import { AppLayoutComponent } from '@flusys/ng-layout';
+import { AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';
 
 export const routes: Routes = [
   {
-    path: '',
-    component: AppLayoutComponent,
-    canActivate: [appInitGuard],  // Restores session on page refresh
-    children: [
-      { path: 'dashboard', loadComponent: () => import('./pages/dashboard.component') },
-    ],
+    path: 'auth',
+    loadChildren: () => AUTH_ROUTES,        // login, register, forgot-password, reset-password, verify-email
   },
   {
-    path: 'auth',
-    loadChildren: () => import('@flusys/ng-auth').then(m => m.AUTH_ROUTES),
+    path: 'administration',
+    loadChildren: () => ADMINISTRATION_ROUTES, // users, company, branch (protected by authGuard)
   },
-];
-```
-
-### 3. Enable Auth in App Config
-
-```typescript
-// environments/environment.ts
-export const environment = {
-  apiBaseUrl: 'http://localhost:2002',
-  services: {
-    auth: {
-      enabled: true,
-      features: {
-        signUp: true,
-        emailVerification: true,
-        companySelection: true,
-      },
-    },
+  {
+    path: 'profile',
+    loadChildren: () => PROFILE_ROUTES,     // profile page (protected by authGuard)
   },
-};
-```
-
----
-
-## Module Registration
-
-`ng-auth` uses function-based providers (not Angular modules):
-
-### `provideAuthProviders()`
-
-Registers auth adapters against shared provider tokens:
-
-```typescript
-...provideAuthProviders()
-
-// Provides:
-// USER_PROVIDER    → AuthStateService (IUserProvider)
-// COMPANY_PROVIDER → AuthStateService (ICompanyProvider)
+];
 ```
 
-These tokens are consumed by `ng-iam`, `ng-storage`, `ng-notification` — no direct dependency on `ng-auth`.
-
-### `provideAuthLayoutIntegration()`
-
-Bridges auth state and API to the layout:
+## 3. Protect Routes with Guards
 
 ```typescript
-...provideAuthLayoutIntegration()
-
-// Provides:
-// LAYOUT_AUTH_STATE → AuthLayoutStateAdapter (profile picture, company logo)
-// LAYOUT_AUTH_API   → AuthLayoutApiAdapter (logout, select-company actions)
-```
-
----
-
-## Session Restoration Flow
+import { authGuard, guestGuard, companyFeatureGuard } from '@flusys/ng-auth';
 
-On every page refresh, auth state is cleared from memory. The `appInitGuard` restores the session transparently:
-
-```
-Page Refresh
-     │
-     ▼
-appInitGuard runs
-     │
-     ├─ User in memory? ──YES──► Check company → Allow navigation
-     │
-     └─ NO ──► AuthInitService.initialize()
-                    │
-                    ├─ POST /auth/refresh (HTTP-only cookie) → access token
-                    ├─ GET /auth/me → user data
-                    └─ Session restored in memory
-                         │
-                         ├─ Auth enabled? → Check company selection
-                         ├─ IAM enabled? → Load permissions
-                         └─ Allow navigation
-```
-
-### Company Selection Flow
-
-```
-User logs in
-     │
-     ├─ requiresSelection: false ──► Navigate to app
-     │
-     └─ requiresSelection: true
-           │
-           ├─ sessionId + companies[] returned
-           └─ Redirect to /auth/select-company
-                    │
-                    └─ User picks company/branch
-                              │
-                              └─ POST /auth/select { sessionId, companyId, branchId }
-                                        │
-                                        └─ Tokens + company data → Navigate to app
+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'),
+  },
+];
 ```
 
----
+| 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 |
 
-## Auth State Service
+## 4. Read Auth State
 
-`AuthStateService` is the single source of truth for authentication state, powered by Angular signals.
+`AuthStateService` holds all auth state as read-only signals. The access token is memory-only (never persisted).
 
 ```typescript
 import { AuthStateService } from '@flusys/ng-auth';
 
 @Component({ ... })
 export class MyComponent {
-  private authState = inject(AuthStateService);
-
-  // Signals (read-only)
-  user = this.authState.user;                   // Signal<ICurrentUser | null>
-  company = this.authState.company;             // Signal<ICompany | null>
-  branch = this.authState.branch;               // Signal<IBranch | null>
-  isAuthenticated = this.authState.isAuthenticated; // Signal<boolean>
-  accessToken = this.authState.accessToken;     // Signal<string | null>
-
-  // Computed
-  userName = computed(() => this.authState.user()?.name ?? 'Guest');
-}
-```
-
-**AuthStateService API:**
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `user` | `Signal<ICurrentUser \| null>` | Current authenticated user |
-| `company` | `Signal<ICompany \| null>` | Selected company |
-| `branch` | `Signal<IBranch \| null>` | Selected branch |
-| `isAuthenticated` | `Signal<boolean>` | True if user is logged in |
-| `accessToken` | `Signal<string \| null>` | In-memory JWT access token |
-| `setUser(user)` | `void` | Update user state |
-| `setTokens(tokens)` | `void` | Update access token |
-| `setCompany(company, branch)` | `void` | Update company/branch |
-| `clearAll()` | `void` | Clear all auth state (logout) |
+  private readonly authState = inject(AuthStateService);
 
----
-
-## Auth API Service
-
-`AuthApiService` handles all HTTP calls to the auth backend.
-
-```typescript
-import { AuthApiService } from '@flusys/ng-auth';
-
-@Component({ ... })
-export class LoginPageComponent {
-  private authApi = inject(AuthApiService);
-
-  login(email: string, password: string): void {
-    this.authApi.login({ email, password }).subscribe(response => {
-      if (response.requiresSelection) {
-        // Redirect to company selection
-      }
-      // Navigate to app
-    });
-  }
+  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>
 }
 ```
 
-**AuthApiService Methods:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `login(dto)` | `POST /auth/login` | Authenticate user |
-| `register(dto)` | `POST /auth/register` | Self-register |
-| `logout()` | `POST /auth/logout` | Invalidate tokens |
-| `refresh()` | `POST /auth/refresh` | Refresh access token |
-| `me()` | `GET /auth/me` | Get current user info |
-| `selectCompany(dto)` | `POST /auth/select` | Select company after login |
-| `verifyEmail(dto)` | `POST /auth/verify-email` | Verify OTP |
-| `resendVerification()` | `POST /auth/resend-verification` | Resend OTP email |
-| `changePassword(dto)` | `POST /auth/change-password` | Update password |
-| `updateProfile(dto)` | `POST /auth/update-profile` | Update name/avatar |
-
----
-
-## HTTP Interceptors
-
-### authInterceptor
-
-Attaches the in-memory access token as `Authorization: Bearer <token>` header to every outgoing request (except public endpoints).
+Key state methods:
 
 ```typescript
-provideHttpClient(
-  withInterceptors([authInterceptor])
-)
+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)
 ```
 
-### tokenRefreshInterceptor
-
-On 401 responses, automatically:
-1. Calls `POST /auth/refresh`
-2. Updates `AuthStateService` with new token
-3. Retries the original failed request
+## 6. Session Restore
 
-All concurrent 401s are queued — only one refresh call is made.
+`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
-provideHttpClient(
-  withInterceptors([tokenRefreshInterceptor])
-)
-```
-
-**Interceptor Order Matters:**
+import { AuthInitService } from '@flusys/ng-auth';
 
-```typescript
-withInterceptors([
-  authInterceptor,          // Must be FIRST (attaches token)
-  tokenRefreshInterceptor,  // Must be SECOND (handles 401)
-])
-```
-
----
-
-## Guards
-
-| Guard | Usage | Behavior |
-|-------|-------|---------|
-| `appInitGuard` | `canActivate` | Restores session from cookie on page refresh |
-| `AuthenticatedGuard` | `canActivate` | Redirects to `/auth/login` if not authenticated |
-| `GuestGuard` | `canActivate` | Redirects to `/` if already authenticated |
-| `CompanySelectedGuard` | `canActivate` | Redirects to `/auth/select-company` if company not chosen |
-
-```typescript
-// Route with all guards
-{
-  path: '',
-  canActivate: [appInitGuard],
-  children: [
-    {
-      path: 'dashboard',
-      canActivate: [AuthenticatedGuard, CompanySelectedGuard],
-      loadComponent: () => import('./dashboard.component'),
-    },
-  ],
-}
-```
-
----
-
-## Pages
-
-`ng-auth` exports pre-built page components routable via `AUTH_ROUTES`:
-
-```typescript
-import { AUTH_ROUTES } from '@flusys/ng-auth';
+const authInit = inject(AuthInitService);
 
-// app.routes.ts
-{ path: 'auth', loadChildren: () => AUTH_ROUTES }
+authInit.initialize().subscribe(isAuthenticated => {
+  // safe to read authState signals now
+});
 ```
 
-| Route | Component | Description |
-|-------|-----------|-------------|
-| `/auth/login` | `LoginPageComponent` | Email + password login form |
-| `/auth/register` | `RegisterPageComponent` | Self-registration form |
-| `/auth/verify-email` | `VerifyEmailPageComponent` | OTP verification |
-| `/auth/select-company` | `SelectCompanyPageComponent` | Company/branch picker |
-| `/auth/profile` | `ProfilePageComponent` | User profile editor |
-
-All pages support full i18n via `TranslatePipe`.
-
----
-
-## Provider Adapters
+The `initialized` signal is `true` after the first call completes (success or failure).
 
-### AUTH_EMAIL_PROVIDER
+## 7. Extend Registration / Profile (Optional)
 
-`ng-auth` requires an email adapter for verification emails. Register this in your NestJS backend (not Angular). On the Angular side, this is handled automatically by the backend.
-
-### User Enricher
-
-You can inject additional user data at login time:
+Inject custom fields and sections via extension tokens:
 
 ```typescript
-// Custom enricher (rare — usually not needed)
-import { USER_ENRICHER } from '@flusys/ng-auth';
+import { AUTH_REGISTRATION_EXTENSION, AUTH_PROFILE_EXTENSION, AUTH_USER_LIST_EXTENSION, AUTH_VALIDATION_CONFIG } from '@flusys/ng-auth';
 
 providers: [
+  { 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: USER_ENRICHER,
-    useClass: MyUserEnricher,
+    provide: AUTH_VALIDATION_CONFIG,
+    useValue: {
+      password: { minLength: 10, requireUppercase: true, requireSpecialChars: true },
+    },
   },
 ]
 ```
 
----
-
-## API Endpoints
-
-| Method | Endpoint | Auth | Description |
-|--------|----------|------|-------------|
-| POST | `/auth/login` | Public | Login with email/password |
-| POST | `/auth/register` | Public | Self-registration |
-| POST | `/auth/logout` | Bearer | Logout and clear cookie |
-| POST | `/auth/refresh` | Cookie | Refresh access token |
-| GET | `/auth/me` | Bearer | Get current user |
-| POST | `/auth/select` | Session | Select company after login |
-| POST | `/auth/verify-email` | Bearer | Verify email OTP |
-| POST | `/auth/resend-verification` | Bearer | Resend OTP |
-| POST | `/auth/change-password` | Bearer | Change password |
-| POST | `/auth/update-profile` | Bearer | Update profile |
-
----
-
-## Configuration Reference
-
-| Config Key | Type | Default | Description |
-|------------|------|---------|-------------|
-| `services.auth.enabled` | `boolean` | `false` | Enable auth module |
-| `services.auth.features.signUp` | `boolean` | `false` | Allow self-registration |
-| `services.auth.features.emailVerification` | `boolean` | `false` | Require email OTP |
-| `services.auth.features.companySelection` | `boolean` | `false` | Enable multi-company |
-
----
-
-## Troubleshooting
-
-**Token refresh loop (endless 401 cycle)**
-
-This happens when the refresh endpoint itself returns 401. Ensure the refresh token cookie hasn't expired. Also verify that `tokenRefreshInterceptor` skips the `/auth/refresh` endpoint:
-
-```typescript
-// The interceptor automatically skips /auth/refresh to prevent loops
-```
-
-**`appInitGuard` redirects to login on every refresh**
-
-Ensure your backend sets the refresh token cookie with `httpOnly: true`, `sameSite: 'lax'`, and the correct `domain`/`path`. The browser must send the cookie automatically with `POST /auth/refresh`.
-
-**Company selection page shown even after selecting**
-
-Verify that `POST /auth/select` returns both tokens AND the company/branch data. `AuthStateService.setCompany()` must be called with the response.
-
-**User profile picture doesn't load**
-
-Profile pictures are fetched via `FileUrlService`, not by constructing URLs. Ensure `ng-storage` providers are registered and `services.storage.enabled: true`.
-
-**Login form validation errors not translated**
-
-Provide `TRANSLATE_ADAPTER` via `provideLocalization()`. The fallback text (non-translated) is always shown if the adapter is absent.
-
----
-
 ## License
 
 MIT © FLUSYS