@lenne.tech/nest-server 11.32.3 → 11.33.0

package/src/core/modules/file/file-metadata.helper.ts

@@ -0,0 +1,142 @@
+import { mongo, Types } from 'mongoose';
+
+/**
+ * The metadata shape every non-GridFS storage driver writes, and the queries against it.
+ *
+ * WHY THIS FILE EXISTS: `S3FileHelper` and `FilesystemFileHelper` grew the same
+ * six-field document, the same `FileCollection` alias and the same four lookups
+ * independently. Two consequences, and the second one is the reason this is not
+ * merely tidiness:
+ *
+ *  1. The two drifted. `getRawFileInfoByName()` consulted S3 and GridFS but not the
+ *     filesystem, so a by-name authorization rule saw a different set of files than
+ *     the download served.
+ *  2. Because the documents are structurally identical, NOTHING in a fetched file
+ *     info said which store it came from — so every caller that needed to know had
+ *     to go and ask all three stores again. A single download resolved the same id
+ *     up to three times.
+ *
+ * (2) is solved by `CoreFileService.resolveFile()`, which remembers WHICH PROBE
+ * ANSWERED and hands that down instead of letting the next caller re-probe. Not by
+ * the `storage` marker below — see its own doc for why the collection, not the
+ * field, is authoritative when reading.
+ *
+ * DELIBERATELY IMPORT-FREE apart from mongoose types, so it stays a leaf. See
+ * `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ */
+
+/** Metadata collection handle (no Mongoose schema — these collections are driver-managed) */
+export type FileCollection = mongo.Collection<any>;
+
+/**
+ * Which store holds a file's bytes, as recorded on the metadata document.
+ *
+ * GridFS is absent on purpose: its documents live in `fs.files` and are written by
+ * the driver, which will never carry this field. "No marker and found in fs.files"
+ * IS the GridFS case.
+ */
+export type FileStorageMarker = 'filesystem' | 's3';
+
+/**
+ * Metadata of a file whose bytes live outside GridFS.
+ *
+ * The first six fields are exactly a GridFS `fs.files` document, which is what lets
+ * `prepareOutput()` map all three stores onto `CoreFileInfo` unchanged.
+ */
+export interface FileMetadataInfo {
+  _id: Types.ObjectId;
+  contentType?: string;
+  filename: string;
+  length: number;
+  metadata?: Record<string, any>;
+  /**
+   * Which driver wrote these bytes.
+   *
+   * FOR OPERATORS AND DIAGNOSTICS, not for dispatch. Code must derive the store from
+   * the COLLECTION a document was found in, never from this field: the two can only
+   * ever disagree through corruption or a hand-edit, and trusting the field there
+   * would send a read to the wrong store. It earns its place by making the store
+   * answerable in a plain query (`db['s3-files'].countDocuments({ storage: 's3' })`)
+   * and by surviving an export, where the collection name does not.
+   *
+   * Absent on documents written before 11.33.0, and on every GridFS document.
+   */
+  storage?: FileStorageMarker;
+  uploadDate: Date;
+}
+
+/** Find one metadata document by id */
+export async function findMetadataById(
+  collection: FileCollection,
+  id: string | Types.ObjectId,
+): Promise<FileMetadataInfo | null> {
+  return (await collection.findOne({ _id: new Types.ObjectId(id) })) as FileMetadataInfo | null;
+}
+
+/**
+ * Find one metadata document by filename.
+ *
+ * Resolves the FIRST match — filenames are not unique in any of these stores, and
+ * are client-supplied on both the multer and the tus path. Prefer the id lookup
+ * wherever the caller has an id.
+ */
+export async function findMetadataByName(
+  collection: FileCollection,
+  filename: string,
+): Promise<FileMetadataInfo | null> {
+  return (await collection.findOne({ filename })) as FileMetadataInfo | null;
+}
+
+/** Find metadata documents by filter */
+export async function findMetadata(
+  collection: FileCollection,
+  filter: any = {},
+  options: any = {},
+): Promise<FileMetadataInfo[]> {
+  return (await collection.find(filter, options).toArray()) as FileMetadataInfo[];
+}
+
+/**
+ * Namespaces whose `filename` index has already been ensured in this process.
+ *
+ * Keyed by `<db>.<collection>` rather than by object identity: the service builds a
+ * fresh collection handle per instance, and two instances in one process (the tests
+ * do exactly that) would otherwise each pay the round trip.
+ */
+const filenameIndexEnsured = new Set<string>();
+
+/**
+ * Ensure the `filename` index, ON THE WRITE PATH ONLY.
+ *
+ * These collections have no Mongoose schema, so nothing creates their indexes
+ * implicitly the way the driver does for GridFS's `fs.files`. Without one,
+ * `GET /files/:filename` is a collection scan that grows with the file count.
+ *
+ * WHY THIS IS NOT CALLED WHEN READING: `createIndex` CREATES the collection. Calling
+ * it on the read path made a deployment that only ever uses GridFS grow an empty
+ * `s3-files` and an empty `filesystem-files` — collections it has no reason to have,
+ * which then show up in backups and in the Hub's DB panel as if the driver were in
+ * use. A store that is never written to now stays absent, and a store that HAS been
+ * written to necessarily went through here, so the index exists exactly where there
+ * is data to index.
+ *
+ * NEVER THROWS. A missing index makes later reads slow, not wrong, and must not turn
+ * an upload into a 500 — so a failure only un-marks the namespace, and the next write
+ * tries again rather than pinning the failure for the process lifetime.
+ *
+ * @returns whether the index is now known to exist
+ */
+export async function ensureFilenameIndex(collection: FileCollection): Promise<boolean> {
+  const namespace = `${collection.dbName}.${collection.collectionName}`;
+  if (filenameIndexEnsured.has(namespace)) {
+    return true;
+  }
+  filenameIndexEnsured.add(namespace);
+  try {
+    await collection.createIndex({ filename: 1 });
+    return true;
+  } catch {
+    filenameIndexEnsured.delete(namespace);
+    return false;
+  }
+}

