@lenne.tech/nest-server 11.35.0 → 11.35.1

package/migration-guides/11.34.x-to-11.35.x.md

@@ -49,11 +49,12 @@ Then run the one-time audit in §3.
 them is half-wired if you take one side and not the other, and a half-wired enforcement layer is worse
 than none because it reads as protection.
 
-**Seven new files:**
+**Nine new files** (eight rows — the two file-module files ship as one pair):
 
 | File | Belongs with |
 |------|--------------|
 | `common/plugins/mongoose-system-role.plugin.ts` | `common/enums/role.enum.ts` — the plugin is the unconditional layer, the enum holds the predicates (§1) |
+| `modules/tenant/core-role-scope.registry.ts` | `modules/tenant/core-tenant.helpers.ts` + `modules/tenant/core-tenant.module.ts` + `common/enums/role.enum.ts` — the registry holds the global-vs-tenant split the guards resolve against, `core-tenant.helpers.ts` feeds it from configuration, and `core-tenant.module.ts` is where `forRoot()` registers that source and runs `assertRoleVocabularyIsCoherent()`. Without the module wiring the registry stays empty, every role resolves to `RoleScope.UNKNOWN`, and the boot check that refuses an incoherent vocabulary never runs (§5) |
 | `common/decorators/nested-type.registry.ts` | `decorators/restricted.decorator.ts` + `decorators/unified-field.decorator.ts` — the registry is written by one and read by the other (§8) |
 | `common/decorators/restrictions-checked.marker.ts` | `decorators/restricted.decorator.ts` + both interceptors — all four read the marker; an old truthy check anywhere reopens the bypass (§13) |
 | `common/helpers/graphql-ws-context.helper.ts` | `common/services/core-tenant-context.registry.ts` + `core.module.ts` + `modules/tenant/core-tenant.guard.ts` — the context is useless without the resolver, and unreached without the `core.module.ts` wiring (§7) |
@@ -66,8 +67,21 @@ than none because it reads as protection.
 `common/plugins/mongoose-tenant.plugin.ts`, `common/services/core-s3.service.ts`,
 `modules/file/{core-file.service,file-metadata.helper,file-roles.helper}.ts`,
 `modules/tus/{core-tus.service,tus.constants,index}.ts`, `modules/user/inputs/core-user.input.ts`,
