@lenne.tech/nest-server 11.34.0 → 11.35.0

package/src/core/common/plugins/mongoose-system-role.plugin.ts

@@ -0,0 +1,193 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../enums/role.enum';
+
+/**
+ * Mongoose plugin that refuses to STORE system roles (`s_*`) in a `roles` array.
+ *
+ * **This answers a different question than `mongooseRoleGuardPlugin`, which is why it is a
+ * separate plugin:**
+ *
+ * | Plugin | Question | Configurable | On violation |
+ * |--------|----------|--------------|--------------|
+ * | `mongooseRoleGuardPlugin` | WHO may change roles? | yes (`security.mongooseRoleGuardPlugin`) | strips the change |
+ * | `mongooseSystemRolePlugin` | WHICH values may be stored at all? | **no** | throws |
+ *
+ * Mixing the two would be a mistake in both directions: an ADMIN is allowed to change roles but
+ * still must not be able to store `s_self`, and a bypass (`runWithBypassRoleGuard()` / `force:
+ * true`) grants authority over the *change*, never permission to write a value that is invalid by
+ * construction. So this check runs FIRST and runs ALWAYS — for admins, for bypassed writes, for
+ * system operations with no user context.
+ *
+ * **Why storing one is dangerous:** `hasRole()` is a plain string intersection
+ * (`core-user.model.ts`), so a stored `'s_self'` satisfies every `S_SELF` check — including
+ * `updateUser` / `deleteUser` on ARBITRARY users (mail/password change → account takeover) —
+ * without the account carrying any real role. The rule "NEVER store S_ roles in user.roles" was
+ * documented for years; this is where it became enforced.
+ *
+ * **Why it throws rather than stripping:** silently dropping the value would hide a
+ * misconfiguration in an admin tool, which is exactly how the dormant skeleton key gets minted in
+ * the first place. A loud 400 is recoverable; a silent success is not observable.
+ *
+ * **Why the check is broader than the six `RoleEnum.S_*` members:** it rejects ANY value that
+ * looks like a system role after trimming and lower-casing (see {@link looksLikeSystemRole}).
+ * The framework cannot distinguish a future system role from a project role that happens to start
+ * with `s_`, and a false rejection is fixable by renaming while a false acceptance is a silent
+ * authorization hole. Projects using an `s_`-prefixed role name must rename it — see the
+ * 11.34.x-to-11.35.x migration guide.
+ *
+ * Registered unconditionally in `CoreModule` — unlike the configurable plugins beside it, there is
+ * no opt-out, because there is no legitimate reason to store one of these values.
+ */
+export function mongooseSystemRolePlugin(schema) {
+  schema.pre('save', function () {
+    if (!this.isModified('roles')) {
+      return;
+    }
+    // A NEW document has no stored baseline, so every value in it is being introduced.
+    assertNoSystemRoles(this['roles'], this.isNew ? [] : toRoleArray(this.$__.originalRoles));
+  });
+
+  // Capture the pre-modification value so the save hook above can tell an introduced value from a
+  // pre-existing one. `init` fires when a document is hydrated from the database.
+  schema.post('init', function () {
+    this.$__.originalRoles = Array.isArray(this['roles']) ? [...this['roles']] : undefined;
+  });
+
+  for (const op of ['findOneAndUpdate', 'updateOne', 'replaceOne', 'findOneAndReplace']) {
+    schema.pre(op, async function () {
+      await assertUpdateIntroducesNoSystemRoles(this);
+    });
+  }
+
+  // updateMany can span documents with different stored values, so there is no single baseline to
+  // compare against. Any system role in the update payload is refused outright.
+  schema.pre('updateMany', function () {
+    assertUpdateHasNoSystemRoles(this.getUpdate());
+  });
+
+  schema.pre('insertMany', function (docs) {
+    if (!Array.isArray(docs)) {
+      return;
+    }
+    for (const doc of docs) {
+      assertNoSystemRoles(doc?.roles);
+    }
+  });
+
+  schema.pre('bulkWrite', function (ops) {
+    if (!Array.isArray(ops)) {
+      return;
+    }
+    for (const op of ops) {
+      if ('insertOne' in op) {
+        assertNoSystemRoles(op.insertOne.document?.roles);
+      } else if ('updateOne' in op) {
+        assertUpdateHasNoSystemRoles(op.updateOne.update);
+      } else if ('updateMany' in op) {
+        assertUpdateHasNoSystemRoles(op.updateMany.update);
+      } else if ('replaceOne' in op) {
+        assertNoSystemRoles(op.replaceOne.replacement?.roles);
+      }
+    }
+  });
+}
+
+/** Normalize an unknown value to a string array; anything else becomes an empty baseline. */
+function toRoleArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/**
+ * Throw if the write INTRODUCES a system role.
+ *
+ * `alreadyStored` is the document's current value. A system role that is already in there is NOT
+ * refused, and this is load-bearing rather than lenient: `CrudService.update()` writes the whole
+ * object back, so a login (`updateRefreshToken` → `update`) re-sends the stored `roles` verbatim.
+ * Refusing that would lock every already-contaminated account out of the system on upgrade — and
+ * would do the same, fleet-wide, to any project whose own role name happens to start with `s_`.
+ * An upgrade must not cause a login outage; cleaning up stored values is what the migration guide's
+ * audit query is for.
+ *
+ * Accepts anything: a non-array (nothing to check) and non-string elements (cannot be a system
+ * role) pass through untouched — type validation is not this plugin's job.
+ */
+function assertNoSystemRoles(roles: unknown, alreadyStored: string[] = []): void {
+  if (!Array.isArray(roles)) {
+    return;
+  }
+
+  const introduced = roles.filter((role) => looksLikeSystemRole(role) && !alreadyStored.includes(role));
+  if (introduced.length) {
+    throw new BadRequestException(
+      `System roles (${SYSTEM_ROLE_PREFIX}*) must never be stored in user.roles: ${introduced.join(', ')}`,
+    );
+  }
+}
+
+/**
+ * Query-level variant: resolves the affected document's stored roles before deciding.
+ *
+ * The lookup is skipped entirely unless the payload actually carries a system role, so the common
+ * case costs nothing — only a write that is about to be refused pays for one extra read.
+ */
+async function assertUpdateIntroducesNoSystemRoles(query: any): Promise<void> {
+  const update = query.getUpdate();
+  if (!update || !collectRoleValues(update).some((role) => looksLikeSystemRole(role))) {
+    return;
+  }
+
+  // Only now — the payload is suspicious, so the baseline is worth one read.
+  let stored: string[] = [];
+  try {
+    const current = await query.model.findOne(query.getFilter()).select('roles').lean().exec();
+    stored = toRoleArray(current?.roles);
+  } catch {
+    // A failed lookup must not turn into an allow: fall through with an empty baseline, which
+    // refuses the write. Failing closed is correct for an authorization invariant.
+  }
+
+  assertUpdateHasNoSystemRoles(update, stored);
+}
+
+/** Every roles value the update could write, flattened across the operators that can carry one. */
+function collectRoleValues(update: any): unknown[] {
+  const values: unknown[] = [
+    ...toRoleArray(update.roles),
+    ...toRoleArray(update.$set?.roles),
+    ...toRoleArray(update.$setOnInsert?.roles),
+  ];
+
+  for (const operator of [update.$push?.roles, update.$addToSet?.roles]) {
+    if (operator === undefined || operator === null) {
+      continue;
+    }
+    values.push(...(Array.isArray(operator?.$each) ? operator.$each : [operator]));
+  }
+
+  return values;
+}
+
+/**
+ * Check every operator through which a roles value can reach the document.
+ *
+ * `$pull` is deliberately NOT checked — removing an `s_*` value from a document that already has
+ * one is exactly the cleanup this release asks projects to perform, so it must stay possible.
+ */
+function assertUpdateHasNoSystemRoles(update: any, alreadyStored: string[] = []): void {
+  if (!update) {
+    return;
+  }
+
+  assertNoSystemRoles(update.roles, alreadyStored);
+  assertNoSystemRoles(update.$set?.roles, alreadyStored);
+  assertNoSystemRoles(update.$setOnInsert?.roles, alreadyStored);
+
+  // $push / $addToSet take either a bare value or a { $each: [...] } modifier
+  for (const operator of [update.$push?.roles, update.$addToSet?.roles]) {
+    if (operator === undefined || operator === null) {
+      continue;
+    }
+    assertNoSystemRoles(Array.isArray(operator?.$each) ? operator.$each : [operator], alreadyStored);
+  }
+}

