@lenne.tech/nest-server 11.42.12 → 11.42.13

package/docs/REQUEST-LIFECYCLE.md

@@ -167,7 +167,7 @@ JWT-based authentication for existing projects:
 | **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
 | **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
 | **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
-| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })`. Configured by `TusModule.forRoot({ config })`, else the server config's `tus` key (11.42.9+). Switched-off `creation` / `termination` answer 501 (enforced by `CoreTusService`, not `@tus/server`); upload URLs follow the path the upload was created at |
+| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })`. Configured by `TusModule.forRoot({ config })`, else the server config's `tus` key (11.42.9+). Switched-off `creation` / `termination` answer 501 (enforced by `CoreTusService`, not `@tus/server`); upload URLs follow the path the upload was created at. The response that completes an upload carries the stored file's ID as `X-File-Id` (11.42.13+, listed in `Access-Control-Expose-Headers`) — the last segment of the TUS URL is the upload id, not the file id |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |
 

package/docs/error-codes.md

@@ -162,6 +162,76 @@ All error codes follow the format: `#PREFIX_XXXX: Description`
 
 ---
 
+### LTNS_0103: notTenantMember
+
+**Message:** Not a member of this tenant
+
+**Description:** Thrown by the CoreTenantGuard when the `X-Tenant-Id` header names a tenant the user has no active membership in
+
+**Solution:** Send the header of a tenant the user belongs to, or add the membership
+
+**Translations:**
+- DE: Sie sind kein Mitglied dieses Mandanten.
+- EN: You are not a member of this tenant.
+
+---
+
+### LTNS_0104: insufficientTenantRole
+
+**Message:** Insufficient tenant role
+
+**Description:** Thrown by the CoreTenantGuard when the membership role in the header's tenant does not satisfy the required tenant role
+
+**Solution:** Raise the membership role or use an endpoint with a lower requirement
+
+**Translations:**
+- DE: Ihre Rolle in diesem Mandanten reicht für diese Aktion nicht aus.
+- EN: Your role in this tenant does not allow this action.
+
+---
+
+### LTNS_0105: insufficientRole
+
+**Message:** Insufficient role
+
+**Description:** Thrown by the CoreTenantGuard when `user.roles` does not meet the required role — without a tenant header, or on a `@SkipTenantCheck` route
+
+**Solution:** Grant the role, or send the tenant header so the membership role is checked
+
+**Translations:**
+- DE: Ihre Rolle reicht für diese Aktion nicht aus.
+- EN: Your role does not allow this action.
+
+---
+
+### LTNS_0106: tenantInactive
+
+**Message:** Tenant is inactive
+
+**Description:** Thrown by the CoreTenantGuard when `multiTenancy.isTenantActive` reports the header's tenant as switched off
+
+**Solution:** Reactivate the tenant, then call `invalidateTenant(tenantId)`
+
+**Translations:**
+- DE: Dieser Mandant ist deaktiviert.
+- EN: This tenant is deactivated.
+
+---
+
+### LTNS_0107: verificationRequired
+
+**Message:** Verification required
+
+**Description:** Thrown by the CoreTenantGuard on an `S_VERIFIED` endpoint for a user who is not verified
+
+**Solution:** Complete the verification of the account
+
+**Translations:**
+- DE: Für diese Aktion muss Ihr Konto verifiziert sein.
+- EN: Your account must be verified for this action.
+
+---
+
 ## User Errors (LTNS_0200-LTNS_0299)
 
 ### LTNS_0200: emailAlreadyExists

package/migration-guides/11.42.12-to-11.42.13.md

