@lenne.tech/nest-server 11.34.1 → 11.35.0

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.
 
 ---
 

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

@@ -18,6 +18,7 @@ import {
   FilesystemFileHelper,
 } from '../file/filesystem-file.helper';
 import { S3_FILES_COLLECTION, S3FileHelper } from '../file/s3-file.helper';
+import { TUS_OWNER_METADATA_KEY } from './tus.constants';
 import { TusRedisLocker } from './tus-redis-locker';
 import {
   DEFAULT_TUS_ALLOWED_HEADERS,
@@ -181,6 +182,11 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       const contentType = metadata.filetype || 'application/octet-stream';
       const fileMetadata = {
         originalMetadata: metadata,
+        // The key `CoreFileService.checkRights()` documents for a per-file ownership rule. Without it
+        // a tus-uploaded file could never satisfy that rule — it failed CLOSED for everyone but
+        // ADMIN, so a project following the documented pattern ended up with undownloadable files.
+        // Written from the SERVER-recorded owner, never from the client's own metadata.
+        ...(metadata[TUS_OWNER_METADATA_KEY] ? { ownerId: metadata[TUS_OWNER_METADATA_KEY] } : {}),
         tusUploadId: upload.id,
         uploadedAt: new Date(),
       };
@@ -460,6 +466,79 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
     await this.deleteStagedUpload(upload.id);
   }
 
