@lenne.tech/nest-server 11.21.3 → 11.22.0

package/migration-guides/11.19.x-to-11.20.0.md

@@ -0,0 +1,170 @@
+# Migration Guide: 11.19.x → 11.20.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Multi-Tenancy Plugin (opt-in) |
+| **Bugfixes** | None |
+| **Migration Effort** | 0 min (feature is opt-in, no changes required for existing projects) |
+
+---
+
+## Quick Migration (No Breaking Changes)
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.20.0
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+No code changes required. Multi-tenancy is disabled by default and has zero overhead when not configured.
+
+---
+
+## What's New in 11.20.0
+
+### Multi-Tenancy: Tenant-Based Data Isolation
+
+A global Mongoose plugin that automatically filters all database queries by `tenantId`, providing tenant isolation in a shared MongoDB database.
+
+**Key features:**
+- Auto-filters queries (find, update, delete, aggregate, count, distinct)
+- Auto-sets `tenantId` on new documents (save, insertMany)
+- Zero overhead when disabled (plugin not registered)
+- Works with both Legacy Auth (JWT) and BetterAuth (IAM)
+- Follows the "Presence Implies Enabled" configuration pattern
+
+#### Step 1: Enable in config
+
+```typescript
+// config.env.ts
+{
+  // Enable with defaults (userField: 'tenantId')
+  multiTenancy: {},
+
+  // Or with options
+  multiTenancy: {
+    excludeSchemas: ['User', 'Session'], // Model names to exclude from filtering
+    userField: 'tenantId',               // Field on req.user (default: 'tenantId')
+  },
+
+  // Pre-configured but disabled
+  multiTenancy: {
+    enabled: false,
+    excludeSchemas: ['User'],
+  },
+}
+```
+
+#### Step 2: Add `tenantId` to your User model
+
+```typescript
+// In your project's User model (NOT in nest-server!)
+export class User extends CoreUserModel {
+  @UnifiedField({
+    mongoose: { type: String, index: true },
+    roles: RoleEnum.S_NO_ONE, // Users cannot modify their own tenantId
+  })
+  tenantId: string = undefined;
+}
+```
+
+#### Step 3: Add `tenantId` to domain models
+
+> **Security Warning:** You **MUST** use `@UnifiedField` with `roles: RoleEnum.S_NO_ONE` on the `tenantId` field of every domain model. Without this, API consumers can inject arbitrary tenant IDs via request body, bypassing tenant isolation on writes. The plugin auto-sets `tenantId` from the user context — manual input should be blocked.
+>
+> **This is a developer responsibility that the plugin cannot enforce.** The tenant plugin operates at the Mongoose middleware layer and has no knowledge of your GraphQL/REST input schema. If you omit the `roles: RoleEnum.S_NO_ONE` declaration, the field will be writable via API input, silently undermining tenant isolation on write paths. There is no runtime warning — the plugin will simply preserve whatever `tenantId` value was provided in the request body instead of auto-assigning from the user context.
+
+```typescript
+@MongooseSchema({ timestamps: true })
+export class Order extends CorePersistenceModel {
+  @UnifiedField({
+    mongoose: { type: String, index: true },
+    roles: RoleEnum.S_NO_ONE, // Prevent user from setting tenantId via API input
+  })
+  tenantId: string = undefined;
+
+  // ... other fields
+}
+```
+
+The plugin automatically activates on any schema that has a `tenantId` field. Schemas without `tenantId` are not affected.
+
+#### Cross-Tenant Admin Operations
+
+**Important:** ADMIN users are also filtered by their own `tenantId`. For admin dashboards or cross-tenant queries, use the explicit bypass:
+
+```typescript
+import { RequestContext } from '@lenne.tech/nest-server';
+
+// Admin dashboard: view all tenants
+const allOrders = await RequestContext.runWithBypassTenantGuard(async () => {
+  return this.orderService.find();
+});
+```
+
+#### Behavior Reference
+
+| Situation | Behavior |
+|-----------|----------|
+| No `multiTenancy` config | Plugin not registered, zero overhead |
+| No RequestContext (cron, migration) | No filter applied |
+| `bypassTenantGuard: true` | No filter applied |
+| Schema in `excludeSchemas` | No filter applied |
+| User with `tenantId: "abc"` | Filter: `{ tenantId: "abc" }` |
+| User without `tenantId` | Filter: `{ tenantId: null }` (sees only unassigned data) |
+| User with `tenantId: ""` (empty string) | Same as without — empty string is falsy, filter: `{ tenantId: null }` |
+| No user (public endpoint) | No filter applied |
+
+#### Known Limitations
+
+1. **`populate()`**: Referenced models with `tenantId` are also filtered. Shared models (User, Config) should be in `excludeSchemas`.
+2. **`estimatedDocumentCount`**: Does not support query filters (MongoDB limitation).
+3. **`$lookup` in aggregates**: Joined collections are not automatically filtered. Add `$match` in `$lookup.pipeline` manually.
+4. **Legacy data**: Existing documents without `tenantId` are not auto-assigned. Backfill tenantIds via migration script.
+5. **Write-path protection**: The plugin auto-sets `tenantId` on new documents but does not enforce it on explicit values. Use `@UnifiedField({ roles: RoleEnum.S_NO_ONE })` on domain model `tenantId` fields to prevent cross-tenant write injection via API input.
+6. **Empty string tenantId**: If `req.user.tenantId` is an empty string (`''`), it is treated as falsy — the user sees only documents with `tenantId: null`. Ensure tenant IDs are never stored as empty strings.
+
+---
+
+## Compatibility Notes
+
+### Pattern: Existing projects without multi-tenancy
+
+**Status: Fully compatible, no action required**
+
+If your project does not configure `multiTenancy`, the plugin is never registered. There is zero performance impact.
+
+### Pattern: Projects with custom Mongoose plugins
+
+**Status: Compatible**
+
+The tenant plugin is registered after the audit fields plugin in `connectionFactory`. It does not interfere with other plugins.
+
+---
+
+## Module Documentation
+
+| Module | Documentation |
+|--------|--------------|
+| Multi-Tenancy Plugin | `src/core/common/plugins/mongoose-tenant.plugin.ts` |
+| RequestContext | `src/core/common/services/request-context.service.ts` |
+| Configuration | `IMultiTenancy` in `src/core/common/interfaces/server-options.interface.ts` |
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Admin can't see all tenants | Use `RequestContext.runWithBypassTenantGuard()` — ADMIN users are also filtered |
+| `populate()` returns null for cross-tenant refs | Add referenced model to `excludeSchemas` |
+| Legacy data invisible after enabling MT | Backfill `tenantId` on existing documents |
+| Cron job sees all data | Expected — no RequestContext = no filter |

