@nocobase/plugin-file-manager 2.1.0-beta.8 → 2.2.0-alpha.1

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

@@ -90,11 +90,16 @@ class AliYunOssStorage {
       });
     }).catch(cb);
   }
-  _removeFile(req, file, cb) {
+  async _removeFile(req, file, cb) {
     if (!this.client) {
       return cb(ERROR_NO_CLIENT);
     }
-    this.client.delete(file.filename).then((result) => cb(null, result)).catch(cb);
+    try {
+      const result = await this.client.delete(file.filename);
+      cb(null, result);
+    } catch (error) {
+      cb(error);
+    }
   }
 }
 class ali_oss_default extends import__.StorageType {
@@ -118,6 +123,22 @@ class ali_oss_default extends import__.StorageType {
       filename: (0, import_utils.cloudFilenameGetter)(this.storage)
     });
   }
+  async exists(record) {
+    const { client } = this.make();
+    try {
+      await client.head((0, import_utils.getFileKey)(record));
+      return true;
+    } catch (error) {
+      if (["NoSuchKey", "NotFoundError"].includes(error.name)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async copy(source, target) {
+    const { client } = this.make();
+    await client.copy((0, import_utils.getFileKey)(target), (0, import_utils.getFileKey)(source));
+  }
   async delete(records) {
     const { client } = this.make();
     const { deleted } = await client.deleteMulti(records.map(import_utils.getFileKey));

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

@@ -24,6 +24,7 @@ export interface StorageModel {
     settings?: Record<string, any>;
 }
 export interface AttachmentModel {
+    id?: number;
     title: string;
     filename: string;
     mimetype?: string;
@@ -38,6 +39,8 @@ export declare abstract class StorageType {
     constructor(storage: StorageModel);
     abstract make(): StorageEngine;
     abstract delete(records: AttachmentModel[]): [number, AttachmentModel[]] | Promise<[number, AttachmentModel[]]>;
+    exists(record: AttachmentModel): Promise<boolean>;
+    copy(source: AttachmentModel, target: AttachmentModel): Promise<void>;
     getFileKey(record: AttachmentModel): any;
     getFileData(file: any, meta?: {}): {
         title: string;
@@ -50,7 +53,7 @@ export declare abstract class StorageType {
         storageId: number;
     };
     getFileURL(file: AttachmentModel, preview?: boolean): string | Promise<string>;
-    getFileStream(file: AttachmentModel): Promise<{
+    getFileStream(file: AttachmentModel, options?: GetFileStreamOptions): Promise<{
         stream: Readable;
         contentType?: string;
     }>;
@@ -58,3 +61,6 @@ export declare abstract class StorageType {
 export type StorageClassType = {
     new (storage: StorageModel): StorageType;
 } & typeof StorageType;
+export type GetFileStreamOptions = {
+    requestOptions?: any;
+};

package/dist/server/storages/index.js

@@ -52,6 +52,12 @@ class StorageType {
     return {};
   }
   static filenameKey;
+  async exists(record) {
+    throw new Error(`Storage type "${this.storage.type}" does not support object existence checks`);
+  }
+  async copy(source, target) {
+    throw new Error(`Storage type "${this.storage.type}" does not support object copy`);
+  }
   getFileKey(record) {
     return (0, import_utils2.getFileKey)(record);
   }
@@ -88,12 +94,13 @@ class StorageType {
     ].filter(Boolean);
     return (0, import_url_join.default)(keys);
   }
-  async getFileStream(file) {
+  async getFileStream(file, options) {
     var _a;
     try {
       const fileURL = await this.getFileURL(file);
       const requestOptions = {
         ...(_a = this.storage.settings) == null ? void 0 : _a.requestOptions,
+        ...(options == null ? void 0 : options.requestOptions) ?? {},
         responseType: "stream",
         validateStatus: (status) => status === 200,
         timeout: 3e4

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

@@ -10,8 +10,12 @@
 import multer from 'multer';
 import type { Readable } from 'stream';
 import { AttachmentModel, 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;
+export declare function validateLocalStorageConfig(storage: Pick<StorageType['storage'], 'type' | 'options' | 'path'>, { validateDocumentRoot }?: {
+    validateDocumentRoot?: boolean;
+}): void;
 export default class extends StorageType {
     static defaults(): {
         title: string;
@@ -27,6 +31,8 @@ export default class extends StorageType {
         };
     };
     make(): multer.StorageEngine;
+    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>;
     getFileStream(file: AttachmentModel): Promise<{

package/dist/server/storages/local.js

@@ -38,7 +38,9 @@ var local_exports = {};
 __export(local_exports, {
   default: () => local_default,
   getDocumentRoot: () => getDocumentRoot,
-  resolveSafePath: () => resolveSafePath
+  normalizeLocalStoragePath: () => normalizeLocalStoragePath,
+  resolveSafePath: () => resolveSafePath,
+  validateLocalStorageConfig: () => validateLocalStorageConfig
 });
 module.exports = __toCommonJS(local_exports);
 var import_utils = require("@nocobase/utils");
@@ -51,21 +53,64 @@ var import__ = require(".");
 var import_constants = require("../../constants");
 var import_utils2 = require("../utils");
 const DEFAULT_BASE_URL = "/storage/uploads";
+function pathError(message) {
+  const error = new Error(message);
+  error.code = "PATH_TRAVERSAL";
+  return error;
+}
+function isInside(base, target) {
+  const relative = import_path.default.relative(base, target);
+  return !relative.startsWith("..") && !import_path.default.isAbsolute(relative);
+}
+function resolveDocumentRoot(documentRoot) {
+  if (typeof documentRoot !== "string" || !documentRoot || documentRoot.includes("\0")) {
+    throw pathError("Invalid local storage document root");
+  }
+  return (0, import_utils2.normalizeDocumentRoot)(documentRoot);
+}
+function allowedRoots() {
+  var _a;
+  const roots = [(0, import_utils.storagePathJoin)()];
+  const extra = [process.env.LOCAL_STORAGE_DEST, ...((_a = process.env.LOCAL_STORAGE_ALLOWED_ROOTS) == null ? void 0 : _a.split(",")) ?? []];
+  for (const item of extra) {
+    if (item == null ? void 0 : item.trim()) {
+      roots.push(resolveDocumentRoot(item.trim()));
+    }
+  }
+  return roots;
+}
+function normalizeLocalStoragePath(storagePath) {
+  if (storagePath == null || storagePath === "") {
+    return "";
+  }
+  if (typeof storagePath !== "string" || storagePath.includes("\0")) {
+    throw pathError("Invalid local storage path");
+  }
+  return storagePath.replace(/\\/g, "/").replace(/^\/+/, "");
+}
 function getDocumentRoot(storage) {
-  const { documentRoot = process.env.LOCAL_STORAGE_DEST || import_path.default.join(process.cwd(), "storage", "uploads") } = storage.options || {};
-  return import_path.default.resolve(import_path.default.isAbsolute(documentRoot) ? documentRoot : import_path.default.join(process.cwd(), documentRoot));
+  var _a;
+  const raw = ((_a = storage == null ? void 0 : storage.options) == null ? void 0 : _a.documentRoot) ?? process.env.LOCAL_STORAGE_DEST ?? (0, import_utils.storagePathJoin)("uploads");
+  return resolveDocumentRoot(raw);
 }
 function resolveSafePath(documentRoot, filePath, filename) {
-  const root = import_path.default.resolve(documentRoot);
+  const root = resolveDocumentRoot(documentRoot);
   const target = import_path.default.resolve(root, filePath || "", filename || "");
-  const relative = import_path.default.relative(root, target);
-  if (relative.startsWith("..") || import_path.default.isAbsolute(relative)) {
-    const error = new Error("Access denied");
-    error.code = "PATH_TRAVERSAL";
-    throw error;
+  if (!isInside(root, target)) {
+    throw pathError("Access denied");
   }
   return target;
 }
+function validateLocalStorageConfig(storage, { validateDocumentRoot = false } = {}) {
+  if (storage.type !== import_constants.STORAGE_TYPE_LOCAL) {
+    return;
+  }
+  const root = getDocumentRoot(storage);
+  if (validateDocumentRoot && !allowedRoots().some((allowed) => isInside(allowed, root))) {
+    throw pathError("Invalid local storage document root");
+  }
+  resolveSafePath(root, normalizeLocalStoragePath(storage.path));
+}
 class local_default extends import__.StorageType {
   static defaults() {
     return {
@@ -85,13 +130,31 @@ class local_default extends import__.StorageType {
   make() {
     return import_multer.default.diskStorage({
       destination: (req, file, cb) => {
-        const destPath = import_path.default.join(getDocumentRoot(this.storage), this.storage.path || "");
+        const destPath = resolveSafePath(getDocumentRoot(this.storage), normalizeLocalStoragePath(this.storage.path));
         const mkdirp = require("mkdirp");
         mkdirp(destPath, (err) => cb(err, destPath));
       },
       filename: (0, import_utils2.diskFilenameGetter)(this.storage)
     });
   }
+  async exists(record) {
+    try {
+      await import_promises.default.stat(resolveSafePath(getDocumentRoot(this.storage), record.path, record.filename));
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async copy(source, target) {
+    const documentRoot = getDocumentRoot(this.storage);
+    const sourcePath = resolveSafePath(documentRoot, source.path, source.filename);
+    const targetPath = resolveSafePath(documentRoot, target.path, target.filename);
+    await import_promises.default.mkdir(import_path.default.dirname(targetPath), { recursive: true });
+    await import_promises.default.copyFile(sourcePath, targetPath);
+  }
   async delete(records) {
     const documentRoot = getDocumentRoot(this.storage);
     let count = 0;
@@ -140,5 +203,7 @@ class local_default extends import__.StorageType {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getDocumentRoot,
-  resolveSafePath
+  normalizeLocalStoragePath,
+  resolveSafePath,
+  validateLocalStorageConfig
 });

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

@@ -32,5 +32,7 @@ export default class extends StorageType {
     deleteS3Objects(bucketName: string, objects: string[]): Promise<{
         Deleted: any[];
     }>;
+    exists(record: AttachmentModel): Promise<boolean>;
+    copy(source: AttachmentModel, target: AttachmentModel): Promise<void>;
     delete(records: AttachmentModel[]): Promise<[number, AttachmentModel[]]>;
 }

package/dist/server/storages/s3.js

@@ -173,6 +173,32 @@ class s3_default extends import__.StorageType {
       Deleted
     };
   }
+  async exists(record) {
+    try {
+      await this.client.send(
+        new import_client_s3.HeadObjectCommand({
+          Bucket: this.storage.options.bucket,
+          Key: this.getFileKey(record)
+        })
+      );
+      return true;
+    } catch (error) {
+      if (["NotFound", "NoSuchKey", "NoSuchBucket"].includes(error.name)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async copy(source, target) {
+    const sourceKey = this.getFileKey(source);
+    await this.client.send(
+      new import_client_s3.CopyObjectCommand({
+        Bucket: this.storage.options.bucket,
+        Key: this.getFileKey(target),
+        CopySource: `${this.storage.options.bucket}/${sourceKey.split("/").map((segment) => encodeURIComponent(segment)).join("/")}`
+      })
+    );
+  }
   async delete(records) {
     const { Deleted } = await this.deleteS3Objects(
       this.storage.options.bucket,

package/dist/server/storages/tx-cos.d.ts

@@ -7,6 +7,20 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 import { AttachmentModel, StorageType } from '.';
+declare class TxCosStorage {
+    cos: any;
+    getFilename: Function;
+    baseUrl: string;
+    options: Record<string, any>;
+    constructor({ config, baseUrl, filename }: {
+        config: any;
+        baseUrl: any;
+        filename: any;
+    });
+    getUploadedFileURL(key: string, location?: string): any;
+    _handleFile(req: any, file: any, cb: any): any;
+    _removeFile(req: any, file: any, cb: any): any;
+}
 export default class extends StorageType {
     static defaults(): {
         title: string;
@@ -21,6 +35,9 @@ export default class extends StorageType {
         };
     };
     static filenameKey: string;
-    make(): any;
+    make(): TxCosStorage;
+    exists(record: AttachmentModel): Promise<boolean>;
+    copy(source: AttachmentModel, target: AttachmentModel): Promise<void>;
     delete(records: AttachmentModel[]): Promise<[number, AttachmentModel[]]>;
 }
+export {};

package/dist/server/storages/tx-cos.js

@@ -7,9 +7,11 @@
  * 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)
@@ -23,6 +25,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   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 tx_cos_exports = {};
 __export(tx_cos_exports, {
@@ -30,9 +40,103 @@ __export(tx_cos_exports, {
 });
 module.exports = __toCommonJS(tx_cos_exports);
 var import_util = require("util");
+var import_stream = require("stream");
+var import_url_join = __toESM(require("url-join"));
 var import__ = require(".");
 var import_constants = require("../../constants");
-var import_utils2 = require("../utils");
+var import_utils = require("../utils");
+const ERROR_NO_CLIENT = new Error("cos client undefined");
+class CountingStream extends import_stream.Transform {
+  size = 0;
+  _transform(chunk, encoding, callback) {
+    this.size += chunk.length;
+    callback(null, chunk);
+  }
+}
+class TxCosStorage {
+  cos;
+  getFilename;
+  baseUrl;
+  options;
+  constructor({ config, baseUrl, filename }) {
+    const COS = require("cos-nodejs-sdk-v5");
+    this.cos = new COS({
+      SecretId: config.SecretId,
+      SecretKey: config.SecretKey,
+      SecurityToken: config.SecurityToken,
+      XCosSecurityToken: config.XCosSecurityToken,
+      FileParallelLimit: config.FileParallelLimit,
+      ChunkParallelLimit: config.ChunkParallelLimit,
+      ChunkSize: config.ChunkSize,
+      Domain: config.Domain,
+      Protocol: config.Protocol,
+      Timeout: config.Timeout,
+      KeepAlive: config.KeepAlive,
+      ForcePathStyle: config.ForcePathStyle,
+      CompatibilityMode: config.CompatibilityMode,
+      UseAccelerate: config.UseAccelerate
+    });
+    this.getFilename = filename;
+    this.baseUrl = baseUrl;
+    this.options = config;
+  }
+  getUploadedFileURL(key, location) {
+    if (this.baseUrl) {
+      return (0, import_url_join.default)(this.baseUrl, key);
+    }
+    if (!location) {
+      return key;
+    }
+    if (/^https?:\/\//.test(location)) {
+      return location;
+    }
+    return `https://${location}`;
+  }
+  _handleFile(req, file, cb) {
+    if (!this.cos) {
+      return cb(ERROR_NO_CLIENT);
+    }
+    const getFilename = (0, import_util.promisify)(this.getFilename);
+    Promise.resolve().then(async () => {
+      const key = await getFilename(req, file);
+      const counter = new CountingStream();
+      const body = file.stream.pipe(counter);
+      const params = {
+        Bucket: this.options.Bucket,
+        Region: this.options.Region,
+        Key: key,
+        Body: body
+      };
+      if (file.mimetype === "text/plain") {
+        params.ContentType = "text/plain; charset=utf-8";
+      } else if (file.mimetype) {
+        params.ContentType = file.mimetype;
+      }
+      const result = await (0, import_util.promisify)(this.cos.putObject).call(this.cos, params);
+      cb(null, {
+        key,
+        size: counter.size,
+        url: this.getUploadedFileURL(key, result == null ? void 0 : result.Location)
+      });
+    }).catch(cb);
+  }
+  _removeFile(req, file, cb) {
+    if (!this.cos) {
+      return cb(ERROR_NO_CLIENT);
+    }
+    if (!file.key) {
+      return cb(null);
+    }
+    this.cos.deleteObject(
+      {
+        Bucket: this.options.Bucket,
+        Region: this.options.Region,
+        Key: file.key
+      },
+      cb
+    );
+  }
+}
 class tx_cos_default extends import__.StorageType {
   static defaults() {
     return {
@@ -50,13 +154,37 @@ class tx_cos_default extends import__.StorageType {
   }
   static filenameKey = "url";
   make() {
-    const createTxCosStorage = require("multer-cos");
-    return new createTxCosStorage({
-      cos: {
-        ...this.storage.options,
-        dir: (this.storage.path ?? "").replace(/\/+$/, "")
-      },
-      filename: (0, import_utils2.diskFilenameGetter)(this.storage)
+    return new TxCosStorage({
+      config: this.storage.options,
+      baseUrl: this.storage.baseUrl,
+      filename: (0, import_utils.cloudFilenameGetter)(this.storage)
+    });
+  }
+  async exists(record) {
+    const { cos } = this.make();
+    try {
+      await (0, import_util.promisify)(cos.headObject).call(cos, {
+        Region: this.storage.options.Region,
+        Bucket: this.storage.options.Bucket,
+        Key: (0, import_utils.getFileKey)(record)
+      });
+      return true;
+    } catch (error) {
+      if (["NoSuchKey", "NotFound"].includes(error.name)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async copy(source, target) {
+    const { cos } = this.make();
+    const sourceKey = (0, import_utils.getFileKey)(source);
+    const copySource = `${this.storage.options.Bucket}.cos.${this.storage.options.Region}.myqcloud.com/${sourceKey.split("/").map((segment) => encodeURIComponent(segment)).join("/")}`;
+    await (0, import_util.promisify)(cos.putObjectCopy).call(cos, {
+      Region: this.storage.options.Region,
+      Bucket: this.storage.options.Bucket,
+      Key: (0, import_utils.getFileKey)(target),
+      CopySource: copySource
     });
   }
   async delete(records) {
@@ -64,8 +192,8 @@ class tx_cos_default extends import__.StorageType {
     const { Deleted } = await (0, import_util.promisify)(cos.deleteMultipleObject).call(cos, {
       Region: this.storage.options.Region,
       Bucket: this.storage.options.Bucket,
-      Objects: records.map((record) => ({ Key: (0, import_utils2.getFileKey)(record) }))
+      Objects: records.map((record) => ({ Key: (0, import_utils.getFileKey)(record) }))
     });
-    return [Deleted.length, records.filter((record) => !Deleted.find((item) => item.Key === (0, import_utils2.getFileKey)(record)))];
+    return [Deleted.length, records.filter((record) => !Deleted.find((item) => item.Key === (0, import_utils.getFileKey)(record)))];
   }
 }

package/dist/server/utils.d.ts

@@ -10,5 +10,8 @@ export declare function getFilename(req: any, file: any, cb: any): void;
 export declare const cloudFilenameGetter: (storage: any) => (req: any, file: any, cb: any) => void;
 export declare const diskFilenameGetter: (storage: any) => (req: any, file: any, cb: any) => void;
 export declare function getFileKey(record: any): any;
+export declare function normalizeStorageSubPath(subPath?: unknown): string;
+export declare function resolveStoragePath(storagePath?: unknown, subPath?: unknown): string;
 export declare function ensureUrlEncoded(value: any): any;
 export declare function encodeURL(url: any): any;
+export declare function normalizeDocumentRoot(documentRoot?: string): string;

package/dist/server/utils.js

@@ -41,13 +41,23 @@ __export(utils_exports, {
   encodeURL: () => encodeURL,
   ensureUrlEncoded: () => ensureUrlEncoded,
   getFileKey: () => getFileKey,
-  getFilename: () => getFilename
+  getFilename: () => getFilename,
+  normalizeDocumentRoot: () => normalizeDocumentRoot,
+  normalizeStorageSubPath: () => normalizeStorageSubPath,
+  resolveStoragePath: () => resolveStoragePath
 });
 module.exports = __toCommonJS(utils_exports);
 var import_utils = require("@nocobase/utils");
 var import_crypto = __toESM(require("crypto"));
 var import_path = __toESM(require("path"));
 var import_url_join = __toESM(require("url-join"));
+const INVALID_FILENAME_CHARS = /* @__PURE__ */ new Set(["<", ">", "?", "*", "|", ":", '"', "\\", "/"]);
+function sanitizeFilename(value) {
+  return Array.from(value).map((char) => {
+    const code = char.charCodeAt(0);
+    return code < 32 || code === 127 || INVALID_FILENAME_CHARS.has(char) ? "-" : char;
+  }).join("");
+}
 function normalizeOriginalname(file) {
   const originalname = file == null ? void 0 : file.originalname;
   if (!originalname) {
@@ -56,6 +66,9 @@ function normalizeOriginalname(file) {
   if (Buffer.isBuffer(originalname)) {
     return originalname.toString("utf8");
   }
+  if (Array.from(originalname).some((char) => char.charCodeAt(0) > 255)) {
+    return originalname;
+  }
   const decoded = Buffer.from(originalname, "binary").toString("utf8");
   if (decoded.includes("\uFFFD")) {
     return originalname;
@@ -64,13 +77,13 @@ function normalizeOriginalname(file) {
 }
 function getFilename(req, file, cb) {
   const originalname = normalizeOriginalname(file);
-  const baseName = import_path.default.basename(originalname.replace(/[<>?*|:"\\/]/g, "-"), import_path.default.extname(originalname));
+  const baseName = import_path.default.basename(sanitizeFilename(originalname), import_path.default.extname(originalname));
   cb(null, `${baseName}-${(0, import_utils.uid)(6)}${import_path.default.extname(originalname)}`);
 }
 function getOriginalFilename(file) {
   const originalname = normalizeOriginalname(file);
   const extname = import_path.default.extname(originalname);
-  const baseName = import_path.default.basename(originalname.replace(/[<>?*|:"\\/]/g, "-"), extname);
+  const baseName = import_path.default.basename(sanitizeFilename(originalname), extname);
   return `${baseName}${extname}`;
 }
 const cloudFilenameGetter = (storage) => (req, file, cb) => {
@@ -118,6 +131,41 @@ const diskFilenameGetter = (storage) => (req, file, cb) => {
 function getFileKey(record) {
   return (0, import_url_join.default)(record.path || "", record.filename).replace(/^\//, "");
 }
+function pathError(message) {
+  const error = new Error(message);
+  error.code = "PATH_TRAVERSAL";
+  return error;
+}
+function normalizeStoragePathForJoin(value, message, { allowLeadingSlash = false } = {}) {
+  if (value == null || value === "") {
+    return "";
+  }
+  if (typeof value !== "string" || value.includes("\0")) {
+    throw pathError(message);
+  }
+  const normalized = value.replace(/\\/g, "/");
+  if (!allowLeadingSlash && normalized.startsWith("/")) {
+    throw pathError(message);
+  }
+  const segments = normalized.replace(/^\/+|\/+$/g, "").split("/").filter((segment) => segment && segment !== ".");
+  if (segments.some((segment) => segment === "..")) {
+    throw pathError("Access denied");
+  }
+  return segments.join("/");
+}
+function normalizeStorageSubPath(subPath) {
+  return normalizeStoragePathForJoin(subPath, "Invalid storage sub path");
+}
+function resolveStoragePath(storagePath, subPath) {
+  const normalizedSubPath = normalizeStorageSubPath(subPath);
+  if (!normalizedSubPath) {
+    return typeof storagePath === "string" ? storagePath : "";
+  }
+  const normalizedStoragePath = normalizeStoragePathForJoin(storagePath, "Invalid storage path", {
+    allowLeadingSlash: true
+  });
+  return normalizedStoragePath ? `${normalizedStoragePath}/${normalizedSubPath}` : normalizedSubPath;
+}
 function ensureUrlEncoded(value) {
   try {
     if (decodeURIComponent(value) !== value) {
@@ -140,6 +188,23 @@ function encodeURL(url) {
     return url;
   }
 }
+function isStorageRelativeDocumentRoot(documentRoot) {
+  return documentRoot === "storage" || documentRoot.startsWith("storage/") || documentRoot === "./storage" || documentRoot.startsWith("./storage/");
+}
+function normalizeDocumentRoot(documentRoot) {
+  if (!documentRoot) {
+    return (0, import_utils.storagePathJoin)("uploads");
+  }
+  if (import_path.default.isAbsolute(documentRoot)) {
+    return documentRoot;
+  }
+  const normalizedDocumentRoot = documentRoot.replace(/\\/g, "/");
+  if (isStorageRelativeDocumentRoot(normalizedDocumentRoot)) {
+    const relativePath = normalizedDocumentRoot.replace(/^\.?\/?storage(?:\/|$)/, "").replace(/^[/\\]+/, "");
+    return relativePath ? (0, import_utils.storagePathJoin)(relativePath) : (0, import_utils.storagePathJoin)();
+  }
+  return import_path.default.resolve(process.cwd(), documentRoot);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cloudFilenameGetter,
@@ -147,5 +212,8 @@ function encodeURL(url) {
   encodeURL,
   ensureUrlEncoded,
   getFileKey,
-  getFilename
+  getFilename,
+  normalizeDocumentRoot,
+  normalizeStorageSubPath,
+  resolveStoragePath
 });