+  /**
+   * The authenticated caller's id, as the upstream role guard left it on the request.
+   *
+   * `CoreTusController.handleTus(req, res)` receives the Express request, so `req.user` is whatever
+   * the guard put there. But `@tus/server` v2 does NOT hand that object to its hooks: `handle()`
+   * converts the Node request into a WHATWG `ServerRequest` (srvx) first, and anything the guard
+   * attached lives on the ORIGINAL request, reachable through `runtime.node.req`. Reading only
+   * `req.user` therefore finds nothing and every upload silently becomes owner-less — which fails in
+   * the permissive direction, so it would not have shown up as an error anywhere.
+   *
+   * Returns `undefined` for an unauthenticated request, which is a legitimate state: a project may
+   * open the gate with `tus.roles: [RoleEnum.S_EVERYONE]` for a public form.
+   *
+   * Override to read the owner from somewhere else (an API key, a signed form token).
+   */
+  protected readRequestUserId(req: any): string | undefined {
+    const id = req?.user?.id ?? req?.runtime?.node?.req?.user?.id ?? req?.context?.user?.id;
+    return id === undefined || id === null || id === '' ? undefined : String(id);
+  }
+
+  /**
+   * Refuse a request that names an upload the caller does not own.
+   *
+   * `tus.roles` is the coarse gate — who may reach the endpoint at all. This is the fine one: HEAD
+   * (read the offset), PATCH (APPEND BYTES) and DELETE (terminate) all address an upload by its URL,
+   * and without this any authenticated caller who learns an id could resume, overwrite or destroy
+   * somebody else's upload. Appending is the sharpest: those bytes are then migrated into the file
+   * store under the ORIGINAL uploader's filename, so the attacker's content is served as the victim's.
+   *
+   * **Refuses with 404, never 403** — the same policy `CoreFileService.checkRights()` states: a
+   * refusal must be indistinguishable from an upload that does not exist, or the endpoint becomes an
+   * existence oracle for ids that are not secrets.
+   *
+   * **An OWNER-LESS upload stays reachable by anyone who may reach the endpoint.** That is deliberate
+   * and load-bearing for backward compatibility: uploads created before 11.35.0 carry no owner, and
+   * so does every upload of a project that deliberately runs the endpoint public. Denying those would
+   * turn an upgrade into a fleet-wide breakage of in-flight uploads and break a documented
+   * configuration. What is closed is the case that actually leaks: an upload that HAS an owner being
+   * touched by somebody else.
+   *
+   * Override to widen this — e.g. to let a support role resume any upload.
+   */
+  protected async assertUploadOwnership(req: any, uploadId: string): Promise<void> {
+    // No id: this is a creation (POST) or a server-capability request (OPTIONS). Nothing to own yet.
+    if (!uploadId) {
+      return;
+    }
+
+    let owner: string | undefined;
+    try {
+      const upload = await (this.tusServer as any)?.datastore?.getUpload?.(uploadId);
+      const recorded = upload?.metadata?.[TUS_OWNER_METADATA_KEY];
+      owner = recorded === undefined || recorded === null ? undefined : String(recorded);
+    } catch {
+      // Unknown id, or a store that cannot answer right now. Say nothing and let the tus server
+      // produce its own 404 — inventing a refusal here would also refuse legitimate retries during a
+      // transient store outage.
+      return;
+    }
+
+    if (!owner) {
+      return; // owner-less upload — see the note above
+    }
+
+    const caller = this.readRequestUserId(req);
+    if (caller && caller === owner) {
+      return;
+    }
+
+    this.logger.warn(`Refused tus request for upload ${uploadId}: caller is not its owner`);
+    throw Object.assign(new Error('Upload not found'), { body: 'Upload not found', status_code: 404 });
+  }
+
   /**
    * Validate file type against allowedTypes configuration
    *
@@ -519,11 +598,20 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       datastore,
       ...(locker ? { locker } : {}),
       maxSize: this.config.maxSize,
-      onUploadCreate: async (_req, upload) => {
+      // Every request that names an upload — HEAD (offset), PATCH (append bytes), DELETE
+      // (terminate) — is checked against the upload's recorded owner. `tus.roles` alone cannot do
+      // this: it decides who may reach the endpoint, not which upload they may touch, and the tus
+      // protocol is built around a per-upload URL. Appending is the sharp end — bytes PATCHed into
+      // somebody else's upload are migrated into the file store under THEIR filename.
+      onIncomingRequest: async (req, uploadId) => this.assertUploadOwnership(req, uploadId),
+      onUploadCreate: async (req, upload) => {
+        // Record the creator FIRST, so the ownership check below has something to compare against.
+        // Overwrites rather than merges: see TUS_OWNER_METADATA_KEY.
+        const metadata = { ...upload.metadata, [TUS_OWNER_METADATA_KEY]: this.readRequestUserId(req) ?? null };
+
         // Validate file type if allowedTypes is configured
         if (this.config.allowedTypes && this.config.allowedTypes.length > 0) {
-          const metadata = this.parseMetadata(upload.metadata);
-          const filetype = metadata.filetype;
+          const filetype = this.parseMetadata(upload.metadata).filetype;
 
           if (!this.validateFileType(filetype)) {
             const allowedList = this.config.allowedTypes.join(', ');
@@ -541,8 +629,9 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
           }
         }
 
-        // Return empty object to proceed with upload
-        return {};
+        // Returning the metadata is what PERSISTS the owner — the tus server writes the returned
+        // value onto the upload. Returning `{}` here would keep the client's own metadata verbatim.
+        return { metadata };
       },
       onUploadFinish: async (_req, upload) => {
         try {

package/src/core/modules/tus/index.ts

@@ -2,4 +2,5 @@
 export * from './core-tus.controller';
 export * from './core-tus.service';
 export * from './interfaces/tus-config.interface';
+export * from './tus.constants';
 export * from './tus.module';

package/src/core/modules/tus/tus.constants.ts

@@ -1,5 +1,5 @@
 /**
- * Dependency-injection tokens of the TUS module.
+ * Dependency-injection tokens AND cross-file constants of the TUS module.
  *
  * They live in a dedicated, import-free leaf file — never in `tus.module.ts` or a service — so that
  * no file needing a token has to import the module (or vice versa) and close an import cycle.
@@ -23,3 +23,19 @@
  * Injected type: `Required<ITusConfig>`.
  */
 export const TUS_CONFIG = 'TUS_CONFIG';
+
+/**
+ * Metadata key recording WHO created a tus upload, in the upload's own (staged) metadata.
+ *
+ * Framework-owned and ALWAYS overwritten in `onUploadCreate` — metadata otherwise arrives from the
+ * client in the `Upload-Metadata` header, so a merged value would let a caller declare somebody else
+ * as the owner and hand themselves access to the victim's upload URL.
+ *
+ * Deliberately NOT `ownerId`: that is the key of the FINISHED FILE's metadata (the one
+ * `CoreFileService.checkRights()` documents), and keeping the two distinct means a project's own
+ * `ownerId` metadata on a file cannot be confused with the upload-time record.
+ *
+ * It lives here rather than in the service for the same reason the token above does — and because
+ * `tests/unit/import-cycle-invariants.spec.ts` enforces exactly that placement.
+ */
+export const TUS_OWNER_METADATA_KEY = 'ltOwnerId';

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

