@h-ai/storage 1.0.0-beta.2 → 1.0.0-beta.20

package/dist/node.js

@@ -1,8 +1,8 @@
-import { HaiStorageError, StorageConfigSchema, PresignUploadOptionsSchema, PresignOptionsSchema } from './chunk-ANAESRWS.js';
-export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageOperationLogConfigSchema, StorageTypeSchema } from './chunk-ANAESRWS.js';
-import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-TLZY4IP6.js';
-export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-TLZY4IP6.js';
-export { STORAGE_DELETE_MAX_KEYS, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema, StorageKeySchema, StoragePrefixSchema, StoragePresignExpiresInSchema, getStorageKeyIssue } from './chunk-P65WYXJG.js';
+import { HaiStorageError, StorageConfigSchema, PresignUploadOptionsSchema, PresignOptionsSchema } from './chunk-FK7KRCML.js';
+export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageOperationLogConfigSchema, StorageTypeSchema } from './chunk-FK7KRCML.js';
+import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-JAJYHGLI.js';
+export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-JAJYHGLI.js';
+export { STORAGE_DELETE_MAX_KEYS, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema, StorageKeySchema, StoragePrefixSchema, StoragePresignExpiresInSchema, getStorageKeyIssue } from './chunk-6YG3N3CW.js';
 import process from 'node:process';
 import { core, err, ok } from '@h-ai/core';
 import { Buffer } from 'node:buffer';
@@ -23,7 +23,9 @@ function toStorageDeleteResult(summary) {
     success: false,
     error: {
       ...HaiStorageError.OPERATION_FAILED,
-      message: storageM("storage_deleteManyFailed", { params: { count: summary.failures.length } }),
+      message: storageM("storage_deleteManyFailed", {
+        params: { count: summary.failures.length }
+      }),
       ext: { deleteMany: summary }
     }
   };
