@lenne.tech/nest-server 11.34.1 → 11.35.1

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

@@ -1,6 +1,6 @@
 import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
 import { DynamicModule, Global, MiddlewareConsumer, Module, NestModule, UnauthorizedException } from '@nestjs/common';
-import { APP_INTERCEPTOR, APP_PIPE } from '@nestjs/core';
+import { APP_INTERCEPTOR, APP_PIPE, DiscoveryModule } from '@nestjs/core';
 import { GraphQLModule } from '@nestjs/graphql';
 import { MongooseModule } from '@nestjs/mongoose';
 import type { Context } from 'graphql-ws';
@@ -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,8 @@ 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 { CoreFileAccessAuditInitializer } from './core/modules/file/core-file-access-audit.initializer';
+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 +259,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 +285,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) {
@@ -289,6 +306,11 @@ export class CoreModule implements NestModule {
 
       // Core Services
       CoreCronJobsInitializer,
+      // Audits the file endpoints the project actually REGISTERED. applyFileRoles() above can only
+      // reach the base-class members; a subclass that re-declares one keeps its own @Roles() and the
+      // configuration never reaches that route. Only a bootstrap-time look at the registered class
+      // can tell those apart — see the initializer.
+      CoreFileAccessAuditInitializer,
       CoreRedisService,
       CoreS3Service,
       CoreTrustProxyInitializer,
@@ -365,7 +387,9 @@ export class CoreModule implements NestModule {
       }
     }
 
-    const imports: any[] = [MongooseModule.forRoot(config.mongoose.uri, config.mongoose.options)];
+    // DiscoveryModule: CoreFileAccessAuditInitializer needs the registered controller/resolver
+    // classes, which only exist once Nest has built its route table.
+    const imports: any[] = [DiscoveryModule, MongooseModule.forRoot(config.mongoose.uri, config.mongoose.options)];
 
     if (isGraphQlEnabled && config.graphQl) {
       imports.push(
@@ -593,6 +617,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 +727,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 +854,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

@@ -36,9 +36,11 @@ export * from './core/common/helpers/cookies.helper';
 export * from './core/common/helpers/graceful-shutdown.helper';
 export * from './core/common/helpers/db.helper';
 export * from './core/common/helpers/decorator.helper';
+export * from './core/common/helpers/execution-context-request.helper';
 export * from './core/common/helpers/file.helper';
 export * from './core/common/helpers/filter.helper';
 export * from './core/common/helpers/graphql.helper';
+export * from './core/common/helpers/graphql-ws-context.helper';
 export * from './core/common/helpers/interceptor.helper';
 export * from './core/common/helpers/gridfs.helper';
 export * from './core/common/helpers/input.helper';
@@ -81,6 +83,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';
@@ -93,6 +96,7 @@ export * from './core/common/services/core-cron-jobs.service';
 export * from './core/common/services/core-redis.service';
 export * from './core/common/services/core-redis-pubsub';
 export * from './core/common/services/core-s3.service';
+export * from './core/common/services/core-tenant-context.registry';
 export * from './core/common/services/rate-limit-store';
 export * from './core/common/services/crud.service';
 export * from './core/common/services/email.service';
@@ -172,10 +176,12 @@ export * from './core/modules/error-code';
 // Core - Modules - File
 // =====================================================================================================================
 
+export * from './core/modules/file/core-file-access-audit.initializer';
 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 +242,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 =

package/src/test/test.helper.ts

@@ -92,6 +92,16 @@ export interface TestGraphQLOptions {
    */
   cookies?: Record<string, string> | string;
 
+  /**
+   * Additional `connectionParams` for a SUBSCRIPTION handshake.
+   *
+   * Merged on top of the `Authorization` entry derived from `token`. A WebSocket carries no HTTP
+   * headers per operation, so anything the server reads from a header on the HTTP path — the tenant
+   * header above all — has to travel here instead. Without this a tenant-scoped subscription could
+   * not be tested at all.
+   */
+  connectionParams?: Record<string, string>;
+
   /**
    * Count of subscription messages, specifies how many messages are to be received on subscription
    */
@@ -788,10 +798,13 @@ export class TestHelper {
     }
 
     // Prepare subscription
-    let connectionParams;
+    let connectionParams: Record<string, string> | undefined;
     if (options?.token) {
       connectionParams = { Authorization: `Bearer ${options?.token}` };
     }
+    if (options?.connectionParams) {
+      connectionParams = { ...connectionParams, ...options.connectionParams };
+    }
 
     // Init client
     if (options.log) {
@@ -800,10 +813,27 @@ export class TestHelper {
     const client = createClient({ connectionParams, url: this.subscriptionUrl, webSocketImpl: ws });
     const messages: any[] = [];
     let unsubscribe: () => void;
+    let rejectSubscription: (reason: unknown) => void;
+
     const onNext = (message) => {
       if (options.log) {
         console.info('Subscription message', JSON.stringify(message, null, 2));
       }
+
+      // A REFUSED subscription arrives as a `next` message carrying `errors`, not through the
+      // transport's `error` callback: when a guard throws, graphql's `subscribe()` returns an
+      // ExecutionResult instead of an async iterable, and graphql-ws emits that as one payload
+      // followed by `complete`. Projecting only `data[name]` therefore turned "you may not subscribe
+      // to this" into an indistinguishable `undefined`/`null` message — so a test asserting that an
+      // unauthorized subscriber gets nothing passed just as well when the gate was wide open.
+      // Rejecting makes the refusal observable, which is what the caller actually experiences.
+      if (message?.errors?.length) {
+        const detail = message.errors.map((error: any) => error?.message ?? String(error)).join('; ');
+        rejectSubscription?.(new Error(`Subscription "${graphql.name}" failed: ${detail}`));
+        unsubscribe?.();
+        return;
+      }
+
       messages.push(message?.data?.[graphql.name]);
       if (messages.length <= options.countOfSubscriptionMessages) {
         unsubscribe();
@@ -811,16 +841,29 @@ export class TestHelper {
     };
 
     // Subscribe
-    await new Promise((resolve, reject) => {
-      unsubscribe = client.subscribe(
-        { query },
-        {
-          complete: resolve as any,
-          error: reject,
-          next: onNext,
-        },
-      );
-    });
+    //
+    // Disposed in `finally`, including on the refusal path: without it the client keeps its socket
+    // (and graphql-ws its reconnect timer) open past the end of the test, which surfaces later as a
+    // hanging process or as an error attributed to whichever test happened to run next.
+    try {
+      await new Promise((resolve, reject) => {
+        rejectSubscription = reject;
+        unsubscribe = client.subscribe(
+          { query },
+          {
+            complete: resolve as any,
+            error: reject,
+            next: onNext,
+          },
+        );
+      });
+    } finally {
+      try {
+        await client.dispose?.();
+      } catch {
+        // Already closing — nothing to clean up, and a teardown error must not mask the result.
+      }
+    }
 
     // Return subscribed messages
     return messages;