@zucker-framework/storage 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1035 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/storage.interface.ts
+var DANGEROUS_EXTENSIONS = [
+  "exe",
+  "bat",
+  "cmd",
+  "com",
+  "msi",
+  "scr",
+  "pif",
+  "vbs",
+  "vbe",
+  "js",
+  "jse",
+  "wsf",
+  "wsh",
+  "ps1",
+  "sh",
+  "bash",
+  "csh",
+  "ksh",
+  "php",
+  "phtml",
+  "php3",
+  "php4",
+  "php5",
+  "phps",
+  "asp",
+  "aspx",
+  "jsp",
+  "jspx",
+  "cgi",
+  "pl",
+  "py",
+  "rb",
+  "dll",
+  "so",
+  "dylib",
+  "class",
+  "jar",
+  "war",
+  "htaccess",
+  "htpasswd",
+  "svg"
+];
+function sanitizeFileName(fileName) {
+  let normalized = fileName.normalize("NFKC");
+  normalized = normalized.replace(/\\/g, "/");
+  const lastSlash = normalized.lastIndexOf("/");
+  if (lastSlash >= 0) {
+    normalized = normalized.substring(lastSlash + 1);
+  }
+  normalized = normalized.replace(/[\x00-\x1f\x7f]/g, "");
+  if (!normalized) {
+    throw new Error("\u975E\u6CD5\u6587\u4EF6\u540D");
+  }
+  return normalized;
+}
+__name(sanitizeFileName, "sanitizeFileName");
+function isSafeOriginalFileName(name) {
+  return /^[a-zA-Z0-9._-]+$/.test(name);
+}
+__name(isSafeOriginalFileName, "isSafeOriginalFileName");
+function isFileDenied(fileName, mimeType, validation, fileSize) {
+  const sanitized = sanitizeFileName(fileName);
+  const dotIndex = sanitized.lastIndexOf(".");
+  const ext = dotIndex >= 0 ? sanitized.substring(dotIndex + 1).toLowerCase() : "";
+  if (validation.maxFileSize && validation.maxFileSize > 0 && fileSize !== void 0) {
+    if (fileSize > validation.maxFileSize) return true;
+  }
+  let defaultDeny = false;
+  if (validation.denyExtensions?.length) {
+    if (validation.denyExtensions.includes(ext)) return true;
+    defaultDeny = false;
+  }
+  if (validation.allowExtensions?.length) {
+    if (validation.allowExtensions.includes(ext)) return false;
+    defaultDeny = true;
+  }
+  if (mimeType && validation.denyMimeTypes?.length) {
+    if (validation.denyMimeTypes.includes(mimeType)) return true;
+    defaultDeny = false;
+  }
+  if (mimeType && validation.allowMimeTypes?.length) {
+    if (validation.allowMimeTypes.includes(mimeType)) return false;
+    defaultDeny = true;
+  }
+  return defaultDeny;
+}
+__name(isFileDenied, "isFileDenied");
+function generateDateBasedKey(originalName, options) {
+  const safeName = sanitizeFileName(originalName);
+  const now = /* @__PURE__ */ new Date();
+  const datePart = [
+    now.getFullYear().toString(),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0")
+  ].join("");
+  const dotIndex = safeName.lastIndexOf(".");
+  const ext = dotIndex >= 0 ? safeName.substring(dotIndex) : "";
+  const prefix = options?.prefix ? `${options.prefix}/` : "";
+  if (options?.useOriginalFileName && isSafeOriginalFileName(safeName)) {
+    const uniqueDir = `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    return `${prefix}${datePart}/${uniqueDir}/${safeName}`;
+  }
+  const uniqueName = `${Date.now()}-${Math.random().toString(36).substring(2, 8)}${ext}`;
+  return `${prefix}${datePart}/${uniqueName}`;
+}
+__name(generateDateBasedKey, "generateDateBasedKey");
+
+// src/local-storage.ts
+import { Injectable, Logger } from "@nestjs/common";
+import * as fs from "fs";
+import * as path from "path";
+import { randomUUID } from "crypto";
+import { createReadStream } from "fs";
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata, "_ts_metadata");
+var LocalFileStorage = class _LocalFileStorage {
+  static {
+    __name(this, "LocalFileStorage");
+  }
+  logger = new Logger(_LocalFileStorage.name);
+  providerType = "local";
+  basePath;
+  baseUrl;
+  /** Active chunked upload sessions */
+  chunkedUploads = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.basePath = options.basePath;
+    this.baseUrl = options.baseUrl ?? "";
+    fs.mkdirSync(this.basePath, {
+      recursive: true
+    });
+    this.logger.log(`\u672C\u5730\u5B58\u50A8\u5DF2\u521D\u59CB\u5316: ${this.basePath}`);
+  }
+  isConfigured() {
+    return true;
+  }
+  async upload(buffer, key, _options) {
+    const filePath = this.resolvePath(key);
+    fs.mkdirSync(path.dirname(filePath), {
+      recursive: true
+    });
+    fs.writeFileSync(filePath, buffer);
+    return {
+      key,
+      url: this.buildUrl(key),
+      size: buffer.length
+    };
+  }
+  async uploadStream(stream, key, options) {
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.from(chunk));
+    }
+    return this.upload(Buffer.concat(chunks), key, options);
+  }
+  async download(key) {
+    const filePath = this.resolvePath(key);
+    const stat = fs.statSync(filePath);
+    return {
+      stream: createReadStream(filePath),
+      size: stat.size
+    };
+  }
+  async delete(key) {
+    const filePath = this.resolvePath(key);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  }
+  async exists(key) {
+    return fs.existsSync(this.resolvePath(key));
+  }
+  async getPublicUrl(key) {
+    return this.buildUrl(key);
+  }
+  async getDownloadUrl(key) {
+    return this.getPublicUrl(key);
+  }
+  async list(prefix) {
+    const dirPath = this.resolvePath(prefix);
+    if (!fs.existsSync(dirPath)) return [];
+    const entries = fs.readdirSync(dirPath, {
+      withFileTypes: true
+    });
+    return entries.filter((e) => e.isFile()).map((e) => {
+      const filePath = path.join(dirPath, e.name);
+      const stat = fs.statSync(filePath);
+      return {
+        key: path.join(prefix, e.name),
+        size: stat.size,
+        lastModified: stat.mtime
+      };
+    });
+  }
+  async downloadRange(key, position, length) {
+    const filePath = this.resolvePath(key);
+    const stat = fs.statSync(filePath);
+    const end = length !== void 0 ? Math.min(position + length - 1, stat.size - 1) : stat.size - 1;
+    const readSize = end - position + 1;
+    return {
+      stream: createReadStream(filePath, {
+        start: position,
+        end
+      }),
+      size: readSize
+    };
+  }
+  async getFileInfo(key) {
+    const filePath = this.resolvePath(key);
+    if (!fs.existsSync(filePath)) return void 0;
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile()) return void 0;
+    return {
+      key,
+      size: stat.size,
+      lastModified: stat.mtime
+    };
+  }
+  async copy(sourceKey, destKey) {
+    const src = this.resolvePath(sourceKey);
+    const dest = this.resolvePath(destKey);
+    fs.mkdirSync(path.dirname(dest), {
+      recursive: true
+    });
+    fs.copyFileSync(src, dest);
+  }
+  async move(sourceKey, destKey) {
+    const src = this.resolvePath(sourceKey);
+    const dest = this.resolvePath(destKey);
+    fs.mkdirSync(path.dirname(dest), {
+      recursive: true
+    });
+    fs.renameSync(src, dest);
+  }
+  async initChunkedUpload(key, totalChunks, totalSize) {
+    const uploadId = randomUUID();
+    const chunksDir = path.join(this.basePath, ".chunks", uploadId);
+    fs.mkdirSync(chunksDir, {
+      recursive: true
+    });
+    this.chunkedUploads.set(uploadId, {
+      uploadId,
+      key,
+      totalChunks,
+      receivedChunks: [],
+      totalSize,
+      complete: false
+    });
+    this.logger.log(`Chunked upload initialized: ${uploadId} for key=${key}, totalChunks=${totalChunks}`);
+    return uploadId;
+  }
+  async uploadChunk(uploadId, chunkIndex, buffer) {
+    const state = this.chunkedUploads.get(uploadId);
+    if (!state) {
+      throw new Error(`Unknown upload session: ${uploadId}`);
+    }
+    if (chunkIndex < 0 || chunkIndex >= state.totalChunks) {
+      throw new Error(`Invalid chunk index ${chunkIndex} (expected 0-${state.totalChunks - 1})`);
+    }
+    const chunkPath = path.join(this.basePath, ".chunks", uploadId, `chunk-${chunkIndex}`);
+    fs.writeFileSync(chunkPath, buffer);
+    state.receivedChunks.push(chunkIndex);
+  }
+  async completeChunkedUpload(uploadId, _options) {
+    const state = this.chunkedUploads.get(uploadId);
+    if (!state) {
+      throw new Error(`Unknown upload session: ${uploadId}`);
+    }
+    const missing = [];
+    for (let i = 0; i < state.totalChunks; i++) {
+      if (!state.receivedChunks.includes(i)) {
+        missing.push(i);
+      }
+    }
+    if (missing.length > 0) {
+      throw new Error(`Missing chunks: ${missing.join(", ")}`);
+    }
+    const filePath = this.resolvePath(state.key);
+    fs.mkdirSync(path.dirname(filePath), {
+      recursive: true
+    });
+    const writeStream = fs.createWriteStream(filePath);
+    for (let i = 0; i < state.totalChunks; i++) {
+      const chunkPath = path.join(this.basePath, ".chunks", uploadId, `chunk-${i}`);
+      const chunkData = fs.readFileSync(chunkPath);
+      writeStream.write(chunkData);
+    }
+    writeStream.end();
+    await new Promise((resolve2, reject) => {
+      writeStream.on("finish", resolve2);
+      writeStream.on("error", reject);
+    });
+    const chunksDir = path.join(this.basePath, ".chunks", uploadId);
+    fs.rmSync(chunksDir, {
+      recursive: true,
+      force: true
+    });
+    state.complete = true;
+    this.chunkedUploads.delete(uploadId);
+    const stat = fs.statSync(filePath);
+    return {
+      key: state.key,
+      url: this.buildUrl(state.key),
+      size: stat.size
+    };
+  }
+  async abortChunkedUpload(uploadId) {
+    const chunksDir = path.join(this.basePath, ".chunks", uploadId);
+    if (fs.existsSync(chunksDir)) {
+      fs.rmSync(chunksDir, {
+        recursive: true,
+        force: true
+      });
+    }
+    this.chunkedUploads.delete(uploadId);
+    this.logger.log(`Chunked upload aborted: ${uploadId}`);
+  }
+  /**
+  * 便捷文件保存
+  * 自动根据文件类型生成日期归档路径并保存。
+  */
+  async saveFile(buffer, fileType, options) {
+    const normalizedType = fileType.startsWith(".") ? fileType : `.${fileType}`;
+    const key = generateDateBasedKey(`_temp${normalizedType}`);
+    return this.upload(buffer, key, options);
+  }
+  /**
+  * 应用 POSIX 文件权限
+  * 使用 fs.chmodSync 设置文件权限，非 POSIX 系统静默忽略错误。
+  */
+  async applyFilePermission(key, permissions) {
+    const filePath = this.resolvePath(key);
+    try {
+      fs.chmodSync(filePath, permissions.mode);
+    } catch {
+    }
+  }
+  /**
+  * Resolve a storage key to an absolute file path.
+  * Validates against path traversal attacks (e.g. "../../../etc/passwd").
+  */
+  resolvePath(key) {
+    const resolved = path.resolve(this.basePath, key);
+    const normalizedBase = path.resolve(this.basePath);
+    if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
+      throw new Error(`Path traversal detected: key "${key}" resolves outside base path`);
+    }
+    return resolved;
+  }
+  buildUrl(key) {
+    return this.baseUrl ? `${this.baseUrl}/${key}` : key;
+  }
+};
+LocalFileStorage = _ts_decorate([
+  Injectable(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    Object
+  ])
+], LocalFileStorage);
+
+// src/s3-storage.ts
+import { Injectable as Injectable2, Logger as Logger2 } from "@nestjs/common";
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadObjectCommand, ListObjectsV2Command, CopyObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata2, "_ts_metadata");
+var S3Storage = class _S3Storage {
+  static {
+    __name(this, "S3Storage");
+  }
+  logger = new Logger2(_S3Storage.name);
+  client;
+  bucket;
+  publicUrl;
+  objectAclMode;
+  uploadUrlMode;
+  signedUrlExpiresIn;
+  providerType = "s3";
+  constructor(options) {
+    this.bucket = options.bucket;
+    this.publicUrl = options.publicUrl ?? "";
+    this.objectAclMode = options.objectAclMode ?? "object-acl";
+    this.uploadUrlMode = options.uploadUrlMode ?? "signed";
+    this.signedUrlExpiresIn = options.signedUrlExpiresIn ?? 3600;
+    this.client = new S3Client({
+      region: options.region ?? "us-east-1",
+      endpoint: options.endpoint,
+      credentials: {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey
+      },
+      forcePathStyle: options.forcePathStyle ?? Boolean(options.endpoint)
+    });
+    this.logger.log("S3 storage initialized");
+  }
+  onModuleDestroy() {
+    this.client.destroy();
+    this.logger.log("S3 \u5BA2\u6237\u7AEF\u5DF2\u5173\u95ED");
+  }
+  isConfigured() {
+    return true;
+  }
+  async upload(buffer, key, options) {
+    if (this.objectAclMode === "none" && options?.acl === "public-read") {
+      throw new Error("Object-level public ACL is disabled for this storage provider");
+    }
+    const input = {
+      Bucket: this.bucket,
+      Key: key,
+      Body: buffer,
+      ContentType: options?.contentType ?? "application/octet-stream",
+      Metadata: options?.metadata,
+      ...this.objectAclMode === "object-acl" && options?.acl ? {
+        ACL: options.acl
+      } : {}
+    };
+    await this.client.send(new PutObjectCommand(input));
+    return {
+      key,
+      url: this.publicUrl ? await this.getPublicUrl(key) : this.uploadUrlMode === "signed" ? await this.getDownloadUrl(key) : "",
+      size: buffer.length
+    };
+  }
+  async uploadStream(stream, key, options) {
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.from(chunk));
+    }
+    return this.upload(Buffer.concat(chunks), key, options);
+  }
+  async download(key) {
+    const response = await this.client.send(new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: key
+    }));
+    if (!response.Body) {
+      throw new Error("Stored object response had no body");
+    }
+    return {
+      stream: response.Body,
+      size: response.ContentLength ?? 0
+    };
+  }
+  async delete(key) {
+    await this.client.send(new DeleteObjectCommand({
+      Bucket: this.bucket,
+      Key: key
+    }));
+  }
+  async exists(key) {
+    try {
+      await this.client.send(new HeadObjectCommand({
+        Bucket: this.bucket,
+        Key: key
+      }));
+      return true;
+    } catch (error) {
+      const s3Err = error;
+      if (s3Err.name === "NotFound" || s3Err.$metadata?.httpStatusCode === 404) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  async getPublicUrl(key) {
+    if (!this.publicUrl) {
+      throw new Error("No public URL is configured for this storage provider");
+    }
+    return `${this.publicUrl}/${encodeKeyPath(key)}`;
+  }
+  async getDownloadUrl(key, expiresIn = this.signedUrlExpiresIn) {
+    if (this.publicUrl) return this.getPublicUrl(key);
+    return getSignedUrl(this.client, new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: key
+    }), {
+      expiresIn
+    });
+  }
+  async list(prefix) {
+    const files = [];
+    let continuationToken;
+    do {
+      const response = await this.client.send(new ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: prefix,
+        ContinuationToken: continuationToken
+      }));
+      files.push(...(response.Contents ?? []).map((item) => ({
+        key: item.Key ?? "",
+        size: item.Size ?? 0,
+        lastModified: item.LastModified ?? /* @__PURE__ */ new Date()
+      })));
+      continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+    } while (continuationToken);
+    return files;
+  }
+  async getFileInfo(key) {
+    try {
+      const response = await this.client.send(new HeadObjectCommand({
+        Bucket: this.bucket,
+        Key: key
+      }));
+      return {
+        key,
+        size: response.ContentLength ?? 0,
+        lastModified: response.LastModified ?? /* @__PURE__ */ new Date(),
+        contentType: response.ContentType
+      };
+    } catch (error) {
+      const s3Err = error;
+      if (s3Err.name === "NotFound" || s3Err.$metadata?.httpStatusCode === 404) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
+  async copy(sourceKey, destKey) {
+    await this.client.send(new CopyObjectCommand({
+      Bucket: this.bucket,
+      CopySource: `${this.bucket}/${encodeKeyPath(sourceKey)}`,
+      Key: destKey
+    }));
+  }
+  async move(sourceKey, destKey) {
+    await this.copy(sourceKey, destKey);
+    await this.delete(sourceKey);
+  }
+};
+S3Storage = _ts_decorate2([
+  Injectable2(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof S3StorageOptions === "undefined" ? Object : S3StorageOptions
+  ])
+], S3Storage);
+function encodeKeyPath(key) {
+  return key.split("/").map(encodeURIComponent).join("/");
+}
+__name(encodeKeyPath, "encodeKeyPath");
+
+// src/webdav-storage.ts
+import { Injectable as Injectable3, Logger as Logger3 } from "@nestjs/common";
+import * as path2 from "path";
+import { Readable } from "stream";
+function _ts_decorate3(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate3, "_ts_decorate");
+function _ts_metadata3(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata3, "_ts_metadata");
+var WebDavStorage = class _WebDavStorage {
+  static {
+    __name(this, "WebDavStorage");
+  }
+  logger = new Logger3(_WebDavStorage.name);
+  clientPromise;
+  publicUrl;
+  basePath;
+  directoryPromises = /* @__PURE__ */ new Map();
+  providerType = "webdav";
+  options;
+  constructor(options) {
+    if (!options.url || !options.username || !options.password) {
+      throw new Error("WebDAV url, username and password are required");
+    }
+    this.options = options;
+    this.publicUrl = (options.publicUrl ?? "").replace(/\/$/, "");
+    this.basePath = options.basePath?.trim() || "/";
+    this.logger.log("WebDAV storage initialized");
+  }
+  async initClient() {
+    const { createClient } = await import("webdav");
+    return createClient(this.options.url, {
+      username: this.options.username,
+      password: this.options.password
+    });
+  }
+  getClient() {
+    this.clientPromise ??= this.initClient();
+    return this.clientPromise;
+  }
+  isConfigured() {
+    return true;
+  }
+  async upload(buffer, key, options) {
+    const client = await this.getClient();
+    const remotePath = this.resolvePath(key);
+    const parentDir = remotePath.substring(0, remotePath.lastIndexOf("/"));
+    if (parentDir && parentDir !== "/") {
+      await this.ensureDirectory(parentDir);
+    }
+    await client.putFileContents(remotePath, buffer, {
+      contentLength: buffer.length,
+      overwrite: true,
+      headers: options?.contentType ? {
+        "Content-Type": options.contentType
+      } : void 0
+    });
+    return {
+      key,
+      url: this.buildUrl(key),
+      size: buffer.length
+    };
+  }
+  async uploadStream(stream, key, options) {
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.from(chunk));
+    }
+    return this.upload(Buffer.concat(chunks), key, options);
+  }
+  async download(key) {
+    const client = await this.getClient();
+    const remotePath = this.resolvePath(key);
+    const stat = await client.stat(remotePath);
+    const buffer = await client.getFileContents(remotePath);
+    const readable = Readable.from(buffer);
+    return {
+      stream: readable,
+      size: stat.size ?? buffer.length
+    };
+  }
+  async delete(key) {
+    const client = await this.getClient();
+    const remotePath = this.resolvePath(key);
+    try {
+      await client.deleteFile(remotePath);
+    } catch (error) {
+      const err = error;
+      if (err.status === 404) return;
+      throw error;
+    }
+  }
+  async exists(key) {
+    const client = await this.getClient();
+    const remotePath = this.resolvePath(key);
+    return client.exists(remotePath);
+  }
+  async getPublicUrl(key) {
+    return this.buildUrl(key);
+  }
+  async getDownloadUrl(key) {
+    return this.getPublicUrl(key);
+  }
+  async list(prefix) {
+    const client = await this.getClient();
+    const remotePath = this.resolvePath(prefix);
+    try {
+      const items = await client.getDirectoryContents(remotePath, {
+        deep: true
+      });
+      return items.filter((item) => item.type === "file").map((item) => ({
+        key: this.stripBasePath(item.filename),
+        size: item.size ?? 0,
+        lastModified: new Date(item.lastmod ?? Date.now()),
+        contentType: item.mime
+      }));
+    } catch (error) {
+      const err = error;
+      if (err.status === 404) return [];
+      throw error;
+    }
+  }
+  async getFileInfo(key) {
+    const client = await this.getClient();
+    const remotePath = this.resolvePath(key);
+    try {
+      const stat = await client.stat(remotePath);
+      if (stat.type === "directory") return void 0;
+      return {
+        key,
+        size: stat.size ?? 0,
+        lastModified: new Date(stat.lastmod ?? Date.now()),
+        contentType: stat.mime
+      };
+    } catch (error) {
+      const err = error;
+      if (err.status === 404) return void 0;
+      throw error;
+    }
+  }
+  async copy(sourceKey, destKey) {
+    const client = await this.getClient();
+    const src = this.resolvePath(sourceKey);
+    const dest = this.resolvePath(destKey);
+    const parentDir = dest.substring(0, dest.lastIndexOf("/"));
+    if (parentDir && parentDir !== "/") {
+      await this.ensureDirectory(parentDir);
+    }
+    await client.copyFile(src, dest);
+  }
+  async move(sourceKey, destKey) {
+    const client = await this.getClient();
+    const src = this.resolvePath(sourceKey);
+    const dest = this.resolvePath(destKey);
+    const parentDir = dest.substring(0, dest.lastIndexOf("/"));
+    if (parentDir && parentDir !== "/") {
+      await this.ensureDirectory(parentDir);
+    }
+    await client.moveFile(src, dest);
+  }
+  /**
+  * 递归创建目录
+  */
+  async ensureDirectory(dirPath) {
+    const inflight = this.directoryPromises.get(dirPath);
+    if (inflight) return inflight;
+    const creation = this.createDirectoryIfMissing(dirPath);
+    this.directoryPromises.set(dirPath, creation);
+    try {
+      await creation;
+    } finally {
+      if (this.directoryPromises.get(dirPath) === creation) {
+        this.directoryPromises.delete(dirPath);
+      }
+    }
+  }
+  async createDirectoryIfMissing(dirPath) {
+    const client = await this.getClient();
+    if (await client.exists(dirPath)) return;
+    const parent = dirPath.substring(0, dirPath.lastIndexOf("/"));
+    if (parent && parent !== "/") {
+      await this.ensureDirectory(parent);
+    }
+    try {
+      await client.createDirectory(dirPath);
+    } catch (error) {
+      const status = error.status;
+      if ([
+        405,
+        409
+      ].includes(status ?? 0) && await client.exists(dirPath)) return;
+      throw error;
+    }
+  }
+  resolvePath(key) {
+    const base = this.basePath.endsWith("/") ? this.basePath : `${this.basePath}/`;
+    const resolved = path2.posix.resolve(base, key);
+    const normalizedBase = path2.posix.resolve(base);
+    if (!resolved.startsWith(normalizedBase + "/") && resolved !== normalizedBase) {
+      throw new Error(`Path traversal detected: key "${key}" resolves outside base path`);
+    }
+    return resolved;
+  }
+  stripBasePath(fullPath) {
+    const base = this.basePath.endsWith("/") ? this.basePath : `${this.basePath}/`;
+    if (fullPath.startsWith(base)) {
+      return fullPath.substring(base.length);
+    }
+    return fullPath;
+  }
+  buildUrl(key) {
+    return this.publicUrl ? `${this.publicUrl}/${key}` : key;
+  }
+};
+WebDavStorage = _ts_decorate3([
+  Injectable3(),
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [
+    typeof WebDavStorageOptions === "undefined" ? Object : WebDavStorageOptions
+  ])
+], WebDavStorage);
+
+// src/file-lifecycle.ts
+import { Injectable as Injectable4, Logger as Logger4 } from "@nestjs/common";
+function _ts_decorate4(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate4, "_ts_decorate");
+var FileLifecycleManager = class _FileLifecycleManager {
+  static {
+    __name(this, "FileLifecycleManager");
+  }
+  logger = new Logger4(_FileLifecycleManager.name);
+  policies = [];
+  /** 注册一个生命周期策略 */
+  registerPolicy(policy) {
+    this.policies.push(policy);
+    this.logger.log(`File lifecycle policy registered: prefix=${policy.pathPrefix ?? "*"}, maxAge=${policy.maxAge ?? "none"}`);
+  }
+  /** 获取所有已注册策略 */
+  getPolicies() {
+    return [
+      ...this.policies
+    ];
+  }
+  /**
+  * 评估文件列表，返回需要清理的文件 keys。
+  * 调用方负责实际删除操作。
+  */
+  evaluate(files, policy) {
+    const toDelete = [];
+    const activePolicies = policy ? [
+      policy
+    ] : this.policies;
+    const now = Date.now();
+    for (const p of activePolicies) {
+      let scopedFiles = files;
+      if (p.pathPrefix) {
+        scopedFiles = files.filter((f) => f.key.startsWith(p.pathPrefix));
+      }
+      const sorted = [
+        ...scopedFiles
+      ].sort((a, b) => a.createdAt - b.createdAt);
+      if (p.maxAge && p.maxAge > 0) {
+        for (const f of sorted) {
+          if (now - f.createdAt > p.maxAge) {
+            toDelete.push(f.key);
+          }
+        }
+      }
+      if (p.maxCount && p.maxCount > 0) {
+        const remaining = sorted.filter((f) => !toDelete.includes(f.key));
+        if (remaining.length > p.maxCount) {
+          const excess = remaining.slice(0, remaining.length - p.maxCount);
+          for (const f of excess) {
+            toDelete.push(f.key);
+          }
+        }
+      }
+      if (p.maxTotalSize && p.maxTotalSize > 0) {
+        const remaining = sorted.filter((f) => !toDelete.includes(f.key));
+        let totalSize = remaining.reduce((sum, f) => sum + f.size, 0);
+        for (const f of remaining) {
+          if (totalSize <= p.maxTotalSize) break;
+          toDelete.push(f.key);
+          totalSize -= f.size;
+        }
+      }
+    }
+    return [
+      ...new Set(toDelete)
+    ];
+  }
+};
+FileLifecycleManager = _ts_decorate4([
+  Injectable4()
+], FileLifecycleManager);
+
+// src/storage.module.ts
+import { Module, Global } from "@nestjs/common";
+function _ts_decorate5(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate5, "_ts_decorate");
+var FILE_MANAGER = "FILE_MANAGER";
+var STORAGE_MODULE_OPTIONS = /* @__PURE__ */ Symbol("STORAGE_MODULE_OPTIONS");
+var ZuckerStorageModule = class _ZuckerStorageModule {
+  static {
+    __name(this, "ZuckerStorageModule");
+  }
+  static forRoot(options) {
+    return {
+      module: _ZuckerStorageModule,
+      global: true,
+      providers: [
+        {
+          provide: FILE_MANAGER,
+          useFactory: /* @__PURE__ */ __name(() => _ZuckerStorageModule.createFileManager(options), "useFactory")
+        }
+      ],
+      exports: [
+        FILE_MANAGER
+      ]
+    };
+  }
+  static forRootAsync(options) {
+    const asyncProviders = this.createAsyncProviders(options);
+    return {
+      module: _ZuckerStorageModule,
+      global: true,
+      imports: options.imports ?? [],
+      providers: [
+        ...asyncProviders,
+        {
+          provide: FILE_MANAGER,
+          useFactory: /* @__PURE__ */ __name((opts) => _ZuckerStorageModule.createFileManager(opts), "useFactory"),
+          inject: [
+            STORAGE_MODULE_OPTIONS
+          ]
+        }
+      ],
+      exports: [
+        FILE_MANAGER
+      ]
+    };
+  }
+  static createFileManager(options) {
+    if (options.provider === "local") {
+      return new LocalFileStorage({
+        basePath: options.basePath,
+        baseUrl: options.baseUrl
+      });
+    }
+    if (options.provider === "webdav") {
+      const { provider: _2, ...webdavOpts } = options;
+      return new WebDavStorage(webdavOpts);
+    }
+    const { provider: _, ...s3Opts } = options;
+    return new S3Storage(s3Opts);
+  }
+  static createAsyncProviders(options) {
+    if (options.useFactory) {
+      return [
+        {
+          provide: STORAGE_MODULE_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject ?? []
+        }
+      ];
+    }
+    const optionsProvider = {
+      provide: STORAGE_MODULE_OPTIONS,
+      useFactory: /* @__PURE__ */ __name(async (factory) => factory.createStorageOptions(), "useFactory"),
+      inject: [
+        options.useClass ?? options.useExisting
+      ]
+    };
+    if (options.useClass) {
+      return [
+        {
+          provide: options.useClass,
+          useClass: options.useClass
+        },
+        optionsProvider
+      ];
+    }
+    return [
+      optionsProvider
+    ];
+  }
+};
+ZuckerStorageModule = _ts_decorate5([
+  Global(),
+  Module({})
+], ZuckerStorageModule);
+
+// src/index.ts
+var StorageProvider = /* @__PURE__ */ (function(StorageProvider2) {
+  StorageProvider2["LOCAL"] = "LOCAL";
+  StorageProvider2["S3"] = "S3";
+  StorageProvider2["WEBDAV"] = "WEBDAV";
+  return StorageProvider2;
+})({});
+export {
+  DANGEROUS_EXTENSIONS,
+  FILE_MANAGER,
+  FileLifecycleManager,
+  LocalFileStorage,
+  S3Storage,
+  StorageProvider,
+  WebDavStorage,
+  ZuckerStorageModule,
+  generateDateBasedKey,
+  isFileDenied,
+  isSafeOriginalFileName,
+  sanitizeFileName
+};