@flusys/nestjs-auth 1.1.0-beta → 2.0.0-rc.0

package/README.md

@@ -1,23 +1,23 @@
 # Authentication Package Guide
 
 > **Package:** `@flusys/nestjs-auth`
-> **Type:** Authentication system with JWT, multi-tenant, and company/branch support
-
-This comprehensive guide covers the authentication package - flexible auth system for NestJS applications.
+> **Type:** Authentication system with JWT, email verification, multi-tenant, and company/branch support
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+- [Constants](#constants)
+- [Entities](#entities)
+- [Provider Interfaces](#provider-interfaces)
+- [Services](#services)
 - [API Endpoints](#api-endpoints)
-- [Architecture](#architecture)
 - [Login Flows](#login-flows)
+- [Email Verification Flow](#email-verification-flow)
 - [User Management](#user-management)
-- [Environment Variables](#environment-variables)
-- [Migrations](#migrations)
-- [Configuration Modes](#configuration-modes)
-- [IAM Integration](#iam-integration)
+- [No-IAM Mode](#no-iam-mode)
+- [API Reference](#api-reference)
 
 ---
 
@@ -40,17 +40,16 @@ import { AuthModule } from '@flusys/nestjs-auth';
     AuthModule.forRoot({
       global: true,
       includeController: true,
-      includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
       bootstrapAppConfig: {
         databaseMode: 'single',
         enableCompanyFeature: false,
       },
       config: {
         defaultDatabaseConfig: {
-          type: 'mysql',
+          type: 'postgres',
           host: 'localhost',
-          port: 3306,
-          username: 'root',
+          port: 5432,
+          username: 'postgres',
           password: 'password',
           database: 'myapp',
         },
@@ -69,20 +68,12 @@ export class AppModule {}
 AuthModule.forRoot({
   global: true,
   includeController: true,
-  includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
   bootstrapAppConfig: {
     databaseMode: 'single',
-    enableCompanyFeature: true,  // Enable company/branch support
+    enableCompanyFeature: true,
   },
   config: {
-    defaultDatabaseConfig: {
-      type: 'mysql',
-      host: 'localhost',
-      port: 3306,
-      username: 'root',
-      password: 'password',
-      database: 'myapp',
-    },
+    defaultDatabaseConfig: { /* ... */ },
     jwtSecret: process.env.JWT_SECRET,
     refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
     refreshTokenExpiration: '7d',
@@ -97,17 +88,16 @@ AuthModule.forRoot({
 AuthModule.forRoot({
   global: true,
   includeController: true,
-  includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
   bootstrapAppConfig: {
     databaseMode: 'multi-tenant',
     enableCompanyFeature: true,
   },
   config: {
     tenantDefaultDatabaseConfig: {
-      type: 'mysql',
+      type: 'postgres',
       host: 'localhost',
-      port: 3306,
-      username: 'root',
+      port: 5432,
+      username: 'postgres',
       password: 'password',
     },
     tenants: [
@@ -119,19 +109,36 @@ AuthModule.forRoot({
 })
 ```
 
-### Async Configuration
+### With Email Provider (Password Reset, Email Verification)
 
 ```typescript
-AuthModule.forRootAsync({
-  global: true,
-  includeController: true,
-  includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
-  bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: false,
-  },
-  imports: [HttpModule],
-  useClass: AuthConfigFactory,  // Implements AuthOptionsFactory
+import { AUTH_EMAIL_PROVIDER } from '@flusys/nestjs-auth';
+import { EmailSendService } from '@flusys/nestjs-email';
+
+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],
+    },
+  ],
 })
 ```
 
@@ -143,356 +150,386 @@ AuthModule.forRootAsync({
 interface AuthModuleOptions {
   global?: boolean;                    // Make module global
   includeController?: boolean;         // Include default controllers
-  includeIAM?: boolean;                // Include IAM entities in TypeORM.forRoot() (required for IAM module)
-  bootstrapAppConfig: {
+  bootstrapAppConfig?: {
     databaseMode: 'single' | 'multi-tenant';
-    enableCompanyFeature: boolean;     // Enable company/branch feature
+    enableCompanyFeature: boolean;
   };
-  config: {
+  config?: {
     defaultDatabaseConfig?: IDatabaseConfig;
     tenantDefaultDatabaseConfig?: IDatabaseConfig;
     tenants?: ITenantDatabaseConfig[];
-    jwtSecret: string;
-    jwtExpiration?: string;
+    jwtSecret?: string;
+    jwtExpiration?: string;             // Default: '1h'
     refreshTokenSecret?: string;
-    refreshTokenExpiration?: string;
-    refreshTokenCookieName?: string;   // Default: 'fsn_refresh_token'
+    refreshTokenExpiration?: string;    // Default: '7d'
+    refreshTokenCookieName?: string;    // Default: 'fsn_refresh_token'
+    frontendUrl?: string;               // For email links
   };
+  providers?: Provider[];               // Additional providers (AUTH_EMAIL_PROVIDER, USER_ENRICHER)
 }
 ```
 
-**Important Notes:**
+## Constants
 
-1. **includeIAM Flag**: When using `@flusys/nestjs-iam` in single-tenant mode, set `includeIAM: true` in Auth module options. This registers IAM entities with TypeORM during initialization. Not required in multi-tenant mode.
+```typescript
+// Injection Tokens
+export const AUTH_MODULE_OPTIONS = 'AUTH_MODULE_OPTIONS';
+export const USER_ENRICHER = 'USER_ENRICHER';
 
-2. **Module Separation**: Auth module handles authentication (login, JWT, user management). For authorization and permissions, use the separate `@flusys/nestjs-iam` package.
+// Security
+export const BCRYPT_SALT_ROUNDS = 12;
 
-## API Endpoints
+// Cookie
+export const DEFAULT_COOKIE_NAME = 'fsn_refresh_token';
+export const MAX_COOKIE_BYTES = 3500;
 
-### Authentication Endpoints
+// Cache Key Prefixes
+export const SESSION_CACHE_PREFIX = 'auth:session';
+export const TOKEN_REVOKED_PREFIX = 'auth:revoked';
+```
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/auth/login` | POST | Login with email/password |
-| `/auth/register` | POST | Register new user |
-| `/auth/refresh` | POST | Refresh access token |
-| `/auth/logout` | POST | Logout (clears refresh token cookie) |
-| `/auth/change-password` | POST | Change user password |
-| `/auth/me` | GET | Get current user info |
+## Entities
 
-#### GET /auth/me - Get Current User Info
+### Entity Groups
 
-**Purpose:** Retrieve current authenticated user information with optional company/branch context
+```typescript
+// Core entities (always loaded)
+export const CoreEntities = [User, UserToken, PendingRegistration];
 
-**Authentication:** Requires valid access token (Bearer token in Authorization header)
+// Company entities (when enableCompanyFeature: true)
+export const CompanyEntities = [Company, CompanyBranch, UserCompanyPermission];
 
-**Response Behavior:**
+// All entities
+export const AllEntities = [...CoreEntities, ...CompanyEntities];
 
-When `enableCompanyFeature: false`:
-```json
-{
-  "user": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "email": "john@example.com",
-    "name": "John Doe",
-    "profilePictureId": null
-  }
+// Helper function
+export function getEntitiesByConfig(enableCompanyFeature: boolean) {
+  return enableCompanyFeature ? AllEntities : CoreEntities;
 }
 ```
 
-When `enableCompanyFeature: true`:
-```json
-{
-  "user": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "email": "john@example.com",
-    "name": "John Doe",
-    "profilePictureId": null
-  },
-  "company": {
-    "id": "550e8400-e29b-41d4-a716-446655440001",
-    "name": "Acme Corporation",
-    "slug": "acme-corp",
-    "logoId": null
-  },
-  "branch": {
-    "id": "550e8400-e29b-41d4-a716-446655440002",
-    "name": "Main Branch",
-    "slug": "main-branch",
-    "logoId": null
-  }
-}
-```
+### User Entity
 
-**Key Characteristics:**
-- Uses HTTP GET (not POST like other auth endpoints)
-- Returns only user context data (no tokens)
-- `company` and `branch` fields are automatically excluded from Swagger docs when company feature is disabled
-- Used for session restoration on page refresh (frontend calls this after token refresh)
+Extends `UserRoot` from `@flusys/nestjs-shared`:
 
-**Related Service:** `AuthenticationService.getUserInfo()` in `authentication.service.ts`
+| 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 |
 
-### Company Selection Endpoints (when company feature enabled)
+### UserToken Entity
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/auth/select` | POST | Select company and branch after login |
-| `/auth/switch-company` | POST | Switch to different company/branch |
-| `/auth/companies` | GET | Get user's available companies |
-| `/auth/companies/:companyId/branches` | GET | Get branches for a company |
+Stores tokens for existing user actions:
 
-> **Note:** These endpoints are automatically hidden from Swagger when `enableCompanyFeature: false`
+```typescript
+enum TokenType {
+  PASSWORD_RESET = 'password_reset',
+  EMAIL_VERIFICATION = 'email_verification',
+  EMAIL_CHANGE = 'email_change',
+}
+```
 
-### Swagger Schema Behavior
+| 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 |
+| `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 |
+| `name` | `varchar(255)` | Company name |
+| `slug` | `varchar(255)` | URL-friendly identifier |
+| `phone` | `varchar(255)` | Contact phone |
+| `address` | `text` | Address |
+| `logoId` | `uuid` | Reference to storage file |
+| `isActive` | `boolean` | Company status |
+
+### CompanyBranch Entity
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `uuid` | Primary key |
+| `name` | `varchar(255)` | Branch name |
+| `slug` | `varchar(255)` | URL-friendly identifier |
+| `companyId` | `uuid` | Parent company |
+| `parentId` | `uuid` | Parent branch (hierarchical) |
+| `serial` | `int` | Display order |
+| `logoId` | `uuid` | Reference to storage file |
+| `isActive` | `boolean` | Branch status |
+
+### UserCompanyPermission Entity (Polymorphic)
 
-When `enableCompanyFeature: false`, the following are automatically hidden from Swagger:
+```typescript
+enum PermissionType {
+  COMPANY = 'company',
+  BRANCH = 'branch',
+}
+```
 
-**Excluded Tags:**
-- Companies
-- Branches
-- User Permissions (NEW - v4.1.3+)
-- Company Selection
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `uuid` | Primary key |
+| `userId` | `uuid` | Reference to user |
+| `permissionType` | `PermissionType` | company or branch |
+| `targetId` | `uuid` | Company ID or Branch ID |
+| `isActive` | `boolean` | Permission status |
 
-**Excluded DTO Properties:**
+## Provider Interfaces
 
-| DTO | Hidden Fields |
-|-----|---------------|
-| `RegistrationDto` | `companySlug`, `branchSlug`, `newCompanyName`, `newCompanyPhone`, `newCompanyAddress` |
-| `RegistrationResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
-| `LoginResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
-| `MeResponseDto` | `company`, `branch` |
+### AUTH_EMAIL_PROVIDER
 
-### User Management Endpoints (`/administration/users`)
+Allows auth to work independently of the email module:
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/users/insert` | POST | Create user |
-| `/users/insert-many` | POST | Bulk create users |
-| `/users/get/:id` | POST | Get user by ID |
-| `/users/get-all` | POST | Get paginated user list |
-| `/users/update` | POST | Update user |
-| `/users/update-many` | POST | Bulk update users |
-| `/users/delete` | POST | Delete/restore/permanent delete |
-| `/users/profile` | POST | Update own profile |
-| `/users/:id/verify-email` | POST | Mark email as verified |
-| `/users/:id/verify-phone` | POST | Mark phone as verified |
-| `/users/:id/status` | PUT | Update user active status |
-
-### User Permission Endpoints (NEW - when company feature enabled)
+```typescript
+interface IAuthEmailProvider {
+  /** Send password reset email */
+  sendPasswordResetEmail(email: string, token: string, resetUrl: string): Promise<void>;
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/administration/permissions/user-company/assign` | POST | Batch assign/revoke user-company permissions |
-| `/administration/permissions/user-company` | GET | Get user's assigned companies |
-| `/administration/permissions/user-branch/assign` | POST | Batch assign/revoke user-branch permissions |
-| `/administration/permissions/user-branch` | GET | Get user's assigned branches |
+  /** Send email verification email */
+  sendVerificationEmail(email: string, token: string, verifyUrl: string): Promise<void>;
 
-**Example: Assign companies to user**
-```json
-POST /administration/permissions/user-company/assign
-{
-  "userId": "user-123",
-  "items": [
-    { "targetId": "company-1", "isAdd": true },
-    { "targetId": "company-2", "isAdd": true }
-  ]
+  /** Send welcome email after registration (optional) */
+  sendWelcomeEmail?(email: string, name: string): Promise<void>;
 }
 ```
 
-**Example: Revoke branch access**
-```json
-POST /administration/permissions/user-branch/assign
+**Example Implementation:**
+
+```typescript
 {
-  "userId": "user-123",
-  "items": [
-    { "targetId": "branch-5", "isAdd": false }
-  ]
+  provide: AUTH_EMAIL_PROVIDER,
+  useFactory: (emailSendService: EmailSendService) => ({
+    sendPasswordResetEmail: async (email, token, resetUrl) => {
+      await emailSendService.sendTemplateEmail({
+        templateSlug: 'password-reset',
+        to: email,
+        variables: { resetUrl, token },
+      });
+    },
+    sendVerificationEmail: async (email, token, verifyUrl) => {
+      await emailSendService.sendTemplateEmail({
+        templateSlug: 'email-verification',
+        to: email,
+        variables: { verifyUrl, token },
+      });
+    },
+  }),
+  inject: [EmailSendService],
 }
 ```
 
-> **Note:** These endpoints are only available when `enableCompanyFeature: true`
-
-### Company Management Endpoints (`/administration/company`) - When `enableCompanyFeature: true`
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/company/insert` | POST | Create company |
-| `/company/insert-many` | POST | Bulk create companies |
-| `/company/get/:id` | POST | Get company by ID |
-| `/company/get-all` | POST | Get paginated company list |
-| `/company/update` | POST | Update company |
-| `/company/update-many` | POST | Bulk update companies |
-| `/company/delete` | POST | Delete/restore company |
-
-### Branch Management Endpoints (`/administration/branch`) - When `enableCompanyFeature: true`
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/branch/insert` | POST | Create branch |
-| `/branch/insert-many` | POST | Bulk create branches |
-| `/branch/get/:id` | POST | Get branch by ID |
-| `/branch/get-all` | POST | Get paginated branch list (auto-filtered by company) |
-| `/branch/update` | POST | Update branch |
-| `/branch/update-many` | POST | Bulk update branches |
-| `/branch/delete` | POST | Delete/restore branch |
-
-## Architecture
+### USER_ENRICHER
 
-### Module Independence
+Extends user list and profile without modifying base package:
 
+```typescript
+interface IUserEnricher {
+  /** 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[]>;
+
+  /** Get extra profile data (roles, permissions, sections) */
+  getProfileExtras?(
+    userId: string,
+    user: ILoggedUserInfo,
+  ): Promise<IProfileExtras>;
+
+  /** Handle profile update with extra fields */
+  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 (LEADPRO-style)
+  getProfileSections?(): IProfileSection[];
+  getProfileSectionData?(userId, sectionId, user): Promise<IProfileSectionData>;
+  updateProfileSection?(userId, sectionId, data, queryRunner): Promise<void>;
+  handleSectionFileUpload?(userId, sectionId, field, fileInfo, queryRunner): Promise<IProfileFile>;
+  handleSectionFileDelete?(userId, sectionId, field, fileId, queryRunner): Promise<void>;
+  calculateProfileCompletion?(userId, user): Promise<number>;
+}
 ```
-@flusys/nestjs-shared
-├── JwtAuthGuard (validates tokens using Passport)
-└── PermissionGuard (checks permissions from cache)
-         ↓
-@flusys/nestjs-auth
-├── AuthConfigService (JWT settings via AUTH_MODULE_OPTIONS)
-├── JwtStrategy (registers with Passport, validates users)
-├── AuthenticationService (generates tokens)
-├── User management
-└── Company/Branch management (optional)
-```
-
-**Key Points:**
-- ✅ **JwtAuthGuard** in shared → All modules can use without depending on Auth
-- ✅ **JwtStrategy** in auth → Registers JWT validation with Passport
-- ✅ **AuthConfigService** in auth → Provides JWT settings (secret, expiration)
-- ✅ **Token generation** handled by AuthenticationService
-- ✅ **Token validation** uses JwtStrategy registered by Auth module
 
-**Result:** IAM and Storage modules only depend on Shared, not Auth.
-
-### JwtStrategy Architecture
-
-The `JwtStrategy` is a **singleton** (required by Passport), but needs to access the **request-scoped** `AuthDataSourceProvider`. This is solved using `ModuleRef`:
+**Profile Section Interface (for multi-step profiles):**
 
 ```typescript
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
-  constructor(
-    private readonly authConfig: AuthConfigService,
-    private readonly moduleRef: ModuleRef,  // Used to resolve request-scoped providers
-  ) {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      secretOrKey: authConfig.getJwtSecret(),
-      passReqToCallback: true,  // Pass request to validate method
-    });
-  }
-
-  async validate(_req: Request, payload: TokenPayload) {
-    // Resolve request-scoped AuthDataSourceProvider per request
-    const dataSourceProvider = await this.moduleRef.resolve(
-      AuthDataSourceProvider,
-      undefined,
-      { strict: false },
-    );
+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?: string; // Required permission
+}
 
-    const userRepository = await dataSourceProvider.getRepository(User);
-    // ... validate user
-  }
+interface IProfileExtras {
+  roles?: IProfileRole[];
+  actions?: IProfileAction[];
+  sections?: IProfileSectionData[];
+  completionPercentage?: number;
 }
 ```
 
-**Why this pattern:**
-- ✅ Works for both **single-tenant** and **multi-tenant** modes
-- ✅ `AuthDataSourceProvider` handles tenant detection from request headers
-- ✅ Connection pools are cached internally (no reconnect per request)
-- ✅ Singleton strategy + request-scoped provider = best of both worlds
-
-### Package Structure
-
-```
-┌─────────────────────────────────────────────────────────┐
-│         @flusys/nestjs-auth v4.1.2+                     │
-│                                                         │
-│  ┌─────────────────────────────────────────────────┐   │
-│  │           CORE AUTH (Always Loaded)              │   │
-│  │                                                  │   │
-│  │  ┌──────────┐                                    │   │
-│  │  │   User   │                                    │   │
-│  │  └──────────┘                                    │   │
-│  │                                                  │   │
-│  │  • User login/registration                      │   │
-│  │  • Password hashing (bcrypt)                    │   │
-│  │  • JWT token generation                          │   │
-│  │  • JwtStrategy (Passport integration)           │   │
-│  └─────────────────────────────────────────────────┘   │
-│                                                         │
-│  ┌─────────────────────────────────────────────────┐   │
-│  │     COMPANY FEATURE (Optional - Flag Enabled)    │   │
-│  │                                                  │   │
-│  │  ┌─────────┐  ┌──────────────┐  ┌────────────┐ │   │
-│  │  │ Company │  │CompanyBranch │  │UserCompany │ │   │
-│  │  │         │  │              │  │Permission  │ │   │
-│  │  └─────────┘  └──────────────┘  └────────────┘ │   │
-│  │                                                  │   │
-│  │  • Multi-company support                        │   │
-│  │  • Hierarchical branches                        │   │
-│  │  • User-company-branch assignments             │   │
-│  │  • Company-scoped permissions                   │   │
-│  │  • Enhanced login with selection                │   │
-│  └─────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Entity Relationships
-
-#### Without Company Feature (Simple)
-
-```
-┌──────────────┐
-│     User     │
-├──────────────┤
-│ id           │
-│ name         │
-│ email        │◄────── Authentication
-│ password     │
-│ phone        │
-└──────────────┘
-```
-
-#### With Company Feature (Polymorphic Design)
-
-```
-┌──────────────┐       ┌───────────────────┐       ┌──────────────────┐
-│     User     │       │ UserCompany       │       │     Company      │
-├──────────────┤       │ Permission        │       ├──────────────────┤
-│ id           │◄──────┤ userId            │       │ id               │
-│ name         │       │ permissionType    │──────►│ name             │
-│ email        │       │ targetId (UUID)   │       │ slug             │
-│ password     │       │ isActive          │       │ isActive         │
-└──────────────┘       │ metadata          │       └──────────────────┘
-                       └───────────────────┘                │
-                                │                           │
-                permissionType: 'company'|'branch'          ▼
-                targetId: company.id OR branch.id   ┌──────────────────┐
-                                │                   │  CompanyBranch   │
-                                └──────────────────►├──────────────────┤
-                                                    │ id               │
-                                                    │ name, companyId  │
-                                                    │ parentId ◄──┐    │
-                                                    │ isActive    │    │
-                                                    └─────────────┴────┘
-                                                       Hierarchical
-```
-
-**Polymorphic Permission Design:**
-- `permissionType`: Enum ('company' | 'branch') determines target type
-- `targetId`: UUID of the company OR branch (single field, not both)
-- One table handles both company and branch permissions
-
-### Services
+## 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 (pending registration or existing user) |
+| `resendVerificationEmail(email, verifyUrlBase)` | Resend verification email |
+| `cleanupExpired()` | Clean up expired tokens and pending registrations |
+
+**Token Expiry:**
+- Password Reset: 1 hour
+- Email Verification: 24 hours
+
+## API Endpoints
+
+### Authentication Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/auth/login` | POST | Login with email/password |
+| `/auth/register` | POST | Register new user |
+| `/auth/refresh` | POST | Refresh access token |
+| `/auth/logout` | POST | Logout (revokes all tokens) |
+| `/auth/change-password` | POST | Change user password |
+| `/auth/me` | GET | Get current user info |
+
+### Email Authentication Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/auth/forgot-password` | POST | Request password reset email |
+| `/auth/reset-password` | POST | Reset password using token |
+| `/auth/verify-email` | POST | Verify email using token |
+| `/auth/resend-verification` | POST | Resend email verification link |
+
+> **Note:** Email endpoints require `AUTH_EMAIL_PROVIDER` to be configured.
+
+### Company Selection Endpoints (when company feature enabled)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/auth/select` | POST | Select company and branch after login |
+| `/auth/switch-company` | POST | Switch to different company/branch |
+| `/auth/companies` | GET | Get user's available companies |
+| `/auth/companies/:companyId/branches` | GET | Get branches for a company |
+
+### User Management Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/administration/users/insert` | POST | Create user |
+| `/administration/users/insert-many` | POST | Bulk create users |
+| `/administration/users/get/:id` | POST | Get user by ID |
+| `/administration/users/get-all` | POST | Get paginated user list |
+| `/administration/users/update` | POST | Update user |
+| `/administration/users/update-many` | POST | Bulk update users |
+| `/administration/users/delete` | POST | Delete/restore/permanent delete |
+| `/administration/users/profile` | POST | Update own profile |
+| `/administration/users/:id/verify-email` | POST | Mark email as verified |
+| `/administration/users/:id/verify-phone` | POST | Mark phone as verified |
+| `/administration/users/:id/status` | PUT | Update user active status |
+
+### User Permission Endpoints (when company feature enabled)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/administration/permissions/user-company/assign` | POST | Batch assign/revoke user-company permissions |
+| `/administration/permissions/user-company` | GET | Get user's assigned companies |
+| `/administration/permissions/user-branch/assign` | POST | Batch assign/revoke user-branch permissions |
+| `/administration/permissions/user-branch` | GET | Get user's assigned branches |
+
+### Company/Branch Management Endpoints (when company feature enabled)
+
+| Resource | Endpoints |
+|----------|-----------|
+| Companies | `/administration/company` - CRUD operations |
+| Branches | `/administration/branch` - CRUD operations |
 
 ## Login Flows
 
@@ -507,8 +544,10 @@ POST /auth/login { email, password }
 │  .login()               │
 └────────────┬────────────┘
              │
-             │ 1. Verify credentials
-             │ 2. Generate JWT token
+             │ 1. Check pending registration
+             │ 2. Verify credentials
+             │ 3. Check email verified (if email enabled)
+             │ 4. Generate JWT tokens
              ▼
     { accessToken, refreshToken, user }
 ```
@@ -537,56 +576,148 @@ POST /auth/login { email, password }
 POST /auth/login { email, password }
               │
               ▼
-┌─────────────────────────┐
-│  AuthenticationService  │
-│  .login()               │
-└────────────┬────────────┘
-             │
-             │ Found: Multiple companies/branches
-             ▼
     { requiresSelection: true, sessionId, companies: [...] }
-             │
-             │ User selects company & branch
-             ▼
+              │
+              │ User selects company & branch
+              ▼
 POST /auth/select { sessionId, companyId, branchId }
-             │
-             ▼
-┌─────────────────────────┐
-│  AuthenticationService  │
-│  .select()              │
-└────────────┬────────────┘
-             │
-             │ 1. Validate access via UserCompanyPermission
-             │ 2. Generate token with company context
-             ▼
+              │
+              ▼
     { accessToken, refreshToken, user, company, branch }
 ```
 
+### Login with Email Verification Required
+
+```
+POST /auth/login { email, password }
+              │
+              ▼
+    If pending registration OR email not verified:
+    { requiresEmailVerification: true, email, message }
+```
+
+## Email Verification Flow
+
+### New User Registration (with email enabled)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 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? }
+```
+
+### Password Reset Flow
+
+```
+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
 
-### User Active Status
+### Company Permission Assignment Flow
+
+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' }         │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-The `PUT /users/:id/status` endpoint handles user active status based on company feature setting:
+### User Active Status
 
 **When company feature is disabled:**
 - Updates `User.isActive` directly
-- Simple on/off for the user globally
 
 **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
-- `getAll` users filters by company permissions
-- `isActive` in responses reflects company permission status
 
-### Registration Flow
+### Registration Flows
 
 **Simple registration:**
 ```json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123"
-}
+{ "name": "John Doe", "email": "john@example.com", "password": "password123" }
 ```
 
 **Join existing company:**
@@ -607,160 +738,146 @@ The `PUT /users/:id/status` endpoint handles user active status based on company
   "email": "john@example.com",
   "password": "password123",
   "newCompanyName": "My Company",
-  "newBranchName": "Headquarters"
+  "newCompanyPhone": "+1234567890",
+  "newCompanyAddress": "123 Main St"
 }
 ```
 
-### Hierarchical Branch Structure
-
-```
-Company: "Acme Corporation"
-│
-├── Main Office (Branch)
-│   ├── Sales Department (Sub-Branch)
-│   │   ├── Inside Sales (Sub-Sub-Branch)
-│   │   └── Outside Sales
-│   └── Support Department
-│       ├── Tier 1 Support
-│       └── Tier 2 Support
-│
-└── Regional Office (Branch)
-    ├── East Branch
-    └── West Branch
-```
+## No-IAM Mode
 
-## Environment Variables
+When not using `@flusys/nestjs-iam` but controllers use `level: 'permission'` security, set wildcard permissions after login:
 
-```env
-# Database
-DB_HOST=localhost
-DB_PORT=3306
-DB_USERNAME=root
-DB_PASSWORD=password
-DB_DATABASE=myapp
+```typescript
+import { HybridCache, CACHE_INSTANCE, PERMISSIONS_CACHE_PREFIX } from '@flusys/nestjs-shared';
 
-# JWT
-JWT_SECRET=your-secret-key-change-in-production
-JWT_EXPIRATION=1h
-REFRESH_TOKEN_SECRET=your-refresh-secret
-REFRESH_TOKEN_EXPIRATION=7d
-REFRESH_TOKEN_COOKIE_NAME=fsn_refresh_token
-```
+@Injectable()
+export class AuthenticationService {
+  constructor(
+    @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
+  ) {}
 
-## Migrations
+  async login(dto: LoginDto): Promise<LoginResponse> {
+    // ... validate credentials, generate tokens
 
-See [MIGRATION.md](./MIGRATION.md) for detailed migration commands.
+    // When IAM is NOT used, grant all permissions via wildcard
+    await this.setWildcardPermissions(user.id);
 
-### Quick Commands
+    return { accessToken, user };
+  }
 
-```bash
-# Generate migration
-npm run migration:generate --name=InitialSetup
+  private async setWildcardPermissions(userId: string): Promise<void> {
+    const cacheKey = `${PERMISSIONS_CACHE_PREFIX}:user:${userId}`;
+    await this.cache.set(cacheKey, ['*'], 86400000); // 24 hours TTL
+  }
+}
+```
 
-# Run migrations
-npm run migration:run
+### With Company Feature Enabled
 
-# Check status
-npm run migration:status
+```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);
+  }
+}
 ```
 
-## Configuration Modes
-
-### Mode 1: Minimal (No Companies)
+### Wildcard Permission Patterns
 
-```typescript
-AuthModule.forRoot({
-  bootstrapAppConfig: {
-    enableCompanyFeature: false,
-  },
-})
+| Pattern | Meaning |
+|---------|---------|
+| `*` | Full access to everything |
+| `user.*` | All user permissions |
+| `branch.*` | All branch permissions |
 
-Entities:   User
-Tables:     1
-Features:   Basic login, registration
-Size:       Minimal
-Performance: Fast
-```
+## API Reference
 
-### Mode 2: Full Featured (With Companies)
+### Exports
 
 ```typescript
-AuthModule.forRoot({
-  includeIAM: true, // If using IAM module
-  bootstrapAppConfig: {
-    enableCompanyFeature: true,
-  },
-})
+// Config
+export { AUTH_MODULE_OPTIONS, BCRYPT_SALT_ROUNDS, DEFAULT_COOKIE_NAME, MAX_COOKIE_BYTES, SESSION_CACHE_PREFIX, TOKEN_REVOKED_PREFIX } from './config';
 
-Entities:   User, Company, CompanyBranch, UserCompanyPermission
-            (+ IAM entities if includeIAM: true)
-Tables:     4 (or more with IAM)
-Features:   Multi-tenant, hierarchical branches
-Size:       Complete
-Performance: Scalable
-```
+// 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 { CoreEntities, CompanyEntities, AllEntities, getEntitiesByConfig } from './entities';
 
-## IAM Integration
+// Enums
+export { PermissionType } from './enums';
 
-### Why includeIAM Flag?
+// Interfaces
+export { IAuthEmailProvider, AUTH_EMAIL_PROVIDER } from './interfaces/auth-email-provider.interface';
+export { IUserEnricher, IProfileSection, IProfileExtras, IEnrichedUser } from './interfaces/user-enricher.interface';
+export { AuthModuleOptions, AuthModuleAsyncOptions, AuthOptionsFactory } from './interfaces/auth-module-options.interface';
+export { TokenPayload, TokenPayloadWithCompany, LoginResponse, MeResponse, RegistrationResponse } from './interfaces/authentication.interface';
 
-When using `@flusys/nestjs-iam` with Auth module in **single-tenant mode**, TypeORM needs to know about all entities during initialization.
+// 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';
 
-**The Problem:**
-```typescript
-// Auth module calls TypeOrmModule.forRoot() with auth entities
-TypeOrmModule.forRoot({ entities: [User, Company, ...] })
+// Modules
+export { AuthModule } from './modules/auth.module';
 
-// IAM module tries to use forFeature() but entities not registered
-TypeOrmModule.forFeature([Action, Role, Permission]) // ❌ Error!
-```
+// Strategies
+export { JwtStrategy } from './strategies/jwt.strategy';
 
-**The Solution:**
-```typescript
-// Auth module dynamically includes IAM entities when includeIAM: true
-AuthModule.forRoot({
-  includeIAM: true, // Auth module loads IAM entities
-  // ...
-})
+// Interceptors
+export { SetToken } from './interceptors/set-token.interceptor';
+export { ClearToken } from './interceptors/clear-token.interceptor';
+
+// DTOs
+export * from './dtos';
 
-// Now TypeORM knows about all entities
-TypeOrmModule.forRoot({
-  entities: [User, Company, Action, Role, Permission, ...]
-}) // ✅ Works!
+// Swagger Config
+export { authSwaggerConfig } from './docs/auth-swagger.config';
 ```
 
-**When to use:**
-- ✅ Single-tenant mode + IAM module → `includeIAM: true`
-- ❌ Multi-tenant mode → Not needed (each tenant has own connection)
-- ❌ Not using IAM → `includeIAM: false` (default)
+### Module Static Methods
 
-### Architecture
+```typescript
+// Get entities based on feature flags
+AuthModule.getEntities(enableCompanyFeature?: boolean): any[]
 
-```
-App Module
-├── AuthModule.forRoot({ includeIAM: true })
-│   └── TypeOrmModule.forRoot([Auth entities + IAM entities])
-│
-└── IAMModule.forRoot()
-    └── TypeOrmModule.forFeature([IAM entities])
+// Configure module
+AuthModule.forRoot(options: AuthModuleOptions): DynamicModule
+AuthModule.forRootAsync(options: AuthModuleAsyncOptions): DynamicModule
 ```
 
-Auth module is responsible for database connection, but dynamically includes IAM entities when requested. This maintains separation while solving the TypeORM registration requirement.
+### Swagger Schema Behavior
 
----
+When `enableCompanyFeature: false`, the following are automatically hidden from Swagger:
 
-## Summary
+**Excluded Tags:** Companies, Branches, User Permissions, Company Selection
 
-The authentication package provides:
+**Excluded DTO Properties:**
 
-- **Flexibility** - Use simple or complex mode
-- **Scalability** - Grows with your needs
-- **Type Safety** - Full TypeScript support
-- **Clean Design** - Clear separation of concerns
-- **IAM Integration** - Seamless permission management
-- **Well Organized** - Logical module structure
-- **Performance** - Only load what you need
+| DTO | Hidden Fields |
+|-----|---------------|
+| `RegistrationDto` | `companySlug`, `branchSlug`, `newCompanyName`, `newCompanyPhone`, `newCompanyAddress` |
+| `RegistrationResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
+| `LoginResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
+| `MeResponseDto` | `company`, `branch` |
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-21