package/src/core/common/plugins/mongoose-tenant.plugin.ts

@@ -1,8 +1,48 @@
-import { ForbiddenException } from '@nestjs/common';
+import { ForbiddenException, Logger } from '@nestjs/common';
 
 import { ConfigService } from '../services/config.service';
 import { RequestContext } from '../services/request-context.service';
 
+/** Models already warned about, so the message appears once per process rather than per query. */
+const isolationDisabledWarned = new Set<string>();
+
+/**
+ * Say out loud that isolation is off for a schema that was built for it.
+ *
+ * `excludeSchemas` is a legitimate feature — a genuinely global lookup table has no tenant. But this
+ * plugin only ever attaches to schemas that DECLARE a `tenantId` field, so reaching here means the
+ * author of that schema intended per-tenant rows and the configuration silently overrides them.
+ * Nothing said so, and the shape is easy to arrive at by accident: the framework's own documentation
+ * carried `excludeSchemas: ['User', 'Session']` in a copyable `@example` from 11.20.0 onwards, which
+ * on a project with per-tenant users switches filtering off for the user collection.
+ *
+ * A warning, not a boot failure. An ambiguous ROLE vocabulary fails the boot because its access
+ * decisions cannot be resolved coherently; this configuration is perfectly coherent — it is simply
+ * one nobody may make without noticing.
+ *
+ * The membership model is skipped: `CoreModule` adds it to `excludeSchemas` itself because
+ * membership is tenant-spanning by design, so warning about it would be the framework complaining
+ * about its own correct default.
+ */
+function warnIsolationDisabled(modelName: string): void {
+  if (isolationDisabledWarned.has(modelName)) {
+    return;
+  }
+  isolationDisabledWarned.add(modelName);
+
+  const membershipModel = ConfigService.configFastButReadOnly?.multiTenancy?.membershipModel ?? 'TenantMember';
+  if (modelName === membershipModel) {
+    return;
+  }
+
+  new Logger('mongooseTenantPlugin').warn(
+    `Tenant isolation is DISABLED for "${modelName}": the schema declares a tenantId field, but ` +
+      `"${modelName}" is listed in multiTenancy.excludeSchemas — so no tenant filter is applied and ` +
+      `every query on it sees every tenant's rows. Remove it from excludeSchemas unless this ` +
+      `collection is genuinely global.`,
+  );
+}
+
 /**
  * Mongoose plugin that provides automatic tenant-based data isolation.
  * Only activates on schemas that have a `tenantId` path defined.
@@ -63,6 +103,19 @@ export function mongooseTenantPlugin(schema) {
       if (filter !== undefined) {
         this.where(filter);
       }
+
+      // The filter above constrains WHICH rows are touched, never what the update WRITES. So a
+      // caller could legitimately match their own row and then rewrite its tenantId — moving it
+      // into a tenant they control, or simply out of reach of its rightful owner.
+      const single = resolveSingleTenantId(modelName);
+      if (single) {
+        const update: any = typeof this.getUpdate === 'function' ? this.getUpdate() : undefined;
+        for (const candidate of [update?.tenantId, update?.$set?.tenantId, update?.$setOnInsert?.tenantId]) {
+          if (candidate !== undefined) {
+            assertOwnTenant(candidate, single, false);
+          }
+        }
+      }
     });
   }
 
@@ -70,14 +123,23 @@ export function mongooseTenantPlugin(schema) {
   // Intentional asymmetry: writes only set tenantId when truthy (not null).
   // Only uses single tenantId from header — tenantIds array is for reads only.
   schema.pre('save', function () {
+    // Document hooks: `this` is the document instance — modelName is on the constructor (the Model class)
+    const modelName = (this.constructor as any).modelName;
+    const tenantId = resolveSingleTenantId(modelName);
+    if (!tenantId) {
+      return;
+    }
+
     if (this.isNew && !this['tenantId']) {
-      // Document hooks: `this` is the document instance — modelName is on the constructor (the Model class)
-      const modelName = (this.constructor as any).modelName;
-      const tenantId = resolveSingleTenantId(modelName);
-      if (tenantId) {
-        this['tenantId'] = tenantId;
-      }
+      this['tenantId'] = tenantId;
+      return;
     }
+
+    // A tenantId that is already on the document did NOT come from this hook. Stamping only when
+    // absent is right for system writes, but on its own it means a caller-supplied value survives —
+    // so an explicit foreign tenantId would place the row in someone else's tenant, and modifying it
+    // on an existing document would move the row out of this one.
+    assertOwnTenant(this['tenantId'], tenantId, this.isNew);
   });
 
   // === insertMany (Mongoose 9: first arg is docs array, no next callback) ===
@@ -89,6 +151,8 @@ export function mongooseTenantPlugin(schema) {
       for (const doc of docs) {
         if (!doc.tenantId) {
           doc.tenantId = tenantId;
+        } else {
+          assertOwnTenant(doc.tenantId, tenantId, true);
         }
       }
     }
@@ -123,17 +187,182 @@ export function mongooseTenantPlugin(schema) {
     }
   });
 
-  // === Aggregate: prepend $match stage ===
+  // === estimatedDocumentCount: unfilterable, so refuse it inside a tenant context ===
+  //
+  // It reads collection metadata rather than running a query, so MongoDB ignores any filter — there
+  // is nothing to inject. Returning it unchanged would hand a tenant the row count of the WHOLE
+  // collection, i.e. every other tenant's volume. Throwing is the only honest option; callers that
+  // want a tenant's own count use countDocuments(), which IS filtered.
+  schema.pre('estimatedDocumentCount', function () {
+    const modelName = (this as any).model?.modelName;
+    if (shouldBypass(modelName)) {
+      return;
+    }
+    const context = RequestContext.get();
+    if (context?.isAdminBypass && !context?.tenantId) {
+      return; // platform admin without a tenant header legitimately sees everything
+    }
+    throw new ForbiddenException(
+      "estimatedDocumentCount() cannot be tenant-filtered and would expose other tenants' row counts — " +
+        'use countDocuments() instead',
+    );
+  });
+
+  // === Aggregate: prepend $match stage, and secure every cross-collection stage ===
   schema.pre('aggregate', function () {
     // Aggregate hooks: `this` is the Aggregation pipeline — the model is on the internal `_model` property
-    const modelName = (this as any)._model?.modelName;
+    const model = (this as any)._model;
+    const modelName = model?.modelName;
     const filter = resolveTenantFilter(modelName);
-    if (filter !== undefined) {
-      this.pipeline().unshift({ $match: filter });
+    if (filter === undefined) {
+      return;
+    }
+
+    const pipeline = this.pipeline();
+
+    // $out and $merge are the only aggregation stages that WRITE, and neither can be constrained
+    // the way a read stage can: $out REPLACES a whole collection, and $merge writes rows whose
+    // tenantId comes from the pipeline rather than from the caller's context. Either one turns an
+    // aggregation into a way to launder rows across the boundary — or, with $out, to erase another
+    // tenant's collection outright. There is nothing to inject here, so a tenant-scoped caller is
+    // refused; system code that legitimately needs them runs under runWithBypassTenantGuard().
+    const writeStage = pipeline.find((stage: any) => stage && (stage.$out !== undefined || stage.$merge !== undefined));
+    if (writeStage) {
+      throw new ForbiddenException(
+        `Aggregation write stages ($out / $merge) are not permitted inside a tenant context — ` +
+          'they cannot be tenant-filtered. Run them as a system operation if this is intended.',
+      );
     }
+
+    pipeline.unshift({ $match: filter });
+
+    // The $match above only constrains the SOURCE collection. `$lookup`, `$unionWith` and
+    // `$graphLookup` read a DIFFERENT collection, and that collection's own `aggregate` hook never
+    // fires — the join runs inside this pipeline. Without the pass below, a single aggregation
+    // returns every tenant's rows from the joined collection, which is exactly the shape a
+    // reporting query takes.
+    secureCrossCollectionStages(pipeline, model);
   });
 }
 
+/**
+ * Inject the tenant filter into every stage that reads another collection.
+ *
+ * Recurses, because these stages nest: a `$lookup.pipeline` may itself contain a `$lookup`, and
+ * `$facet` holds a sub-pipeline per key.
+ *
+ * A joined collection is only constrained when it is itself tenant-scoped (its model has a
+ * `tenantId` path and is not excluded). Joining a global lookup table stays untouched — filtering
+ * it by `tenantId` would silently return nothing.
+ */
+function secureCrossCollectionStages(pipeline: any[], model: any): void {
+  if (!Array.isArray(pipeline)) {
+    return;
+  }
+
+  for (const stage of pipeline) {
+    if (!stage || typeof stage !== 'object') {
+      continue;
+    }
+
+    if (stage.$lookup) {
+      const filter = filterForCollection(stage.$lookup.from, model);
+      if (filter) {
+        // MongoDB 5.0+ allows `pipeline` alongside localField/foreignField, so this works for the
+        // concise join form too, not only the explicit-pipeline one.
+        stage.$lookup.pipeline = [{ $match: filter }, ...(stage.$lookup.pipeline ?? [])];
+      }
+      secureCrossCollectionStages(stage.$lookup.pipeline, model);
+    }
+
+    if (stage.$unionWith) {
+      // Two forms: `$unionWith: 'coll'` and `$unionWith: { coll, pipeline }`.
+      if (typeof stage.$unionWith === 'string') {
+        const filter = filterForCollection(stage.$unionWith, model);
+        if (filter) {
+          stage.$unionWith = { coll: stage.$unionWith, pipeline: [{ $match: filter }] };
+        }
+      } else {
+        const filter = filterForCollection(stage.$unionWith.coll, model);
+        if (filter) {
+          stage.$unionWith.pipeline = [{ $match: filter }, ...(stage.$unionWith.pipeline ?? [])];
+        }
+        secureCrossCollectionStages(stage.$unionWith.pipeline, model);
+      }
+    }
+
+    if (stage.$graphLookup) {
+      const filter = filterForCollection(stage.$graphLookup.from, model);
+      if (filter) {
+        // $graphLookup takes no pipeline; `restrictSearchWithMatch` is its filter hook and applies
+        // to EVERY recursive step, which is what a traversal needs.
+        stage.$graphLookup.restrictSearchWithMatch = {
+          ...stage.$graphLookup.restrictSearchWithMatch,
+          ...filter,
+        };
+      }
+    }
+
+    if (stage.$facet && typeof stage.$facet === 'object') {
+      for (const branch of Object.values(stage.$facet)) {
+        secureCrossCollectionStages(branch as any[], model);
+      }
+    }
+  }
+}
+
+/**
+ * Tenant filter for a JOINED collection, or `undefined` when none applies.
+ *
+ * Resolves the collection name back to its model so the same "is this tenant-scoped?" rule applies
+ * as for a direct query. An unknown collection name yields no filter: the plugin cannot tell
+ * whether it is tenant-scoped, and inventing a `tenantId` constraint for a collection that has no
+ * such field would turn a working join into an empty result.
+ */
+function filterForCollection(collectionName: unknown, sourceModel: any): Record<string, any> | undefined {
+  if (typeof collectionName !== 'string' || !collectionName) {
+    return undefined;
+  }
+
+  const models = sourceModel?.db?.models ?? {};
+  for (const name of Object.keys(models)) {
+    const candidate = models[name];
+    if (candidate?.collection?.name !== collectionName) {
+      continue;
+    }
+    if (!candidate.schema?.path('tenantId')) {
+      return undefined; // not tenant-scoped — leave the join alone
+    }
+    const filter = resolveTenantFilter(name);
+    // `{}` means "admin bypass, sees everything" — nothing to inject.
+    return filter && Object.keys(filter).length ? filter : undefined;
+  }
+
+  return undefined;
+}
+
+/**
+ * Refuse a tenantId that is not the caller's own.
+ *
+ * Covers both directions of the same boundary:
+ * - creating a row with a FOREIGN tenantId → planting data in someone else's tenant;
+ * - changing an existing row's tenantId → moving data out of this one.
+ *
+ * Throwing rather than overwriting is deliberate. Silently rewriting the value would make a request
+ * that asked for something impossible look like it succeeded, and for tenant-scoped medical data
+ * "the write went somewhere other than you asked" is not a recoverable ambiguity.
+ */
+function assertOwnTenant(value: unknown, ownTenantId: string, isNew: boolean): void {
+  if (value === undefined || value === null || value === ownTenantId) {
+    return;
+  }
+  throw new ForbiddenException(
+    isNew
+      ? `Cannot create a document in a foreign tenant (got "${String(value)}", own tenant is "${ownTenantId}")`
+      : `Cannot move a document to a foreign tenant (got "${String(value)}", own tenant is "${ownTenantId}")`,
+  );
+}
+
 /**
  * Check common bypass conditions.
  *
@@ -146,7 +375,10 @@ function shouldBypass(modelName?: string): boolean {
   const context = RequestContext.get();
   if (!context) return true;
   if (context.bypassTenantGuard) return true;
-  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) return true;
+  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) {
+    warnIsolationDisabled(modelName);
+    return true;
+  }
 
   return false;
 }

package/src/core/common/services/core-s3.service.ts

@@ -92,7 +92,15 @@ export class CoreS3Service implements OnApplicationShutdown, OnModuleInit {
       this.logger.warn('Ignoring the `s3` configuration: no `bucket` is set, so S3 cannot be used.');
       return;
     }
-    const presigned = raw.presignedDownloads;
+    // `enabled: false` disables, exactly as everywhere else in the config (see
+    // .claude/rules/configurable-features.md). Reading any object as "enabled" made this the one
+    // knob where the documented pre-configuration idiom silently turned a feature ON — and it is a
+    // feature that hands out session-less bearer URLs.
+    const rawPresigned = raw.presignedDownloads;
+    const presigned =
+      rawPresigned && typeof rawPresigned === 'object' && (rawPresigned as { enabled?: boolean }).enabled === false
+        ? undefined
+        : rawPresigned;
     this.config = {
       accessKeyId: raw.accessKeyId,
       autoCreateBucket: raw.autoCreateBucket ?? false,

package/src/core/common/services/core-tenant-context.registry.ts

@@ -0,0 +1,50 @@
+/**
+ * How a non-HTTP transport asks the tenant machinery "which tenant is this caller in?".
+ *
+ * DELIBERATELY IMPORT-FREE apart from a type-only import, so it stays a leaf — and it lives under
+ * `src/core/common/` rather than next to the tenant module for a second reason: the reader is
+ * `graphql-ws-context.helper`, also in `src/core/common/`, and `src/core/common/**` must not import
+ * from `src/core/modules/**`. The writer (`CoreTenantGuard`) imports in the allowed direction.
+ * A registry rather than DI because the GraphQL wiring in `core.module.ts` must not depend on a
+ * provider that only exists when multi-tenancy is configured. Same pattern as
+ * `core-cron-jobs.registry.ts`. See `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ *
+ * WHY IT EXISTS: `CoreTenantGuard` answers this question from an Express request and writes the
+ * answer onto it (`request.tenantId` / `request.tenantIds`), which `RequestContextMiddleware` then
+ * exposes through AsyncLocalStorage. A WebSocket never traverses either — no Express middleware runs
+ * on an upgrade, and the guard's own `getRequest()` returns nothing for a subscription context, so it
+ * returns `true` without deciding anything. This registry is what lets the WebSocket path ask the
+ * same question through the same membership logic and cache.
+ */
+import type { IRequestContext } from './request-context.service';
+
+/** The tenant-relevant slice of a request context — everything the Mongoose tenant plugin reads. */
+export type ResolvedTenantContext = Pick<IRequestContext, 'isAdminBypass' | 'tenantId' | 'tenantIds' | 'tenantRole'>;
+
+export interface TenantContextResolver {
+  /**
+   * @param user the authenticated user (with `roles`), or undefined for an anonymous caller
+   * @param headerTenantId the raw tenant id the transport carried, if any — NEVER trusted; it is
+   *   validated against an active membership before it is returned
+   */
+  resolve(user: { id: string; roles?: string[] } | undefined, headerTenantId?: string): Promise<ResolvedTenantContext>;
+}
+
+let resolver: TenantContextResolver | undefined;
+
+/** Registered by `CoreTenantGuard` on init. Idempotent — test fixtures build the guard repeatedly. */
+export function setTenantContextResolver(next: TenantContextResolver | undefined): void {
+  resolver = next;
+}
+
+/**
+ * The registered resolver, or `undefined` when multi-tenancy is not in play.
+ *
+ * `undefined` must NOT be read as "no tenant restrictions": it means nothing can answer the
+ * question, so a caller establishes a context WITHOUT tenant information and lets the Mongoose
+ * plugin's safety net refuse tenant-scoped reads. That is the difference between "this data is not
+ * tenant-scoped" and "nobody knows which tenant this is".
+ */
+export function getTenantContextResolver(): TenantContextResolver | undefined {
+  return resolver;
+}