@@ -0,0 +1,154 @@
+# Migration Guide: 11.42.12 → 11.42.13
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | `CoreTenantGuard` refusals carry translatable error codes (§1); `GET /files/id/:id` answers 404 instead of 500 for an id that is not an ObjectId (§3) |
+| **New Features**     | A finished TUS upload names the stored file in the `X-File-Id` response header (§2)                      |
+| **Framework API**    | Additive only: `ErrorCode.NOT_TENANT_MEMBER` … `VERIFICATION_REQUIRED` (`LTNS_0103`–`LTNS_0107`), `TUS_FILE_ID_HEADER`, `CoreFileService.isMalformedFileId()` (protected) |
+| **Dependencies**     | None for the package                                                                                     |
+| **Breaking Changes** | None. Status codes and access decisions are unchanged; only the message text of five tenant refusals gains a prefix (§1) |
+| **Migration Effort** | None for most projects. Check §1 if you compare a tenant refusal message for exact equality, and §2 if your frontend derives a file id from the TUS URL |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. No code or configuration change is required unless one of
+the checks below applies to you.
+
+## 1. Tenant guard refusals are translatable
+
+Five of the guard's 403 refusals were thrown as plain English strings. Without the `#LTNS_XXXX:` prefix the
+frontend error translation could not map them, so users saw the raw English text in a toast.
+
+| Code        | Message (unchanged wording)   | Refused because                                                                          |
+| ----------- | ----------------------------- | ---------------------------------------------------------------------------------------- |
+| `LTNS_0103` | `Not a member of this tenant` | the tenant header names a tenant the user has no active membership in                     |
+| `LTNS_0104` | `Insufficient tenant role`    | the membership role does not satisfy the required tenant role                             |
+| `LTNS_0105` | `Insufficient role`           | `user.roles` does not meet the required role (no header, or a `@SkipTenantCheck` route)   |
+| `LTNS_0106` | `Tenant is inactive`          | `multiTenancy.isTenantActive` reports the header's tenant as switched off                 |
+| `LTNS_0107` | `Verification required`       | an `S_VERIFIED` endpoint, and the user is not verified                                    |
+
+The response `message` is now e.g. `#LTNS_0103: Not a member of this tenant`. Status code (403), exception class
+and the decision itself are unchanged. German and English translations ship in the error catalog
+(`GET /i18n/errors/:locale`), so `nuxt-extensions` translates them without any change.
+
+**What to check:**
+
+- **You compare the message for exact equality** (`toBe('Insufficient role')`, `message === '…'`): switch to a
+  substring match or, better, to the code:
+
+  ```typescript
+  // Before
+  expect(res.body.message).toBe('Not a member of this tenant');
+
+  // After
+  expect(res.body.message).toBe(ErrorCode.NOT_TENANT_MEMBER);
+  // or, tolerant of both versions
+  expect(res.body.message).toContain('Not a member of this tenant');
+  ```
+
+  Substring matches (`toContain`, log filters) keep working unchanged — the original wording stays behind the
+  code.
+- **Your product does not call them tenants:** override the translations in your own error registry
+  (`errorCode.additionalErrorRegistry`). It is registered after the core, and translations are merged per code,
+  so your entry for `LTNS_0103` wins.
+
+## 2. A finished TUS upload names the stored file (`X-File-Id`)
+
+Until now a client knew only the TUS URL after an upload. Its last segment is the TUS **upload** id — a key of the
+staging store, not of the file store — and `/files/id/<upload-id>` cannot answer with the file. The response that
+completes an upload now carries the ID of the stored file:
+
+```
+HTTP/1.1 204 No Content
+Upload-Offset: 52428800
+X-File-Id: 6720c1f0a2b4c8e9d0f1a2b3
+Access-Control-Expose-Headers: …, X-File-Id
+```
+
+- Sent on the completing request only: the last `PATCH`, or the `POST` of a creation-with-upload. Creation and
+  partial `PATCH`es store nothing yet and carry no header.
+- Listed in `Access-Control-Expose-Headers`, so a browser on a separate app origin can read it.
+- The name is exported as `TUS_FILE_ID_HEADER`.
+
+With `tus-js-client`:
+
+```typescript
+let fileId: string | undefined;
+const upload = new Upload(file, {
+  endpoint: '/tus',
+  onAfterResponse: (_req, res) => {
+    const id = res.getHeader('X-File-Id');
+    if (id) {
+      fileId = id;
+    }
+  },
+  onSuccess: () => {
+    // use `/files/id/${fileId}` — NOT the last segment of `upload.url`
+  },
+});
+```
+
+**What to check:**
+
+- **Your frontend takes the last segment of the TUS URL as the file id:** read `X-File-Id` instead. Treat a
+  missing header (an older server, see the next point) as "no file id known" — never fall back to the URL.
+- **You override `onUploadComplete()`:** nothing to change as long as the override calls
+  `super.onUploadComplete(upload)` with the `upload` it received — both `await super…` and `return super…` keep
+  compiling and keep the header. An override that never calls `super` (it stores the file itself) completes the
+  upload without `X-File-Id`. The method's signature did not change.
+
+## 3. `GET /files/id/:id` answers 404 for an id that is not an ObjectId
+
+An id that is not a 24-character hex string — typically a TUS upload id (32 hex characters) taken for the file id,
+see §2 — reached `new ObjectId()` and threw a `BSONError`, so the route answered **500**. It now answers exactly
+like an unknown id: `404` with `ErrorCode.FILE_NOT_FOUND`.
+
+The guard sits in `CoreFileService` (`getFileInfo`, `resolveFile`, `getFileStream`, `getBuffer`,
+`getDownloadUrl`, `getRawFileInfo`, `deleteFile`, `duplicateById`), so every route built on those methods
+benefits — including a project's own `GET /files/info/:id` / `DELETE /files/:id`. Only strings are judged; an
+`ObjectId` instance keeps its previous path.
+
+**What to check:**
+
+- **Your files use ids that are not ObjectIds** (unusual — every core store keys by ObjectId): override the new
+  protected `isMalformedFileId(id)` in your `FileService` to accept them.
+- **A monitor or test expected the 500:** it now gets 404.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| npm-mode and vendor-mode projects without tenant-message comparisons or TUS overrides | Nothing to do |
+| Tests or frontends matching tenant refusals with `toContain` / a substring | Compatible |
+| Tests comparing a tenant refusal message with `toBe` / `===` | Compare against `ErrorCode.*` (§1) |
+| `TusService extends CoreTusService` overriding `onUploadComplete()` and calling `super` | Compatible, header included |
+| `onUploadComplete()` override that does not call `super` | Compatible, no `X-File-Id` (§2) |
+| `FileService extends CoreFileService` with a `checkRights()` that reads `getRawFileInfo()` | Compatible; a malformed id now reaches it as `null` |
+
+## Troubleshooting
+
+**The browser never sees `X-File-Id` although the server sends it**
+The header is exposed by the tus server itself. If a proxy rewrites `Access-Control-Expose-Headers`, add
+`X-File-Id` there as well.
+
+**`X-File-Id` is missing on the completing response**
+Check for an `onUploadComplete()` override that does not call `super.onUploadComplete(upload)`, or that passes it a
+copy of `upload` (§2).
+
+**A tenant refusal shows in English although the frontend translates errors**
+The frontend translation loads the catalog from `GET /i18n/errors/:locale`. Make sure the error-code module is
+registered (it is by default) and the catalog contains `LTNS_0103`–`LTNS_0107`.
+
+## Module Documentation
+
+- [Tenant module README](../src/core/modules/tenant/README.md) — "Refusal Codes"
+- [Error codes](../docs/error-codes.md) — `LTNS_0103`–`LTNS_0107`
+- [TUS module README](../src/core/modules/tus/README.md) — "The ID of the Stored File", "Custom Upload Handler"
+- [TUS integration checklist](../src/core/modules/tus/INTEGRATION-CHECKLIST.md)
+- [File module README](../src/core/modules/file/README.md) — "Error responses"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.12",
+  "version": "11.42.13",
   "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",
