@flusys/nestjs-auth 1.0.0-rc → 2.0.0

package/README.md

@@ -1,7 +1,7 @@
 # Authentication Package Guide
 
 > **Package:** `@flusys/nestjs-auth`
-> **Type:** Authentication system with JWT, multi-tenant, and company/branch support
+> **Type:** Authentication system with JWT, email verification, multi-tenant, and company/branch support
 
 ## Table of Contents
 
@@ -9,13 +9,15 @@
 - [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)
+- [No-IAM Mode](#no-iam-mode)
+- [API Reference](#api-reference)
 
 ---
 
@@ -44,10 +46,10 @@ import { AuthModule } from '@flusys/nestjs-auth';
       },
       config: {
         defaultDatabaseConfig: {
-          type: 'mysql',
+          type: 'postgres',
           host: 'localhost',
-          port: 3306,
-          username: 'root',
+          port: 5432,
+          username: 'postgres',
           password: 'password',
           database: 'myapp',
         },
@@ -71,14 +73,7 @@ AuthModule.forRoot({
     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',
@@ -99,10 +94,10 @@ AuthModule.forRoot({
   },
   config: {
     tenantDefaultDatabaseConfig: {
-      type: 'mysql',
+      type: 'postgres',
       host: 'localhost',
-      port: 3306,
-      username: 'root',
+      port: 5432,
+      username: 'postgres',
       password: 'password',
     },
     tenants: [
@@ -114,18 +109,36 @@ AuthModule.forRoot({
 })
 ```
 
-### Async Configuration
+### With Email Provider (Password Reset, Email Verification)
 
 ```typescript
-AuthModule.forRootAsync({
-  global: true,
-  includeController: true,
-  bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: false,
-  },
-  imports: [HttpModule],
-  useClass: AuthConfigFactory,
+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],
+    },
+  ],
 })
 ```
 
@@ -146,20 +159,18 @@ interface AuthModuleOptions {
     tenantDefaultDatabaseConfig?: IDatabaseConfig;
     tenants?: ITenantDatabaseConfig[];
     jwtSecret?: string;
-    jwtExpiration?: string;
+    jwtExpiration?: string;             // Default: '1h'
     refreshTokenSecret?: string;
-    refreshTokenExpiration?: string;
-    refreshTokenCookieName?: string;   // Default: 'fsn_refresh_token'
-    frontendUrl?: string;              // For email links
+    refreshTokenExpiration?: string;    // Default: '7d'
+    refreshTokenCookieName?: string;    // Default: 'fsn_refresh_token'
+    frontendUrl?: string;               // For email links
   };
-  providers?: Provider[];              // Additional providers (e.g., AUTH_EMAIL_PROVIDER)
+  providers?: Provider[];               // Additional providers (AUTH_EMAIL_PROVIDER, USER_ENRICHER)
 }
 ```
 
 ## Constants
 
-Centralized constants in `auth.constants.ts`:
-
 ```typescript
 // Injection Tokens
 export const AUTH_MODULE_OPTIONS = 'AUTH_MODULE_OPTIONS';
@@ -177,6 +188,284 @@ export const SESSION_CACHE_PREFIX = 'auth:session';
 export const TOKEN_REVOKED_PREFIX = 'auth:revoked';
 ```
 
+## Entities
+
+### Entity Groups
+
+```typescript
+// Core entities (always loaded)
+export const CoreEntities = [User, UserToken, PendingRegistration];
+
+// Company entities (when enableCompanyFeature: true)
+export const CompanyEntities = [Company, CompanyBranch, UserCompanyPermission];
+
+// All entities
+export const AllEntities = [...CoreEntities, ...CompanyEntities];
+
+// Helper function
+export function getEntitiesByConfig(enableCompanyFeature: boolean) {
+  return enableCompanyFeature ? AllEntities : CoreEntities;
+}
+```
+
+### User Entity
+
+Extends `UserRoot` from `@flusys/nestjs-shared`:
+
+| 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 |
+
+### UserToken Entity
+
+Stores tokens for existing user actions:
+
+```typescript
+enum TokenType {
+  PASSWORD_RESET = 'password_reset',
+  EMAIL_VERIFICATION = 'email_verification',
+  EMAIL_CHANGE = 'email_change',
+}
+```
+
+| 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)
+
+```typescript
+enum PermissionType {
+  COMPANY = 'company',
+  BRANCH = 'branch',
+}
+```
+
+| 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 |
+
+## Provider Interfaces
+
+### AUTH_EMAIL_PROVIDER
+
+Allows auth to work independently of the email module:
+
+```typescript
+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>;
+}
+```
+
+**Example Implementation:**
+
+```typescript
+{
+  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],
+}
+```
+
+### USER_ENRICHER
+
+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>;
+}
+```
+
+**Profile Section Interface (for multi-step profiles):**
+
+```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
+}
+
+interface IProfileExtras {
+  roles?: IProfileRole[];
+  actions?: IProfileAction[];
+  sections?: IProfileSectionData[];
+  completionPercentage?: number;
+}
+```
+
+## 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
@@ -186,7 +475,7 @@ export const TOKEN_REVOKED_PREFIX = 'auth:revoked';
 | `/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/logout` | POST | Logout (revokes all tokens) |
 | `/auth/change-password` | POST | Change user password |
 | `/auth/me` | GET | Get current user info |
 
@@ -199,42 +488,7 @@ export const TOKEN_REVOKED_PREFIX = 'auth:revoked';
 | `/auth/verify-email` | POST | Verify email using token |
 | `/auth/resend-verification` | POST | Resend email verification link |
 
-> **Note:** Email endpoints require `AuthEmailService` to be configured via the `providers` option.
-
-#### GET /auth/me - Get Current User Info
-
-**Authentication:** Requires valid access token (Bearer token)
-
-When `enableCompanyFeature: false`:
-```json
-{
-  "user": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "email": "john@example.com",
-    "name": "John Doe",
-    "profilePictureId": null
-  }
-}
-```
-
-When `enableCompanyFeature: true`:
-```json
-{
-  "user": { ... },
-  "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
-  }
-}
-```
+> **Note:** Email endpoints require `AUTH_EMAIL_PROVIDER` to be configured.
 
 ### Company Selection Endpoints (when company feature enabled)
 
@@ -245,21 +499,6 @@ When `enableCompanyFeature: true`:
 | `/auth/companies` | GET | Get user's available companies |
 | `/auth/companies/:companyId/branches` | GET | Get branches for a company |
 
-### Swagger Schema Behavior
-
-When `enableCompanyFeature: false`, the following are automatically hidden from Swagger:
-
-**Excluded Tags:** Companies, Branches, User Permissions, Company Selection
-
-**Excluded DTO Properties:**
-
-| DTO | Hidden Fields |
-|-----|---------------|
-| `RegistrationDto` | `companySlug`, `branchSlug`, `newCompanyName`, `newCompanyPhone`, `newCompanyAddress` |
-| `RegistrationResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
-| `LoginResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
-| `MeResponseDto` | `company`, `branch` |
-
 ### User Management Endpoints
 
 | Endpoint | Method | Description |
@@ -285,18 +524,6 @@ When `enableCompanyFeature: false`, the following are automatically hidden from
 | `/administration/permissions/user-branch/assign` | POST | Batch assign/revoke user-branch permissions |
 | `/administration/permissions/user-branch` | GET | Get user's assigned branches |
 
-**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 }
-  ]
-}
-```
-
 ### Company/Branch Management Endpoints (when company feature enabled)
 
 | Resource | Endpoints |