package/src/core/modules/auth/guards/roles.guard.ts

@@ -9,6 +9,8 @@ import {
 } from '@nestjs/common';
 import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
+
+import { resolveGuardRequest } from '../../../common/helpers/execution-context-request.helper';
 import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
@@ -341,10 +343,10 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
    * Integrate request from GraphQL
    */
   getRequest(context: ExecutionContext) {
-    const ctx = GqlExecutionContext.create(context);
-    // For GraphQL: ctx.getContext() is the GQL context with `.req` property
-    // For REST/HTTP: ctx.getContext() returns the `next` function (truthy but without `.req`)
-    // Using `?.req ||` ensures we fall back to the HTTP request for REST controllers
-    return ctx.getContext()?.req || context.switchToHttp().getRequest();
+    // Shared with BetterAuthRolesGuard and CoreTenantGuard — see execution-context-request.helper.
+    // For GraphQL over HTTP the context carries `.req`; for REST it does not (it is the `next`
+    // function) and the HTTP fallback applies; for a GraphQL SUBSCRIPTION neither holds, and the
+    // subscription context itself is the request-like object.
+    return resolveGuardRequest(context, (ctx) => GqlExecutionContext.create(ctx).getContext());
   }
 }

package/src/core/modules/better-auth/better-auth-roles.guard.ts

