@flusys/nestjs-auth 4.0.1 → 4.1.0

package/README.md

@@ -1,27 +1,96 @@
-# Authentication Package Guide
+# @flusys/nestjs-auth
 
-> **Package:** `@flusys/nestjs-auth`
-> **Version:** 4.0.1
-> **Type:** Authentication system with JWT, email verification, multi-tenant, and company/branch support
+> Production-grade authentication and user management module for NestJS — with JWT, email verification, multi-company hierarchy, multi-tenant support, and pluggable extensibility.
+
+[![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)
-- [Configuration](#configuration)
-- [Constants](#constants)
-- [Entities](#entities)
-- [Provider Interfaces](#provider-interfaces)
-- [Services](#services)
+- [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)
-- [Login Flows](#login-flows)
-- [Email Verification Flow](#email-verification-flow)
-- [User Management](#user-management)
-- [No-IAM Mode](#no-iam-mode)
-- [JWT Strategy](#jwt-strategy)
+- [Entities](#entities)
+- [Provider Interfaces (Extensibility)](#provider-interfaces-extensibility)
+  - [AUTH_EMAIL_PROVIDER](#auth_email_provider)
+  - [USER_ENRICHER](#user_enricher)
+- [Exported Services](#exported-services)
 - [Interceptors](#interceptors)
-- [Validators](#validators)
-- [API Reference](#api-reference)
+- [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
+```
 
 ---
 
@@ -31,9 +100,21 @@
 npm install @flusys/nestjs-auth @flusys/nestjs-shared @flusys/nestjs-core
 ```
 
+```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
+```
+
+---
+
 ## Quick Start
 
-### Basic Setup (Single Database, No Company Feature)
+Register `AuthModule` in your root `AppModule`. This minimal setup enables JWT authentication, user CRUD, and email verification in a single-database application:
 
 ```typescript
 import { Module } from '@nestjs/common';
@@ -47,18 +128,22 @@ import { AuthModule } from '@flusys/nestjs-auth';
       bootstrapAppConfig: {
         databaseMode: 'single',
         enableCompanyFeature: false,
+        enableEmailVerification: true,
       },
       config: {
         defaultDatabaseConfig: {
           type: 'postgres',
-          host: 'localhost',
-          port: 5432,
-          username: 'postgres',
-          password: 'password',
-          database: 'myapp',
+          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: '1h',
+        jwtExpiration: '15m',
+        refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
+        refreshTokenExpiration: '7d',
+        frontendUrl: process.env.FRONTEND_URL,
       },
     }),
   ],
@@ -66,7 +151,13 @@ import { AuthModule } from '@flusys/nestjs-auth';
 export class AppModule {}
 ```
 
-### With Company Feature
+---
+
+## Module Registration
+
+### forRoot (Sync)
+
+Use when all configuration values are available synchronously (environment variables, hardcoded values):
 
 ```typescript
 AuthModule.forRoot({
@@ -74,355 +165,371 @@ AuthModule.forRoot({
   includeController: true,
   bootstrapAppConfig: {
     databaseMode: 'single',
-    enableCompanyFeature: true,
+    enableCompanyFeature: false,
+    enableEmailVerification: true,
   },
   config: {
-    defaultDatabaseConfig: { /* ... */ },
+    defaultDatabaseConfig: { /* TypeORM DataSourceOptions */ },
     jwtSecret: process.env.JWT_SECRET,
+    jwtExpiration: '15m',
     refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
     refreshTokenExpiration: '7d',
-    refreshTokenCookieName: 'fsn_refresh_token',
+    frontendUrl: 'http://localhost:3000',
   },
+  providers: [], // Optional: AUTH_EMAIL_PROVIDER, USER_ENRICHER, etc.
 })
 ```
 
-### Multi-Tenant Mode
+### forRootAsync (Factory)
+
+Use when configuration is loaded from an external service or config module:
 
 ```typescript
-AuthModule.forRoot({
+import { ConfigService } from '@nestjs/config';
+import { AuthModule } from '@flusys/nestjs-auth';
+
+AuthModule.forRootAsync({
   global: true,
   includeController: true,
+  imports: [ConfigModule],
   bootstrapAppConfig: {
-    databaseMode: 'multi-tenant',
+    databaseMode: 'single',
     enableCompanyFeature: true,
+    enableEmailVerification: true,
   },
-  config: {
-    tenantDefaultDatabaseConfig: {
+  useFactory: (configService: ConfigService) => ({
+    defaultDatabaseConfig: {
       type: 'postgres',
-      host: 'localhost',
-      port: 5432,
-      username: 'postgres',
-      password: 'password',
+      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'),
     },
-    tenants: [
-      { id: 'tenant1', database: 'tenant1_db', name: 'Tenant 1', isActive: true },
-      { id: 'tenant2', database: 'tenant2_db', name: 'Tenant 2', isActive: true },
-    ],
-    jwtSecret: process.env.JWT_SECRET,
-  },
+    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'),
+  }),
+  inject: [ConfigService],
+  providers: [emailProviderFactory, userEnricherProvider],
 })
 ```
 
-### With Email Provider (Password Reset, Email Verification)
+### forRootAsync (Class)
+
+Use when configuration is encapsulated in a dedicated service:
 
 ```typescript
-import { AUTH_EMAIL_PROVIDER } from '@flusys/nestjs-auth';
-import { EmailSendService } from '@flusys/nestjs-email';
+import { AuthOptionsFactory, IAuthModuleConfig } from '@flusys/nestjs-auth';
+import { Injectable } from '@nestjs/common';
 
-AuthModule.forRoot({
-  // ... config
-  providers: [
-    {
-      provide: AUTH_EMAIL_PROVIDER,
-      useFactory: (emailService: EmailSendService) => ({
-        sendPasswordResetEmail: async (email, token, resetUrl) => {
-          await emailService.sendTemplateEmail({
-            templateSlug: 'password-reset',
-            to: email,
-            variables: { resetUrl, token },
-          });
-        },
-        sendVerificationEmail: async (email, token, verifyUrl) => {
-          await emailService.sendTemplateEmail({
-            templateSlug: 'email-verification',
-            to: email,
-            variables: { verifyUrl, token },
-          });
-        },
-      }),
-      inject: [EmailSendService],
-    },
-  ],
+@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:
+AuthModule.forRootAsync({
+  bootstrapAppConfig: { databaseMode: 'single', enableCompanyFeature: false },
+  useClass: MyAuthConfigFactory,
 })
 ```
 
-## Configuration
+---
+
+## Configuration Reference
+
+### Bootstrap Config
 
-### Configuration Options
+Bootstrap configuration is **fixed at startup** — it determines which entities, controllers, and services are registered. It cannot change at runtime.
 
 ```typescript
-interface AuthModuleOptions {
-  global?: boolean;                    // Make module global
-  includeController?: boolean;         // Include default controllers
-  bootstrapAppConfig?: {
-    databaseMode: 'single' | 'multi-tenant';
-    enableCompanyFeature: boolean;
-    enableEmailVerification?: boolean; // Default: true
-  };
-  config?: {
-    defaultDatabaseConfig?: IDatabaseConfig;
-    tenantDefaultDatabaseConfig?: IDatabaseConfig;
-    tenants?: ITenantDatabaseConfig[];
-    jwtSecret?: string;
-    jwtExpiration?: string;             // Default: '1h'
-    refreshTokenSecret?: string;
-    refreshTokenExpiration?: string;    // Default: '7d'
-    refreshTokenCookieName?: string;    // Default: 'fsn_refresh_token'
-    frontendUrl?: string;               // For email links
-  };
-  providers?: Provider[];               // Additional providers (AUTH_EMAIL_PROVIDER, USER_ENRICHER)
+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;
 }
 ```
 
-**Bootstrap Configuration Flags:**
+### Runtime Config
 
-| Flag | Type | Default | Effect |
-|------|------|---------|--------|
-| `enableCompanyFeature` | `boolean` | `false` | Enables company/branch entities and APIs |
-| `enableEmailVerification` | `boolean` | `true` | When `false`: excludes `AuthEmailService`, hides email-related APIs (forgot-password, reset-password, verify-email, resend-verification), and excludes `PendingRegistration` entity from migrations |
-
-## Constants
+Runtime configuration is loaded at startup but can be sourced from environment variables, config files, or external APIs.
 
 ```typescript
-// Injection Tokens
-export const AUTH_MODULE_OPTIONS = 'AUTH_MODULE_OPTIONS';
-export const USER_ENRICHER = 'USER_ENRICHER';
+interface IAuthModuleConfig {
+  /** TypeORM DataSource options for the default (or single) database */
+  defaultDatabaseConfig?: DataSourceOptions;
 
-// Security
-export const BCRYPT_SALT_ROUNDS = 12;
+  /** Tenant database configs (multi-tenant mode only) */
+  tenants?: Array<{ id: string; databaseConfig: DataSourceOptions }>;
+
+  /** JWT access token secret */
+  jwtSecret?: string;
 
-// Cookie
-export const DEFAULT_COOKIE_NAME = 'fsn_refresh_token';
-export const MAX_COOKIE_BYTES = 3500;
+  /** JWT access token expiration (e.g. '15m', '1h', '7d') */
+  jwtExpiration?: string;
 
-// Cache Key Prefixes
-export const SESSION_CACHE_PREFIX = 'auth:session';
-export const TOKEN_REVOKED_PREFIX = 'auth:revoked';
+  /** 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;
+}
 ```
 
-## Entities
+---
 
-### Entity Groups
+## Feature Toggles
 
-The auth module organizes entities into groups based on feature flags:
+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
-// Internal entity groups (not exported directly)
-// Base entities: User, UserToken
-// Email entities: PendingRegistration
-// Company entities: Company, CompanyBranch, UserCompanyPermission
-
-// Exported interface for configuration
-export interface IAuthEntitiesConfig {
-  enableCompanyFeature?: boolean;
-  enableEmailVerification?: boolean;  // Default: true
+bootstrapAppConfig: {
+  databaseMode: 'single',
+  enableCompanyFeature: false,
+  enableEmailVerification: true,
 }
+```
 
-// Get entities based on feature flags (exported)
-export function getEntitiesByConfig(config: IAuthEntitiesConfig): any[] {
-  const { enableCompanyFeature = false, enableEmailVerification = true } = config;
+### Single Database + Multi-Company
 
-  const entities = [User, UserToken];
-  if (enableEmailVerification) entities.push(PendingRegistration);
-  if (enableCompanyFeature) entities.push(Company, CompanyBranch, UserCompanyPermission);
-  return entities;
+```typescript
+bootstrapAppConfig: {
+  databaseMode: 'single',
+  enableCompanyFeature: true,
+  enableEmailVerification: true,
 }
 ```
 
-**Usage:**
-```typescript
-import { getEntitiesByConfig } from '@flusys/nestjs-auth/entities';
+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.
 
-// Get entities for single database without company feature
-const entities = getEntitiesByConfig({ enableCompanyFeature: false });
-// Returns: [User, UserToken, PendingRegistration]
+### Multi-Tenant (Separate DB per Tenant)
 
-// Get entities with company feature, no email verification
-const entities = getEntitiesByConfig({ enableCompanyFeature: true, enableEmailVerification: false });
-// Returns: [User, UserToken, Company, CompanyBranch, UserCompanyPermission]
+```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,
+  // ...
+}
 ```
 
-**Entity Selection by Feature Flags:**
+---
 
-| enableEmailVerification | enableCompanyFeature | Entities |
-|------------------------|---------------------|----------|
-| `true` (default) | `false` | User, UserToken, PendingRegistration |
-| `true` | `true` | All entities |
-| `false` | `false` | User, UserToken only |
-| `false` | `true` | User, UserToken, Company, CompanyBranch, UserCompanyPermission |
+## API Endpoints
 
-### User Entity
+All endpoints use **POST** (POST-only RPC design). Authentication required unless marked **Public**.
 
-Extends `UserRoot` from `@flusys/nestjs-shared`:
+### Authentication — `POST /auth/*`
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `uuid` | Primary key |
-| `name` | `varchar(255)` | User's name |
-| `email` | `varchar(255)` | Unique email address |
-| `password` | `text` | Bcrypt hashed password |
-| `phone` | `varchar(255)` | Phone number |
-| `isActive` | `boolean` | Account status |
-| `emailVerified` | `boolean` | Email verification status |
-| `phoneVerified` | `boolean` | Phone verification status |
-| `profilePictureId` | `uuid` | Reference to storage file |
-| `lastLoginAt` | `timestamp` | Last login timestamp |
-| `additionalFields` | `json` | Extensible JSON fields |
-| `createdAt` | `timestamp` | Auto-generated |
-| `updatedAt` | `timestamp` | Auto-updated |
-| `deletedAt` | `timestamp` | Soft delete timestamp |
+| 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 |
 
-### UserToken Entity
+#### Login Response Variants
 
-Stores tokens for existing user actions:
+Login returns one of three shapes depending on configuration:
 
 ```typescript
-enum TokenType {
-  PASSWORD_RESET = 'password_reset',
-  EMAIL_VERIFICATION = 'email_verification',
-  EMAIL_CHANGE = 'email_change',
-}
+// 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
 ```
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `uuid` | Primary key |
-| `userId` | `uuid` | Reference to user |
-| `type` | `TokenType` | Token purpose |
-| `token` | `varchar(64)` | SHA-256 hashed token |
-| `expiresAt` | `timestamp` | Expiration time |
-| `usedAt` | `timestamp` | When token was used |
-| `metadata` | `varchar(255)` | Additional data (e.g., new email for EMAIL_CHANGE) |
-| `createdAt` | `timestamp` | Auto-generated |
-
-**Indexes:**
-- `IDX_user_token_token` - Unique on token
-- `IDX_user_token_user_type` - userId + type
-- `IDX_user_token_expires` - For cleanup queries
-
-### PendingRegistration Entity
-
-Stores registration data until email verification (prevents garbage accounts):
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `uuid` | Primary key |
-| `email` | `varchar(255)` | Unique pending email |
-| `name` | `varchar(255)` | User's name |
-| `phone` | `varchar(255)` | Phone number |
-| `passwordHash` | `text` | Pre-hashed password |
-| `token` | `varchar(64)` | SHA-256 hashed verification token |
-| `expiresAt` | `timestamp` | Expiration (24 hours) |
-| `companyData` | `json` | Company registration data |
-| `additionalFields` | `json` | Extension fields for USER_ENRICHER |
-| `createdAt` | `timestamp` | Auto-generated |
-
-**Indexes:**
-- `IDX_pending_reg_email` - Unique
-- `IDX_pending_reg_token` - Unique
-- `IDX_pending_reg_expires` - For cleanup
-
-### Company Entity (when company feature enabled)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `uuid` | Primary key |
-| `readOnly` | `boolean` | Read-only flag (default: false) |
-| `name` | `varchar(255)` | Company name (unique) |
-| `slug` | `varchar(255)` | URL-friendly identifier (unique) |
-| `logoId` | `char(36)` | Reference to storage file |
-| `address` | `text` | Company address |
-| `phone` | `varchar(50)` | Contact phone |
-| `email` | `varchar(255)` | Contact email |
-| `website` | `varchar(100)` | Company website URL |
-| `serial` | `int` | Display order |
-| `isActive` | `boolean` | Company status (default: true) |
-| `settings` | `json` | Company-specific settings |
-| `additionalFields` | `json` | Extension fields |
-| `createdAt` | `timestamp` | Auto-generated |
-| `updatedAt` | `timestamp` | Auto-updated |
-
-**Relations:**
-- `branches` - One-to-Many relation to CompanyBranch
-
-### CompanyBranch Entity
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `uuid` | Primary key |
-| `readOnly` | `boolean` | Read-only flag (default: false) |
-| `name` | `varchar(255)` | Branch name |
-| `slug` | `varchar(255)` | URL-friendly identifier (unique per company) |
-| `logoId` | `char(36)` | Reference to storage file |
-| `address` | `text` | Branch address |
-| `phone` | `varchar(50)` | Branch phone |
-| `email` | `varchar(255)` | Branch email |
-| `serial` | `int` | Display order |
-| `isActive` | `boolean` | Branch status (default: true) |
-| `additionalFields` | `json` | Extension fields |
-| `parentId` | `uuid` | Parent branch (for hierarchical branches) |
-| `companyId` | `uuid` | Parent company ID |
-| `createdAt` | `timestamp` | Auto-generated |
-| `updatedAt` | `timestamp` | Auto-updated |
-
-**Relations:**
-- `company` - Many-to-One relation to Company (CASCADE delete)
-- `parent` - Many-to-One relation to self (hierarchical, CASCADE delete)
-- `children` - One-to-Many relation to self
-
-### UserCompanyPermission Entity (Polymorphic)
+### 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`)
+
+| 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`:
 
 ```typescript
-enum PermissionType {
-  COMPANY = 'company',
-  BRANCH = 'branch',
-}
+import { AuthModule } from '@flusys/nestjs-auth';
+
+TypeOrmModule.forRoot({
+  // ...
+  entities: [
+    ...AuthModule.getEntities({ enableCompanyFeature: true, enableEmailVerification: true }),
+    // other app entities
+  ],
+})
 ```
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `uuid` | Primary key |
-| `userId` | `uuid` | Reference to user |
-| `permissionType` | `varchar(50)` | company or branch |
-| `targetId` | `uuid` | Company ID or Branch ID |
-| `metadata` | `json` | Optional metadata for the permission |
-| `isActive` | `boolean` | Permission status (default: true) |
-| `createdAt` | `timestamp` | Auto-generated |
-| `updatedAt` | `timestamp` | Auto-updated |
-
-**Indexes:**
-- Unique index on `(userId, permissionType, targetId)`
-- Index on `(userId, permissionType)`
-- Index on `(permissionType, targetId)`
-
-**Relations:**
-- `user` - Many-to-One relation to User (CASCADE delete)
-- `company` - Many-to-One relation to Company (no FK constraint - polymorphic)
-- `branch` - Many-to-One relation to CompanyBranch (no FK constraint - polymorphic)
-
-## Provider Interfaces
+---
+
+## Provider Interfaces (Extensibility)
+
+`@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.
 
 ### AUTH_EMAIL_PROVIDER
 
-Allows auth to work independently of the email module:
+Enables password-reset and email-verification emails without a hard dependency on any email module.
+
+**Interface:**
 
 ```typescript
+import { IAuthEmailProvider, AUTH_EMAIL_PROVIDER } from '@flusys/nestjs-auth';
+
 interface IAuthEmailProvider {
-  /** Send password reset email */
   sendPasswordResetEmail(email: string, token: string, resetUrl: string): Promise<void>;
-
-  /** Send email verification email */
   sendVerificationEmail(email: string, token: string, verifyUrl: string): Promise<void>;
-
-  /** Send welcome email after registration (optional) */
-  sendWelcomeEmail?(email: string, name: string): Promise<void>;
+  sendWelcomeEmail?(email: string, name: string): Promise<void>; // optional
 }
 ```
 
-**Example Implementation:**
+**Implementation example (using `@flusys/nestjs-email`):**
 
 ```typescript
-{
+import { AUTH_EMAIL_PROVIDER } from '@flusys/nestjs-auth';
+import { EmailSendService } from '@flusys/nestjs-email';
+
+export const authEmailProvider = {
   provide: AUTH_EMAIL_PROVIDER,
   useFactory: (emailSendService: EmailSendService) => ({
     sendPasswordResetEmail: async (email, token, resetUrl) => {
@@ -439,960 +546,295 @@ interface IAuthEmailProvider {
         variables: { verifyUrl, token },
       });
     },
+    sendWelcomeEmail: async (email, name) => {
+      await emailSendService.sendTemplateEmail({
+        templateSlug: 'welcome',
+        to: email,
+        variables: { name },
+      });
+    },
   }),
   inject: [EmailSendService],
-}
+};
 ```
 
-### USER_ENRICHER
-
-Extends user list and profile without modifying base package:
+**Register in `forRootAsync`:**
 
 ```typescript
-interface IUserEnricher {
-  // ===== List Enrichment =====
-
-  /** Enrich user list query with extra joins/selects */
-  enrichListQuery?(
-    query: SelectQueryBuilder<User>,
-    user: ILoggedUserInfo | null,
-  ): Promise<{ extraFields: string[] }>;
-
-  /** Transform user list items with extra computed data */
-  enrichListItems?(
-    users: IUser[],
-    user: ILoggedUserInfo | null,
-  ): Promise<IEnrichedUser[]>;
-
-  // ===== Profile Enrichment =====
-
-  /** Get extra profile data (roles, permissions, sections) */
-  getProfileExtras?(
-    userId: string,
-    user: ILoggedUserInfo,
-  ): Promise<IProfileExtras>;
-
-  /** Handle profile update with extra fields (within transaction) */
-  updateProfileExtras?(
-    userId: string,
-    extras: Record<string, any>,
-    queryRunner: QueryRunner,
-  ): Promise<void>;
-
-  /** Validate extra fields before profile update */
-  validateProfileExtras?(
-    userId: string,
-    extras: Record<string, any>,
-    user: ILoggedUserInfo,
-  ): Promise<void>;
-
-  // ===== Multi-Step Profile Methods =====
-
-  /** Get profile section definitions for multi-step profiles */
-  getProfileSections?(): IProfileSection[];
-
-  /** Get specific section data for a user */
-  getProfileSectionData?(
-    userId: string,
-    sectionId: string,
-    user: ILoggedUserInfo,
-  ): Promise<IProfileSectionData>;
-
-  /** Update specific profile section (within transaction) */
-  updateProfileSection?(
-    userId: string,
-    sectionId: string,
-    data: Record<string, any>,
-    queryRunner: QueryRunner,
-  ): Promise<void>;
-
-  /** Handle file upload for 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 profile section */
-  handleSectionFileDelete?(
-    userId: string,
-    sectionId: string,
-    field: string,
-    fileId: string,
-    queryRunner: QueryRunner,
-  ): Promise<void>;
-
-  /** Calculate profile completion percentage (0-100) */
-  calculateProfileCompletion?(
-    userId: string,
-    user: ILoggedUserInfo,
-  ): Promise<number>;
-
-  // ===== Registration Hook =====
-
-  /**
-   * Hook called after user is created during registration
-   * Runs within the same database transaction as user creation
-   * Use this to create related entities (e.g., UserProfileInfo)
-   * Throw error to rollback the entire registration
-   */
-  onUserCreated?(
-    userId: string,
-    additionalFields: Record<string, any> | null,
-    queryRunner: QueryRunner,
-  ): Promise<void>;
-}
+AuthModule.forRootAsync({
+  // ...
+  providers: [authEmailProvider],
+})
 ```
 
-**Profile Related Interfaces:**
+When `AUTH_EMAIL_PROVIDER` is not provided, the auth module runs without email sending — registration still works but verification emails are silently skipped.
 
-```typescript
-interface IProfileSection {
-  id: string;                        // Unique identifier
-  name: string;                      // Display name
-  order: number;                     // Stepper order
-  icon?: string;                     // PrimeNG icon class
-  required?: boolean;                // Required for completion
-  hasFileUpload?: boolean;           // Has file fields
-  editPermission?: IPermissionLogic; // Required permission
-}
-
-interface IProfileSectionData {
-  sectionId: string;
-  data: Record<string, any>;
-  isComplete: boolean;
-  files?: IProfileFile[];
-}
-
-interface IProfileFile {
-  field: string;
-  id: string;
-  name: string;
-  url?: string;
-  type?: string;
-}
-
-interface IProfileExtras {
-  roles?: IProfileRole[];
-  actions?: IProfileAction[];
-  sections?: IProfileSectionData[];
-  completionPercentage?: number;
-}
-
-interface IProfileRole {
-  id: string;
-  name: string;
-  description?: string | null;
-}
+---
 
-interface IProfileAction {
-  id: string;
-  name: string;
-  code: string;
-  description?: string | null;
-}
+### USER_ENRICHER
 
-type IEnrichedUser = IUser & IProfileExtras;
-```
+Allows extending the user list and profile responses with data from external modules (roles, permissions, custom profile sections) without creating circular dependencies.
 
-**Registration Hook Example (UserProfileInfo):**
+**Interface:**
 
 ```typescript
-// In your consuming app (e.g., FLUSYS-TEMPLATE)
-import { USER_ENRICHER, IUserEnricher } from '@flusys/nestjs-auth';
-import { QueryRunner } from 'typeorm';
-
-@Injectable({ scope: Scope.REQUEST })
-export class MyUserEnricher implements IUserEnricher {
-  /**
-   * Called after user creation, within the same transaction
-   * If this throws, the entire registration rolls back
-   */
-  async onUserCreated(
-    userId: string,
-    additionalFields: Record<string, any> | null,
-    queryRunner: QueryRunner,
-  ): Promise<void> {
-    if (!additionalFields) return;
-
-    // Create related entity (e.g., UserProfileInfo)
-    const profileInfo = queryRunner.manager.create(UserProfileInfo, {
-      userId,
-      prevCompanyName: additionalFields.prevCompanyName ?? null,
-      prevCompanyLocation: additionalFields.prevCompanyLocation ?? null,
-    });
-
-    await queryRunner.manager.save(UserProfileInfo, profileInfo);
-  }
-}
+import { IUserEnricher, USER_ENRICHER } from '@flusys/nestjs-auth';
 
-// Register the provider
-{
-  provide: USER_ENRICHER,
-  useClass: MyUserEnricher,
-}
-```
-
-**Registration with additionalFields:**
+interface IUserEnricher {
+  // Extend the user list SQL query with extra joins/selects
+  enrichListQuery?(query: SelectQueryBuilder<User>, user: ILoggedUserInfo | null): Promise<{ extraFields: string[] }>;
 
-```json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123",
-  "additionalFields": {
-    "prevCompanyName": "Acme Corp",
-    "prevCompanyLocation": "New York"
-  }
-}
-```
+  // Transform user list items (add computed fields)
+  enrichListItems?(users: IUser[], user: ILoggedUserInfo | null): Promise<IEnrichedUser[]>;
 
-## Services
-
-| Service | Scope | Description |
-|---------|-------|-------------|
-| `AuthenticationService` | REQUEST | Login, register, token management, company selection |
-| `AuthEmailService` | REQUEST | Email verification, password reset, pending registrations |
-| `UserService` | REQUEST | User CRUD, extends `RequestScopedApiService` |
-| `CompanyService` | REQUEST | Company CRUD (when company feature enabled) |
-| `BranchService` | REQUEST | Branch CRUD with company filtering |
-| `UserPermissionService` | REQUEST | User-company/branch permission management |
-| `AuthDataSourceProvider` | REQUEST | Dynamic datasource for single/multi-tenant |
-| `AuthConfigService` | SINGLETON | JWT and module configuration access |
-| `CompanySelectionSessionService` | SINGLETON | Session management for company selection |
-
-### AuthEmailService
-
-Token Security: All tokens are stored as SHA-256 hashes. Raw tokens are sent to users via email, but only hashes are stored in the database.
-
-| Method | Description |
-|--------|-------------|
-| `isEmailEnabled()` | Check if email provider is configured |
-| `hasPendingRegistration(email)` | Check for pending registration |
-| `createPendingRegistration(data)` | Create pending registration with verification email |
-| `forgotPassword(email, resetUrlBase)` | Send password reset email |
-| `resetPassword(token, newPassword)` | Reset password using token |
-| `verifyEmail(token)` | Verify email (returns `{ type: 'pending', pending }` or `{ type: 'verified', message }`) |
-| `resendVerificationEmail(email, verifyUrlBase)` | Resend verification email |
-| `cleanupExpired()` | Clean up expired tokens and pending registrations |
-
-**Token Expiry:**
-- Password Reset: 1 hour
-- Email Verification: 24 hours
-
-### AuthenticationService
-
-| Method | Description |
-|--------|-------------|
-| `login(email, password)` | Validate credentials and return tokens |
-| `register(dto, verifyUrlBase?)` | Register new user (creates pending registration if email enabled) |
-| `createUserFromPendingRegistration(pending)` | Create user from verified pending registration |
-| `select(sessionId, companyId, branchId)` | Complete company selection after login |
-| `switchCompany(userId, companyId, branchId)` | Switch to different company/branch |
-| `refreshToken(refreshToken)` | Refresh access token |
-| `changePassword(userId, currentPassword, newPassword)` | Change user password |
-| `logout(userId)` | Revoke all tokens for user |
-| `isTokenRevoked(userId, tokenIssuedAt)` | Check if token is revoked |
-| `getUserCompanies(userId)` | Get user's available companies |
-| `getUserBranches(userId, companyId)` | Get user's branches for a company |
-| `getUserInfo(userId, companyId?, branchId?)` | Get current user info |
-
-### UserService
-
-Extends `RequestScopedApiService` for full CRUD support.
-
-| Method | Description |
-|--------|-------------|
-| `insert(dto, user)` | Create user (auto-assigns company permissions) |
-| `verifyEmail(id)` | Mark user email as verified |
-| `verifyPhone(id)` | Mark user phone as verified |
-| `updateStatus(id, isActive, user)` | Update user status (company-aware) |
-| `profile(dto, user)` | Update own profile with optional extras |
-| `getProfileWithExtras(userId, user)` | Get profile with enricher data |
-| `getProfileSections()` | Get profile section definitions |
-| `getProfileSectionData(userId, sectionId, user)` | Get specific section data |
-| `updateProfileSection(userId, sectionId, data, user)` | Update specific section |
-| `getProfileCompletion(userId, user)` | Calculate profile completion % |
-| `getEnrichedList(users, user)` | Enrich user list with extra data |
-
-### CompanyService
-
-Extends `RequestScopedApiService` for full CRUD support on Company entity.
-
-### BranchService
-
-Extends `RequestScopedApiService` for full CRUD support on CompanyBranch entity.
-Automatically applies company filter based on logged user context.
-
-### UserPermissionService
-
-| Method | Description |
-|--------|-------------|
-| `findUserPermissions(userId, type)` | Get all permissions of type for user |
-| `assignPermission(userId, targetId, type, metadata?)` | Assign permission to user |
-| `revokePermission(userId, targetId, type)` | Revoke permission from user |
-| `findUserCompanies(userId)` | Get user's company permissions |
-| `findUserBranches(userId, companyId?)` | Get user's branch permissions |
-
-### CompanySelectionSessionService
-
-Manages temporary sessions during company/branch selection flow.
-
-| Method | Description |
-|--------|-------------|
-| `createSession(userId)` | Create session (returns sessionId, TTL: 5 minutes) |
-| `getSession(sessionId)` | Get session without consuming |
-| `consumeSession(sessionId)` | Get and delete session (one-time use) |
-| `deleteSession(sessionId)` | Delete session |
-
-### AuthConfigService
-
-Provides configuration access.
-
-| Method | Description |
-|--------|-------------|
-| `getDatabaseMode()` | Returns 'single' or 'multi-tenant' |
-| `isMultiTenant()` | Check if multi-tenant mode |
-| `isCompanyFeatureEnabled()` | Check if company feature enabled |
-| `isEmailVerificationEnabled()` | Check if email verification enabled |
-| `getJwtSecret()` | Get JWT secret (throws if not configured) |
-| `getJwtExpiration()` | Get JWT expiration (default: '1h') |
-| `getRefreshTokenSecret()` | Get refresh token secret |
-| `getRefreshTokenExpiration()` | Get refresh expiration (default: '7d') |
-| `getRefreshTokenCookieName()` | Get cookie name (default: 'fsn_refresh_token') |
-| `getFrontendUrl()` | Get frontend URL for email links |
-
-### AuthDataSourceProvider
-
-Extends `MultiTenantDataSourceService` for dynamic datasource handling.
-
-| Method | Description |
-|--------|-------------|
-| `getDataSource()` | Get current tenant's DataSource |
-| `getRepository(entity)` | Get repository for entity |
-| `isCompanyFeatureEnabled(tenant?)` | Check company feature for tenant |
-| `isEmailVerificationEnabled(tenant?)` | Check email verification for tenant |
-| `getAuthEntities()` | Get entities based on feature flags |
+  // Return extra profile data (roles, actions, etc.)
+  getProfileExtras?(userId: string, user: ILoggedUserInfo): Promise<IProfileExtras>;
 
-## API Endpoints
+  // Update extra profile fields inside a transaction
+  updateProfileExtras?(userId: string, extras: Record<string, any>, queryRunner: QueryRunner): Promise<void>;
 
-> **Note:** All endpoints use POST method following POST-only RPC pattern.
-
-### Authentication Endpoints
-
-| Endpoint | Method | Auth | Description |
-|----------|--------|------|-------------|
-| `/auth/login` | POST | No | Login with email/password |
-| `/auth/register` | POST | No | Register new user |
-| `/auth/refresh` | POST | No | Refresh access token |
-| `/auth/logout` | POST | JWT | Logout (revokes all tokens) |
-| `/auth/change-password` | POST | JWT | Change user password |
-| `/auth/me` | POST | JWT | Get current user info |
-
-**Rate Limits:**
-- `/auth/login` - 5 attempts per minute
-- `/auth/register` - 3 attempts per minute
-- `/auth/refresh` - 30 attempts per minute
-
-### Email Authentication Endpoints
-
-| Endpoint | Method | Auth | Description |
-|----------|--------|------|-------------|
-| `/auth/forgot-password` | POST | No | Request password reset email |
-| `/auth/reset-password` | POST | No | Reset password using token |
-| `/auth/verify-email` | POST | No | Verify email using token |
-| `/auth/resend-verification` | POST | No | Resend email verification link |
-
-**Rate Limits:**
-- `/auth/forgot-password` - 3 requests per 5 minutes
-- `/auth/reset-password` - 5 attempts per 15 minutes
-- `/auth/verify-email` - 10 attempts per minute
-- `/auth/resend-verification` - 3 requests per 5 minutes
-
-> **Note:** Email endpoints require `AUTH_EMAIL_PROVIDER` to be configured and `enableEmailVerification: true`.
-
-### Company Selection Endpoints (when company feature enabled)
-
-| Endpoint | Method | Auth | Description |
-|----------|--------|------|-------------|
-| `/auth/select` | POST | No | Select company and branch after login |
-| `/auth/switch-company` | POST | JWT | Switch to different company/branch |
-| `/auth/get-companies` | POST | JWT | Get user's available companies |
-| `/auth/get-company-branches` | POST | JWT | Get branches for a company |
-
-### User Management Endpoints
-
-| Endpoint | Method | Auth | Permission | Description |
-|----------|--------|------|------------|-------------|
-| `/administration/users/insert` | POST | JWT | `user.create` | Create user |
-| `/administration/users/insert-many` | POST | JWT | `user.create` | Bulk create users |
-| `/administration/users/get/:id` | POST | JWT | `user.read` | Get user by ID |
-| `/administration/users/get-all` | POST | JWT | `user.read` | Get paginated user list |
-| `/administration/users/update` | POST | JWT | `user.update` | Update user |
-| `/administration/users/update-many` | POST | JWT | `user.update` | Bulk update users |
-| `/administration/users/delete` | POST | JWT | `user.delete` | Delete/restore/permanent delete |
-| `/administration/users/profile` | POST | JWT | - | Update own profile |
-| `/administration/users/:id/verify-email` | POST | JWT | `user.update` | Mark email as verified |
-| `/administration/users/:id/verify-phone` | POST | JWT | `user.update` | Mark phone as verified |
-| `/administration/users/:id/status` | POST | JWT | `user.update` | Update user active status |
-
-### User Profile Extensions Endpoints
-
-| Endpoint | Method | Auth | Permission | Description |
-|----------|--------|------|------------|-------------|
-| `/administration/users/:id/profile-extras` | POST | JWT | `user.read` | Get profile with enricher extras |
-| `/administration/users/profile-sections` | POST | JWT | `user.read` | Get profile section definitions |
-| `/administration/users/:id/profile-section/:sectionId` | POST | JWT | `user.read` | Get specific section data |
-| `/administration/users/:id/profile-section/:sectionId/update` | POST | JWT | `user.update` | Update specific section |
-| `/administration/users/:id/profile-completion` | POST | JWT | `user.read` | Get profile completion % |
-
-### User Permission Endpoints (when company feature enabled)
-
-| Endpoint | Method | Auth | Permission | Description |
-|----------|--------|------|------------|-------------|
-| `/administration/permissions/user-company/assign` | POST | JWT | `user.update` | Batch assign/revoke user-company permissions |
-| `/administration/permissions/get-user-company` | POST | JWT | `user.read` | Get user's assigned companies |
-| `/administration/permissions/user-branch/assign` | POST | JWT | `user.update` | Batch assign/revoke user-branch permissions |
-| `/administration/permissions/get-user-branch` | POST | JWT | `user.read` | Get user's assigned branches |
-
-### Company Management Endpoints (when company feature enabled)
-
-| Endpoint | Method | Auth | Permission | Description |
-|----------|--------|------|------------|-------------|
-| `/administration/company/insert` | POST | JWT | `company.create` | Create company |
-| `/administration/company/insert-many` | POST | JWT | `company.create` | Bulk create companies |
-| `/administration/company/get/:id` | POST | JWT | `company.read` | Get company by ID |
-| `/administration/company/get-all` | POST | JWT | `company.read` | Get paginated company list |
-| `/administration/company/update` | POST | JWT | `company.update` | Update company |
-| `/administration/company/update-many` | POST | JWT | `company.update` | Bulk update companies |
-| `/administration/company/delete` | POST | JWT | `company.delete` | Delete/restore/permanent delete |
-
-### Branch Management Endpoints (when company feature enabled)
-
-| Endpoint | Method | Auth | Permission | Description |
-|----------|--------|------|------------|-------------|
-| `/administration/branch/insert` | POST | JWT | `branch.create` | Create branch |
-| `/administration/branch/insert-many` | POST | JWT | `branch.create` | Bulk create branches |
-| `/administration/branch/get/:id` | POST | JWT | `branch.read` | Get branch by ID |
-| `/administration/branch/get-all` | POST | JWT | `branch.read` | Get paginated branch list |
-| `/administration/branch/update` | POST | JWT | `branch.update` | Update branch |
-| `/administration/branch/update-many` | POST | JWT | `branch.update` | Bulk update branches |
-| `/administration/branch/delete` | POST | JWT | `branch.delete` | Delete/restore/permanent delete |
-
-## Login Flows
-
-### Simple Mode (Company Feature Disabled)
+  // Validate extra fields before saving
+  validateProfileExtras?(userId: string, extras: Record<string, any>, user: ILoggedUserInfo): Promise<void>;
 
-```
-POST /auth/login { email, password }
-              │
-              ▼
-┌─────────────────────────┐
-│  AuthenticationService  │
-│  .login()               │
-└────────────┬────────────┘
-             │
-             │ 1. Check pending registration
-             │ 2. Verify credentials
-             │ 3. Check email verified (if email enabled)
-             │ 4. Generate JWT tokens
-             ▼
-    { accessToken, refreshToken, user }
-```
+  // Return multi-step profile section definitions
+  getProfileSections?(): IProfileSection[];
 
-### Company Mode - Auto-Select (Single Company/Branch)
+  // Return data for a specific profile section
+  getProfileSectionData?(userId: string, sectionId: string, user: ILoggedUserInfo): Promise<IProfileSectionData>;
 
-```
-POST /auth/login { email, password }
-              │
-              ▼
-┌─────────────────────────┐
-│  AuthenticationService  │
-│  .login()               │
-└────────────┬────────────┘
-             │
-             │ 1. Verify credentials
-             │ 2. Check UserCompanyPermission
-             │ 3. Found: 1 company, 1 branch → Auto-select
-             ▼
-    { accessToken, refreshToken, user, company, branch }
-```
+  // Update a specific profile section inside a transaction
+  updateProfileSection?(userId: string, sectionId: string, data: Record<string, any>, queryRunner: QueryRunner): Promise<void>;
 
-### Company Mode - Selection Required (Multiple Options)
+  // 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>;
 
-```
-POST /auth/login { email, password }
-              │
-              ▼
-    { requiresSelection: true, sessionId, companies: [...] }
-              │
-              │ User selects company & branch
-              ▼
-POST /auth/select { sessionId, companyId, branchId }
-              │
-              ▼
-    { accessToken, refreshToken, user, company, branch }
-```
+  // Handle file deletion for a profile section
+  handleSectionFileDelete?(userId: string, sectionId: string, field: string, fileId: string, queryRunner: QueryRunner): Promise<void>;
 
-### Login with Email Verification Required
+  // Return profile completion percentage (0–100)
+  calculateProfileCompletion?(userId: string, user: ILoggedUserInfo): Promise<number>;
 
-```
-POST /auth/login { email, password }
-              │
-              ▼
-    If pending registration OR email not verified:
-    { requiresEmailVerification: true, email, message }
+  // 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>;
+}
 ```
 
-## Email Verification Flow
+**Implementation example (adding IAM roles to user profile):**
 
-### New User Registration (with email enabled)
+```typescript
+import { USER_ENRICHER, IUserEnricher } from '@flusys/nestjs-auth';
+import { PermissionService } from '@flusys/nestjs-iam';
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ POST /auth/register { email, password, name }                   │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ 1. Check existing user (must not exist)                         │
-│ 2. Hash password with bcrypt (SALT_ROUNDS = 12)                 │
-│ 3. Generate verification token                                  │
-│ 4. Hash token with SHA-256 for storage                          │
-│ 5. Create PendingRegistration record                            │
-│ 6. Send verification email via AUTH_EMAIL_PROVIDER              │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-    { requiresEmailVerification: true, message: "Check your email" }
-                              │
-                              │ User clicks email link
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ POST /auth/verify-email { token }                               │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ 1. Hash incoming token with SHA-256                             │
-│ 2. Find PendingRegistration by hashed token                     │
-│ 3. Check expiration                                             │
-│ 4. Delete PendingRegistration record                            │
-│ 5. Create User with emailVerified: true                         │
-│ 6. Process company assignment if companyData present            │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-    { accessToken, refreshToken, user, company?, branch? }
-```
+@Injectable()
+export class IamUserEnricher implements IUserEnricher {
+  constructor(private readonly permissionService: PermissionService) {}
 
-### Password Reset Flow
+  async getProfileExtras(userId: string, user: ILoggedUserInfo) {
+    const roles = await this.permissionService.getRolesForUser(userId);
+    const actions = await this.permissionService.getActionsForUser(userId);
+    return { roles, actions };
+  }
+}
 
+export const userEnricherProvider = {
+  provide: USER_ENRICHER,
+  useClass: IamUserEnricher,
+};
 ```
-POST /auth/forgot-password { email }
-              │
-              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ 1. Find user by email                                           │
-│ 2. Delete existing PASSWORD_RESET tokens for user               │
-│ 3. Generate new token, hash with SHA-256                        │
-│ 4. Create UserToken record (expires in 1 hour)                  │
-│ 5. Send reset email via AUTH_EMAIL_PROVIDER                     │
-│ 6. Return success (same response even if user not found)        │
-└─────────────────────────────────────────────────────────────────┘
-              │
-              ▼
-    { success: true, message: "If email exists, reset link sent" }
-              │
-              │ User clicks email link
-              ▼
-POST /auth/reset-password { token, newPassword }
-              │
-              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ 1. Hash incoming token with SHA-256                             │
-│ 2. Find UserToken by hashed token + type: PASSWORD_RESET        │
-│ 3. Validate not expired, not used                               │
-│ 4. Update user password                                         │
-│ 5. Mark token as used (usedAt = now)                            │
-└─────────────────────────────────────────────────────────────────┘
-              │
-              ▼
-    { success: true, message: "Password reset successfully" }
-```
-
-## User Management
 
-### Company Permission Assignment Flow
+**Register in `forRootAsync`:**
 
-When creating users with `enableCompanyFeature: true`, permissions are automatically assigned:
-
-```
-User Creation (with companyId/branchId)
-                │
-                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ 1. Insert user record                                           │
-└─────────────────────────────────────────────────────────────────┘
-                │
-                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ 2. Check if company permission exists                           │
-│    - Lookup UserCompanyPermission for user + company            │
-│    - If not exists: create { userId, targetId: companyId,       │
-│                              permissionType: 'company' }        │
-└─────────────────────────────────────────────────────────────────┘
-                │
-                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ 3. Check if branch permission exists                            │
-│    - Lookup UserCompanyPermission for user + branch             │
-│    - If not exists: create { userId, targetId: branchId,        │
-│                              permissionType: 'branch' }         │
-└─────────────────────────────────────────────────────────────────┘
+```typescript
+AuthModule.forRootAsync({
+  // ...
+  providers: [userEnricherProvider],
+})
 ```
 
-### User Active Status
+All methods in `IUserEnricher` are optional. Implement only the hooks you need.
 
-**When company feature is disabled:**
-- Updates `User.isActive` directly
+---
 
-**When company feature is enabled:**
-- Updates `UserCompanyPermission.isActive` for the logged user's company
-- User can be active in Company A but inactive in Company B
+## Exported Services
 
-### Registration Flows
+These services are exported by `AuthModule` and can be injected into your application:
 
-**Simple registration:**
-```json
-{ "name": "John Doe", "email": "john@example.com", "password": "password123" }
-```
+| 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 |
 
-**Join existing company:**
-```json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123",
-  "companySlug": "acme-corp",
-  "branchSlug": "main-branch"
-}
-```
+**Usage:**
 
-**Create new company:**
-```json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123",
-  "newCompanyName": "My Company",
-  "newCompanyPhone": "+1234567890",
-  "newCompanyAddress": "123 Main St"
-}
-```
+```typescript
+import { AuthenticationService } from '@flusys/nestjs-auth';
 
-**Registration with extension fields (additionalFields):**
-```json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123",
-  "additionalFields": {
-    "prevCompanyName": "Acme Corporation",
-    "prevCompanyLocation": "New York, USA",
-    "prevIndustryType": "technology"
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject(AuthenticationService) private readonly authService: AuthenticationService,
+  ) {}
+
+  async validateToken(token: string) {
+    return this.authService.refreshToken(token);
   }
 }
 ```
 
-> **Note:** `additionalFields` are passed to the `USER_ENRICHER.onUserCreated` hook within the same database transaction. If the hook throws an error, the entire registration is rolled back, ensuring atomicity.
+> **Note:** Always use `@Inject(ServiceClass)` explicitly. This package is distributed as an esbuild bundle where TypeScript metadata is not preserved.
 
-## No-IAM Mode
+---
 
-When not using `@flusys/nestjs-iam` but controllers use `level: 'permission'` security, set wildcard permissions after login:
+## Interceptors
 
-```typescript
-import { HybridCache, CACHE_INSTANCE, PERMISSIONS_CACHE_PREFIX } from '@flusys/nestjs-shared';
+| 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 |
 
-@Injectable()
-export class AuthenticationService {
-  constructor(
-    @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
-  ) {}
+Applied automatically by the auth controllers. Export them from `AuthModule` if you need them in custom controllers.
 
-  async login(dto: LoginDto): Promise<LoginResponse> {
-    // ... validate credentials, generate tokens
+---
 
-    // When IAM is NOT used, grant all permissions via wildcard
-    await this.setWildcardPermissions(user.id);
+## Security
 
-    return { accessToken, user };
-  }
+### Token Strategy
 
-  private async setWildcardPermissions(userId: string): Promise<void> {
-    const cacheKey = `${PERMISSIONS_CACHE_PREFIX}:user:${userId}`;
-    await this.cache.set(cacheKey, ['*'], 86400000); // 24 hours TTL
-  }
-}
-```
+| 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) |
 
-### With Company Feature Enabled
+### Password Hashing
 
-```typescript
-private async setWildcardPermissions(
-  userId: string,
-  companyId?: string,
-  branchId?: string,
-): Promise<void> {
-  if (companyId) {
-    const cacheKey = `${PERMISSIONS_CACHE_PREFIX}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`;
-    await this.cache.set(cacheKey, ['*'], 86400000);
-  } else {
-    const cacheKey = `${PERMISSIONS_CACHE_PREFIX}:user:${userId}`;
-    await this.cache.set(cacheKey, ['*'], 86400000);
-  }
-}
-```
+bcrypt with **12 salt rounds** (OWASP recommended minimum).
 
-### Wildcard Permission Patterns
+### Rate Limiting
 
-| Pattern | Meaning |
-|---------|---------|
-| `*` | Full access to everything |
-| `user.*` | All user permissions |
-| `branch.*` | All branch permissions |
+Built-in via `@nestjs/throttler`:
 
-## JWT Strategy
+| 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 |
 
-The `JwtStrategy` is a singleton Passport strategy that validates JWT tokens and extracts user info.
+### SQL Injection Protection
 
-**Token Payload:**
-```typescript
-interface TokenPayload {
-  id: string;                    // User ID
-  email: string;                 // User email
-  type: 'access' | 'refresh';    // Token type
-  profilePictureId?: string;     // Profile picture file ID
-  tenantId?: string;             // Tenant ID (multi-tenant)
-  iat?: number;                  // Issued at
-  exp?: number;                  // Expiration
-}
+All database queries use TypeORM parameterized statements. No raw string interpolation.
 
-// When company feature enabled
-interface TokenPayloadWithCompany extends TokenPayload {
-  companyId: string;             // Selected company ID
-  branchId?: string;             // Selected branch ID (optional)
-  companyLogoId?: string | null; // Company logo file ID
-  branchLogoId?: string | null;  // Branch logo file ID
-}
-```
+### Important Notes
 
-**Validation Flow:**
-1. Extract token from `Authorization: Bearer <token>` header
-2. Verify token signature using JWT secret
-3. Check token revocation status (if cache available)
-4. Validate user exists and is active
-5. Return `ILoggedUserInfo` with user context
+- 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.
 
-**Token Revocation:**
-- Uses cache to track revoked tokens
-- Key format: `auth:revoked:{userId}`
-- Stores timestamp of last logout
-- Tokens issued before logout timestamp are rejected
+---
 
-## Interceptors
+## Environment Variables
 
-### SetToken Interceptor
+```env
+# Database
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=secret
+DB_NAME=myapp
 
-Automatically sets refresh token as HTTP-only cookie for browser clients:
+# JWT
+JWT_SECRET=change-me-in-production
+JWT_EXPIRATION=15m
+REFRESH_TOKEN_SECRET=change-me-in-production-2
+REFRESH_TOKEN_EXPIRATION=7d
 
-```typescript
-@UseInterceptors(SetToken)
-async login(@Body() loginDto: LoginDto) { ... }
+# Application
+FRONTEND_URL=http://localhost:3000
+PORT=3001
 ```
 
-**Behavior:**
-- Detects browser requests via `User-Agent` and `x-client-type` header
-- For browsers: Sets `refreshToken` as HTTP-only cookie, removes from response body
-- For API/Mobile: Returns `refreshToken` in response body
-- Cookie options: `httpOnly: true`, `secure: true` (production), `sameSite: 'lax'`
+---
+
+## Troubleshooting
 
-### ClearToken Interceptor
+**`Cannot read properties of undefined` on service injection**
 
-Clears refresh token cookie on logout:
+You are likely missing `@Inject()` on a constructor parameter. This package is bundled with esbuild and TypeScript metadata is not preserved:
 
 ```typescript
-@UseInterceptors(ClearToken)
-async logout(@CurrentUser('id') userId: string) { ... }
+// Wrong
+constructor(private readonly authService: AuthenticationService) {}
+
+// Correct
+constructor(@Inject(AuthenticationService) private readonly authService: AuthenticationService) {}
 ```
 
-## Validators
+---
 
-### IsStrongPassword
+**Login returns `requiresEmailVerification: true` unexpectedly**
 
-Custom password validation decorator:
+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.
 
-```typescript
-@IsStrongPassword()
-password!: string;
+---
 
-// With custom options
-@IsStrongPassword({ minLength: 12, requireSpecialChar: false })
-password!: string;
-```
+**Login returns `requiresSelection: true` unexpectedly**
 
-**Default Requirements:**
-- Minimum 8 characters
-- Maximum 128 characters
-- At least one uppercase letter
-- At least one lowercase letter
-- At least one number
-- At least one special character (`!@#$%^&*()_+-=[]{}...`)
+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.
 
-**Custom Options:**
-```typescript
-interface PasswordComplexityOptions {
-  minLength?: number;          // Default: 8
-  maxLength?: number;          // Default: 128
-  requireUppercase?: boolean;  // Default: true
-  requireLowercase?: boolean;  // Default: true
-  requireNumber?: boolean;     // Default: true
-  requireSpecialChar?: boolean; // Default: true
-}
-```
+---
 
-## API Reference
+**`No metadata for entity` error on startup**
 
-### Exports
+Ensure `AuthModule.getEntities()` is called with the correct config when registering `TypeOrmModule`:
 
 ```typescript
-// Config
-export { AUTH_MODULE_OPTIONS, USER_ENRICHER, BCRYPT_SALT_ROUNDS, DEFAULT_COOKIE_NAME, MAX_COOKIE_BYTES, SESSION_CACHE_PREFIX, TOKEN_REVOKED_PREFIX } from './config';
-
-// Entities
-export { User } from './entities/user.entity';
-export { UserToken, TokenType } from './entities/user-token.entity';
-export { PendingRegistration } from './entities/pending-registration.entity';
-export { Company } from './entities/company.entity';
-export { CompanyBranch } from './entities/company-branch.entity';
-export { UserCompanyPermission, PermissionType } from './entities/user-company-permission.entity';
-export { getEntitiesByConfig, IAuthEntitiesConfig } from './entities';
-
-// Enums
-export { PermissionType } from './enums';
-
-// Interfaces
-export { IAuthEmailProvider, AUTH_EMAIL_PROVIDER } from './interfaces/auth-email-provider.interface';
-export { IUserEnricher, IProfileSection, IProfileSectionData, IProfileFile, IProfileExtras, IProfileRole, IProfileAction, IEnrichedUser } from './interfaces/user-enricher.interface';
-export { AuthModuleOptions, AuthModuleAsyncOptions, AuthOptionsFactory, IAuthModuleConfig } from './interfaces/auth-module-options.interface';
-export { TokenPayload, TokenPayloadWithCompany, LoginResponse, LoginResponseRequiresSelection, LoginResponseRequiresEmailVerification, MeResponse, RegistrationResponse, CompanyWithBranches, BranchForSelection } from './interfaces/authentication.interface';
-export { IUser, IUserMini, IUserWithPassword } from './interfaces/user.interface';
-export { ICompany, ICompanyMini } from './interfaces/company.interface';
-export { ICompanyBranch, ICompanyBranchMini } from './interfaces/company-branch.interface';
-
-// Services
-export { AuthenticationService } from './services/authentication.service';
-export { AuthEmailService } from './services/auth-email.service';
-export { AuthConfigService } from './services/auth-config.service';
-export { AuthDataSourceProvider } from './services/auth-datasource.provider';
-export { UserService } from './services/user.service';
-export { CompanyService } from './services/company.service';
-export { BranchService } from './services/branch.service';
-export { UserPermissionService } from './services/user-permission.service';
-export { CompanySelectionSessionService } from './services/company-selection-session.service';
-
-// Modules
-export { AuthModule } from './modules/auth.module';
-
-// Controllers
-export { AuthenticationController } from './controllers/authentication.controller';
-export { EmailVerificationController } from './controllers/email-verification.controller';
-export { CompanySelectionController } from './controllers/company-selection.controller';
-export { UserController } from './controllers/user.controller';
-export { CompanyController } from './controllers/company.controller';
-export { BranchController } from './controllers/branch.controller';
-export { UserPermissionController } from './controllers/user-permission.controller';
-
-// Strategies
-export { JwtStrategy } from './strategies/jwt.strategy';
-
-// Interceptors
-export { SetToken } from './interceptors/set-token.interceptor';
-export { ClearToken } from './interceptors/clear-token.interceptor';
-
-// Validators
-export { IsStrongPassword, PasswordComplexityOptions } from './validators/password.validator';
-
-// DTOs
-export * from './dtos';
-
-// Swagger Config
-export { authSwaggerConfig } from './docs/auth-swagger.config';
+TypeOrmModule.forRoot({
+  entities: [
+    ...AuthModule.getEntities({
+      enableCompanyFeature: true,
+      enableEmailVerification: true,
+    }),
+  ],
+})
 ```
 
-### Module Static Methods
-
-```typescript
-// Get entities based on feature flags (requires IBootstrapAppConfig)
-AuthModule.getEntities(config: IBootstrapAppConfig): any[]
-
-// Examples:
-AuthModule.getEntities({ enableCompanyFeature: false })
-// Returns: [User, UserToken, PendingRegistration]
-
-AuthModule.getEntities({ enableCompanyFeature: true })
-// Returns: [User, UserToken, PendingRegistration, Company, CompanyBranch, UserCompanyPermission]
-
-AuthModule.getEntities({ enableCompanyFeature: true, enableEmailVerification: false })
-// Returns: [User, UserToken, Company, CompanyBranch, UserCompanyPermission]
+---
 
-// Configure module synchronously
-AuthModule.forRoot(options: AuthModuleOptions): DynamicModule
+**Refresh token cookie not being set**
 
-// Configure module asynchronously
-AuthModule.forRootAsync(options: AuthModuleAsyncOptions): DynamicModule
-```
+Ensure your Express app has `cookie-parser` middleware installed and registered before NestJS:
 
-**AuthModuleOptions Interface:**
 ```typescript
-interface AuthModuleOptions {
-  global?: boolean;              // Make module global (default: false)
-  includeController?: boolean;   // Include default controllers (default: true)
-  bootstrapAppConfig?: IBootstrapAppConfig;
-  config?: IAuthModuleConfig;
-  providers?: Provider[];        // Additional providers (AUTH_EMAIL_PROVIDER, USER_ENRICHER)
-}
-
-interface IAuthModuleConfig {
-  defaultDatabaseConfig?: IDatabaseConfig;
-  tenantDefaultDatabaseConfig?: IDatabaseConfig;
-  tenants?: ITenantDatabaseConfig[];
-  jwtSecret?: string;
-  jwtExpiration?: string;              // Default: '1h'
-  refreshTokenSecret?: string;
-  refreshTokenExpiration?: string;     // Default: '7d'
-  refreshTokenCookieName?: string;     // Default: 'fsn_refresh_token'
-  frontendUrl?: string;                // For email links
-}
+import * as cookieParser from 'cookie-parser';
+app.use(cookieParser());
 ```
 
-### Swagger Schema Behavior
+---
+
+**Password reset / verification emails not being sent**
 
-When `enableCompanyFeature: false`, the following are automatically hidden from Swagger:
+`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)).
 
-**Excluded Tags:** Companies, Branches, User Permissions, Company Selection
+---
 
-**Excluded DTO Properties:**
+## License
 
-| DTO | Hidden Fields |
-|-----|---------------|
-| `RegistrationDto` | `companySlug`, `branchSlug`, `newCompanyName`, `newCompanyPhone`, `newCompanyAddress` |
-| `RegistrationResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
-| `LoginResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
-| `MeResponseDto` | `company`, `branch` |
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-25
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.