@flusys/nestjs-auth 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,776 @@
+# Authentication Package Guide
+
+> **Package:** `@flusys/nestjs-auth`
+> **Type:** Authentication system with JWT, multi-tenant, and company/branch support
+
+This comprehensive guide covers the authentication package - flexible auth system for NestJS applications.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [API Endpoints](#api-endpoints)
+- [Architecture](#architecture)
+- [Login Flows](#login-flows)
+- [User Management](#user-management)
+- [Environment Variables](#environment-variables)
+- [Migrations](#migrations)
+- [Configuration Modes](#configuration-modes)
+- [IAM Integration](#iam-integration)
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/nestjs-auth @flusys/nestjs-shared @flusys/nestjs-core
+```
+
+## Quick Start
+
+### Basic Setup (Single Database, No Company Feature)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { AuthModule } from '@flusys/nestjs-auth';
+
+@Module({
+  imports: [
+    AuthModule.forRoot({
+      global: true,
+      includeController: true,
+      includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
+      bootstrapAppConfig: {
+        databaseMode: 'single',
+        enableCompanyFeature: false,
+      },
+      config: {
+        defaultDatabaseConfig: {
+          type: 'mysql',
+          host: 'localhost',
+          port: 3306,
+          username: 'root',
+          password: 'password',
+          database: 'myapp',
+        },
+        jwtSecret: process.env.JWT_SECRET,
+        jwtExpiration: '1h',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### With Company Feature
+
+```typescript
+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
+  },
+  config: {
+    defaultDatabaseConfig: {
+      type: 'mysql',
+      host: 'localhost',
+      port: 3306,
+      username: 'root',
+      password: 'password',
+      database: 'myapp',
+    },
+    jwtSecret: process.env.JWT_SECRET,
+    refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET,
+    refreshTokenExpiration: '7d',
+    refreshTokenCookieName: 'fsn_refresh_token',
+  },
+})
+```
+
+### Multi-Tenant Mode
+
+```typescript
+AuthModule.forRoot({
+  global: true,
+  includeController: true,
+  includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
+  bootstrapAppConfig: {
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
+  },
+  config: {
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: 'localhost',
+      port: 3306,
+      username: 'root',
+      password: 'password',
+    },
+    tenants: [
+      { id: 'tenant1', database: 'tenant1_db', name: 'Tenant 1', isActive: true },
+      { id: 'tenant2', database: 'tenant2_db', name: 'Tenant 2', isActive: true },
+    ],
+    jwtSecret: process.env.JWT_SECRET,
+  },
+})
+```
+
+### Async Configuration
+
+```typescript
+AuthModule.forRootAsync({
+  global: true,
+  includeController: true,
+  includeIAM: true, // Include IAM entities if using @flusys/nestjs-iam
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: false,
+  },
+  imports: [HttpModule],
+  useClass: AuthConfigFactory,  // Implements AuthOptionsFactory
+})
+```
+
+## Configuration
+
+### Configuration Options
+
+```typescript
+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: {
+    databaseMode: 'single' | 'multi-tenant';
+    enableCompanyFeature: boolean;     // Enable company/branch feature
+  };
+  config: {
+    defaultDatabaseConfig?: IDatabaseConfig;
+    tenantDefaultDatabaseConfig?: IDatabaseConfig;
+    tenants?: ITenantDatabaseConfig[];
+    jwtSecret: string;
+    jwtExpiration?: string;
+    refreshTokenSecret?: string;
+    refreshTokenExpiration?: string;
+    refreshTokenCookieName?: string;   // Default: 'fsn_refresh_token'
+  };
+}
+```
+
+**Important Notes:**
+
+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.
+
+2. **Module Separation**: Auth module handles authentication (login, JWT, user management). For authorization and permissions, use the separate `@flusys/nestjs-iam` package.
+
+## API Endpoints
+
+### Authentication Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/auth/login` | POST | Login with email/password |
+| `/auth/register` | POST | Register new user |
+| `/auth/refresh` | POST | Refresh access token |
+| `/auth/logout` | POST | Logout (clears refresh token cookie) |
+| `/auth/change-password` | POST | Change user password |
+| `/auth/me` | GET | Get current user info |
+
+#### GET /auth/me - Get Current User Info
+
+**Purpose:** Retrieve current authenticated user information with optional company/branch context
+
+**Authentication:** Requires valid access token (Bearer token in Authorization header)
+
+**Response Behavior:**
+
+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": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "email": "john@example.com",
+    "name": "John Doe",
+    "profilePictureId": null
+  },
+  "company": {
+    "id": "550e8400-e29b-41d4-a716-446655440001",
+    "name": "Acme Corporation",
+    "slug": "acme-corp",
+    "logoId": null
+  },
+  "branch": {
+    "id": "550e8400-e29b-41d4-a716-446655440002",
+    "name": "Main Branch",
+    "slug": "main-branch",
+    "logoId": null
+  }
+}
+```
+
+**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 |
+|----------|--------|-------------|
+| `/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 |
+
+> **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 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 (`/administration/users`)
+
+| 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)
+
+| 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 |
+
+**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 }
+  ]
+}
+```
+
+**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 Management Endpoints (`/administration/company`) - When `enableCompanyFeature: true`
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/company/insert` | POST | Create company |
+| `/company/insert-many` | POST | Bulk create companies |
+| `/company/get/:id` | POST | Get company by ID |
+| `/company/get-all` | POST | Get paginated company list |
+| `/company/update` | POST | Update company |
+| `/company/update-many` | POST | Bulk update companies |
+| `/company/delete` | POST | Delete/restore company |
+
+### Branch Management Endpoints (`/administration/branch`) - When `enableCompanyFeature: true`
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/branch/insert` | POST | Create branch |
+| `/branch/insert-many` | POST | Bulk create branches |
+| `/branch/get/:id` | POST | Get branch by ID |
+| `/branch/get-all` | POST | Get paginated branch list (auto-filtered by company) |
+| `/branch/update` | POST | Update branch |
+| `/branch/update-many` | POST | Bulk update branches |
+| `/branch/delete` | POST | Delete/restore branch |
+
+## Architecture
+
+### 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 (secret, expiration)
+- ✅ **Token generation** handled by AuthenticationService
+- ✅ **Token validation** uses JwtStrategy registered by Auth module
+
+**Result:** IAM and Storage modules only depend on Shared, not Auth.
+
+### JwtStrategy Architecture
+
+The `JwtStrategy` is a **singleton** (required by Passport), but needs to access the **request-scoped** `AuthDataSourceProvider`. This is solved using `ModuleRef`:
+
+```typescript
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
+  constructor(
+    private readonly authConfig: AuthConfigService,
+    private readonly moduleRef: ModuleRef,  // Used to resolve request-scoped providers
+  ) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKey: authConfig.getJwtSecret(),
+      passReqToCallback: true,  // Pass request to validate method
+    });
+  }
+
+  async validate(_req: Request, payload: TokenPayload) {
+    // Resolve request-scoped AuthDataSourceProvider per request
+    const dataSourceProvider = await this.moduleRef.resolve(
+      AuthDataSourceProvider,
+      undefined,
+      { strict: false },
+    );
+
+    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                │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Entity Relationships
+
+#### Without Company Feature (Simple)
+
+```
+┌──────────────┐
+│     User     │
+├──────────────┤
+│ id           │
+│ name         │
+│ email        │◄────── Authentication
+│ password     │
+│ phone        │
+└──────────────┘
+```
+
+#### With Company Feature (Polymorphic Design)
+
+```
+┌──────────────┐       ┌───────────────────┐       ┌──────────────────┐
+│     User     │       │ UserCompany       │       │     Company      │
+├──────────────┤       │ Permission        │       ├──────────────────┤
+│ id           │◄──────┤ userId            │       │ id               │
+│ name         │       │ permissionType    │──────►│ name             │
+│ email        │       │ targetId (UUID)   │       │ slug             │
+│ password     │       │ isActive          │       │ isActive         │
+└──────────────┘       │ metadata          │       └──────────────────┘
+                       └───────────────────┘                │
+                                │                           │
+                permissionType: 'company'|'branch'          ▼
+                targetId: company.id OR branch.id   ┌──────────────────┐
+                                │                   │  CompanyBranch   │
+                                └──────────────────►├──────────────────┤
+                                                    │ id               │
+                                                    │ name, companyId  │
+                                                    │ parentId ◄──┐    │
+                                                    │ isActive    │    │
+                                                    └─────────────┴────┘
+                                                       Hierarchical
+```
+
+**Polymorphic Permission Design:**
+- `permissionType`: Enum ('company' | 'branch') determines target type
+- `targetId`: UUID of the company OR branch (single field, not both)
+- One table handles both company and branch permissions
+
+### Services
+
+| 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 |
+
+## Login Flows
+
+### Simple Mode (Company Feature Disabled)
+
+```
+POST /auth/login { email, password }
+              │
+              ▼
+┌─────────────────────────┐
+│  AuthenticationService  │
+│  .login()               │
+└────────────┬────────────┘
+             │
+             │ 1. Verify credentials
+             │ 2. Generate JWT token
+             ▼
+    { accessToken, refreshToken, user }
+```
+
+### Company Mode - Auto-Select (Single Company/Branch)
+
+```
+POST /auth/login { email, password }
+              │
+              ▼
+┌─────────────────────────┐
+│  AuthenticationService  │
+│  .login()               │
+└────────────┬────────────┘
+             │
+             │ 1. Verify credentials
+             │ 2. Check UserCompanyPermission
+             │ 3. Found: 1 company, 1 branch → Auto-select
+             ▼
+    { accessToken, refreshToken, user, company, branch }
+```
+
+### Company Mode - Selection Required (Multiple Options)
+
+```
+POST /auth/login { email, password }
+              │
+              ▼
+┌─────────────────────────┐
+│  AuthenticationService  │
+│  .login()               │
+└────────────┬────────────┘
+             │
+             │ Found: Multiple companies/branches
+             ▼
+    { requiresSelection: true, sessionId, companies: [...] }
+             │
+             │ 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
+
+The `PUT /users/:id/status` endpoint handles user active status based on company feature setting:
+
+**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"
+}
+```
+
+**Join existing company:**
+```json
+{
+  "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
+```
+
+## 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
+```
+
+## 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
+```
+
+## Configuration Modes
+
+### Mode 1: Minimal (No Companies)
+
+```typescript
+AuthModule.forRoot({
+  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,
+  },
+})
+
+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
+
+### Why includeIAM Flag?
+
+When using `@flusys/nestjs-iam` with Auth module in **single-tenant mode**, TypeORM needs to know about all entities during initialization.
+
+**The Problem:**
+```typescript
+// Auth module calls TypeOrmModule.forRoot() with auth entities
+TypeOrmModule.forRoot({ entities: [User, Company, ...] })
+
+// IAM module tries to use forFeature() but entities not registered
+TypeOrmModule.forFeature([Action, Role, Permission]) // ❌ Error!
+```
+
+**The Solution:**
+```typescript
+// Auth module dynamically includes IAM entities when includeIAM: true
+AuthModule.forRoot({
+  includeIAM: true, // Auth module loads IAM entities
+  // ...
+})
+
+// Now TypeORM knows about all entities
+TypeOrmModule.forRoot({
+  entities: [User, Company, Action, Role, Permission, ...]
+}) // ✅ Works!
+```
+
+**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)
+
+### Architecture
+
+```
+App Module
+├── AuthModule.forRoot({ includeIAM: true })
+│   └── TypeOrmModule.forRoot([Auth entities + IAM entities])
+│
+└── IAMModule.forRoot()
+    └── TypeOrmModule.forFeature([IAM entities])
+```
+
+Auth module is responsible for database connection, but dynamically includes IAM entities when requested. This maintains separation while solving the TypeORM registration requirement.
+
+---
+
+## Summary
+
+The authentication package provides:
+
+- **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
+
+---
+
+**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