@@ -304,134 +531,6 @@ POST /administration/permissions/user-company/assign
 | Companies | `/administration/company` - CRUD operations |
 | Branches | `/administration/branch` - CRUD operations |
 
-## Architecture
-
-### Module Independence
-
-```
-@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
-- Token generation handled by AuthenticationService
-- Token validation uses JwtStrategy registered by Auth module
-
-### JwtStrategy Architecture
-
-The `JwtStrategy` is a singleton but needs to access the request-scoped `AuthDataSourceProvider`. This is solved using `ModuleRef`:
-
-```typescript
-@Injectable()
-export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
-  constructor(
-    private readonly authConfig: AuthConfigService,
-    private readonly moduleRef: ModuleRef,
-  ) {
-    super({
-      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
-      secretOrKey: authConfig.getJwtSecret(),
-      passReqToCallback: true,
-    });
-  }
-
-  async validate(_req: Request, payload: TokenPayload) {
-    const dataSourceProvider = await this.moduleRef.resolve(
-      AuthDataSourceProvider,
-      undefined,
-      { strict: false },
-    );
-    const userRepository = await dataSourceProvider.getRepository(User);
-    // ... validate user
-  }
-}
-```
-
-### Package Structure
-
-```
-┌─────────────────────────────────────────────────────────┐
-│         @flusys/nestjs-auth                              │
-│                                                          │
-│  ┌─────────────────────────────────────────────────┐    │
-│  │           CORE AUTH (Always Loaded)              │    │
-│  │                                                  │    │
-│  │  • User login/registration                      │    │
-│  │  • Password hashing (bcrypt)                    │    │
-│  │  • JWT token generation                          │    │
-│  │  • JwtStrategy (Passport integration)           │    │
-│  └─────────────────────────────────────────────────┘    │
-│                                                          │
-│  ┌─────────────────────────────────────────────────┐    │
-│  │     COMPANY FEATURE (Optional - Flag Enabled)    │    │
-│  │                                                  │    │
-│  │  • Multi-company support                        │    │
-│  │  • Hierarchical branches                        │    │
-│  │  • User-company-branch assignments             │    │
-│  │  • Company-scoped permissions                   │    │
-│  │  • Enhanced login with selection                │    │
-│  └─────────────────────────────────────────────────┘    │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Entity Relationships
-
-#### Without Company Feature
-
-```
-┌──────────────┐
-│     User     │
-├──────────────┤
-│ id, name     │
-│ email        │◄── Authentication
-│ password     │
-│ phone        │
-└──────────────┘
-```
-
-#### With Company Feature (Polymorphic Design)
-
-```
-┌──────────────┐       ┌───────────────────┐       ┌──────────────────┐
-│     User     │       │ UserCompany       │       │     Company      │
-├──────────────┤       │ Permission        │       ├──────────────────┤
-│ id           │◄──────┤ userId            │       │ id, name, slug   │
-│ name, email  │       │ permissionType    │──────►│ isActive         │
-│ password     │       │ targetId (UUID)   │       └──────────────────┘
-└──────────────┘       │ isActive          │                │
-                       └───────────────────┘                ▼
-                                │               ┌──────────────────┐
-                permissionType: 'company'|'branch' │  CompanyBranch   │
-                targetId: company.id OR branch.id  │ id, name, companyId │
-                                └──────────────►│ parentId (hierarchical) │
-                                                └──────────────────┘
-```
-
-### Services
-
-| Service | Scope | Description |
-|---------|-------|-------------|
-| `AuthenticationService` | REQUEST | Login, register, token management, company selection |
-| `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` | SINGLETON | Email verification and password reset |
-
 ## Login Flows
 
 ### Simple Mode (Company Feature Disabled)
