@flusys/nestjs-auth 0.1.0-beta.3 → 1.0.0-rc

package/README.md

@@ -3,13 +3,12 @@
 > **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.
-
 ## Table of Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+- [Constants](#constants)
 - [API Endpoints](#api-endpoints)
 - [Architecture](#architecture)
 - [Login Flows](#login-flows)
@@ -17,7 +16,6 @@ This comprehensive guide covers the authentication package - flexible auth syste
 - [Environment Variables](#environment-variables)
 - [Migrations](#migrations)
 - [Configuration Modes](#configuration-modes)
-- [IAM Integration](#iam-integration)
 
 ---
 
@@ -40,7 +38,6 @@ 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,
@@ -69,10 +66,9 @@ 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: {
@@ -97,7 +93,6 @@ AuthModule.forRoot({
 AuthModule.forRoot({
   global: true,
   includeController: true,
-  includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
   bootstrapAppConfig: {
     databaseMode: 'multi-tenant',
     enableCompanyFeature: true,
@@ -125,13 +120,12 @@ AuthModule.forRoot({
 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
+  useClass: AuthConfigFactory,
 })
 ```
 
@@ -143,29 +137,45 @@ 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;
+    jwtSecret?: string;
     jwtExpiration?: string;
     refreshTokenSecret?: string;
     refreshTokenExpiration?: string;
     refreshTokenCookieName?: string;   // Default: 'fsn_refresh_token'
+    frontendUrl?: string;              // For email links
   };
+  providers?: Provider[];              // Additional providers (e.g., AUTH_EMAIL_PROVIDER)
 }
 ```
 
-**Important Notes:**
+## Constants
+
+Centralized constants in `auth.constants.ts`:
+
+```typescript
+// Injection Tokens
+export const AUTH_MODULE_OPTIONS = 'AUTH_MODULE_OPTIONS';
+export const USER_ENRICHER = 'USER_ENRICHER';
+
+// Security
+export const BCRYPT_SALT_ROUNDS = 12;
 
-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.
+// Cookie
+export const DEFAULT_COOKIE_NAME = 'fsn_refresh_token';
+export const MAX_COOKIE_BYTES = 3500;
 
-2. **Module Separation**: Auth module handles authentication (login, JWT, user management). For authorization and permissions, use the separate `@flusys/nestjs-iam` package.
+// Cache Key Prefixes
+export const SESSION_CACHE_PREFIX = 'auth:session';
+export const TOKEN_REVOKED_PREFIX = 'auth:revoked';
+```
 
 ## API Endpoints
 
@@ -180,13 +190,20 @@ interface AuthModuleOptions {
 | `/auth/change-password` | POST | Change user password |
 | `/auth/me` | GET | Get current user info |
 
-#### GET /auth/me - 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 |
 
-**Purpose:** Retrieve current authenticated user information with optional company/branch context
+> **Note:** Email endpoints require `AuthEmailService` to be configured via the `providers` option.
 
-**Authentication:** Requires valid access token (Bearer token in Authorization header)
+#### GET /auth/me - Get Current User Info
 
-**Response Behavior:**
+**Authentication:** Requires valid access token (Bearer token)
 
 When `enableCompanyFeature: false`:
 ```json
@@ -203,12 +220,7 @@ When `enableCompanyFeature: false`:
 When `enableCompanyFeature: true`:
 ```json
 {
-  "user": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "email": "john@example.com",
-    "name": "John Doe",
-    "profilePictureId": null
-  },
+  "user": { ... },
   "company": {
     "id": "550e8400-e29b-41d4-a716-446655440001",
     "name": "Acme Corporation",
@@ -224,14 +236,6 @@ When `enableCompanyFeature: true`:
 }
 ```
 
-**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)
-
-**Related Service:** `AuthenticationService.getUserInfo()` in `authentication.service.ts`
-
 ### Company Selection Endpoints (when company feature enabled)
 
 | Endpoint | Method | Description |
@@ -241,17 +245,11 @@ When `enableCompanyFeature: true`:
 | `/auth/companies` | GET | Get user's available companies |
 | `/auth/companies/:companyId/branches` | GET | Get branches for a company |
 
-> **Note:** These endpoints are automatically hidden from Swagger when `enableCompanyFeature: false`
-
 ### Swagger Schema Behavior
 
 When `enableCompanyFeature: false`, the following are automatically hidden from Swagger:
 
-**Excluded Tags:**
-- Companies
-- Branches
-- User Permissions (NEW - v4.1.3+)
-- Company Selection
+**Excluded Tags:** Companies, Branches, User Permissions, Company Selection
 
 **Excluded DTO Properties:**
 
@@ -262,23 +260,23 @@ When `enableCompanyFeature: false`, the following are automatically hidden from
 | `LoginResponseDto` | `company`, `branch`, `companyFeatureEnabled` |
 | `MeResponseDto` | `company`, `branch` |
 
-### User Management Endpoints (`/administration/users`)
+### User Management Endpoints
 
 | 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)
+| `/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 |
 |----------|--------|-------------|
@@ -299,42 +297,12 @@ POST /administration/permissions/user-company/assign
 }
 ```
 
-**Example: Revoke branch access**
-```json
-POST /administration/permissions/user-branch/assign
-{
-  "userId": "user-123",
-  "items": [
-    { "targetId": "branch-5", "isAdd": false }
-  ]
-}
-```
-
-> **Note:** These endpoints are only available when `enableCompanyFeature: true`
+### Company/Branch Management Endpoints (when company feature enabled)
 
-### 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 |
+| Resource | Endpoints |
+|----------|-----------|
+| Companies | `/administration/company` - CRUD operations |
+| Branches | `/administration/branch` - CRUD operations |
 
 ## Architecture
 
@@ -354,99 +322,79 @@ POST /administration/permissions/user-branch/assign
 ```
 
 **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.
+- 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** (required by Passport), but needs to access the **request-scoped** `AuthDataSourceProvider`. This is solved using `ModuleRef`:
+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,  // Used to resolve request-scoped providers
+    private readonly moduleRef: ModuleRef,
   ) {
     super({
       jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
       secretOrKey: authConfig.getJwtSecret(),
-      passReqToCallback: true,  // Pass request to validate method
+      passReqToCallback: true,
     });
   }
 
   async validate(_req: Request, payload: TokenPayload) {
-    // Resolve request-scoped AuthDataSourceProvider per request
     const dataSourceProvider = await this.moduleRef.resolve(
       AuthDataSourceProvider,
       undefined,
       { strict: false },
     );
-
     const userRepository = await dataSourceProvider.getRepository(User);
     // ... validate user
   }
 }
 ```
 
-**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                │   │
-│  └─────────────────────────────────────────────────┘   │
+│         @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 (Simple)
+#### Without Company Feature
 
 ```
 ┌──────────────┐
 │     User     │
 ├──────────────┤
-│ id           │
-│ name         │
-│ email        │◄────── Authentication
+│ id, name     │
+│ email        │◄── Authentication
 │ password     │
 │ phone        │
 └──────────────┘
@@ -458,29 +406,17 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
 ┌──────────────┐       ┌───────────────────┐       ┌──────────────────┐
 │     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
+│ 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
 
@@ -493,6 +429,8 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
 | `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
 
@@ -537,96 +475,112 @@ 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 }
 ```
 
 ## User Management
 
-### User Active Status
+### Company Permission Assignment Flow
+
+When creating users with `enableCompanyFeature: true`, the `UserService` automatically assigns company and branch permissions:
 
-The `PUT /users/:id/status` endpoint handles user active status based on company feature setting:
+**Flow Diagram:**
+
+```
+User Creation (with companyId/branchId)
+                │
+                ▼
+┌─────────────────────────────────────────────────────────┐
+│ 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' }    │
+                    └─────────────────────────────────────┘
+                │
+                ▼
+┌─────────────────────────────────────────────────────────┐
+│ 4. Check if branch permission exists                    │
+│    - Lookup UserCompanyPermission for user + branch     │
+└─────────────────────────────────────────────────────────┘
+                │
+       exists? ─┴── no ──┐
+         │               │
+         ▼               ▼
+    [Skip]          ┌─────────────────────────────────────┐
+                    │ 5. Create branch permission record  │
+                    │    { 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:**
 - 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
 
 **Simple registration:**
 ```json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123"
-}
+{ "name": "John Doe", "email": "john@example.com", "password": "password123" }
 ```
 
 **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"
-}
-```
-
-### 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
+{ "name": "John Doe", "email": "john@example.com", "password": "password123",
+  "newCompanyName": "My Company", "newBranchName": "Headquarters" }
 ```
 
 ## Environment Variables
@@ -645,22 +599,18 @@ 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.
 
-### Quick Commands
-
 ```bash
-# Generate migration
 npm run migration:generate --name=InitialSetup
-
-# Run migrations
 npm run migration:run
-
-# Check status
 npm run migration:status
 ```
 
@@ -670,107 +620,130 @@ npm run migration:status
 
 ```typescript
 AuthModule.forRoot({
-  bootstrapAppConfig: {
-    enableCompanyFeature: false,
-  },
+  bootstrapAppConfig: { enableCompanyFeature: false },
 })
 
 Entities:   User
-Tables:     1
 Features:   Basic login, registration
-Size:       Minimal
-Performance: Fast
 ```
 
 ### Mode 2: Full Featured (With Companies)
 
 ```typescript
 AuthModule.forRoot({
-  includeIAM: true, // If using IAM module
-  bootstrapAppConfig: {
-    enableCompanyFeature: true,
-  },
+  bootstrapAppConfig: { enableCompanyFeature: true },
 })
 
 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
 ```
 
-## IAM Integration
+---
+
+## No-IAM Mode (Bypassing Permission Guards)
 
-### Why includeIAM Flag?
+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.
 
-When using `@flusys/nestjs-iam` with Auth module in **single-tenant mode**, TypeORM needs to know about all entities during initialization.
+**Solution:** Populate the cache with wildcard permissions after login.
 
-**The Problem:**
-```typescript
-// Auth module calls TypeOrmModule.forRoot() with auth entities
-TypeOrmModule.forRoot({ entities: [User, Company, ...] })
+### How Permission Guard Works
 
-// IAM module tries to use forFeature() but entities not registered
-TypeOrmModule.forFeature([Action, Role, Permission]) // ❌ Error!
 ```
+Controller (level: 'permission')
+    ↓
+PermissionGuard.canActivate()
+    ↓
+getUserPermissions() → cache.get(`permissions:user:{userId}`)
+    ↓
+No IAM = Empty cache → NoPermissionsFoundException ❌
+```
+
+### Fix: Set Wildcard Permissions After Login
+
+Add this to your `AuthenticationService.login()` or create a custom login hook:
 
-**The Solution:**
 ```typescript
-// Auth module dynamically includes IAM entities when includeIAM: true
-AuthModule.forRoot({
-  includeIAM: true, // Auth module loads IAM entities
-  // ...
-})
+import { HybridCache, CACHE_INSTANCE, PERMISSIONS_CACHE_PREFIX } from '@flusys/nestjs-shared';
 
-// Now TypeORM knows about all entities
-TypeOrmModule.forRoot({
-  entities: [User, Company, Action, Role, Permission, ...]
-}) // ✅ Works!
-```
+@Injectable()
+export class AuthenticationService {
+  constructor(
+    @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
+    // ... other dependencies
+  ) {}
 
-**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)
+  async login(dto: LoginDto): Promise<LoginResponse> {
+    // ... validate credentials, generate tokens
 
-### Architecture
+    // When IAM is NOT used, grant all permissions via wildcard
+    await this.setWildcardPermissions(user.id);
 
+    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
+  }
+}
 ```
-App Module
-├── AuthModule.forRoot({ includeIAM: true })
-│   └── TypeOrmModule.forRoot([Auth entities + IAM entities])
-│
-└── IAMModule.forRoot()
-    └── TypeOrmModule.forFeature([IAM entities])
+
+### With Company Feature Enabled
+
+If using `enableCompanyFeature: true`, the cache key format is different:
+
+```typescript
+private async setWildcardPermissions(
+  userId: string,
+  companyId?: string,
+  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);
+  }
+}
 ```
 
-Auth module is responsible for database connection, but dynamically includes IAM entities when requested. This maintains separation while solving the TypeORM registration requirement.
+### Wildcard Permission Syntax
 
----
+The `PermissionGuard` supports these wildcard patterns:
+
+| Pattern | Meaning |
+|---------|---------|
+| `*` | Full access to everything |
+| `user.*` | All user permissions (user.create, user.read, etc.) |
+| `branch.*` | All branch permissions |
 
-## Summary
+### For Jest Tests
 
-The authentication package provides:
+Mock the cache to return wildcard permissions:
 
-- **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
+```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();
+});
+```
 
 ---
 
-**Last Updated:** 2026-02-09
-**Version:** 4.1.6
-
-**Recent Improvements:**
-- 2026-02-09: Added explicit `@Inject()` decorators to all services for esbuild bundling compatibility
-- 2026-02-09: All services now use REQUEST scope with DataSource Provider pattern
-- 2026-02-07: Fixed entity diagram to show polymorphic design (permissionType/targetId)
-- 2026-02-07: Updated service names to match actual implementation
-- 2026-02-07: Simplified login flow diagrams
-- 2026-01-15: Fixed JwtStrategy to use `ModuleRef` for request-scoped `AuthDataSourceProvider` resolution
-- 2026-01-14: Added `UserPermissionController` for batch permission management
+**Last Updated:** 2026-02-19