@lenne.tech/nest-server 11.34.0 → 11.35.0

package/src/core/modules/file/file-roles.config.ts

@@ -0,0 +1,202 @@
+/**
+ * File-role CONFIGURATION and the two boot warnings — the half that touches no endpoint class.
+ *
+ * SPLIT OUT OF `file-roles.helper.ts` because that file imports `CoreFileController` and
+ * `CoreFileResolver` (it writes role metadata onto their prototypes), and both of them inject
+ * `CoreFileService`. So a service reading a warning from there closes
+ *
+ *   core-file.service -> file-roles.helper -> core-file.controller -> core-file.service
+ *
+ * and the controller dereferences `CoreFileService` in `design:paramtypes`, i.e. at CLASS-DEFINITION
+ * time. That is the fatal shape: SWC -> CommonJS dies at startup with
+ * `Cannot access 'CoreFileService' before initialization`, while tsc, vitest and oxlint all stay
+ * green. `pnpm run check:swc-tdz` caught exactly that when the warning was first added here.
+ *
+ * This file therefore imports only enums and interfaces. See
+ * `.claude/rules/architecture.md` -> "DI Token Placement (SWC-Safe)".
+ */
+import { Logger } from '@nestjs/common';
+
+import { RoleEnum } from '../../common/enums/role.enum';
+import { IFileConfig, IS3Config } from '../../common/interfaces/server-options.interface';
+
+const logger = new Logger('CoreFileRoles');
+
+/**
+ * Roles applied when `file` is not configured at all.
+ *
+ * Restrictive on purpose: one GridFS bucket is shared by every feature of the
+ * consuming project, and the ObjectIds naming its blobs are not secrets.
+ */
+export type FileRoleKey = 'deleteRoles' | 'downloadRoles' | 'uploadRoles';
+
+export const FILE_ROLE_DEFAULTS: Record<FileRoleKey, string[]> = {
+  deleteRoles: [RoleEnum.ADMIN],
+  downloadRoles: [RoleEnum.ADMIN],
+  uploadRoles: [RoleEnum.ADMIN],
+};
+
+/**
+ * Resolve one knob to the role list that will actually be applied.
+ *
+ * An empty array is treated as "not configured". It cannot mean "nobody": the
+ * guards read an all-empty role set as "no roles required" and return true, so
+ * honouring it literally would OPEN the route instead of closing it — the exact
+ * opposite of what someone writing `[]` intends.
+ */
+export function resolveRoles(key: FileRoleKey, config?: IFileConfig): string[] {
+  const configured = config?.[key];
+
+  if (configured === undefined) {
+    return FILE_ROLE_DEFAULTS[key];
+  }
+
+  if (!Array.isArray(configured) || configured.length === 0 || configured.some((role) => typeof role !== 'string')) {
+    logger.warn(
+      `Ignoring file.${key}: expected a non-empty array of role strings, got ${JSON.stringify(configured)}. ` +
+        `Falling back to ${JSON.stringify(FILE_ROLE_DEFAULTS[key])}.`,
+    );
+    return FILE_ROLE_DEFAULTS[key];
+  }
+
+  return configured;
+}
+
+/**
+ * Warn when presigned S3 downloads are combined with a restricted `downloadRoles`.
+ *
+ * The two settings pull in opposite directions, and the conflict is invisible at the call site:
+ *
+ * - `downloadRoles` says "only these roles may download this file". It is enforced on every request.
+ * - `presignedDownloads` answers `302` with a time-limited S3 URL instead of streaming. That URL is
+ *   a BEARER capability — authorized once, at issue time. Whoever holds it afterwards fetches the
+ *   object with no session, from any IP, until it expires, and **the grant cannot be revoked in
+ *   between**. It survives in browser history, `Referer` headers, proxy logs and chat messages.
+ *
+ * So the second setting hands out exactly what the first one restricts. That is a sound trade for
+ * public assets (which is what presigning is FOR — hence no warning when downloads are
+ * `S_EVERYONE`), and almost never what a project means when it has narrowed the roles.
+ *
+ * A warning rather than a boot failure: unlike an incoherent role vocabulary, this combination has
+ * legitimate uses (short expiry, a CDN in front, files whose audience really is "anyone who once
+ * held the link"). The operator has to be able to choose it — they just should not choose it by
+ * accident.
+ */
+export function warnOnPresignedDownloadsWithRestrictedRoles(
+  s3Config?: IS3Config,
+  fileConfig?: IFileConfig,
+): string | undefined {
+  const presigned = s3Config?.presignedDownloads;
+  const presignedEnabled =
+    presigned === true || (!!presigned && typeof presigned === 'object' && (presigned as any).enabled !== false);
+  if (!presignedEnabled) {
+    return undefined;
+  }
+
+  const downloadRoles = resolveRoles('downloadRoles', fileConfig);
+  // Public downloads are the intended use of presigning — nothing to warn about.
+  if (downloadRoles.includes(RoleEnum.S_EVERYONE)) {
+    return undefined;
+  }
+
+  // Returned as well as logged: the message IS the contract here (an operator has to be able to act
+  // on it), and a module-private Logger instance cannot be asserted against from a unit test.
+  const message =
+    `s3.presignedDownloads is enabled while file.downloadRoles restricts downloads to ` +
+    `${JSON.stringify(downloadRoles)}. A presigned URL is a BEARER capability: it is authorized ` +
+    `once, at issue time, and afterwards anyone holding it can fetch the object with no session, ` +
+    `from any IP, until it expires — the grant cannot be revoked in between, and it survives in ` +
+    `browser history, Referer headers and proxy logs. The role check therefore applies to ` +
+    `obtaining the link, not to reading the file. If these files are sensitive (personal or ` +
+    `medical data), set s3.presignedDownloads: false so the API streams them and re-checks ` +
+    `rights on every request.`;
+
+  logger.warn(message);
+  return message;
+}
+
+/**
+ * Warn when the file gate is open and NOTHING decides the per-file policy.
+ *
+ * THE GAP: the role knobs are a coarse audience filter — they answer "may this caller reach the route
+ * at all". They cannot express "…but only their own", because that sentence needs data. So a deployment
+ * that widened the gate past platform admins and expressed no per-file policy anywhere has a store
+ * every holder of that role can read in full.
+ *
+ * And that is practically reachable, not theoretically: file ids are ENUMERABLE. An ObjectId is 4 bytes
+ * of timestamp + 5 bytes of randomness generated once PER PROCESS + a 3-byte incrementing counter, so a
+ * caller who obtains one valid id — their own upload — knows the random part and a counter reference
+ * point, and neighbouring files sit on neighbouring values. Nothing rate-limits the file routes either.
+ *
+ * WHY THE CONDITIONS ARE THIS NARROW — a warning that fires on a correct configuration gets muted, and
+ * a muted warning is worse than none. So every way of DECIDING silences it, and all three are
+ * legitimate:
+ *
+ *  1. `file.access` names a project class (`'public'`, `'authenticated'`, `'owner'`, `'tenant'`);
+ *  2. `checkRights()` is overridden — the project wrote its own rule, and grading it is beyond what a
+ *     boot check can do;
+ *  3. the gate is still admin-only — a platform admin legitimately sees everything.
+ *
+ * That leaves exactly one case: the gate is open and nothing says what the policy is. This warning is
+ * about the difference between a DECISION and an OMISSION, which is the only thing a boot check can
+ * usefully detect.
+ *
+ * Multi-tenancy changes only the WORDING. An earlier version of this warning fired only for tenant
+ * projects, which was too narrow: `downloadRoles: [S_USER]` with no rule leaks every file to every
+ * signed-in user whether or not tenants exist. Where tenants DO exist, the leak also crosses that
+ * boundary, and that sentence has to appear — the file stores are reached outside Mongoose, so
+ * `mongooseTenantPlugin` never scopes them and these role names resolve against `user.roles`, a GLOBAL
+ * attribute.
+ *
+ * A warning, not a boot failure. The framework cannot know whether the files are patient documents or
+ * public logos, and refusing to start on a configuration that is correct for the second would be
+ * wrong. What it can do is refuse to be silent.
+ *
+ * @param hasPerFileRule whether `CoreFileService.checkRights()` is overridden — the caller knows,
+ *   because it has the instance; this helper stays a pure function so it can be unit-tested.
+ * @returns the message, or `undefined` when there is nothing to warn about. Returned as well as
+ *   logged for the same reason as {@link warnOnPresignedDownloadsWithRestrictedRoles}: the message IS
+ *   the contract, and a module-private Logger cannot be asserted against.
+ */
+export function warnOnUndecidedFileAccess(options: {
+  fileConfig?: IFileConfig;
+  hasPerFileRule: boolean;
+  multiTenancyEnabled: boolean;
+}): string | undefined {
+  const { fileConfig, hasPerFileRule, multiTenancyEnabled } = options;
+
+  // (1) and (2): somebody decided.
+  if (hasPerFileRule || (fileConfig?.access && fileConfig.access !== 'custom')) {
+    return undefined;
+  }
+
+  // (3): admin-only. ADMIN is unioned in by the class-level decorator regardless, so it never widens.
+  const widened: string[] = [];
+  for (const key of ['deleteRoles', 'downloadRoles', 'uploadRoles'] as FileRoleKey[]) {
+    const roles = resolveRoles(key, fileConfig);
+    if (roles.some((role) => role !== RoleEnum.ADMIN)) {
+      widened.push(`file.${key}=${JSON.stringify(roles)}`);
+    }
+  }
+  if (!widened.length) {
+    return undefined;
+  }
+
+  const tenantNote = multiTenancyEnabled
+    ? ' multiTenancy is active, and the leak crosses tenants too: the file stores are reached outside ' +
+      'Mongoose, so mongooseTenantPlugin never scopes them and these role names resolve against ' +
+      'user.roles — a GLOBAL attribute — never against membership.role.'
+    : '';
+
+  const message =
+    `The file gate is open beyond platform admins (${widened.join(', ')}), but no per-file policy is ` +
+    `declared: file.access is unset and CoreFileService.checkRights() is not overridden. Every holder ` +
+    `of such a role can therefore read, overwrite or delete EVERY file — and file ids are not secret, ` +
+    `they are ENUMERABLE (an ObjectId shares a per-process random part and an incrementing counter, so ` +
+    `one own upload reveals the neighbourhood), with no rate limit on the file routes.${tenantNote} ` +
+    `Declare the project class with file.access ('public' | 'authenticated' | 'owner' | 'tenant'), or ` +
+    `override checkRights() — see src/core/modules/file/README.md § Access control.`;
+
+  logger.warn(message);
+  return message;
+}