@@ -445,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 }
 ```
@@ -485,76 +586,124 @@ POST /auth/select { sessionId, companyId, branchId }
     { 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
 
 ### Company Permission Assignment Flow
 
-When creating users with `enableCompanyFeature: true`, the `UserService` automatically assigns company and branch permissions:
-
-**Flow Diagram:**
+When creating users with `enableCompanyFeature: true`, permissions are automatically assigned:
 
 ```
 User Creation (with companyId/branchId)
                 │
                 ▼
-┌─────────────────────────────────────────────────────────┐
-│ 1. Insert user record                                   │
-└─────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. Insert user record                                           │
+└─────────────────────────────────────────────────────────────────┘
                 │
                 ▼
-┌─────────────────────────────────────────────────────────┐
-│ 2. Check if company permission exists                   │
-│    - Lookup UserCompanyPermission for user + company    │
-└─────────────────────────────────────────────────────────┘
-                │
-       exists? ─┴── no ──┐
-         │               │
-         ▼               ▼
-    [Skip]          ┌─────────────────────────────────────┐
-                    │ 3. Create company permission record │
-                    │    { userId, targetId: companyId,   │
-                    │      permissionType: 'company' }    │
-                    └─────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. Check if company permission exists                           │
+│    - Lookup UserCompanyPermission for user + company            │
+│    - If not exists: create { userId, targetId: companyId,       │
+│                              permissionType: 'company' }        │
+└─────────────────────────────────────────────────────────────────┘
                 │
                 ▼
