@nocobase/plugin-file-manager 2.2.0-beta.13 → 2.2.0-beta.14

package/dist/server/file-access.js

@@ -0,0 +1,134 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var file_access_exports = {};
+__export(file_access_exports, {
+  createFileAccessMiddleware: () => createFileAccessMiddleware
+});
+module.exports = __toCommonJS(file_access_exports);
+var import_utils = require("./utils");
+const DEFAULT_APP_NAME = "main";
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/;
+function stripPublicPath(path) {
+  const publicPath = (0, import_utils.trimPublicPath)(process.env.APP_PUBLIC_PATH);
+  if (publicPath && (path === publicPath || path.startsWith(`${publicPath}/`))) {
+    return path.slice(publicPath.length) || "/";
+  }
+  return path;
+}
+function parseFileAccessPath(path) {
+  const normalizedPath = stripPublicPath(path);
+  const segments = normalizedPath.split("/").filter(Boolean);
+  if (segments[0] !== "files") {
+    return null;
+  }
+  if (segments.length !== 5) {
+    throw Object.assign(new Error("Invalid file URL"), { status: 404 });
+  }
+  try {
+    const fileIdSegment = decodeURIComponent(segments[4]);
+    const extnameIndex = fileIdSegment.lastIndexOf(".");
+    const extname = extnameIndex > 0 ? (0, import_utils.normalizeFileAccessExtname)(fileIdSegment.slice(extnameIndex)) : "";
+    const params = {
+      appName: decodeURIComponent(segments[1]),
+      dataSourceKey: decodeURIComponent(segments[2]),
+      collectionName: decodeURIComponent(segments[3]),
+      id: extname ? fileIdSegment.slice(0, extnameIndex) : fileIdSegment,
+      extname: extname || void 0
+    };
+    if (!IDENTIFIER_PATTERN.test(params.appName) || !IDENTIFIER_PATTERN.test(params.dataSourceKey) || !IDENTIFIER_PATTERN.test(params.collectionName)) {
+      throw Object.assign(new Error("Invalid file URL"), { status: 404 });
+    }
+    return params;
+  } catch (error) {
+    throw Object.assign(new Error("Invalid file URL"), { status: 404 });
+  }
+}
+function getApiBasePath(dataSource) {
+  var _a, _b;
+  return (0, import_utils.trimPublicPath)((_b = (_a = dataSource.resourceManager) == null ? void 0 : _a.options) == null ? void 0 : _b.prefix);
+}
+function createFileAccessMiddleware(plugin) {
+  return async function handleFileAccess(ctx, next) {
+    const pathParams = parseFileAccessPath(ctx.path);
+    if (!pathParams) {
+      return next();
+    }
+    if (!["GET", "HEAD"].includes(ctx.method)) {
+      return ctx.throw(405);
+    }
+    const temporaryAccessToken = ctx.query["temporaryAccessToken"];
+    const params = {
+      ...pathParams,
+      preview: ctx.query.preview === "1",
+      temporaryAccess: typeof temporaryAccessToken === "string",
+      temporaryAccessToken: typeof temporaryAccessToken === "string" ? temporaryAccessToken : void 0
+    };
+    if (params.preview && params.temporaryAccess) {
+      return ctx.throw(404);
+    }
+    if (params.appName !== (plugin.app.name || DEFAULT_APP_NAME)) {
+      return ctx.throw(404);
+    }
+    const dataSource = plugin.app.dataSourceManager.get(params.dataSourceKey);
+    if (!dataSource) {
+      return ctx.throw(404);
+    }
+    const originalPath = ctx.path;
+    const originalDataSourceHeader = ctx.req.headers["x-data-source"];
+    const originalDb = ctx.db;
+    const originalOptionalAuth = ctx.state.optionalAuth;
+    const originalFileAccess = ctx.state.fileAccess;
+    const originalSkipAuthCheck = ctx.skipAuthCheck;
+    try {
+      ctx.path = `${getApiBasePath(dataSource)}/${encodeURIComponent(
+        params.collectionName
+      )}:getFile/${encodeURIComponent(params.id)}`;
+      ctx.req.headers["x-data-source"] = params.dataSourceKey;
+      ctx.db = plugin.app.db;
+      ctx.state.optionalAuth = !params.temporaryAccess;
+      ctx.skipAuthCheck = params.temporaryAccess ? true : originalSkipAuthCheck;
+      ctx.state.fileAccess = params;
+      await plugin.app.dataSourceManager.middleware()(ctx, async () => {
+      });
+    } finally {
+      ctx.path = originalPath;
+      if (originalDataSourceHeader === void 0) {
+        delete ctx.req.headers["x-data-source"];
+      } else {
+        ctx.req.headers["x-data-source"] = originalDataSourceHeader;
+      }
+      ctx.db = originalDb;
+      ctx.state.optionalAuth = originalOptionalAuth;
+      ctx.state.fileAccess = originalFileAccess;
+      ctx.skipAuthCheck = originalSkipAuthCheck;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFileAccessMiddleware
+});

package/dist/server/index.d.ts

@@ -9,6 +9,7 @@
 import { StorageEngine } from 'multer';
 export * from '../constants';
 export { AttachmentModel, default, PluginFileManagerServer, StorageModel } from './server';
+export type { FileAccessAuthorizeParams, FileAccessAuthorizer } from './server';
 export { cloudFilenameGetter } from './utils';
-export { StorageType, GetFileStreamOptions } from './storages';
+export { appendDownloadResponse, getDownloadContentDisposition, StorageType, GetFileStreamOptions, GetFileURLOptions, } from './storages';
 export { StorageEngine };

package/dist/server/index.js

@@ -39,12 +39,15 @@ var server_exports = {};
 __export(server_exports, {
   AttachmentModel: () => import_server.AttachmentModel,
   GetFileStreamOptions: () => import_storages.GetFileStreamOptions,
+  GetFileURLOptions: () => import_storages.GetFileURLOptions,
   PluginFileManagerServer: () => import_server.PluginFileManagerServer,
   StorageEngine: () => import_multer.StorageEngine,
   StorageModel: () => import_server.StorageModel,
   StorageType: () => import_storages.StorageType,
+  appendDownloadResponse: () => import_storages.appendDownloadResponse,
   cloudFilenameGetter: () => import_utils.cloudFilenameGetter,
-  default: () => import_server.default
+  default: () => import_server.default,
+  getDownloadContentDisposition: () => import_storages.getDownloadContentDisposition
 });
 module.exports = __toCommonJS(server_exports);
 var import_multer = require("multer");
@@ -56,10 +59,13 @@ var import_storages = require("./storages");
 0 && (module.exports = {
   AttachmentModel,
   GetFileStreamOptions,
+  GetFileURLOptions,
   PluginFileManagerServer,
   StorageEngine,
   StorageModel,
   StorageType,
+  appendDownloadResponse,
   cloudFilenameGetter,
+  getDownloadContentDisposition,
   ...require("../constants")
 });

package/dist/server/resolve-file-access-filter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import type { Context } from '@nocobase/actions';
+import type { Collection } from '@nocobase/database';
+export declare function resolveFileAccessFilter(ctx: Context, collection: Collection, filter: object): Promise<object>;

package/dist/server/resolve-file-access-filter.js

@@ -0,0 +1,63 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var resolve_file_access_filter_exports = {};
+__export(resolve_file_access_filter_exports, {
+  resolveFileAccessFilter: () => resolveFileAccessFilter
+});
+module.exports = __toCommonJS(resolve_file_access_filter_exports);
+var import_acl = require("@nocobase/acl");
+var import_lodash = __toESM(require("lodash"));
+async function resolveFileAccessFilter(ctx, collection, filter) {
+  try {
+    const permission = await ctx.dataSource.acl.resolveActionParams(ctx, {
+      resourceName: collection.name,
+      actionName: "view",
+      params: { filter }
+    });
+    const mergedParams = permission.mergedParams || { filter };
+    return import_lodash.default.cloneDeep(mergedParams.filter || filter);
+  } catch (error) {
+    if (error instanceof import_acl.NoPermissionError) {
+      ctx.throw(403, "No permissions");
+    }
+    throw error;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveFileAccessFilter
+});

package/dist/server/server.d.ts

@@ -7,12 +7,14 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 /// <reference types="node" />
+import type { Context } from '@nocobase/actions';
 import { Model, Transactionable } from '@nocobase/database';
 import { Plugin } from '@nocobase/server';
 import { Registry } from '@nocobase/utils';
 import { Readable } from 'stream';
-import { AttachmentModel, GetFileStreamOptions, StorageClassType, StorageModel } from './storages';
+import { AttachmentModel, GetFileStreamOptions, GetFileURLOptions, StorageClassType, StorageModel } from './storages';
 export type * from './storages';
+type AttachmentRecord = Model & AttachmentModel;
 export type FileRecordOptions = {
     collectionName: string;
     filePath: string;
@@ -26,12 +28,26 @@ export type UploadFileOptions = {
     subPath?: string;
     documentRoot?: string;
 };
+export type FileAccessAuthorizeParams = {
+    appName: string;
+    dataSourceKey: string;
+    collectionName: string;
+    id: string;
+    preview: boolean;
+};
+export type FileAccessAuthorizer = {
+    name: string;
+    authorize: (ctx: Context, params: FileAccessAuthorizeParams) => Promise<boolean | null | undefined> | boolean | null | undefined;
+};
 export declare class PluginFileManagerServer extends Plugin {
     storageTypes: Registry<StorageClassType>;
     storagesCache: Map<string | number, StorageModel>;
+    protected fileAccessAuthorizers: Registry<FileAccessAuthorizer>;
     static staticImport(): Promise<void>;
     afterDestroy: (record: Model, options: any) => Promise<void>;
     registerStorageType(type: string, Type: StorageClassType): void;
+    registerFileAccessAuthorizer(authorizer: FileAccessAuthorizer): void;
+    authorizeFileAccess(ctx: Context, params: FileAccessAuthorizeParams): Promise<boolean>;
     createFileRecord(options: FileRecordOptions): Promise<any>;
     parseStorage(instance: any): any;
     uploadFile(options: UploadFileOptions): Promise<{
@@ -51,7 +67,12 @@ export declare class PluginFileManagerServer extends Plugin {
     handleSyncMessage(message: any): Promise<void>;
     beforeLoad(): Promise<void>;
     load(): Promise<void>;
-    getFileURL(file: AttachmentModel, preview?: boolean): Promise<any>;
+    setFileResponseURLs(record: AttachmentRecord, collectionName: string): Promise<void>;
+    getPermanentFileURL(file: AttachmentModel, preview?: boolean, options?: {
+        dataSourceKey?: string;
+        collectionName?: string;
+    }): any;
+    getFileURL(file: AttachmentModel, preview?: boolean, options?: GetFileURLOptions): Promise<any>;
     isPublicAccessStorage(storageName: any): Promise<boolean>;
     getFileStream(file: AttachmentModel, options?: GetFileStreamOptions): Promise<{
         stream: Readable;

package/dist/server/server.js

@@ -48,6 +48,7 @@ var import_server = require("@nocobase/server");
 var import_utils = require("@nocobase/utils");
 var import_constants = require("../constants");
 var import_actions = __toESM(require("./actions"));
+var import_file_access = require("./file-access");
 var import_attachment_interface = require("./interfaces/attachment-interface");
 var import_ali_oss = __toESM(require("./storages/ali-oss"));
 var import_local = __toESM(require("./storages/local"));
@@ -55,7 +56,20 @@ var import_s3 = __toESM(require("./storages/s3"));
 var import_tx_cos = __toESM(require("./storages/tx-cos"));
 var import_utils2 = require("./utils");
 var import_repair_filenames = require("./commands/repair-filenames");
+var import_temporary_access = require("./temporary-access");
 const DEFAULT_STORAGE_TYPE = import_constants.STORAGE_TYPE_LOCAL;
+const DEFAULT_APP_NAME = "main";
+const DEFAULT_DATA_SOURCE_KEY = "main";
+class FileModel extends import_database.Model {
+  toJSON() {
+    const values = super.toJSON();
+    const local = this.get("local");
+    if (typeof local === "boolean") {
+      values.local = local;
+    }
+    return values;
+  }
+}
 class FileDeleteError extends Error {
   data;
   constructor(message, data) {
@@ -64,9 +78,15 @@ class FileDeleteError extends Error {
     this.data = data;
   }
 }
+function supportsFileStream(dataSource) {
+  return Boolean(
+    dataSource && typeof dataSource === "object" && typeof dataSource.getFileStream === "function"
+  );
+}
 class PluginFileManagerServer extends import_server.Plugin {
   storageTypes = new import_utils.Registry();
   storagesCache = /* @__PURE__ */ new Map();
+  fileAccessAuthorizers = new import_utils.Registry();
   static async staticImport() {
     import_server.Application.addCommand(import_repair_filenames.registerRepairFilenamesCommand);
   }
@@ -99,6 +119,17 @@ class PluginFileManagerServer extends import_server.Plugin {
   registerStorageType(type, Type) {
     this.storageTypes.register(type, Type);
   }
+  registerFileAccessAuthorizer(authorizer) {
+    this.fileAccessAuthorizers.register(authorizer.name, authorizer);
+  }
+  async authorizeFileAccess(ctx, params) {
+    for (const authorizer of this.fileAccessAuthorizers.getValues()) {
+      if (await authorizer.authorize(ctx, params)) {
+        return true;
+      }
+    }
+    return false;
+  }
   async createFileRecord(options) {
     const { values, storageName, subPath, collectionName, filePath, transaction } = options;
     const collection = this.db.getCollection(collectionName);
@@ -190,7 +221,8 @@ class PluginFileManagerServer extends import_server.Plugin {
     }
   }
   async beforeLoad() {
-    this.db.registerModels({ FileModel: import_database.Model });
+    (0, import_temporary_access.getTemporaryFileAccessExpiresIn)();
+    this.db.registerModels({ FileModel });
     this.db.on("beforeDefineCollection", (options) => {
       if (options.template === "file") {
         options.model = "FileModel";
@@ -200,7 +232,27 @@ class PluginFileManagerServer extends import_server.Plugin {
       if (collection.options.template !== "file") {
         return;
       }
+      collection.setField("local", {
+        type: "virtual",
+        hidden: true
+      });
+      const idField = collection.getField("id");
+      if (idField) {
+        idField.options.deletable = false;
+        idField.options.updatable = false;
+      }
+      const extnameField = collection.getField("extname");
+      if (extnameField) {
+        extnameField.options.updatable = false;
+      }
+      collection.model.afterCreate(async (model) => {
+        await this.setFileResponseURLs(model, collection.name);
+      });
       collection.model.beforeUpdate((model) => {
+        if (model.changed("extname")) {
+          model.set("extname", model.previous("extname"));
+          model.changed("extname", false);
+        }
         if (!model.changed("url") || !model.changed("preview")) {
           return;
         }
@@ -287,6 +339,7 @@ class PluginFileManagerServer extends import_server.Plugin {
       }
     });
     this.app.db.interfaceManager.registerInterfaceType("attachment", import_attachment_interface.AttachmentInterface);
+    this.app.use((0, import_file_access.createFileAccessMiddleware)(this), { tag: "fileAccess", before: "dataSource", after: "dataWrapping" });
     this.db.on("afterFind", async (instances) => {
       var _a, _b, _c;
       if (!instances) {
@@ -298,28 +351,59 @@ class PluginFileManagerServer extends import_server.Plugin {
         const collection = this.db.getCollection(name);
         if ((collection == null ? void 0 : collection.name) === "attachments" || ((_c = collection == null ? void 0 : collection.options) == null ? void 0 : _c.template) === "file") {
           for (const record of records) {
-            const url = await this.getFileURL(record);
-            const previewUrl = await this.getFileURL(record, true);
-            record.set("url", url);
-            record.set("preview", previewUrl);
-            record.dataValues.preview = previewUrl;
+            await this.setFileResponseURLs(record, collection.name);
           }
         }
       }
     });
   }
-  async getFileURL(file, preview = false) {
+  async setFileResponseURLs(record, collectionName) {
+    const url = this.getPermanentFileURL(record, false, { collectionName });
+    const previewUrl = this.getPermanentFileURL(record, true, { collectionName });
+    const storage = this.storagesCache.get(record.get("storageId"));
+    record.set("url", url);
+    record.set("preview", previewUrl);
+    record.dataValues.preview = previewUrl;
+    if (storage == null ? void 0 : storage.type) {
+      record.set("local", storage.type === import_constants.STORAGE_TYPE_LOCAL);
+    }
+  }
+  getPermanentFileURL(file, preview = false, options = {}) {
     if (!file.storageId) {
       return (0, import_utils2.encodeURL)(file.url);
     }
+    const publicPath = (0, import_utils2.getFilePublicBasePath)();
+    const appName = this.app.name || DEFAULT_APP_NAME;
+    const dataSourceKey = options.dataSourceKey || DEFAULT_DATA_SOURCE_KEY;
+    const collectionName = options.collectionName || (0, import_utils2.getRecordCollectionName)(file);
+    const id = (0, import_utils2.getFileAccessPathSegment)(file.id, file.extname);
+    const url = `${publicPath}/files/${encodeURIComponent(String(appName))}/${encodeURIComponent(
+      String(dataSourceKey)
+    )}/${encodeURIComponent(String(collectionName))}/${id}`;
+    return preview ? `${url}?preview=1` : url;
+  }
+  async getFileURL(file, preview = false, options = {}) {
+    if (!file.storageId) {
+      return (0, import_utils2.encodeURL)(file.url);
+    }
+    const storageFile = (0, import_utils2.getFilePlainObject)(file);
+    if ((0, import_utils2.isPermanentFileAccessURL)(storageFile.url, storageFile, this.app.name || DEFAULT_APP_NAME)) {
+      storageFile.url = void 0;
+    }
     const storage = this.storagesCache.get(file.storageId);
     if (!storage) {
-      return (0, import_utils2.encodeURL)(file.url);
+      throw new Error("[file-manager] no linked or default storage provided");
     }
     const storageType = this.storageTypes.get(storage.type);
+    if (!storageType) {
+      throw new Error(`[file-manager] storage type "${storage.type}" is not defined`);
+    }
     return new storageType(storage).getFileURL(
-      file,
-      Boolean(file.mimetype && (0, import_mime_match.default)(file.mimetype, "image/*") && preview && storage.options.thumbnailRule)
+      storageFile,
+      Boolean(
+        storageFile.mimetype && (0, import_mime_match.default)(storageFile.mimetype, "image/*") && preview && storage.options.thumbnailRule
+      ),
+      options
     );
   }
   async isPublicAccessStorage(storageName) {
@@ -345,6 +429,14 @@ class PluginFileManagerServer extends import_server.Plugin {
     return !!((_a = storage.options) == null ? void 0 : _a.public);
   }
   async getFileStream(file, options) {
+    var _a;
+    const dataSourceKey = (_a = file.source) == null ? void 0 : _a.dataSourceKey;
+    if (dataSourceKey && dataSourceKey !== "main") {
+      const dataSource = this.app.dataSourceManager.get(dataSourceKey);
+      if (supportsFileStream(dataSource)) {
+        return dataSource.getFileStream(file, options);
+      }
+    }
     if (!file.storageId) {
       throw new Error("File storageId not found");
     }

package/dist/server/storages/ali-oss.d.ts

@@ -6,7 +6,7 @@
  * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
-import { AttachmentModel, StorageType } from '.';
+import { AttachmentModel, GetFileURLOptions, StorageType } from '.';
 declare function getRandomFilename(req: any, file: any, cb: any): void;
 declare class AliYunOssStorage {
     client: any;
@@ -34,6 +34,7 @@ export default class extends StorageType {
         };
     };
     make(): AliYunOssStorage;
+    getFileURL(file: AttachmentModel, preview?: boolean, options?: GetFileURLOptions): Promise<any>;
     exists(record: AttachmentModel): Promise<boolean>;
     copy(source: AttachmentModel, target: AttachmentModel): Promise<void>;
     delete(records: AttachmentModel[]): Promise<[number, AttachmentModel[]]>;

package/dist/server/storages/ali-oss.js

@@ -123,6 +123,18 @@ class ali_oss_default extends import__.StorageType {
       filename: (0, import_utils.cloudFilenameGetter)(this.storage)
     });
   }
+  async getFileURL(file, preview = false, options = {}) {
+    if (!options.download) {
+      return super.getFileURL(file, preview, options);
+    }
+    const { client } = this.make();
+    return client.signatureUrl((0, import_utils.getFileKey)(file), {
+      expires: this.storage.options.signedUrlExpires || 900,
+      response: {
+        "content-disposition": (0, import__.getDownloadContentDisposition)(file.filename)
+      }
+    });
+  }
   async exists(record) {
     const { client } = this.make();
     try {

package/dist/server/storages/index.d.ts

@@ -27,10 +27,18 @@ export interface AttachmentModel {
     id?: number;
     title: string;
     filename: string;
+    extname?: string;
     mimetype?: string;
     path: string;
     url?: string;
-    storageId: number;
+    storageId?: number | null;
+    source?: {
+        dataSourceKey?: string;
+        collectionName?: string;
+        field?: string;
+        documentCache?: boolean;
+        trustworthy?: boolean;
+    };
 }
 export declare abstract class StorageType {
     storage: StorageModel;
@@ -52,7 +60,7 @@ export declare abstract class StorageType {
         meta: {};
         storageId: number;
     };
-    getFileURL(file: AttachmentModel, preview?: boolean): string | Promise<string>;
+    getFileURL(file: AttachmentModel, preview?: boolean, options?: GetFileURLOptions): string | Promise<string>;
     getFileStream(file: AttachmentModel, options?: GetFileStreamOptions): Promise<{
         stream: Readable;
         contentType?: string;
@@ -64,3 +72,8 @@ export type StorageClassType = {
 export type GetFileStreamOptions = {
     requestOptions?: any;
 };
+export type GetFileURLOptions = {
+    download?: boolean;
+};
+export declare function getDownloadContentDisposition(filename: string): string;
+export declare function appendDownloadResponse(url: string, filename: string): string;

package/dist/server/storages/index.js

@@ -36,7 +36,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var storages_exports = {};
 __export(storages_exports, {
-  StorageType: () => StorageType
+  StorageType: () => StorageType,
+  appendDownloadResponse: () => appendDownloadResponse,
+  getDownloadContentDisposition: () => getDownloadContentDisposition
 });
 module.exports = __toCommonJS(storages_exports);
 var import_axios = __toESM(require("axios"));
@@ -79,12 +81,12 @@ class StorageType {
     };
     return data;
   }
-  getFileURL(file, preview) {
+  getFileURL(file, preview, options = {}) {
     if (file.url && (0, import_utils.isURL)(file.url)) {
       if (preview && this.storage.options.thumbnailRule) {
         return (0, import_utils2.encodeURL)(file.url) + this.storage.options.thumbnailRule;
       }
-      return (0, import_utils2.encodeURL)(file.url);
+      return options.download ? appendDownloadResponse(file.url, file.filename) : (0, import_utils2.encodeURL)(file.url);
     }
     const keys = [
       this.storage.baseUrl,
@@ -92,7 +94,8 @@ class StorageType {
       (0, import_utils2.ensureUrlEncoded)(file.filename),
       preview && this.storage.options.thumbnailRule
     ].filter(Boolean);
-    return (0, import_url_join.default)(keys);
+    const url = (0, import_url_join.default)(keys);
+    return options.download ? appendDownloadResponse(url, file.filename) : url;
   }
   async getFileStream(file, options) {
     var _a;
@@ -116,7 +119,27 @@ class StorageType {
     }
   }
 }
+function getDownloadContentDisposition(filename) {
+  const name = import_path.default.basename(filename || "file");
+  const fallback = name.replace(/[^\x20-\x7e]/g, "_").replace(/["\\]/g, "_") || "file";
+  const encoded = encodeURIComponent(name).replace(
+    /['()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+  return `attachment; filename="${fallback}"; filename*=UTF-8''${encoded}`;
+}
+function appendDownloadResponse(url, filename) {
+  try {
+    const target = new URL(url);
+    target.searchParams.set("response-content-disposition", getDownloadContentDisposition(filename));
+    return target.toString();
+  } catch (error) {
+    return url;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  StorageType
+  StorageType,
+  appendDownloadResponse,
+  getDownloadContentDisposition
 });

package/dist/server/storages/local.d.ts

@@ -9,7 +9,7 @@
 /// <reference types="node" />
 import multer from 'multer';
 import type { Readable } from 'stream';
-import { AttachmentModel, StorageType } from '.';
+import { AttachmentModel, GetFileURLOptions, StorageType } from '.';
 export declare function normalizeLocalStoragePath(storagePath?: unknown): string;
 export declare function getDocumentRoot(storage: any): string;
 export declare function resolveSafePath(documentRoot: string, filePath?: string, filename?: string): string;
@@ -34,7 +34,7 @@ export default class extends StorageType {
     exists(record: AttachmentModel): Promise<boolean>;
     copy(source: AttachmentModel, target: AttachmentModel): Promise<void>;
     delete(records: AttachmentModel[]): Promise<[number, AttachmentModel[]]>;
-    getFileURL(file: AttachmentModel, preview?: boolean): Promise<any>;
+    getFileURL(file: AttachmentModel, preview?: boolean, options?: GetFileURLOptions): Promise<any>;
     getFileStream(file: AttachmentModel): Promise<{
         stream: Readable;
         contentType?: string;