-`modules/user/core-user.service.ts`, `modules/tenant/core-tenant.helpers.ts`, and the three module
-READMEs (`file`, `tenant`, `tus`) plus `modules/file/INTEGRATION-CHECKLIST.md`.
+`modules/user/core-user.service.ts`,
+`modules/tenant/{core-tenant.helpers,core-tenant.module,core-tenant.service}.ts`, and the three
+module READMEs (`file`, `tenant`, `tus`) plus `modules/file/INTEGRATION-CHECKLIST.md`.
+
+`core-tenant.module.ts` and `core-tenant.service.ts` are easy to miss and both carry enforcement:
+`forRoot()` registers the role-scope source and asserts the vocabulary is coherent, and
+`core-tenant.service.ts` gains `assertAssignableMembershipRole()`, which refuses a membership role
+named after a system (`s_*`) or global-only role at assignment time (§5).
+
+The remaining changed files — `common/enums/role.enum.ts`,
+`common/decorators/{restricted,unified-field}.decorator.ts`, both interceptors
+(`check-security`, `response-model`), and all three guards
+(`modules/auth/guards/roles.guard.ts`, `modules/better-auth/better-auth-roles.guard.ts`,
+`modules/tenant/core-tenant.guard.ts`) — are the counterparts already named in the "Belongs with"
+column above. Take them with the new file they pair with.
 
 **Also worth taking:** `src/test/test.helper.ts` (subscription `connectionParams`, and a refused
 subscription now rejects instead of delivering an indistinguishable `null` — without it you cannot test

package/migration-guides/11.35.0-to-11.35.1.md

@@ -0,0 +1,152 @@
+# Migration Guide: 11.35.0 → 11.35.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None in signatures. One **client-visible** change: a refused upload now answers **400** instead of **500**, with Nest's standard error envelope instead of an internal-error one (§1) |
+| **Bugfixes** | `multerFileFilter` rejections finally map to a 4xx (§1). Seven documented helper names are reachable from the package root for the first time (§2). The file-access boot warning can no longer be fooled by a subclassed controller (§3) |
+| **Migration Effort** | Nothing to configure. Read §1 if a frontend, a test, or an alerting rule branches on the status or body of a rejected upload. **Read §3 if you subclass `CoreFileController` / `CoreFileResolver` and re-declare a member** — you may see a new warning at startup, and it is probably telling you something true |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.35.1
+pnpm run build
+pnpm test
+```
+
+No configuration change is required, and no source change is required in a typical project.
+
+**Vendor-mode projects:** §1 and §2 are single-file and independent —
+`src/core/common/helpers/file.helper.ts` and `src/index.ts`. §3 is **not**: it adds
+`src/core/modules/file/core-file-access-audit.initializer.ts` and changes
+`file-roles.config.ts`, `file-roles.helper.ts` and `core.module.ts` together. Taking the initializer
+without the `core.module.ts` provider registration gives you a file that is never constructed — a
+security check that silently does not run, which is worse than not having it. Sync those four
+together.
+
+---
+
+## 1. A refused upload answers 400, not 500
+
+11.32.4 §8 changed `multerFileFilter`'s rejection from a bare string to `new Error(...)`, intending a
+clean 400. It never produced one.
+
+`transformException` in `@nestjs/platform-express` returns any **non-`HttpException`** unchanged. Its
+switch matches only multer's own message constants (`LIMIT_FILE_SIZE`, `LIMIT_UNEXPECTED_FILE`, …),
+and a message this helper writes matches none of them — so the rejection fell off the end of the
+switch, reached Nest's exception layer as a plain error, and the client was told the **server** had
+failed for a file the **client** sent wrong.
+
+Both rejection paths are affected and both are fixed: the allow-list refusal, and the
+scriptable-type refusal (`text/html`, `image/svg+xml`) added by 11.32.4 §6.
+
+| | Before | After |
+|---|---|---|
+| Status | `500 Internal Server Error` | `400 Bad Request` |
+| Body | internal-error envelope | Nest's standard 400 shape |
+| Message text | unchanged | unchanged — same text, still built from the accept list |
+
+**What to check:**
+
+- **Frontends** that branch on the status of an upload response. A rejected file was previously
+  indistinguishable from a storage outage; it now identifies itself, and the message is worth showing
+  to the user.
+- **Tests** pinned to the broken output. A test asserting `500` on a refused upload fails and should
+  be updated to `400`.
+- **Alerting.** Refused uploads no longer raise 5xx. If a dashboard counted them, its numbers drop —
+  that is the fix, not a regression. Conversely, an alert that was tuned to tolerate that noise can
+  be tightened again.
+
+A consumer catching the rejection in code is unaffected: `BadRequestException extends HttpException
+extends Error`, so an `instanceof Error` check keeps working.
+
+---
+
+## 2. Seven documented helpers are now exported from the package root
+
+The 11.34.x → 11.35.x guide's *New Exports* block lists names that `src/index.ts` never exported, so
+importing them from `@lenne.tech/nest-server` failed to compile:
+
+| Name | Module |
+|---|---|
+| `resolveGuardRequest` | `common/helpers/execution-context-request.helper` |
+| `buildRequestContextAwareExecute` | `common/helpers/graphql-ws-context.helper` |
+| `buildRequestContextAwareSubscribe` | same |
+| `createRequestContextAwareExecute` | same |
+| `createRequestContextAwareSubscribe` | same |
+| `getTenantContextResolver` | `common/services/core-tenant-context.registry` |
+| `setTenantContextResolver` | same |
+
+Purely additive — three `export * from` lines. Nothing was renamed or removed, and no existing import
+changes meaning.
+
+**Who this affected:** npm-mode consumers only, and only those who followed the guide. In-tree and
+vendor-mode consumers import over relative paths and never touched the barrel, which is also why
+nothing in this repo noticed: no framework module, test or e2e spec imports from `src/index.ts`, so a
+helper could be written, wired, documented and shipped with the full suite green.
+`tests/unit/public-api-barrel.spec.ts` now reads the expected names out of the migration guides
+themselves and walks the re-export graph, so a documented-but-unexported name fails at test time
+rather than at a consumer's `import`.
+
+---
+
+## 3. The file-access warning now sees a subclassed controller
+
+The boot warning that reports "the file gate is open and nothing declares a per-file policy" read
+**configuration** — `file.downloadRoles` and friends. That is the correct source for a member you
+inherit, and the wrong one for a member you re-declare.
+
+```typescript
+@Controller('files')
+export class FileController extends CoreFileController {
+  @Get('id/:id')
+  @Roles(RoleEnum.S_EVERYONE)      // anonymous downloads
+  override async getFileById(...) { return super.getFileById(...); }
+}
+```
+
+`applyFileRoles()` writes the configured roles onto `CoreFileController.prototype.getFileById`, but
+decorator metadata lives on the **function object** — your override is a different function, it keeps
+its own `@Roles()`, and that is the function Nest registers. The configuration never reaches the
+route. The old warning asked `resolveRoles('downloadRoles', config)`, got `[ADMIN]`, and stayed quiet
+while the route served everyone. Two consumer projects shipped exactly that.
+
+`CoreFileAccessAuditInitializer` now reads the roles off the class you actually registered, at
+`onApplicationBootstrap` (the earliest point at which the route table exists), and names the member:
+
+```
+A registered file endpoint is open beyond platform admins through roles declared in your own class,
+not through configuration (FileController.getFileById → ["s_everyone"]), and no per-file policy is
+declared: file.access is unset and CoreFileService.checkRights() is not overridden. …
+```
+
+**Nothing changes about who may reach what.** Your `@Roles()` still wins; the audit reports and does
+not correct. That is deliberate: rewriting an override's metadata would silently relax a route a
+project pinned on purpose — which is why the TUS module's approach, where configuration wins over the
+override, was not adopted here.
+
+**What to do if the warning appears:**
+
+| If the open access is | Then |
+|---|---|
+| intended, with a per-file rule | declare it: `file.access: 'owner' \| 'tenant' \| …`, or override `CoreFileService.checkRights()`. Either silences the warning, for both halves of the check |
+| intended, genuinely public files | nothing is broken — but the warning is the reminder that ids are enumerable and the routes are not rate-limited |
+| **not** intended | inherit the member instead of re-declaring it, so `file.downloadRoles` governs it again |
+
+**No new warning if you do not subclass**, and none if you subclass without re-declaring a governed
+member — the audit only reports roles the configuration cannot account for, so it never duplicates
+the existing configuration-side warning.
+
+Governed members: `getFileById`, `getFile` (controller); `getFileInfo`, `uploadFile`, `uploadFiles`,
+`deleteFile` (resolver).
+
+---
+
+## Module Documentation
+
+- File module, upload filters and access rules: [`src/core/modules/file/README.md`](../src/core/modules/file/README.md)
+- Request lifecycle and exception handling: [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.35.0",
+  "version": "11.35.1",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/core/common/helpers/file.helper.ts

@@ -1,3 +1,4 @@
+import { BadRequestException } from '@nestjs/common';
 import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer-options.interface';
 import { randomBytes } from 'crypto';
 import { diskStorage, memoryStorage } from 'multer';
@@ -147,9 +148,14 @@ function normalizeMimeType(value: string): string {
  * `options.allowScriptableTypes` is set — that is what closes the hole for
  * expressions that already exist in consumer projects.
  *
- * Rejections are reported as a real `Error`. Passing a bare string (as this
- * helper did before) leaves multer with an "error" that has no `message`, which
- * NestJS's `transformException` cannot map to a 4xx.
+ * Rejections are reported as a `BadRequestException`, so the caller gets a 400
+ * with a readable reason. An `HttpException` is required, not merely tidier:
+ * NestJS's `transformException` returns any NON-`HttpException` unchanged — its
+ * switch matches only multer's own message constants (`LIMIT_FILE_SIZE`,
+ * `LIMIT_UNEXPECTED_FILE`, …), and a message written here matches none of them.
+ * A bare `new Error()` therefore still surfaced to the client as a 500, which
+ * reads as "the server broke" for what is in fact a refused file. See
+ * `tests/unit/file-upload-rejection-status.spec.ts`.
  */
 export function multerFileFilter(
   accept: RegExp | UploadAllowList = IMAGE_UPLOAD_ALLOW_LIST,
@@ -163,7 +169,7 @@ export function multerFileFilter(
       !options?.allowScriptableTypes &&
       (SCRIPTABLE_UPLOAD_MIME_TYPES.includes(mimeType) || SCRIPTABLE_UPLOAD_EXTENSIONS.includes(extension))
     ) {
-      return cb(new Error(`File upload rejected: ${mimeType || 'unknown type'} may execute as script`));
+      return cb(new BadRequestException(`File upload rejected: ${mimeType || 'unknown type'} may execute as script`));
     }
 
     const accepted =
@@ -174,7 +180,7 @@ export function multerFileFilter(
     if (accepted) {
       return cb(null, true);
     }
-    cb(new Error(`File upload only supports the following filetypes - ${describeAccept(accept)}`));
+    cb(new BadRequestException(`File upload only supports the following filetypes - ${describeAccept(accept)}`));
   };
 }
 

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

@@ -346,6 +346,16 @@ override async getFileById(@Param('id') id: string, @Res() res: Response) {
 A class-level `@Roles()` on your subclass cannot relax an inherited member either: the inherited
 function carries its own handler-level roles, and the two are unioned rather than overridden.
 
+> **Boot reports this, since 11.35.1 — but it only reports.** `CoreFileAccessAuditInitializer` reads
+> the roles off the class you actually registered and warns when a member is open beyond platform
+> admins for a reason the configuration cannot explain. So a subclass whose `getFileById()` carries
+> `@Roles(RoleEnum.S_EVERYONE)` is now named at startup, with the member and the offending roles.
+>
+> It does **not** correct anything: your `@Roles()` still wins, because overwriting it would silently
+> relax a route you may have pinned on purpose. **If you re-declare a download member, its `@Roles()`
+> is your whole audience gate** — the warning tells you so, it does not close it for you. Inherit the
+> member instead if you want `file.downloadRoles` to govern it.
+
 ### If you override `getFileInfo()`: `GET /files/id/:id` no longer calls it (11.33.0)
 
 Up to 11.32.x, `GET /files/id/:id` called the public `CoreFileService.getFileInfo()` and then let

package/src/core/modules/file/core-file-access-audit.initializer.ts

@@ -0,0 +1,164 @@
+import { Injectable, Logger, OnApplicationBootstrap, Optional } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+
+import { ConfigService } from '../../common/services/config.service';
+import { CoreFileController } from './core-file.controller';
+import { CoreFileResolver } from './core-file.resolver';
+import { CoreFileService } from './core-file.service';
+import {
+  FILE_ROLE_MEMBERS,
+  FileEndpointClassName,
+  ObservedFileHandler,
+  warnOnUndecidedEffectiveFileAccess,
+} from './file-roles.config';
+
+/**
+ * Audits the file endpoints a project ACTUALLY registered, and warns when one of them is open beyond
+ * platform admins for a reason the configuration cannot show.
+ *
+ * WHY THIS CANNOT LIVE WHERE THE OTHER FILE WARNINGS LIVE
+ * -------------------------------------------------------
+ * `warnOnUndecidedFileAccess()` runs in the `CoreFileService` constructor and reads CONFIGURATION.
+ * For an inherited member that is exactly right: `applyFileRoles()` writes the configured roles onto
+ * the base-class function, the subclass picks them up through the prototype chain, and configuration
+ * and reality agree.
+ *
+ * They stop agreeing when a project RE-DECLARES a member. Decorator metadata lives on the function
+ * object, so an override is a different function carrying its own `@Roles()` — and that is the
+ * function Nest registers. Answering "is the gate open?" from configuration then answers a question
+ * about a route that is not the one being served. Two consumer projects shipped anonymously readable
+ * downloads that way, and nothing said a word.
+ *
+ * Seeing the real answer needs the registered class, and the registered class only exists once Nest
+ * has built its route table. Neither the service constructor nor `CoreModule.forRoot()` — which runs
+ * before any of that — can reach it. Hence a provider, and hence `onApplicationBootstrap`.
+ *
+ * WHY DISCOVERY RATHER THAN A CONFIG OPTION
+ * ------------------------------------------
+ * The file module ships abstract classes only: there is no `CoreFileModule.forRoot()` to hand a class
+ * to, and a class reference cannot travel through `config.env.ts` (it has to survive
+ * `NEST_SERVER_CONFIG` / `NSC__*`, i.e. JSON). Asking every consumer to register their controller in
+ * a second place would also make the audit opt-in — and an opt-in audit is missing precisely where
+ * nobody thought about access control, which is the population it exists for.
+ *
+ * WARNING ONLY. It never changes a role, and deliberately so: rewriting an override's metadata would
+ * silently relax a route the project pinned on purpose, which is the trap that rules out adopting the
+ * TUS module's approach here. The audit reports; the project decides.
+ *
+ * Registered as a `CoreModule` provider; consumers never interact with it.
+ */
+@Injectable()
+export class CoreFileAccessAuditInitializer implements OnApplicationBootstrap {
+  protected readonly logger = new Logger(CoreFileAccessAuditInitializer.name);
+
+  constructor(@Optional() protected readonly discoveryService?: DiscoveryService) {}
+
+  onApplicationBootstrap(): void {
+    if (!this.discoveryService) {
+      return;
+    }
+
+    const handlers = this.collectHandlers();
+    // No file endpoint registered — there is no route to be wrong about, and the configuration-side
+    // warning in the service constructor already covers a service-only integration.
+    if (!handlers.length) {
+      return;
+    }
+
+    const config = ConfigService.configFastButReadOnly;
+    warnOnUndecidedEffectiveFileAccess({
+      fileConfig: config?.file,
+      handlers,
+      hasPerFileRule: this.hasPerFileRule(),
+      multiTenancyEnabled: !!config?.multiTenancy && config.multiTenancy.enabled !== false,
+    });
+  }
+
+  /**
+   * The effective roles of every known member on every registered file endpoint class.
+   *
+   * `proto[method]` resolves through the prototype chain, so it yields the OVERRIDE when there is one
+   * and the inherited base function otherwise — which is exactly the function Nest registered.
+   */
+  protected collectHandlers(): ObservedFileHandler[] {
+    const handlers: ObservedFileHandler[] = [];
+
+    for (const [className, target] of this.registeredEndpointClasses()) {
+      for (const member of FILE_ROLE_MEMBERS) {
+        if (member.className !== className) {
+          continue;
+        }
+
+        const fn = (target.prototype as Record<string, unknown>)?.[member.method];
+        if (typeof fn !== 'function') {
+          continue;
+        }
+
+        handlers.push({
+          key: member.key,
+          member: `${target.name}.${member.method}`,
+          roles: this.effectiveRoles(fn, target),
+        });
+      }
+    }
+
+    return handlers;
+  }
+
+  /**
+   * The union the guards will compute for a member.
+   *
+   * Mirrors `mergeRolesMetadata([handlerRoles, classRoles])`: both halves count, so a class-level
+   * `@Roles()` on the subclass is seen too. `Reflect.getMetadata` walks the prototype chain for the
+   * class, which is what makes an undecorated subclass inherit the core `@Roles(ADMIN)` — the same
+   * resolution Nest's `Reflector` performs.
+   */
+  protected effectiveRoles(fn: unknown, target: Function): string[] {
+    const handlerRoles: string[] = Reflect.getMetadata('roles', fn as object) ?? [];
+    const classRoles: string[] = Reflect.getMetadata('roles', target) ?? [];
+    return [...handlerRoles, ...classRoles];
+  }
+
+  /** Whether the registered `CoreFileService` overrides `checkRights()` — the project wrote a rule. */
+  protected hasPerFileRule(): boolean {
+    const services = (this.discoveryService?.getProviders() ?? [])
+      .map((wrapper) => wrapper.instance)
+      .filter((instance): instance is CoreFileService => instance instanceof CoreFileService);
+
+    return services.some((service) => (service as any).checkRights !== (CoreFileService.prototype as any).checkRights);
+  }
+
+  /**
+   * Every registered class that IS one of the two file endpoint classes, deduplicated.
+   *
+   * Read off the instance rather than the wrapper's `metatype`, because that is the object whose
+   * prototype chain answers the `instanceof` question reliably for both controllers and providers.
+   */
+  protected registeredEndpointClasses(): [FileEndpointClassName, Function][] {
+    const found = new Map<Function, FileEndpointClassName>();
+
+    const consider = (instance: unknown): void => {
+      if (!instance || typeof instance !== 'object') {
+        return;
+      }
+      const target = (instance as object).constructor;
+      if (typeof target !== 'function' || found.has(target)) {
+        return;
+      }
+      if (instance instanceof CoreFileController) {
+        found.set(target, 'CoreFileController');
+      } else if (instance instanceof CoreFileResolver) {
+        found.set(target, 'CoreFileResolver');
+      }
+    };
+
+    for (const wrapper of this.discoveryService?.getControllers() ?? []) {
+      consider(wrapper.instance);
+    }
+    for (const wrapper of this.discoveryService?.getProviders() ?? []) {
+      consider(wrapper.instance);
+    }
+
+    return [...found].map(([target, className]) => [className, target]);
+  }
+}

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

@@ -36,6 +36,31 @@ export const FILE_ROLE_DEFAULTS: Record<FileRoleKey, string[]> = {
   uploadRoles: [RoleEnum.ADMIN],
 };
 
+/**
+ * Which endpoint member each knob governs, by NAME only.
+ *
+ * Deliberately strings rather than function references: this file must stay a leaf that imports
+ * nothing but enums and interfaces (see the header), and both consumers need the same list —
+ * `applyFileRoles()` writes metadata onto these members, and the boot audit reads it back off
+ * whichever class the project actually registered. Two hand-maintained copies of that list is
+ * exactly how one of them ends up governing a member the other forgot.
+ *
+ * `getFileInfo` rides with `downloadRoles` rather than getting its own knob: it answers filename,
+ * size and content type for a blob, which is the metadata half of a download. Splitting it would let
+ * a project accidentally publish the bucket's contents list while believing downloads were closed.
+ */
+export const FILE_ROLE_MEMBERS: { className: FileEndpointClassName; key: FileRoleKey; method: string }[] = [
+  { className: 'CoreFileController', key: 'downloadRoles', method: 'getFileById' },
+  { className: 'CoreFileController', key: 'downloadRoles', method: 'getFile' },
+  { className: 'CoreFileResolver', key: 'downloadRoles', method: 'getFileInfo' },
+  { className: 'CoreFileResolver', key: 'uploadRoles', method: 'uploadFile' },
+  { className: 'CoreFileResolver', key: 'uploadRoles', method: 'uploadFiles' },
+  { className: 'CoreFileResolver', key: 'deleteRoles', method: 'deleteFile' },
+];
+
+/** The two core endpoint classes the role knobs govern. */
+export type FileEndpointClassName = 'CoreFileController' | 'CoreFileResolver';
+
 /**
  * Resolve one knob to the role list that will actually be applied.
  *
@@ -62,6 +87,21 @@ export function resolveRoles(key: FileRoleKey, config?: IFileConfig): string[] {
   return configured;
 }
 
+/**
+ * Did somebody DECLARE the per-file policy?
+ *
+ * Shared by both file-access warnings on purpose. They must silence on exactly the same conditions,
+ * and two copies of that rule is how a third silencer gets added to one and forgotten in the other —
+ * at which point the boot audit starts firing on a project that did decide, gets muted, and protects
+ * nobody. Keeping it in one place makes that particular drift impossible rather than merely unlikely.
+ *
+ * `'custom'` does not count: it is the escape hatch that says "I will answer this in code", so the
+ * only evidence that somebody actually did is an overridden `checkRights()`.
+ */
+export function hasDeclaredFilePolicy(options: { fileConfig?: IFileConfig; hasPerFileRule: boolean }): boolean {
+  return options.hasPerFileRule || !!(options.fileConfig?.access && options.fileConfig.access !== 'custom');
+}
+
 /**
  * Warn when presigned S3 downloads are combined with a restricted `downloadRoles`.
  *
@@ -152,6 +192,15 @@ export function warnOnPresignedDownloadsWithRestrictedRoles(
  * public logos, and refusing to start on a configuration that is correct for the second would be
  * wrong. What it can do is refuse to be silent.
  *
+ * SCOPE — this function reads CONFIGURATION, which is the right source for a member the project
+ * INHERITS: `applyFileRoles()` writes the configured roles onto the base-class function, the subclass
+ * picks them up through the prototype chain, and config and reality agree. It says nothing about a
+ * member the project RE-DECLARES, because an override is a different function carrying its own
+ * `@Roles()` and the configuration never reaches that route. That half is covered by
+ * {@link warnOnUndecidedEffectiveFileAccess}, driven from `CoreFileAccessAuditInitializer` at
+ * bootstrap — the earliest point at which the registered class exists. The two do not overlap: the
+ * audit reports only roles this function's source cannot account for.
+ *
  * @param hasPerFileRule whether `CoreFileService.checkRights()` is overridden — the caller knows,
  *   because it has the instance; this helper stays a pure function so it can be unit-tested.
  * @returns the message, or `undefined` when there is nothing to warn about. Returned as well as
@@ -166,7 +215,7 @@ export function warnOnUndecidedFileAccess(options: {
   const { fileConfig, hasPerFileRule, multiTenancyEnabled } = options;
 
   // (1) and (2): somebody decided.
-  if (hasPerFileRule || (fileConfig?.access && fileConfig.access !== 'custom')) {
+  if (hasDeclaredFilePolicy({ fileConfig, hasPerFileRule })) {
     return undefined;
   }
 
@@ -200,3 +249,109 @@ export function warnOnUndecidedFileAccess(options: {
   logger.warn(message);
   return message;
 }
+
+/**
+ * One registered endpoint member, as the GUARDS will see it.
+ *
+ * `roles` is the union of handler-level and class-level metadata, because that is what
+ * `mergeRolesMetadata` computes — not the handler alone. A subclass that carries a class-level
+ * `@Roles(S_EVERYONE)` widens every member it declares, and reading only the handler would miss it.
+ */
+export interface ObservedFileHandler {
+  /** which knob governs this member */
+  key: FileRoleKey;
+  /** `'FileController.getFileById'` — named as REGISTERED, so the operator can go straight to it */
+  member: string;
+  /** the effective role union the guards will evaluate */
+  roles: string[];
+}
+
+/**
+ * Warn when a REGISTERED file endpoint is open beyond platform admins for a reason the configuration
+ * does not explain — i.e. a `@Roles()` written in the project's own subclass.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM {@link warnOnUndecidedFileAccess}. That one reads CONFIGURATION,
+ * which is the right source for the inherited case: `applyFileRoles()` writes the configured roles
+ * onto the base-class member, an inheriting subclass picks them up through the prototype chain, and
+ * config and reality agree. They stop agreeing the moment a project RE-DECLARES a member. Decorator
+ * metadata lives on the function object, so an override is a different function carrying its own
+ * roles — and that is the function Nest registers. The configuration never reaches the route.
+ *
+ * The consequence was a silence exactly where the noise was wanted: a subclassed `getFileById()` with
+ * `@Roles(RoleEnum.S_EVERYONE)` serves anonymous downloads while `resolveRoles('downloadRoles', …)`
+ * still answers `[ADMIN]`. Two independent consumer projects shipped that, and in both the actually
+ * open routes were the ones nothing reported. A warning that is quiet in the dangerous case and loud
+ * in the safe one is worse than no warning, because it reads as a clean bill of health.
+ *
+ * WHAT IT REPORTS — only roles the configuration does not account for:
+ *
+ *   effective = union(handler roles, class roles)      // what mergeRolesMetadata gives the guard
+ *   unexplained = effective − {ADMIN} − configured(key)
+ *
+ * That subtraction is what keeps this from double-warning. When the widening came from
+ * `file.downloadRoles`, {@link warnOnUndecidedFileAccess} has already said so and `unexplained` is
+ * empty. When an override widens FURTHER than the configuration does, only the extra roles are
+ * named — the part that is genuinely invisible elsewhere.
+ *
+ * ADMIN is subtracted because both endpoint classes carry a class-level `@Roles(ADMIN)` that the
+ * guards union in unconditionally. It is present on every member and never widens anything.
+ *
+ * The silencers are deliberately identical to {@link warnOnUndecidedFileAccess} — an overridden
+ * `checkRights()` or a declared `file.access` means somebody decided, and how they decided is beyond
+ * what a boot check can grade. A warning that fires on a correct setup gets muted, and a muted
+ * warning protects nobody.
+ *
+ * @returns the message, or `undefined` when there is nothing to report. Returned as well as logged
+ *   for the same reason as the other two warnings: the message IS the contract, and a module-private
+ *   Logger cannot be asserted against from a unit test.
+ */
+export function warnOnUndecidedEffectiveFileAccess(options: {
+  fileConfig?: IFileConfig;
+  handlers: ObservedFileHandler[];
+  hasPerFileRule: boolean;
+  multiTenancyEnabled: boolean;
+}): string | undefined {
+  const { fileConfig, handlers, hasPerFileRule, multiTenancyEnabled } = options;
+
+  // Somebody decided. The SAME predicate the configuration-side warning uses — see
+  // hasDeclaredFilePolicy() for why this must not be a second copy of the rule.
+  if (hasDeclaredFilePolicy({ fileConfig, hasPerFileRule })) {
+    return undefined;
+  }
+
+  const findings: string[] = [];
+  for (const handler of handlers) {
+    const configured = resolveRoles(handler.key, fileConfig);
+    const unexplained = handler.roles.filter((role) => role !== RoleEnum.ADMIN && !configured.includes(role));
+    if (unexplained.length) {
+      findings.push(`${handler.member} → ${JSON.stringify([...new Set(unexplained)])}`);
+    }
+  }
+
+  if (!findings.length) {
+    return undefined;
+  }
+
+  const tenantNote = multiTenancyEnabled
+    ? ' multiTenancy is active, and the leak crosses tenants too: the file stores are reached outside ' +
+      'Mongoose, so mongooseTenantPlugin never scopes them and these role names resolve against ' +
+      'user.roles — a GLOBAL attribute — never against membership.role.'
+    : '';
+
+  const message =
+    `A registered file endpoint is open beyond platform admins through roles declared in your own ` +
+    `class, not through configuration (${findings.join(', ')}), and no per-file policy is declared: ` +
+    `file.access is unset and CoreFileService.checkRights() is not overridden. Because the member is ` +
+    `RE-DECLARED, file.downloadRoles/uploadRoles/deleteRoles do NOT apply to it — decorator metadata ` +
+    `lives on the function object, so your override keeps its own @Roles() and the configuration ` +
+    `never reaches the route. Every holder of such a role can therefore read, overwrite or delete ` +
+    `EVERY file — and file ids are not secret, they are ENUMERABLE (an ObjectId shares a per-process ` +
+    `random part and an incrementing counter, so one own upload reveals the neighbourhood), with no ` +
+    `rate limit on the file routes.${tenantNote} Either inherit the member instead of re-declaring ` +
+    `it, so the knobs apply, or declare the per-file policy with file.access ` +
+    `('public' | 'authenticated' | 'owner' | 'tenant') or an overridden checkRights() — see ` +
+    `src/core/modules/file/README.md § Access control.`;
+
+  logger.warn(message);
+  return message;
+}