@flusys/nestjs-auth 4.1.0 → 5.0.0

package/README.md

@@ -1,96 +1,9 @@
 # @flusys/nestjs-auth
 
-> Production-grade authentication and user management module for NestJS — with JWT, email verification, multi-company hierarchy, multi-tenant support, and pluggable extensibility.
+Drop-in authentication for NestJS — JWT access/refresh tokens, bcrypt passwords, multi-company hierarchy, email verification, and pluggable email + user enrichment.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/nestjs-auth.svg)](https://www.npmjs.com/package/@flusys/nestjs-auth)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Module Registration](#module-registration)
-  - [forRoot (Sync)](#forroot-sync)
-  - [forRootAsync (Factory)](#forrootasync-factory)
-  - [forRootAsync (Class)](#forrootasync-class)
-- [Configuration Reference](#configuration-reference)
-  - [Bootstrap Config](#bootstrap-config)
-  - [Runtime Config](#runtime-config)
-- [Feature Toggles](#feature-toggles)
-- [Deployment Modes](#deployment-modes)
-- [API Endpoints](#api-endpoints)
-- [Entities](#entities)
-- [Provider Interfaces (Extensibility)](#provider-interfaces-extensibility)
-  - [AUTH_EMAIL_PROVIDER](#auth_email_provider)
-  - [USER_ENRICHER](#user_enricher)
-- [Exported Services](#exported-services)
-- [Interceptors](#interceptors)
-- [Security](#security)
-- [Environment Variables](#environment-variables)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/nestjs-auth` is a complete, drop-in authentication system for NestJS applications. It supports three deployment topologies out of the box:
-
-| Mode | Description |
-|------|-------------|
-| **Single** | One database, one tenant, no company hierarchy |
-| **Multi-Company** | One database, users belong to multiple companies/branches |
-| **Multi-Tenant** | Separate database per tenant, full data isolation |
-
-All features are opt-in via bootstrap configuration — enabling or disabling them at startup time.
-
----
-
-## Features
-
-- **JWT Authentication** — Access token + refresh token pair with configurable expiration
-- **HTTP-only Cookie** — Refresh token stored in a secure, HTTP-only cookie for browser clients; body-based for mobile/API clients
-- **Email Verification** — Registration-gated email verification flow with token-based links
-- **Password Security** — bcrypt hashing with 12 salt rounds; SHA-256 hashing for stored tokens
-- **Rate Limiting** — Built-in throttle limits on login (5/min), register (3/min), and refresh (30/min)
-- **Company / Branch Hierarchy** — Optional multi-company support with branch sub-groups
-- **Company Selection Flow** — Session-based company selection when a user belongs to multiple companies
-- **User Management CRUD** — Full user administration endpoints with permission guards
-- **Profile Enrichment** — Pluggable `USER_ENRICHER` for adding roles, permissions, and multi-step profile sections
-- **Email Integration** — Pluggable `AUTH_EMAIL_PROVIDER` to send password-reset and verification emails via any provider
-- **Multi-Tenant Support** — Dynamic DataSource resolution per request for multiple databases
-- **Swagger Documentation** — All endpoints documented with `@nestjs/swagger`
-- **Passport.js + JWT Strategy** — Standard NestJS Passport integration
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| `@nestjs/core` | `^11.0.0` |
-| `@nestjs/common` | `^11.0.0` |
-| `@nestjs/jwt` | `^10.0.0` |
-| `@nestjs/passport` | `^10.0.0` |
-| `typeorm` | `^0.3.0` |
-| `passport-jwt` | `^4.0.0` |
-| `bcrypt` | `^5.0.0` |
-| Node.js | `>= 18.x` |
-| TypeScript | `>= 5.0` |
-
-**Peer dependencies (must be installed in your app):**
-
-```
-@flusys/nestjs-core  @flusys/nestjs-shared
-```
 
 ---
 
@@ -98,96 +11,107 @@ All features are opt-in via bootstrap configuration — enabling or disabling th
 
 ```bash
 npm install @flusys/nestjs-auth @flusys/nestjs-shared @flusys/nestjs-core
+npm install @nestjs/jwt @nestjs/passport passport-jwt bcrypt cookie-parser
 ```
 
-```bash
-# yarn
-yarn add @flusys/nestjs-auth @flusys/nestjs-shared @flusys/nestjs-core
-```
-
-```bash
-# pnpm
-pnpm add @flusys/nestjs-auth @flusys/nestjs-shared @flusys/nestjs-core
-```
-
----
+## 1. Module Registration
 
-## Quick Start
+### Sync (`forRoot`)
 
-Register `AuthModule` in your root `AppModule`. This minimal setup enables JWT authentication, user CRUD, and email verification in a single-database application:
+#### Mode 1: Single Database
 
 ```typescript
-import { Module } from '@nestjs/common';
 import { AuthModule } from '@flusys/nestjs-auth';
 
-@Module({
-  imports: [
-    AuthModule.forRoot({
-      global: true,
-      includeController: true,
-      bootstrapAppConfig: {
-        databaseMode: 'single',
-        enableCompanyFeature: false,
-        enableEmailVerification: true,
-      },
-      config: {
-        defaultDatabaseConfig: {
-          type: 'postgres',
-          host: process.env.DB_HOST,
-          port: Number(process.env.DB_PORT ?? 5432),
-          username: process.env.DB_USER,
-          password: process.env.DB_PASSWORD,
-          database: process.env.DB_NAME,
-        },
-        jwtSecret: process.env.JWT_SECRET,
-        jwtExpiration: '15m',
-        refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
-        refreshTokenExpiration: '7d',
-        frontendUrl: process.env.FRONTEND_URL,
-      },
-    }),
-  ],
-})
-export class AppModule {}
+AuthModule.forRoot({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: false,
+    enableEmailVerification: true,
+  },
+  config: {
+    defaultDatabaseConfig: {
+      type: 'mysql',
+      host: process.env.DB_HOST,
+      port: Number(process.env.DB_PORT ?? 3306),
+      username: process.env.DB_USER,
+      password: process.env.DB_PASSWORD,
+      database: process.env.DB_NAME,
+    },
+    jwtSecret: process.env.JWT_SECRET,
+    jwtExpiration: '15m',
+    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
+    refreshTokenExpiration: '7d',
+    // refreshTokenCookieName: 'fsn_refresh_token', // optional, this is the default
+  },
+});
 ```
 
----
+#### Mode 2: Multi-Tenant
 
-## Module Registration
+In multi-tenant mode you provide:
 
-### forRoot (Sync)
+- `tenantDefaultDatabaseConfig` — connection template applied to all tenants; individual tenants override only the fields that differ
+- `tenants` — per-tenant database config (`ITenantDatabaseConfig[]`); tenant resolved per request via `x-tenant-id` header
 
-Use when all configuration values are available synchronously (environment variables, hardcoded values):
+`defaultDatabaseConfig` is not needed — `tenantDefaultDatabaseConfig` serves as the fallback for both template building and single-datasource resolution.
 
 ```typescript
 AuthModule.forRoot({
   global: true,
   includeController: true,
   bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: false,
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
     enableEmailVerification: true,
   },
   config: {
-    defaultDatabaseConfig: { /* TypeORM DataSourceOptions */ },
+    // Default template applied to every tenant unless overridden
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: process.env.TENANT_DB_HOST,
+      port: Number(process.env.TENANT_DB_PORT ?? 3306),
+      username: process.env.TENANT_DB_USER,
+      password: process.env.TENANT_DB_PASSWORD,
+      database: process.env.TENANT_DB_NAME,
+    },
+    // Per-tenant overrides — only fields that differ from tenantDefaultDatabaseConfig
+    tenants: [
+      {
+        id: 'tenant-a',
+        name: 'Tenant A',
+        database: 'tenant_a_db',
+        enableCompanyFeature: true,
+        permissionMode: 'FULL',
+      },
+      {
+        id: 'tenant-b',
+        name: 'Tenant B',
+        host: 'tenant-b.db.example.com',
+        database: 'tenant_b_db',
+        enableCompanyFeature: false,
+        permissionMode: 'RBAC',
+      },
+    ],
     jwtSecret: process.env.JWT_SECRET,
     jwtExpiration: '15m',
     refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
     refreshTokenExpiration: '7d',
-    frontendUrl: 'http://localhost:3000',
   },
-  providers: [], // Optional: AUTH_EMAIL_PROVIDER, USER_ENRICHER, etc.
-})
+});
 ```
 
-### forRootAsync (Factory)
+### Async (`forRootAsync`)
 
-Use when configuration is loaded from an external service or config module:
+Use when config comes from `ConfigService` or another async source:
 
 ```typescript
-import { ConfigService } from '@nestjs/config';
-import { AuthModule } from '@flusys/nestjs-auth';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { AuthModule, ITenantDatabaseConfig } from '@flusys/nestjs-auth';
 
+// Single database
 AuthModule.forRootAsync({
   global: true,
   includeController: true,
@@ -196,342 +120,85 @@ AuthModule.forRootAsync({
     databaseMode: 'single',
     enableCompanyFeature: true,
     enableEmailVerification: true,
-  },
-  useFactory: (configService: ConfigService) => ({
+  },why you cannot fix it,, need to need gap bellow LAB REPORT text
+  useFactory: (cfg: ConfigService) => ({
     defaultDatabaseConfig: {
-      type: 'postgres',
-      host: configService.get('DB_HOST'),
-      port: configService.get<number>('DB_PORT'),
-      username: configService.get('DB_USER'),
-      password: configService.get('DB_PASSWORD'),
-      database: configService.get('DB_NAME'),
+      type: 'mysql',
+      host: cfg.get('DB_HOST'),
+      port: cfg.get<number>('DB_PORT'),
+      username: cfg.get('DB_USER'),
+      password: cfg.get('DB_PASSWORD'),
+      database: cfg.get('DB_NAME'),
     },
-    jwtSecret: configService.get('JWT_SECRET'),
-    jwtExpiration: configService.get('JWT_EXPIRATION', '15m'),
-    refreshTokenSecret: configService.get('REFRESH_TOKEN_SECRET'),
-    refreshTokenExpiration: configService.get('REFRESH_TOKEN_EXPIRATION', '7d'),
-    frontendUrl: configService.get('FRONTEND_URL'),
+    jwtSecret: cfg.get('JWT_SECRET'),
+    jwtExpiration: cfg.get('JWT_EXPIRATION', '15m'),
+    refreshTokenSecret: cfg.get('REFRESH_TOKEN_SECRET'),
+    refreshTokenExpiration: cfg.get('REFRESH_TOKEN_EXPIRATION', '7d'),
   }),
   inject: [ConfigService],
-  providers: [emailProviderFactory, userEnricherProvider],
-})
-```
-
-### forRootAsync (Class)
-
-Use when configuration is encapsulated in a dedicated service:
-
-```typescript
-import { AuthOptionsFactory, IAuthModuleConfig } from '@flusys/nestjs-auth';
-import { Injectable } from '@nestjs/common';
+  providers: [authEmailProvider, userEnricherProvider],
+});
 
-@Injectable()
-export class MyAuthConfigFactory implements AuthOptionsFactory {
-  createAuthOptions(): IAuthModuleConfig {
-    return {
-      jwtSecret: process.env.JWT_SECRET,
-      jwtExpiration: '15m',
-      refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
-      refreshTokenExpiration: '7d',
-    };
-  }
-  createOptions() { return this.createAuthOptions(); }
-}
-
-// In module:
+// Multi-tenant
 AuthModule.forRootAsync({
-  bootstrapAppConfig: { databaseMode: 'single', enableCompanyFeature: false },
-  useClass: MyAuthConfigFactory,
-})
-```
-
----
-
-## Configuration Reference
-
-### Bootstrap Config
-
-Bootstrap configuration is **fixed at startup** — it determines which entities, controllers, and services are registered. It cannot change at runtime.
-
-```typescript
-interface IBootstrapAppConfig {
-  /** Database topology */
-  databaseMode: 'single' | 'multi-tenant';
-
-  /** Enable company/branch hierarchy and related controllers */
-  enableCompanyFeature: boolean;
-
-  /** Enable email verification flow (default: true) */
-  enableEmailVerification?: boolean;
-}
-```
-
-### Runtime Config
-
-Runtime configuration is loaded at startup but can be sourced from environment variables, config files, or external APIs.
-
-```typescript
-interface IAuthModuleConfig {
-  /** TypeORM DataSource options for the default (or single) database */
-  defaultDatabaseConfig?: DataSourceOptions;
-
-  /** Tenant database configs (multi-tenant mode only) */
-  tenants?: Array<{ id: string; databaseConfig: DataSourceOptions }>;
-
-  /** JWT access token secret */
-  jwtSecret?: string;
-
-  /** JWT access token expiration (e.g. '15m', '1h', '7d') */
-  jwtExpiration?: string;
-
-  /** JWT refresh token secret */
-  refreshTokenSecret?: string;
-
-  /** Refresh token expiration (e.g. '7d', '30d') */
-  refreshTokenExpiration?: string;
-
-  /** HTTP-only cookie name for refresh token (default: 'fsn_refresh_token') */
-  refreshTokenCookieName?: string;
-
-  /** Frontend URL used to build email verification and password reset links */
-  frontendUrl?: string;
-}
-```
-
----
-
-## Feature Toggles
-
-All features are independently gated by `bootstrapAppConfig`:
-
-| Feature | Config Key | Default | Effect when enabled |
-|---------|-----------|---------|---------------------|
-| Company / Branch | `enableCompanyFeature: true` | `false` | Registers `Company`, `CompanyBranch`, `UserCompanyPermission` entities; adds company, branch, company-selection, and user-permission controllers |
-| Email Verification | `enableEmailVerification: true` | `true` | Registers `PendingRegistration` entity; adds email-verification controller; blocks login until email is confirmed |
-
----
-
-## Deployment Modes
-
-### Single Database (No Company)
-
-```typescript
-bootstrapAppConfig: {
-  databaseMode: 'single',
-  enableCompanyFeature: false,
-  enableEmailVerification: true,
-}
-```
-
-### Single Database + Multi-Company
-
-```typescript
-bootstrapAppConfig: {
-  databaseMode: 'single',
-  enableCompanyFeature: true,
-  enableEmailVerification: true,
-}
-```
-
-When a user belongs to multiple companies, login returns a `CompanySelectionResponseDto` instead of tokens. The client must call `/auth/select-company` with a `sessionId` to complete login.
-
-### Multi-Tenant (Separate DB per Tenant)
-
-```typescript
-bootstrapAppConfig: {
-  databaseMode: 'multi-tenant',
-  enableCompanyFeature: true,
-  enableEmailVerification: true,
-},
-config: {
-  defaultDatabaseConfig: { /* fallback/core DB */ },
-  tenants: [
-    { id: 'tenant-a', databaseConfig: { /* ... */ } },
-    { id: 'tenant-b', databaseConfig: { /* ... */ } },
-  ],
-  jwtSecret: process.env.JWT_SECRET,
-  // ...
-}
-```
-
----
-
-## API Endpoints
-
-All endpoints use **POST** (POST-only RPC design). Authentication required unless marked **Public**.
-
-### Authentication — `POST /auth/*`
-
-| Endpoint | Auth | Rate Limit | Description |
-|----------|------|-----------|-------------|
-| `POST /auth/login` | Public | 5/min | Login with email + password |
-| `POST /auth/register` | Public | 3/min | Register a new user account |
-| `POST /auth/refresh` | Public | 30/min | Refresh access token (cookie or body) |
-| `POST /auth/me` | JWT | — | Get current user info |
-| `POST /auth/logout` | JWT | — | Logout and clear refresh token cookie |
-| `POST /auth/change-password` | JWT | 5/min | Change authenticated user's password |
-
-#### Login Response Variants
-
-Login returns one of three shapes depending on configuration:
-
-```typescript
-// 1. Standard login success
-{ accessToken: string; refreshToken: string; user: IUser }
-
-// 2. Company selection required (enableCompanyFeature: true, multiple companies)
-{ requiresSelection: true; sessionId: string; expiresAt: string; user: IUser; companies: ICompany[] }
-
-// 3. Email verification required (enableEmailVerification: true, unverified account)
-{ requiresEmailVerification: true; email: string; message: string }
-```
-
-#### Refresh Token — Browser vs Mobile
-
-```
-Browser clients:  Refresh token read from HTTP-only cookie (set automatically on login).
-                  Falls back to request body if cookie is absent.
-
-Mobile / API:     Send refreshToken in request body.
-                  Set header: x-client-type: mobile  OR  x-client-type: api
+  global: true,
+  includeController: true,
+  imports: [ConfigModule],
+  bootstrapAppConfig: {
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
+    enableEmailVerification: true,
+  },
+  useFactory: (cfg: ConfigService) => ({
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: cfg.get('TENANT_DB_HOST'),
+      port: cfg.get<number>('TENANT_DB_PORT'),
+      username: cfg.get('TENANT_DB_USER'),
+      password: cfg.get('TENANT_DB_PASSWORD'),
+      database: cfg.get('TENANT_DB_NAME'),
+    },
+    tenants: cfg.get<ITenantDatabaseConfig[]>('TENANTS'),
+    jwtSecret: cfg.get('JWT_SECRET'),
+    jwtExpiration: cfg.get('JWT_EXPIRATION', '15m'),
+    refreshTokenSecret: cfg.get('REFRESH_TOKEN_SECRET'),
+    refreshTokenExpiration: cfg.get('REFRESH_TOKEN_EXPIRATION', '7d'),
+  }),
+  inject: [ConfigService],
+  providers: [authEmailProvider, userEnricherProvider],
+});
 ```
 
-### Email Verification — `POST /auth/email-verification/*`
-
-Registered when `enableEmailVerification: true`.
-
-| Endpoint | Auth | Description |
-|----------|------|-------------|
-| `POST /auth/email-verification/verify` | Public | Verify email with token from link |
-| `POST /auth/email-verification/resend` | Public | Resend verification email |
-
-### Company Selection — `POST /auth/company-selection/*`
-
-Registered when `enableCompanyFeature: true`.
-
-| Endpoint | Auth | Description |
-|----------|------|-------------|
-| `POST /auth/company-selection/select` | Public + Session | Complete login by selecting company/branch |
-
-### User Administration — `POST /administration/users/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /administration/users/insert` | `user.create` | Create a new user |
-| `POST /administration/users/insert-many` | `user.create` | Bulk create users |
-| `POST /administration/users/get-all` | `user.read` | Paginated user list |
-| `POST /administration/users/get/:id` | `user.read` | Get user by ID |
-| `POST /administration/users/update` | `user.update` | Update user fields |
-| `POST /administration/users/update-many` | `user.update` | Bulk update users |
-| `POST /administration/users/delete` | `user.delete` | Soft delete user |
-| `POST /administration/users/profile` | JWT | Update own profile |
-| `POST /administration/users/profile-sections` | `user.read` | List profile section definitions |
-| `POST /administration/users/:id/profile-extras` | `user.read` | Get user with enriched extras |
-| `POST /administration/users/:id/profile-section/:sectionId` | `user.read` | Get profile section data |
-| `POST /administration/users/:id/profile-section/:sectionId/update` | `user.update` | Update profile section |
-| `POST /administration/users/:id/profile-completion` | `user.read` | Profile completion percentage |
-| `POST /administration/users/:id/verify-email` | `user.update` | Admin: mark email as verified |
-| `POST /administration/users/:id/verify-phone` | `user.update` | Admin: mark phone as verified |
-| `POST /administration/users/:id/status` | `user.update` | Enable / disable user |
-
-### Company & Branch — `POST /companies/*`, `POST /branches/*`
-
-Registered when `enableCompanyFeature: true`.
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /companies/insert` | `company.create` | Create company |
-| `POST /companies/get-all` | `company.read` | List companies |
-| `POST /companies/get/:id` | `company.read` | Get company by ID |
-| `POST /companies/update` | `company.update` | Update company |
-| `POST /companies/delete` | `company.delete` | Delete company |
-| `POST /branches/insert` | `branch.create` | Create branch |
-| `POST /branches/get-all` | `branch.read` | List branches |
-| `POST /branches/update` | `branch.update` | Update branch |
-| `POST /branches/delete` | `branch.delete` | Delete branch |
-
-### User Permissions — `POST /administration/user-permissions/*`
-
-Registered when `enableCompanyFeature: true`.
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /administration/user-permissions/assign` | `user.update` | Assign user to company/branch |
-| `POST /administration/user-permissions/remove` | `user.update` | Remove user from company/branch |
-| `POST /administration/user-permissions/get-by-user` | `user.read` | Get all permissions for a user |
-
----
-
-## Entities
-
-### Core Entities (always registered)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `User` | `user` | User accounts. Passwords hashed with bcrypt (12 rounds) |
-| `UserToken` | `user_token` | Password-reset and email-verification tokens (SHA-256 hashed at rest) |
-
-### Email Verification Entities (`enableEmailVerification: true`)
+## 2. Entity Registration
 
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `PendingRegistration` | `pending_registration` | Holds unverified registration data until email is confirmed |
-
-### Company Feature Entities (`enableCompanyFeature: true`)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `Company` | `company` | Company with name, slug, logo, active flag |
-| `CompanyBranch` | `company_branch` | Branch within a company |
-| `UserCompanyPermission` | `user_company_permission` | User ↔ Company / Branch assignment with `PermissionType` |
-
-#### Entity Registration in TypeORM
-
-Use `AuthModule.getEntities()` to include auth entities in your `TypeOrmModule`:
+Pass auth entities to your TypeORM setup using the static helper:
 
 ```typescript
-import { AuthModule } from '@flusys/nestjs-auth';
+import { getEntitiesByConfig } from '@flusys/nestjs-auth/entities';
 
 TypeOrmModule.forRoot({
-  // ...
   entities: [
-    ...AuthModule.getEntities({ enableCompanyFeature: true, enableEmailVerification: true }),
-    // other app entities
+    ...getEntitiesByConfig({
+      enableCompanyFeature: true,
+      enableEmailVerification: false,
+    }),
   ],
-})
+});
 ```
 
----
-
-## Provider Interfaces (Extensibility)
+Keep the flags here in sync with those passed to `forRoot`/`forRootAsync`.
 
-`@flusys/nestjs-auth` is designed to be standalone — it does not import `@flusys/nestjs-email` or `@flusys/nestjs-iam`. Optional features are connected via **provider interfaces** defined in this package and implemented in your application.
+## 3. Pluggable Email — `AUTH_EMAIL_PROVIDER`
 
-### AUTH_EMAIL_PROVIDER
-
-Enables password-reset and email-verification emails without a hard dependency on any email module.
-
-**Interface:**
+Auth never imports `nestjs-email`. Connect them via a factory provider:
 
 ```typescript
-import { IAuthEmailProvider, AUTH_EMAIL_PROVIDER } from '@flusys/nestjs-auth';
-
-interface IAuthEmailProvider {
-  sendPasswordResetEmail(email: string, token: string, resetUrl: string): Promise<void>;
-  sendVerificationEmail(email: string, token: string, verifyUrl: string): Promise<void>;
-  sendWelcomeEmail?(email: string, name: string): Promise<void>; // optional
-}
-```
-
-**Implementation example (using `@flusys/nestjs-email`):**
-
-```typescript
-import { AUTH_EMAIL_PROVIDER } from '@flusys/nestjs-auth';
+import { AUTH_EMAIL_PROVIDER, IAuthEmailProvider } from '@flusys/nestjs-auth';
 import { EmailSendService } from '@flusys/nestjs-email';
 
 export const authEmailProvider = {
   provide: AUTH_EMAIL_PROVIDER,
-  useFactory: (emailSendService: EmailSendService) => ({
+  useFactory: (emailSendService: EmailSendService): IAuthEmailProvider => ({
     sendPasswordResetEmail: async (email, token, resetUrl) => {
       await emailSendService.sendTemplateEmail({
         templateSlug: 'password-reset',
@@ -546,93 +213,48 @@ export const authEmailProvider = {
         variables: { verifyUrl, token },
       });
     },
-    sendWelcomeEmail: async (email, name) => {
-      await emailSendService.sendTemplateEmail({
-        templateSlug: 'welcome',
-        to: email,
-        variables: { name },
-      });
-    },
+    // sendWelcomeEmail is optional
   }),
   inject: [EmailSendService],
 };
-```
-
-**Register in `forRootAsync`:**
 
-```typescript
-AuthModule.forRootAsync({
-  // ...
-  providers: [authEmailProvider],
-})
+// Register:
+AuthModule.forRootAsync({ ..., providers: [authEmailProvider] });
 ```
 
-When `AUTH_EMAIL_PROVIDER` is not provided, the auth module runs without email sending — registration still works but verification emails are silently skipped.
-
----
+When `AUTH_EMAIL_PROVIDER` is not provided, registration still works but emails are silently skipped.
 
-### USER_ENRICHER
+## 4. User Enrichment — `USER_ENRICHER`
 
-Allows extending the user list and profile responses with data from external modules (roles, permissions, custom profile sections) without creating circular dependencies.
+Extend user list and profile responses without creating circular imports. All methods are optional — implement only what you need.
 
-**Interface:**
+| Method | When called | Purpose |
+| --- | --- | --- |
+| `enrichListQuery` | User list query build | Add extra joins/selects to the query |
+| `enrichListItems` | After user list fetch | Attach computed data to list items |
+| `getProfileExtras` | `POST /users/get/:id` | Add roles, actions, sections to profile |
+| `updateProfileExtras` | Profile update (in tx) | Persist extra profile fields |
+| `validateProfileExtras` | Before profile update | Validate extra fields |
+| `getProfileSections` | Profile form init | Return multi-step section definitions |
+| `getProfileSectionData` | Section fetch | Return section-specific data |
+| `updateProfileSection` | Section save (in tx) | Persist section data |
+| `handleSectionFileUpload` | File upload (in tx) | Handle file attach to section |
+| `handleSectionFileDelete` | File delete (in tx) | Handle file removal from section |
+| `calculateProfileCompletion` | Profile fetch | Return 0–100 completion score |
+| `onUserCreated` | Registration (in tx) | Hook after user row created; throw to rollback |
 
 ```typescript
-import { IUserEnricher, USER_ENRICHER } from '@flusys/nestjs-auth';
-
-interface IUserEnricher {
-  // Extend the user list SQL query with extra joins/selects
-  enrichListQuery?(query: SelectQueryBuilder<User>, user: ILoggedUserInfo | null): Promise<{ extraFields: string[] }>;
-
-  // Transform user list items (add computed fields)
-  enrichListItems?(users: IUser[], user: ILoggedUserInfo | null): Promise<IEnrichedUser[]>;
-
-  // Return extra profile data (roles, actions, etc.)
-  getProfileExtras?(userId: string, user: ILoggedUserInfo): Promise<IProfileExtras>;
-
-  // Update extra profile fields inside a transaction
-  updateProfileExtras?(userId: string, extras: Record<string, any>, queryRunner: QueryRunner): Promise<void>;
-
-  // Validate extra fields before saving
-  validateProfileExtras?(userId: string, extras: Record<string, any>, user: ILoggedUserInfo): Promise<void>;
-
-  // Return multi-step profile section definitions
-  getProfileSections?(): IProfileSection[];
-
-  // Return data for a specific profile section
-  getProfileSectionData?(userId: string, sectionId: string, user: ILoggedUserInfo): Promise<IProfileSectionData>;
-
-  // Update a specific profile section inside a transaction
-  updateProfileSection?(userId: string, sectionId: string, data: Record<string, any>, queryRunner: QueryRunner): Promise<void>;
-
-  // Handle file upload for a profile section
-  handleSectionFileUpload?(userId: string, sectionId: string, field: string, fileInfo: { name: string; url: string; size: number; type: string }, queryRunner: QueryRunner): Promise<IProfileFile>;
-
-  // Handle file deletion for a profile section
-  handleSectionFileDelete?(userId: string, sectionId: string, field: string, fileId: string, queryRunner: QueryRunner): Promise<void>;
-
-  // Return profile completion percentage (0–100)
-  calculateProfileCompletion?(userId: string, user: ILoggedUserInfo): Promise<number>;
-
-  // Hook: called after user is created during registration (inside transaction — throw to rollback)
-  onUserCreated?(userId: string, additionalFields: Record<string, any> | null, queryRunner: QueryRunner): Promise<void>;
-}
-```
-
-**Implementation example (adding IAM roles to user profile):**
-
-```typescript
-import { USER_ENRICHER, IUserEnricher } from '@flusys/nestjs-auth';
-import { PermissionService } from '@flusys/nestjs-iam';
+import { USER_ENRICHER, IUserEnricher, IProfileExtras } from '@flusys/nestjs-auth';
+import { ILoggedUserInfo } from '@flusys/nestjs-shared/interfaces';
+import { Injectable, Inject } from '@nestjs/common';
 
 @Injectable()
 export class IamUserEnricher implements IUserEnricher {
-  constructor(private readonly permissionService: PermissionService) {}
+  constructor(@Inject(PermissionService) private readonly permissionService: PermissionService) {}
 
-  async getProfileExtras(userId: string, user: ILoggedUserInfo) {
+  async getProfileExtras(userId: string, user: ILoggedUserInfo): Promise<IProfileExtras> {
     const roles = await this.permissionService.getRolesForUser(userId);
-    const actions = await this.permissionService.getActionsForUser(userId);
-    return { roles, actions };
+    return { roles };
   }
 }
 
@@ -640,201 +262,11 @@ export const userEnricherProvider = {
   provide: USER_ENRICHER,
   useClass: IamUserEnricher,
 };
-```
 
-**Register in `forRootAsync`:**
-
-```typescript
-AuthModule.forRootAsync({
-  // ...
-  providers: [userEnricherProvider],
-})
+// Register:
+AuthModule.forRootAsync({ ..., providers: [userEnricherProvider] });
 ```
 
-All methods in `IUserEnricher` are optional. Implement only the hooks you need.
-
----
-
-## Exported Services
-
-These services are exported by `AuthModule` and can be injected into your application:
-
-| Service | Description |
-|---------|-------------|
-| `AuthenticationService` | Core auth logic: login, register, refresh, logout, change password |
-| `UserService` | User CRUD, profile management, enrichment hooks |
-| `CompanyService` | Company CRUD (exported when `enableCompanyFeature: true`) |
-| `BranchService` | Branch CRUD (exported when `enableCompanyFeature: true`) |
-| `UserPermissionService` | User-company-branch assignment (exported when `enableCompanyFeature: true`) |
-| `CompanySelectionSessionService` | Session management for multi-company login flow |
-| `AuthEmailService` | Wraps `AUTH_EMAIL_PROVIDER` for internal email dispatch |
-| `AuthConfigService` | Provides runtime config values (JWT secrets, cookie name, frontend URL) |
-| `AuthDataSourceProvider` | Dynamic TypeORM DataSource resolution per request |
-| `JwtStrategy` | Passport JWT strategy |
-| `JwtAuthGuard` | Guard that validates Bearer token on protected endpoints |
-
-**Usage:**
-
-```typescript
-import { AuthenticationService } from '@flusys/nestjs-auth';
-
-@Injectable()
-export class MyService {
-  constructor(
-    @Inject(AuthenticationService) private readonly authService: AuthenticationService,
-  ) {}
-
-  async validateToken(token: string) {
-    return this.authService.refreshToken(token);
-  }
-}
-```
-
-> **Note:** Always use `@Inject(ServiceClass)` explicitly. This package is distributed as an esbuild bundle where TypeScript metadata is not preserved.
-
----
-
-## Interceptors
-
-| Interceptor | Token | Description |
-|-------------|-------|-------------|
-| `SetToken` | `SetToken` | Writes the refresh token as an HTTP-only cookie on login/register responses |
-| `ClearToken` | `ClearToken` | Clears the refresh token cookie on logout |
-
-Applied automatically by the auth controllers. Export them from `AuthModule` if you need them in custom controllers.
-
----
-
-## Security
-
-### Token Strategy
-
-| Token | Storage | Hashing | Expiry |
-|-------|---------|---------|--------|
-| Access Token (JWT) | Client memory / Authorization header | JWT-signed | Short (e.g. 15m) |
-| Refresh Token | HTTP-only cookie (browser) / request body (mobile) | SHA-256 in DB | Long (e.g. 7d) |
-| Password Reset Token | Email link only | SHA-256 in DB | Short (e.g. 1h) |
-| Email Verification Token | Email link only | SHA-256 in DB | Short (e.g. 24h) |
-
-### Password Hashing
-
-bcrypt with **12 salt rounds** (OWASP recommended minimum).
-
-### Rate Limiting
-
-Built-in via `@nestjs/throttler`:
-
-| Endpoint | Limit |
-|----------|-------|
-| `POST /auth/login` | 5 requests / 60s |
-| `POST /auth/register` | 3 requests / 60s |
-| `POST /auth/change-password` | 5 requests / 60s |
-| `POST /auth/refresh` | 30 requests / 60s |
-
-### SQL Injection Protection
-
-All database queries use TypeORM parameterized statements. No raw string interpolation.
-
-### Important Notes
-
-- Never expose `jwtSecret` or `refreshTokenSecret` in version control.
-- Set `frontendUrl` correctly — it is used to construct password-reset and email-verification links sent via email.
-- In production, set `NODE_ENV=production` to enforce secure cookie flags.
-
----
-
-## Environment Variables
-
-```env
-# Database
-DB_HOST=localhost
-DB_PORT=5432
-DB_USER=postgres
-DB_PASSWORD=secret
-DB_NAME=myapp
-
-# JWT
-JWT_SECRET=change-me-in-production
-JWT_EXPIRATION=15m
-REFRESH_TOKEN_SECRET=change-me-in-production-2
-REFRESH_TOKEN_EXPIRATION=7d
-
-# Application
-FRONTEND_URL=http://localhost:3000
-PORT=3001
-```
-
----
-
-## Troubleshooting
-
-**`Cannot read properties of undefined` on service injection**
-
-You are likely missing `@Inject()` on a constructor parameter. This package is bundled with esbuild and TypeScript metadata is not preserved:
-
-```typescript
-// Wrong
-constructor(private readonly authService: AuthenticationService) {}
-
-// Correct
-constructor(@Inject(AuthenticationService) private readonly authService: AuthenticationService) {}
-```
-
----
-
-**Login returns `requiresEmailVerification: true` unexpectedly**
-
-The user registered but has not verified their email. Either:
-1. Provide `AUTH_EMAIL_PROVIDER` so the verification email is actually sent.
-2. Disable email verification: `enableEmailVerification: false`.
-3. Use the admin endpoint `POST /administration/users/:id/verify-email` to manually verify.
-
----
-
-**Login returns `requiresSelection: true` unexpectedly**
-
-The user belongs to more than one company. Your frontend must handle the `CompanySelectionResponseDto` response and call `POST /auth/company-selection/select` with the `sessionId` and chosen company/branch IDs.
-
----
-
-**`No metadata for entity` error on startup**
-
-Ensure `AuthModule.getEntities()` is called with the correct config when registering `TypeOrmModule`:
-
-```typescript
-TypeOrmModule.forRoot({
-  entities: [
-    ...AuthModule.getEntities({
-      enableCompanyFeature: true,
-      enableEmailVerification: true,
-    }),
-  ],
-})
-```
-
----
-
-**Refresh token cookie not being set**
-
-Ensure your Express app has `cookie-parser` middleware installed and registered before NestJS:
-
-```typescript
-import * as cookieParser from 'cookie-parser';
-app.use(cookieParser());
-```
-
----
-
-**Password reset / verification emails not being sent**
-
-`AUTH_EMAIL_PROVIDER` is optional. If not provided, emails are silently skipped. Implement and register the provider to enable email sending (see [AUTH_EMAIL_PROVIDER](#auth_email_provider)).
-
----
-
 ## License
 
 MIT © FLUSYS
-
----
-
-> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.