@lenne.tech/nest-server 11.42.11 → 11.42.13

package/src/core/modules/better-auth/core-better-auth-cookie.helper.ts

@@ -81,6 +81,16 @@ export interface BetterAuthCookieHelperConfig {
    * CRITICAL: Required for Passkey/2FA to work correctly.
    */
   secret?: string;
+  /**
+   * Whether Better-Auth's own handlers set `Secure` on the cookies they write
+   * (`CoreBetterAuthService.usesSecureCookies()`). `true` makes this helper set it too, whatever the
+   * environment, so one session cookie never carries two different transport rules.
+   *
+   * @since 11.42.12 Before, `secure` followed {@link isProductionLikeEnv} alone, so on the deployed
+   *                 `develop` / `test` stages of a starter-based project the cookie this helper wrote
+   *                 lacked `Secure` while Better-Auth's handlers set it on the same https deployment.
+   */
+  secureTransport?: boolean;
 }
 
 /**
@@ -146,9 +156,11 @@ export class BetterAuthCookieHelper {
   /**
    * Gets the default cookie options for authentication cookies.
    *
-   * The `secure` flag is `true` when either `config.env` is production-like
-   * (`production` / `staging`) or `NODE_ENV === 'production'`. This covers
-   * staging deployments where only one of the two signals is set.
+   * The `secure` flag is `true` when Better-Auth's own cookies are secure (`config.secureTransport`,
+   * i.e. an `https://` base URL unless the project opted out), when `config.env` is production-like
+   * (`production` / `staging`), or when `NODE_ENV === 'production'`. The first covers every https
+   * deployment whatever its environment name; the other two keep `Secure` where real users are
+   * certain even if a project switched it off in Better-Auth.
    *
    * @returns Cookie options with httpOnly, sameSite, and secure settings
    */
