uploaderkit 1.0.0 → 2.0.0

package/dist/server.cjs

@@ -0,0 +1,550 @@
+'use strict';
+
+var crypto = require('crypto');
+var stream = require('stream');
+
+// src/server/crypto.ts
+
+// src/constants.ts
+var KB = 1024;
+var MB = 1024 * KB;
+var MAGIC_NUMBERS = {
+  png: [137, 80, 78, 71, 13, 10, 26, 10],
+  jpg: [255, 216, 255],
+  jpeg: [255, 216, 255],
+  gif: [71, 73, 70, 56],
+  webp: [82, 73, 70, 70],
+  // RIFF; bytes 8-11 spell WEBP
+  ico: [0, 0, 1, 0],
+  pdf: [37, 80, 68, 70],
+  // %PDF
+  // OOXML files are ZIP containers, so docx/xlsx share the PK signature.
+  docx: [80, 75, 3, 4],
+  xlsx: [80, 75, 3, 4],
+  doc: [208, 207, 17, 224],
+  xls: [208, 207, 17, 224],
+  // DER/ASN.1 sequence header.
+  cer: [48, 130],
+  crt: [48, 130],
+  key: [48, 130],
+  pem: [45, 45, 45, 45, 45],
+  // -----
+  webm: [26, 69, 223, 163],
+  avi: [82, 73, 70, 70],
+  mp3: [73, 68, 51],
+  // ID3
+  wav: [82, 73, 70, 70],
+  ogg: [79, 103, 103, 83],
+  aac: [255, 241]
+};
+var MIME_TYPES = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  svg: "image/svg+xml",
+  webp: "image/webp",
+  gif: "image/gif",
+  ico: "image/x-icon",
+  heic: "image/heic",
+  cer: "application/x-x509-ca-cert",
+  crt: "application/x-x509-ca-cert",
+  pem: "application/x-pem-file",
+  key: "application/x-pem-file",
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  csv: "text/csv",
+  txt: "text/plain",
+  xml: "application/xml",
+  json: "application/json",
+  mp4: "video/mp4",
+  mov: "video/quicktime",
+  avi: "video/x-msvideo",
+  webm: "video/webm",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  aac: "audio/aac"
+};
+var FILE_CATEGORY_CONFIG = {
+  image: {
+    extensions: ["png", "jpg", "jpeg", "svg", "webp", "gif"],
+    maxBytes: 5 * MB,
+    validateMagicNumbers: true,
+    label: "image",
+    accept: "image/*"
+  },
+  certificate: {
+    extensions: ["cer", "crt", "pem"],
+    maxBytes: 50 * KB,
+    validateMagicNumbers: true,
+    label: "certificate",
+    accept: ".cer,.crt,.pem"
+  },
+  key: {
+    extensions: ["key"],
+    maxBytes: 50 * KB,
+    validateMagicNumbers: true,
+    label: "private key",
+    accept: ".key"
+  },
+  pdf: {
+    extensions: ["pdf"],
+    maxBytes: 20 * MB,
+    validateMagicNumbers: true,
+    label: "PDF",
+    accept: ".pdf"
+  },
+  document: {
+    extensions: ["pdf", "doc", "docx", "xls", "xlsx", "csv", "txt"],
+    maxBytes: 20 * MB,
+    validateMagicNumbers: false,
+    label: "document",
+    accept: ".pdf,.doc,.docx,.xls,.xlsx,.csv,.txt"
+  },
+  data: {
+    extensions: ["xml", "json"],
+    maxBytes: 5 * MB,
+    validateMagicNumbers: false,
+    label: "data file",
+    accept: ".xml,.json"
+  },
+  video: {
+    extensions: ["mp4", "mov", "avi", "webm"],
+    maxBytes: 100 * MB,
+    validateMagicNumbers: false,
+    label: "video",
+    accept: "video/*"
+  },
+  audio: {
+    extensions: ["mp3", "wav", "ogg", "aac"],
+    maxBytes: 20 * MB,
+    validateMagicNumbers: false,
+    label: "audio",
+    accept: "audio/*"
+  },
+  any: {
+    extensions: [],
+    maxBytes: 20 * MB,
+    validateMagicNumbers: false,
+    label: "file",
+    accept: "*/*"
+  }
+};
+
+// src/file.ts
+var getFileExtension = (fileName) => {
+  const dot = fileName.lastIndexOf(".");
+  if (dot < 1 || dot === fileName.length - 1) return "";
+  return fileName.slice(dot + 1).toLowerCase();
+};
+var isKnownExtension = (value) => value in MIME_TYPES;
+var formatFileSize = (bytes) => {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let size = bytes / 1024;
+  let unit = 0;
+  while (size >= 1024 && unit < units.length - 1) {
+    size /= 1024;
+    unit++;
+  }
+  return `${size.toFixed(size >= 10 ? 0 : 1)} ${units[unit]}`;
+};
+
+// src/labels.ts
+var DEFAULT_LABELS = {
+  dropPrompt: "Choose a file or drag it here",
+  tapPrompt: "Tap to choose a file",
+  bulkDropPrompt: "Drop several files \u2014 each lands on its document",
+  bulkTapPrompt: "Tap to add several files",
+  uploadAll: "Upload files",
+  view: "View",
+  remove: "Remove",
+  cancel: "Cancel",
+  ready: "Done",
+  staged: "Ready to upload",
+  upload: "Upload",
+  replace: "Replace",
+  dropToReplace: "Drop to replace",
+  previous: "Previous",
+  next: "Next",
+  uploadFailed: "The file could not be uploaded",
+  uploadNetworkFailed: "The file could not be uploaded. Check your connection",
+  removeFailed: "The file could not be removed from storage",
+  readFailed: "The file could not be loaded",
+  maxFilesReached: (max) => `At most ${max} file(s)`,
+  slotFormatNotAllowed: (slotLabel, extensions) => `${slotLabel}: format not allowed. Accepted: ${extensions.join(", ")}`,
+  fileWithoutSlot: (fileName) => `"${fileName}" does not match any document`,
+  viewerLoading: "Loading\u2026",
+  viewerError: "The preview could not be loaded",
+  viewerErrorHint: "The file may have moved or the link expired. You can retry or download it.",
+  viewerRetry: "Retry",
+  openInTab: "Open in tab",
+  downloadShort: "Download",
+  close: "Close",
+  noPreview: "This format has no preview",
+  download: (fileName) => `Download ${fileName}`,
+  filePreview: "File",
+  confirm: "Confirm",
+  confirmRemoveTitle: "Remove file",
+  confirmRemoveMessage: (fileName) => `Remove "${fileName}"? You can upload another one later.`,
+  confirmReplaceTitle: "Replace file",
+  confirmReplaceMessage: (current, incoming) => `Replace "${current}" with "${incoming}"?`,
+  dropAnywhereTitle: "Drop the files here",
+  dropAnywhereHint: "Anywhere on the screen counts",
+  avatarChange: "Change photo",
+  avatarDropHere: "Drop here",
+  avatarRemove: "Remove photo",
+  galleryAdd: "Add",
+  fileHasNoExtension: "The file has no extension",
+  formatNotAllowed: (extensions) => `Format not allowed. Accepted: ${extensions.join(", ")}`,
+  fileIsEmpty: "The file is empty",
+  fileTooLarge: (size, max) => `The file weighs ${size} and the maximum is ${max}`,
+  fileIncomplete: "The file is incomplete",
+  contentDoesNotMatchExtension: "The file contents do not match its extension",
+  requestIncomplete: "Incomplete request",
+  unauthorized: "Unauthorized",
+  fileRequired: "A file is required",
+  unknownScope: "Unknown file destination",
+  processingFailed: "The file could not be processed",
+  unnamedFile: "file"
+};
+var resolveLabels = (labels, base = DEFAULT_LABELS) => labels ? { ...base, ...labels } : base;
+({ ...DEFAULT_LABELS });
+
+// src/validation.ts
+var ok = { valid: true };
+var fail = (code, message) => ({ valid: false, code, message });
+var validateExtension = (fileName, allowed, labels) => {
+  if (allowed.length === 0) return ok;
+  const copy = resolveLabels(labels);
+  const extension = getFileExtension(fileName);
+  if (!extension) {
+    return fail("extension-not-allowed", copy.fileHasNoExtension);
+  }
+  if (!allowed.includes(extension)) {
+    return fail("extension-not-allowed", copy.formatNotAllowed(allowed));
+  }
+  return ok;
+};
+var validateSize = (size, maxBytes, labels) => {
+  const copy = resolveLabels(labels);
+  if (size === 0) return fail("empty-file", copy.fileIsEmpty);
+  if (size > maxBytes) {
+    return fail(
+      "too-large",
+      copy.fileTooLarge(formatFileSize(size), formatFileSize(maxBytes))
+    );
+  }
+  return ok;
+};
+var validateMagicNumbers = async (file, labels) => {
+  const copy = resolveLabels(labels);
+  const extension = getFileExtension(file.name);
+  if (!isKnownExtension(extension)) return ok;
+  const expected = MAGIC_NUMBERS[extension];
+  if (!expected) return ok;
+  const head = new Uint8Array(await file.arrayBuffer()).slice(
+    0,
+    expected.length
+  );
+  if (head.length < expected.length) {
+    return fail("magic-number-mismatch", copy.fileIncomplete);
+  }
+  const matches = expected.every((byte, index) => head[index] === byte);
+  return matches ? ok : fail("magic-number-mismatch", copy.contentDoesNotMatchExtension);
+};
+var validateFile = async (file, options = {}) => {
+  const {
+    maxBytes = Infinity,
+    allowedExtensions = [],
+    validateMagicNumbers: checkMagic = false,
+    labels,
+    customValidation
+  } = options;
+  const size = validateSize(file.size, maxBytes, labels);
+  if (!size.valid) return size;
+  const extension = validateExtension(file.name, allowedExtensions, labels);
+  if (!extension.valid) return extension;
+  if (checkMagic) {
+    const magic = await validateMagicNumbers(file, labels);
+    if (!magic.valid) return magic;
+  }
+  if (customValidation) return customValidation(file);
+  return ok;
+};
+
+// src/scopes.ts
+var ScopeError = class extends Error {
+  name = "ScopeError";
+};
+var PROBE_ENTITY = "__entity__";
+var probeFile = (name) => ({
+  name,
+  size: 0,
+  type: "",
+  arrayBuffer: async () => new ArrayBuffer(0)
+});
+var hasStableKey = (scope) => scope.path(PROBE_ENTITY, probeFile("a.png")) === scope.path(PROBE_ENTITY, probeFile("b.png"));
+var resolveReplaceMode = (scope) => {
+  if (scope.replace !== void 0) return scope.replace;
+  if ((scope.maxFiles ?? 1) > 1) return "key";
+  return hasStableKey(scope) ? "key" : "entity";
+};
+var dirname = (key) => {
+  const cut = key.lastIndexOf("/");
+  return cut === -1 ? "" : key.slice(0, cut);
+};
+var resolveScopePrefix = (scope, entityId) => scope.prefix?.(entityId) ?? dirname(scope.path(entityId, probeFile("probe.bin")));
+var validateForScope = async (registry, name, file, labels) => {
+  const scope = registry.get(name);
+  const category = scope.category ? FILE_CATEGORY_CONFIG[scope.category] : void 0;
+  return validateFile(file, {
+    maxBytes: scope.maxBytes,
+    allowedExtensions: scope.accept,
+    validateMagicNumbers: category?.validateMagicNumbers ?? true,
+    labels
+  });
+};
+var assertProviderSupports = (registry, provider) => {
+  const needsSigning = registry.names.filter(
+    (name) => registry.get(name).visibility === "private"
+  );
+  if (needsSigning.length > 0 && !provider.capabilities.signedUrl) {
+    throw new ScopeError(
+      `Provider "${provider.name}" cannot sign URLs, but these scopes are private: ${needsSigning.join(", ")}`
+    );
+  }
+};
+var escapesPrefix = (key) => key.startsWith("/") || key.split("/").some((segment) => segment === ".." || segment === ".");
+var resolveKey = (registry, name, entityId, file) => {
+  const key = registry.get(name).path(entityId, file);
+  if (escapesPrefix(key)) {
+    throw new ScopeError(`Scope "${name}" produced an unsafe key: ${key}`);
+  }
+  return key;
+};
+
+// src/server/crypto.ts
+var IV_LENGTH = 12;
+var TAG_LENGTH = 16;
+var HEADER_LENGTH = IV_LENGTH + TAG_LENGTH;
+var KEY_PATTERN = /^[0-9a-fA-F]{64}$/;
+var GcmDecryptStream = class extends stream.Transform {
+  constructor(key) {
+    super();
+    this.key = key;
+  }
+  key;
+  #header = Buffer.alloc(0);
+  #decipher = null;
+  _transform(chunk, _encoding, done) {
+    let body = chunk;
+    if (!this.#decipher) {
+      this.#header = Buffer.concat([this.#header, chunk]);
+      if (this.#header.length < HEADER_LENGTH) return done();
+      this.#decipher = crypto.createDecipheriv(
+        "aes-256-gcm",
+        this.key,
+        this.#header.subarray(0, IV_LENGTH)
+      );
+      this.#decipher.setAuthTag(this.#header.subarray(IV_LENGTH, HEADER_LENGTH));
+      body = this.#header.subarray(HEADER_LENGTH);
+      if (body.length === 0) return done();
+    }
+    try {
+      this.push(this.#decipher.update(body));
+      done();
+    } catch (error) {
+      done(error);
+    }
+  }
+  _flush(done) {
+    if (!this.#decipher) {
+      return done(new Error("Encrypted object ended before its header"));
+    }
+    try {
+      this.push(this.#decipher.final());
+      done();
+    } catch (error) {
+      done(error);
+    }
+  }
+};
+var createAesGcmCrypto = (hexKey) => {
+  if (!KEY_PATTERN.test(hexKey)) {
+    throw new ScopeError(
+      "createAesGcmCrypto: the key must be exactly 64 hex characters (32 bytes). Generate one with `openssl rand -hex 32`."
+    );
+  }
+  const key = Buffer.from(hexKey, "hex");
+  return {
+    encrypt: (data) => {
+      const iv = crypto.randomBytes(IV_LENGTH);
+      const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+      const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+      return Buffer.concat([iv, cipher.getAuthTag(), encrypted]);
+    },
+    decrypt: (data) => {
+      const buffer = Buffer.from(data);
+      const iv = buffer.subarray(0, IV_LENGTH);
+      const tag = buffer.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+      const ciphertext = buffer.subarray(IV_LENGTH + TAG_LENGTH);
+      const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+      decipher.setAuthTag(tag);
+      return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    },
+    decryptStream: (source) => source.pipe(new GcmDecryptStream(key))
+  };
+};
+var StorageRequestError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+  status;
+  name = "StorageRequestError";
+};
+var toHex = (buffer) => [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+var createStorage = ({
+  scopes,
+  provider,
+  crypto,
+  signedUrlTtl = 300,
+  encryptedUrl,
+  labels
+}) => {
+  const copy = resolveLabels(labels);
+  assertProviderSupports(scopes, provider);
+  const encrypted = scopes.names.filter((name) => scopes.get(name).encrypt);
+  if (encrypted.length > 0 && !crypto) {
+    throw new ScopeError(
+      `Scopes ${encrypted.join(", ")} declare "encrypt" but no CryptoHooks were provided to createStorage`
+    );
+  }
+  if (encrypted.length > 0 && !encryptedUrl) {
+    throw new ScopeError(
+      `Scopes ${encrypted.join(", ")} declare "encrypt" but no "encryptedUrl" was provided \u2014 a signed URL would serve ciphertext. Point it at the app's authenticated view endpoint.`
+    );
+  }
+  const getScope = (name) => {
+    if (!scopes.has(name)) {
+      throw new StorageRequestError(copy.unknownScope, 404);
+    }
+    return scopes.get(name);
+  };
+  const upload = async ({
+    scope: name,
+    entityId,
+    file,
+    uploadedBy
+  }) => {
+    const scope = getScope(name);
+    const result = await validateForScope(scopes, name, file, copy);
+    if (!result.valid) throw new StorageRequestError(result.message, 422);
+    const key = resolveKey(scopes, name, entityId, file);
+    const raw = new Uint8Array(await file.arrayBuffer());
+    const checksum = toHex(
+      await globalThis.crypto.subtle.digest("SHA-256", raw)
+    );
+    const body = scope.encrypt ? await crypto.encrypt(raw) : raw;
+    const put = await provider.put({
+      key,
+      body,
+      // Encrypted bytes are opaque on purpose: serving them with the real
+      // MIME would let a browser try to render ciphertext.
+      contentType: scope.encrypt ? "application/octet-stream" : file.type,
+      visibility: scope.visibility,
+      metadata: scope.metadata
+    });
+    const replaced = [];
+    if (resolveReplaceMode(scope) === "entity") {
+      const prefix = resolveScopePrefix(scope, entityId);
+      const stale = (await provider.list(prefix)).filter(
+        (object) => object.key !== put.key
+      );
+      await Promise.all(
+        stale.map(
+          (object) => provider.delete(object.key).then((deleted) => {
+            if (deleted) replaced.push(object.key);
+          }).catch(() => void 0)
+        )
+      );
+    }
+    const contentChecksum = put.checksum ?? checksum;
+    const publicUrl = put.url ? `${put.url}${put.url.includes("?") ? "&" : "?"}v=${contentChecksum.slice(0, 16)}` : put.url;
+    return {
+      key: put.key,
+      replaced,
+      url: scope.encrypt ? encryptedUrl({ scope: name, entityId, key: put.key }) : scope.visibility === "private" ? await provider.signedUrl(put.key, { expiresIn: signedUrlTtl }) : publicUrl,
+      scope: name,
+      entityId,
+      fileName: file.name,
+      mimeType: file.type,
+      size: file.size,
+      checksum: contentChecksum,
+      uploadedAt: Date.now(),
+      ...uploadedBy ? { uploadedBy } : {}
+    };
+  };
+  const read = async ({ scope: name, key }) => {
+    const scope = getScope(name);
+    const data = await provider.get(key);
+    return scope.encrypt ? crypto.decrypt(data) : data;
+  };
+  const readStream = async ({
+    scope: name,
+    key
+  }) => {
+    const scope = getScope(name);
+    const canStream = provider.getStream && (!scope.encrypt || crypto?.decryptStream);
+    if (!canStream) {
+      return stream.Readable.from([Buffer.from(await read({ scope: name, key }))]);
+    }
+    const source = await provider.getStream(key);
+    return scope.encrypt ? crypto.decryptStream(source) : source;
+  };
+  const remove = ({ scope: name, key }) => {
+    const scope = getScope(name);
+    if (scope.keepOnRemove) {
+      return Promise.resolve(false);
+    }
+    return provider.delete(key);
+  };
+  const signedUrl = ({
+    scope: name,
+    key,
+    download,
+    expiresIn
+  }) => {
+    const scope = getScope(name);
+    if (scope.visibility !== "private") {
+      throw new ScopeError(
+        `Scope "${name}" is public; its objects are reachable by their stored URL and never signed`
+      );
+    }
+    const options = {
+      expiresIn: expiresIn ?? signedUrlTtl,
+      ...download !== void 0 ? { download } : {}
+    };
+    return provider.signedUrl(key, options);
+  };
+  return {
+    upload,
+    read,
+    readStream,
+    remove,
+    signedUrl,
+    list: (prefix) => provider.list(prefix),
+    scopes,
+    labels: copy
+  };
+};
+
+exports.StorageRequestError = StorageRequestError;
+exports.createAesGcmCrypto = createAesGcmCrypto;
+exports.createStorage = createStorage;
+//# sourceMappingURL=server.cjs.map
+//# sourceMappingURL=server.cjs.map