@lenne.tech/nest-server 11.42.12 → 11.42.14

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 |
 
@@ -781,6 +781,14 @@ their public-route shortcut, so the policy holds whichever guard runs first or a
 4. A request that carries a token credential but reaches a guard without a token context (the
    middleware did not run) is refused with 401 rather than treated as anonymous.
 
+A route-level `@UseGuards(AuthGuard(AuthGuardStrategy.JWT | BETTER_AUTH))` (redundant next to
+`@Roles()`, but common — nest-server-starter's `UserController` carries it on six routes) accepts the
+token `CoreApiTokenMiddleware` authenticated instead of re-verifying the `ltt_…` credential, which
+neither Passport nor `BetterAuthTokenService` knows; before 11.42.14 that re-verification answered
+401 on every released route. It calls `enforceApiTokenRoute()` itself, so it never opens a route the
+role guards would refuse, even where it runs without one. `JWT_REFRESH` and project-defined strategies
+never accept a token.
+
 #### System Roles (S_ prefix)
 
 System roles are evaluated at runtime and must **never** be stored in `user.roles`.

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/migration-guides/11.42.13-to-11.42.14.md

@@ -0,0 +1,74 @@
+# Migration Guide: 11.42.13 → 11.42.14
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | A route-level `@UseGuards(AuthGuard(...))` no longer refuses every API token with 401 on a route released via `@ApiTokenScopes()` (§1) |
+| **New Features**     | None                                                                                                     |
+| **Framework API**    | Unchanged — no new exports, no changed signatures                                                        |
+| **Dependencies**     | None for the package (development tooling only)                                                          |
+| **Breaking Changes** | None. Tokens on routes that do not release them are refused exactly as before                            |
+| **Migration Effort** | None. Projects that removed an `AuthGuard` to make tokens work may keep it removed (§1)                   |
+
+## 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.
+
+## 1. An explicit `AuthGuard` no longer closes a released route to API tokens
+
+Many projects put `@UseGuards(AuthGuard(AuthGuardStrategy.BETTER_AUTH))` (or `AuthGuard(AuthGuardStrategy.JWT)`) on
+routes next to `@Roles()`. nest-server-starter's `UserController` does so on six routes. The guard is redundant
+there, because `@Roles()` already authenticates, but it was not harmless: it re-verified every request unless the
+user came from Better-Auth, and a user authenticated by an API token does not. So it read the `ltt_…` credential as a
+session or a JWT, failed, and answered **401** — on a route the role guard had just admitted via
+`@ApiTokenScopes()`. Opening such a route for tokens therefore never worked while the guard was on it.
+
+The guard now accepts the token `CoreApiTokenMiddleware` already authenticated, for the `JWT` and `BETTER_AUTH`
+strategies. It applies the same route policy as the role guards (`enforceApiTokenRoute()`: deny by default, scopes,
+tenant binding) itself, so it never admits a token on a route that does not release it — also in a setup where it
+runs without a framework role guard in front of it.
+
+```typescript
+@ApiTokenScopes('read')
+@Get(':id')
+@Roles(RoleEnum.S_USER)
+@UseGuards(AuthGuard(AuthGuardStrategy.BETTER_AUTH)) // 11.42.13: 401 for every token; 11.42.14: works
+async getUser(@CurrentUser() currentUser: User, @Param('id') id: string): Promise<User> { … }
+```
+
+`AuthGuard(AuthGuardStrategy.JWT_REFRESH)`, `RefreshTokenGuard` and project-defined strategies never accept a token.
+
+**What to check:**
+
+- **You removed an `AuthGuard` from a route to make tokens work:** nothing to do. The guard stays redundant next to
+  `@Roles()`; restoring it is optional.
+- **A test expected 401 for a token on a released route that carries an `AuthGuard`:** it now gets the route's
+  answer. A token on a route WITHOUT `@ApiTokenScopes()` is still refused with 403, as before.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| Routes with `@Roles()` only | Unchanged |
+| Routes with `@Roles()` + `@UseGuards(AuthGuard(BETTER_AUTH \| JWT))` + `@ApiTokenScopes()` | Tokens now pass (§1) |
+| Routes with `@UseGuards(AuthGuard(...))` but no `@ApiTokenScopes()` | Tokens refused with 403, as before |
+| `refreshToken` / `AuthGuard(JWT_REFRESH)` / custom Passport strategies | Never accept a token, as before |
+| A project guard that extends `AuthGuard(...)` and overrides `handleRequest()` | Compatible; the override also runs for token users |
+
+## Troubleshooting
+
+**A token still gets 401 on a route with an `AuthGuard`**
+Check that the route (or its class) declares `@ApiTokenScopes()` with a scope the token holds — without it, the role
+guard refuses the token with 403 before the `AuthGuard` runs. A 401 means the token itself did not authenticate
+(revoked, expired, wrong prefix); the token middleware answers that before any guard.
+
+## Module Documentation
+
+- [API token module README](../src/core/modules/api-token/README.md) — "Opening a route"
+- [API token integration checklist](../src/core/modules/api-token/INTEGRATION-CHECKLIST.md)
+- [Request lifecycle](../docs/REQUEST-LIFECYCLE.md) — "API tokens (`@ApiTokenScopes`)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.12",
+  "version": "11.42.14",
   "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",
@@ -192,7 +192,7 @@
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.2.7",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.16.13",
+    "@swc/core": "1.16.18",
     "@tus/s3-store": "2.0.7",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
@@ -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/api-token/README.md

@@ -60,6 +60,11 @@ What an opened route means per kind:
   membership role. Losing a membership removes the token's access at once — rights are read per
   request, never copied into the token.
 
+An explicit `@UseGuards(AuthGuard(AuthGuardStrategy.BETTER_AUTH))` or `AuthGuard(AuthGuardStrategy.JWT)`
+on the route does not close it to tokens (since 11.42.14; before, it answered 401): it accepts the token
+the middleware authenticated and applies the same route policy. `AuthGuard(JWT_REFRESH)` and custom
+strategies never accept a token.
+
 `request.user`:
 
 - TENANT token: `{ id: <token id>, name, scopes, tenantId, roles: [], hasRole: () => false }`

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

@@ -6,6 +6,7 @@ import { defaultOptions } from '@nestjs/passport/dist/options.js';
 import { memoize } from '@nestjs/passport/dist/utils/memoize.util.js';
 import passport = require('passport');
 
+import { enforceApiTokenRoute, getApiTokenContext } from '../../api-token/core-api-token.helpers';
 import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service';
 import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types';
 import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
@@ -21,6 +22,21 @@ const NO_STRATEGY_ERROR =
   'In order to use "defaultStrategy", please, ensure to import PassportModule in each ' +
   "place where AuthGuard() is being used. Otherwise, passport won't work correctly.";
 
+/**
+ * Strategies that authenticate a person by an access credential. An API token authenticated by
+ * `CoreApiTokenMiddleware` satisfies them; `JWT_REFRESH` and project-defined strategies authenticate
+ * something else (a refresh token, a custom credential), so a token never stands in for those.
+ */
+const API_TOKEN_SATISFIED_STRATEGIES: ReadonlySet<string> = new Set([
+  AuthGuardStrategy.BETTER_AUTH,
+  AuthGuardStrategy.JWT,
+]);
+
+function isSatisfiedByApiToken(strategy: string | string[] | undefined): boolean {
+  const strategies = Array.isArray(strategy) ? strategy : [strategy];
+  return strategies.some((value) => !!value && API_TOKEN_SATISFIED_STRATEGIES.has(value));
+}
+
 /**
  * Interface for auth guard
  */
@@ -61,6 +77,9 @@ const createPassportContext =
  * - If not, validates the token via BetterAuthTokenService (JWT or session token)
  * - Loads the full user from MongoDB with hasRole() capability
  *
+ * API tokens (JWT and BETTER_AUTH only): a token authenticated by CoreApiTokenMiddleware is accepted as is
+ * and the route is decided by enforceApiTokenRoute(), exactly as in the role guards.
+ *
  * Can be removed when pull request is merged:
  * https://github.com/nestjs/passport/pull/66
  */
@@ -118,11 +137,22 @@ function createAuthGuard(type?: AuthGuardStrategy | string | string[]): Type<IAu
 
       const options = { ...defaultOptions, ...this.options };
       const request = this.getRequest(context);
+      const existingUser = request?.[options.property || defaultOptions.property];
+
+      // An API token was already authenticated by CoreApiTokenMiddleware. Neither Passport nor
+      // BetterAuthTokenService knows its credential, so verifying it again here refused every token with
+      // 401 — also on a route that released it via @ApiTokenScopes(). The route is decided here with the
+      // same function the role guards use (deny by default, scopes, tenant binding), so the policy holds
+      // even where this guard runs without a framework role guard in front of it.
+      if (getApiTokenContext(existingUser) && isSatisfiedByApiToken(type || this.options?.defaultStrategy)) {
+        enforceApiTokenRoute({ controllerClass: context.getClass(), handler: context.getHandler(), request });
+        request[options.property || defaultOptions.property] = this.handleRequest(null, existingUser, null, context);
+        return true;
+      }
 
       // Check if user is already authenticated via Better-Auth middleware
       // Only skip Passport for Better-Auth users (marked with _authenticatedViaBetterAuth)
       // This ensures JWT_REFRESH guard still validates refresh tokens properly
-      const existingUser = request?.[options.property || defaultOptions.property];
       if (existingUser && existingUser._authenticatedViaBetterAuth === true) {
         // User is authenticated via Better-Auth - skip Passport authentication
         // Validate through handleRequest to ensure role checks work

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                                                                                                                          |