-┌─────────────────────────────────────────────────────────┐
-│ 4. Check if branch permission exists                    │
-│    - Lookup UserCompanyPermission for user + branch     │
-└─────────────────────────────────────────────────────────┘
-                │
-       exists? ─┴── no ──┐
-         │               │
-         ▼               ▼
-    [Skip]          ┌─────────────────────────────────────┐
-                    │ 5. Create branch permission record  │
-                    │    { userId, targetId: branchId,    │
-                    │      permissionType: 'branch' }     │
-                    └─────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. Check if branch permission exists                            │
+│    - Lookup UserCompanyPermission for user + branch             │
+│    - If not exists: create { userId, targetId: branchId,        │
+│                              permissionType: 'branch' }         │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
-**Code Example:**
-
-```typescript
-// When inserting a user with company feature enabled
-await userService.insert({
-  name: 'John Doe',
-  email: 'john@example.com',
-  password: 'securePassword123',
-  companyId: 'company-uuid',
-  branchId: 'branch-uuid',
-});
-// UserService automatically:
-// 1. Creates user record
-// 2. Creates UserCompanyPermission with targetId=companyId
-// 3. Creates UserCompanyPermission with targetId=branchId
-```
-
-**Key Points:**
-- Permissions are created idempotently (won't duplicate if exists)
-- Both company and branch permissions are required for user login flow
-- Branch permission uses `permissionType: 'branch'` to distinguish from company
-- This logic runs within a transaction for consistency
-
 ### User Active Status
 
 **When company feature is disabled:**
@@ -564,7 +713,7 @@ await userService.insert({
 - Updates `UserCompanyPermission.isActive` for the logged user's company
 - User can be active in Company A but inactive in Company B
 
-### Registration Flow
+### Registration Flows
 
 **Simple registration:**
 ```json
@@ -573,94 +722,30 @@ await userService.insert({
 
 **Join existing company:**
 ```json
-{ "name": "John Doe", "email": "john@example.com", "password": "password123",
-  "companySlug": "acme-corp", "branchSlug": "main-branch" }
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "password": "password123",
+  "companySlug": "acme-corp",
+  "branchSlug": "main-branch"
+}
 ```
 
 **Create new company:**
 ```json
-{ "name": "John Doe", "email": "john@example.com", "password": "password123",
-  "newCompanyName": "My Company", "newBranchName": "Headquarters" }
-```
-
-## Environment Variables
-
-```env
-# Database
-DB_HOST=localhost
-DB_PORT=3306
-DB_USERNAME=root
-DB_PASSWORD=password
-DB_DATABASE=myapp
-
-# 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
-
-# Frontend (for email links)
-FRONTEND_URL=http://localhost:2001
-```
-
-## Migrations
-
-See [MIGRATION.md](./MIGRATION.md) for detailed migration commands.
-
-```bash
-npm run migration:generate --name=InitialSetup
-npm run migration:run
-npm run migration:status
-```
-
-## Configuration Modes
-
-### Mode 1: Minimal (No Companies)
-
-```typescript
-AuthModule.forRoot({
-  bootstrapAppConfig: { enableCompanyFeature: false },
-})
-
-Entities:   User
-Features:   Basic login, registration
-```
-
-### Mode 2: Full Featured (With Companies)
-
-```typescript
-AuthModule.forRoot({
-  bootstrapAppConfig: { enableCompanyFeature: true },
-})
-
-Entities:   User, Company, CompanyBranch, UserCompanyPermission
-Features:   Multi-tenant, hierarchical branches
-```
-
----
-
-## No-IAM Mode (Bypassing Permission Guards)
-
-When you don't use the `@flusys/nestjs-iam` module but your controllers use `level: 'permission'` security, the `PermissionGuard` will fail because permissions aren't cached.
-
-**Solution:** Populate the cache with wildcard permissions after login.
-
-### How Permission Guard Works
-
-```
-Controller (level: 'permission')
-    ↓
-PermissionGuard.canActivate()
-    ↓
-getUserPermissions() → cache.get(`permissions:user:{userId}`)
-    ↓
-No IAM = Empty cache → NoPermissionsFoundException ❌
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "password": "password123",
+  "newCompanyName": "My Company",
+  "newCompanyPhone": "+1234567890",
+  "newCompanyAddress": "123 Main St"
+}
 ```
 
-### Fix: Set Wildcard Permissions After Login
+## No-IAM Mode
 
-Add this to your `AuthenticationService.login()` or create a custom login hook:
+When not using `@flusys/nestjs-iam` but controllers use `level: 'permission'` security, set wildcard permissions after login:
 
 ```typescript
 import { HybridCache, CACHE_INSTANCE, PERMISSIONS_CACHE_PREFIX } from '@flusys/nestjs-shared';
@@ -669,7 +754,6 @@ import { HybridCache, CACHE_INSTANCE, PERMISSIONS_CACHE_PREFIX } from '@flusys/n
 export class AuthenticationService {
   constructor(
     @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
-    // ... other dependencies
   ) {}
 
   async login(dto: LoginDto): Promise<LoginResponse> {
@@ -681,10 +765,6 @@ export class AuthenticationService {
     return { accessToken, user };
   }
 
-  /**
-   * Sets wildcard permissions for users when IAM module is not installed.
-   * The '*' permission grants access to all protected endpoints.
-   */
   private async setWildcardPermissions(userId: string): Promise<void> {
     const cacheKey = `${PERMISSIONS_CACHE_PREFIX}:user:${userId}`;
     await this.cache.set(cacheKey, ['*'], 86400000); // 24 hours TTL
@@ -694,8 +774,6 @@ export class AuthenticationService {
 
 ### With Company Feature Enabled
 
-If using `enableCompanyFeature: true`, the cache key format is different:
-
 ```typescript
 private async setWildcardPermissions(
   userId: string,
@@ -703,47 +781,103 @@ private async setWildcardPermissions(
   branchId?: string,
 ): Promise<void> {
   if (companyId) {
-    // Company-scoped permissions
     const cacheKey = `${PERMISSIONS_CACHE_PREFIX}:company:${companyId}:branch:${branchId || 'null'}:user:${userId}`;
     await this.cache.set(cacheKey, ['*'], 86400000);
   } else {
-    // User-level permissions
     const cacheKey = `${PERMISSIONS_CACHE_PREFIX}:user:${userId}`;
     await this.cache.set(cacheKey, ['*'], 86400000);
   }
 }
 ```
 
-### Wildcard Permission Syntax
-
-The `PermissionGuard` supports these wildcard patterns:
+### Wildcard Permission Patterns
 
 | Pattern | Meaning |
 |---------|---------|
 | `*` | Full access to everything |
-| `user.*` | All user permissions (user.create, user.read, etc.) |
+| `user.*` | All user permissions |
 | `branch.*` | All branch permissions |
 
-### For Jest Tests
+## API Reference
 
-Mock the cache to return wildcard permissions:
+### Exports
 
 ```typescript
-const mockCache = {
-  get: jest.fn().mockResolvedValue(['*']),
-  set: jest.fn().mockResolvedValue(undefined),
-};
-
-beforeEach(async () => {
-  const module = await Test.createTestingModule({
-    providers: [
-      YourService,
-      { provide: CACHE_INSTANCE, useValue: mockCache },
-    ],
-  }).compile();
-});
+// Config
+export { AUTH_MODULE_OPTIONS, 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 { CoreEntities, CompanyEntities, AllEntities, getEntitiesByConfig } 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';
+
+// 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';
+
+// Strategies
+export { JwtStrategy } from './strategies/jwt.strategy';
+
+// Interceptors
+export { SetToken } from './interceptors/set-token.interceptor';
+export { ClearToken } from './interceptors/clear-token.interceptor';
+
+// DTOs
+export * from './dtos';
+
+// Swagger Config
+export { authSwaggerConfig } from './docs/auth-swagger.config';
+```
+
+### Module Static Methods
+
+```typescript
+// Get entities based on feature flags
+AuthModule.getEntities(enableCompanyFeature?: boolean): any[]
+
+// Configure module
+AuthModule.forRoot(options: AuthModuleOptions): DynamicModule
+AuthModule.forRootAsync(options: AuthModuleAsyncOptions): DynamicModule
 ```
 
+### Swagger Schema Behavior
+
+When `enableCompanyFeature: false`, the following are automatically hidden from Swagger:
+
+**Excluded Tags:** Companies, Branches, User Permissions, Company Selection
+
+**Excluded DTO Properties:**
+
+| DTO | Hidden Fields |
+|-----|---------------|
+| `RegistrationDto` | `companySlug`, `branchSlug`, `newCompanyName`, `newCompanyPhone`, `newCompanyAddress` |
+| `RegistrationResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
+| `LoginResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
+| `MeResponseDto` | `company`, `branch` |
+
 ---
 
-**Last Updated:** 2026-02-19
+**Last Updated:** 2026-02-21