@lenne.tech/nest-server 11.42.12 → 11.42.14

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

package/src/core/modules/tus/tus.constants.ts

@@ -51,3 +51,14 @@ export const TUS_OWNER_METADATA_KEY = 'ltOwnerId';
  * resolves to a tenant they are an active member of; otherwise it is `null`.
  */
 export const TUS_TENANT_METADATA_KEY = 'ltTenantId';
+
+/**
+ * Response header naming the ID of the stored file, sent on the request that COMPLETES a tus upload
+ * (the last PATCH, or the POST of a creation-with-upload).
+ *
+ * Without it a client knows only the TUS URL, whose last segment is the tus UPLOAD id — a key of the
+ * staging store, which `/files/id/<id>` answers with 404. The header is also listed in
+ * `Access-Control-Expose-Headers`, because a browser on a separate app origin cannot read it
+ * otherwise.
+ */
+export const TUS_FILE_ID_HEADER = 'X-File-Id';