package/src/core/modules/file/file-roles.helper.ts

@@ -0,0 +1,110 @@
+import { Logger } from '@nestjs/common';
+
+import { RoleEnum } from '../../common/enums/role.enum';
+import { IFileConfig } from '../../common/interfaces/server-options.interface';
+import { CoreFileController } from './core-file.controller';
+import { CoreFileResolver } from './core-file.resolver';
+
+const logger = new Logger('CoreFileRoles');
+
+/**
+ * Roles applied when `file` is not configured at all.
+ *
+ * Restrictive on purpose: one GridFS bucket is shared by every feature of the
+ * consuming project, and the ObjectIds naming its blobs are not secrets.
+ */
+export type FileRoleKey = 'deleteRoles' | 'downloadRoles' | 'uploadRoles';
+
+export const FILE_ROLE_DEFAULTS: Record<FileRoleKey, string[]> = {
+  deleteRoles: [RoleEnum.ADMIN],
+  downloadRoles: [RoleEnum.ADMIN],
+  uploadRoles: [RoleEnum.ADMIN],
+};
+
+/**
+ * Which member is governed by which knob.
+ *
+ * `getFileInfo` rides with `downloadRoles` rather than getting its own knob:
+ * it answers filename, size and content type for a blob, which is the metadata
+ * half of a download. Splitting it would let a project accidentally publish the
+ * bucket's contents list while believing downloads were still closed.
+ */
+const ROLE_TARGETS: { key: FileRoleKey; member: string; owner: () => unknown }[] = [
+  {
+    key: 'downloadRoles',
+    member: 'CoreFileController.getFileById',
+    owner: () => CoreFileController.prototype.getFileById,
+  },
+  { key: 'downloadRoles', member: 'CoreFileController.getFile', owner: () => CoreFileController.prototype.getFile },
+  { key: 'downloadRoles', member: 'CoreFileResolver.getFileInfo', owner: () => CoreFileResolver.prototype.getFileInfo },
+  { key: 'uploadRoles', member: 'CoreFileResolver.uploadFile', owner: () => CoreFileResolver.prototype.uploadFile },
+  { key: 'uploadRoles', member: 'CoreFileResolver.uploadFiles', owner: () => CoreFileResolver.prototype.uploadFiles },
+  { key: 'deleteRoles', member: 'CoreFileResolver.deleteFile', owner: () => CoreFileResolver.prototype.deleteFile },
+];
+
+/**
+ * Resolve one knob to the role list that will actually be applied.
+ *
+ * An empty array is treated as "not configured". It cannot mean "nobody": the
+ * guards read an all-empty role set as "no roles required" and return true, so
+ * honouring it literally would OPEN the route instead of closing it — the exact
+ * opposite of what someone writing `[]` intends.
+ */
+function resolveRoles(key: FileRoleKey, config?: IFileConfig): string[] {
+  const configured = config?.[key];
+
+  if (configured === undefined) {
+    return FILE_ROLE_DEFAULTS[key];
+  }
+
+  if (!Array.isArray(configured) || configured.length === 0 || configured.some((role) => typeof role !== 'string')) {
+    logger.warn(
+      `Ignoring file.${key}: expected a non-empty array of role strings, got ${JSON.stringify(configured)}. ` +
+        `Falling back to ${JSON.stringify(FILE_ROLE_DEFAULTS[key])}.`,
+    );
+    return FILE_ROLE_DEFAULTS[key];
+  }
+
+  return configured;
+}
+
+/**
+ * Apply the configured file roles to the core file endpoints.
+ *
+ * Uses `Reflect.defineMetadata` rather than `@Roles()` for the same reason
+ * `CorePermissionsModule` does: the value is only known at runtime, from the
+ * configuration. `RolesGuard` / `BetterAuthRolesGuard` read exactly this key.
+ *
+ * TWO PROPERTIES A READER SHOULD KNOW ABOUT:
+ *
+ * 1. **ADMIN always keeps access.** Both classes carry a class-level
+ *    `@Roles(RoleEnum.ADMIN)`, and the guards UNION handler and class metadata
+ *    (`mergeRolesMetadata`) rather than letting one override the other. So
+ *    `downloadRoles: ['editor']` grants editors *in addition to* admins. That is
+ *    intended — it keeps a misconfiguration from locking the owner out — but it
+ *    does mean these knobs cannot be used to exclude admins.
+ *
+ * 2. **A subclass that OVERRIDES a member opts out of the configuration.**
+ *    Decorator metadata lives on the function object; an override is a different
+ *    function, so what this writes onto the base method no longer applies.
+ *    Consumers who want config-driven roles must inherit the member rather than
+ *    re-declaring it. This is precisely the trap that kept `nest-server-starter`
+ *    serving public downloads after the core default had already been closed.
+ */
+export function applyFileRoles(config?: IFileConfig): void {
+  const resolved = new Map<FileRoleKey, string[]>();
+
+  for (const { key, member, owner } of ROLE_TARGETS) {
+    if (!resolved.has(key)) {
+      resolved.set(key, resolveRoles(key, config));
+    }
+
+    const target = owner();
+    if (typeof target !== 'function') {
+      logger.warn(`Cannot apply file.${key}: ${member} is not a function — skipping.`);
+      continue;
+    }
+
+    Reflect.defineMetadata('roles', resolved.get(key), target);
+  }
+}

