@h-ai/storage 0.1.0-alpha8 → 1.0.0-beta.1

package/dist/node.js

@@ -1,19 +1,123 @@
-import { HaiStorageError, StorageConfigSchema } from './chunk-KHZOR6CR.js';
-export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageTypeSchema } from './chunk-KHZOR6CR.js';
-import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-U427BQIQ.js';
-export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-U427BQIQ.js';
+import { HaiStorageError, StorageConfigSchema, PresignUploadOptionsSchema, PresignOptionsSchema } from './chunk-P4NA6BCH.js';
+export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageOperationLogConfigSchema, StorageTypeSchema } from './chunk-P4NA6BCH.js';
+import { storageM, MIME_TYPES, MIME_TYPE_DEFAULT } from './chunk-KVFEQHRX.js';
+export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-KVFEQHRX.js';
+export { STORAGE_DELETE_MAX_KEYS, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema, StorageKeySchema, StoragePrefixSchema, StoragePresignExpiresInSchema, getStorageKeyIssue } from './chunk-P65WYXJG.js';
+import process from 'node:process';
 import { core, err, ok } from '@h-ai/core';
-import { Buffer } from 'buffer';
-import * as crypto from 'crypto';
-import * as fs from 'fs';
-import * as fsp from 'fs/promises';
-import * as path from 'path';
-import { S3Client, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, CopyObjectCommand, DeleteObjectsCommand, DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { Buffer } from 'node:buffer';
+import * as crypto from 'node:crypto';
+import { createHash, timingSafeEqual } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { S3Client, HeadBucketCommand, CreateBucketCommand, ListObjectsV2Command, PutObjectCommand, GetObjectCommand, CopyObjectCommand, DeleteObjectsCommand, DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 
+function toStorageDeleteResult(summary) {
+  if (summary.failures.length === 0)
+    return ok(summary);
+  return {
+    success: false,
+    error: {
+      ...HaiStorageError.OPERATION_FAILED,
+      message: storageM("storage_deleteManyFailed", { params: { count: summary.failures.length } }),
+      ext: { deleteMany: summary }
+    }
+  };
+}
+async function* toByteStream(data, signal) {
+  signal?.throwIfAborted();
+  if (typeof data === "string" || data instanceof Uint8Array) {
+    yield typeof data === "string" ? Buffer.from(data) : data;
+    return;
+  }
+  const iterator = data[Symbol.asyncIterator]();
+  let completed = false;
+  try {
+    while (true) {
+      signal?.throwIfAborted();
+      let result;
+      let onAbort;
+      try {
+        const cancelled = signal ? new Promise((_, reject) => {
+          onAbort = () => reject(signal.reason);
+          signal.addEventListener("abort", onAbort, { once: true });
+        }) : void 0;
+        const next = iterator.next();
+        result = await (cancelled ? Promise.race([next, cancelled]) : next);
+      } finally {
+        if (onAbort)
+          signal?.removeEventListener("abort", onAbort);
+      }
+      if (result.done) {
+        completed = true;
+        break;
+      }
+      if (!(result.value instanceof Uint8Array))
+        throw new TypeError(storageM("storage_streamInvalidChunk"));
+      yield result.value;
+    }
+    signal?.throwIfAborted();
+  } finally {
+    if (!completed && iterator.return) {
+      if (signal?.aborted)
+        void Promise.resolve(iterator.return()).catch(() => {
+        });
+      else
+        await iterator.return();
+    }
+  }
+}
+
+// src/providers/storage-operation-log.ts
+function normalizePayloadValue(value) {
+  if (value instanceof Uint8Array) {
+    return { byteLength: value.byteLength };
+  }
+  return value;
+}
+function stringifyOperationPayload(payload, maxLength) {
+  if (maxLength <= 0) {
+    return "";
+  }
+  try {
+    const text = JSON.stringify(payload, (_key, value) => {
+      if (typeof value === "bigint") {
+        return value.toString();
+      }
+      if (typeof value === "function") {
+        return "[Function]";
+      }
+      return normalizePayloadValue(value);
+    });
+    return text.length > maxLength ? `${text.slice(0, maxLength)}...` : text;
+  } catch {
+    const text = String(payload);
+    return text.length > maxLength ? `${text.slice(0, maxLength)}...` : text;
+  }
+}
+function logStorageOperation(logger4, config, category, operation, payload) {
+  if (!config?.[category]) {
+    return;
+  }
+  logger4[config.level]("Storage operation executed", {
+    category,
+    operation,
+    payload: stringifyOperationPayload(payload, config.maxLength)
+  });
+}
+
+// src/providers/storage-provider-local.ts
 var logger = core.logger.child({ module: "storage", scope: "provider-local" });
+var PATH_SEGMENT_SPLIT_REGEX = /[\\/]+/;
 function toStorageError(error, key) {
   const e = error;
+  if (e.code === "EEXIST") {
+    return { ...HaiStorageError.ALREADY_EXISTS, message: storageM("storage_fileAlreadyExists", { params: { key: key ?? "" } }), cause: error };
+  }
   if (e.code === "ENOENT") {
     return {
       ...HaiStorageError.NOT_FOUND,
@@ -63,7 +167,7 @@ function calculateEtag(stat2) {
   return `"${stat2.size.toString(16)}-${stat2.mtimeMs.toString(16)}"`;
 }
 function isMetaFile(key) {
-  return key.endsWith(".meta.json");
+  return key.endsWith(".meta.json") || key.endsWith(".upload.tmp");
 }
 function createInvalidPathError() {
   const error = new Error(storageM("storage_pathTraversal"));
@@ -71,7 +175,7 @@ function createInvalidPathError() {
   return error;
 }
 function hasPathTraversalSegment(key) {
-  const segments = key.split(/[\\/]+/).filter(Boolean);
+  const segments = key.split(PATH_SEGMENT_SPLIT_REGEX).filter(Boolean);
   return segments.includes("..");
 }
 function safePath(root, key) {
@@ -102,14 +206,8 @@ function createLocalProvider() {
   function fullPath(key) {
     return safePath(getConfig().root, key);
   }
-  function toBuffer(data) {
-    if (typeof data === "string") {
-      return Buffer.from(data);
-    }
-    if (data instanceof Buffer) {
-      return data;
-    }
-    return Buffer.from(data);
+  function logOperation(category, operation, payload) {
+    logStorageOperation(logger, config?.operationLog, category, operation, payload);
   }
   const file = {
     async put(key, data, options = {}) {
@@ -119,13 +217,23 @@ function createLocalProvider() {
           storageM("storage_metaFileAccess", { params: { key } })
         );
       }
+      let temporaryPath;
       try {
         const filePath = fullPath(key);
-        const buffer = toBuffer(data);
-        logger.debug("Putting file", { key, size: buffer.length });
+        logOperation("write", "file.put", { key, options });
         const dir2 = path.dirname(filePath);
         await fsp.mkdir(dir2, { recursive: true, mode: getConfig().directoryMode });
-        await fsp.writeFile(filePath, buffer, { mode: getConfig().fileMode });
+        temporaryPath = `${filePath}.${crypto.randomUUID()}.upload.tmp`;
+        await pipeline(
+          Readable.from(toByteStream(data, options.signal), { objectMode: false }),
+          fs.createWriteStream(temporaryPath, { flags: "wx", mode: getConfig().fileMode }),
+          { signal: options.signal }
+        );
+        options.signal?.throwIfAborted();
+        if (options.ifNoneMatch === "*")
+          await fsp.link(temporaryPath, filePath);
+        else
+          await fsp.rename(temporaryPath, filePath);
         const stat2 = await fsp.stat(filePath);
         const metadata = {
           key,
@@ -135,7 +243,7 @@ function createLocalProvider() {
           etag: calculateEtag(stat2),
           metadata: options.metadata
         };
-        if (options.metadata) {
+        if (options.metadata || options.contentType) {
           const metaPath = `${filePath}.meta.json`;
           await fsp.writeFile(metaPath, JSON.stringify({
             contentType: options.contentType,
@@ -146,9 +254,26 @@ function createLocalProvider() {
       } catch (error) {
         logger.warn("Put file failed", { key, error });
         return err(toStorageError(error, key));
+      } finally {
+        if (temporaryPath)
+          await fsp.unlink(temporaryPath).catch(() => {
+          });
       }
     },
     async get(key, options = {}) {
+      const streamed = await file.getStream(key, options);
+      if (!streamed.success)
+        return streamed;
+      try {
+        const chunks = [];
+        for await (const chunk of streamed.data)
+          chunks.push(chunk);
+        return ok(Buffer.concat(chunks));
+      } catch (error) {
+        return err(toStorageError(error, key));
+      }
+    },
+    async getStream(key, options = {}) {
       if (isMetaFile(key)) {
         return err(
           HaiStorageError.INVALID_PATH,
@@ -157,20 +282,17 @@ function createLocalProvider() {
       }
       try {
         const filePath = fullPath(key);
-        if (options.rangeStart !== void 0 || options.rangeEnd !== void 0) {
-          const stat2 = await fsp.stat(filePath);
-          const start = options.rangeStart ?? 0;
-          const end = options.rangeEnd !== void 0 ? options.rangeEnd : stat2.size - 1;
-          return new Promise((resolve2) => {
-            const chunks = [];
-            const stream = fs.createReadStream(filePath, { start, end });
-            stream.on("data", (chunk) => chunks.push(chunk));
-            stream.on("end", () => resolve2(ok(Buffer.concat(chunks))));
-            stream.on("error", (error) => resolve2(err(toStorageError(error, 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 } }));
+        async function* read() {
+          const stream = fs.createReadStream(filePath, { start: options.rangeStart, end: options.rangeEnd, signal: options.signal });
+          for await (const chunk of stream)
+            yield chunk;
         }
-        const data = await fsp.readFile(filePath);
-        return ok(data);
+        return ok(read());
       } catch (error) {
         return err(toStorageError(error, key));
       }
@@ -184,6 +306,7 @@ function createLocalProvider() {
       }
       try {
         const filePath = fullPath(key);
+        logOperation("read", "file.head", { key });
         const stat2 = await fsp.stat(filePath);
         if (stat2.isDirectory()) {
           return err(
@@ -220,6 +343,7 @@ function createLocalProvider() {
       }
       try {
         const filePath = fullPath(key);
+        logOperation("read", "file.exists", { key });
         await fsp.access(filePath, fs.constants.F_OK);
         return ok(true);
       } catch (error) {
@@ -238,6 +362,7 @@ function createLocalProvider() {
       }
       try {
         const filePath = fullPath(key);
+        logOperation("write", "file.delete", { key });
         logger.debug("Deleting file", { key });
         await fsp.unlink(filePath);
         try {
@@ -254,21 +379,23 @@ function createLocalProvider() {
       }
     },
     async deleteMany(keys) {
-      const results = await Promise.allSettled(keys.map((key) => file.delete(key)));
-      const errors = [];
-      for (const result of results) {
-        if (result.status === "fulfilled" && !result.value.success) {
-          errors.push(result.value.error);
+      logOperation("write", "file.deleteMany", { count: keys.length, keys });
+      const summary = { deletedKeys: [], failures: [] };
+      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
+            summary.deletedKeys.push(key);
         }
       }
-      if (errors.length > 0) {
-        return err(
-          HaiStorageError.OPERATION_FAILED,
-          storageM("storage_deleteManyFailed", { params: { count: errors.length } }),
-          errors
-        );
-      }
-      return ok(void 0);
+      return toStorageDeleteResult(summary);
     },
     async copy(sourceKey, destKey, options = {}) {
       if (isMetaFile(sourceKey) || isMetaFile(destKey)) {
@@ -281,6 +408,7 @@ function createLocalProvider() {
       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);
@@ -310,48 +438,85 @@ function createLocalProvider() {
     async list(options = {}) {
       try {
         const cfg = getConfig();
-        const prefix = options.prefix || "";
-        const delimiter = options.delimiter || "";
-        const maxKeys = options.maxKeys || 1e3;
-        const basePath = safePath(cfg.root, prefix);
-        const files = [];
-        const commonPrefixes = /* @__PURE__ */ new Set();
-        async function readDir(dirPath) {
-          let entries;
+        const prefix = options.prefix === void 0 ? "" : options.prefix;
+        const delimiter = options.delimiter === void 0 ? "" : options.delimiter;
+        const maxKeys = options.maxKeys === void 0 ? 1e3 : options.maxKeys;
+        if (typeof prefix !== "string" || typeof delimiter !== "string" || !Number.isInteger(maxKeys) || maxKeys < 1 || maxKeys > 1e3 || Buffer.from(prefix).toString("utf8") !== prefix || Buffer.from(delimiter).toString("utf8") !== delimiter) {
+          return err(HaiStorageError.INVALID_LIST_OPTIONS, storageM("storage_listOptionsInvalid"));
+        }
+        logOperation("read", "dir.list", { options });
+        safePath(cfg.root, prefix);
+        const root = await fsp.realpath(cfg.root);
+        const scope = crypto.createHash("sha256").update(JSON.stringify([root, prefix, delimiter])).digest("hex");
+        let after = "";
+        if (options.continuationToken !== void 0) {
+          const token = options.continuationToken;
           try {
-            entries = await fsp.readdir(dirPath, { withFileTypes: true });
+            if (typeof token !== "string" || token.length === 0 || token.length > 262144)
+              throw new Error("Invalid cursor encoding");
+            const bytes = Buffer.from(token, "base64url");
+            if (bytes.toString("base64url") !== token)
+              throw new Error("Invalid cursor encoding");
+            const decoded = JSON.parse(bytes.toString("utf8"));
+            if (!Array.isArray(decoded) || decoded.length !== 3 || decoded[0] !== 1 || decoded[1] !== scope || typeof decoded[2] !== "string" || decoded[2].length === 0 || !decoded[2].startsWith(prefix)) {
+              throw new Error("Invalid cursor scope");
+            }
+            after = decoded[2];
           } catch {
-            return;
+            return err(HaiStorageError.INVALID_LIST_OPTIONS, storageM("storage_listCursorInvalid"));
           }
+        }
+        const files = [];
+        const commonPrefixes = [];
+        const compare = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+        async function* readDir(dirPath, directoryKey) {
+          const entries = await fsp.readdir(dirPath, { withFileTypes: true });
+          entries.sort((left, right) => compare(left.name + (left.isDirectory() ? "/" : ""), right.name + (right.isDirectory() ? "/" : "")));
           for (const entry of entries) {
-            if (files.length >= maxKeys)
-              return;
-            const fullEntryPath = path.join(dirPath, entry.name);
-            const key = path.relative(cfg.root, fullEntryPath).replace(/\\/g, "/");
-            if (entry.name.endsWith(".meta.json"))
+            if (isMetaFile(entry.name))
               continue;
+            const key = directoryKey + entry.name;
+            const filePath = path.join(dirPath, entry.name);
             if (entry.isDirectory()) {
-              if (delimiter) {
-                commonPrefixes.add(`${key}/`);
-              } else {
-                await readDir(fullEntryPath);
+              const childPrefix = `${key}/`;
+              if (prefix.startsWith(childPrefix) || childPrefix.startsWith(prefix)) {
+                yield* readDir(filePath, childPrefix);
               }
-            } else if (entry.isFile()) {
-              const stat2 = await fsp.stat(fullEntryPath);
-              files.push({
-                key,
-                size: stat2.size,
-                contentType: getMimeType2(key),
-                lastModified: stat2.mtime
-              });
+            } else if (entry.isFile() && key.startsWith(prefix)) {
+              yield { key, filePath };
             }
           }
         }
-        await readDir(basePath);
+        let previous = "";
+        let last = "";
+        let count = 0;
+        let isTruncated = false;
+        for await (const entry of readDir(root, "")) {
+          const index = delimiter ? entry.key.indexOf(delimiter, prefix.length) : -1;
+          const logicalKey = index < 0 ? entry.key : entry.key.slice(0, index + delimiter.length);
+          if (logicalKey === previous)
+            continue;
+          previous = logicalKey;
+          if (compare(logicalKey, after) <= 0)
+            continue;
+          if (count === maxKeys) {
+            isTruncated = true;
+            break;
+          }
+          if (index >= 0) {
+            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 });
+          }
+          count++;
+          last = logicalKey;
+        }
         return ok({
           files,
-          commonPrefixes: Array.from(commonPrefixes),
-          isTruncated: files.length >= maxKeys
+          commonPrefixes,
+          isTruncated,
+          ...isTruncated ? { nextContinuationToken: Buffer.from(JSON.stringify([1, scope, last])).toString("base64url") } : {}
         });
       } catch (error) {
         return err(toStorageError(error));
@@ -360,6 +525,7 @@ function createLocalProvider() {
     async delete(prefix) {
       try {
         const dirPath = fullPath(prefix);
+        logOperation("write", "dir.delete", { prefix });
         await fsp.rm(dirPath, { recursive: true, force: true });
         return ok(void 0);
       } catch (error) {
@@ -372,18 +538,15 @@ function createLocalProvider() {
   };
   const presign = {
     async getUrl(key, options) {
-      const expiresIn = options?.expiresIn || 3600;
-      const expires = Math.floor(Date.now() / 1e3) + expiresIn;
-      const signature = crypto.createHash("sha256").update(`${key}:${expires}`).digest("hex").slice(0, 16);
-      return ok(`local://${key}?expires=${expires}&signature=${signature}`);
+      logOperation("read", "presign.getUrl", { key, options });
+      return err(HaiStorageError.UNSUPPORTED_OPERATION, storageM("storage_localPresignUnsupported"));
     },
     async putUrl(key, options) {
-      const expiresIn = options?.expiresIn || 3600;
-      const expires = Math.floor(Date.now() / 1e3) + expiresIn;
-      const signature = crypto.createHash("sha256").update(`put:${key}:${expires}`).digest("hex").slice(0, 16);
-      return ok(`local://${key}?action=put&expires=${expires}&signature=${signature}`);
+      logOperation("write", "presign.putUrl", { key, options });
+      return err(HaiStorageError.UNSUPPORTED_OPERATION, storageM("storage_localPresignUnsupported"));
     },
-    publicUrl(_key) {
+    publicUrl(key) {
+      logOperation("read", "presign.publicUrl", { key });
       return null;
     }
   };
@@ -423,20 +586,14 @@ function createLocalProvider() {
   };
 }
 var logger2 = core.logger.child({ module: "storage", scope: "provider-s3" });
-function sanitizeEndpointUrl(url) {
-  try {
-    const parsed = new URL(url);
-    if (parsed.username)
-      parsed.username = "***";
-    if (parsed.password)
-      parsed.password = "***";
-    return parsed.toString();
-  } catch {
-    return "(invalid url)";
-  }
-}
+var TRAILING_SLASHES_REGEX = /\/+$/;
+var LEADING_SLASHES_REGEX = /^\/+/;
+var DELETE_BATCH_SIZE = 1e3;
+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 === "NoSuchKey" || e.Code === "NoSuchKey" || e.name === "NotFound" || e.Code === "NotFound" || e.name === "404" || e.$metadata?.httpStatusCode === 404) {
     return {
       ...HaiStorageError.NOT_FOUND,
@@ -474,12 +631,12 @@ function toStorageError2(error, key) {
 function withPrefix(key, prefix) {
   if (!prefix)
     return key;
-  return `${prefix.replace(/\/+$/, "")}/${key.replace(/^\/+/, "")}`;
+  return `${prefix.replace(TRAILING_SLASHES_REGEX, "")}/${key.replace(LEADING_SLASHES_REGEX, "")}`;
 }
 function withoutPrefix(key, prefix) {
   if (!prefix)
     return key;
-  const normalizedPrefix = `${prefix.replace(/\/+$/, "")}/`;
+  const normalizedPrefix = `${prefix.replace(TRAILING_SLASHES_REGEX, "")}/`;
   if (key.startsWith(normalizedPrefix)) {
     return key.slice(normalizedPrefix.length);
   }
@@ -487,15 +644,49 @@ function withoutPrefix(key, prefix) {
 }
 function createS3Provider() {
   let client = null;
+  let deleteClient = null;
+  let presignClient = null;
   let config = null;
-  function getClient() {
-    if (!client) {
+  let ready = false;
+  let closing = null;
+  function closeClients() {
+    ready = false;
+    config = null;
+    if (closing)
+      return closing;
+    closing = Promise.resolve().then(() => {
+      const failures = [];
+      for (const kind of ["normal", "delete", "presign"]) {
+        const owned = kind === "normal" ? client : kind === "delete" ? deleteClient : presignClient;
+        if (!owned)
+          continue;
+        try {
+          owned.destroy();
+          if (kind === "normal")
+            client = null;
+          else if (kind === "delete")
+            deleteClient = null;
+          else presignClient = null;
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      if (failures.length > 0)
+        throw new AggregateError(failures, "S3 client cleanup failed");
+    }).finally(() => {
+      closing = null;
+    });
+    return closing;
+  }
+  function getClient(operation) {
+    const selected = operation === "deleteMany" ? deleteClient : operation === "presign" ? presignClient ?? client : client;
+    if (!ready || !selected) {
       throw new Error(storageM("storage_s3ClientNotInitialized"));
     }
-    return client;
+    return selected;
   }
   function getConfig() {
-    if (!config) {
+    if (!ready || !config) {
       throw new Error(storageM("storage_s3ConfigNotInitialized"));
     }
     return config;
@@ -503,29 +694,59 @@ function createS3Provider() {
   function fullKey(key) {
     return withPrefix(key, getConfig().prefix);
   }
+  function logOperation(category, operation, payload) {
+    logStorageOperation(logger2, config?.operationLog, category, operation, payload);
+  }
   const file = {
     async put(key, data, options = {}) {
       try {
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
+        options.signal?.throwIfAborted();
         const body = typeof data === "string" ? Buffer.from(data) : data;
-        await s3Client.send(new PutObjectCommand({
+        const buffered = body instanceof Uint8Array;
+        let size = buffered ? body.byteLength : 0;
+        const params = {
           Bucket: s3Config.bucket,
           Key: fullPath,
-          Body: body,
           ContentType: options.contentType,
           Metadata: options.metadata,
           CacheControl: options.cacheControl,
-          ContentDisposition: options.contentDisposition
-        }));
+          ContentDisposition: options.contentDisposition,
+          IfNoneMatch: options.ifNoneMatch
+        };
+        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 {
+          async function* counted() {
+            for await (const chunk of toByteStream(data, options.signal)) {
+              size += chunk.byteLength;
+              yield chunk;
+            }
+          }
+          const stream = Readable.from(counted(), { objectMode: false });
+          const controller = new AbortController();
+          const abort = () => controller.abort();
+          options.signal?.addEventListener("abort", abort, { once: true });
+          try {
+            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();
+          } finally {
+            options.signal?.removeEventListener("abort", abort);
+            stream.destroy();
+          }
+        }
         const headResult = await file.head(key);
         if (headResult.success) {
           return headResult;
         }
         return ok({
           key,
-          size: body.length,
+          size,
           contentType: options.contentType || "application/octet-stream",
           lastModified: /* @__PURE__ */ new Date()
         });
@@ -534,10 +755,24 @@ function createS3Provider() {
       }
     },
     async get(key, options = {}) {
+      const streamed = await file.getStream(key, options);
+      if (!streamed.success)
+        return streamed;
+      try {
+        const chunks = [];
+        for await (const chunk of streamed.data)
+          chunks.push(chunk);
+        return ok(Buffer.concat(chunks));
+      } catch (error) {
+        return err(toStorageError2(error, key));
+      }
+    },
+    async getStream(key, options = {}) {
       try {
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
+        logOperation("read", "file.getStream", { key, fullPath, options });
         let Range;
         if (options.rangeStart !== void 0 || options.rangeEnd !== void 0) {
           const start = options.rangeStart ?? 0;
@@ -548,19 +783,15 @@ function createS3Provider() {
           Bucket: s3Config.bucket,
           Key: fullPath,
           Range
-        }));
+        }), { abortSignal: options.signal });
         if (!response.Body) {
           return err(
             HaiStorageError.OPERATION_FAILED,
             storageM("storage_responseBodyEmpty")
           );
         }
-        const chunks = [];
         const stream = response.Body;
-        for await (const chunk of stream) {
-          chunks.push(chunk);
-        }
-        return ok(Buffer.concat(chunks));
+        return ok(stream);
       } catch (error) {
         return err(toStorageError2(error, key));
       }
@@ -570,6 +801,7 @@ function createS3Provider() {
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
+        logOperation("read", "file.head", { key, fullPath });
         const response = await s3Client.send(new HeadObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath
@@ -587,6 +819,7 @@ function createS3Provider() {
       }
     },
     async exists(key) {
+      logOperation("read", "file.exists", { key });
       const result = await file.head(key);
       if (result.success) {
         return ok(true);
@@ -601,6 +834,7 @@ function createS3Provider() {
         const s3Client = getClient();
         const s3Config = getConfig();
         const fullPath = fullKey(key);
+        logOperation("write", "file.delete", { key, fullPath });
         await s3Client.send(new DeleteObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath
@@ -612,18 +846,65 @@ function createS3Provider() {
     },
     async deleteMany(keys) {
       try {
-        const s3Client = getClient();
+        const s3Client = getClient("deleteMany");
         const s3Config = getConfig();
-        if (keys.length === 0) {
-          return ok(void 0);
-        }
-        await s3Client.send(new DeleteObjectsCommand({
-          Bucket: s3Config.bucket,
-          Delete: {
-            Objects: keys.map((key) => ({ Key: fullKey(key) }))
+        logOperation("write", "file.deleteMany", { count: keys.length, 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);
+          for (let attempt = 0; pending.length > 0 && attempt < 3; attempt++) {
+            let response;
+            try {
+              response = await s3Client.send(new DeleteObjectsCommand({
+                Bucket: s3Config.bucket,
+                Delete: { Objects: [...new Set(pending.map(fullKey))].map((Key) => ({ Key })), Quiet: false }
+              }));
+            } catch (cause) {
+              const failure = cause && typeof cause === "object" ? cause : {};
+              const status = failure.$metadata?.httpStatusCode;
+              const code = failure.name && /^[\w.-]{1,80}$/.test(failure.name) ? failure.name : "RequestFailed";
+              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" })));
+              return toStorageDeleteResult(summary);
+            }
+            const outcomes = /* @__PURE__ */ new Map();
+            const requested = new Set(pending.map(fullKey));
+            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" }))
+            ];
+            for (const item of items) {
+              if (!item.key || !requested.has(item.key) || outcomes.has(item.key)) {
+                malformed = true;
+                break;
+              }
+              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" })));
+              return toStorageDeleteResult(summary);
+            }
+            const retry = [];
+            for (const key of pending) {
+              const code = outcomes.get(fullKey(key));
+              if (code === null)
+                summary.deletedKeys.push(key);
+              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" });
+            }
+            pending = retry;
+            if (pending.length > 0)
+              await new Promise((resolve2) => setTimeout(resolve2, 100 * 2 ** attempt));
           }
-        }));
-        return ok(void 0);
+        }
+        return toStorageDeleteResult(summary);
       } catch (error) {
         return err(toStorageError2(error));
       }
@@ -634,6 +915,7 @@ function createS3Provider() {
         const s3Config = getConfig();
         const sourceFullPath = fullKey(sourceKey);
         const destFullPath = fullKey(destKey);
+        logOperation("write", "file.copy", { sourceKey, destKey, sourceFullPath, destFullPath, options });
         await s3Client.send(new CopyObjectCommand({
           Bucket: s3Config.bucket,
           CopySource: `${s3Config.bucket}/${sourceFullPath}`,
@@ -653,6 +935,7 @@ function createS3Provider() {
       try {
         const s3Client = getClient();
         const s3Config = getConfig();
+        logOperation("read", "dir.list", { options });
         let prefix = s3Config.prefix || "";
         if (options.prefix) {
           prefix = withPrefix(options.prefix, s3Config.prefix);
@@ -685,6 +968,7 @@ function createS3Provider() {
     },
     async delete(prefix) {
       try {
+        logOperation("write", "dir.delete", { prefix });
         let continuationToken;
         do {
           const listResult = await dir.list({
@@ -713,17 +997,19 @@ function createS3Provider() {
   const presign = {
     async getUrl(key, options) {
       try {
-        const s3Client = getClient();
+        const parsed = PresignOptionsSchema.parse(options ?? {});
+        const s3Client = getClient("presign");
         const s3Config = getConfig();
         const fullPath = fullKey(key);
+        logOperation("read", "presign.getUrl", { key, fullPath, options });
         const command = new GetObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath,
-          ResponseContentType: options?.responseContentType,
-          ResponseContentDisposition: options?.responseContentDisposition
+          ResponseContentType: parsed.responseContentType,
+          ResponseContentDisposition: parsed.responseContentDisposition
         });
         const url = await getSignedUrl(s3Client, command, {
-          expiresIn: options?.expiresIn || 3600
+          expiresIn: parsed.expiresIn
         });
         return ok(url);
       } catch (error) {
@@ -736,16 +1022,18 @@ function createS3Provider() {
     },
     async putUrl(key, options) {
       try {
-        const s3Client = getClient();
+        const parsed = PresignUploadOptionsSchema.parse(options ?? {});
+        const s3Client = getClient("presign");
         const s3Config = getConfig();
         const fullPath = fullKey(key);
+        logOperation("write", "presign.putUrl", { key, fullPath, options });
         const command = new PutObjectCommand({
           Bucket: s3Config.bucket,
           Key: fullPath,
-          ContentType: options?.contentType || "application/octet-stream"
+          ContentType: parsed.contentType
         });
         const url = await getSignedUrl(s3Client, command, {
-          expiresIn: options?.expiresIn || 3600
+          expiresIn: parsed.expiresIn
         });
         return ok(url);
       } catch (error) {
@@ -762,7 +1050,8 @@ function createS3Provider() {
         return null;
       }
       const fullPath = fullKey(key);
-      return `${s3Config.publicUrl.replace(/\/+$/, "")}/${fullPath}`;
+      logOperation("read", "presign.publicUrl", { key, fullPath });
+      return `${s3Config.publicUrl.replace(TRAILING_SLASHES_REGEX, "")}/${fullPath}`;
     }
   };
   return {
@@ -778,53 +1067,146 @@ function createS3Provider() {
         );
       }
       try {
+        await closeClients();
         config = cfg;
         logger2.info("Connecting S3 provider", {
           bucket: cfg.bucket,
           region: cfg.region,
-          endpoint: cfg.endpoint ? sanitizeEndpointUrl(cfg.endpoint) : void 0
+          endpoint: cfg.endpoint ? core.sanitize.sanitizeUrl(cfg.endpoint) : void 0
         });
-        client = new S3Client({
+        const clientConfig = {
           region: cfg.region,
           endpoint: cfg.endpoint,
           forcePathStyle: cfg.forcePathStyle,
+          // 不强制兼容服务实现 AWS checksum 扩展；校验工具按实际字节独立计算。
+          requestChecksumCalculation: "WHEN_REQUIRED",
+          responseChecksumValidation: "WHEN_REQUIRED",
           credentials: {
             accessKeyId: cfg.accessKeyId,
             secretAccessKey: cfg.secretAccessKey
           }
-        });
+        };
+        client = new S3Client(clientConfig);
+        deleteClient = new S3Client({ ...clientConfig, maxAttempts: 1 });
+        if (cfg.publicEndpoint)
+          presignClient = new S3Client({ ...clientConfig, endpoint: cfg.publicEndpoint });
+        if (cfg.createBucket) {
+          try {
+            await client.send(new HeadBucketCommand({ Bucket: cfg.bucket }));
+          } catch (error) {
+            if (!(error && typeof error === "object" && "$metadata" in error && error.$metadata && typeof error.$metadata === "object" && "httpStatusCode" in error.$metadata && error.$metadata.httpStatusCode === 404)) {
+              throw error;
+            }
+            try {
+              await client.send(new CreateBucketCommand({
+                Bucket: cfg.bucket,
+                // AWS us-east-1 要省略 LocationConstraint；兼容服务可使用自定义区域名。
+                ...cfg.region === "us-east-1" ? {} : { CreateBucketConfiguration: { LocationConstraint: cfg.region } }
+              }));
+              logger2.info("S3 bucket created", { bucket: cfg.bucket });
+            } catch (createError) {
+              if (!(createError instanceof Error && createError.name === "BucketAlreadyOwnedByYou"))
+                throw createError;
+              await client.send(new HeadBucketCommand({ Bucket: cfg.bucket }));
+            }
+          }
+        }
         await client.send(new ListObjectsV2Command({
           Bucket: cfg.bucket,
           MaxKeys: 1
         }));
+        config = cfg;
+        ready = true;
         logger2.info("S3 provider connected", { bucket: cfg.bucket });
         return ok(void 0);
       } catch (error) {
         logger2.error("S3 provider connect failed", { error });
-        config = null;
-        client = null;
-        return err(toStorageError2(error));
-      }
-    },
-    async close() {
-      if (client) {
-        client.destroy();
-        client = null;
-        config = null;
-        logger2.info("S3 provider disconnected");
+        const original = toStorageError2(error);
+        try {
+          await closeClients();
+          return err(original);
+        } catch (cleanupError) {
+          return err({ ...original, ext: { ...original.ext, cleanupPending: true, cleanupError } });
+        }
       }
     },
+    close: closeClients,
     isConnected() {
-      return client !== null && config !== null;
+      return ready && client !== null && deleteClient !== null && config !== null;
     }
   };
 }
+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"]);
+async function generate(data, options = {}) {
+  try {
+    const algorithm = options.algorithm ?? "sha256";
+    if (!ALGORITHMS.has(algorithm))
+      return err(HaiStorageError.INVALID_CHECKSUM, storageM("storage_checksumInvalid"));
+    const hash = createHash(algorithm);
+    for await (const chunk of toByteStream(data, options.signal))
+      hash.update(chunk);
+    return ok(hash.digest(options.encoding ?? "hex"));
+  } catch (error) {
+    return err(HaiStorageError.CHECKSUM_FAILED, storageM("storage_checksumFailed"), error);
+  }
+}
+var checksum = {
+  generate,
+  async verify(data, expected, options = {}) {
+    const encoding = options.encoding ?? "hex";
+    const valid = encoding === "hex" ? expected.length % 2 === 0 && HEX_CHECKSUM.test(expected) : BASE64_CHECKSUM.test(expected) && expected.length > 0;
+    if (!valid)
+      return err(HaiStorageError.INVALID_CHECKSUM, storageM("storage_checksumInvalid"));
+    const calculated = await generate(data, options);
+    if (!calculated.success)
+      return calculated;
+    const actualBytes = Buffer.from(calculated.data, encoding);
+    const expectedBytes = Buffer.from(expected, encoding);
+    return ok(actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes));
+  }
+};
 
 // src/storage-main.ts
 var logger3 = core.logger.child({ module: "storage", scope: "main" });
 var currentProvider = null;
 var currentConfig = null;
 var initInProgress = false;
+var pendingProvider = null;
+var initCompletion = null;
+var closingPromise = null;
+async function closeOwnedProvider() {
+  if (currentProvider) {
+    pendingProvider = currentProvider;
+    currentProvider = null;
+  }
+  currentConfig = null;
+  if (!pendingProvider)
+    return ok(void 0);
+  try {
+    await pendingProvider.close();
+    pendingProvider = null;
+    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 } });
+  }
+}
+async function failInitialization(result) {
+  const cleanup = await closeOwnedProvider();
+  if (result.success)
+    return result;
+  if (cleanup.success) {
+    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: { ...result.error.ext, cleanupPending: true, cleanupError: cleanup.error } });
+}
 function createProvider(config) {
   switch (config.type) {
     case "s3":
@@ -849,17 +1231,27 @@ var notInitializedPresign = new Proxy(
   }
 );
 var storage = {
+  checksum,
   /**
    * 初始化存储连接。
    *
    * 如果当前已有活跃连接，会先自动 close 再重新初始化。
-   * 配置会通过 Zod Schema 校验；校验失败或连接异常会返回 `CONNECTION_FAILED`。
+   * 配置通过 Zod Schema 校验；校验、连接或清理失败均返回 HaiResult，不发布失败候选。
    *
    * @param config 存储配置（S3 或本地），支持省略带默认值的字段。
    * @returns 成功时返回 ok(undefined)；失败时返回包含错误码和消息的 err。
+   * @example
+   * ```ts
+   * import { storage } from '@h-ai/storage'
+   *
+   * const initialized = await storage.init({ type: 'local', root: './data/uploads' })
+   * if (!initialized.success) throw new Error(initialized.error.message)
+   * const closed = await storage.close()
+   * if (!closed.success) throw new Error(closed.error.message)
+   * ```
    */
   async init(config) {
-    if (initInProgress) {
+    if (initInProgress || closingPromise) {
       logger3.warn("Storage init already in progress, skipping concurrent call");
       return err(
         HaiStorageError.OPERATION_FAILED,
@@ -867,11 +1259,14 @@ var storage = {
       );
     }
     initInProgress = true;
+    let resolveInit;
+    initCompletion = new Promise((resolve2) => {
+      resolveInit = resolve2;
+    });
     try {
-      if (currentProvider) {
-        logger3.warn("Storage module is already initialized, reinitializing");
-        await storage.close();
-      }
+      const cleanup = await closeOwnedProvider();
+      if (!cleanup.success)
+        return cleanup;
       logger3.info("Initializing storage module");
       const parseResult = StorageConfigSchema.safeParse(config);
       if (!parseResult.success) {
@@ -883,30 +1278,36 @@ var storage = {
         );
       }
       const parsed = parseResult.data;
+      if (core.module.requiresSharedState(process.env) && parsed.type === "local")
+        return err(HaiStorageError.CONFIG_ERROR, storageM("storage_sharedBackendRequired"));
       const provider = createProvider(parsed);
+      pendingProvider = provider;
       const connectResult = await provider.connect(parsed);
       if (!connectResult.success) {
         logger3.error("Storage module initialization failed", {
           code: connectResult.error.code,
           message: connectResult.error.message
         });
-        return connectResult;
+        return await failInitialization(connectResult);
       }
+      pendingProvider = null;
       currentProvider = provider;
       currentConfig = parsed;
       logger3.info("Storage module initialized");
       return ok(void 0);
     } catch (error) {
       logger3.error("Storage module initialization failed", { error });
-      return err(
+      return await failInitialization(err(
         HaiStorageError.CONNECTION_FAILED,
         storageM("storage_operationFailed", {
           params: { error: error instanceof Error ? error.message : String(error) }
         }),
         error
-      );
+      ));
     } finally {
       initInProgress = false;
+      initCompletion = null;
+      resolveInit();
     }
   },
   /** 文件操作接口。未初始化时所有方法返回 NOT_INITIALIZED 错误 */
@@ -921,36 +1322,39 @@ var storage = {
   get presign() {
     return currentProvider?.presign ?? notInitializedPresign;
   },
-  /** 当前解析后的存储配置；未初始化或已关闭时为 null */
+  /** 当前脱敏后的存储配置快照；未初始化或已关闭时为 null */
   get config() {
-    return currentConfig;
+    return currentConfig ? core.sanitize.sanitizeSensitiveFields(currentConfig) : null;
   },
   /** 是否已完成初始化 */
   get isInitialized() {
-    return currentProvider !== null;
+    return currentProvider !== null && currentProvider.isConnected();
   },
   /**
    * 关闭存储连接并释放资源
    *
    * 关闭后 file/dir/presign 操作将返回 NOT_INITIALIZED 错误。
-   * 重复调用不会报错。
+   * 等待初始化并合并并发关闭；失败时保留资源供 close/init 重试。
+   * @returns 所有客户端释放成功才返回成功。
+   * @example
+   * ```ts
+   * import { storage } from '@h-ai/storage'
+   *
+   * const closed = await storage.close()
+   * if (!closed.success) throw new Error(closed.error.message)
+   * ```
    */
   async close() {
-    if (!currentProvider) {
-      currentConfig = null;
-      logger3.info("Storage module already closed, skipping");
-      return;
-    }
-    logger3.info("Closing storage module");
-    try {
-      await currentProvider.close();
-      logger3.info("Storage module closed");
-    } catch (error) {
-      logger3.error("Storage module close failed", { error });
-    } finally {
-      currentProvider = null;
-      currentConfig = null;
+    if (!closingPromise) {
+      closingPromise = (async () => {
+        if (initCompletion)
+          await initCompletion;
+        return await closeOwnedProvider();
+      })().finally(() => {
+        closingPromise = null;
+      });
     }
+    return await closingPromise;
   }
 };