@@ -156,7 +168,7 @@ export class BetterAuthCookieHelper {
     const options: AuthCookieOptions = {
       httpOnly: true,
       sameSite: 'lax',
-      secure: isProductionLikeEnv(this.config.env),
+      secure: this.config.secureTransport === true || isProductionLikeEnv(this.config.env),
     };
 
     if (this.config.domain) {
@@ -403,7 +415,13 @@ export class BetterAuthCookieHelper {
  */
 export function createCookieHelper(
   basePath: string,
-  options?: { domain?: string; env?: string; legacyCookieEnabled?: boolean; secret?: string },
+  options?: {
+    domain?: string;
+    env?: string;
+    legacyCookieEnabled?: boolean;
+    secret?: string;
+    secureTransport?: boolean;
+  },
   logger?: Logger,
 ): BetterAuthCookieHelper {
   return new BetterAuthCookieHelper({
@@ -413,5 +431,6 @@ export function createCookieHelper(
     legacyCookieEnabled: options?.legacyCookieEnabled ?? false,
     logger,
     secret: options?.secret,
+    secureTransport: options?.secureTransport,
   });
 }

package/src/core/modules/better-auth/core-better-auth-email-verification.service.ts

@@ -4,7 +4,7 @@ import ejs = require('ejs');
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { isProductionLikeEnv, resolveAppUrlFromConfig } from '../../common/helpers/cookies.helper';
+import { isLocalEnv, isProductionLikeEnv, resolveAppUrlFromConfig } from '../../common/helpers/cookies.helper';
 import { maskEmail } from '../../common/helpers/logging.helper';
 import { IBetterAuthEmailVerificationConfig } from '../../common/interfaces/server-options.interface';
 import { BrevoService } from '../../common/services/brevo.service';
@@ -838,25 +838,35 @@ export class CoreBetterAuthEmailVerificationService {
    * Print an auth link (verification / password reset) to stdout for local development.
    *
    * The URL embeds a bearer token: the verification link confirms an address, the reset link
-   * changes a password outright. Neither may reach a deployment holding real accounts, so the gate
-   * is `isProductionLikeEnv()` — the same two-layer check `EmailService` and the cookie helpers
-   * already use. `NODE_ENV !== 'production'` alone is NOT enough: a staging deployment sets
-   * `NODE_ENV=staging` so `getEnvironmentConfig()` loads its config block, which passes that test
-   * while holding real users.
+   * changes a password outright. Neither may reach a deployment's logs, so the link is printed only
+   * in a LOCAL environment (`isLocalEnv()`: `local`, `ci`, `e2e`) — an allowlist, not "anything
+   * that is not production". Until 11.42.12 the gate was `!isProductionLikeEnv()`, which names only
+   * `production` and `staging`; the deployed `develop` and `test` stages of a starter-based project
+   * passed it and wrote live reset links into their log pipeline, where log access alone was
+   * enough to take over an account.
+   *
+   * `LT_LOG_AUTH_URLS=1` opts in for another environment that runs on a developer machine (this
+   * repository's own `development`, for one); `LT_LOG_AUTH_URLS=0` suppresses it everywhere. A
+   * production-like environment never prints, whatever the variable says: the opt-in exists for
+   * laptops, and a hard floor keeps it from being the thing that reopens a deployment.
    *
    * The address is masked (PII, and the rest of this file already masks it); the URL is printed in
-   * full because following it without a mail server is the whole point locally. Set
-   * `LT_LOG_AUTH_URLS=0` to suppress it even outside production.
+   * full because following it without a mail server is the whole point locally.
    *
    * `console.log` rather than the NestJS logger, deliberately and for two reasons: the logger
    * buffers, which makes interception unreliable under Vitest, and a logger call would route the
    * token into `HubLogBufferService`'s ring buffer, which is readable over HTTP by any ADMIN.
    */
   protected logAuthUrlForDevelopment(label: string, email: string, url: string): void {
-    if (process.env.LT_LOG_AUTH_URLS === '0') {
+    const optIn = process.env.LT_LOG_AUTH_URLS;
+    if (optIn === '0') {
+      return;
+    }
+    const env = this.configService?.getFastButReadOnly<string>('env') ?? process.env.NODE_ENV;
+    if (isProductionLikeEnv(env)) {
       return;
     }
-    if (isProductionLikeEnv(this.configService?.getFastButReadOnly<string>('env'))) {
+    if (!isLocalEnv(env) && optIn !== '1') {
       return;
     }
     // oxlint-disable-next-line no-console

package/src/core/modules/better-auth/core-better-auth.controller.ts

@@ -268,6 +268,10 @@ export class CoreBetterAuthController {
         env: this.configService.getFastButReadOnly<string>('env'),
         legacyCookieEnabled: legacyAuthEnabled,
         secret: betterAuthConfig?.secret,
+        // Mirror Better-Auth's own `Secure` decision, so the cookie this controller writes and the
+        // one Better-Auth's handlers write follow the same transport rule on every https deployment.
+        // Optional call: a project's test stub of the service may predate the method.
+        secureTransport: this.betterAuthService.usesSecureCookies?.() === true,
       },
       this.logger,
     );

package/src/core/modules/better-auth/core-better-auth.service.ts

@@ -703,6 +703,30 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
     return this.config.baseUrl || 'http://localhost:3000';
   }
 
+  /**
+   * Whether Better-Auth's own handlers set `Secure` on the cookies they write, read off the live
+   * instance.
+   *
+   * `createBetterAuthInstance()` pins `useSecureCookies: false` (for the cookie NAME) and restores
+   * the transport flag through `advanced.defaultCookieAttributes.secure` on an `https://` base URL;
+   * a project may override either. Reading the instance rather than re-deriving from a URL gives
+   * exactly the answer Better-Auth applies — including the base URL it actually uses, which
+   * {@link getBaseUrl} does not know when only the server's `baseUrl` is set.
+   *
+   * The framework's own cookie helper mirrors this, so a session cookie carries `Secure` no matter
+   * which path wrote it.
+   *
+   * @since 11.42.12
+   */
+  usesSecureCookies(): boolean {
+    const advanced = (
+      this.getInstance() as unknown as {
+        options?: { advanced?: { defaultCookieAttributes?: { secure?: unknown }; useSecureCookies?: unknown } };
+      } | null
+    )?.options?.advanced;
+    return advanced?.useSecureCookies === true || advanced?.defaultCookieAttributes?.secure === true;
+  }
+
   /**
    * Gets the resolved cookie domain for cross-subdomain cookie sharing.
    *

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

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

@@ -21,7 +21,7 @@ import {
   FilesystemFileHelper,
 } from '../file/filesystem-file.helper';
 import { S3_FILES_COLLECTION, S3FileHelper } from '../file/s3-file.helper';
-import { TUS_OWNER_METADATA_KEY, TUS_TENANT_METADATA_KEY } from './tus.constants';
+import { TUS_FILE_ID_HEADER, TUS_OWNER_METADATA_KEY, TUS_TENANT_METADATA_KEY } from './tus.constants';
 import { TusRedisLocker } from './tus-redis-locker';
 import {
   DEFAULT_TUS_ALLOWED_HEADERS,
@@ -86,6 +86,17 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
   private files: mongo.GridFSBucket;
   private cleanupInterval: NodeJS.Timeout | null = null;
 
+  /**
+   * The ID of the stored file per finished upload, recorded by {@link CoreTusService.onUploadComplete}
+   * and read by `onUploadFinish` for the `X-File-Id` response header.
+   *
+   * Recorded on the side rather than returned, so the hook keeps its `Promise<void>` signature: a
+   * project override in either documented shape — `await super.onUploadComplete(upload)` or
+   * `return super.onUploadComplete(upload)` — still compiles AND still yields the header. Keyed by
+   * the `Upload` object `onUploadFinish` hands to the hook, so nothing outlives the request.
+   */
+  private readonly storedFileIds = new WeakMap<Upload, string>();
+
   /** Datastore of the TUS server; set when uploads are staged in S3 */
   protected s3Store: any = null;
 
@@ -183,10 +194,15 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
   }
 
   /**
-   * Handle upload completion - migrate to GridFS
+   * Handle upload completion - migrate the finished upload into the configured file storage
    *
    * This method can be overridden in extending services to customize
    * what happens after an upload completes.
+   *
+   * Records the ID of the stored file, which the completing response sends to the client as
+   * `X-File-Id` (`TUS_FILE_ID_HEADER`). An override must call `super.onUploadComplete(upload)` with
+   * the `upload` it received; one that does not stores nothing here and sends no header — the client
+   * then knows the TUS URL alone, whose last segment is the upload id, not the file id.
    */
   protected async onUploadComplete(upload: Upload): Promise<void> {
     try {
@@ -231,6 +247,7 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
           `Upload ${upload.id} copied inside S3 to ${fileInfo._id} (filename: ${filename}) — no bytes through this process`,
         );
         await this.deleteStagedUpload(upload.id);
+        this.storedFileIds.set(upload, String(fileInfo._id));
         return;
       }
 
@@ -239,15 +256,16 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
         return;
       }
 
+      let fileInfo: { _id: unknown };
       if (this.fileStorageDriver === 'filesystem') {
-        const fileInfo = await FilesystemFileHelper.writeFile(
+        fileInfo = await FilesystemFileHelper.writeFile(
           this.fileStorageDir,
           this.connection.db.collection(FILESYSTEM_FILES_COLLECTION),
           { body: readStream, contentType, filename, metadata: fileMetadata },
         );
         this.logger.debug(`Upload ${upload.id} migrated to the filesystem as ${fileInfo._id} (filename: ${filename})`);
       } else if (this.s3FileStorage) {
-        const fileInfo = await S3FileHelper.writeFile(
+        fileInfo = await S3FileHelper.writeFile(
           this.options.s3Service,
           this.connection.db.collection(S3_FILES_COLLECTION),
           // Streamed with the length TUS already knows, so a multi-GB resumable upload is never
@@ -256,7 +274,7 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
         );
         this.logger.debug(`Upload ${upload.id} migrated to S3 as ${fileInfo._id} (filename: ${filename})`);
       } else {
-        const fileInfo = await GridFSHelper.writeFileFromStream(this.files, readStream, {
+        fileInfo = await GridFSHelper.writeFileFromStream(this.files, readStream, {
           contentType,
           filename,
           metadata: fileMetadata,
@@ -266,6 +284,7 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
 
       // Clean up the staged upload
       await this.deleteStagedUpload(upload.id);
+      this.storedFileIds.set(upload, String(fileInfo._id));
     } catch (error) {
       this.logger.error(`Failed to migrate upload ${upload.id}: ${error.message}`);
       throw error;
@@ -837,6 +856,9 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
       // which a browser refuses on a credentialed (cookie) request — see resolveCorsOrigins().
       ...(cors ? { allowedCredentials: true, allowedOrigins: cors } : {}),
       datastore,
+      // Appended to the tus protocol headers in `Access-Control-Expose-Headers`: a browser on a
+      // separate app origin cannot read a response header that is not listed there.
+      exposedHeaders: [TUS_FILE_ID_HEADER],
       ...(locker ? { locker } : {}),
       maxSize: this.config.maxSize,
       // Every request that names an upload — HEAD (offset), PATCH (append bytes), DELETE
@@ -864,10 +886,14 @@ export class CoreTusService implements OnModuleDestroy, OnModuleInit {
         const relative = this.config.relativeLocation === true || (server as any)?.options?.relativeLocation === true;
         return relative ? url : `${proto}://${host}${url}`;
       },
+      // The response that completes the upload names the stored file. Without it the client knows
+      // only the TUS URL, whose last segment is the upload id — a staging key `/files/id/` answers
+      // with 404. An override of onUploadComplete() that never calls super records nothing: no header.
       onUploadFinish: async (_req, upload) => {
         try {
           await this.onUploadComplete(upload);
-          return {};
+          const fileId = this.storedFileIds.get(upload);
+          return fileId ? { headers: { [TUS_FILE_ID_HEADER]: fileId } } : {};
         } catch (error) {
           // Do NOT swallow this. `onUploadComplete` is what moves the finished upload into its
           // permanent store; returning `{}` after it failed answers the client with a 204 that