@lenne.tech/nest-server 11.20.1 → 11.21.0

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

@@ -0,0 +1,240 @@
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable, Logger } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+import { RoleEnum } from '../../common/enums/role.enum';
+import { ConfigService } from '../../common/services/config.service';
+import { CoreTenantMemberModel } from './core-tenant-member.model';
+import { SKIP_TENANT_CHECK_KEY } from './core-tenant.decorators';
+import { TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus } from './core-tenant.enums';
+import {
+  checkRoleAccess,
+  getMinRequiredLevel,
+  getRoleHierarchy,
+  isSystemRole,
+  mergeRolesMetadata,
+} from './core-tenant.helpers';
+
+/**
+ * Global guard for multi-tenancy with defense-in-depth security.
+ *
+ * Only registered as APP_GUARD when multiTenancy is active.
+ * Runs after auth guards to validate tenant membership and role access.
+ *
+ * This guard is responsible for ALL non-system role checks when multiTenancy is active.
+ * RolesGuard passes through non-system roles to this guard.
+ *
+ * Security model:
+ * - Guard level: Membership validation, admin bypass, role checks (hierarchy + normal)
+ * - Plugin level: Safety net — ForbiddenException when tenantId-schema accessed without context
+ *
+ * Role check semantics:
+ * - Hierarchy roles (in roleHierarchy config): level comparison — higher includes lower
+ * - Normal roles (not in roleHierarchy): exact match — no compensation by higher role
+ * - Tenant context (header present): checks against membership.role only (user.roles ignored)
+ * - No tenant context: checks against user.roles
+ *
+ * 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
+ *
+ * HEADER PRESENT:
+ *   - System ADMIN (adminBypass: true) → set req.tenantId + isAdminBypass
+ *   - No user → 403 "Authentication required for tenant access"
+ *   - Authenticated non-admin user:
+ *     - Active member → checkRoleAccess against membership.role → set req.tenantId + tenantRole
+ *     - Not active member → ALWAYS 403
+ *
+ * NO HEADER:
+ *   - System ADMIN → set isAdminBypass (sees all data)
+ *   - Authenticated + checkable roles → checkRoleAccess against user.roles
+ *     → resolveUserTenantIds with minLevel filter
+ *   - Authenticated + no checkable roles → resolveUserTenantIds (all memberships)
+ *   - No user + no checkable roles → pass (plugin safety net catches tenantId-schema access)
+ *   - No user + checkable roles → 403 "Authentication required"
+ */
+@Injectable()
+export class CoreTenantGuard implements CanActivate {
+  private readonly logger = new Logger(CoreTenantGuard.name);
+
+  constructor(
+    private readonly reflector: Reflector,
+    @InjectModel(TENANT_MEMBER_MODEL_TOKEN) private readonly memberModel: Model<CoreTenantMemberModel>,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const config = ConfigService.configFastButReadOnly?.multiTenancy;
+    if (!config || config.enabled === false) {
+      return true;
+    }
+
+    const request = this.getRequest(context);
+    if (!request) {
+      return true;
+    }
+
+    // Parse tenant header
+    const headerName = (config.headerName ?? 'x-tenant-id').toLowerCase();
+    const rawHeader = request.headers?.[headerName] as string | undefined;
+    const headerTenantId =
+      rawHeader && typeof rawHeader === 'string' && rawHeader.length <= 128 ? rawHeader.trim() : undefined;
+
+    // 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, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (skipTenantCheck) {
+      if (checkableRoles.length > 0 && user) {
+        if (!isAdmin && !checkRoleAccess(checkableRoles, user.roles, undefined)) {
+          throw new ForbiddenException('Insufficient role');
+        }
+      }
+      return true;
+    }
+
+    // === HEADER PRESENT ===
+    if (headerTenantId) {
+      // Admin bypass: set req.tenantId so plugin filters (read by RequestContextMiddleware
+      // lazy getter → context.tenantId, also consumed by @CurrentTenant() via RequestContext)
+      if (isAdmin) {
+        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})`);
+        return true;
+      }
+
+      // No user + header → 403 (tenant access requires authentication)
+      if (!user) {
+        throw new ForbiddenException('Authentication required for tenant access');
+      }
+
+      // Authenticated non-admin user: MUST be active member
+      const membership = await this.memberModel
+        .findOne({
+          status: TenantMemberStatus.ACTIVE,
+          tenant: headerTenantId,
+          user: user.id,
+        })
+        .lean()
+        .exec();
+
+      if (!membership) {
+        throw new ForbiddenException('Not a member of this tenant');
+      }
+
+      const memberRole = membership.role as string;
+
+      // Check role access if roles are required (hierarchy + normal, against membership.role)
+      if (checkableRoles.length > 0) {
+        if (!checkRoleAccess(checkableRoles, undefined, memberRole)) {
+          throw new ForbiddenException('Insufficient tenant role');
+        }
+      }
+
+      // Set validated tenant context on request (consumed by RequestContextMiddleware
+      // lazy getter → context.tenantId / context.tenantRole, and by @CurrentTenant() via RequestContext)
+      request.tenantId = headerTenantId;
+      request.tenantRole = memberRole;
+      return true;
+    }
+
+    // === NO HEADER ===
+
+    // Admin without header → sees all data
+    if (isAdmin) {
+      request.isAdminBypass = true;
+      return true;
+    }
+
+    // Checkable roles present
+    if (checkableRoles.length > 0) {
+      // No user + roles required → 403
+      if (!user) {
+        throw new ForbiddenException('Authentication required');
+      }
+
+      // Check role access against user.roles (hierarchy: level comparison, normal: exact match)
+      if (!checkRoleAccess(checkableRoles, user.roles, undefined)) {
+        throw new ForbiddenException('Insufficient role');
+      }
+
+      // Resolve tenant IDs filtered by minimum required hierarchy level
+      await this.resolveUserTenantIds(request, minRequiredLevel);
+      return true;
+    }
+
+    // Authenticated user without header and no checkable roles: resolve their tenant memberships
+    // so the plugin can filter by { tenantId: { $in: tenantIds } }
+    if (user) {
+      await this.resolveUserTenantIds(request);
+    }
+
+    return true;
+  }
+
+  /**
+   * Look up all active tenant memberships for the user and store them on the request.
+   * This allows the tenant plugin to filter by { tenantId: { $in: tenantIds } }
+   * when no specific tenant header is set.
+   *
+   * @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)
+    if (request.tenantIds) {
+      return;
+    }
+
+    const memberships = await this.memberModel
+      .find({
+        status: TenantMemberStatus.ACTIVE,
+        user: request.user.id,
+      })
+      .select('tenant role')
+      .lean()
+      .exec();
+
+    if (minLevel !== undefined) {
+      const hierarchy = getRoleHierarchy();
+      request.tenantIds = memberships
+        .filter((m) => {
+          const level = hierarchy[m.role as string] ?? 0;
+          return level >= minLevel;
+        })
+        .map((m) => m.tenant);
+    } else {
+      request.tenantIds = memberships.map((m) => m.tenant);
+    }
+  }
+
+  /**
+   * Extract request from GraphQL or HTTP context
+   */
+  private getRequest(context: ExecutionContext): any {
+    if (context.getType<GqlContextType>() === 'graphql') {
+      const ctx = GqlExecutionContext.create(context);
+      return ctx.getContext()?.req;
+    }
+    try {
+      return context.switchToHttp().getRequest();
+    } catch {
+      return null;
+    }
+  }
+}

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

@@ -0,0 +1,103 @@
+import { ConfigService } from '../../common/services/config.service';
+import { DEFAULT_ROLE_HIERARCHY } from './core-tenant.enums';
+
+const SYSTEM_ROLE_PREFIX = 's_';
+
+/**
+ * Merge handler-level and class-level @Roles() metadata arrays into a single flat array.
+ * Used by RolesGuard, BetterAuthRolesGuard, and CoreTenantGuard to avoid code duplication.
+ *
+ * @param meta - Two-element tuple [handlerRoles, classRoles] from Reflector.getAll or Reflect.getMetadata
+ */
+export function mergeRolesMetadata(meta: (string[] | undefined)[]): string[] {
+  return meta[0] ? (meta[1] ? [...meta[0], ...meta[1]] : meta[0]) : meta[1] || [];
+}
+
+/**
+ * Get the configured role hierarchy or the default.
+ */
+export function getRoleHierarchy(): Record<string, number> {
+  return ConfigService.configFastButReadOnly?.multiTenancy?.roleHierarchy ?? DEFAULT_ROLE_HIERARCHY;
+}
+
+/**
+ * Check if a role is a system role (S_USER, S_EVERYONE, etc.).
+ * System roles are handled by RolesGuard, not CoreTenantGuard.
+ */
+export function isSystemRole(role: string): boolean {
+  return role.startsWith(SYSTEM_ROLE_PREFIX);
+}
+
+/**
+ * Check if multiTenancy is configured and enabled.
+ */
+export function isMultiTenancyActive(): boolean {
+  const config = ConfigService.configFastButReadOnly?.multiTenancy;
+  return !!config && config.enabled !== false;
+}
+
+/**
+ * Check if a role is a hierarchy role (present in the configured role hierarchy).
+ * Returns false when multiTenancy is disabled to avoid false positives.
+ */
+export function isHierarchyRole(role: string): boolean {
+  if (!isMultiTenancyActive()) return false;
+  const hierarchy = getRoleHierarchy();
+  return role in hierarchy;
+}
+
+/**
+ * Get the minimum required level from a set of roles.
+ * Only considers roles that exist in the hierarchy.
+ * Returns undefined if no hierarchy roles found.
+ */
+export function getMinRequiredLevel(roles: string[]): number | undefined {
+  const hierarchy = getRoleHierarchy();
+  const levels = roles.filter((r) => r in hierarchy).map((r) => hierarchy[r]);
+  if (levels.length === 0) return undefined;
+  return Math.min(...levels);
+}
+
+/**
+ * Unified role access check for both tenant and non-tenant context.
+ * Handles hierarchy roles (level comparison) AND normal roles (exact match).
+ *
+ * @param requiredRoles - roles from @Roles/@Restricted (system roles should be filtered out by caller)
+ * @param userRoles - user.roles array (used when no tenantRole)
+ * @param tenantRole - membership.role (used when tenant context active)
+ *
+ * When tenantRole is set: checks against [tenantRole] (tenant overrides user.roles)
+ * When no tenantRole: checks against userRoles
+ *
+ * Hierarchy roles → level comparison (higher includes lower)
+ * Normal roles → exact match (no compensation by higher role)
+ *
+ * OR semantics: any match (hierarchy OR normal) is sufficient.
+ */
+export function checkRoleAccess(requiredRoles: string[], userRoles?: string[], tenantRole?: string): boolean {
+  const availableRoles = tenantRole ? [tenantRole] : (userRoles ?? []);
+  if (availableRoles.length === 0) return false;
+
+  // When multiTenancy is disabled, treat all roles as normal (exact match only)
+  const multiTenancyActive = isMultiTenancyActive();
+  const hierarchy = multiTenancyActive ? getRoleHierarchy() : {};
+  const hierarchyRequired = requiredRoles.filter((r) => r in hierarchy);
+  const nonHierarchyRequired = requiredRoles.filter((r) => !(r in hierarchy));
+
+  if (hierarchyRequired.length === 0 && nonHierarchyRequired.length === 0) return true;
+
+  // OR semantics: any category match is sufficient
+
+  // Hierarchy roles: level comparison (higher includes lower)
+  if (hierarchyRequired.length > 0) {
+    const minRequired = Math.min(...hierarchyRequired.map((r) => hierarchy[r]));
+    if (availableRoles.some((r) => r in hierarchy && hierarchy[r] >= minRequired)) return true;
+  }
+
+  // Non-hierarchy roles: exact match
+  if (nonHierarchyRequired.length > 0) {
+    if (nonHierarchyRequired.some((r) => availableRoles.includes(r))) return true;
+  }
+
+  return false;
+}

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

@@ -0,0 +1,102 @@
+import { CanActivate, DynamicModule, Global, Module, Type } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+import { MongooseModule, SchemaFactory, getModelToken } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+import { CoreTenantMemberModel } from './core-tenant-member.model';
+import { TENANT_MEMBER_MODEL_TOKEN } from './core-tenant.enums';
+import { CoreTenantGuard } from './core-tenant.guard';
+import { CoreTenantService } from './core-tenant.service';
+
+/**
+ * Options for CoreTenantModule.forRoot().
+ *
+ * Projects using auto-registration via `multiTenancy: {}` get default implementations.
+ * For custom model/guard/service, use `CoreTenantModule.forRoot({ ... })` directly
+ * in your ServerModule instead of auto-registration.
+ */
+export interface CoreTenantModuleOptions {
+  /** Custom TenantMember model class (must extend CoreTenantMemberModel) */
+  memberModel?: Type<CoreTenantMemberModel>;
+  /** Custom guard class (must implement CanActivate) */
+  guard?: Type<CanActivate>;
+  /** Custom service class (must extend CoreTenantService) */
+  service?: Type<CoreTenantService>;
+  /**
+   * Mongoose model name for the membership collection.
+   * Defaults to 'TenantMember'. When changed, an alias is created so that
+   * @InjectModel('TenantMember') continues to work in guard and service.
+   * @default 'TenantMember'
+   */
+  modelName?: string;
+}
+
+/**
+ * Core tenant module for multi-tenancy support.
+ *
+ * Provides:
+ * - TenantMember model (user <-> tenant membership with roles)
+ * - CoreTenantGuard (APP_GUARD for X-Tenant-Id header validation)
+ * - CoreTenantService (membership CRUD operations)
+ *
+ * Projects can extend via the Module Inheritance Pattern by passing custom
+ * model, guard, or service classes to forRoot().
+ *
+ * @example
+ * ```typescript
+ * // Auto-registration via CoreModule config
+ * CoreModule.forRoot({ multiTenancy: {} })
+ *
+ * // Manual registration with custom service
+ * CoreTenantModule.forRoot({ service: CustomTenantService })
+ *
+ * // Custom model name (config.multiTenancy.membershipModel)
+ * CoreTenantModule.forRoot({ modelName: 'OrgMember' })
+ * ```
+ */
+@Global()
+@Module({})
+export class CoreTenantModule {
+  static forRoot(options: CoreTenantModuleOptions = {}): DynamicModule {
+    const MemberModel = options.memberModel || CoreTenantMemberModel;
+    const Guard = options.guard || CoreTenantGuard;
+    const Service = options.service || CoreTenantService;
+    const modelName = options.modelName || TENANT_MEMBER_MODEL_TOKEN;
+
+    const memberSchema = SchemaFactory.createForClass(MemberModel);
+
+    // Compound unique index: one membership per user per tenant
+    memberSchema.index({ user: 1, tenant: 1 }, { unique: true });
+    // Compound index for per-request membership lookups (index-covered query)
+    memberSchema.index({ user: 1, tenant: 1, status: 1 });
+
+    const providers: any[] = [
+      {
+        provide: CoreTenantService,
+        useClass: Service,
+      },
+      {
+        provide: APP_GUARD,
+        useClass: Guard,
+      },
+    ];
+
+    // When a custom model name is used, alias the default injection token to the custom model.
+    // This allows @InjectModel(TENANT_MEMBER_MODEL_TOKEN) in guard/service to continue working.
+    if (modelName !== TENANT_MEMBER_MODEL_TOKEN) {
+      providers.push({
+        provide: getModelToken(TENANT_MEMBER_MODEL_TOKEN),
+        useFactory: (model: Model<any>) => model,
+        inject: [getModelToken(modelName)],
+      });
+    }
+
+    return {
+      exports: [CoreTenantService],
+      global: true,
+      imports: [MongooseModule.forFeature([{ name: modelName, schema: memberSchema }])],
+      module: CoreTenantModule,
+      providers,
+    };
+  }
+}

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

@@ -0,0 +1,235 @@
+import { BadRequestException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+
+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';
+
+/**
+ * Core service for tenant membership operations.
+ *
+ * Projects should extend this service via the Module Inheritance Pattern
+ * to add custom logic (e.g., tenant creation, invitation flows).
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class TenantService extends CoreTenantService {
+ *   override async addMember(tenantId: string, userId: string, role?: string) {
+ *     const member = await super.addMember(tenantId, userId, role);
+ *     // Custom: send notification email
+ *     await this.notificationService.sendInvite(userId, tenantId);
+ *     return member;
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class CoreTenantService {
+  protected readonly logger = new Logger(CoreTenantService.name);
+
+  constructor(@InjectModel(TENANT_MEMBER_MODEL_TOKEN) protected readonly memberModel: Model<CoreTenantMemberModel>) {}
+
+  /**
+   * Get the configured role hierarchy.
+   */
+  protected getHierarchy(): Record<string, number> {
+    return ConfigService.configFastButReadOnly?.multiTenancy?.roleHierarchy ?? DEFAULT_ROLE_HIERARCHY;
+  }
+
+  /**
+   * Get the default (lowest) role name from the hierarchy.
+   */
+  protected getDefaultRole(): string {
+    const hierarchy = this.getHierarchy();
+    const entries = Object.entries(hierarchy);
+    if (entries.length === 0) return 'member';
+    return entries.reduce((a, b) => (a[1] <= b[1] ? a : b))[0];
+  }
+
+  /**
+   * Get the highest role name from the hierarchy.
+   */
+  protected getHighestRole(): string {
+    const hierarchy = this.getHierarchy();
+    const entries = Object.entries(hierarchy);
+    if (entries.length === 0) return 'owner';
+    return entries.reduce((a, b) => (a[1] >= b[1] ? a : b))[0];
+  }
+
+  /**
+   * Find all active tenant memberships for a user.
+   */
+  async findMemberships(userId: string): Promise<CoreTenantMemberModel[]> {
+    return this.memberModel.find({ status: TenantMemberStatus.ACTIVE, user: userId }).lean().exec() as Promise<
+      CoreTenantMemberModel[]
+    >;
+  }
+
+  /**
+   * Get a single membership (any status).
+   */
+  async getMembership(tenantId: string, userId: string): Promise<CoreTenantMemberModel | null> {
+    return this.memberModel
+      .findOne({ tenant: tenantId, user: userId })
+      .lean()
+      .exec() as Promise<CoreTenantMemberModel | null>;
+  }
+
+  /**
+   * Add a member to a tenant.
+   * Uses bypassTenantGuard to avoid tenant filtering on the membership collection itself.
+   *
+   * @param role - Role name from the configured hierarchy. Defaults to the lowest role.
+   */
+  async addMember(
+    tenantId: string,
+    userId: string,
+    role?: string,
+    invitedById?: string,
+  ): Promise<CoreTenantMemberModel> {
+    if (!tenantId?.trim()) {
+      throw new BadRequestException('tenantId must not be empty');
+    }
+    if (!userId?.trim()) {
+      throw new BadRequestException('userId must not be empty');
+    }
+    const effectiveRole = role ?? this.getDefaultRole();
+
+    // Check for existing membership
+    const existing = await this.getMembership(tenantId, userId);
+    if (existing) {
+      if (existing.status === TenantMemberStatus.ACTIVE) {
+        throw new BadRequestException('User is already an active member of this tenant');
+      }
+      // Reactivate suspended/invited membership
+      return RequestContext.runWithBypassTenantGuard(async () => {
+        return this.memberModel
+          .findOneAndUpdate(
+            { tenant: tenantId, user: userId },
+            {
+              invitedBy: invitedById,
+              joinedAt: new Date(),
+              role: effectiveRole,
+              status: TenantMemberStatus.ACTIVE,
+            },
+            { new: true },
+          )
+          .lean()
+          .exec() as Promise<CoreTenantMemberModel>;
+      });
+    }
+
+    return RequestContext.runWithBypassTenantGuard(async () => {
+      const doc = await this.memberModel.create({
+        invitedBy: invitedById,
+        joinedAt: new Date(),
+        role: effectiveRole,
+        status: TenantMemberStatus.ACTIVE,
+        tenant: tenantId,
+        user: userId,
+      });
+      return doc.toObject() as CoreTenantMemberModel;
+    });
+  }
+
+  /**
+   * Remove a member from a tenant (sets status to SUSPENDED).
+   * Prevents removing the last owner (highest role).
+   */
+  async removeMember(tenantId: string, userId: string): Promise<CoreTenantMemberModel> {
+    if (!tenantId?.trim()) {
+      throw new BadRequestException('tenantId must not be empty');
+    }
+    if (!userId?.trim()) {
+      throw new BadRequestException('userId must not be empty');
+    }
+    await this.assertNotLastOwner(tenantId, userId);
+
+    return RequestContext.runWithBypassTenantGuard(async () => {
+      const result = await this.memberModel
+        .findOneAndUpdate(
+          { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId },
+          { status: TenantMemberStatus.SUSPENDED },
+          { new: true },
+        )
+        .lean()
+        .exec();
+
+      if (!result) {
+        throw new NotFoundException('Membership not found');
+      }
+
+      return result as CoreTenantMemberModel;
+    });
+  }
+
+  /**
+   * Update a member's role within a tenant.
+   * Prevents demoting the last owner (highest role).
+   */
+  async updateMemberRole(tenantId: string, userId: string, role: string): Promise<CoreTenantMemberModel> {
+    if (!tenantId?.trim()) {
+      throw new BadRequestException('tenantId must not be empty');
+    }
+    if (!userId?.trim()) {
+      throw new BadRequestException('userId must not be empty');
+    }
+    if (!role?.trim()) {
+      throw new BadRequestException('role must not be empty');
+    }
+    const highestRole = this.getHighestRole();
+
+    // If demoting from highest role, ensure it's not the last one
+    const existing = await this.getMembership(tenantId, userId);
+    if (existing?.role === highestRole && role !== highestRole) {
+      await this.assertNotLastOwner(tenantId, userId);
+    }
+
+    return RequestContext.runWithBypassTenantGuard(async () => {
+      const result = await this.memberModel
+        .findOneAndUpdate(
+          { status: TenantMemberStatus.ACTIVE, tenant: tenantId, user: userId },
+          { role },
+          { new: true },
+        )
+        .lean()
+        .exec();
+
+      if (!result) {
+        throw new NotFoundException('Active membership not found');
+      }
+
+      return result as CoreTenantMemberModel;
+    });
+  }
+
+  /**
+   * Ensure the given user is not the last owner (highest role) of the tenant.
+   * Throws BadRequestException if removing/demoting them would leave the tenant without an owner.
+   *
+   * Note: This uses a read-check-act pattern which has a theoretical TOCTOU race under
+   * concurrent requests. For production environments with high concurrency, consider using
+   * MongoDB transactions (requires replica set) in your extended service.
+   */
+  async assertNotLastOwner(tenantId: string, userId: string): Promise<void> {
+    const highestRole = this.getHighestRole();
+
+    return RequestContext.runWithBypassTenantGuard(async () => {
+      const ownerCount = await this.memberModel.countDocuments({
+        role: highestRole,
+        status: TenantMemberStatus.ACTIVE,
+        tenant: tenantId,
+      });
+
+      if (ownerCount <= 1) {
+        const membership = await this.getMembership(tenantId, userId);
+        if (membership?.role === highestRole) {
+          throw new BadRequestException('Cannot remove or demote the last owner of a tenant');
+        }
+      }
+    });
+  }
+}