@lenne.tech/nest-server 11.33.1 → 11.34.0

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

@@ -93,6 +93,26 @@ Reads consult **every** store, so files written under a previous driver stay rea
 migration step and no cut-over moment. New files go to the active driver; `findFileInfo()` returns
 the union, paged once over the merged result.
 
+That holds per method and in **both** directions — adopting a driver and switching away from one.
+The metadata lookups are gated on whether a store is USABLE, never on whether it is the active write
+driver, so pinning `file.storage: 'gridfs'` on a deployment that once used S3 keeps the S3 files
+readable rather than 404-ing them.
+
+Three consequences worth knowing about the merged read path:
+
+- **Ordering.** Each store answers its own correctly ordered page, and the merge re-establishes a
+  global order before it pages (`sortMergedFileInfo()`), including dotted sort fields such as
+  `metadata.ownerId`. Without a `sort` the merged page is `uploadDate` descending.
+- **`contentType`.** GridFS keeps it inside `metadata`, the other two stores at the document root.
+  `GridFSHelper.findFiles()` rewrites the key so a filter or sort on `contentType` behaves the same
+  under every driver.
+- **Duplication crosses drivers.** `duplicateByName()` / `duplicateById()` read the source from
+  whichever store holds it and write the copy to the ACTIVE driver, so duplicating a file that is
+  still in GridFS while `file.storage: 's3'` simply moves it forward.
+
+`s3-files` and `filesystem-files` are created on their first WRITE, never on a read — a deployment
+that only ever uses GridFS never grows them.
+
 The boot log names the driver in use, so it never has to be inferred from where files stopped
 appearing:
 
@@ -184,6 +204,20 @@ rather than exempt from it. The reference server does both: `src/server/modules/
 `src/server/modules/user/avatar.controller.ts`. The contract test for the whole rule, covering the
 `id` **and** the `filename` branch, lives in `tests/file-ownership.e2e-spec.ts`.
 
+**It covers duplication too (11.34.0+).** `duplicateByName()` / `duplicateById()` authorize a copy as
+a READ of the source (`'filename'` / `'id'`) plus a WRITE of the copy (`'file'`), through the same
+public methods every other caller uses — so forward the context:
+
+```typescript
+await this.fileService.duplicateById(id, { currentUser });
+// …and give the COPY its own owner, because it does NOT inherit the source's metadata
+await this.fileService.duplicateById(id, { currentUser, metadata: { ownerId: currentUser.id } });
+```
+
+Not copying the source's `metadata` is deliberate: doing so would silently hand the duplicate the
+source's owner. A copy made without metadata is ADMIN-only under the rule above — fail-closed, not
+lost.
+
 Three pieces make this work, and all three are needed:
 
 1. **Write the metadata at upload time** — `createFile(file, { metadata: { ownerId: user.id } })`.
@@ -325,12 +359,14 @@ export class FileController extends CoreFileController {
 
 ### Error responses
 
-| Situation                                                                              | Status | Body                                                                                                  |
-| -------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
-| Unknown id / filename, or `checkRights()` refused                                      | `404`  | `NotFoundException` with `ErrorCode.FILE_NOT_FOUND`                                                   |
-| Missing id / filename in the route                                                     | `400`  | `BadRequestException` with `ErrorCode.REQUIRED_FIELD_MISSING`                                         |
-| GridFS read fails **before** any byte was sent (file document exists, chunks are gone) | `404`  | `{ "error": "Not Found", "message": "<FILE_NOT_FOUND>", "statusCode": 404 }`                          |
-| GridFS read fails **after** streaming started                                          | —      | The connection is closed; a truncated transfer is the only signal left once the status is on the wire |
+| Situation                                                                              | Status | Body                                                                                                                                                                                 |
+| -------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Unknown id / filename, or `checkRights()` refused                                      | `404`  | `NotFoundException` with `ErrorCode.FILE_NOT_FOUND`                                                                                                                                  |
+| `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 |
+| GridFS read fails **before** any byte was sent (file document exists, chunks are gone) | `404`  | `{ "error": "Not Found", "message": "<FILE_NOT_FOUND>", "statusCode": 404 }`                                                                                                         |
+| GridFS read fails **after** streaming started                                          | —      | The connection is closed; a truncated transfer is the only signal left once the status is on the wire                                                                                |
 
 The mid-stream failure case is handled by `pipeFileToResponse()`. Without it the stream error would
 go unhandled, Node would destroy the socket, and a reverse proxy would report **502 Bad Gateway** —

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