package/src/core/modules/file/file-roles.helper.ts

@@ -1,25 +1,22 @@
 import { Logger } from '@nestjs/common';
 
-import { RoleEnum } from '../../common/enums/role.enum';
 import { IFileConfig } from '../../common/interfaces/server-options.interface';
 import { CoreFileController } from './core-file.controller';
 import { CoreFileResolver } from './core-file.resolver';
+import { FileRoleKey, resolveRoles } from './file-roles.config';
 
 const logger = new Logger('CoreFileRoles');
 
-/**
- * Roles applied when `file` is not configured at all.
- *
- * Restrictive on purpose: one GridFS bucket is shared by every feature of the
- * consuming project, and the ObjectIds naming its blobs are not secrets.
- */
-export type FileRoleKey = 'deleteRoles' | 'downloadRoles' | 'uploadRoles';
-
-export const FILE_ROLE_DEFAULTS: Record<FileRoleKey, string[]> = {
-  deleteRoles: [RoleEnum.ADMIN],
-  downloadRoles: [RoleEnum.ADMIN],
-  uploadRoles: [RoleEnum.ADMIN],
-};
+// Re-exported so no import path broke: `FILE_ROLE_DEFAULTS`, the warnings and the key type are part
+// of the published API and used to live here. They moved into an import-free leaf because this file
+// imports the endpoint classes, which inject CoreFileService — see file-roles.config.ts.
+export {
+  FILE_ROLE_DEFAULTS,
+  resolveRoles,
+  warnOnPresignedDownloadsWithRestrictedRoles,
+  warnOnUndecidedFileAccess,
+} from './file-roles.config';
+export type { FileRoleKey } from './file-roles.config';
 
 /**
  * Which member is governed by which knob.
@@ -42,32 +39,6 @@ const ROLE_TARGETS: { key: FileRoleKey; member: string; owner: () => unknown }[]
   { key: 'deleteRoles', member: 'CoreFileResolver.deleteFile', owner: () => CoreFileResolver.prototype.deleteFile },
 ];
 
-/**
- * Resolve one knob to the role list that will actually be applied.
- *
- * An empty array is treated as "not configured". It cannot mean "nobody": the
- * guards read an all-empty role set as "no roles required" and return true, so
- * honouring it literally would OPEN the route instead of closing it — the exact
- * opposite of what someone writing `[]` intends.
- */
-function resolveRoles(key: FileRoleKey, config?: IFileConfig): string[] {
-  const configured = config?.[key];
-
-  if (configured === undefined) {
-    return FILE_ROLE_DEFAULTS[key];
-  }
-
-  if (!Array.isArray(configured) || configured.length === 0 || configured.some((role) => typeof role !== 'string')) {
-    logger.warn(
-      `Ignoring file.${key}: expected a non-empty array of role strings, got ${JSON.stringify(configured)}. ` +
-        `Falling back to ${JSON.stringify(FILE_ROLE_DEFAULTS[key])}.`,
-    );
-    return FILE_ROLE_DEFAULTS[key];
-  }
-
-  return configured;
-}
-
 /**
  * Apply the configured file roles to the core file endpoints.
  *

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

@@ -42,7 +42,7 @@ multiTenancy: {
   headerName: 'x-tenant-id',        // Header name (default: 'x-tenant-id')
   membershipModel: 'TenantMember',  // Mongoose model name (default)
   adminBypass: true,                 // System admins bypass membership (default: true)
-  excludeSchemas: ['User', 'Session'], // Schemas without tenant filtering
+  excludeSchemas: [], // OFF SWITCH for isolation, per model — see the warning below
   cacheTtlMs: 30000,                // Membership cache TTL in ms (default: 30s, 0 = disabled)
   roleHierarchy: {                   // Custom role hierarchy (default below)
     member: 1,
@@ -55,6 +55,25 @@ multiTenancy: {
 multiTenancy: { enabled: false },
 ```
 
+### `excludeSchemas` is an OFF SWITCH for isolation — read this before adding an entry
+
+A listed model gets **no tenant filter at all**: every query on it returns every tenant's rows. That
+is correct for a genuinely global collection and a data leak for anything else. The plugin only ever
+attaches to schemas that declare a `tenantId` field, so listing such a model overrides the intent of
+whoever declared it — since 11.35.0 that logs a warning naming the model.
+
+| Situation                                                                      | Do                                                                                                                  |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| Truly global lookup table (no `tenantId`)                                      | nothing — the plugin never attached                                                                                 |
+| Global USERS: one account reaches several tenants, memberships carry the scope | `excludeSchemas: ['User']` is correct                                                                               |
+| Per-tenant users: `User` has a `tenantId`                                      | do **not** list `User` — that switches isolation off for the account collection                                     |
+| `populate()` returns null across tenants                                       | that is the isolation working. Scope the reference, or confirm the target really is global — do not silence it here |
+| Membership model (`TenantMember`)                                              | added automatically, no entry needed                                                                                |
+
+Earlier versions of this README suggested `excludeSchemas: ['User', 'Session']` as an example. That
+suggestion is withdrawn: it is only right for the global-user model, and it was being copied into
+projects whose users are per-tenant.
+
 ## Components
 
 | Component                | Purpose                                                |

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;
   }
 
   // ===================================================================================================================