@@ -113,22 +115,33 @@ function logStorageOperation(logger4, config, category, operation, payload) {
 // src/providers/storage-provider-local.ts
 var logger = core.logger.child({ module: "storage", scope: "provider-local" });
 var PATH_SEGMENT_SPLIT_REGEX = /[\\/]+/;
+var METADATA_DIRECTORY = ".hai-storage-meta";
 function toStorageError(error, key) {
   const e = error;
   if (e.code === "EEXIST") {
-    return { ...HaiStorageError.ALREADY_EXISTS, message: storageM("storage_fileAlreadyExists", { params: { key: key ?? "" } }), cause: error };
+    return {
+      ...HaiStorageError.ALREADY_EXISTS,
+      message: storageM("storage_fileAlreadyExists", {
+        params: { key: key ?? "" }
+      }),
+      cause: error
+    };
   }
   if (e.code === "ENOENT") {
     return {
       ...HaiStorageError.NOT_FOUND,
-      message: storageM("storage_fileNotFound", { params: { key: key ?? "" } }),
+      message: storageM("storage_fileNotFound", {
+        params: { key: key ?? "" }
+      }),
       cause: error
     };
   }
   if (e.code === "EACCES" || e.code === "EPERM") {
     return {
       ...HaiStorageError.PERMISSION_DENIED,
-      message: storageM("storage_permissionDenied", { params: { key: key ?? "" } }),
+      message: storageM("storage_permissionDenied", {
+        params: { key: key ?? "" }
+      }),
       cause: error
     };
   }
@@ -142,7 +155,9 @@ function toStorageError(error, key) {
   if (e.code === "EISDIR") {
     return {
       ...HaiStorageError.INVALID_PATH,
-      message: storageM("storage_pathIsDir", { params: { key: key ?? "" } }),
+      message: storageM("storage_pathIsDir", {
+        params: { key: key ?? "" }
+      }),
       cause: error
     };
   }
@@ -154,8 +169,8 @@ function toStorageError(error, key) {
     };
   }
   return {
-    code: HaiStorageError.IO_ERROR.code,
-    message: storageM("storage_ioError", { params: { error: e.message ?? "" } }),
+    ...HaiStorageError.IO_ERROR,
+    message: storageM("storage_ioError"),
     cause: error
   };
 }
@@ -164,10 +179,33 @@ function getMimeType2(filePath) {
   return MIME_TYPES[ext] || MIME_TYPE_DEFAULT;
 }
 function calculateEtag(stat2) {
-  return `"${stat2.size.toString(16)}-${stat2.mtimeMs.toString(16)}"`;
+  const modified = "mtimeNs" in stat2 ? Number(stat2.mtimeNs) / 1e6 : stat2.mtimeMs;
+  return `"${stat2.size.toString(16)}-${modified.toString(16)}"`;
+}
+function metadataGeneration(stat2) {
+  return crypto.createHash("sha256").update([
+    stat2.dev,
+    stat2.ino,
+    stat2.birthtimeNs,
+    stat2.mtimeNs,
+    stat2.size
+  ].join(":")).digest("hex");
+}
+function isMetadataRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  if ("contentType" in value && typeof value.contentType !== "string")
+    return false;
+  if ("metadata" in value) {
+    const metadata = value.metadata;
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata) || Object.values(metadata).some((item) => typeof item !== "string")) {
+      return false;
+    }
+  }
+  return true;
 }
 function isMetaFile(key) {
-  return key.endsWith(".meta.json") || key.endsWith(".upload.tmp");
+  return key.toLowerCase().split(PATH_SEGMENT_SPLIT_REGEX).some((segment) => segment === METADATA_DIRECTORY || segment.endsWith(".meta.json") || segment.endsWith(".upload.tmp"));
 }
 function createInvalidPathError() {
   const error = new Error(storageM("storage_pathTraversal"));
@@ -182,7 +220,7 @@ function safePath(root, key) {
   if (path.isAbsolute(key)) {
     throw createInvalidPathError();
   }
-  if (key.includes("\0") || hasPathTraversalSegment(key)) {
+  if (key.includes("\0") || hasPathTraversalSegment(key) || process.platform === "win32" && key.split(PATH_SEGMENT_SPLIT_REGEX).some((segment) => /[:. ]$/.test(segment) || segment.includes(":"))) {
     throw createInvalidPathError();
   }
   const normalized = path.normalize(key);
@@ -203,52 +241,96 @@ function createLocalProvider() {
     }
     return config;
   }
-  function fullPath(key) {
-    return safePath(getConfig().root, key);
+  async function fullPath(key) {
+    const root = getConfig().root;
+    const target = safePath(root, key);
+    let current = root;
+    for (const segment of path.relative(root, target).split(path.sep).filter(Boolean)) {
+      current = path.join(current, segment);
+      try {
+        if ((await fsp.lstat(current)).isSymbolicLink())
+          throw createInvalidPathError();
+      } catch (error) {
+        if (error.code === "ENOENT")
+          break;
+        throw error;
+      }
+    }
+    return target;
   }
   function logOperation(category, operation, payload) {
     logStorageOperation(logger, config?.operationLog, category, operation, payload);
   }
+  function metadataKey(filePath, stat2) {
+    return path.relative(getConfig().root, path.join(path.dirname(filePath), METADATA_DIRECTORY, `${metadataGeneration(stat2)}.meta.json`));
+  }
   const file = {
     async put(key, data, options = {}) {
       if (isMetaFile(key)) {
         return err(
           HaiStorageError.INVALID_PATH,
-          storageM("storage_metaFileAccess", { params: { key } })
+          storageM("storage_metaFileAccess", {
+            params: { key }
+          })
         );
       }
       let temporaryPath;
+      let preparedMetadataPath;
+      let published = false;
       try {
-        const filePath = fullPath(key);
+        const filePath = await fullPath(key);
+        const cfg = getConfig();
+        let previousMetadataKey;
+        try {
+          previousMetadataKey = metadataKey(filePath, await fsp.stat(filePath, { bigint: true }));
+        } catch (error) {
+          if (error.code !== "ENOENT")
+            throw error;
+        }
         logOperation("write", "file.put", { key, options });
         const dir2 = path.dirname(filePath);
-        await fsp.mkdir(dir2, { recursive: true, mode: getConfig().directoryMode });
+        await fsp.mkdir(dir2, { recursive: true, mode: cfg.directoryMode });
         temporaryPath = `${filePath}.${crypto.randomUUID()}.upload.tmp`;
         await pipeline(
           Readable.from(toByteStream(data, options.signal), { objectMode: false }),
-          fs.createWriteStream(temporaryPath, { flags: "wx", mode: getConfig().fileMode }),
+          fs.createWriteStream(temporaryPath, { flags: "wx", mode: cfg.fileMode }),
           { signal: options.signal }
         );
         options.signal?.throwIfAborted();
+        const stat2 = await fsp.stat(temporaryPath, { bigint: true });
+        const metaPath = await fullPath(metadataKey(filePath, stat2));
+        const serializedMetadata = JSON.stringify({ contentType: options.contentType, metadata: options.metadata });
+        await fsp.mkdir(path.dirname(metaPath), { recursive: true, mode: cfg.directoryMode });
+        const metadataFile = await fsp.open(metaPath, "wx", cfg.fileMode);
+        preparedMetadataPath = metaPath;
+        try {
+          await metadataFile.writeFile(serializedMetadata);
+        } finally {
+          await metadataFile.close();
+        }
+        options.signal?.throwIfAborted();
         if (options.ifNoneMatch === "*")
           await fsp.link(temporaryPath, filePath);
         else
           await fsp.rename(temporaryPath, filePath);
-        const stat2 = await fsp.stat(filePath);
+        published = true;
         const metadata = {
           key,
-          size: stat2.size,
+          size: Number(stat2.size),
           contentType: options.contentType || getMimeType2(key),
           lastModified: stat2.mtime,
           etag: calculateEtag(stat2),
           metadata: options.metadata
         };
-        if (options.metadata || options.contentType) {
-          const metaPath = `${filePath}.meta.json`;
-          await fsp.writeFile(metaPath, JSON.stringify({
-            contentType: options.contentType,
-            metadata: options.metadata
-          }));
+        if (previousMetadataKey) {
+          try {
+            const previousMetadataPath = await fullPath(previousMetadataKey);
+            if (previousMetadataPath !== metaPath)
+              await fsp.unlink(previousMetadataPath);
+          } catch (error) {
+            if (error.code !== "ENOENT")
+              logger.warn("Obsolete local metadata cleanup failed", { key });
+          }
         }
         return ok(metadata);
       } catch (error) {
@@ -258,6 +340,8 @@ function createLocalProvider() {
         if (temporaryPath)
           await fsp.unlink(temporaryPath).catch(() => {
           });
+        if (preparedMetadataPath && !published)
+          await fsp.unlink(preparedMetadataPath).catch(() => logger.warn("Unpublished local metadata cleanup failed", { key }));
       }
     },
     async get(key, options = {}) {
@@ -277,16 +361,21 @@ function createLocalProvider() {
       if (isMetaFile(key)) {
         return err(
           HaiStorageError.INVALID_PATH,
-          storageM("storage_metaFileAccess", { params: { key } })
+          storageM("storage_metaFileAccess", {
+            params: { key }
+          })
         );
       }
       try {
-        const filePath = fullPath(key);
+        const filePath = await fullPath(key);
         logOperation("read", "file.getStream", { key, options });
         options.signal?.throwIfAborted();
         const stat2 = await fsp.stat(filePath);
-        if (stat2.isDirectory())
-          return err(HaiStorageError.INVALID_PATH, storageM("storage_pathIsDir", { params: { key } }));
+        if (stat2.isDirectory()) {
+          return err(HaiStorageError.INVALID_PATH, storageM("storage_pathIsDir", {
+            params: { key }
+          }));
+        }
         async function* read() {
           const stream = fs.createReadStream(filePath, { start: options.rangeStart, end: options.rangeEnd, signal: options.signal });
           for await (const chunk of stream)
@@ -301,35 +390,59 @@ function createLocalProvider() {
       if (isMetaFile(key)) {
         return err(
           HaiStorageError.INVALID_PATH,
-          storageM("storage_metaFileAccess", { params: { key } })
+          storageM("storage_metaFileAccess", {
+            params: { key }
+          })
         );
       }
       try {
-        const filePath = fullPath(key);
+        const filePath = await fullPath(key);
         logOperation("read", "file.head", { key });
-        const stat2 = await fsp.stat(filePath);
-        if (stat2.isDirectory()) {
-          return err(
-            HaiStorageError.INVALID_PATH,
-            storageM("storage_pathIsDir", { params: { key } })
-          );
-        }
-        let customMetadata = {};
-        try {
-          const metaPath = `${filePath}.meta.json`;
-          const metaContent = await fsp.readFile(metaPath, "utf-8");
-          customMetadata = JSON.parse(metaContent);
-        } catch {
+        for (let attempt = 0; attempt < 3; attempt++) {
+          const stat2 = await fsp.stat(filePath, { bigint: true });
+          if (stat2.isDirectory()) {
+            return err(HaiStorageError.INVALID_PATH, storageM("storage_pathIsDir", {
+              params: { key }
+            }));
+          }
+          let serializedMetadata;
+          try {
+            const metaPath = await fullPath(metadataKey(filePath, stat2));
+            serializedMetadata = await fsp.readFile(metaPath, "utf8");
+          } catch (error) {
+            if (!["ENOENT", "ENOTDIR"].includes(error.code ?? ""))
+              throw error;
+            if (metadataGeneration(await fsp.stat(filePath, { bigint: true })) !== metadataGeneration(stat2))
+              continue;
+            return err(HaiStorageError.OPERATION_FAILED, storageM("storage_metadataRequired"));
+          }
+          let customMetadata;
+          try {
+            customMetadata = JSON.parse(serializedMetadata);
+          } catch {
+            logger.warn("Invalid local metadata record", {
+              key,
+              generation: metadataGeneration(stat2)
+            });
+            return err(HaiStorageError.OPERATION_FAILED, storageM("storage_metadataInvalid"));
+          }
+          if (!isMetadataRecord(customMetadata)) {
+            logger.warn("Invalid local metadata shape", {
+              key,
+              generation: metadataGeneration(stat2)
+            });
+            return err(HaiStorageError.OPERATION_FAILED, storageM("storage_metadataInvalid"));
+          }
+          return ok({
+            key,
+            size: Number(stat2.size),
+            contentType: customMetadata.contentType || getMimeType2(key),
+            lastModified: stat2.mtime,
+            etag: calculateEtag(stat2),
+            metadata: customMetadata.metadata
+          });
         }
-        const etag = `"${stat2.size.toString(16)}-${stat2.mtimeMs.toString(16)}"`;
-        return ok({
-          key,
-          size: stat2.size,
-          contentType: customMetadata.contentType || getMimeType2(key),
-          lastModified: stat2.mtime,
-          etag,
-          metadata: customMetadata.metadata
-        });
+        return err(HaiStorageError.OPERATION_FAILED, storageM("storage_fileChanged"));
       } catch (error) {
         return err(toStorageError(error, key));
       }
@@ -338,11 +451,13 @@ function createLocalProvider() {
       if (isMetaFile(key)) {
         return err(
           HaiStorageError.INVALID_PATH,
-          storageM("storage_metaFileAccess", { params: { key } })
+          storageM("storage_metaFileAccess", {
+            params: { key }
+          })
         );
       }
       try {
-        const filePath = fullPath(key);
+        const filePath = await fullPath(key);
         logOperation("read", "file.exists", { key });
         await fsp.access(filePath, fs.constants.F_OK);
         return ok(true);
@@ -357,17 +472,22 @@ function createLocalProvider() {
       if (isMetaFile(key)) {
         return err(
           HaiStorageError.INVALID_PATH,
-          storageM("storage_metaFileAccess", { params: { key } })
+          storageM("storage_metaFileAccess", {
+            params: { key }
+          })
         );
       }
       try {
-        const filePath = fullPath(key);
+        const filePath = await fullPath(key);
+        const generationKey = metadataKey(filePath, await fsp.stat(filePath, { bigint: true }));
         logOperation("write", "file.delete", { key });
         logger.debug("Deleting file", { key });
         await fsp.unlink(filePath);
         try {
-          await fsp.unlink(`${filePath}.meta.json`);
-        } catch {
+          await fsp.unlink(await fullPath(generationKey));
+        } catch (error) {
+          if (error.code !== "ENOENT")
+            logger.warn("Deleted object metadata cleanup failed", { key });
         }
         return ok(void 0);
       } catch (error) {
@@ -381,57 +501,47 @@ function createLocalProvider() {
     async deleteMany(keys) {
       logOperation("write", "file.deleteMany", { count: keys.length, keys });
       const summary = { deletedKeys: [], failures: [] };
-      const uniqueKeys = [...new Set(keys)];
+      const uniqueKeys = [
+        ...new Set(keys)
+      ];
       for (let offset = 0; offset < uniqueKeys.length; offset += 32) {
         const batch = uniqueKeys.slice(offset, offset + 32);
         const results = await Promise.allSettled(batch.map((key) => file.delete(key)));
         for (const [index, result] of results.entries()) {
           const key = batch[index];
-          if (result.status === "rejected")
-            summary.failures.push({ key, code: "UnexpectedDeleteFailure", retryable: false, outcome: "failed" });
-          else if (!result.value.success)
-            summary.failures.push({ key, code: String(result.value.error.code), retryable: false, outcome: "failed" });
-          else
+          if (result.status === "rejected") {
+            summary.failures.push({
+              key,
+              code: "UnexpectedDeleteFailure",
+              retryable: false,
+              outcome: "failed"
+            });
+          } else if (!result.value.success) {
+            summary.failures.push({
+              key,
+              code: String(result.value.error.code),
+              retryable: false,
+              outcome: "failed"
+            });
+          } else {
             summary.deletedKeys.push(key);
+          }
         }
       }
       return toStorageDeleteResult(summary);
     },
     async copy(sourceKey, destKey, options = {}) {
-      if (isMetaFile(sourceKey) || isMetaFile(destKey)) {
-        return err(
-          HaiStorageError.INVALID_PATH,
-          storageM("storage_metaFileAccess", { params: { key: sourceKey } }),
-          sourceKey
-        );
-      }
-      try {
-        const sourcePath = fullPath(sourceKey);
-        const destPath = fullPath(destKey);
-        logOperation("write", "file.copy", { sourceKey, destKey, options });
-        logger.debug("Copying file", { sourceKey, destKey });
-        await fsp.mkdir(path.dirname(destPath), { recursive: true, mode: getConfig().directoryMode });
-        await fsp.copyFile(sourcePath, destPath);
-        const stat2 = await fsp.stat(destPath);
-        const metadata = {
-          key: destKey,
-          size: stat2.size,
-          contentType: options.contentType || getMimeType2(destKey),
-          lastModified: stat2.mtime,
-          etag: calculateEtag(stat2),
-          metadata: options.metadata
-        };
-        if (options.contentType || options.metadata) {
-          const metaPath = `${destPath}.meta.json`;
-          await fsp.writeFile(metaPath, JSON.stringify({
-            contentType: options.contentType,
-            metadata: options.metadata
-          }));
-        }
-        return ok(metadata);
-      } catch (error) {
-        return err(toStorageError(error, sourceKey));
-      }
+      logOperation("write", "file.copy", { sourceKey, destKey, options });
+      const source = await file.head(sourceKey);
+      if (!source.success)
+        return source;
+      const stream = await file.getStream(sourceKey);
+      if (!stream.success)
+        return stream;
+      return file.put(destKey, stream.data, {
+        contentType: options.contentType ?? source.data.contentType,
+        metadata: options.metadata ?? source.data.metadata
+      });
     }
   };
   const dir = {
@@ -507,7 +617,12 @@ function createLocalProvider() {
             commonPrefixes.push(logicalKey);
           } else {
             const stat2 = await fsp.stat(entry.filePath);
-            files.push({ key: entry.key, size: stat2.size, contentType: getMimeType2(entry.key), lastModified: stat2.mtime });
+            files.push({
+              key: entry.key,
+              size: stat2.size,
+              contentType: getMimeType2(entry.key),
+              lastModified: stat2.mtime
+            });
           }
           count++;
           last = logicalKey;
@@ -516,15 +631,22 @@ function createLocalProvider() {
           files,
           commonPrefixes,
           isTruncated,
-          ...isTruncated ? { nextContinuationToken: Buffer.from(JSON.stringify([1, scope, last])).toString("base64url") } : {}
+          ...isTruncated ? {
+            nextContinuationToken: Buffer.from(JSON.stringify([1, scope, last])).toString("base64url")
+          } : {}
         });
       } catch (error) {
         return err(toStorageError(error));
       }
     },
     async delete(prefix) {
+      if (isMetaFile(prefix)) {
+        return err(HaiStorageError.INVALID_PATH, storageM("storage_metaFileAccess", {
+          params: { key: prefix }
+        }));
+      }
       try {
-        const dirPath = fullPath(prefix);
+        const dirPath = await fullPath(prefix);
         logOperation("write", "dir.delete", { prefix });
         await fsp.rm(dirPath, { recursive: true, force: true });
         return ok(void 0);
@@ -566,6 +688,7 @@ function createLocalProvider() {
         config = cfg;
         logger.info("Connecting local provider", { root: cfg.root });
         await fsp.mkdir(cfg.root, { recursive: true, mode: cfg.directoryMode });
+        config = { ...cfg, root: await fsp.realpath(cfg.root) };
         connected = true;
         logger.info("Local provider connected", { root: cfg.root });
         return ok(void 0);
@@ -589,22 +712,38 @@ var logger2 = core.logger.child({ module: "storage", scope: "provider-s3" });
 var TRAILING_SLASHES_REGEX = /\/+$/;
 var LEADING_SLASHES_REGEX = /^\/+/;
 var DELETE_BATCH_SIZE = 1e3;
-var RETRYABLE_DELETE_CODES = /* @__PURE__ */ new Set(["InternalError", "ServiceUnavailable", "SlowDown", "RequestTimeout"]);
+var RETRYABLE_DELETE_CODES = /* @__PURE__ */ new Set([
+  "InternalError",
+  "ServiceUnavailable",
+  "SlowDown",
+  "RequestTimeout"
+]);
 function toStorageError2(error, key) {
   const e = error;
-  if (e.name === "PreconditionFailed" || e.$metadata?.httpStatusCode === 412)
-    return { ...HaiStorageError.ALREADY_EXISTS, message: storageM("storage_fileAlreadyExists", { params: { key: key ?? "" } }), cause: error };
+  if (e.name === "PreconditionFailed" || e.$metadata?.httpStatusCode === 412) {
+    return {
+      ...HaiStorageError.ALREADY_EXISTS,
+      message: storageM("storage_fileAlreadyExists", {
+        params: { key: key ?? "" }
+      }),
+      cause: error
+    };
+  }
   if (e.name === "NoSuchKey" || e.Code === "NoSuchKey" || e.name === "NotFound" || e.Code === "NotFound" || e.name === "404" || e.$metadata?.httpStatusCode === 404) {
     return {
       ...HaiStorageError.NOT_FOUND,
-      message: storageM("storage_fileNotFound", { params: { key: key ?? "" } }),
+      message: storageM("storage_fileNotFound", {
+        params: { key: key ?? "" }
+      }),
       cause: error
     };
   }
   if (e.name === "AccessDenied" || e.Code === "AccessDenied") {
     return {
       ...HaiStorageError.PERMISSION_DENIED,
-      message: storageM("storage_permissionDenied", { params: { key: key ?? "" } }),
+      message: storageM("storage_permissionDenied", {
+        params: { key: key ?? "" }
+      }),
       cause: error
     };
   }
@@ -624,7 +763,9 @@ function toStorageError2(error, key) {
   }
   return {
     ...HaiStorageError.OPERATION_FAILED,
-    message: storageM("storage_operationFailed", { params: { error: e.message ?? "" } }),
+    message: storageM("storage_operationFailed", {
+      params: { error: e.message ?? "" }
+    }),
     cause: error
   };
 }
@@ -636,7 +777,7 @@ function withPrefix(key, prefix) {
 function withoutPrefix(key, prefix) {
   if (!prefix)
     return key;
-  const normalizedPrefix = `${prefix.replace(TRAILING_SLASHES_REGEX, "")}/`;
+  const normalizedPrefix = withPrefix("", prefix);
   if (key.startsWith(normalizedPrefix)) {
     return key.slice(normalizedPrefix.length);
   }
@@ -724,7 +865,12 @@ function createS3Provider() {
           ContentDisposition: options.contentDisposition,
           IfNoneMatch: options.ifNoneMatch
         };
-        logOperation("write", "file.put", { key, fullPath, byteLength: buffered ? size : void 0, options });
+        logOperation("write", "file.put", {
+          key,
+          fullPath,
+          byteLength: buffered ? size : void 0,
+          options
+        });
         if (buffered) {
           await s3Client.send(new PutObjectCommand({ ...params, Body: body }), { abortSignal: options.signal });
         } else {
@@ -742,7 +888,13 @@ function createS3Provider() {
             if (options.signal?.aborted)
               abort();
             const { Upload } = await import('@aws-sdk/lib-storage');
-            await new Upload({ client: s3Client, params: { ...params, Body: stream }, queueSize: 2, leavePartsOnError: false, abortController: controller }).done();
+            await new Upload({
+              client: s3Client,
+              params: { ...params, Body: stream },
+              queueSize: 2,
+              leavePartsOnError: false,
+              abortController: controller
+            }).done();
           } finally {
             options.signal?.removeEventListener("abort", abort);
             stream.destroy();
@@ -857,7 +1009,9 @@ function createS3Provider() {
         const s3Client = getClient("deleteMany");
         const s3Config = getConfig();
         logOperation("write", "file.deleteMany", { count: keys.length, keys });
-        const uniqueKeys = [...new Set(keys)];
+        const uniqueKeys = [
+          ...new Set(keys)
+        ];
         const summary = { deletedKeys: [], failures: [] };
         for (let offset = 0; offset < uniqueKeys.length; offset += DELETE_BATCH_SIZE) {
           let pending = uniqueKeys.slice(offset, offset + DELETE_BATCH_SIZE);
@@ -866,7 +1020,12 @@ function createS3Provider() {
             try {
               response = await s3Client.send(new DeleteObjectsCommand({
                 Bucket: s3Config.bucket,
-                Delete: { Objects: [...new Set(pending.map(fullKey))].map((Key) => ({ Key })), Quiet: false }
+                Delete: {
+                  Objects: [
+                    ...new Set(pending.map(fullKey))
+                  ].map((Key) => ({ Key })),
+                  Quiet: false
+                }
               }));
             } catch (cause) {
               const failure = cause && typeof cause === "object" ? cause : {};
@@ -875,7 +1034,12 @@ function createS3Provider() {
               const retryable = status === void 0 || status === 408 || status === 429 || status >= 500;
               const outcome = status !== void 0 && status >= 400 && status < 500 && status !== 408 ? "failed" : "unknown";
               summary.failures.push(...pending.map((key) => ({ key, code, retryable, outcome })));
-              summary.failures.push(...uniqueKeys.slice(offset + DELETE_BATCH_SIZE).map((key) => ({ key, code, retryable, outcome: "notAttempted" })));
+              summary.failures.push(...uniqueKeys.slice(offset + DELETE_BATCH_SIZE).map((key) => ({
+                key,
+                code,
+                retryable,
+                outcome: "notAttempted"
+              })));
               return toStorageDeleteResult(summary);
             }
             const outcomes = /* @__PURE__ */ new Map();
@@ -883,7 +1047,10 @@ function createS3Provider() {
             let malformed = false;
             const items = [
               ...(response.Deleted ?? []).map((item) => ({ key: item.Key, code: null })),
-              ...(response.Errors ?? []).map((item) => ({ key: item.Key, code: item.Code && /^[\w.-]{1,80}$/.test(item.Code) ? item.Code : "UnknownError" }))
+              ...(response.Errors ?? []).map((item) => ({
+                key: item.Key,
+                code: item.Code && /^[\w.-]{1,80}$/.test(item.Code) ? item.Code : "UnknownError"
+              }))
             ];
             for (const item of items) {
               if (!item.key || !requested.has(item.key) || outcomes.has(item.key)) {
@@ -893,19 +1060,35 @@ function createS3Provider() {
               outcomes.set(item.key, item.code);
             }
             if (malformed || outcomes.size !== requested.size) {
-              summary.failures.push(...pending.map((key) => ({ key, code: "InvalidDeleteResponse", retryable: false, outcome: "unknown" })));
-              summary.failures.push(...uniqueKeys.slice(offset + DELETE_BATCH_SIZE).map((key) => ({ key, code: "InvalidDeleteResponse", retryable: false, outcome: "notAttempted" })));
+              summary.failures.push(...pending.map((key) => ({
+                key,
+                code: "InvalidDeleteResponse",
+                retryable: false,
+                outcome: "unknown"
+              })));
+              summary.failures.push(...uniqueKeys.slice(offset + DELETE_BATCH_SIZE).map((key) => ({
+                key,
+                code: "InvalidDeleteResponse",
+                retryable: false,
+                outcome: "notAttempted"
+              })));
               return toStorageDeleteResult(summary);
             }
             const retry = [];
             for (const key of pending) {
               const code = outcomes.get(fullKey(key));
-              if (code === null)
+              if (code === null) {
                 summary.deletedKeys.push(key);
-              else if (code && RETRYABLE_DELETE_CODES.has(code) && attempt < 2)
+              } else if (code && RETRYABLE_DELETE_CODES.has(code) && attempt < 2) {
                 retry.push(key);
-              else
-                summary.failures.push({ key, code: code ?? "UnknownError", retryable: !!code && RETRYABLE_DELETE_CODES.has(code), outcome: "failed" });
+              } else {
+                summary.failures.push({
+                  key,
+                  code: code ?? "UnknownError",
+                  retryable: !!code && RETRYABLE_DELETE_CODES.has(code),
+                  outcome: "failed"
+                });
+              }
             }
             pending = retry;
             if (pending.length > 0)
@@ -923,10 +1106,20 @@ function createS3Provider() {
         const s3Config = getConfig();
         const sourceFullPath = fullKey(sourceKey);
         const destFullPath = fullKey(destKey);
-        logOperation("write", "file.copy", { sourceKey, destKey, sourceFullPath, destFullPath, options });
+        const copySource = [
+          s3Config.bucket,
+          ...sourceFullPath.split("/")
+        ].map((part) => encodeURIComponent(part).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`)).join("/");
+        logOperation("write", "file.copy", {
+          sourceKey,
+          destKey,
+          sourceFullPath,
+          destFullPath,
+          options
+        });
         await s3Client.send(new CopyObjectCommand({
           Bucket: s3Config.bucket,
-          CopySource: `${s3Config.bucket}/${sourceFullPath}`,
+          CopySource: copySource,
           Key: destFullPath,
           ContentType: options.contentType,
           Metadata: options.metadata,
@@ -944,13 +1137,9 @@ function createS3Provider() {
         const s3Client = getClient();
         const s3Config = getConfig();
         logOperation("read", "dir.list", { options });
-        let prefix = s3Config.prefix || "";
-        if (options.prefix) {
-          prefix = withPrefix(options.prefix, s3Config.prefix);
-        }
         const response = await s3Client.send(new ListObjectsV2Command({
           Bucket: s3Config.bucket,
-          Prefix: prefix || void 0,
+          Prefix: withPrefix(options.prefix ?? "", s3Config.prefix) || void 0,
           Delimiter: options.delimiter,
           MaxKeys: options.maxKeys,
           ContinuationToken: options.continuationToken
@@ -1101,7 +1290,11 @@ function createS3Provider() {
         if (cfg.publicEndpoint) {
           const endpoint = new URL(cfg.publicEndpoint);
           publicBasePath = endpoint.pathname.replace(TRAILING_SLASHES_REGEX, "");
-          presignClient = new S3Client({ ...clientConfig, endpoint: endpoint.origin, forcePathStyle: publicBasePath ? true : cfg.forcePathStyle });
+          presignClient = new S3Client({
+            ...clientConfig,
+            endpoint: endpoint.origin,
+            forcePathStyle: publicBasePath ? true : cfg.forcePathStyle
+          });
         }
         if (cfg.createBucket) {
           try {
@@ -1114,7 +1307,9 @@ function createS3Provider() {
               await client.send(new CreateBucketCommand({
                 Bucket: cfg.bucket,
                 // AWS us-east-1 要省略 LocationConstraint；兼容服务可使用自定义区域名。
-                ...cfg.region === "us-east-1" ? {} : { CreateBucketConfiguration: { LocationConstraint: cfg.region } }
+                ...cfg.region === "us-east-1" ? {} : {
+                  CreateBucketConfiguration: { LocationConstraint: cfg.region }
+                }
               }));
               logger2.info("S3 bucket created", { bucket: cfg.bucket });
             } catch (createError) {
@@ -1126,6 +1321,7 @@ function createS3Provider() {
         }
         await client.send(new ListObjectsV2Command({
           Bucket: cfg.bucket,
+          Prefix: withPrefix("", cfg.prefix) || void 0,
           MaxKeys: 1
         }));
         config = cfg;
@@ -1139,7 +1335,10 @@ function createS3Provider() {
           await closeClients();
           return err(original);
         } catch (cleanupError) {
-          return err({ ...original, ext: { ...original.ext, cleanupPending: true, cleanupError } });
+          return err({
+            ...original,
+            ext: { ...original.ext, cleanupPending: true, cleanupError }
+          });
         }
       }
     },
@@ -1151,7 +1350,13 @@ function createS3Provider() {
 }
 var HEX_CHECKSUM = /^[\da-f]+$/i;
 var BASE64_CHECKSUM = /^(?:[A-Z\d+/]{4})*(?:[A-Z\d+/]{2}==|[A-Z\d+/]{3}=)?$/i;
-var ALGORITHMS = /* @__PURE__ */ new Set(["sha256", "sha384", "sha512", "sha1", "md5"]);
+var ALGORITHMS = /* @__PURE__ */ new Set([
+  "sha256",
+  "sha384",
+  "sha512",
+  "sha1",
+  "md5"
+]);
 async function generate(data, options = {}) {
   try {
     const algorithm = options.algorithm ?? "sha256";
@@ -1203,9 +1408,16 @@ async function closeOwnedProvider() {
     return ok(void 0);
   } catch (error) {
     logger3.error("Provider cleanup failed; retaining resource for retry", { error });
-    return err({ ...HaiStorageError.CONNECTION_FAILED, message: storageM("storage_operationFailed", {
-      params: { error: error instanceof Error ? error.message : String(error) }
-    }), cause: error, ext: { cleanupPending: true } });
+    return err({
+      ...HaiStorageError.CONNECTION_FAILED,
+      message: storageM("storage_operationFailed", {
+        params: {
+          error: error instanceof Error ? error.message : String(error)
+        }
+      }),
+      cause: error,
+      ext: { cleanupPending: true }
+    });
   }
 }
 async function failInitialization(result) {
@@ -1216,9 +1428,15 @@ async function failInitialization(result) {
     const ext = { ...result.error.ext };
     delete ext.cleanupPending;
     delete ext.cleanupError;
-    return err({ ...result.error, ext: Object.keys(ext).length > 0 ? ext : void 0 });
+    return err({
+      ...result.error,
+      ext: Object.keys(ext).length > 0 ? ext : void 0
+    });
   }
-  return err({ ...result.error, ext: { ...result.error.ext, cleanupPending: true, cleanupError: cleanup.error } });
+  return err({
+    ...result.error,
+    ext: { ...result.error.ext, cleanupPending: true, cleanupError: cleanup.error }
+  });
 }
 function createProvider(config) {
   switch (config.type) {
@@ -1227,7 +1445,9 @@ function createProvider(config) {
     case "local":
       return createLocalProvider();
     default:
-      throw new Error(storageM("storage_unsupportedType", { params: { type: config.type } }));
+      throw new Error(storageM("storage_unsupportedType", {
+        params: { type: config.type }
+      }));
   }
 }
 var notInitialized = core.module.createNotInitializedKit(
@@ -1268,7 +1488,9 @@ var storage = {
       logger3.warn("Storage init already in progress, skipping concurrent call");
       return err(
         HaiStorageError.OPERATION_FAILED,
-        storageM("storage_operationFailed", { params: { error: "Concurrent initialization detected" } })
+        storageM("storage_operationFailed", {
+          params: { error: "Concurrent initialization detected" }
+        })
       );
     }
     initInProgress = true;
@@ -1286,7 +1508,9 @@ var storage = {
         logger3.error("Storage config validation failed", { error: parseResult.error.message });
         return err(
           HaiStorageError.CONFIG_ERROR,
-          storageM("storage_configError", { params: { error: parseResult.error.message } }),
+          storageM("storage_configError", {
+            params: { error: parseResult.error.message }
+          }),
           parseResult.error
         );
       }
@@ -1313,7 +1537,9 @@ var storage = {
       return await failInitialization(err(
         HaiStorageError.CONNECTION_FAILED,
         storageM("storage_operationFailed", {
-          params: { error: error instanceof Error ? error.message : String(error) }
+          params: {
+            error: error instanceof Error ? error.message : String(error)
+          }
         }),
         error
       ));