@rezwanul7/storage 0.0.0-stage → 0.1.0

package/dist/server/index.cjs

@@ -0,0 +1,545 @@
+'use strict';
+
+var fileType = require('file-type');
+var fs = require('fs/promises');
+var fs$1 = require('fs');
+var path = require('path');
+var stream = require('stream');
+var crypto = require('crypto');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
+var crypto__default = /*#__PURE__*/_interopDefault(crypto);
+
+// src/server/storage.errors.ts
+var StorageError = class extends Error {
+  /** Always `"StorageError"`. */
+  name = "StorageError";
+  /** Stable code naming what went wrong. */
+  code;
+  /** Context for logs, such as the Provider's name. */
+  meta;
+  /**
+   * @param code - The stable code.
+   * @param opts - The message, the underlying `cause` and context for logs.
+   */
+  constructor(code, opts) {
+    super(opts.message, { cause: opts.cause });
+    this.code = code;
+    this.meta = opts.meta;
+  }
+};
+
+// src/shared/mimeTypes.ts
+var DANGEROUS_EXTENSIONS = /* @__PURE__ */ new Set([
+  "sh",
+  "bash",
+  "zsh",
+  "exe",
+  "dll",
+  "com",
+  "scr",
+  "bat",
+  "cmd",
+  "ps1",
+  "jar",
+  "class"
+]);
+var DANGEROUS_MIME = /* @__PURE__ */ new Set([
+  "application/x-sh",
+  "application/x-shellscript",
+  "text/x-shellscript",
+  "text/x-sh",
+  "application/x-dosexec",
+  "application/java-archive"
+]);
+var MIME_BY_EXT = {
+  // Image
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  bmp: "image/bmp",
+  webp: "image/webp",
+  tiff: "image/tiff",
+  tif: "image/tiff",
+  svg: "image/svg+xml",
+  ico: "image/vnd.microsoft.icon",
+  avif: "image/avif",
+  heic: "image/heic",
+  // Audio
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  flac: "audio/x-flac",
+  m4a: "audio/mp4",
+  // Video
+  mp4: "video/mp4",
+  mkv: "video/x-matroska",
+  mov: "video/quicktime",
+  avi: "video/x-msvideo",
+  webm: "video/webm",
+  // Documents
+  pdf: "application/pdf",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ods: "application/vnd.oasis.opendocument.spreadsheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  odp: "application/vnd.oasis.opendocument.presentation",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  odt: "application/vnd.oasis.opendocument.text",
+  rtf: "application/rtf",
+  // Datasets (JSON Lines has no registered MIME, so it is served as JSON)
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  json: "application/json",
+  jsonl: "application/json",
+  ndjson: "application/json",
+  // Archives
+  zip: "application/zip",
+  rar: "application/x-rar-compressed",
+  "7z": "application/x-7z-compressed",
+  tar: "application/x-tar",
+  gz: "application/gzip",
+  // Code
+  js: "text/javascript",
+  jsx: "text/jsx",
+  ts: "text/typescript",
+  tsx: "text/tsx",
+  py: "text/x-python",
+  rb: "text/x-ruby",
+  php: "application/x-httpd-php",
+  java: "text/x-java-source",
+  kt: "text/x-kotlin",
+  c: "text/x-c",
+  cpp: "text/x-c",
+  h: "text/x-c",
+  hpp: "text/x-c",
+  cs: "text/x-csharp",
+  go: "text/x-go",
+  rs: "text/x-rust",
+  html: "text/html",
+  htm: "text/html",
+  css: "text/css",
+  scss: "text/x-scss",
+  yaml: "text/yaml",
+  yml: "text/yaml",
+  sql: "application/sql",
+  xml: "application/xml",
+  // Text
+  txt: "text/plain",
+  md: "text/markdown",
+  markdown: "text/markdown",
+  log: "text/plain",
+  ini: "text/plain",
+  cfg: "text/plain",
+  conf: "text/plain",
+  env: "text/plain",
+  // Executables (blocked by DANGEROUS_EXTENSIONS, mapped so they report a real MIME)
+  sh: "application/x-sh",
+  bash: "application/x-sh",
+  zsh: "application/x-sh",
+  exe: "application/x-msdos-program",
+  dll: "application/x-msdownload",
+  com: "application/x-msdownload",
+  bat: "application/x-msdownload",
+  jar: "application/java-archive",
+  class: "application/java-vm"
+};
+var EXT_BY_MIME = {};
+for (const [ext, mime] of Object.entries(MIME_BY_EXT)) {
+  EXT_BY_MIME[mime] ??= ext;
+}
+function mimeFromExtension(ext) {
+  if (!ext) return void 0;
+  return MIME_BY_EXT[ext.toLowerCase()];
+}
+function extensionFromMime(mime) {
+  if (!mime) return void 0;
+  return EXT_BY_MIME[mime.toLowerCase()];
+}
+
+// src/shared/fileExtension.ts
+function getFileExtension(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot === -1) return void 0;
+  return name.slice(dot + 1).toLowerCase() || void 0;
+}
+
+// src/server/internal/detectFileType.ts
+async function detectFileType(buffer, fileName, declaredMime) {
+  const declaredExt = getFileExtension(fileName);
+  const detected = await fileType.fileTypeFromBuffer(buffer);
+  if (detected) {
+    return {
+      declaredExt,
+      declaredMime,
+      detectedExt: detected.ext,
+      detectedMime: detected.mime,
+      ext: detected.ext,
+      mime: detected.mime,
+      confidence: "high"
+    };
+  }
+  if (declaredExt) {
+    const mime = mimeFromExtension(declaredExt);
+    return {
+      declaredExt,
+      declaredMime,
+      ext: declaredExt,
+      mime: mime ?? declaredMime ?? "application/octet-stream",
+      confidence: mime ? "medium" : "low"
+    };
+  }
+  if (declaredMime) {
+    const mimeExt = extensionFromMime(declaredMime);
+    return {
+      declaredExt,
+      declaredMime,
+      ext: mimeExt,
+      mime: declaredMime,
+      confidence: "low"
+    };
+  }
+  return { confidence: "low" };
+}
+
+// src/server/internal/checkTypeSpoofing.ts
+function checkForSpoofing(d) {
+  if (d.detectedExt && d.declaredExt && d.detectedExt !== d.declaredExt) {
+    return {
+      ok: false,
+      spoofed: true,
+      reason: `Declared ".${d.declaredExt}" but file content is actually ".${d.detectedExt}".`
+    };
+  }
+  if (d.detectedMime && d.declaredMime && d.detectedMime !== d.declaredMime) {
+    return {
+      ok: false,
+      spoofed: true,
+      reason: `Declared MIME "${d.declaredMime}" does not match content "${d.detectedMime}".`
+    };
+  }
+  return { ok: true };
+}
+
+// src/server/internal/checkFileStructure.ts
+function checkFileStructure(ext, buffer) {
+  if (buffer.includes(0)) {
+    return {
+      ok: false,
+      reason: "File contains binary data but expected text content."
+    };
+  }
+  const text = buffer.toString("utf8");
+  if (ext === "json") {
+    try {
+      JSON.parse(text);
+      return { ok: true };
+    } catch {
+      return { ok: false, reason: "Invalid JSON format." };
+    }
+  }
+  if (ext === "jsonl") {
+    const lines = text.split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        JSON.parse(line);
+      } catch {
+        return { ok: false, reason: "Invalid JSONL format." };
+      }
+    }
+    return { ok: true };
+  }
+  if (ext === "csv") {
+    const rows = text.split("\n");
+    if (rows.length < 1)
+      return { ok: false, reason: "CSV file is empty or malformed." };
+    return { ok: true };
+  }
+  return { ok: true };
+}
+
+// src/shared/fileSize.ts
+var SIZE_UNITS = {
+  b: 1,
+  kb: 1024,
+  mb: 1024 ** 2,
+  gb: 1024 ** 3,
+  tb: 1024 ** 4
+};
+function parseFileSize(input) {
+  if (input == null) return void 0;
+  if (typeof input === "number" && Number.isFinite(input)) return input;
+  if (typeof input !== "string") return void 0;
+  const match = input.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/);
+  if (!match) return void 0;
+  return parseFloat(match[1]) * (SIZE_UNITS[match[2] || "b"] ?? 1);
+}
+function formatFileSize(bytes) {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const index = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, index)).toFixed(1)} ${units[index]}`;
+}
+
+// src/server/internal/checkRules.ts
+function checkRules(d, size, rules) {
+  const errors = [];
+  const detectedMime = d.mime ?? "application/octet-stream";
+  const detectedExt = d.ext ?? "unknown";
+  const maxSize = parseFileSize(rules.maxFileSize);
+  if (maxSize && size > maxSize) {
+    errors.push(`File exceeds maximum size of ${formatFileSize(maxSize)}.`);
+  }
+  const minSize = parseFileSize(rules.minFileSize);
+  if (minSize && size < minSize) {
+    errors.push(`File must be at least ${formatFileSize(minSize)}.`);
+  }
+  if (rules.allowedMimeTypes && !rules.allowedMimeTypes.includes(detectedMime)) {
+    errors.push(`MIME '${detectedMime}' is not allowed.`);
+  }
+  if (rules.blockedMimeTypes && rules.blockedMimeTypes.includes(detectedMime)) {
+    errors.push(`MIME '${detectedMime}' is blocked.`);
+  }
+  if (rules.allowedExtensions && !rules.allowedExtensions.includes(detectedExt)) {
+    errors.push(`Extension '.${detectedExt}' is not allowed.`);
+  }
+  if (rules.blockedExtensions && rules.blockedExtensions.includes(detectedExt)) {
+    errors.push(`Extension '.${detectedExt}' is blocked.`);
+  }
+  return errors;
+}
+
+// src/server/internal/checkDangerousTypes.ts
+function checkDangerousTypes(ext, mime) {
+  if (ext && DANGEROUS_EXTENSIONS.has(ext)) {
+    return { ok: false, reason: `Extension '.${ext}' is unsafe.` };
+  }
+  if (mime && DANGEROUS_MIME.has(mime)) {
+    return { ok: false, reason: `MIME type '${mime}' is unsafe.` };
+  }
+  return { ok: true };
+}
+
+// src/server/core/validateFile.ts
+async function validateFile(file, rules = {}) {
+  const errors = [];
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const size = buffer.length;
+  const detection = await detectFileType(buffer, file.name, file.type);
+  const danger = checkDangerousTypes(detection.ext, detection.mime);
+  if (!danger.ok) errors.push(danger.reason);
+  const spoofing = checkForSpoofing(detection);
+  if (!spoofing.ok) errors.push(spoofing.reason);
+  if (detection.confidence !== "high") {
+    const struct = checkFileStructure(detection.ext ?? "", buffer);
+    if (!struct.ok) errors.push(struct.reason);
+  }
+  const hasDetectionFailure = !detection.mime || !detection.ext;
+  if (hasDetectionFailure) {
+    errors.push("File type detection failed");
+  }
+  errors.push(...checkRules(detection, size, rules));
+  if (rules.customValidators?.length) {
+    for (const validator of rules.customValidators) {
+      const msg = await validator({
+        buffer,
+        originalName: file.name,
+        declaredMime: file.type,
+        detectedMime: detection.mime,
+        detectedExt: detection.ext,
+        size
+      });
+      if (msg) errors.push(msg);
+    }
+  }
+  if (errors.length > 0 || hasDetectionFailure) {
+    return { valid: false, errors };
+  }
+  return {
+    valid: true,
+    file: {
+      originalName: file.name,
+      mime: detection.mime ?? "Unknown",
+      ext: detection.ext ?? "Unknown",
+      size,
+      buffer
+    }
+  };
+}
+
+// src/server/core/fileUpload.service.ts
+var FileUploadService = class {
+  constructor(storage, logger) {
+    this.storage = storage;
+    this.logger = logger;
+  }
+  async store(files, rules, { directory }) {
+    const list = Array.isArray(files) ? files : [files];
+    const validated = [];
+    const errors = {};
+    for (const [index, file] of list.entries()) {
+      const result = await validateFile(file, rules);
+      if (result.valid) validated.push(result.file);
+      else
+        errors[index] = result.errors.length ? result.errors : ["File validation failed"];
+    }
+    if (Object.keys(errors).length > 0) {
+      return { ok: false, errors };
+    }
+    const stored = [];
+    try {
+      for (const file of validated) {
+        stored.push(await this.upload(file, directory));
+      }
+    } catch (error) {
+      await this.removeStored(stored);
+      if (error instanceof StorageError) throw error;
+      throw new StorageError("STORAGE_UPLOAD_FAILED", {
+        message: error instanceof Error ? error.message : "The storage provider couldn't store the file.",
+        cause: error,
+        meta: { provider: this.storage.provider, directory }
+      });
+    }
+    return { ok: true, files: stored };
+  }
+  async upload(validated, directory) {
+    const stored = await this.storage.upload({
+      buffer: validated.buffer,
+      mime: validated.mime,
+      ext: validated.ext,
+      directory
+    });
+    return {
+      originalFileName: validated.originalName,
+      provider: this.storage.provider,
+      storageId: stored.storageId,
+      url: stored.url,
+      size: validated.size,
+      mime: validated.mime,
+      ext: validated.ext
+    };
+  }
+  /** Deletes the files of a failed upload. A file left behind is logged, not thrown. */
+  async removeStored(stored) {
+    const outcomes = await Promise.allSettled(
+      stored.map(({ storageId }) => this.storage.delete(storageId))
+    );
+    outcomes.forEach((outcome, index) => {
+      if (outcome.status === "rejected") {
+        this.logger.error("storage.rollback_delete_failed", {
+          provider: this.storage.provider,
+          storageId: stored[index]?.storageId,
+          error: outcome.reason
+        });
+      }
+    });
+  }
+};
+
+// src/server/createFileUpload.ts
+var noop = () => {
+};
+var SILENT_LOGGER = { error: noop };
+function createFileUpload({
+  storage,
+  logger = SILENT_LOGGER
+}) {
+  return new FileUploadService(storage, logger);
+}
+var LocalFileStorage = class {
+  /** The Provider's name, saved with each file. */
+  provider = "local";
+  root;
+  urlPrefix;
+  /**
+   * @param options - The folder to store under and the URL prefix.
+   */
+  constructor({ root, urlPrefix }) {
+    this.root = path__default.default.resolve(root);
+    this.urlPrefix = urlPrefix;
+  }
+  /**
+   * Writes a file under `directory` with a random name.
+   *
+   * @param params - The file's bytes, MIME type, extension and folder.
+   * @returns Where the file was stored.
+   */
+  async upload({
+    buffer,
+    mime,
+    ext,
+    directory
+  }) {
+    const fileId = crypto__default.default.randomBytes(16).toString("hex");
+    const storageId = `${directory}/${fileId}.${ext}`;
+    const filePath = this.resolve(storageId);
+    await fs__default.default.mkdir(path__default.default.dirname(filePath), { recursive: true });
+    await fs__default.default.writeFile(filePath, buffer);
+    return {
+      url: this.getUrl(storageId),
+      storageId,
+      mime,
+      size: buffer.length
+    };
+  }
+  /**
+   * Reads a stored file as a stream.
+   *
+   * @param storageId - The file's Storage ID.
+   * @returns The file, or null when nothing is stored there.
+   */
+  async read(storageId) {
+    const filePath = this.resolve(storageId);
+    try {
+      const stats = await fs__default.default.stat(filePath);
+      if (!stats.isFile()) return null;
+      return {
+        stream: stream.Readable.toWeb(
+          fs$1.createReadStream(filePath)
+        ),
+        size: stats.size
+      };
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  }
+  /**
+   * Deletes a stored file; succeeds when it isn't there.
+   *
+   * @param storageId - The file's Storage ID.
+   */
+  async delete(storageId) {
+    await fs__default.default.rm(this.resolve(storageId), { force: true });
+  }
+  /**
+   * The file's URL under `urlPrefix`. Nothing serves it until your app does.
+   *
+   * @param storageId - The file's Storage ID.
+   * @returns The URL.
+   */
+  getUrl(storageId) {
+    return `${this.urlPrefix}/${storageId}`;
+  }
+  /** Maps a storage ID to a path under the root, refusing IDs that would escape it. */
+  resolve(storageId) {
+    const filePath = path__default.default.resolve(this.root, storageId);
+    if (!filePath.startsWith(this.root + path__default.default.sep)) {
+      throw new StorageError("STORAGE_INVALID_ID", {
+        message: `Invalid storage ID: ${storageId}`,
+        meta: { provider: this.provider }
+      });
+    }
+    return filePath;
+  }
+};
+
+exports.LocalFileStorage = LocalFileStorage;
+exports.StorageError = StorageError;
+exports.createFileUpload = createFileUpload;