@lenne.tech/nest-server 11.34.1 → 11.35.1

package/src/core/modules/tenant/core-role-scope.registry.ts

@@ -0,0 +1,195 @@
+import { GLOBAL_ONLY_ROLES, isSystemRole, looksLikeSystemRole } from '../../common/enums/role.enum';
+import { ConfigService } from '../../common/services/config.service';
+import { DEFAULT_ROLE_HIERARCHY } from './core-tenant.enums';
+
+/**
+ * Where a role's authority comes from — and therefore which source may answer it.
+ *
+ * This is the tenant boundary expressed as data. Roles are plain strings at runtime
+ * (`RoleEnum.ADMIN` IS `'admin'`), and they arrive from three trust levels: the framework, the
+ * project, and the CUSTOMER (membership roles are free text). Comparing them with `===` in one
+ * shared namespace is what allowed a tenant owner to grant themselves platform authority by naming
+ * their tenant role `'admin'`.
+ *
+ * Encoding the scope as an ATTRIBUTE rather than in the name is deliberate, and it is what makes
+ * this forward-compatible with admin-managed roles stored in the database: a future
+ * `DbRoleScopeSource` can feed the same registry, and every caller keeps working unchanged. A
+ * naming convention (e.g. storing tenant roles as `t:owner`) would instead put the scope inside a
+ * string that whoever creates the role can mistype, and would add a normalization step to every
+ * comparison — inside the authorization path, which is the last place that should grow moving parts.
+ */
+export enum RoleScope {
+  /** Authority granted by the PLATFORM. Resolved against `user.roles`, never a membership role. */
+  GLOBAL = 'global',
+
+  /** A runtime-context check (`s_*`), never a stored role and never a string comparison. */
+  SYSTEM = 'system',
+
+  /** Authority granted WITHIN one tenant. Resolved against `membership.role` in tenant context. */
+  TENANT = 'tenant',
+
+  /** Declared nowhere. Grants nothing — see {@link CoreRoleScopeRegistry.scopeOf}. */
+  UNKNOWN = 'unknown',
+}
+
+/**
+ * A source of role→scope knowledge.
+ *
+ * Implemented today by the config reader below. The interface exists so an admin-managed,
+ * database-backed source can be added later without touching the guards: register it, and every
+ * `scopeOf()` caller picks it up.
+ */
+export interface RoleScopeSource {
+  /** All roles this source declares as globally scoped. */
+  globalRoles(): Iterable<string>;
+
+  /** All roles this source declares as tenant scoped. */
+  tenantRoles(): Iterable<string>;
+}
+
+/**
+ * Resolves the scope of a role, from one or more sources.
+ *
+ * **Deny by default.** A role no source declares resolves to {@link RoleScope.UNKNOWN}, and callers
+ * must treat that as "grants nothing". That is the property worth having: an undeclared membership
+ * role cannot accidentally line up with an undeclared required role and authorize something. The
+ * previous behaviour — exact string match against whatever happened to be stored — is precisely the
+ * hole this replaces.
+ *
+ * The registry is a plain object rather than a Nest provider on purpose: `checkRestricted()` runs
+ * far outside DI (it is called from decorators and helpers), and giving it an injected dependency
+ * would put a container lookup in the field-level authorization path.
+ */
+export class CoreRoleScopeRegistry {
+  private readonly sources: RoleScopeSource[] = [];
+
+  /** Drop all registered sources. Used by tests and by config reloads. */
+  clear(): void {
+    this.sources.length = 0;
+  }
+
+  /**
+   * Roles that are declared in BOTH scopes — a contradiction that must fail the boot.
+   *
+   * Such a role would have to be resolved against `user.roles` and `membership.role` at the same
+   * time. Whichever way it were decided, one of the two declarations would silently not hold.
+   */
+  conflicts(): string[] {
+    const global = this.collect((source) => source.globalRoles());
+    const tenant = this.collect((source) => source.tenantRoles());
+    return [...global].filter((role) => tenant.has(role)).sort();
+  }
+
+  /** Is this role declared as tenant-scoped by any source? */
+  isTenantRole(role: string): boolean {
+    return this.scopeOf(role) === RoleScope.TENANT;
+  }
+
+  /** Register a source. Later sources add to, never replace, earlier ones. */
+  register(source: RoleScopeSource): void {
+    this.sources.push(source);
+  }
+
+  /**
+   * Scope of a single role.
+   *
+   * Order matters: system roles first (they are never stored and never string-compared), then
+   * global (so a project cannot demote a framework role by declaring it per tenant), then tenant.
+   */
+  scopeOf(role: string): RoleScope {
+    if (typeof role !== 'string') {
+      return RoleScope.UNKNOWN;
+    }
+    if (isSystemRole(role) || looksLikeSystemRole(role)) {
+      return RoleScope.SYSTEM;
+    }
+    if (GLOBAL_ONLY_ROLES.includes(role) || this.collect((source) => source.globalRoles()).has(role)) {
+      return RoleScope.GLOBAL;
+    }
+    if (this.collect((source) => source.tenantRoles()).has(role)) {
+      return RoleScope.TENANT;
+    }
+    return RoleScope.UNKNOWN;
+  }
+
+  /**
+   * Is any source able to answer tenant-scope questions at all?
+   *
+   * Lets callers distinguish "declared as NOT a tenant role" from "nothing is declared yet", which
+   * are very different answers when deciding whether to deny.
+   */
+  hasTenantKnowledge(): boolean {
+    return this.collect((source) => source.tenantRoles()).size > 0;
+  }
+
+  /**
+   * Split required roles by the source entitled to answer them.
+   *
+   * `unknown` is returned separately rather than folded into either half, so callers can decide
+   * explicitly. The guards treat it as "grants nothing via tenant membership" but still resolve it
+   * against `user.roles` — that keeps a project which never configured `multiTenancy` working
+   * exactly as before, while ensuring a membership role can never be the thing that satisfies it.
+   */
+  split(requiredRoles: string[]): { global: string[]; system: string[]; tenant: string[]; unknown: string[] } {
+    const result = { global: [] as string[], system: [] as string[], tenant: [] as string[], unknown: [] as string[] };
+    for (const role of requiredRoles ?? []) {
+      switch (this.scopeOf(role)) {
+        case RoleScope.GLOBAL:
+          result.global.push(role);
+          break;
+        case RoleScope.SYSTEM:
+          result.system.push(role);
+          break;
+        case RoleScope.TENANT:
+          result.tenant.push(role);
+          break;
+        default:
+          result.unknown.push(role);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * The `multiTenancy` config, read fresh on every lookup and ALWAYS consulted.
+   *
+   * Built in rather than registered, because a registered source only exists after
+   * `CoreTenantModule.forRoot()` has run — and the guards can be constructed before that (test
+   * fixtures, standalone usage). A registry that silently knows nothing is worse than no registry:
+   * `globalOnlyRoles` would be ignored and the roles it protects would fall back to being
+   * tenant-satisfiable, which is precisely the escalation this exists to prevent.
+   */
+  private configSource(): RoleScopeSource {
+    return {
+      globalRoles: () => ConfigService.configFastButReadOnly?.multiTenancy?.globalOnlyRoles ?? [],
+      tenantRoles: () => {
+        const config = ConfigService.configFastButReadOnly?.multiTenancy;
+        return [
+          ...Object.keys(config?.roleHierarchy ?? DEFAULT_ROLE_HIERARCHY),
+          ...(config?.additionalMembershipRoles ?? []),
+        ];
+      },
+    };
+  }
+
+  private collect(pick: (source: RoleScopeSource) => Iterable<string>): Set<string> {
+    const collected = new Set<string>();
+    for (const source of [this.configSource(), ...this.sources]) {
+      for (const role of pick(source) ?? []) {
+        if (typeof role === 'string' && role.length) {
+          collected.add(role);
+        }
+      }
+    }
+    return collected;
+  }
+}
+
+/**
+ * The process-wide registry.
+ *
+ * Module-level singleton in an import-free-ish leaf for the same reason the DI tokens live in
+ * leaves: it is read from `checkRestricted()`, which sits on the field-level authorization path and
+ * must not depend on the Nest container being available.
+ */
+export const roleScopeRegistry = new CoreRoleScopeRegistry();

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

@@ -10,12 +10,14 @@ import {
   UnauthorizedException,
 } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
-import { GqlContextType, GqlExecutionContext } from '@nestjs/graphql';
+import { GqlExecutionContext } from '@nestjs/graphql';
 import { InjectModel } from '@nestjs/mongoose';
 import { Model } from 'mongoose';
 
 import { RoleEnum } from '../../common/enums/role.enum';
+import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper';
 import { ConfigService } from '../../common/services/config.service';
+import { ResolvedTenantContext, setTenantContextResolver } from '../../common/services/core-tenant-context.registry';
 import { CoreRedisService } from '../../common/services/core-redis.service';
 import { ErrorCode } from '../error-code/error-codes';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
@@ -27,6 +29,8 @@ import {
   getRoleHierarchy,
   isSystemRole,
   mergeRolesMetadata,
+  resolveGlobalAndTenantRoles,
+  tenantSatisfiableRoles,
 } from './core-tenant.helpers';
 
 /**
@@ -155,6 +159,67 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     if (this.cleanupInterval.unref) {
       this.cleanupInterval.unref();
     }
+
+    // Make the membership logic reachable from transports that have no Express request — today the
+    // GraphQL WebSocket. See core-tenant-context.registry.ts for why this is a registry and not DI.
+    setTenantContextResolver({
+      resolve: (user, headerTenantId) => this.resolveTenantContext(user, headerTenantId),
+    });
+  }
+
+  /**
+   * Answer "which tenant is this caller in?" WITHOUT an Express request.
+   *
+   * The HTTP path answers this inside `canActivate()` and writes the result onto the request, which
+   * `RequestContextMiddleware` then publishes through AsyncLocalStorage. A WebSocket has neither, so
+   * this is the same decision reachable from a transport that only has a user and a header value.
+   *
+   * It deliberately does NOT decide ACCESS — that is `canActivate()`'s job, driven by `@Roles()`
+   * metadata this method cannot see. It only establishes the tenant SCOPE the Mongoose plugin
+   * filters by, so a read from such a transport is narrowed instead of running unscoped.
+   *
+   * A header naming a tenant the user is not an active member of yields NO tenant id rather than the
+   * requested one: the plugin then finds no tenant scope and its safety net refuses the read. An
+   * unvalidated header would be strictly worse than no header at all.
+   */
+  async resolveTenantContext(
+    user: { id: string; roles?: string[] } | undefined,
+    headerTenantId?: string,
+  ): Promise<ResolvedTenantContext> {
+    const config = ConfigService.configFastButReadOnly?.multiTenancy;
+    if (!config || config.enabled === false) {
+      return {};
+    }
+
+    const trimmed =
+      headerTenantId && typeof headerTenantId === 'string' && headerTenantId.length <= 128
+        ? headerTenantId.trim()
+        : undefined;
+
+    const adminBypass = config.adminBypass !== false;
+    if (adminBypass && user?.roles?.includes(RoleEnum.ADMIN)) {
+      // Mirrors canActivate(): with a header an admin is scoped to that tenant, without one they see
+      // everything. No membership is required either way.
+      return trimmed ? { isAdminBypass: true, tenantId: trimmed } : { isAdminBypass: true };
+    }
+
+    if (!user?.id) {
+      return {};
+    }
+
+    if (trimmed) {
+      const membership = await this.findMembershipCached(user.id, trimmed);
+      if (!membership) {
+        return {};
+      }
+      return { tenantId: trimmed, tenantRole: membership.role as string };
+    }
+
+    // No header: scope to every tenant the user is an active member of — the same fallback the HTTP
+    // path uses, so the plugin filters by `{ tenantId: { $in: tenantIds } }`.
+    const carrier: { tenantIds?: string[]; user: { id: string } } = { user: { id: user.id } };
+    await this.resolveUserTenantIds(carrier);
+    return { tenantIds: carrier.tenantIds ?? [] };
   }
 
   /**
@@ -425,9 +490,28 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
 
       const memberRole = membership.role as string;
 
-      // Check role access if roles are required (hierarchy + normal, against membership.role)
+      // Check role access if roles are required (hierarchy + normal, against membership.role).
+      //
+      // Global-only roles (RoleEnum.ADMIN) are resolved against user.roles instead — a membership
+      // role is customer-assigned free text, so comparing it against the framework's global admin
+      // role by string equality would let any tenant owner mint platform-wide access by naming
+      // their tenant role 'admin'. The two authority levels stay separate:
+      //   global admin → RoleEnum.ADMIN in user.roles (every tenant)
+      //   tenant admin → a membership role such as 'tenantAdmin' (this tenant only)
+      //
+      // OR semantics across both halves, so @Roles(ADMIN, 'owner') keeps reading as alternatives.
       if (checkableRoles.length > 0) {
-        if (!checkRoleAccess(checkableRoles, undefined, memberRole)) {
+        const { global: globalRoles } = resolveGlobalAndTenantRoles(checkableRoles);
+        // Deny by default: only roles DECLARED as tenant-scoped may be satisfied by a membership.
+        // An undeclared role is not silently matched against customer-assigned free text.
+        const tenantRoles = tenantSatisfiableRoles(checkableRoles);
+        const satisfiedGlobally = globalRoles.some((r) => user.roles?.includes(r));
+        // The length guard is NOT redundant here (unlike the `.some()` above): checkRoleAccess
+        // returns TRUE for an empty required-roles list, so calling it with no tenant roles would
+        // grant access to a handler that only ever required a global role.
+        const satisfiedByTenant = tenantRoles.length > 0 && checkRoleAccess(tenantRoles, undefined, memberRole);
+
+        if (!satisfiedGlobally && !satisfiedByTenant) {
           throw new ForbiddenException('Insufficient tenant role');
         }
       }
@@ -538,15 +622,11 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
    * 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;
-    }
+    // Shared with both role guards — see execution-context-request.helper for why the GraphQL
+    // WEBSOCKET branch is load-bearing: without it this method answered `null` for every
+    // subscription, `canActivate()` hit `if (!request) return true`, and because the role guard
+    // delegates non-system roles here, `@Roles()` on a subscription was enforced by nobody.
+    return resolveGuardRequest(context, (ctx) => GqlExecutionContext.create(ctx).getContext()) ?? null;
   }
 
   // ===================================================================================================================

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

@@ -1,8 +1,8 @@
+import { isForbiddenMembershipRole, isGlobalOnlyRole, looksLikeSystemRole } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
+import { RoleScope, roleScopeRegistry, RoleScopeSource } from './core-role-scope.registry';
 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.
@@ -23,13 +23,145 @@ export function getRoleHierarchy(): Record<string, number> {
   return ConfigService.configFastButReadOnly?.multiTenancy?.roleHierarchy ?? DEFAULT_ROLE_HIERARCHY;
 }
 
+// `isSystemRole` used to be defined here. It now lives in `common/enums/role.enum.ts`, next to the
+// RoleEnum members it describes, so the storage guards and the runtime guards share ONE predicate
+// instead of drifting apart (they already disagreed on case). Re-exported below for compatibility.
+export {
+  GLOBAL_ONLY_ROLES,
+  isForbiddenMembershipRole,
+  isGlobalOnlyRole,
+  isSystemRole,
+  looksLikeGlobalOnlyRole,
+  looksLikeSystemRole,
+  SYSTEM_ROLE_PREFIX,
+} from '../../common/enums/role.enum';
+
+/**
+ * Feeds the role-scope registry from `multiTenancy` config.
+ *
+ * Reads the config lazily on every call rather than caching, so a `ConfigService.setConfig()` in a
+ * test (or a future runtime reload) is picked up without re-registering the source.
+ */
+export const configRoleScopeSource: RoleScopeSource = {
+  globalRoles: () => ConfigService.configFastButReadOnly?.multiTenancy?.globalOnlyRoles ?? [],
+  tenantRoles: () => {
+    const config = ConfigService.configFastButReadOnly?.multiTenancy;
+    return [
+      ...Object.keys(config?.roleHierarchy ?? DEFAULT_ROLE_HIERARCHY),
+      ...(config?.additionalMembershipRoles ?? []),
+    ];
+  },
+};
+
+/**
+ * Validate the configured role vocabulary. Throws when it cannot be enforced coherently.
+ *
+ * Called at boot (`CoreTenantModule`). Failing the boot is the right severity: every condition here
+ * describes a configuration whose access decisions would be ambiguous or silently wrong, and an
+ * ambiguous authorization rule is worse than a server that refuses to start.
+ */
+export function assertRoleVocabularyIsCoherent(): void {
+  const config = ConfigService.configFastButReadOnly?.multiTenancy;
+  if (!config || config.enabled === false) {
+    return;
+  }
+
+  const hierarchy = Object.keys(config.roleHierarchy ?? DEFAULT_ROLE_HIERARCHY);
+  const additional = config.additionalMembershipRoles ?? [];
+  const declaredGlobal = config.globalOnlyRoles ?? [];
+
+  // 1. A tenant role must never be named after a framework role.
+  const reserved = [...hierarchy, ...additional].filter((role) => isForbiddenMembershipRole(role));
+  if (reserved.length) {
+    throw new Error(
+      `multiTenancy: tenant role(s) [${reserved.join(', ')}] use a reserved framework role name. ` +
+        'A tenant role of that name would be compared against the framework role by exact string match, ' +
+        'letting a tenant owner grant themselves platform authority. Rename them (e.g. "tenantAdmin") ' +
+        'and declare platform-wide roles via multiTenancy.globalOnlyRoles.',
+    );
+  }
+
+  // 2. A role cannot be global and tenant-scoped at once — it would need two sources of truth.
+  const both = declaredGlobal.filter((role) => hierarchy.includes(role) || additional.includes(role));
+  if (both.length) {
+    throw new Error(
+      `multiTenancy: role(s) [${both.join(', ')}] are declared BOTH in globalOnlyRoles and as tenant roles. ` +
+        'Each role must resolve against exactly one source (user.roles for global, membership.role for tenant).',
+    );
+  }
+
+  // 3. A declared global role must not be a system role either.
+  const systemGlobals = declaredGlobal.filter((role) => looksLikeSystemRole(role));
+  if (systemGlobals.length) {
+    throw new Error(
+      `multiTenancy.globalOnlyRoles contains system role(s) [${systemGlobals.join(', ')}]. ` +
+        'System roles are runtime-context checks and are never stored or granted.',
+    );
+  }
+}
+
 /**
- * Check if a role is a system role (S_USER, S_EVERYONE, etc.).
- * System roles are checked by RolesGuard/BetterAuthRolesGuard for authentication
- * and by CoreTenantGuard as OR alternatives before real role checks.
+ * Split required roles into the ones only the PLATFORM can satisfy and the ones a TENANT can.
+ *
+ * This split is the tenant boundary. Membership roles are customer-assigned free text, and in
+ * tenant context they are compared against required roles by exact string match — so without the
+ * split, a member whose tenant role is literally `'admin'` satisfies `@Roles(RoleEnum.ADMIN)`, the
+ * global platform role. Anyone allowed to manage members (a tenant owner, i.e. a customer) could
+ * mint platform-wide access for themselves.
+ *
+ * Callers must resolve each half against its own source:
+ * - `global` → `user.roles` (never the membership role)
+ * - `tenant` → `membership.role` in tenant context, `user.roles` otherwise
+ *
+ * OR semantics across the two halves: satisfying either is enough, which keeps
+ * `@Roles(ADMIN, 'owner')` working as the alternative it reads as.
  */
-export function isSystemRole(role: string): boolean {
-  return role.startsWith(SYSTEM_ROLE_PREFIX);
+export function resolveGlobalAndTenantRoles(requiredRoles: string[]): { global: string[]; tenant: string[] } {
+  const global: string[] = [];
+  const tenant: string[] = [];
+  for (const role of requiredRoles ?? []) {
+    // The registry knows framework roles, project-declared global roles and configured tenant
+    // roles. `isGlobalOnlyRole` is kept as the floor so RoleEnum.ADMIN is global even before any
+    // source is registered (e.g. a unit test constructing the helper in isolation).
+    const scope = roleScopeRegistry.scopeOf(role);
+    (scope === RoleScope.GLOBAL || isGlobalOnlyRole(role) ? global : tenant).push(role);
+  }
+  return { global, tenant };
+}
+
+/**
+ * Which required roles may a TENANT MEMBERSHIP satisfy?
+ *
+ * Two tiers, and the distinction is the whole design:
+ *
+ * 1. **Unconditional** — roles with GLOBAL scope are never satisfiable by a membership. This is the
+ *    security fix: a customer-assigned role must not answer for the platform. Always on.
+ * 2. **Opt-in** (`multiTenancy.strictMembershipRoles`) — narrow further to roles the project
+ *    DECLARED as tenant-scoped, so an undeclared name cannot line up with a membership by
+ *    coincidence.
+ *
+ * Tier 2 is not the default on purpose. A project may legitimately use exact-match roles that
+ * appear only in `@Roles()` and in its membership data and never in `roleHierarchy`; denying those
+ * at the guard by default would be a silent, fleet-wide lockout — a worse failure than the case it
+ * guards against, which tier 1 already covers as soon as the role is declared global.
+ */
+export function tenantSatisfiableRoles(requiredRoles: string[]): string[] {
+  // Always excluded: roles whose authority is global. That is the security fix, and it is
+  // unconditional — a customer-assigned membership role must never answer for the platform.
+  const candidates = resolveGlobalAndTenantRoles(requiredRoles).tenant;
+
+  // Beyond that, opt-in. `strictMembershipRoles` narrows matching to roles the project actually
+  // DECLARED, so an undeclared name cannot line up with a membership by coincidence.
+  //
+  // It is deliberately NOT the default: a project may legitimately use exact-match roles that
+  // appear only in @Roles() and in its membership data, never in roleHierarchy. Denying those by
+  // default would break such setups at the guard — a silent, fleet-wide lockout — for a case the
+  // global/tenant split already covers as soon as the role is declared global.
+  if (!ConfigService.configFastButReadOnly?.multiTenancy?.strictMembershipRoles) {
+    return candidates;
+  }
+
+  return candidates.filter((role) => roleScopeRegistry.isTenantRole(role));
 }
 
 /**

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

@@ -3,8 +3,10 @@ import { APP_GUARD } from '@nestjs/core';
 import { MongooseModule, SchemaFactory, getModelToken } from '@nestjs/mongoose';
 import { Model } from 'mongoose';
 
+import { roleScopeRegistry } from './core-role-scope.registry';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
 import { TENANT_MEMBER_MODEL_TOKEN } from './core-tenant.enums';
+import { assertRoleVocabularyIsCoherent, configRoleScopeSource } from './core-tenant.helpers';
 import { CoreTenantGuard } from './core-tenant.guard';
 import { CoreTenantService } from './core-tenant.service';
 
@@ -58,6 +60,16 @@ export interface CoreTenantModuleOptions {
 @Module({})
 export class CoreTenantModule {
   static forRoot(options: CoreTenantModuleOptions = {}): DynamicModule {
+    // Teach the role-scope registry which roles are global and which are tenant-scoped, then
+    // refuse to boot on a vocabulary that cannot be enforced coherently (a tenant role named after
+    // a framework role, or one role declared in both scopes). An ambiguous authorization rule is
+    // worse than a server that does not start, so this throws rather than warns.
+    //
+    // Registration is idempotent: forRoot() may run more than once across test module fixtures.
+    roleScopeRegistry.clear();
+    roleScopeRegistry.register(configRoleScopeSource);
+    assertRoleVocabularyIsCoherent();
+
     const MemberModel = options.memberModel || CoreTenantMemberModel;
     const Guard = options.guard || CoreTenantGuard;
     const Service = options.service || CoreTenantService;

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

@@ -2,6 +2,7 @@ import { BadRequestException, Injectable, Logger, NotFoundException, Optional }
 import { InjectModel } from '@nestjs/mongoose';
 import { Model } from 'mongoose';
 
+import { looksLikeGlobalOnlyRole, looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
 import { RequestContext } from '../../common/services/request-context.service';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
@@ -101,6 +102,7 @@ export class CoreTenantService {
       throw new BadRequestException('userId must not be empty');
     }
     const effectiveRole = role ?? this.getDefaultRole();
+    assertAssignableMembershipRole(effectiveRole);
 
     // Check for existing membership
     const existing = await this.getMembership(tenantId, userId);
@@ -188,6 +190,7 @@ export class CoreTenantService {
     if (!role?.trim()) {
       throw new BadRequestException('role must not be empty');
     }
+    assertAssignableMembershipRole(role);
     const highestRole = this.getHighestRole();
 
     // If demoting from highest role, ensure it's not the last one
@@ -242,3 +245,56 @@ export class CoreTenantService {
     });
   }
 }
+
+/**
+ * Refuse a membership role that would cross the tenant boundary.
+ *
+ * Membership roles are customer-assigned free text, and whoever may manage members is typically a
+ * tenant owner — a customer. Two families of name must never become one:
+ *
+ * - **system roles** (`s_*`) are runtime-context questions ("is this the owner of the record?"),
+ *   not stored roles. A membership named `s_self` used to satisfy `@Restricted(S_SELF)` on
+ *   arbitrary records.
+ * - **global-only roles** (`RoleEnum.ADMIN`) are platform authority. A membership named `admin`
+ *   used to satisfy `@Roles(RoleEnum.ADMIN)` — the global role — inside tenant context.
+ *
+ * This is the SECOND layer, not the protection itself. The guards resolve each required role
+ * against its own source (`user.roles` vs `membership.role`), so an already-stored dangerous name
+ * is inert even without this check — which matters, because a future `RoleEnum` addition would
+ * otherwise turn every pre-existing membership of that name into a hole retroactively. This check
+ * only stops new ones from being created, and gives a clear error instead of silent inertness.
+ */
+export function assertAssignableMembershipRole(role: string): void {
+  if (looksLikeSystemRole(role)) {
+    throw new BadRequestException(
+      `A system role (${SYSTEM_ROLE_PREFIX}*) must never be used as a tenant membership role: ${role}`,
+    );
+  }
+  if (looksLikeGlobalOnlyRole(role)) {
+    throw new BadRequestException(
+      `"${role}" is a global role and must never be used as a tenant membership role — ` +
+        'use a tenant-specific name such as "tenantAdmin" instead',
+    );
+  }
+
+  // Deny by default, when enabled: only roles the project actually declared.
+  //
+  // An undeclared role can never GRANT anything either way — the guards match only declared tenant
+  // roles — so this does not change access decisions. What it changes is WHEN the mistake surfaces:
+  // as a 400 at assignment time, instead of as a membership that silently authorizes nothing while
+  // looking perfectly fine in a members list.
+  const config = ConfigService.configFastButReadOnly?.multiTenancy;
+  if (config?.strictMembershipRoles) {
+    const declared = new Set([
+      ...Object.keys(config.roleHierarchy ?? DEFAULT_ROLE_HIERARCHY),
+      ...(config.additionalMembershipRoles ?? []),
+    ]);
+    if (!declared.has(role)) {
+      throw new BadRequestException(
+        `"${role}" is not a declared tenant role. Declared: [${[...declared].sort().join(', ')}]. ` +
+          'Add it to multiTenancy.roleHierarchy or multiTenancy.additionalMembershipRoles, ' +
+          'or disable multiTenancy.strictMembershipRoles.',
+      );
+    }
+  }
+}

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

@@ -380,13 +380,52 @@ query {
 
 The following metadata is stored with each GridFS file:
 
-| Field              | Source                            |
-| ------------------ | --------------------------------- |
-| `filename`         | From TUS `Upload-Metadata` header |
-| `contentType`      | From TUS `filetype` metadata      |
-| `tusUploadId`      | Original TUS upload ID            |
-| `originalMetadata` | All TUS metadata                  |
-| `uploadedAt`       | Completion timestamp              |
+| Field              | Source                                |
+| ------------------ | ------------------------------------- |
+| `filename`         | From TUS `Upload-Metadata` header     |
+| `contentType`      | From TUS `filetype` metadata          |
+| `tusUploadId`      | Original TUS upload ID                |
+| `originalMetadata` | All TUS metadata                      |
+| `ownerId`          | The authenticated uploader (11.35.0+) |
+| `uploadedAt`       | Completion timestamp                  |
+
+### Upload ownership (11.35.0+)
+
+`tus.roles` decides **who may reach the endpoint**. It says nothing about **which upload** a caller may
+touch — and the protocol is built around a per-upload URL: after `POST /tus` the client holds
+`/tus/<id>` and uses it for `HEAD` (offset), `PATCH` (append bytes) and `DELETE` (terminate). Until
+11.35.0 all three carried only that coarse gate, so any other authenticated caller who learned an id
+could resume, **overwrite** or destroy somebody else's upload. Overwriting is the sharp end: the bytes
+are migrated into the file store under the ORIGINAL uploader's filename.
+
+Two things changed:
+
+- **`onUploadCreate` records the creator** in the upload's own metadata under
+  `TUS_OWNER_METADATA_KEY` (`ltOwnerId`). It **overwrites** any client-supplied value — metadata
+  arrives in the `Upload-Metadata` header, so a merged value would let a caller name somebody else as
+  the owner.
+- **`onIncomingRequest` refuses a request naming an upload the caller does not own**, with **404** — the
+  same "a refusal is indistinguishable from a missing resource" policy the file module uses, so the
+  endpoint is not an existence oracle for upload ids.
+
+The finished file's metadata gains `ownerId`, which is the key
+`CoreFileService.checkRights()` documents — so a tus-uploaded file can finally satisfy a per-file
+ownership rule. Before this it could not: the rule failed closed for everyone but ADMIN, and a project
+following the documented pattern ended up with files nobody could download.
+
+**An owner-LESS upload stays reachable by anyone who may reach the endpoint.** Deliberately: uploads
+created before 11.35.0 carry no owner, and neither does an intentionally public form
+(`tus.roles: [RoleEnum.S_EVERYONE]`). Denying those would break in-flight uploads on upgrade and a
+documented configuration. What is closed is an upload that HAS an owner being touched by somebody else.
+
+Both `readRequestUserId()` and `assertUploadOwnership()` are `protected` — override to read the owner
+from elsewhere (an API key, a signed form token), or to let a support role resume any upload.
+
+> **Note for a custom service:** `@tus/server` v2 does NOT hand the Express request to its hooks. It
+> converts the Node request into a WHATWG `ServerRequest` first, so anything a guard attached lives on
+> the original request, reachable through `runtime.node.req` — which is why `readRequestUserId()` checks
+> there as well. Reading only `req.user` finds nothing and every upload silently becomes owner-less,
+> failing in the permissive direction.
 
 ---