@flusys/nestjs-auth 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Authentication Package Guide
 
 > **Package:** `@flusys/nestjs-auth`
+> **Version:** 3.0.0
 > **Type:** Authentication system with JWT, email verification, multi-tenant, and company/branch support
 
 ## Table of Contents
@@ -17,6 +18,9 @@
 - [Email Verification Flow](#email-verification-flow)
 - [User Management](#user-management)
 - [No-IAM Mode](#no-iam-mode)
+- [JWT Strategy](#jwt-strategy)
+- [Interceptors](#interceptors)
+- [Validators](#validators)
 - [API Reference](#api-reference)
 
 ---
@@ -153,6 +157,7 @@ interface AuthModuleOptions {
   bootstrapAppConfig?: {
     databaseMode: 'single' | 'multi-tenant';
     enableCompanyFeature: boolean;
+    enableEmailVerification?: boolean; // Default: true
   };
   config?: {
     defaultDatabaseConfig?: IDatabaseConfig;
@@ -169,6 +174,13 @@ interface AuthModuleOptions {
 }
 ```
 
+**Bootstrap Configuration Flags:**
+
+| 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
 
 ```typescript
@@ -192,22 +204,53 @@ export const TOKEN_REVOKED_PREFIX = 'auth:revoked';
 
 ### Entity Groups
 
-```typescript
-// Core entities (always loaded)
-export const CoreEntities = [User, UserToken, PendingRegistration];
+The auth module organizes entities into groups based on feature flags:
 
-// Company entities (when enableCompanyFeature: true)
-export const CompanyEntities = [Company, CompanyBranch, UserCompanyPermission];
+```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
+}
 
-// All entities
-export const AllEntities = [...CoreEntities, ...CompanyEntities];
+// Get entities based on feature flags (exported)
+export function getEntitiesByConfig(config: IAuthEntitiesConfig): any[] {
+  const { enableCompanyFeature = false, enableEmailVerification = true } = config;
 
-// Helper function
-export function getEntitiesByConfig(enableCompanyFeature: boolean) {
-  return enableCompanyFeature ? AllEntities : CoreEntities;
+  const entities = [User, UserToken];
+  if (enableEmailVerification) entities.push(PendingRegistration);
+  if (enableCompanyFeature) entities.push(Company, CompanyBranch, UserCompanyPermission);
+  return entities;
 }
 ```
 
+**Usage:**
+```typescript
+import { getEntitiesByConfig } from '@flusys/nestjs-auth/entities';
+
+// Get entities for single database without company feature
+const entities = getEntitiesByConfig({ enableCompanyFeature: false });
+// Returns: [User, UserToken, PendingRegistration]
+
+// Get entities with company feature, no email verification
+const entities = getEntitiesByConfig({ enableCompanyFeature: true, enableEmailVerification: false });
+// Returns: [User, UserToken, Company, CompanyBranch, UserCompanyPermission]
+```
+
+**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 |
+
 ### User Entity
 
 Extends `UserRoot` from `@flusys/nestjs-shared`:
@@ -271,6 +314,7 @@ Stores registration data until email verification (prevents garbage accounts):
 | `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:**
@@ -283,25 +327,48 @@ Stores registration data until email verification (prevents garbage accounts):
 | 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 |
+| `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 |
-| `companyId` | `uuid` | Parent company |
-| `parentId` | `uuid` | Parent branch (hierarchical) |
+| `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 |
-| `logoId` | `uuid` | Reference to storage file |
-| `isActive` | `boolean` | Branch status |
+| `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)
 
@@ -316,9 +383,22 @@ enum PermissionType {
 |-------|------|-------------|
 | `id` | `uuid` | Primary key |
 | `userId` | `uuid` | Reference to user |
-| `permissionType` | `PermissionType` | company or branch |
+| `permissionType` | `varchar(50)` | company or branch |
 | `targetId` | `uuid` | Company ID or Branch ID |
-| `isActive` | `boolean` | Permission status |
+| `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
 
@@ -370,6 +450,8 @@ Extends user list and profile without modifying base package:
 
 ```typescript
 interface IUserEnricher {
+  // ===== List Enrichment =====
+
   /** Enrich user list query with extra joins/selects */
   enrichListQuery?(
     query: SelectQueryBuilder<User>,
@@ -382,13 +464,15 @@ interface IUserEnricher {
     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 */
+  /** Handle profile update with extra fields (within transaction) */
   updateProfileExtras?(
     userId: string,
     extras: Record<string, any>,
@@ -402,27 +486,92 @@ interface IUserEnricher {
     user: ILoggedUserInfo,
   ): Promise<void>;
 
-  // Multi-Step Profile Methods (LEADPRO-style)
+  // ===== Multi-Step Profile Methods =====
+
+  /** Get profile section definitions for multi-step profiles */
   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>;
+
+  /** 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>;
 }
 ```
 
-**Profile Section Interface (for multi-step profiles):**
+**Profile Related Interfaces:**
 
 ```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?: string; // Required permission
+  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 {
@@ -431,6 +580,73 @@ interface IProfileExtras {
   sections?: IProfileSectionData[];
   completionPercentage?: number;
 }
+
+interface IProfileRole {
+  id: string;
+  name: string;
+  description?: string | null;
+}
+
+interface IProfileAction {
+  id: string;
+  name: string;
+  code: string;
+  description?: string | null;
+}
+
+type IEnrichedUser = IUser & IProfileExtras;
+```
+
+**Registration Hook Example (UserProfileInfo):**
+
+```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);
+  }
+}
+
+// Register the provider
+{
+  provide: USER_ENRICHER,
+  useClass: MyUserEnricher,
+}
+```
+
+**Registration with additionalFields:**
+
+```json
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "password": "password123",
+  "additionalFields": {
+    "prevCompanyName": "Acme Corp",
+    "prevCompanyLocation": "New York"
+  }
+}
 ```
 
 ## Services
@@ -458,7 +674,7 @@ Token Security: All tokens are stored as SHA-256 hashes. Raw tokens are sent to
 | `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) |
+| `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 |
 
@@ -466,70 +682,204 @@ Token Security: All tokens are stored as SHA-256 hashes. Raw tokens are sent to
 - 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 |
+
 ## API Endpoints
 
+> **Note:** All endpoints use POST method following POST-only RPC pattern.
+
 ### 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 |
+| 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 | 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 |
+| 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.
+> **Note:** Email endpoints require `AUTH_EMAIL_PROVIDER` to be configured and `enableEmailVerification: true`.
 
 ### 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 |
+| 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 | 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 |
+| 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 | 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 |
+| 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
 
@@ -743,6 +1093,22 @@ User Creation (with companyId/branchId)
 }
 ```
 
+**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"
+  }
+}
+```
+
+> **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.
+
 ## No-IAM Mode
 
 When not using `@flusys/nestjs-iam` but controllers use `level: 'permission'` security, set wildcard permissions after login:
@@ -798,13 +1164,112 @@ private async setWildcardPermissions(
 | `user.*` | All user permissions |
 | `branch.*` | All branch permissions |
 
+## JWT Strategy
+
+The `JwtStrategy` is a singleton Passport strategy that validates JWT tokens and extracts user info.
+
+**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
+}
+
+// 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
+}
+```
+
+**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
+
+**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
+
+### SetToken Interceptor
+
+Automatically sets refresh token as HTTP-only cookie for browser clients:
+
+```typescript
+@UseInterceptors(SetToken)
+async login(@Body() loginDto: LoginDto) { ... }
+```
+
+**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'`
+
+### ClearToken Interceptor
+
+Clears refresh token cookie on logout:
+
+```typescript
+@UseInterceptors(ClearToken)
+async logout(@CurrentUser('id') userId: string) { ... }
+```
+
+## Validators
+
+### IsStrongPassword
+
+Custom password validation decorator:
+
+```typescript
+@IsStrongPassword()
+password!: string;
+
+// With custom options
+@IsStrongPassword({ minLength: 12, requireSpecialChar: false })
+password!: string;
+```
+
+**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 (`!@#$%^&*()_+-=[]{}...`)
+
+**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
 
 ### Exports
 
 ```typescript
 // Config
-export { AUTH_MODULE_OPTIONS, BCRYPT_SALT_ROUNDS, DEFAULT_COOKIE_NAME, MAX_COOKIE_BYTES, SESSION_CACHE_PREFIX, TOKEN_REVOKED_PREFIX } from './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';
@@ -813,16 +1278,19 @@ 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';
+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, 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';
+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';
@@ -838,6 +1306,15 @@ export { CompanySelectionSessionService } from './services/company-selection-ses
 // 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';
 
@@ -845,6 +1322,9 @@ export { JwtStrategy } from './strategies/jwt.strategy';
 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';
 
@@ -855,14 +1335,49 @@ export { authSwaggerConfig } from './docs/auth-swagger.config';
 ### Module Static Methods
 
 ```typescript
-// Get entities based on feature flags
-AuthModule.getEntities(enableCompanyFeature?: boolean): any[]
+// Get entities based on feature flags (requires IBootstrapAppConfig)
+AuthModule.getEntities(config: IBootstrapAppConfig): any[]
+
+// Examples:
+AuthModule.getEntities({ enableCompanyFeature: false })
+// Returns: [User, UserToken, PendingRegistration]
 
-// Configure module
+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
+
+// Configure module asynchronously
 AuthModule.forRootAsync(options: AuthModuleAsyncOptions): DynamicModule
 ```
 
+**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
+}
+```
+
 ### Swagger Schema Behavior
 
 When `enableCompanyFeature: false`, the following are automatically hidden from Swagger:
@@ -880,4 +1395,4 @@ When `enableCompanyFeature: false`, the following are automatically hidden from
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25