@@ -4,6 +4,7 @@ import crypto = require('crypto');
 import { sha256 } from 'js-sha256';
 import { Document, Model } from 'mongoose';
 
+import { looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../../common/enums/role.enum';
 import { assignPlain, prepareServiceOptionsForCreate } from '../../common/helpers/input.helper';
 import { ServiceOptions } from '../../common/interfaces/service-options.interface';
 import { ConfigService } from '../../common/services/config.service';
@@ -263,6 +264,17 @@ export abstract class CoreUserService<
       throw new BadRequestException('Roles contains invalid values');
     }
 
+    // Reject system roles (s_*). This is the framework's canonical "assign roles" API and it writes
+    // straight through findByIdAndUpdate, so neither MapAndValidatePipe nor check() sees the values.
+    // mongooseSystemRolePlugin is the backstop below this; the explicit check here exists to fail
+    // before the DB round-trip and with a message naming the offending values.
+    const systemRoles = roles.filter((role) => looksLikeSystemRole(role));
+    if (systemRoles.length) {
+      throw new BadRequestException(
+        `System roles (${SYSTEM_ROLE_PREFIX}*) must never be stored in user.roles: ${systemRoles.join(', ')}`,
+      );
+    }
+
     // Update and return user
     return this.process(
       async () => {

package/src/core/modules/user/inputs/core-user.input.ts

@@ -1,10 +1,10 @@
 import { InputType } from '@nestjs/graphql';
-import { IsEmail } from 'class-validator';
+import { IsEmail, IsString, Matches } from 'class-validator';
 
 import { Restricted } from '../../../common/decorators/restricted.decorator';
 import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
 import { ProcessType } from '../../../common/enums/process-type.enum';
-import { RoleEnum } from '../../../common/enums/role.enum';
+import { RoleEnum, SYSTEM_ROLE_PREFIX, SYSTEM_ROLE_REJECT_PATTERN } from '../../../common/enums/role.enum';
 import { CoreInput } from '../../../common/inputs/core-input.input';
 
 /**
@@ -50,12 +50,38 @@ export abstract class CoreUserInput extends CoreInput {
 
   /**
    * Roles of the user
+   *
+   * System roles (`s_*` prefix, see RoleEnum) are runtime-context checks and must NEVER be stored:
+   * `hasRole` is a plain string intersection, so a stored `s_self` would satisfy every S_SELF
+   * check (e.g. update/delete of ARBITRARY users) without the account carrying a real role.
+   * The @Restricted above limits WHO may send the field; this validator limits WHAT it may hold.
+   *
+   * A rejected value answers HTTP 400 (`Validation failed for 1 field: roles (matches)`, with the
+   * per-field message in the response body). `CoreUserCreateInput` inherits this field, so sign-up
+   * and user creation are covered too.
+   *
+   * This validator is the FIRST of three layers, not the only one — it gives the best error
+   * message, but a subclass that redeclares `roles` replaces it (MapAndValidatePipe walks the
+   * prototype chain child-first and skips a property once a child class has validated it), and
+   * `force: true` / direct Mongoose writes never reach it at all. `CoreUserService.setRoles()` and
+   * the unconditional `mongooseSystemRolePlugin` close those paths.
    */
   @Restricted({ processType: ProcessType.INPUT, roles: RoleEnum.ADMIN })
   @UnifiedField({
+    description: 'Roles of the user (system roles with s_ prefix are rejected)',
     isArray: true,
     isOptional: true,
     type: String,
+    // `opts` already carries `each: true` for array fields — do not hardcode it, or array-ness has
+    // two sources of truth. Note that supplying `validator` REPLACES the built-in `IsString`, so it
+    // is re-declared here explicitly rather than relying on `matches()` rejecting non-strings.
+    validator: (opts) => [
+      IsString(opts),
+      Matches(SYSTEM_ROLE_REJECT_PATTERN, {
+        ...opts,
+        message: `System roles (${SYSTEM_ROLE_PREFIX}*) must never be stored in user.roles`,
+      }),
+    ],
   })
   roles?: string[] = undefined;
 

package/src/core.module.ts

@@ -8,6 +8,10 @@ import graphqlUploadExpress = require('graphql-upload/graphqlUploadExpress.js');
 import mongoose from 'mongoose';
 
 import { merge } from './core/common/helpers/config.helper';
+import {
+  buildRequestContextAwareExecute,
+  buildRequestContextAwareSubscribe,
+} from './core/common/helpers/graphql-ws-context.helper';
 import { CheckResponseInterceptor } from './core/common/interceptors/check-response.interceptor';
 import { CheckSecurityInterceptor } from './core/common/interceptors/check-security.interceptor';
 import { ResponseModelInterceptor } from './core/common/interceptors/response-model.interceptor';
@@ -31,6 +35,7 @@ import { mongooseIdPlugin } from './core/common/plugins/mongoose-id.plugin';
 import { mongooseAuditFieldsPlugin } from './core/common/plugins/mongoose-audit-fields.plugin';
 import { mongoosePasswordPlugin } from './core/common/plugins/mongoose-password.plugin';
 import { mongooseRoleGuardPlugin } from './core/common/plugins/mongoose-role-guard.plugin';
+import { mongooseSystemRolePlugin } from './core/common/plugins/mongoose-system-role.plugin';
 import { mongooseTenantPlugin } from './core/common/plugins/mongoose-tenant.plugin';
 import { ConfigService } from './core/common/services/config.service';
 import { CoreCronJobsInitializer } from './core/common/services/core-cron-jobs.initializer';
@@ -46,7 +51,7 @@ import { CoreBetterAuthUserMapper } from './core/modules/better-auth/core-better
 import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-auth.module';
 import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
-import { applyFileRoles } from './core/modules/file/file-roles.helper';
+import { applyFileRoles, warnOnPresignedDownloadsWithRestrictedRoles } from './core/modules/file/file-roles.helper';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 import { CoreHubModule } from './core/modules/hub/core-hub.module';
 import { isHubEnabled, isHubQueriesEnabled } from './core/modules/hub/hub-config.helper';
@@ -253,6 +258,12 @@ export class CoreModule implements NestModule {
       if (config.security?.mongooseRoleGuardPlugin !== false) {
         connection.plugin(mongooseRoleGuardPlugin);
       }
+      // Refuse to store system roles (s_*) in a roles array. Deliberately NOT configurable and
+      // registered independently of the role guard above: that one decides WHO may change roles
+      // (and can be switched off), this one decides WHICH values may exist at all. A stored
+      // 's_self' satisfies every S_SELF check on arbitrary users, so there is no configuration
+      // under which writing one is legitimate.
+      connection.plugin(mongooseSystemRolePlugin);
       // Add audit fields plugin (enabled by default, opt-out via config)
       if (config.security?.mongooseAuditFieldsPlugin !== false) {
         connection.plugin(mongooseAuditFieldsPlugin);
@@ -273,6 +284,11 @@ export class CoreModule implements NestModule {
     // function and opt out of this; see applyFileRoles() for why.
     applyFileRoles(config.file);
 
+    // Presigned downloads hand out a bearer URL that ignores roles after it is issued, so pairing
+    // them with a restricted downloadRoles is usually an oversight. Warn rather than fail — the
+    // combination has legitimate uses, it just should not be reached by accident.
+    warnOnPresignedDownloadsWithRestrictedRoles(config.s3, config.file);
+
     // Check secrets
     const jwtConfig = config.jwt;
     if (jwtConfig?.secret && jwtConfig.secret && jwtConfig.refresh && jwtConfig.refresh.secret === jwtConfig.secret) {
@@ -593,6 +609,21 @@ export class CoreModule implements NestModule {
             cors,
             installSubscriptionHandlers: true,
             subscriptions: {
+              // WEBSOCKET REQUEST CONTEXT. `GqlSubscriptionService` destructures `execute` /
+              // `subscribe` from its own options and hands them to BOTH WS transports, so these two
+              // are the only place where a whole WS operation is reachable as one call. They must sit
+              // INSIDE `subscriptions`: `ApolloDriver.start()` forwards only
+              // `{ schema, path, context, ...options.subscriptions }`, so a top-level pair is
+              // silently dropped.
+              //
+              // Without them a WS operation runs with NO `RequestContext` at all — no Express
+              // middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a
+              // subscription context — and `mongooseTenantPlugin` reads "no context" as "system
+              // operation, no filter". A tenant-scoped read while delivering a subscription message
+              // therefore returned EVERY tenant's rows, with the plugin's safety net unable to
+              // notice. HTTP does not pass through these (Apollo runs its own pipeline).
+              execute: buildRequestContextAwareExecute(),
+              subscribe: buildRequestContextAwareSubscribe(),
               'graphql-ws': {
                 context: ({ extra }) => extra,
                 onConnect: async (context: Context<any, any>) => {
@@ -688,6 +719,21 @@ export class CoreModule implements NestModule {
             cors,
             installSubscriptionHandlers: true,
             subscriptions: {
+              // WEBSOCKET REQUEST CONTEXT. `GqlSubscriptionService` destructures `execute` /
+              // `subscribe` from its own options and hands them to BOTH WS transports, so these two
+              // are the only place where a whole WS operation is reachable as one call. They must sit
+              // INSIDE `subscriptions`: `ApolloDriver.start()` forwards only
+              // `{ schema, path, context, ...options.subscriptions }`, so a top-level pair is
+              // silently dropped.
+              //
+              // Without them a WS operation runs with NO `RequestContext` at all — no Express
+              // middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a
+              // subscription context — and `mongooseTenantPlugin` reads "no context" as "system
+              // operation, no filter". A tenant-scoped read while delivering a subscription message
+              // therefore returned EVERY tenant's rows, with the plugin's safety net unable to
+              // notice. HTTP does not pass through these (Apollo runs its own pipeline).
+              execute: buildRequestContextAwareExecute(),
+              subscribe: buildRequestContextAwareSubscribe(),
               'graphql-ws': {
                 context: ({ extra }) => extra,
                 onConnect: async (context: Context<any, any>) => {
@@ -800,6 +846,21 @@ export class CoreModule implements NestModule {
             cors,
             installSubscriptionHandlers: true,
             subscriptions: {
+              // WEBSOCKET REQUEST CONTEXT. `GqlSubscriptionService` destructures `execute` /
+              // `subscribe` from its own options and hands them to BOTH WS transports, so these two
+              // are the only place where a whole WS operation is reachable as one call. They must sit
+              // INSIDE `subscriptions`: `ApolloDriver.start()` forwards only
+              // `{ schema, path, context, ...options.subscriptions }`, so a top-level pair is
+              // silently dropped.
+              //
+              // Without them a WS operation runs with NO `RequestContext` at all — no Express
+              // middleware runs on an upgrade, and `CoreTenantGuard.getRequest()` finds no `req` on a
+              // subscription context — and `mongooseTenantPlugin` reads "no context" as "system
+              // operation, no filter". A tenant-scoped read while delivering a subscription message
+              // therefore returned EVERY tenant's rows, with the plugin's safety net unable to
+              // notice. HTTP does not pass through these (Apollo runs its own pipeline).
+              execute: buildRequestContextAwareExecute(),
+              subscribe: buildRequestContextAwareSubscribe(),
               'graphql-ws': {
                 context: ({ extra }) => extra,
                 onConnect: async (context: Context<any, any>) => {

package/src/index.ts

@@ -81,6 +81,7 @@ export * from './core/common/plugins/mongoose-id.plugin';
 export * from './core/common/plugins/mongoose-audit-fields.plugin';
 export * from './core/common/plugins/mongoose-password.plugin';
 export * from './core/common/plugins/mongoose-role-guard.plugin';
+export * from './core/common/plugins/mongoose-system-role.plugin';
 export * from './core/common/plugins/mongoose-tenant.plugin';
 export * from './core/common/scalars/any.scalar';
 export * from './core/common/scalars/date-timestamp.scalar';
@@ -176,6 +177,7 @@ export * from './core/modules/file/core-file-info.model';
 export * from './core/modules/file/core-file.controller';
 export * from './core/modules/file/core-file.resolver';
 export * from './core/modules/file/core-file.service';
+export * from './core/modules/file/file-access.helper';
 export * from './core/modules/file/file-roles.helper';
 export * from './core/modules/file/file-storage.helper';
 export * from './core/modules/file/filesystem-file.helper';
@@ -236,6 +238,7 @@ export * from './core/modules/tenant/core-tenant-member.model';
 export * from './core/modules/tenant/core-tenant.decorators';
 export * from './core/modules/tenant/core-tenant.enums';
 export * from './core/modules/tenant/core-tenant.guard';
+export * from './core/modules/tenant/core-role-scope.registry';
 export * from './core/modules/tenant/core-tenant.helpers';
 export * from './core/modules/tenant/core-tenant.module';
 export * from './core/modules/tenant/core-tenant.service';

package/src/server/modules/file/file.service.ts

@@ -98,12 +98,28 @@ export class FileService extends CoreFileService {
    * See `src/core/modules/file/README.md` § Access control, and
    * `tests/file-ownership.e2e-spec.ts` for the end-to-end contract test.
    */
+  /**
+   * NOTE FOR CONSUMERS: since 11.35.0 you may not need any of this.
+   *
+   * `file.access: 'owner'` is exactly the rule below, shipped by the framework — including the parts
+   * that are easy to get wrong (fail closed without a user, require the owner field to be PRESENT,
+   * cover the by-name branch, refuse a listing) and including the metadata stamping, which this project
+   * does by hand in `AvatarController`. `'tenant'` is the same rule against
+   * `metadata.tenantId` and the validated `RequestContext` tenant.
+   *
+   * This override stays because the reference server has to EXERCISE the seam — a rule that lives only
+   * in a preset proves the preset works, never that the inheritance point a consuming project extends
+   * still does. Keep it here; in your own project, prefer the preset unless your rights are something
+   * the framework cannot guess (an explicit read right, a case assignment, a published flag).
+   */
   protected override async checkRights(
     input: any,
     options?: FileServiceOptions & { checkInputType: FileInputCheckType },
   ): Promise<boolean> {
-    // Writes, list queries and forced (system) calls stay on the coarse role gate.
-    if (options?.force || (options?.checkInputType !== 'filename' && options?.checkInputType !== 'id')) {
+    // Forced (system) calls and WRITES stay on the coarse role gate. Writes deliberately so: an
+    // upload has no owner to compare against yet — `AvatarController` records `metadata.ownerId` as
+    // it writes — so the only meaningful gate there is `file.uploadRoles`.
+    if (options?.force || options?.checkInputType === 'file' || options?.checkInputType === 'files') {
       return true;
     }
 
@@ -111,6 +127,33 @@ export class FileService extends CoreFileService {
       return true;
     }
 
+    // A LISTING cannot be narrowed by this hook, so it is refused rather than waved through.
+    //
+    // The hook is asked ONCE for the whole query, not once per row, so there is no answer here that
+    // means "…but only their own files". Returning `true` — which this rule used to do, and which is
+    // therefore the shape projects copied — hands a non-admin a full inventory of every upload the
+    // moment a project surfaces `findFileInfo()`: `CoreFileInfo` carries `filename`, `length`,
+    // `uploadDate` and the `id`, and for medical data the filename frequently IS the content.
+    //
+    // A project that wants "my files" FORCES the constraint server-side and passes `force: true`:
+    //
+    //   this.fileService.findFileInfo(
+    //     { filterQuery: { 'metadata.ownerId': String(currentUser.id) } },
+    //     { force: true },
+    //   );
+    //
+    // Note what that is NOT: it does not inspect the caller's `filterArgs` to check whether they are
+    // already narrowed. `filterArgs` is CLIENT-CONTROLLED, so approving a filter shape means
+    // validating attacker input — and any such check is one filter shape away from being wrong.
+    // Override the filter; never approve it. See tests/file-ownership.e2e-spec.ts.
+    // Explicit, even though falling through would ALSO deny: with `checkInputType: 'filterArgs'` the
+    // `input` is a FilterArgs object, so the by-name raw lookup below answers null and the comparison
+    // fails. That is an accident of the fall-through, not a decision — it would flip the moment a
+    // project's own raw lookup behaved differently for a non-string input. Say it outright instead.
+    if (options.checkInputType === 'filterArgs') {
+      return false;
+    }
+
     // The RAW document on purpose: the public getFileInfo() runs prepareOutput(), which
     // strips `metadata` — the very field this decision rests on.
     const raw =