@@ -213,7 +213,7 @@
     "oxfmt": "0.71.0",
     "oxlint": "1.87.0",
     "rimraf": "6.1.3",
-    "smtp-server": "3.19.19",
+    "smtp-server": "3.19.21",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "tsx": "4.23.15",

package/src/core/modules/error-code/error-codes.ts

@@ -373,6 +373,55 @@ export const LtnsErrors = {
     },
   },
 
+  // CoreTenantGuard refusals (LTNS_0103-LTNS_0107). Each `message` is the guard's original
+  // plain-string wording, kept verbatim: consumers match on it, and the `#CODE: ` prefix keeps a
+  // substring match working. The code is what makes the refusal translatable at all.
+
+  NOT_TENANT_MEMBER: {
+    code: 'LTNS_0103',
+    message: 'Not a member of this tenant',
+    translations: {
+      de: 'Sie sind kein Mitglied dieses Mandanten.',
+      en: 'You are not a member of this tenant.',
+    },
+  },
+
+  INSUFFICIENT_TENANT_ROLE: {
+    code: 'LTNS_0104',
+    message: 'Insufficient tenant role',
+    translations: {
+      de: 'Ihre Rolle in diesem Mandanten reicht für diese Aktion nicht aus.',
+      en: 'Your role in this tenant does not allow this action.',
+    },
+  },
+
+  INSUFFICIENT_ROLE: {
+    code: 'LTNS_0105',
+    message: 'Insufficient role',
+    translations: {
+      de: 'Ihre Rolle reicht für diese Aktion nicht aus.',
+      en: 'Your role does not allow this action.',
+    },
+  },
+
+  TENANT_INACTIVE: {
+    code: 'LTNS_0106',
+    message: 'Tenant is inactive',
+    translations: {
+      de: 'Dieser Mandant ist deaktiviert.',
+      en: 'This tenant is deactivated.',
+    },
+  },
+
+  VERIFICATION_REQUIRED: {
+    code: 'LTNS_0107',
+    message: 'Verification required',
+    translations: {
+      de: 'Für diese Aktion muss Ihr Konto verifiziert sein.',
+      en: 'Your account must be verified for this action.',
+    },
+  },
+
   // =====================================================
   // User Errors (LTNS_0200-LTNS_0299)
   // =====================================================

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