package/migration-guides/11.20.x-to-11.21.0.md

@@ -0,0 +1,216 @@
+# Migration Guide: 11.20.x → 11.21.0
+
+## Overview
+
+| Category | Changes | Effort |
+|----------|---------|--------|
+| **Breaking** | `userField` removed from `IMultiTenancy`, tenant filtering behavior changed | Medium |
+| **Breaking** | Safety Net: tenantId-schemas throw `ForbiddenException` without valid tenant context | Low |
+| **New Feature** | Header-based multi-tenant membership with configurable hierarchy roles | Low-Medium |
+
+## Not Using Multi-Tenancy?
+
+If your project does **not** configure `multiTenancy` in `config.env.ts`, this update requires **no action**. All changes are fully backward compatible — just update the package version.
+
+## Breaking Changes
+
+### 1. `userField` Removed from IMultiTenancy
+
+The `userField` property has been removed. Tenant ID is now read from the `X-Tenant-Id` request header instead of from `req.user`.
+
+**Before (11.20.x):**
+```typescript
+multiTenancy: {
+  userField: 'organizationId',
+  excludeSchemas: ['User'],
+}
+```
+
+**After (11.21.0):**
+```typescript
+multiTenancy: {
+  headerName: 'x-tenant-id', // Optional, this is the default
+  excludeSchemas: ['User'],
+}
+```
+
+**Action Required:** Remove any `userField` references from your `config.env.ts`.
+
+### 2. Tenant Filtering Behavior Change
+
+**Before (11.20.x):**
+- Logged-in user without `tenantId` → queries filtered by `{ tenantId: null }` (sees only unassigned data)
+
+**After (11.21.0):**
+- Unauthenticated request with `X-Tenant-Id` header → **403 "Authentication required for tenant access"**
+- Authenticated request without `X-Tenant-Id` header + hierarchy role → checks `user.roles`, filters `tenantIds` by level
+- Authenticated user with no memberships → **Safety Net: `ForbiddenException`** on tenantId-schemas
+- Use `@Roles(DefaultHR.MEMBER)` to require tenant membership on specific endpoints
+
+**Action Required:** If you relied on the null-filter behavior, use `@Roles(DefaultHR.MEMBER)` on endpoints that should require tenant context.
+
+### 3. Safety Net (Defense-in-Depth)
+
+The Mongoose tenant plugin now throws `ForbiddenException` instead of returning unfiltered data when a tenantId-scoped schema is accessed without valid tenant context.
+
+**Affected scenarios:**
+- Public endpoints (`@Roles(S_EVERYONE)`) accessing tenantId-scoped models → now throw 403
+- System operations without `RequestContext` → unaffected (no context = no filter, as before)
+- Operations with `bypassTenantGuard` → unaffected (bypass skips all filtering)
+
+**Action Required:** Public routes that access tenantId-scoped models must use one of:
+- `@SkipTenantCheck()` decorator + `RequestContext.runWithBypassTenantGuard()` in the service
+- Or ensure a valid tenant context is provided
+
+### 4. New IMultiTenancy Properties
+
+```typescript
+export interface IMultiTenancy {
+  enabled?: boolean;
+  excludeSchemas?: string[];
+  // NEW
+  headerName?: string;           // Default: 'x-tenant-id'
+  membershipModel?: string;      // Default: 'TenantMember'
+  adminBypass?: boolean;          // Default: true
+  roleHierarchy?: Record<string, number>;  // Default: { member: 1, manager: 2, owner: 3 }
+}
+```
+
+## New Feature: Multi-Tenant Membership
+
+### What's New
+
+- **CoreTenantModule** — Auto-registered when `multiTenancy` is configured
+- **CoreTenantMemberModel** — Join table for user-tenant membership with roles
+- **CoreTenantGuard** — APP_GUARD validating tenant header and membership
+- **CoreTenantService** — Membership CRUD operations
+- **Hierarchy Roles** — Configurable role levels with level comparison (`@Roles(DefaultHR.MEMBER)`)
+- **Normal Roles** — Non-hierarchy roles with exact match (`@Roles('auditor')`)
+- **`createHierarchyRoles()`** — Generate type-safe constants from hierarchy config
+- **`DefaultHR`** — Pre-built constants for default hierarchy (MEMBER, MANAGER, OWNER)
+- **`@SkipTenantCheck()`** — Skip tenant validation for specific endpoints
+- **`@CurrentTenant()`** — Parameter decorator for tenant ID extraction
+- **`TenantMemberStatus`** enum — ACTIVE, INVITED, SUSPENDED
+
+### Quick Setup
+
+```typescript
+// config.env.ts — enable tenant system
+multiTenancy: {},
+```
+
+### Protecting Endpoints
+
+```typescript
+import { Roles, CurrentTenant, DefaultHR } from '@lenne.tech/nest-server';
+
+@Controller('projects')
+export class ProjectController {
+  @Get()
+  @Roles(DefaultHR.MEMBER)  // any active member
+  async list(@CurrentTenant() tenantId: string) {
+    return this.projectService.find({ tenantId });
+  }
+
+  @Delete(':id')
+  @Roles(DefaultHR.OWNER)  // highest level only
+  async delete(@Param('id') id: string) {
+    return this.projectService.delete(id);
+  }
+}
+```
+
+### Custom Hierarchy (5+ Levels)
+
+```typescript
+// config.env.ts
+multiTenancy: {
+  roleHierarchy: { viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 },
+}
+
+// roles.ts
+import { createHierarchyRoles } from '@lenne.tech/nest-server';
+export const HR = createHierarchyRoles({ viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 });
+
+// resolver.ts
+@Roles(HR.EDITOR)  // requires level >= 2 (editor, manager, admin, owner)
+```
+
+### Tenant Context Rule
+
+When `X-Tenant-Id` header is present: only `membership.role` is checked (user.roles ignored, except ADMIN bypass).
+When no header: `user.roles` is checked instead (same hierarchy/normal semantics).
+
+### Frontend: Send Tenant Header
+
+All tenant-scoped API calls must include:
+```
+X-Tenant-Id: <tenant-id>
+```
+
+### How It Works
+
+1. `RequestContextMiddleware` provides lazy getters for tenant context
+2. `CoreTenantGuard` validates membership → sets `req.tenantId` (only after successful check)
+3. Mongoose tenant plugin reads `tenantId` from `RequestContext` → filters queries
+4. **Safety Net:** Plugin throws `ForbiddenException` if tenantId-schema accessed without valid context
+
+### Admin Bypass
+
+System admins (`RoleEnum.ADMIN`) skip membership validation by default.
+Disable: `multiTenancy: { adminBypass: false }`.
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| `multiTenancy: {}` | Compatible | Enables tenant system with defaults |
+| `multiTenancy: { enabled: false }` | Compatible | Pre-configured but disabled |
+| No `multiTenancy` config | Compatible | Zero overhead, no changes needed |
+| `excludeSchemas` | Compatible | Works as before; `TenantMember` auto-added |
+| `RequestContext.runWithBypassTenantGuard()` | Compatible | Unchanged |
+| Public endpoints on non-tenant schemas | Compatible | Unaffected by Safety Net |
+| Public endpoints on tenant schemas | **Breaking** | Safety Net throws 403 — use `@SkipTenantCheck()` + bypass |
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| 403 "Authentication required for tenant access" | Header present but no user | Authenticate before accessing tenant endpoints |
+| 403 "Insufficient tenant role" | Membership role too low for hierarchy requirement | Upgrade membership role or use a lower-level decorator |
+| 403 "Insufficient role" | No header, user.roles don't meet requirement | Add appropriate role to user.roles or send tenant header |
+| 403 "Not a member of this tenant" | User has no active membership | Add membership via `CoreTenantService.addMember()` |
+| 403 "Tenant context required" | Safety Net: tenantId-schema accessed without valid context | Add `@SkipTenantCheck()` + `runWithBypassTenantGuard()`, or provide tenant header |
+| Data not filtered by tenant | Model missing `tenantId` field | Add `@Prop({ type: String }) tenantId: string` |
+| TypeScript error: `userField` not found | Breaking change in IMultiTenancy | Remove `userField` from config |
+
+## Rollback / Downgrade
+
+If you need to revert to 11.20.x after upgrading:
+
+1. **Downgrade the package:**
+   ```bash
+   pnpm add @lenne.tech/nest-server@11.20.1
+   ```
+
+2. **Restore `userField` in config:**
+   ```typescript
+   multiTenancy: {
+     userField: 'tenantId', // Re-add the removed property
+     excludeSchemas: ['User'],
+   }
+   ```
+
+3. **Remove tenant decorators** from any endpoints where you added `@Roles(DefaultHR.*)`, `@SkipTenantCheck()`, or `@CurrentTenant()`.
+
+4. **Remove `X-Tenant-Id` header** from frontend API calls if already added.
+
+5. **Note:** The `TenantMember` collection created by 11.21.0 will remain in MongoDB but is unused by 11.20.x. You can drop it manually if desired:
+   ```
+   db.tenantmembers.drop()
+   ```
+
+## Module Documentation
+
+- [Tenant Module README](../src/core/modules/tenant/README.md)
+- [Integration Checklist](../src/core/modules/tenant/INTEGRATION-CHECKLIST.md)

