@lenne.tech/nest-server 11.21.0 → 11.21.2

package/src/core/modules/tenant/README.md

@@ -43,6 +43,7 @@ multiTenancy: {
   membershipModel: 'TenantMember',  // Mongoose model name (default)
   adminBypass: true,                 // System admins bypass membership (default: true)
   excludeSchemas: ['User', 'Session'], // Schemas without tenant filtering
+  cacheTtlMs: 30000,                // Membership cache TTL in ms (default: 30s, 0 = disabled)
   roleHierarchy: {                   // Custom role hierarchy (default below)
     member: 1,
     manager: 2,
@@ -194,9 +195,45 @@ CoreTenantModule.forRoot({ service: TenantService });
 
 ## Performance Considerations
 
-The `CoreTenantGuard` resolves tenant memberships (`resolveUserTenantIds()`) on every authenticated request that does not include an `X-Tenant-Id` header. This is necessary so the Mongoose plugin can filter by `{ tenantId: { $in: tenantIds } }`.
+### Membership Cache (since 11.21.1)
 
-For high-frequency endpoints that don't access tenant-scoped data, use `@SkipTenantCheck()` to avoid the membership lookup.
+The `CoreTenantGuard` uses an in-memory TTL cache for membership lookups and tenant ID resolution. This avoids repeated DB queries when the same user accesses the same tenant across multiple requests.
+
+```typescript
+// config.env.ts — configure or disable the cache
+multiTenancy: {
+  cacheTtlMs: 30000, // default: 30s. Set to 0 to disable.
+}
+```
+
+**Cache behavior:**
+
+- **Positive-only:** Only active memberships are cached. Non-member lookups always hit the DB (security-first).
+- **Auto-invalidation:** `CoreTenantService.addMember/removeMember/updateMemberRole` automatically invalidate the cache.
+- **Config-change detection:** Cache is flushed when `multiTenancy` config changes (e.g., `roleHierarchy` update).
+- **Bounded:** Max 500 entries with FIFO eviction. Memory overhead: ~100-250 KB.
+
+**Important:** The cache is process-local. In horizontally scaled deployments (multiple instances), membership changes on one instance are not reflected on other instances until the TTL expires. Set `cacheTtlMs: 0` for security-sensitive deployments.
+
+### Manual Cache Invalidation
+
+When extending `CoreTenantService` with custom membership mutation methods, call `invalidateUser()` after changes:
+
+```typescript
+@Injectable()
+export class TenantService extends CoreTenantService {
+  async customMembershipChange(tenantId: string, userId: string) {
+    // ... your logic ...
+    this.tenantGuard?.invalidateUser(userId);
+  }
+}
+```
+
+Use `invalidateAll()` to flush the entire cache (e.g., after bulk operations).
+
+### SkipTenantCheck
+
+For high-frequency endpoints that don't access tenant-scoped data, use `@SkipTenantCheck()` to avoid the membership lookup entirely.
 
 ## Security Notes
 
@@ -225,8 +262,40 @@ export class TenantMemberController {
 }
 ```
 
+### BetterAuth (IAM) Integration
+
+When both Multi-Tenancy and BetterAuth are active, IAM endpoints (sign-up, sign-in, sign-out,
+session, etc.) automatically skip tenant validation by default. This is because authentication
+typically happens before tenant context is established.
+
+**Behavior with `skipTenantCheck: true` (default):**
+
+- No `X-Tenant-Id` header → skip tenant validation, proceed without tenant context
+- `X-Tenant-Id` header IS provided → validate normally (membership check, tenant context set)
+
+The tenant is optional but respected when present. This allows tenant-aware auth flows
+(subdomain-based, invite links, etc.) to coexist with the default cross-tenant behavior.
+
+**Configuration:**
+
+```typescript
+// config.env.ts — Default: skip tenant validation on IAM endpoints (most projects)
+betterAuth: {
+  skipTenantCheck: true, // (default) No X-Tenant-Id header → skip; header present → validate
+}
+
+// config.env.ts — Tenant-aware auth (subdomain-based, invite links, SSO per tenant)
+betterAuth: {
+  skipTenantCheck: false, // IAM endpoints ALWAYS require valid X-Tenant-Id header
+}
+```
+
+When `skipTenantCheck: false`, IAM endpoints will require a valid `X-Tenant-Id` header
+and the user must be a member of that tenant for protected endpoints.
+
 ## Related
 
 - [Integration Checklist](./INTEGRATION-CHECKLIST.md)
 - [Configurable Features](../../../.claude/rules/configurable-features.md)
+
 - [Request Lifecycle](../../../docs/REQUEST-LIFECYCLE.md)

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -1,4 +1,4 @@
-import { CanActivate, ExecutionContext, ForbiddenException, Injectable, Logger } from '@nestjs/common';
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
 import { InjectModel } from '@nestjs/mongoose';
@@ -17,6 +17,22 @@ import {
   mergeRolesMetadata,
 } from './core-tenant.helpers';
 
+/**
+ * Cached membership entry with TTL
+ */
+interface CachedMembership {
+  expiresAt: number;
+  result: CoreTenantMemberModel | null;
+}
+
+/**
+ * Cached tenant IDs entry with TTL
+ */
+interface CachedTenantIds {
+  expiresAt: number;
+  ids: string[];
+}
+
 /**
  * Global guard for multi-tenancy with defense-in-depth security.
  *
@@ -36,11 +52,18 @@ import {
  * - Tenant context (header present): checks against membership.role only (user.roles ignored)
  * - No tenant context: checks against user.roles
  *
+ * BetterAuth (IAM) auto-skip behavior (skipTenantCheck config, default: true):
+ * - No X-Tenant-Id header: skip tenant validation entirely (auth before tenant is the expected case)
+ * - X-Tenant-Id header IS present: fall through to normal validation (membership check + context)
+ * This allows tenant-aware auth flows (subdomain-based, invite links, etc.) to coexist with
+ * the default cross-tenant behavior. The tenant is optional but respected when provided.
+ *
  * Flow:
  * 1. Config check: multiTenancy enabled?
  * 2. Parse header (X-Tenant-Id, max 128 chars, trimmed)
  * 3. @SkipTenantCheck → role check against user.roles, no tenant context
  * 4. Read @Roles() metadata, filter out system roles
+ * 5. BetterAuth auto-skip (betterAuth.skipTenantCheck config + no header) → skip, no tenant context
  *
  * HEADER PRESENT:
  *   - System ADMIN (adminBypass: true) → set req.tenantId + isAdminBypass
@@ -58,13 +81,81 @@ import {
  *   - No user + checkable roles → 403 "Authentication required"
  */
 @Injectable()
-export class CoreTenantGuard implements CanActivate {
+export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
   private readonly logger = new Logger(CoreTenantGuard.name);
 
+  /**
+   * In-memory TTL cache for membership lookups.
+   * Key: `${userId}:${tenantId}`, Value: cached membership result with expiry.
+   * Eliminates repeated DB queries for the same user+tenant combination.
+   */
+  private readonly membershipCache = new Map<string, CachedMembership>();
+
+  /**
+   * In-memory TTL cache for tenant ID resolution (no-header path).
+   * Key: `${userId}` or `${userId}:${minLevel}`, Value: cached tenant IDs with expiry.
+   */
+  private readonly tenantIdsCache = new Map<string, CachedTenantIds>();
+
+  /** Cache TTL in milliseconds. Configurable via multiTenancy.cacheTtlMs (default: 30s, 0 = disabled) */
+  private cacheTtlMs: number = 30_000;
+  /** Maximum cache entries before eviction */
+  private static readonly MAX_CACHE_SIZE = 500;
+  /** Cleanup interval handle */
+  private cleanupInterval: NodeJS.Timeout | null = null;
+  /** Tracks the last seen config reference to detect config changes (e.g., roleHierarchy) */
+  private lastSeenConfig: object | null = null;
+
   constructor(
     private readonly reflector: Reflector,
     @InjectModel(TENANT_MEMBER_MODEL_TOKEN) private readonly memberModel: Model<CoreTenantMemberModel>,
-  ) {}
+  ) {
+    // Clean up expired cache entries every 60 seconds
+    this.cleanupInterval = setInterval(() => this.evictExpired(), 60_000);
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  onModuleDestroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.membershipCache.clear();
+    this.tenantIdsCache.clear();
+  }
+
+  /**
+   * Invalidate all cache entries for a specific user.
+   * Call this when memberships change (add/remove/update).
+   *
+   * Note: userId must not contain ':' characters (used as cache key delimiter).
+   * MongoDB ObjectIds and standard UUID formats are safe.
+   *
+   * @param userId - The user ID whose cache entries should be invalidated
+   */
+  invalidateUser(userId: string): void {
+    for (const key of this.membershipCache.keys()) {
+      if (key.startsWith(`${userId}:`)) {
+        this.membershipCache.delete(key);
+      }
+    }
+    for (const key of this.tenantIdsCache.keys()) {
+      if (key === userId || key.startsWith(`${userId}:`)) {
+        this.tenantIdsCache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all cache entries.
+   * Useful when configuration changes (e.g., roleHierarchy) or for testing.
+   */
+  invalidateAll(): void {
+    this.membershipCache.clear();
+    this.tenantIdsCache.clear();
+  }
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
     const config = ConfigService.configFastButReadOnly?.multiTenancy;
@@ -72,6 +163,16 @@ export class CoreTenantGuard implements CanActivate {
       return true;
     }
 
+    // Detect config changes (e.g., roleHierarchy modified in tests) and flush caches
+    if (this.lastSeenConfig !== config) {
+      this.lastSeenConfig = config;
+      // Default 30s in production, 0 (disabled) in test environments to avoid stale data between test cases
+      const isTestEnv =
+        process.env.VITEST === 'true' || process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'e2e';
+      this.cacheTtlMs = config.cacheTtlMs ?? (isTestEnv ? 0 : 30_000);
+      this.invalidateAll();
+    }
+
     const request = this.getRequest(context);
     if (!request) {
       return true;
@@ -86,25 +187,45 @@ export class CoreTenantGuard implements CanActivate {
     // Read @Roles() metadata and filter to non-system roles
     const rolesMetadata = this.reflector.getAll<string[][]>('roles', [context.getHandler(), context.getClass()]);
     const roles = mergeRolesMetadata(rolesMetadata);
-    const checkableRoles = roles.filter((r) => !isSystemRole(r));
-    const minRequiredLevel = getMinRequiredLevel(checkableRoles);
 
     const user = request.user;
     const adminBypass = config.adminBypass !== false;
     const isAdmin = adminBypass && user?.roles?.includes(RoleEnum.ADMIN);
 
-    // @SkipTenantCheck → no tenant context, but role check against user.roles
-    const skipTenantCheck = this.reflector.getAllAndOverride<boolean>(SKIP_TENANT_CHECK_KEY, [
+    // Filter to checkable (non-system) roles only when needed (avoids array allocation on fast paths)
+    const hasNonSystemRoles = roles.some((r) => !isSystemRole(r));
+    const checkableRoles = hasNonSystemRoles ? roles.filter((r) => !isSystemRole(r)) : [];
+    const minRequiredLevel = checkableRoles.length > 0 ? getMinRequiredLevel(checkableRoles) : undefined;
+
+    // @SkipTenantCheck decorator → no tenant context, but role check against user.roles
+    const hasSkipDecorator = this.reflector.getAllAndOverride<boolean>(SKIP_TENANT_CHECK_KEY, [
       context.getHandler(),
       context.getClass(),
     ]);
-    if (skipTenantCheck) {
-      if (checkableRoles.length > 0 && user) {
-        if (!isAdmin && !checkRoleAccess(checkableRoles, user.roles, undefined)) {
-          throw new ForbiddenException('Insufficient role');
-        }
+    if (hasSkipDecorator) {
+      return this.skipWithUserRoleCheck(checkableRoles, user, isAdmin);
+    }
+
+    // Auto-skip tenant check for BetterAuth (IAM) handlers when configured,
+    // but ONLY when no X-Tenant-Id header is present.
+    // - No header: skip tenant validation (auth before tenant is the expected case for most projects)
+    // - Header present: fall through to normal validation (membership check, tenant context set)
+    // This allows tenant-aware auth scenarios to coexist with the default cross-tenant behavior.
+    // Default config: betterAuth.skipTenantCheck = true (note: distinct from @SkipTenantCheck decorator above).
+    if (!hasSkipDecorator && !headerTenantId && this.isBetterAuthHandler(context)) {
+      const betterAuthConfig = ConfigService.configFastButReadOnly?.betterAuth;
+      // Boolean shorthand: `betterAuth: true` → skip, `betterAuth: false` → no skip
+      const shouldSkip =
+        betterAuthConfig !== null && betterAuthConfig !== undefined && typeof betterAuthConfig === 'object'
+          ? betterAuthConfig.skipTenantCheck !== false // default: true
+          : betterAuthConfig !== false; // true/undefined → skip; false → no skip
+
+      if (shouldSkip) {
+        this.logger.debug(
+          `BetterAuth auto-skip: ${context.getClass().name}::${context.getHandler().name} — no X-Tenant-Id header, skipping tenant validation`,
+        );
+        return this.skipWithUserRoleCheck(checkableRoles, user, isAdmin);
       }
-      return true;
     }
 
     // === HEADER PRESENT ===
@@ -115,7 +236,9 @@ export class CoreTenantGuard implements CanActivate {
         request.tenantId = headerTenantId;
         request.isAdminBypass = true;
         const requiredRole = checkableRoles.length > 0 ? checkableRoles.join(',') : 'none';
-        this.logger.log(`Admin bypass: user ${user.id} accessing tenant ${headerTenantId} (required: ${requiredRole})`);
+        // Sanitize control characters to prevent log injection
+        const safeTenantId = headerTenantId.replace(/[\r\n\t]/g, '_');
+        this.logger.log(`Admin bypass: user ${user.id} accessing tenant ${safeTenantId} (required: ${requiredRole})`);
         return true;
       }
 
@@ -125,14 +248,7 @@ export class CoreTenantGuard implements CanActivate {
       }
 
       // Authenticated non-admin user: MUST be active member
-      const membership = await this.memberModel
-        .findOne({
-          status: TenantMemberStatus.ACTIVE,
-          tenant: headerTenantId,
-          user: user.id,
-        })
-        .lean()
-        .exec();
+      const membership = await this.findMembershipCached(user.id, headerTenantId);
 
       if (!membership) {
         throw new ForbiddenException('Not a member of this tenant');
@@ -193,33 +309,59 @@ export class CoreTenantGuard implements CanActivate {
    * This allows the tenant plugin to filter by { tenantId: { $in: tenantIds } }
    * when no specific tenant header is set.
    *
+   * Uses a process-level TTL cache to avoid repeated DB queries for the same user.
+   *
    * @param minLevel - When set, only include memberships where role level >= minLevel
    */
   private async resolveUserTenantIds(request: any, minLevel?: number): Promise<void> {
-    // Skip if already resolved (request-scoped caching)
+    // Skip if already resolved on this request
     if (request.tenantIds) {
       return;
     }
 
+    const userId = request.user.id;
+    const ttl = this.cacheTtlMs;
+
+    // When cache is enabled, check process-level cache
+    if (ttl > 0) {
+      const cacheKey = minLevel !== undefined ? `${userId}:${minLevel}` : userId;
+      const now = Date.now();
+      const cached = this.tenantIdsCache.get(cacheKey);
+      if (cached && now < cached.expiresAt) {
+        request.tenantIds = cached.ids;
+        return;
+      }
+    }
+
     const memberships = await this.memberModel
       .find({
         status: TenantMemberStatus.ACTIVE,
-        user: request.user.id,
+        user: userId,
       })
       .select('tenant role')
       .lean()
       .exec();
 
+    let ids: string[];
     if (minLevel !== undefined) {
       const hierarchy = getRoleHierarchy();
-      request.tenantIds = memberships
+      ids = memberships
         .filter((m) => {
           const level = hierarchy[m.role as string] ?? 0;
           return level >= minLevel;
         })
-        .map((m) => m.tenant);
+        .map((m) => m.tenant as string);
     } else {
-      request.tenantIds = memberships.map((m) => m.tenant);
+      ids = memberships.map((m) => m.tenant as string);
+    }
+
+    request.tenantIds = ids;
+
+    // Store in process-level cache when enabled
+    if (ttl > 0) {
+      const cacheKey = minLevel !== undefined ? `${userId}:${minLevel}` : userId;
+      this.evictIfOverCapacity(this.tenantIdsCache);
+      this.tenantIdsCache.set(cacheKey, { expiresAt: Date.now() + ttl, ids });
     }
   }
 
@@ -237,4 +379,139 @@ export class CoreTenantGuard implements CanActivate {
       return null;
     }
   }
+
+  // ===================================================================================================================
+  // Cache helpers
+  // ===================================================================================================================
+
+  /**
+   * Look up a membership with process-level TTL cache.
+   * Avoids repeated DB queries when the same user accesses the same tenant repeatedly.
+   */
+  private async findMembershipCached(userId: string, tenantId: string): Promise<CoreTenantMemberModel | null> {
+    const ttl = this.cacheTtlMs;
+
+    // Cache disabled (ttl = 0): always query DB
+    if (ttl <= 0) {
+      return this.memberModel
+        .findOne({ status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId })
+        .lean()
+        .exec() as Promise<CoreTenantMemberModel | null>;
+    }
+
+    const key = `${userId}:${tenantId}`;
+    const now = Date.now();
+
+    const cached = this.membershipCache.get(key);
+    if (cached && now < cached.expiresAt) {
+      return cached.result;
+    }
+
+    const result = (await this.memberModel
+      .findOne({
+        status: TenantMemberStatus.ACTIVE,
+        tenant: tenantId,
+        user: userId,
+      })
+      .lean()
+      .exec()) as CoreTenantMemberModel | null;
+
+    // Only cache positive results (active membership found).
+    // Negative results (null) are NOT cached to ensure that:
+    // - Newly added members are recognized immediately
+    // - Removed memberships lead to immediate denial
+    if (result) {
+      this.evictIfOverCapacity(this.membershipCache);
+      this.membershipCache.set(key, { expiresAt: now + ttl, result });
+    } else {
+      // Ensure stale positive cache entries are removed
+      this.membershipCache.delete(key);
+    }
+    return result;
+  }
+
+  /**
+   * Evict the oldest entry if the cache exceeds MAX_CACHE_SIZE.
+   * Uses a simple FIFO strategy (Map insertion order).
+   */
+  private evictIfOverCapacity<T>(cache: Map<string, T>): void {
+    if (cache.size >= CoreTenantGuard.MAX_CACHE_SIZE) {
+      // Delete first 10% to avoid evicting on every insert
+      const deleteCount = Math.max(1, Math.floor(CoreTenantGuard.MAX_CACHE_SIZE * 0.1));
+      let deleted = 0;
+      for (const key of cache.keys()) {
+        if (deleted >= deleteCount) break;
+        cache.delete(key);
+        deleted++;
+      }
+    }
+  }
+
+  /**
+   * Remove all expired entries from both caches.
+   * Called periodically by the cleanup interval.
+   */
+  private evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.membershipCache.entries()) {
+      if (now >= entry.expiresAt) {
+        this.membershipCache.delete(key);
+      }
+    }
+    for (const [key, entry] of this.tenantIdsCache.entries()) {
+      if (now >= entry.expiresAt) {
+        this.tenantIdsCache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Skip tenant validation but still check non-system roles against user.roles.
+   * Shared by @SkipTenantCheck decorator path and BetterAuth auto-skip path.
+   */
+  private skipWithUserRoleCheck(checkableRoles: string[], user: any, isAdmin: boolean): true {
+    if (checkableRoles.length > 0) {
+      // Defense-in-depth: reject unauthenticated access even if RolesGuard is absent
+      if (!user) {
+        throw new ForbiddenException('Authentication required');
+      }
+      if (!isAdmin && !checkRoleAccess(checkableRoles, user.roles, undefined)) {
+        throw new ForbiddenException('Insufficient role');
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Check if the current request is handled by a BetterAuth (IAM) handler
+   * (controller or resolver). Used for auto-skip tenant check on IAM endpoints.
+   *
+   * Uses require() instead of import to avoid a circular dependency:
+   * tenant module → better-auth module (which may depend on tenant module indirectly).
+   * The require() is lazy and resolved only when needed (Node.js caches the result).
+   */
+  private isBetterAuthHandler(context: ExecutionContext): boolean {
+    const handler = context.getClass();
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { CoreBetterAuthController } =
+        require('../better-auth/core-better-auth.controller') as typeof import('../better-auth/core-better-auth.controller');
+      if (handler === CoreBetterAuthController || handler.prototype instanceof CoreBetterAuthController) {
+        return true;
+      }
+    } catch {
+      /* BetterAuth controller not available */
+    }
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { CoreBetterAuthResolver } =
+        require('../better-auth/core-better-auth.resolver') as typeof import('../better-auth/core-better-auth.resolver');
+      if (handler === CoreBetterAuthResolver || handler.prototype instanceof CoreBetterAuthResolver) {
+        return true;
+      }
+    } catch {
+      /* BetterAuth resolver not available */
+    }
+    return false;
+  }
 }

package/src/core/modules/tenant/core-tenant.service.ts

@@ -1,4 +1,4 @@
-import { BadRequestException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger, NotFoundException, Optional } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
 import { Model } from 'mongoose';
 
@@ -6,6 +6,7 @@ import { ConfigService } from '../../common/services/config.service';
 import { RequestContext } from '../../common/services/request-context.service';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
 import { DEFAULT_ROLE_HIERARCHY, TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus } from './core-tenant.enums';
+import { CoreTenantGuard } from './core-tenant.guard';
 
 /**
  * Core service for tenant membership operations.
@@ -30,7 +31,10 @@ import { DEFAULT_ROLE_HIERARCHY, TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus }
 export class CoreTenantService {
   protected readonly logger = new Logger(CoreTenantService.name);
 
-  constructor(@InjectModel(TENANT_MEMBER_MODEL_TOKEN) protected readonly memberModel: Model<CoreTenantMemberModel>) {}
+  constructor(
+    @InjectModel(TENANT_MEMBER_MODEL_TOKEN) protected readonly memberModel: Model<CoreTenantMemberModel>,
+    @Optional() protected readonly tenantGuard?: CoreTenantGuard,
+  ) {}
 
   /**
    * Get the configured role hierarchy.
@@ -106,7 +110,7 @@ export class CoreTenantService {
       }
       // Reactivate suspended/invited membership
       return RequestContext.runWithBypassTenantGuard(async () => {
-        return this.memberModel
+        const result = (await this.memberModel
           .findOneAndUpdate(
             { tenant: tenantId, user: userId },
             {
@@ -118,7 +122,9 @@ export class CoreTenantService {
             { new: true },
           )
           .lean()
-          .exec() as Promise<CoreTenantMemberModel>;
+          .exec()) as CoreTenantMemberModel;
+        this.tenantGuard?.invalidateUser(userId);
+        return result;
       });
     }
 
@@ -131,6 +137,7 @@ export class CoreTenantService {
         tenant: tenantId,
         user: userId,
       });
+      this.tenantGuard?.invalidateUser(userId);
       return doc.toObject() as CoreTenantMemberModel;
     });
   }
@@ -162,6 +169,7 @@ export class CoreTenantService {
         throw new NotFoundException('Membership not found');
       }
 
+      this.tenantGuard?.invalidateUser(userId);
       return result as CoreTenantMemberModel;
     });
   }
@@ -202,6 +210,7 @@ export class CoreTenantService {
         throw new NotFoundException('Active membership not found');
       }
 
+      this.tenantGuard?.invalidateUser(userId);
       return result as CoreTenantMemberModel;
     });
   }

package/src/core/modules/user/core-user.service.ts

@@ -253,7 +253,14 @@ export abstract class CoreUserService<
     // Update and return user
     return this.process(
       async () => {
-        return await this.mainDbModel.findByIdAndUpdate(userId, { roles }).exec();
+        const user = await this.mainDbModel.findByIdAndUpdate(userId, { roles }).exec();
+
+        // Invalidate BetterAuth user cache so changed roles take effect immediately
+        if (this.options?.betterAuthUserMapper && (user as any)?.iamId) {
+          this.options.betterAuthUserMapper.invalidateUserCache((user as any).iamId);
+        }
+
+        return user;
       },
       { serviceOptions },
     );
@@ -313,6 +320,15 @@ export abstract class CoreUserService<
       }
     }
 
+    // Invalidate BetterAuth user cache when roles or verified status may have changed
+    if (this.options?.betterAuthUserMapper && (oldUser as any)?.iamId) {
+      const rolesChanged = 'roles' in (input as any);
+      const verifiedChanged = 'verified' in (input as any) || 'emailVerified' in (input as any);
+      if (rolesChanged || verifiedChanged) {
+        this.options.betterAuthUserMapper.invalidateUserCache((oldUser as any).iamId);
+      }
+    }
+
     return updatedUser;
   }