@@ -1,8 +1,9 @@
 import { Logger, NotFoundException } from '@nestjs/common';
-import mongoose, { Connection, mongo, Types } from 'mongoose';
+import { Connection, mongo, Types } from 'mongoose';
 import { Readable } from 'stream';
 
 import { FilterArgs } from '../../common/args/filter.args';
+import { accessDeniedException } from '../../common/exceptions/access-denied.exception';
 import { getObjectIds, getStringIds } from '../../common/helpers/db.helper';
 import { convertFilterArgsToQuery } from '../../common/helpers/filter.helper';
 import { GridFSHelper } from '../../common/helpers/gridfs.helper';
@@ -195,73 +196,103 @@ export abstract class CoreFileService {
 
   /**
    * Duplicate file by name
+   *
+   * A duplicate is a READ of the source plus a WRITE of the copy, and it is
+   * authorized as exactly that: the source goes through `getFileInfoByName()` +
+   * `getFileStreamByName()` (`checkInputType: 'filename'`) and the copy through
+   * `createFile()` (`checkInputType: 'file'`) — the same public methods, with the
+   * same `checkRights()` hook, that every other caller uses.
+   *
+   * `serviceOptions` is OPTIONAL and additive. Omitting it keeps the pre-11.34.0
+   * behaviour for the framework default `checkRights()` (which returns `true`),
+   * and turns what used to be a crash into a clean refusal for a project that
+   * overrides it fail-closed: the GridFS branch used to bypass the hook
+   * altogether and copy the file unchecked, while the S3 / filesystem branches
+   * died inside a storage helper. System-internal callers say `{ force: true }`,
+   * the same idiom the rest of this service uses.
+   *
+   * The copy does NOT inherit the source's `metadata`. Copying it would silently
+   * hand the duplicate the source's owner, which is the one thing an ownership
+   * rule must not do behind the caller's back — pass `serviceOptions.metadata`
+   * to state the copy's own.
+   *
+   * @returns the file info of the COPY. Up to 11.33.1 the GridFS branch resolved
+   *   the raw `GridFSBucketWriteStream` instead, so a project reading anything
+   *   beyond `.id` / `.filename` off it has to adjust.
    */
-  async duplicateByName(name: string, newName: string): Promise<any> {
-    // Route through the storage dispatch like every other read/write. Going straight to GridFS
-    // meant that with `file.storage: 's3'` the source simply is not there — and the resulting
-    // FileNotFound arrives on a stream with NO error handler, so it becomes an uncaught
-    // exception that takes the process down instead of a 404.
-    const nonGridFsSource = (await this.findS3FileByName(name)) || (await this.findFilesystemFileByName(name));
-    if (nonGridFsSource) {
-      const source = await this.getFileStreamByName(name);
-      return this.createFile({
-        createReadStream: () => source,
-        filename: newName,
-        mimetype: nonGridFsSource.contentType || 'application/octet-stream',
-      });
+  async duplicateByName(name: string, newName: string, serviceOptions?: FileServiceOptions): Promise<CoreFileInfo> {
+    const source = await this.getFileInfoByName(name, serviceOptions);
+    if (!source) {
+      throw new NotFoundException(`File not found with filename ${name}`);
     }
-
-    return new Promise((resolve, reject) => {
-      const downloadStream = GridFSHelper.openDownloadStreamByName(this.files, name);
-      downloadStream.on('error', reject);
-      const uploadStream = GridFSHelper.openUploadStream(this.files, newName);
-      uploadStream.on('error', reject);
-      uploadStream.on('finish', () => resolve(uploadStream));
-      downloadStream.pipe(uploadStream);
-    });
+    return this.duplicateFile(source, newName, () => this.getFileStreamByName(name, serviceOptions), serviceOptions);
   }
 
   /**
    * Duplicate file by ID
+   *
+   * See {@link duplicateByName} for the authorization model and for why
+   * `serviceOptions` matters. The copy keeps the source's filename.
+   *
+   * @returns the id of the copy
    */
-  async duplicateById(id: string): Promise<string> {
+  async duplicateById(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions): Promise<string> {
     const objectId = getObjectIds(id);
-    const file = await this.getFileInfo(objectId);
-
-    // Same dispatch as duplicateByName: a file stored outside GridFS has no GridFS counterpart.
-    const nonGridFsSource = (await this.findS3FileById(objectId)) || (await this.findFilesystemFileById(objectId));
-    if (nonGridFsSource) {
-      const source = await this.getFileStream(objectId);
-      const copy = await this.createFile({
-        createReadStream: () => source,
-        filename: file.filename,
-        mimetype: file.contentType || 'application/octet-stream',
-      });
-      return copy.id;
-    }
-
-    return new Promise((resolve, reject) => {
-      const downloadStream = GridFSHelper.openDownloadStream(this.files, objectId);
-
-      const newFileId = new mongoose.Types.ObjectId();
-      const uploadStream = GridFSHelper.openUploadStreamWithId(this.files, newFileId, file.filename, {
-        contentType: file.contentType,
-      });
-
-      downloadStream.pipe(uploadStream);
+    const source = await this.getFileInfo(objectId, serviceOptions);
+    if (!source) {
+      // Was a `TypeError` on `file.filename`: the source had been re-resolved with
+      // an empty context, so a fail-closed rule answered null and the null was then
+      // dereferenced. A refusal must read as a refusal, never as a crash.
+      throw new NotFoundException(`File not found with id ${getStringIds(objectId)}`);
+    }
+    const copy = await this.duplicateFile(
+      source,
+      source.filename,
+      () => this.getFileStream(objectId, serviceOptions),
+      serviceOptions,
+    );
+    return copy.id;
+  }
 
-      uploadStream.on('finish', () => {
-        resolve(getStringIds(newFileId));
-      });
+  /**
+   * Shared write half of the two duplicate methods.
+   *
+   * Deliberately driver-agnostic: it opens the source through the public read
+   * path (whichever store answers) and writes the copy through `createFile()`
+   * (whichever store is active). That is what makes a duplicate work ACROSS a
+   * driver change — a file still in GridFS is copied into S3 without a migration
+   * step — and what keeps the three drivers from drifting apart again.
+   */
+  protected async duplicateFile(
+    source: CoreFileInfo,
+    newName: string,
+    openSourceStream: () => Promise<Readable>,
+    serviceOptions?: FileServiceOptions,
+  ): Promise<CoreFileInfo> {
+    const stream = await openSourceStream();
+    if (!stream) {
+      // The read was refused between the two checks (or the bytes vanished).
+      // Same answer as an unknown file: never confirm that it exists.
+      throw new NotFoundException(`File not found with filename ${source.filename}`);
+    }
 
-      uploadStream.on('error', (err: { message: any }) => {
-        reject(new Error(`File duplication failed: ${err.message}`));
-      });
+    const copy = await this.createFile(
+      {
+        createReadStream: () => stream,
+        filename: newName,
+        mimetype: source.contentType || 'application/octet-stream',
+      },
+      serviceOptions,
+    );
 
-      downloadStream.on('error', (err: { message: any }) => {
-        reject(new Error(`File download failed: ${err.message}`));
-      });
-    });
+    if (!copy) {
+      // The WRITE half was refused. Unlike a refused read this is not an
+      // existence question — the caller has already been shown the source — so it
+      // answers with the framework's 401/403 policy rather than a 404.
+      stream.destroy?.();
+      throw accessDeniedException(serviceOptions?.currentUser);
+    }
+    return copy;
   }
 
   /**
@@ -317,8 +348,8 @@ export abstract class CoreFileService {
     const effective: [string, number][] = spec.length ? (spec as [string, number][]) : [['uploadDate', -1]];
     return [...docs].sort((a, b) => {
       for (const [field, direction] of effective) {
-        const left = a?.[field];
-        const right = b?.[field];
+        const left = this.readSortField(a, field);
+        const right = this.readSortField(b, field);
         if (left === right) {
           continue;
         }
@@ -336,6 +367,33 @@ export abstract class CoreFileService {
     });
   }
 
+  /**
+   * Read the value a `sort` key names, resolving DOTTED paths.
+   *
+   * `SortInput.field` is a free string, and MongoDB reads `metadata.ownerId` as a
+   * path into the document — so each store sorted correctly on its own while the
+   * merge above compared `doc['metadata.ownerId']`, which is `undefined` for every
+   * row. Every comparison then tied, the merged page came out grouped by store,
+   * and `skip`/`limit` over it returned the WRONG ROWS rather than the right rows
+   * in the wrong order.
+   *
+   * A path segment is only followed through plain objects. Anything else stops the
+   * walk and yields `undefined`, which the caller already sorts last.
+   */
+  protected readSortField(doc: Record<string, any>, field: string): any {
+    if (!field.includes('.')) {
+      return doc?.[field];
+    }
+    let current: any = doc;
+    for (const segment of field.split('.')) {
+      if (current === null || current === undefined || typeof current !== 'object') {
+        return undefined;
+      }
+      current = current[segment];
+    }
+    return current;
+  }
+
   /**
    * Get info about file via file ID
    */
@@ -531,6 +589,17 @@ export abstract class CoreFileService {
 
   /**
    * Delete file
+   *
+   * An unknown id answers `NotFoundException`, exactly as {@link deleteFileByName}
+   * does for an unknown filename. It used to fall through to GridFS and surface
+   * the driver's own `MongoRuntimeError: File not found for id …` — a **500** for
+   * the very condition its by-name sibling reported as a clean **404**, under all
+   * three storage drivers.
+   *
+   * A REFUSAL still answers `null` rather than throwing, which is the module-wide
+   * contract: a refusal must be indistinguishable from a file that is not there.
+   * Reaching the lookup below means `checkRights()` already said yes for this
+   * exact input, so a `null` here is genuinely a missing file.
    */
   async deleteFile(id: string | Types.ObjectId, serviceOptions?: FileServiceOptions): Promise<CoreFileInfo> {
     if (!(await this.checkRights(id, { ...serviceOptions, checkInputType: 'id' }))) {
@@ -538,6 +607,9 @@ export abstract class CoreFileService {
     }
     const objectId = getObjectIds(id);
     const fileInfo = await this.getFileInfo(objectId, serviceOptions);
+    if (!fileInfo) {
+      throw new NotFoundException(`File not found with id ${getStringIds(objectId)}`);
+    }
     if (await this.findS3FileById(objectId)) {
       await S3FileHelper.deleteFile(this.options.s3Service, this.s3Files, objectId);
       return fileInfo;

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

@@ -38,7 +38,7 @@ Do NOT set `hub` in the `production` block unless you intend the cockpit to be r
 | Database             | `/hub/db`             | dbStats / per-collection collStats                              |
 | Models / ERD         | `/hub/models`         | Mongoose schemas → Mermaid ER diagram                           |
 | Migrations           | `/hub/migrations`     | `MigrationRunner` status + run/rollback                         |
-| Files                | `/hub/files`          | GridFS listing + delete                                         |
+| Files                | `/hub/files`          | listing + delete across all three storage drivers               |
 | Config               | `/hub/config`         | full config, secrets masked                                     |
 | Auth Migration       | `/hub/auth-migration` | Legacy → IAM progress (BetterAuth, optional)                    |
 | Routes / Permissions | `/hub/routes`         | route + role + `@Restricted` map (Permissions module, optional) |
@@ -50,19 +50,45 @@ Do NOT set `hub` in the `production` block unless you intend the cockpit to be r
 Each panel has a `*.json` sidecar (the stable data contract) that the client polls. Optional sources
 degrade to an "unavailable" state instead of erroring.
 
+### Files panel
+
+The panel reads all three file metadata stores, not just GridFS — the same three
+`CoreFileService.findFileInfo()` consults, because metadata always lives in MongoDB whichever store
+holds the bytes:
+
+| Store        | Collection                            | Bytes live in                   |
+| ------------ | ------------------------------------- | ------------------------------- |
+| `s3`         | `s3-files`                            | the S3 bucket                   |
+| `filesystem` | `filesystem-files`                    | `file.storageDir` on local disk |
+| `gridfs`     | `<bucket>.files` (default `fs.files`) | MongoDB                         |
+
+Every row carries the `store` it was found in, and `files.json` reports a per-store `count` so an
+empty store reads as **empty** rather than as _"this panel does not cover your driver"_. Until
+11.34.0 it read `fs.files` alone, so under `file.storage: 's3'` or `'filesystem'` it confidently
+answered **0 files** — the worst answer available, since the Hub is what an operator opens precisely
+when they are unsure whether an upload landed.
+
+Two properties worth knowing:
+
+- **Delete dispatches to the owning store.** An S3-backed file needs `CoreS3Service` to be
+  configured in this process; without it the action REFUSES (`S3 storage is not available.`) rather
+  than deleting the metadata document and orphaning the object in the bucket.
+- **Reading never creates a collection.** A GridFS-only deployment does not grow an empty
+  `s3-files` / `filesystem-files` from the panel looking at them.
+
 ## Actions (mutating)
 
 Enabled by default (`actions: true`). Every mutating request requires the `X-Hub-Request: 1` header
 (CSRF defense) and destructive ones a server-validated `confirm` keyword:
 
-| Action                  | Endpoint                                   | Confirm      |
-| ----------------------- | ------------------------------------------ | ------------ |
-| Run pending migrations  | `POST /hub/actions/migrations/run`         | `RUN`        |
-| Rollback last migration | `POST /hub/actions/migrations/down`        | `DOWN`       |
-| Delete GridFS file      | `DELETE /hub/actions/files/:id`            | the filename |
-| Cron start/stop/trigger | `POST /hub/actions/cron/:name/:action`     | the job name |
-| Clear collector buffer  | `POST /hub/actions/collectors/:name/clear` | `CLEAR`      |
-| Send test mail          | `POST /hub/actions/email/test`             | —            |
+| Action                   | Endpoint                                   | Confirm      |
+| ------------------------ | ------------------------------------------ | ------------ |
+| Run pending migrations   | `POST /hub/actions/migrations/run`         | `RUN`        |
+| Rollback last migration  | `POST /hub/actions/migrations/down`        | `DOWN`       |
+| Delete file (any driver) | `DELETE /hub/actions/files/:id`            | the filename |
+| Cron start/stop/trigger  | `POST /hub/actions/cron/:name/:action`     | the job name |
+| Clear collector buffer   | `POST /hub/actions/collectors/:name/clear` | `CLEAR`      |
+| Send test mail           | `POST /hub/actions/email/test`             | —            |
 
 Every action writes an audit line: `[HUB-ACTION] <action> by user <id>`.
 

package/src/core/modules/hub/helpers/hub-client-js.helper.ts

@@ -506,9 +506,20 @@ export function getHubClientJs(): string {
 
   Hub.panels.files = function (content) {
     pollInto(content, 'files.json', function (c, d) {
-      c.appendChild(tiles([{ label: 'Files', value: d.total }, { label: 'Bucket', value: d.bucket }]));
+      // One tile per metadata store, so an empty store reads as "empty" rather than as "this panel
+      // does not cover your driver" — the ambiguity that made a GridFS-only listing look like the
+      // whole truth under file.storage: 's3'.
+      var storeTiles = [{ label: 'Files', value: d.total }];
+      (d.stores || []).forEach(function (s) {
+        storeTiles.push({ cls: s.error ? 'err' : '', label: s.store === 'gridfs' ? 'GridFS (' + d.bucket + ')' : s.store, value: s.error ? '!' : s.count });
+      });
+      c.appendChild(tiles(storeTiles));
+      (d.stores || []).filter(function (s) { return s.error; }).forEach(function (s) {
+        c.appendChild(el('p', { class: 'hub-hint', text: s.collection + ': ' + s.error }));
+      });
       c.appendChild(table([
         { key: 'filename', label: 'Filename' },
+        { key: 'store', label: 'Store', render: function (r) { return el('span', { class: 'hub-chip', text: r.store }); } },
         { key: 'length', label: 'Size', render: function (r) { return fmtBytes(r.length); } },
         { key: 'contentType', label: 'Type', render: function (r) { return r.contentType || '–'; } },
         { key: 'uploadDate', label: 'Uploaded', render: function (r) { return r.uploadDate ? relTime(r.uploadDate) : '–'; } },

package/src/core/modules/hub/hub-action-messages.ts

@@ -21,8 +21,16 @@ export const HubActionMessage = {
   confirmationFilenameRequired: 'Confirmation filename required.',
   /** Test mail: the EmailService is not wired into this app. */
   emailServiceUnavailable: 'EmailService is not available.',
-  /** Delete file: no GridFS file with the given id. */
+  /** Delete file: no file with the given id in any of the three metadata stores. */
   fileNotFound: 'File not found.',
+  /**
+   * Delete file: the file's bytes are in S3, but `CoreS3Service` is not configured in this process.
+   *
+   * Deliberately a REFUSAL rather than a metadata-only delete. Removing the document while the
+   * object stays in the bucket produces an orphan nothing can find again — unrecoverable in a way
+   * that "try again with S3 configured" is not.
+   */
+  s3Unavailable: 'S3 storage is not available.',
   /** Delete file: the id is not a valid ObjectId. */
   invalidFileId: 'Invalid file id.',
   /** Migrations action while the migrations panel is disabled. */

package/src/core/modules/hub/interfaces/hub-panels.interface.ts

@@ -79,9 +79,39 @@ export interface HubMigrationsData {
   source: 'collection' | 'runner';
 }
 
+/**
+ * Which metadata store a Hub file row came from.
+ *
+ * Mirrors `FileStorageDriver`, but is deliberately its OWN type: this one describes where a file
+ * was FOUND, which is a property of the row. `file.storage` describes where the next write GOES,
+ * which is a property of the config. Under a driver switch the two legitimately disagree for every
+ * pre-switch file — the whole reason this panel had to stop assuming one store.
+ */
+export type HubFileStore = 'filesystem' | 'gridfs' | 's3';
+
+/** Per-store summary for the Files panel, so an empty store reads as "empty", not "not covered". */
+export interface HubFileStoreSummary {
+  /** The MongoDB collection holding this store's metadata (`fs.files`, `s3-files`, …). */
+  collection: string;
+  /** Documents in that collection. `0` for a store this deployment has never written to. */
+  count: number;
+  /** Present only when this store could not be read; the other stores are still listed. */
+  error?: string;
+  store: HubFileStore;
+}
+
 export interface HubFilesData {
   bucket: string;
-  files: { contentType?: string; filename: string; id: string; length: number; uploadDate?: string }[];
+  files: {
+    contentType?: string;
+    filename: string;
+    id: string;
+    length: number;
+    store: HubFileStore;
+    uploadDate?: string;
+  }[];
+  /** Every store consulted, whether or not it holds anything. */
+  stores: HubFileStoreSummary[];
   total: number;
 }
 

package/src/core/modules/hub/services/core-hub-actions.service.ts

@@ -3,6 +3,7 @@ import { Injectable, Logger, Optional } from '@nestjs/common';
 import { EmailService } from '../../../common/services/email.service';
 import { RequestContext } from '../../../common/services/request-context.service';
 import { HubActionMessage } from '../hub-action-messages';
+import { HubFileStore } from '../interfaces/hub-panels.interface';
 import { CoreHubDbService } from './core-hub-db.service';
 import { CoreHubEmailService } from './core-hub-email.service';
 import { CoreHubMailboxService } from './core-hub-mailbox.service';
@@ -70,8 +71,15 @@ export class CoreHubActionsService {
     return { action, name };
   }
 
-  /** Delete a GridFS file (the confirm keyword must equal its filename). */
-  async deleteFile(id: string, expectedFilename: string): Promise<{ deleted: { filename: string; id: string } }> {
+  /**
+   * Delete a file from whichever storage driver holds it (the confirm keyword must equal its
+   * filename). The resolved store is echoed back so the `[HUB-ACTION]` audit trail records WHERE
+   * the bytes were removed from, not merely that a delete happened.
+   */
+  async deleteFile(
+    id: string,
+    expectedFilename: string,
+  ): Promise<{ deleted: { filename: string; id: string; store: HubFileStore } }> {
     this.audit(`delete file ${id}`);
     return { deleted: await this.dbService.deleteFile(id, expectedFilename) };
   }