package/src/core/modules/file/file-storage.helper.ts

@@ -0,0 +1,163 @@
+import { Logger } from '@nestjs/common';
+
+import { IServerOptions } from '../../common/interfaces/server-options.interface';
+
+const logger = new Logger('CoreFileStorage');
+
+/**
+ * The three storage drivers. All equivalent in what they offer through
+ * `CoreFileService`; they differ only in where the bytes end up.
+ *
+ * - `'s3'`         — an S3-compatible bucket. The only one that survives horizontal scaling.
+ * - `'gridfs'`     — MongoDB GridFS. No extra infrastructure, bytes share the database.
+ * - `'filesystem'` — the local disk. Pod-local: not shared between replicas, lost on restart
+ *                    unless the path is a mounted volume.
+ */
+export type FileStorageDriver = 'filesystem' | 'gridfs' | 's3';
+
+export const FILE_STORAGE_DRIVERS: FileStorageDriver[] = ['filesystem', 'gridfs', 's3'];
+
+/**
+ * How a driver was arrived at — for the boot log and for error messages, so a
+ * surprising choice can be traced back to the setting that produced it.
+ */
+export interface FileStorageResolution {
+  driver: FileStorageDriver;
+  explicit: boolean;
+  reason: string;
+}
+
+/**
+ * Whether the S3 configuration names a concrete bucket to write to.
+ *
+ * A bucket is the one thing S3 cannot default: region, endpoint and credentials
+ * all have fallbacks (the AWS default credential chain resolves an IAM role,
+ * an instance profile or `AWS_*` environment variables without anything in the
+ * config), but "which bucket" has to be stated. So the presence of a bucket is
+ * what makes an S3 configuration usable — and therefore what makes S3 eligible
+ * as the automatic default.
+ */
+export function hasUsableS3Config(config?: Partial<IServerOptions>): boolean {
+  const s3 = config?.s3;
+  if (!s3 || typeof s3 !== 'object' || (s3 as { enabled?: boolean }).enabled === false) {
+    return false;
+  }
+  return !!(s3 as { bucket?: string }).bucket;
+}
+
+/**
+ * Whether a database connection is configured.
+ *
+ * Note "configured", not "reachable": an unreachable but configured database is
+ * an ERROR, never a reason to quietly store files somewhere else. Mongoose fails
+ * the boot on its own in that case, which is the behaviour we want — silently
+ * degrading to the local disk would scatter a project's files across two stores
+ * during an outage and leave no trace of which file went where.
+ */
+export function hasDatabaseConfig(config?: Partial<IServerOptions>): boolean {
+  return !!config?.mongoose?.uri;
+}
+
+/**
+ * Decide which storage driver to use.
+ *
+ * An EXPLICIT `file.storage` always wins and is never second-guessed here —
+ * whether the chosen store is actually reachable is asserted separately, at
+ * boot, by `assertFileStorageAvailable()`. That split matters: this function
+ * answers "what did the project ask for", not "did it work".
+ *
+ * Without an explicit value the default is derived, most capable first:
+ *
+ *   1. `s3`         — when the S3 config names a bucket
+ *   2. `gridfs`     — when a database is configured
+ *   3. `filesystem` — when neither is (today a theoretical case: `CoreModule`
+ *                     always registers Mongoose, so a project without a database
+ *                     does not boot at all)
+ *
+ * @param config the merged server configuration
+ */
+export function resolveFileStorage(config?: Partial<IServerOptions>): FileStorageResolution {
+  const configured = config?.file?.storage;
+
+  if (configured !== undefined) {
+    if (!FILE_STORAGE_DRIVERS.includes(configured as FileStorageDriver)) {
+      throw new Error(
+        `Invalid file.storage: ${JSON.stringify(configured)}. ` +
+          `Expected one of ${FILE_STORAGE_DRIVERS.map((d) => `'${d}'`).join(', ')}.`,
+      );
+    }
+    return {
+      driver: configured as FileStorageDriver,
+      explicit: true,
+      reason: `file.storage is set to '${configured}'`,
+    };
+  }
+
+  if (hasUsableS3Config(config)) {
+    return { driver: 's3', explicit: false, reason: 's3.bucket is configured' };
+  }
+
+  if (hasDatabaseConfig(config)) {
+    return { driver: 'gridfs', explicit: false, reason: 'a database is configured and no S3 bucket is' };
+  }
+
+  return {
+    driver: 'filesystem',
+    explicit: false,
+    reason: 'neither an S3 bucket nor a database is configured',
+  };
+}
+
+/**
+ * Fail the boot when the resolved driver cannot actually be used.
+ *
+ * This is the deliberate opposite of the previous behaviour, which silently fell
+ * back to GridFS whenever S3 was selected but unavailable. That failure mode is
+ * the worst kind: the application keeps working, so nothing looks broken, while
+ * files land in a store the operator does not believe they are in — and no
+ * migration path exists afterwards, because nobody knows which file went where.
+ *
+ * A misconfiguration should stop the process at boot, where it is cheap.
+ *
+ * Both an explicit and a derived choice are enforced — only the message differs.
+ * A derived one is not automatically safe: `s3.bucket` in the config makes S3
+ * the default, but the bytes still go nowhere unless the project's own
+ * `FileService` forwards `s3Service` to `super()`.
+ *
+ * @param resolution result of `resolveFileStorage()`
+ * @param available  whether the driver's backing service reports itself usable
+ */
+export function assertFileStorageAvailable(resolution: FileStorageResolution, available: boolean): void {
+  if (available) {
+    return;
+  }
+
+  if (!resolution.explicit) {
+    // A derived driver can still be unusable — the commonest case being an `s3`
+    // block that names a bucket while the project's own FileService never
+    // forwards `s3Service` to `super()`, so the driver has nothing to write
+    // through. Failing here is the point: the alternative is files silently
+    // landing in GridFS while the operator reads the config and believes S3.
+    throw new Error(
+      `File storage '${resolution.driver}' was selected automatically (${resolution.reason}) but is not available. ` +
+        'Either make it available (for S3: forward `{ configService, s3Service }` to `super()` in your FileService ' +
+        'and install `@aws-sdk/client-s3`), or pin a different driver with `file.storage`.',
+    );
+  }
+
+  const hint =
+    resolution.driver === 's3'
+      ? 'Configure `s3` (bucket, credentials/endpoint) and install `@aws-sdk/client-s3`, or choose a different `file.storage`.'
+      : `Check the configuration for the '${resolution.driver}' driver, or choose a different \`file.storage\`.`;
+
+  throw new Error(`file.storage is set to '${resolution.driver}', but that storage is not available. ${hint}`);
+}
+
+/**
+ * Log the resolved driver once, so the store in use is visible in the boot log
+ * rather than having to be inferred from where files stop appearing.
+ */
+export function logFileStorage(resolution: FileStorageResolution): void {
+  const how = resolution.explicit ? 'configured' : 'defaulted';
+  logger.log(`File storage: ${resolution.driver} (${how} — ${resolution.reason})`);
+}

