@lenne.tech/nest-server 11.20.0 → 11.21.0

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

@@ -0,0 +1,77 @@
+/**
+ * Injection token for the TenantMember Mongoose model.
+ * Use this constant instead of the string literal 'TenantMember' in @InjectModel() and getModelToken().
+ */
+export const TENANT_MEMBER_MODEL_TOKEN = 'TenantMember';
+
+/**
+ * Membership status for tenant members.
+ */
+export enum TenantMemberStatus {
+  ACTIVE = 'ACTIVE',
+  /** Reserved for future invitation workflow (not yet used in core logic) */
+  INVITED = 'INVITED',
+  SUSPENDED = 'SUSPENDED',
+}
+
+/**
+ * Default role hierarchy for tenant membership.
+ * Keys are role names (stored in membership documents), values are numeric levels.
+ * Higher value = more privileges. Multiple roles can share the same level.
+ *
+ * Can be customized via `multiTenancy.roleHierarchy` in config.
+ *
+ * Hierarchy roles use level comparison: a higher level includes all lower levels.
+ * Non-hierarchy roles (not in this config) use exact match only.
+ *
+ * @example Custom hierarchy:
+ * ```typescript
+ * const roleHierarchy = { viewer: 1, editor: 2, manager: 2, owner: 3 };
+ * const HR = createHierarchyRoles(roleHierarchy);
+ * // HR.VIEWER = 'viewer', HR.EDITOR = 'editor', HR.MANAGER = 'manager', HR.OWNER = 'owner'
+ * ```
+ */
+export const DEFAULT_ROLE_HIERARCHY: Record<string, number> = {
+  member: 1,
+  manager: 2,
+  owner: 3,
+};
+
+/**
+ * Generate typed UPPER_CASE constants from a role hierarchy config.
+ * Provides type-safe role strings for use with @Roles() and @Restricted() decorators.
+ *
+ * @example
+ * ```typescript
+ * const hierarchy = { viewer: 1, editor: 2, manager: 2, owner: 3 };
+ * const HR = createHierarchyRoles(hierarchy);
+ * // HR.VIEWER = 'viewer', HR.EDITOR = 'editor', HR.MANAGER = 'manager', HR.OWNER = 'owner'
+ *
+ * @Roles(HR.EDITOR) // requires at least level 2
+ * ```
+ *
+ * @returns Object with UPPER_CASE keys mapped to the original lowercase role name strings.
+ *          E.g. `{ viewer: 1, owner: 3 }` → `{ VIEWER: 'viewer', OWNER: 'owner' }`.
+ */
+export function createHierarchyRoles<T extends Record<string, number>>(
+  hierarchy: T,
+): { [K in keyof T as Uppercase<string & K>]: string & K } {
+  const result = {} as any;
+  for (const key of Object.keys(hierarchy)) {
+    result[key.toUpperCase()] = key;
+  }
+  return result;
+}
+
+/**
+ * Type-safe constants for the default role hierarchy.
+ * Convenience export for projects using the default { member: 1, manager: 2, owner: 3 } hierarchy.
+ *
+ * @example
+ * ```typescript
+ * @Roles(DefaultHR.MEMBER)   // any active member (level >= 1)
+ * @Roles(DefaultHR.MANAGER)  // at least manager level (level >= 2)
+ * @Roles(DefaultHR.OWNER)    // highest level only (level >= 3)
+ * ```
+ */
+export const DefaultHR = createHierarchyRoles(DEFAULT_ROLE_HIERARCHY);

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,
+    };
+  }
+}