@lenne.tech/nest-server 11.21.0 → 11.21.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.21.0",
+  "version": "11.21.2",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -73,22 +73,22 @@
     "node": ">= 20"
   },
   "dependencies": {
-    "@apollo/server": "5.4.0",
+    "@apollo/server": "5.5.0",
     "@as-integrations/express5": "1.1.2",
     "@better-auth/passkey": "1.5.5",
     "@getbrevo/brevo": "3.0.1",
     "@nestjs/apollo": "13.2.4",
-    "@nestjs/common": "11.1.16",
-    "@nestjs/core": "11.1.16",
+    "@nestjs/common": "11.1.17",
+    "@nestjs/core": "11.1.17",
     "@nestjs/graphql": "13.2.4",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.1.16",
+    "@nestjs/platform-express": "11.1.17",
     "@nestjs/schedule": "6.1.1",
     "@nestjs/swagger": "11.2.6",
     "@nestjs/terminus": "11.1.1",
-    "@nestjs/websockets": "11.1.16",
+    "@nestjs/websockets": "11.1.17",
     "@tus/file-store": "2.0.0",
     "@tus/server": "2.3.0",
     "bcrypt": "6.0.0",
@@ -97,21 +97,21 @@
     "class-validator": "0.15.1",
     "compression": "1.8.1",
     "cookie-parser": "1.4.7",
-    "dotenv": "17.3.1",
+    "dotenv": "17.4.0",
     "ejs": "5.0.1",
     "express": "5.2.1",
-    "graphql": "16.13.1",
+    "graphql": "16.13.2",
     "graphql-query-complexity": "1.1.0",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
-    "lodash": "4.17.23",
-    "mongodb": "7.1.0",
-    "mongoose": "9.3.0",
+    "lodash": "4.18.1",
+    "mongodb": "7.1.1",
+    "mongoose": "9.3.3",
     "multer": "2.1.1",
     "node-mailjet": "6.0.11",
-    "nodemailer": "8.0.2",
+    "nodemailer": "8.0.4",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -122,11 +122,11 @@
   },
   "devDependencies": {
     "@compodoc/compodoc": "1.2.1",
-    "@nestjs/cli": "11.0.16",
-    "@nestjs/schematics": "11.0.9",
-    "@nestjs/testing": "11.1.16",
-    "@swc/cli": "0.8.0",
-    "@swc/core": "1.15.18",
+    "@nestjs/cli": "11.0.17",
+    "@nestjs/schematics": "11.0.10",
+    "@nestjs/testing": "11.1.17",
+    "@swc/cli": "0.8.1",
+    "@swc/core": "1.15.21",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
@@ -137,16 +137,16 @@
     "@types/nodemailer": "7.0.11",
     "@types/passport": "1.0.17",
     "@types/supertest": "7.2.0",
-    "@vitest/coverage-v8": "4.1.0",
-    "@vitest/ui": "4.1.0",
+    "@vitest/coverage-v8": "4.1.2",
+    "@vitest/ui": "4.1.2",
     "ansi-colors": "4.1.3",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.0",
-    "oxfmt": "0.40.0",
-    "oxlint": "1.55.0",
+    "oxfmt": "0.43.0",
+    "oxlint": "1.58.0",
     "rimraf": "6.1.3",
     "supertest": "7.2.2",
     "ts-node": "10.9.2",
@@ -157,7 +157,7 @@
     "vite": "7.3.1",
     "vite-plugin-node": "7.0.0",
     "vite-tsconfig-paths": "6.1.1",
-    "vitest": "4.1.0"
+    "vitest": "4.1.2"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -179,12 +179,19 @@
       "minimatch@<3.1.4": "3.1.4",
       "minimatch@>=9.0.0 <9.0.7": "9.0.7",
       "minimatch@>=10.0.0 <10.2.3": "10.2.4",
-      "rollup@>=4.0.0 <4.59.0": "4.59.0",
+      "rollup@>=4.0.0 <4.60.1": "4.60.1",
       "ajv@<6.14.0": "6.14.0",
       "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0",
-      "file-type@>=13.0.0 <21.3.2": "21.3.2",
       "undici@>=7.0.0 <7.24.0": "7.24.3",
-      "yauzl@<3.2.1": "3.2.1"
+      "srvx@<0.11.13": "0.11.13",
+      "handlebars@>=4.0.0 <4.7.9": "4.7.9",
+      "brace-expansion@<1.1.13": "1.1.13",
+      "brace-expansion@>=4.0.0 <5.0.5": "5.0.5",
+      "picomatch@<2.3.2": "2.3.2",
+      "picomatch@>=4.0.0 <4.0.4": "4.0.4",
+      "path-to-regexp@>=8.0.0 <8.4.0": "8.4.1",
+      "kysely@>=0.26.0 <0.28.15": "0.28.15",
+      "lodash@>=4.0.0 <4.18.0": "4.18.1"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

package/src/core/common/helpers/input.helper.ts

@@ -783,15 +783,30 @@ export function processDeep(
     specialProperties?: string[];
   },
 ): any {
-  // Set options
-  const { processedObjects, specialClasses, specialFunctions, specialProperties } = {
-    processedObjects: new WeakMap(),
-    specialClasses: [],
-    specialFunctions: [],
-    specialProperties: [],
-    ...options,
+  // Set options once and reuse for all recursive calls (avoids creating new objects per property)
+  const resolvedOptions = {
+    processedObjects: options?.processedObjects ?? new WeakMap(),
+    specialClasses: options?.specialClasses ?? [],
+    specialFunctions: options?.specialFunctions ?? [],
+    specialProperties: options?.specialProperties ?? [],
   };
 
+  return processDeepInternal(data, func, resolvedOptions);
+}
+
+/** Internal recursive implementation that reuses the resolved options object */
+function processDeepInternal(
+  data: any,
+  func: (data: any) => any,
+  options: {
+    processedObjects: WeakMap<any, boolean>;
+    specialClasses: ((new (args: any[]) => any) | string)[];
+    specialFunctions: string[];
+    specialProperties: string[];
+  },
+): any {
+  const { processedObjects, specialClasses, specialFunctions, specialProperties } = options;
+
   // Check for falsifiable values
   if (!data) {
     return func(data);
@@ -806,7 +821,7 @@ export function processDeep(
 
   // Process array
   if (Array.isArray(data)) {
-    return func(data.map((item) => processDeep(item, func, { processedObjects, specialClasses })));
+    return func(data.map((item) => processDeepInternal(item, func, options)));
   }
 
   // Process object
@@ -826,7 +841,7 @@ export function processDeep(
       }
     }
     for (const [key, value] of Object.entries(data)) {
-      data[key] = processDeep(value, func, { processedObjects, specialClasses });
+      data[key] = processDeepInternal(value, func, options);
     }
     return func(data);
   }

package/src/core/common/interceptors/check-security.interceptor.ts

@@ -62,18 +62,17 @@ export class CheckSecurityInterceptor implements NestInterceptor {
 
       // Check data
       if (data && typeof data === 'object' && typeof data.securityCheck === 'function') {
-        const dataJson = JSON.stringify(data);
+        // Only capture pre-check state when debug is active (JSON.stringify is expensive)
+        const dataJson = this.config.debug ? JSON.stringify(data) : undefined;
         const response = data.securityCheck(user, force);
-        new Promise(() => {
-          if (this.config.debug && dataJson !== JSON.stringify(response)) {
-            const id = getStringIds(data);
-            console.debug(
-              'CheckSecurityInterceptor: securityCheck changed data of type',
-              data.constructor.name,
-              id && !Array.isArray(id) ? `with ID: ${id}` : '',
-            );
-          }
-        });
+        if (this.config.debug && dataJson !== JSON.stringify(response)) {
+          const id = getStringIds(data);
+          console.debug(
+            'CheckSecurityInterceptor: securityCheck changed data of type',
+            data.constructor.name,
+            id && !Array.isArray(id) ? `with ID: ${id}` : '',
+          );
+        }
         if (response && !data._doNotCheckSecurityDeep) {
           for (const key of Object.keys(response)) {
             response[key] = check(response[key]);

package/src/core/common/interfaces/server-options.interface.ts

@@ -895,6 +895,25 @@ export interface IMultiTenancy {
    * ```
    */
   roleHierarchy?: Record<string, number>;
+
+  /**
+   * TTL in milliseconds for the tenant guard's in-memory membership cache.
+   * The cache avoids repeated DB lookups when the same user accesses the same tenant.
+   * Set to 0 to disable caching (useful for testing or security-critical deployments).
+   *
+   * **Important:** This cache is process-local. In horizontally scaled deployments
+   * (multiple server instances), membership changes on one instance are not reflected
+   * on other instances until the TTL expires. For security-sensitive deployments,
+   * reduce the TTL or set to 0 to disable.
+   *
+   * Note: `CoreBetterAuthUserMapper` has an independent 15-second user cache for
+   * roles and verified status. Both caches affect revocation latency. To control both,
+   * set this to 0 and override `USER_CACHE_TTL_MS` in a custom mapper.
+   *
+   * @default 30000 (30 seconds)
+   * @since 11.21.1
+   */
+  cacheTtlMs?: number;
 }
 
 /**
@@ -2382,6 +2401,32 @@ interface IBetterAuthBase {
    */
   secret?: string;
 
+  /**
+   * Skip tenant validation on IAM endpoints.
+   *
+   * When true (default), IAM endpoints (sign-up, sign-in, sign-out, session, etc.)
+   * skip the CoreTenantGuard tenant membership check. This is the correct default
+   * because authentication typically happens BEFORE tenant context is established.
+   *
+   * Set to false for scenarios where tenant context is known at login time:
+   * - Subdomain-based tenancy (tenant-a.crm.example.com)
+   * - Invite links with embedded tenant (crm.example.com/invite/abc123)
+   * - Tenant-specific login pages (crm.example.com/login?org=tenant-a)
+   * - Tenant-specific auth policies (e.g., one tenant requires SSO)
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * // Default: IAM endpoints skip tenant validation (correct for most cases)
+   * betterAuth: { skipTenantCheck: true }
+   *
+   * // Tenant-aware authentication (subdomain-based tenancy, invite links, etc.)
+   * betterAuth: { skipTenantCheck: false }
+   * ```
+   */
+  skipTenantCheck?: boolean;
+
   /**
    * Sign-up checks configuration.
    *

package/src/core/common/services/email.service.ts

@@ -1,6 +1,7 @@
 import type SMTPPool = require('nodemailer/lib/smtp-pool');
 
-import { Injectable } from '@nestjs/common';
+import { createHash } from 'crypto';
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
 import nodemailer = require('nodemailer');
 import { Attachment } from 'nodemailer/lib/mailer';
 
@@ -12,7 +13,14 @@ import { TemplateService } from './template.service';
  * Email service
  */
 @Injectable()
-export class EmailService {
+export class EmailService implements OnModuleDestroy {
+  /**
+   * Cached transporter to avoid creating new SMTP connections per email.
+   * Reused as long as the SMTP config hasn't changed.
+   */
+  private cachedTransporter: nodemailer.Transporter | null = null;
+  private cachedSmtpConfig: string | null = null;
+
   /**
    * Inject services
    */
@@ -21,6 +29,14 @@ export class EmailService {
     protected templateService: TemplateService,
   ) {}
 
+  onModuleDestroy(): void {
+    if (this.cachedTransporter) {
+      this.cachedTransporter.close();
+      this.cachedTransporter = null;
+      this.cachedSmtpConfig = null;
+    }
+  }
+
   /**
    * Send a mail
    */
@@ -74,11 +90,16 @@ export class EmailService {
       isNonEmptyString(html);
     }
 
-    // Init transporter
-    const transporter = nodemailer.createTransport(smtp);
+    // Reuse transporter if SMTP config hasn't changed (avoids creating new connections per email)
+    // Use hash instead of raw JSON to avoid keeping credentials as a string in memory
+    const smtpKey = createHash('sha256').update(JSON.stringify(smtp)).digest('hex');
+    if (!this.cachedTransporter || this.cachedSmtpConfig !== smtpKey) {
+      this.cachedTransporter = nodemailer.createTransport(smtp);
+      this.cachedSmtpConfig = smtpKey;
+    }
 
     // Send mail
-    return transporter.sendMail({
+    return this.cachedTransporter.sendMail({
       attachments,
       from: `"${senderName}" <${senderEmail}>`,
       html,

package/src/core/common/services/request-context.service.ts

@@ -70,6 +70,10 @@ export class RequestContext {
    */
   static runWithBypassRoleGuard<T>(fn: () => T): T {
     const currentStore = this.storage.getStore();
+    // Skip context creation if already bypassed (avoids redundant object spread)
+    if (currentStore?.bypassRoleGuard) {
+      return fn();
+    }
     const context: IRequestContext = {
       ...currentStore,
       bypassRoleGuard: true,
@@ -103,6 +107,10 @@ export class RequestContext {
    */
   static runWithBypassTenantGuard<T>(fn: () => T): T {
     const currentStore = this.storage.getStore();
+    // Skip context creation if already bypassed (avoids redundant object spread)
+    if (currentStore?.bypassTenantGuard) {
+      return fn();
+    }
     const context: IRequestContext = {
       ...currentStore,
       bypassTenantGuard: true,

package/src/core/modules/better-auth/README.md

@@ -2137,4 +2137,23 @@ For frontend integration with Better-Auth, see the **[Integration Checklist](./I
 1. **Password Hashing**: Always hash passwords with SHA256 client-side before sending
 2. **2FA Redirect**: Check for `twoFactorRedirect: true` in sign-in response
 3. **Passkey Session**: Passkey auth returns session without user - call `validateSession()` to fetch user data
-4. **Credentials**: Use `credentials: 'include'` for cross-origin cookie handling
+4. **Credentials**: Use `credentials: 'include'` for cross-origin cookie handling
+
+---
+
+## Multi-Tenancy Integration
+
+When both BetterAuth and Multi-Tenancy (`multiTenancy: {}`) are active, IAM endpoints
+automatically skip tenant validation by default (`skipTenantCheck: true`). This is the
+correct default — authentication happens before tenant context is established.
+
+For tenant-aware authentication scenarios (subdomain-based tenancy, invite links, etc.),
+set `skipTenantCheck: false`:
+
+```typescript
+betterAuth: {
+  skipTenantCheck: false, // IAM endpoints require valid X-Tenant-Id header
+}
+```
+
+See the [CoreTenantModule README](../tenant/README.md#betterauth-iam-integration) for details.

package/src/core/modules/better-auth/core-better-auth-user.mapper.ts

@@ -97,10 +97,32 @@ export interface SyncedUserDocument {
  * - IAM → Legacy: Copies password from `accounts` to `users.password`
  * - Legacy → IAM: Creates account entry in `accounts` from `users.password`
  */
+/**
+ * Cached user data for mapSessionUser (lightweight: only the fields needed for MappedUser)
+ */
+interface CachedUserData {
+  expiresAt: number;
+  id: string;
+  roles: string[];
+  verified: boolean;
+}
+
 @Injectable()
 export class CoreBetterAuthUserMapper {
   private readonly logger = new Logger(CoreBetterAuthUserMapper.name);
 
+  /**
+   * Lightweight TTL cache for user DB lookups.
+   * Key: iamId (BetterAuth user ID), Value: minimal user data (id, roles, verified).
+   * Only caches ~100 bytes per entry (no full documents). Max 500 entries = ~50KB.
+   */
+  private readonly userCache = new Map<string, CachedUserData>();
+  private static readonly USER_CACHE_MAX = 500;
+
+  /** Cache TTL: 15s in production, disabled in test environments */
+  private static readonly USER_CACHE_TTL_MS =
+    process.env.VITEST === 'true' || process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'e2e' ? 0 : 15_000;
+
   constructor(@Optional() @InjectConnection() private readonly connection?: Connection) {}
 
   /**
@@ -135,6 +157,23 @@ export class CoreBetterAuthUserMapper {
     }
 
     try {
+      // Check lightweight cache first (only stores id, roles, verified — ~100 bytes per entry)
+      const ttl = CoreBetterAuthUserMapper.USER_CACHE_TTL_MS;
+      const now = Date.now();
+      const cached = ttl > 0 ? this.userCache.get(sessionUser.id) : undefined;
+      if (cached && now < cached.expiresAt) {
+        return this.createMappedUser({
+          email: sessionUser.email,
+          emailVerified: sessionUser.emailVerified,
+          iamId: sessionUser.id,
+          id: cached.id,
+          image: sessionUser.image,
+          name: sessionUser.name,
+          roles: cached.roles,
+          verified: cached.verified,
+        });
+      }
+
       // Look up the user in our database by email OR iamId
       // This ensures we find the user regardless of which system they signed up with
       const userCollection = this.connection.collection('users');
@@ -148,6 +187,11 @@ export class CoreBetterAuthUserMapper {
         // Use database verified status, fallback to Better-Auth emailVerified
         const verified = dbUser.verified === true || sessionUser.emailVerified === true;
 
+        // Cache only the minimal data needed (not the full document)
+        if (CoreBetterAuthUserMapper.USER_CACHE_TTL_MS > 0) {
+          this.cacheUserData(sessionUser.id, { id: dbUser._id.toString(), roles, verified });
+        }
+
         return this.createMappedUser({
           email: sessionUser.email,
           emailVerified: sessionUser.emailVerified,
@@ -190,32 +234,53 @@ export class CoreBetterAuthUserMapper {
     return {
       ...userData,
       _authenticatedViaBetterAuth: true,
-      hasRole: (checkRoles: string | string[]): boolean => {
-        const rolesToCheck = Array.isArray(checkRoles) ? checkRoles : [checkRoles];
+      // Bind to static method to avoid creating a new closure per request
+      hasRole: CoreBetterAuthUserMapper.createHasRole(roles, userData.verified === true),
+      roles,
+    };
+  }
 
-        // Check for special roles
-        if (rolesToCheck.includes(RoleEnum.S_EVERYONE)) {
-          return true;
-        }
+  /**
+   * Creates a hasRole function. Uses a shared factory to minimize per-request closure size.
+   * The returned function only captures `roles` (string[]) and `verified` (boolean) — no large objects.
+   */
+  private static createHasRole(roles: string[], verified: boolean): (checkRoles: string | string[]) => boolean {
+    return (checkRoles: string | string[]): boolean => {
+      const rolesToCheck = Array.isArray(checkRoles) ? checkRoles : [checkRoles];
 
-        if (rolesToCheck.includes(RoleEnum.S_USER)) {
-          return true; // User is authenticated via Better-Auth
-        }
+      if (rolesToCheck.includes(RoleEnum.S_EVERYONE)) return true;
+      if (rolesToCheck.includes(RoleEnum.S_USER)) return true;
+      if (rolesToCheck.includes(RoleEnum.S_NO_ONE)) return false;
+      if (rolesToCheck.includes(RoleEnum.S_VERIFIED)) return verified;
 
-        if (rolesToCheck.includes(RoleEnum.S_NO_ONE)) {
-          return false;
-        }
+      return rolesToCheck.some((role) => roles.includes(role));
+    };
+  }
 
-        // S_VERIFIED check - uses verified field (from DB or Better-Auth emailVerified)
-        if (rolesToCheck.includes(RoleEnum.S_VERIFIED)) {
-          return userData.verified === true;
-        }
+  /**
+   * Store minimal user data in the lightweight cache.
+   * Only stores id, roles, verified — no full documents or large objects.
+   */
+  private cacheUserData(iamId: string, data: Omit<CachedUserData, 'expiresAt'>): void {
+    // Evict oldest if at capacity (simple FIFO)
+    if (this.userCache.size >= CoreBetterAuthUserMapper.USER_CACHE_MAX) {
+      const firstKey = this.userCache.keys().next().value;
+      if (firstKey) this.userCache.delete(firstKey);
+    }
+    this.userCache.set(iamId, {
+      ...data,
+      expiresAt: Date.now() + CoreBetterAuthUserMapper.USER_CACHE_TTL_MS,
+    });
+  }
 
-        // Check actual roles
-        return rolesToCheck.some((role) => roles.includes(role));
-      },
-      roles,
-    };
+  /**
+   * Invalidate cached user data. Call when user roles or verified status change.
+   * Called automatically from `CoreUserService.setRoles()` and `CoreUserService.update()`.
+   *
+   * @param iamId - The BetterAuth user ID (from session/account, not MongoDB _id)
+   */
+  invalidateUserCache(iamId: string): void {
+    this.userCache.delete(iamId);
   }
 
   // ===================================================================================================================

package/src/core/modules/better-auth/core-better-auth.service.ts

@@ -1,4 +1,4 @@
-import { BadRequestException, Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { BadRequestException, Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { Request } from 'express';
 import { importJWK, jwtVerify } from 'jose';
@@ -61,7 +61,7 @@ export const BETTER_AUTH_CONFIG = 'BETTER_AUTH_CONFIG';
 export const BETTER_AUTH_COOKIE_DOMAIN = 'BETTER_AUTH_COOKIE_DOMAIN';
 
 @Injectable()
-export class CoreBetterAuthService {
+export class CoreBetterAuthService implements OnModuleInit {
   private readonly logger = new Logger(CoreBetterAuthService.name);
   private readonly config: IBetterAuth;
 
@@ -78,6 +78,31 @@ export class CoreBetterAuthService {
     this.config = this.resolvedConfig || this.configService?.get<IBetterAuth>('betterAuth') || {};
   }
 
+  /**
+   * Ensure performance indices exist on session and users collections.
+   * Indices are idempotent — calling createIndex on an existing index is a no-op.
+   */
+  async onModuleInit(): Promise<void> {
+    if (!this.isEnabled() || !this.connection?.db) return;
+
+    try {
+      const db = this.connection.db;
+
+      // Session collection: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
+      await db.collection('session').createIndex({ token: 1 });
+      await db.collection('session').createIndex({ userId: 1, expiresAt: 1 });
+
+      // Users collection: iamId lookup (mapSessionUser uses $or with email and iamId)
+      // email is typically already indexed by Mongoose schema, but iamId may not be
+      await db.collection('users').createIndex({ iamId: 1 }, { sparse: true });
+
+      this.logger.debug('Performance indices ensured on session and users collections');
+    } catch (error) {
+      // Non-fatal: indices improve performance but are not required for correctness
+      this.logger.warn(`Could not create performance indices: ${error instanceof Error ? error.message : 'unknown'}`);
+    }
+  }
+
   /**
    * Checks if better-auth is enabled and initialized
    * Returns true only if:

package/src/core/modules/tenant/INTEGRATION-CHECKLIST.md

@@ -133,6 +133,23 @@ import { SkipTenantCheck, Roles, RoleEnum } from '@lenne.tech/nest-server';
 async listMyTenants() { ... }
 ```
 
+### 9. BetterAuth (IAM) Coexistence
+
+When both `multiTenancy` and `betterAuth` are active, IAM endpoints (sign-in, sign-up, session, etc.)
+automatically skip tenant validation when no `X-Tenant-Id` header is sent (`betterAuth.skipTenantCheck: true`, default).
+If a header IS present, normal membership validation runs.
+
+For tenant-aware authentication (subdomain-based, invite links, SSO per tenant), opt out:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  skipTenantCheck: false, // IAM endpoints require valid X-Tenant-Id header
+}
+```
+
+See [Tenant README — BetterAuth Integration](./README.md#betterauth-iam-integration) for details.
+
 ## Verification Checklist
 
 - [ ] `pnpm run build` succeeds
@@ -143,6 +160,7 @@ async listMyTenants() { ... }
 - [ ] Non-member gets 403 "Not a member of this tenant"
 - [ ] Unauthenticated + header → 403 "Authentication required for tenant access"
 - [ ] Public endpoint accessing tenantId-schema without context throws 403 (Safety Net)
+- [ ] IAM endpoints work without `X-Tenant-Id` header when `skipTenantCheck: true` (default)
 
 ## Security
 
@@ -162,4 +180,5 @@ async listMyTenants() { ... }
 | Querying membership without bypass               | Empty results due to tenant filter | Use `RequestContext.runWithBypassTenantGuard()`                            |
 | Public endpoint accessing tenantId-schema        | 403 Safety Net exception           | Use `@SkipTenantCheck()` + `RequestContext.runWithBypassTenantGuard()`     |
 | Passing user-supplied tenantId to create()       | Cross-tenant write possible        | Let plugin auto-set tenantId from context                                  |
-| Custom hierarchy doesn't match config            | Roles fail unexpectedly            | Ensure `createHierarchyRoles()` input matches `multiTenancy.roleHierarchy` |
+| Custom hierarchy doesn't match config            | Roles fail unexpectedly            | Ensure `createHierarchyRoles()` input matches `multiTenancy.roleHierarchy` |
+| `@SkipTenantCheck()` on BetterAuth handler       | Redundant since v11.21.2           | Remove — auto-skip handles this via `betterAuth.skipTenantCheck` (default) |