@@ -8,6 +8,8 @@ import {
 } from '@nestjs/common';
 import { GqlExecutionContext } from '@nestjs/graphql';
 
+import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper';
+
 import { RoleEnum } from '../../common/enums/role.enum';
 import { ErrorCode } from '../error-code';
 import { isMultiTenancyActive, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers';
@@ -178,19 +180,11 @@ export class BetterAuthRolesGuard implements CanActivate {
    * Handles both GraphQL and HTTP contexts
    */
   private getRequest(context: ExecutionContext): any {
-    // Try GraphQL context first
-    try {
-      const gqlContext = GqlExecutionContext.create(context);
-      const ctx = gqlContext.getContext();
-      if (ctx?.req) {
-        return ctx.req;
-      }
-    } catch {
-      // GraphQL context not available
-    }
-
-    // Fallback to HTTP context
-    return context.switchToHttp().getRequest();
+    // Shared with RolesGuard and CoreTenantGuard — see execution-context-request.helper. The GraphQL
+    // WEBSOCKET branch is what makes `@Roles()` work on a subscription at all: the subscription
+    // context carries the authenticated user (CoreModule's onConnect records it), while `.req` does
+    // not exist there and the HTTP fallback yields the resolver root.
+    return resolveGuardRequest(context, (ctx) => GqlExecutionContext.create(ctx).getContext());
   }
 
   /**