package/src/core/modules/file/filesystem-file.helper.ts

@@ -0,0 +1,184 @@
+import { createReadStream, createWriteStream } from 'fs';
+import { mkdir, rm, stat } from 'fs/promises';
+import { Types } from 'mongoose';
+import * as path from 'path';
+import { pipeline } from 'stream/promises';
+import { Readable } from 'stream';
+
+import {
+  ensureFilenameIndex,
+  FileCollection,
+  FileMetadataInfo,
+  findMetadata,
+  findMetadataById,
+  findMetadataByName,
+} from './file-metadata.helper';
+import { streamToBuffer } from './s3-file.helper';
+
+/** Metadata collection for files stored on the local filesystem */
+export const FILESYSTEM_FILES_COLLECTION = 'filesystem-files';
+
+/** Default directory for the filesystem storage driver */
+export const DEFAULT_FILESYSTEM_DIR = 'uploads/files';
+
+/**
+ * Metadata of a file stored on the local filesystem.
+ *
+ * Alias of the shared {@link FileMetadataInfo} — same document as `S3FileInfo` and,
+ * in its first six fields, as a GridFS `fs.files` document, which is what lets
+ * `prepareOutput()` map all three onto `CoreFileInfo` unchanged.
+ */
+export type FilesystemFileInfo = FileMetadataInfo;
+
+/**
+ * Helper for files stored on the local filesystem with their metadata in MongoDB.
+ *
+ * Counterpart of `GridFSHelper` and `S3FileHelper`: same operations, the local
+ * disk as the byte store and `filesystem-files` as the metadata store.
+ *
+ * WHY THE METADATA STILL LIVES IN MONGO: filename, content type, length and the
+ * custom `metadata` a per-file authorization rule reads have to be queryable —
+ * `findFileInfo()` filters and pages over them, and `checkRights()` reads them
+ * per request. A directory listing answers none of that, and sidecar files would
+ * reinvent an index that the database already is. So this driver moves the
+ * BYTES off the database, not the bookkeeping.
+ *
+ * OPERATIONAL CONSEQUENCE: the directory is pod-local. Two replicas do not share
+ * it, and a container restart discards it unless the path is a mounted volume.
+ * That makes this the right driver for a single-instance deployment or a real
+ * volume, and the wrong one for a horizontally scaled service — use S3 there.
+ */
+export class FilesystemFileHelper {
+  /**
+   * Resolve the absolute path of a stored file.
+   *
+   * The id is an ObjectId, so its hex form cannot contain a path separator or
+   * `..` — the join can never escape the base directory. Callers must not pass
+   * a user-supplied filename here.
+   */
+  static filePath(directory: string, id: string | Types.ObjectId): string {
+    const objectId = typeof id === 'string' ? new Types.ObjectId(id) : id;
+    return path.join(path.resolve(directory), objectId.toHexString());
+  }
+
+  /**
+   * Store a file on disk and record its metadata.
+   *
+   * The written size is verified via `stat()` before the metadata document is
+   * written, so a file info is never returned for bytes that did not fully
+   * arrive — the same guarantee `GridFSHelper` gives by reading the file
+   * document back, and `S3FileHelper` by issuing a HEAD.
+   *
+   * On any failure the partial file is removed before the error propagates,
+   * otherwise a failed upload would leave an orphan the metadata never names.
+   */
+  static async writeFile(
+    directory: string,
+    collection: FileCollection,
+    options: {
+      body?: Readable;
+      buffer?: Buffer;
+      contentType?: string;
+      filename: string;
+      metadata?: Record<string, any>;
+    },
+  ): Promise<FilesystemFileInfo> {
+    const _id = new Types.ObjectId();
+    const target = FilesystemFileHelper.filePath(directory, _id);
+
+    await mkdir(path.dirname(target), { recursive: true });
+
+    try {
+      if (options.buffer) {
+        await pipeline(Readable.from(options.buffer), createWriteStream(target));
+      } else if (options.body) {
+        await pipeline(options.body, createWriteStream(target));
+      } else {
+        throw new Error('FilesystemFileHelper.writeFile requires either `buffer` or `body`');
+      }
+
+      const stats = await stat(target);
+      if (!stats.size && (options.buffer?.length || 0) > 0) {
+        throw new Error(`File ${_id.toHexString()} was written empty`);
+      }
+
+      // On the WRITE path, not the read path: createIndex creates the collection, so
+      // ensuring it when reading gave a GridFS-only deployment an empty
+      // `filesystem-files`. Here the collection is about to exist anyway. Never throws.
+      await ensureFilenameIndex(collection);
+
+      const fileInfo: FilesystemFileInfo = {
+        _id,
+        contentType: options.contentType,
+        filename: options.filename,
+        length: stats.size,
+        ...(options.metadata ? { metadata: options.metadata } : {}),
+        // Records WHERE the bytes went, so a reader never has to probe all three
+        // stores to find out. Legacy documents lack it and are handled by probing.
+        storage: 'filesystem',
+        uploadDate: new Date(),
+      };
+      await collection.insertOne(fileInfo as any);
+      return fileInfo;
+    } catch (error) {
+      await rm(target, { force: true }).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  /**
+   * Find file metadata by ID
+   */
+  static async findFileById(
+    collection: FileCollection,
+    id: string | Types.ObjectId,
+  ): Promise<FilesystemFileInfo | null> {
+    return findMetadataById(collection, id);
+  }
+
+  /**
+   * Find file metadata by filename
+   */
+  static async findFileByName(collection: FileCollection, filename: string): Promise<FilesystemFileInfo | null> {
+    return findMetadataByName(collection, filename);
+  }
+
+  /**
+   * Find files with filter and options
+   */
+  static async findFiles(
+    collection: FileCollection,
+    filter: any = {},
+    options: any = {},
+  ): Promise<FilesystemFileInfo[]> {
+    return findMetadata(collection, filter, options);
+  }
+
+  /**
+   * Delete a file from disk and remove its metadata.
+   *
+   * The metadata goes last: a missing file with a metadata row answers 404
+   * through the normal "file document without bytes" path, while a stored file
+   * with no metadata row is invisible to every lookup and can never be cleaned
+   * up through the API.
+   */
+  static async deleteFile(directory: string, collection: FileCollection, id: string | Types.ObjectId): Promise<void> {
+    const objectId = typeof id === 'string' ? new Types.ObjectId(id) : id;
+    await rm(FilesystemFileHelper.filePath(directory, objectId), { force: true });
+    await collection.deleteOne({ _id: objectId });
+  }
+
+  /**
+   * Get the download stream of a file
+   */
+  static getStream(directory: string, id: string | Types.ObjectId): Readable {
+    return createReadStream(FilesystemFileHelper.filePath(directory, id));
+  }
+
+  /**
+   * Get the content of a file as a buffer
+   */
+  static async getBuffer(directory: string, id: string | Types.ObjectId): Promise<Buffer> {
+    return streamToBuffer(FilesystemFileHelper.getStream(directory, id));
+  }
+}

package/src/core/modules/file/interfaces/file-service-options.interface.ts

@@ -4,5 +4,19 @@
 export interface FileServiceOptions {
   currentUser?: { hasRole: (roles: string[]) => boolean; id: any };
   force?: boolean;
+
+  /**
+   * Custom GridFS metadata to store alongside the file (create operations only).
+   *
+   * This is what a per-file authorization rule is meant to be built on: write
+   * an owner or tenant here at upload time, then compare against it in an
+   * overridden `checkRights()` (use `getRawFileInfo()` to read it back — the
+   * public `getFileInfo()` strips restricted fields).
+   *
+   * `contentType` is reserved: `GridFSHelper.writeFileFromStream` stores the
+   * file's content type under that key and will overwrite whatever is passed.
+   */
+  metadata?: Record<string, any>;
+
   roles?: string | string[];
 }

package/src/core/modules/file/interfaces/file-upload.interface.ts

@@ -1,10 +1,26 @@
 import { WriteStream } from 'fs-capacitor';
 import { Readable } from 'stream';
 
+/**
+ * What a file store actually needs from an upload.
+ *
+ * `FileUpload` additionally carries the graphql-upload `capacitor`, which no
+ * store touches — so requiring the full type would exclude every upload that did
+ * not arrive over GraphQL (a multer REST upload being the case in point, see
+ * `multerFileToUpload()`). `FileUpload` satisfies this structurally, so both
+ * paths share a single service signature.
+ */
+export interface FileUploadSource {
+  createReadStream: (options?: unknown) => Readable;
+  encoding?: string;
+  filename: string;
+  mimetype: string;
+}
+
 /**
  * Interface for file uploads
  */
-export interface FileUpload {
+export interface FileUpload extends FileUploadSource {
   /**
    * A private implementation detail that shouldn’t be used outside
    */