package/migration-guides/11.21.0-to-11.21.1.md

@@ -0,0 +1,194 @@
+# Migration Guide: 11.21.0 → 11.21.1
+
+## Overview
+
+| Category | Changes | Effort |
+|----------|---------|--------|
+| **Breaking Changes** | None | None |
+| **New Features** | Tenant membership cache with configurable TTL, cache invalidation APIs, DB indices for BetterAuth | Low (opt-in) |
+| **Performance Improvements** | CheckSecurityInterceptor, processDeep, EmailService, RequestContext bypass | None (automatic) |
+| **Migration Effort** | Update package version | ~1 minute |
+
+---
+
+## Quick Migration
+
+This is a PATCH release with no breaking changes. All improvements are backward compatible and most activate automatically.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.21.1
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+No code changes required.
+
+---
+
+## What's New in 11.21.1
+
+### 1. Tenant Membership Cache (`multiTenancy.cacheTtlMs`)
+
+The `CoreTenantGuard` now caches membership lookups in-process to avoid repeated database queries when the same user accesses the same tenant. This is especially beneficial for high-traffic multi-tenant applications.
+
+**Default behavior:** Cache is enabled with a 30-second TTL. In test environments (`VITEST=true`, `NODE_ENV=test`, or `NODE_ENV=e2e`), the cache is automatically disabled to avoid stale data between test cases.
+
+```typescript
+// config.env.ts — default (no changes needed, cache is on)
+multiTenancy: {}
+
+// config.env.ts — custom TTL (e.g., 60 seconds)
+multiTenancy: {
+  cacheTtlMs: 60_000,
+}
+
+// config.env.ts — disable cache entirely
+multiTenancy: {
+  cacheTtlMs: 0,
+}
+```
+
+**Important for horizontally scaled deployments:** The cache is process-local. When a membership is added or removed on one server instance, other instances will not see the change until the TTL expires. For security-critical deployments where immediate revocation is required, reduce the TTL or set it to `0`.
+
+### 2. Cache Invalidation APIs
+
+Two new public methods on `CoreTenantGuard` allow programmatic cache invalidation:
+
+| Method | Description |
+|--------|-------------|
+| `invalidateUser(userId)` | Clears all cached entries for a specific user |
+| `invalidateAll()` | Clears the entire membership cache |
+
+These are called automatically by `CoreTenantService` whenever memberships are added, removed, or updated. **No action required** unless your project extends `CoreTenantService` with custom membership mutation methods.
+
+**Action required only if:** You have a custom service that modifies tenant memberships directly (bypassing `CoreTenantService`). In that case, inject `CoreTenantGuard` and call `invalidateUser()` after changes:
+
+```typescript
+import { CoreTenantGuard } from '@lenne.tech/nest-server';
+
+@Injectable()
+export class CustomTenantService extends CoreTenantService {
+  constructor(
+    // ... other deps
+    private tenantGuard: CoreTenantGuard,
+  ) {
+    super(/* ... */);
+  }
+
+  async customMembershipChange(userId: string, tenantId: string): Promise<void> {
+    // ... your custom logic ...
+    this.tenantGuard.invalidateUser(userId);
+  }
+}
+```
+
+### 3. User Role Cache Invalidation (`CoreBetterAuthUserMapper`)
+
+A new public method `invalidateUserCache(iamId)` is available on `CoreBetterAuthUserMapper`. It clears the cached user data (15-second TTL) used during session-to-user mapping.
+
+This is called automatically from `CoreUserService.setRoles()`. **No action required** unless your project modifies user roles outside of `CoreUserService.setRoles()`.
+
+**Action required only if:** You have custom logic that changes user roles directly in the database:
+
+```typescript
+import { CoreBetterAuthUserMapper } from '@lenne.tech/nest-server';
+
+@Injectable()
+export class CustomUserService {
+  constructor(private userMapper: CoreBetterAuthUserMapper) {}
+
+  async customRoleChange(userId: string, iamId: string): Promise<void> {
+    // ... your custom role update logic ...
+    this.userMapper.invalidateUserCache(iamId);
+  }
+}
+```
+
+### 4. Automatic Database Indices
+
+The following indices are now auto-created by `CoreBetterAuthService.onModuleInit()` when BetterAuth is enabled:
+
+| Collection | Index | Purpose |
+|------------|-------|---------|
+| `session` | `{ token: 1 }` | Fast session token lookups |
+| `session` | `{ userId: 1, expiresAt: 1 }` | Active session queries per user |
+| `users` | `{ iamId: 1 }` (sparse) | IAM ID lookups during session mapping |
+
+No action required. Index creation is idempotent — calling `createIndex` on an existing index is a no-op. These indices improve query performance for BetterAuth session validation and user mapping.
+
+---
+
+## Performance Improvements
+
+These optimizations apply automatically. No configuration or code changes needed.
+
+### 1. CheckSecurityInterceptor: Conditional JSON.stringify
+
+`JSON.stringify` on response data now only runs when `debug: true` is configured. Previously, every response was serialized even when debug output was not used. This reduces CPU overhead on every request that passes through the security interceptor.
+
+### 2. processDeep: Options Object Reuse
+
+The `processDeep()` helper (used by `CheckSecurityInterceptor` and input validation) now reuses its options object across recursive calls instead of recreating it for each nested property. This reduces garbage collection pressure for deeply nested response objects.
+
+### 3. EmailService: SMTP Transport Reuse
+
+The SMTP transport created by `nodemailer.createTransport()` is now cached as a singleton per configuration. Previously, a new transport was created for each email send operation. The cache key is derived from the SMTP configuration hash, so transport changes at runtime are handled correctly.
+
+### 4. RequestContext.runWithBypass*: Skip Redundant Context
+
+`RequestContext.runWithBypassRoleGuard()` and `RequestContext.runWithBypassTenantGuard()` now skip creating a new `AsyncLocalStorage` context when the bypass flag is already set. This avoids unnecessary object spread operations in nested bypass calls.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| `multiTenancy: {}` | Compatible | Cache enabled at 30s TTL by default |
+| `multiTenancy: { cacheTtlMs: 0 }` | Compatible | Cache disabled, same behavior as before 11.21.1 |
+| No `multiTenancy` config | Compatible | No changes, no overhead |
+| Custom `CoreTenantService` extensions | Compatible | Automatic invalidation if using `super.addMember()` etc. |
+| Direct membership DB mutations | **Check** | Must call `invalidateUser()` manually (see section 2 above) |
+| Custom role-change logic (bypassing `CoreUserService.setRoles`) | **Check** | Must call `invalidateUserCache()` manually (see section 3 above) |
+| BetterAuth disabled | Compatible | DB indices are not created when BetterAuth is disabled |
+| Test environments | Compatible | Cache auto-disabled in test/e2e environments |
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Stale membership data after role change | Membership cache TTL not expired | Call `CoreTenantGuard.invalidateUser(userId)` after custom membership changes |
+| Stale user roles after `setRoles()` | Should not happen (auto-invalidated) | Verify you are using `CoreUserService.setRoles()`, not direct DB updates |
+| Membership changes not visible across server instances | Process-local cache | Reduce `cacheTtlMs` or set to `0` for immediate consistency |
+| Tests see stale membership data | Cache enabled in test env | Verify `NODE_ENV=test` or `VITEST=true` is set (auto-disables cache) |
+
+---
+
+## Module Documentation
+
+### Tenant Module
+
+- **README:** [src/core/modules/tenant/README.md](../src/core/modules/tenant/README.md)
+- **Integration Checklist:** [src/core/modules/tenant/INTEGRATION-CHECKLIST.md](../src/core/modules/tenant/INTEGRATION-CHECKLIST.md)
+- **Key File:** `src/core/modules/tenant/core-tenant.guard.ts` — cache implementation and `invalidateUser()`/`invalidateAll()` methods
+
+### BetterAuth Module
+
+- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
+- **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- **Key File:** `src/core/modules/better-auth/core-better-auth.service.ts` — DB index creation in `onModuleInit()`
+- **Key File:** `src/core/modules/better-auth/core-better-auth-user.mapper.ts` — `invalidateUserCache()` method
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [11.20.x → 11.21.0 Migration Guide](./11.20.x-to-11.21.0.md) (previous release with multi-tenancy breaking changes)