@@ -458,6 +458,7 @@ export class FileController extends CoreFileController {
 | Situation                                                                              | Status | Body                                                                                                                                                                                 |
 | -------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Unknown id / filename, or `checkRights()` refused                                      | `404`  | `NotFoundException` with `ErrorCode.FILE_NOT_FOUND`                                                                                                                                  |
+| An id that is not 24 hex characters (e.g. a TUS upload id taken for the file id)       | `404`  | Same as an unknown id — the service answers `null` / `NotFoundException` before any lookup. Up to 11.42.12 `new ObjectId()` threw and the route answered `500`                       |
 | `deleteFile()` / `deleteFileByName()` / `duplicate*()` on a file that is not there     | `404`  | `NotFoundException`. Both halves of each id/name pair answer identically — up to 11.33.1 the by-id delete surfaced the driver's `MongoRuntimeError` as a `500`                       |
 | Missing id / filename in the route                                                     | `400`  | `BadRequestException` with `ErrorCode.REQUIRED_FIELD_MISSING`                                                                                                                        |
 | An upload's SOURCE stream fails (client aborts, staged read drops)                     | `500`  | The promise rejects with the cause — under **every** driver. It used to be an uncaught exception (i.e. a process exit) on GridFS, and on the S3 streaming path tus finalization uses |

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

@@ -139,6 +139,21 @@ export abstract class CoreFileService {
     return this.storageDriver === 'filesystem';
   }
 
+  /**
+   * Whether `id` is a string that cannot name a stored file at all.
+   *
+   * Every store keys files by an ObjectId, so a string that is not 24 hex characters — a TUS upload
+   * id (which clients took for the file id), a filename, a typo in a URL — names no file. It is
+   * answered exactly like an unknown id. Handed to `new ObjectId()` it threw a BSONError instead,
+   * and `GET /files/id/<tus-upload-id>` answered 500 where an unknown id gets 404.
+   *
+   * Only strings are judged: anything else keeps its previous path, so an ObjectId from a second
+   * copy of `bson` (where `instanceof` fails) is not suddenly reported as missing.
+   */
+  protected isMalformedFileId(id: unknown): boolean {
+    return typeof id === 'string' && !(id.length === 24 && Types.ObjectId.isValid(id));
+  }
+
   /**
    * Find the filesystem metadata of a file by ID (null when it is stored elsewhere)
    */
@@ -264,6 +279,9 @@ export abstract class CoreFileService {
    * @returns the id of the copy
    */
   async duplicateById(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions): Promise<string> {
+    if (this.isMalformedFileId(id)) {
+      throw new NotFoundException(`File not found with id ${id}`);
+    }
     const objectId = getObjectIds(id);
     const source = await this.getFileInfo(objectId, serviceOptions);
     if (!source) {
@@ -425,6 +443,9 @@ export abstract class CoreFileService {
    * Get info about file via file ID
    */
   async getFileInfo(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions): Promise<CoreFileInfo> {
+    if (this.isMalformedFileId(id)) {
+      return null;
+    }
     if (!(await this.checkRights(id, { ...serviceOptions, checkInputType: 'id' }))) {
       return null;
     }
@@ -459,6 +480,9 @@ export abstract class CoreFileService {
     serviceOptions?: FileServiceOptions,
     knownStore?: FileStorageDriver,
   ): Promise<Readable> {
+    if (this.isMalformedFileId(id)) {
+      return null;
+    }
     if (!(await this.checkRights(id, { ...serviceOptions, checkInputType: 'id' }))) {
       return null;
     }
@@ -515,6 +539,9 @@ export abstract class CoreFileService {
     id: string | Types.ObjectId,
     serviceOptions?: FileServiceOptions,
   ): Promise<{ info: CoreFileInfo; store: FileStorageDriver } | null> {
+    if (this.isMalformedFileId(id)) {
+      return null;
+    }
     if (!(await this.checkRights(id, { ...serviceOptions, checkInputType: 'id' }))) {
       return null;
     }
@@ -552,6 +579,9 @@ export abstract class CoreFileService {
    * disabled — callers then fall back to streaming the file themselves.
    */
   async getDownloadUrl(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions): Promise<string | undefined> {
+    if (this.isMalformedFileId(id)) {
+      return undefined;
+    }
     if (!(await this.checkRights(id, { ...serviceOptions, checkInputType: 'id' }))) {
       return undefined;
     }
@@ -600,6 +630,9 @@ export abstract class CoreFileService {
    * Get file buffer (for small files) via file ID
    */
   async getBuffer(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions): Promise<Buffer> {
+    if (this.isMalformedFileId(id)) {
+      return null;
+    }
     if (!(await this.checkRights(id, { ...serviceOptions, checkInputType: 'id' }))) {
       return null;
     }
@@ -652,6 +685,9 @@ export abstract class CoreFileService {
    * exact input, so a `null` here is genuinely a missing file.
    */
   async deleteFile(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions): Promise<CoreFileInfo> {
+    if (this.isMalformedFileId(id)) {
+      throw new NotFoundException(`File not found with id ${id}`);
+    }
     if (!(await this.checkRights(id, { ...serviceOptions, checkInputType: 'id' }))) {
       return null;
     }
@@ -748,6 +784,9 @@ export abstract class CoreFileService {
    * @returns the raw document, or null when no file has that id
    */
   protected async getRawFileInfo(id: string | Types.ObjectId): Promise<null | Record<string, any>> {
+    if (this.isMalformedFileId(id)) {
+      return null;
+    }
     const fileInfo =
       (await this.findS3FileById(id)) ||
       (await this.findFilesystemFileById(id)) ||

package/src/core/modules/tenant/INTEGRATION-CHECKLIST.md

@@ -182,8 +182,8 @@ See the module README: "Deactivated Tenants" and "Service-Level Role Checks".
 - [ ] Request with `X-Tenant-Id` header only returns tenant data
 - [ ] Request without header + hierarchy role checks user.roles and filters tenantIds
 - [ ] Admin user can access any tenant (if adminBypass: true)
-- [ ] Non-member gets 403 "Not a member of this tenant"
-- [ ] Unauthenticated + header → 403 "Authentication required for tenant access"
+- [ ] Non-member gets 403 `#LTNS_0103: Not a member of this tenant`
+- [ ] Unauthenticated + header → 401 `#LTNS_0100` (re-authentication is the remedy, so it is not a 403)
 - [ ] Public endpoint accessing tenantId-schema without context throws 403 (Safety Net)
 - [ ] IAM endpoints work without `X-Tenant-Id` header when `skipTenantCheck: true` (default)
 

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

@@ -193,6 +193,22 @@ class UserController {
 // @Roles(DefaultHR.MANAGER) without header → 200 (user.roles manager(2) >= manager(2))
 ```
 
+### Refusal Codes
+
+Every 403 of the guard carries a translatable error code; the text behind the code is the guard's
+original wording, so a substring match on it keeps working:
+
+| Code        | Message                       | Refused because                                                                         |
+| ----------- | ----------------------------- | --------------------------------------------------------------------------------------- |
+| `LTNS_0103` | `Not a member of this tenant` | the header names a tenant the user has no active membership in                          |
+| `LTNS_0104` | `Insufficient tenant role`    | the membership role does not satisfy the required tenant role                           |
+| `LTNS_0105` | `Insufficient role`           | `user.roles` does not meet the required role (no header, or a `@SkipTenantCheck` route) |
+| `LTNS_0106` | `Tenant is inactive`          | `multiTenancy.isTenantActive` reports the header's tenant as switched off               |
+| `LTNS_0107` | `Verification required`       | an `S_VERIFIED` endpoint, and the user is not verified                                  |
+
+A project that calls tenants something else overrides the translations in its own error registry
+(`errorCode.additionalErrorRegistry`, registered after the core and therefore winning).
+
 ### Skipping Tenant Checks
 
 Use `@SkipTenantCheck()` for endpoints that intentionally work without tenant context:
@@ -238,7 +254,7 @@ multiTenancy: {
 
 | Path                                                           | Deactivated tenant                                                                                                                                                                         |
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Header + tenant role, or `S_USER` / `S_VERIFIED` with a header | **403** `Tenant is inactive`                                                                                                                                                               |
+| Header + tenant role, or `S_USER` / `S_VERIFIED` with a header | **403** `#LTNS_0106: Tenant is inactive`                                                                                                                                                   |
 | Tenant API token                                               | **403**                                                                                                                                                                                    |
 | `S_EVERYONE` with a header                                     | not blocked, but no tenant context is set                                                                                                                                                  |
 | No header                                                      | dropped from the user's tenant list — its data stays out of reach                                                                                                                          |

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -470,7 +470,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       }
       const isVerified = !!(user.verified || user.verifiedAt || user.emailVerified);
       if (!isVerified) {
-        throw new ForbiddenException('Verification required');
+        throw new ForbiddenException(ErrorCode.VERIFICATION_REQUIRED);
       }
       if (headerTenantId && !hasSkipDecorator) {
         return this.handleSystemRoleWithTenantHeader(user, headerTenantId, request, isAdmin);
@@ -536,7 +536,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       const membership = await this.findMembershipCached(user.id, headerTenantId);
 
       if (!membership) {
-        throw new ForbiddenException('Not a member of this tenant');
+        throw new ForbiddenException(ErrorCode.NOT_TENANT_MEMBER);
       }
       await this.assertTenantActive(headerTenantId);
 
@@ -567,7 +567,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
           tenantRoles.length > 0 && memberRole !== null && checkRoleAccess(tenantRoles, undefined, memberRole);
 
         if (!satisfiedGlobally && !satisfiedByTenant) {
-          throw new ForbiddenException('Insufficient tenant role');
+          throw new ForbiddenException(ErrorCode.INSUFFICIENT_TENANT_ROLE);
         }
       }
 
@@ -595,7 +595,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
 
       // Check role access against user.roles (hierarchy: level comparison, normal: exact match)
       if (!checkRoleAccess(checkableRoles, user.roles, undefined)) {
-        throw new ForbiddenException('Insufficient role');
+        throw new ForbiddenException(ErrorCode.INSUFFICIENT_ROLE);
       }
 
       // Resolve tenant IDs filtered by minimum required hierarchy level
@@ -904,7 +904,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
   /** 403 for a deactivated tenant. */
   private async assertTenantActive(tenantId: string): Promise<void> {
     if (!(await this.isTenantActive(tenantId))) {
-      throw new ForbiddenException('Tenant is inactive');
+      throw new ForbiddenException(ErrorCode.TENANT_INACTIVE);
     }
   }
 
@@ -946,7 +946,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
 
     const membership = await this.findMembershipCached(user.id, headerTenantId);
     if (!membership) {
-      throw new ForbiddenException('Not a member of this tenant');
+      throw new ForbiddenException(ErrorCode.NOT_TENANT_MEMBER);
     }
     await this.assertTenantActive(headerTenantId);
     request.tenantId = headerTenantId;
@@ -965,7 +965,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
         throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
       if (!isAdmin && !checkRoleAccess(checkableRoles, user.roles, undefined)) {
-        throw new ForbiddenException('Insufficient role');
+        throw new ForbiddenException(ErrorCode.INSUFFICIENT_ROLE);
       }
     }
     return true;

package/src/core/modules/tus/INTEGRATION-CHECKLIST.md

@@ -151,7 +151,7 @@ export class TusService extends CoreTusService {
 
   // After the last byte.
   protected override async onUploadComplete(upload: Upload): Promise<void> {
-    await super.onUploadComplete(upload); // migrates the file into the configured storage
+    await super.onUploadComplete(upload); // stores the file and records its ID for X-File-Id (11.42.13+)
     // custom logic
   }
 }
@@ -243,6 +243,7 @@ TusModule.forRoot({ config: false });
 | Forgot to register custom service                  | `onUploadCreate` / `onUploadComplete` overrides never run | Add `service: TusService` to `forRoot()` (11.41.9+) — Step 2                                    |
 | Constructor dependencies on the service subclass   | `undefined` dependencies, or a crash at boot              | Resolve them at call time via `this.options?.moduleRef` — Step 2                                |
 | Override of `onUploadCreate` without `super`       | Uploads have no owner or tenant; `allowedTypes` ignored   | `return super.onUploadCreate(req, upload)` — Step 2                                             |
+| Override of `onUploadComplete` without `super`     | No `X-File-Id`; links built from the TUS URL answer `404` | Call `super.onUploadComplete(upload)` with the upload received (11.42.13+) — Step 2             |
 | Upload succeeds but the file cannot be downloaded  | `403` on `GET /files/id/:id`                              | `file.downloadRoles` defaults to `[ADMIN]` — widen it, or authorize per file in `checkRights()` |
 | Using wrong endpoint path                          | 404 on upload                                             | Ensure client uses same path as config                                                          |
 

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

@@ -111,6 +111,7 @@ The TUS server automatically handles CORS headers for browser-based clients:
 - `Upload-Length`
 - `Upload-Offset`
 - `Upload-Metadata`
+- `X-File-Id` (11.42.13+) — the ID of the stored file, see [The ID of the Stored File](#the-id-of-the-stored-file-114213)
 
 **`Access-Control-Allow-Origin` follows the API's CORS configuration (11.42.1+).** The tus handler
 writes its responses itself, and without `allowedOrigins` `@tus/server` answers `*`. With cookie
@@ -265,11 +266,19 @@ const upload = new Upload(file, {
     const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
     console.log(`${percentage}%`);
   },
+  // The response that completes the upload names the stored file (11.42.13+).
+  onAfterResponse: (_req, res) => {
+    const id = res.getHeader('X-File-Id');
+    if (id) {
+      fileId = id;
+    }
+  },
   onSuccess: () => {
-    console.log('Upload complete!');
-    console.log('File URL:', upload.url);
+    // `upload.url` is the TUS upload URL — its last segment is NOT the file id.
+    console.log('Upload complete, file:', `/files/id/${fileId}`);
   },
 });
+let fileId: string | undefined;
 
 // Start or resume upload
 upload.start();
@@ -423,6 +432,10 @@ export class TusService extends CoreTusService {
 }
 ```
 
+Call `super.onUploadComplete(upload)` with the `upload` you received: it stores the file and records
+its ID for the `X-File-Id` response header (11.42.13+). An override that never calls `super` still
+completes the upload, but the client receives no `X-File-Id`.
+
 ### Tenant Scoping (11.41.9+)
 
 **Only with `multiTenancy` configured.** Without it nothing changes: no header is read, no field is
@@ -487,6 +500,31 @@ query {
 
 **Recommendation:** Use the ID-based endpoint (`/files/id/:id`) for TUS uploads as filenames may not be unique.
 
+### The ID of the Stored File (11.42.13+)
+
+The response that completes an upload — the last `PATCH`, or the `POST` of a creation-with-upload —
+carries the ID of the stored file:
+
+```
+HTTP/1.1 204 No Content
+Upload-Offset: 52428800
+X-File-Id: 6720c1f0a2b4c8e9d0f1a2b3
+Access-Control-Expose-Headers: …, X-File-Id
+```
+
+Read it from that response and use it for `/files/id/:id`. **Do not take the last segment of the
+TUS URL** (`upload.url`): that is the TUS UPLOAD id, a key of the staging store, and `/files/id/` answers
+it with 404. Until 11.42.13 the header did not exist and the TUS URL was all a client had.
+
+The header is sent on the completing request only — creation and partial `PATCH`es store nothing yet.
+It is listed in `Access-Control-Expose-Headers`, so a browser on a separate app origin can read it. The
+name is exported as `TUS_FILE_ID_HEADER`.
+
+A project override of `onUploadComplete()` keeps the header as long as it calls `super` — see
+[Custom Upload Handler](#custom-upload-handler). The hook's signature did not change. A client must
+still cope with a missing header (an older server, or an override that stores the file itself): treat
+it as "no file id known", never as a reason to fall back to the TUS URL.
+
 > **These download routes are gated.** They require `file.downloadRoles`, which defaults to
 > `[RoleEnum.ADMIN]` — while uploading here only requires `tus.roles` (default `S_USER`). So out of
 > the box a signed-in user can upload but cannot read their own file back.
@@ -634,7 +672,8 @@ calls `getServer().handle()`. No change to `main.ts` is needed.
 3. Client: PATCH /tus/:id (send chunks)
 4. Server: Returns Upload-Offset
 5. Client: Repeat PATCH until complete
-6. Server: Migrate to GridFS, cleanup temp file
+6. Server: Migrate to the configured file storage, cleanup temp file
+7. Server: Answer the completing PATCH with X-File-Id (the stored file's ID)
 ```
 
 ### File Storage