package/migration-guides/11.21.1-to-11.21.2.md

@@ -0,0 +1,114 @@
+# Migration Guide: 11.21.1 → 11.21.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | BetterAuth auto-skip for tenant validation on IAM endpoints |
+| **Bugfixes** | lodash security fix (CVE HIGH + MODERATE) |
+| **Migration Effort** | < 5 minutes |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.21.2
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+No code changes required. The new feature activates automatically with safe defaults.
+
+---
+
+## What's New in 11.21.2
+
+### 1. BetterAuth Auto-Skip for Tenant Validation
+
+**Affects:** Projects with both `multiTenancy` and `betterAuth` active.
+
+When both features are enabled, IAM endpoints (sign-in, sign-up, sign-out, session, etc.)
+now automatically skip `CoreTenantGuard` tenant validation when no `X-Tenant-Id` header is
+present. This solves the chicken-and-egg problem where users couldn't authenticate because
+they weren't yet a member of any tenant.
+
+**Default behavior (`skipTenantCheck: true`):**
+
+| Scenario | Behavior |
+|----------|----------|
+| No `X-Tenant-Id` header | Skip tenant validation (auth before tenant) |
+| `X-Tenant-Id` header present | Validate normally (membership check + tenant context) |
+
+The auto-skip applies to both REST controllers (`CoreBetterAuthController` subclasses)
+and GraphQL resolvers (`CoreBetterAuthResolver` subclasses).
+
+**If you previously used `@SkipTenantCheck()` on your IAM resolver/controller to work
+around this issue, you can remove it** — the framework now handles this automatically.
+
+### 2. Opt-Out for Tenant-Aware Authentication
+
+If your project requires tenant context at login time (e.g., subdomain-based tenancy,
+invite links with embedded tenant, SSO per tenant), disable the auto-skip:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  skipTenantCheck: false, // IAM endpoints require valid X-Tenant-Id header
+}
+```
+
+### 3. Security: lodash Update
+
+`lodash` updated from 4.17.23 to 4.18.1, fixing:
+- GHSA-r5fr-rjxr-66jc (HIGH — prototype pollution)
+- GHSA-f23m-r3pf-42rh (MODERATE — prototype pollution)
+
+A `pnpm.overrides` entry ensures all transitive dependencies also use the patched version.
+
+### 4. Dependency Updates
+
+| Package | From | To | Type |
+|---------|------|----|------|
+| `lodash` | 4.17.23 | 4.18.1 | Security fix |
+| `dotenv` | 17.3.1 | 17.4.0 | Minor feature |
+| `@swc/cli` | 0.8.0 | 0.8.1 | Patch |
+
+Three unnecessary pnpm overrides were removed (`file-type`, `yauzl`, `flatted`).
+
+---
+
+## Compatibility Notes
+
+- **Projects without `multiTenancy`:** Not affected. No behavior change.
+- **Projects without `betterAuth`:** Not affected. No behavior change.
+- **Projects with both features + default config:** IAM endpoints now work without `X-Tenant-Id` header. Previously, these would fail if the user wasn't a tenant member.
+- **Projects with `@SkipTenantCheck()` on IAM endpoints:** The decorator continues to work but is no longer needed for this use case. Safe to remove.
+- **Subdomain-based / invite-link tenancy:** Set `betterAuth.skipTenantCheck: false` to require tenant context on IAM endpoints.
+
+---
+
+## Module Documentation
+
+### Tenant Module
+
+- **README:** [src/core/modules/tenant/README.md](../src/core/modules/tenant/README.md) — See "BetterAuth (IAM) Integration" section
+- **Integration Checklist:** [src/core/modules/tenant/INTEGRATION-CHECKLIST.md](../src/core/modules/tenant/INTEGRATION-CHECKLIST.md) — See § 9 "BetterAuth (IAM) Coexistence"
+
+### BetterAuth Module
+
+- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md) — See "Multi-Tenancy Integration" section
+
+---
+
+## References
+
+- [Configurable Features](../.claude/rules/configurable-features.md) — `betterAuth.skipTenantCheck` entry
+- [Request Lifecycle](../docs/REQUEST-LIFECYCLE.md) — CoreTenantGuard flow with auto-skip
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)