uploaderkit 1.0.0

package/dist/index.cjs

@@ -0,0 +1,349 @@
+'use strict';
+
+// src/constants.ts
+var KB = 1024;
+var MB = 1024 * KB;
+var GB = 1024 * MB;
+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: "imagen",
+    accept: "image/*"
+  },
+  certificate: {
+    extensions: ["cer", "crt", "pem"],
+    maxBytes: 50 * KB,
+    validateMagicNumbers: true,
+    label: "certificado",
+    accept: ".cer,.crt,.pem"
+  },
+  key: {
+    extensions: ["key"],
+    maxBytes: 50 * KB,
+    validateMagicNumbers: true,
+    label: "llave privada",
+    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: "documento",
+    accept: ".pdf,.doc,.docx,.xls,.xlsx,.csv,.txt"
+  },
+  data: {
+    extensions: ["xml", "json"],
+    maxBytes: 5 * MB,
+    validateMagicNumbers: false,
+    label: "archivo de datos",
+    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: "archivo",
+    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 getMimeType = (fileName) => {
+  const ext = getFileExtension(fileName);
+  return MIME_TYPES[ext] ?? "application/octet-stream";
+};
+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]}`;
+};
+var toAcceptAttribute = (extensions) => extensions.length === 0 ? "*/*" : extensions.map((extension) => `.${extension}`).join(",");
+var fromMulterFile = (file) => ({
+  name: file.originalname,
+  size: file.size,
+  type: file.mimetype,
+  arrayBuffer: async () => file.buffer.buffer.slice(
+    file.buffer.byteOffset,
+    file.buffer.byteOffset + file.buffer.byteLength
+  )
+});
+
+// src/validation.ts
+var ok = { valid: true };
+var fail = (code, message) => ({ valid: false, code, message });
+var validateExtension = (fileName, allowed) => {
+  if (allowed.length === 0) return ok;
+  const extension = getFileExtension(fileName);
+  if (!extension) {
+    return fail("extension-not-allowed", "El archivo no tiene extensi\xF3n");
+  }
+  if (!allowed.includes(extension)) {
+    return fail(
+      "extension-not-allowed",
+      `Formato no permitido. Se aceptan: ${allowed.join(", ")}`
+    );
+  }
+  return ok;
+};
+var validateSize = (size, maxBytes) => {
+  if (size === 0) return fail("empty-file", "El archivo est\xE1 vac\xEDo");
+  if (size > maxBytes) {
+    return fail(
+      "too-large",
+      `El archivo pesa ${formatFileSize(size)} y el m\xE1ximo es ${formatFileSize(maxBytes)}`
+    );
+  }
+  return ok;
+};
+var validateMagicNumbers = async (file) => {
+  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", "El archivo est\xE1 incompleto");
+  }
+  const matches = expected.every((byte, index) => head[index] === byte);
+  return matches ? ok : fail(
+    "magic-number-mismatch",
+    "El contenido del archivo no corresponde a su extensi\xF3n"
+  );
+};
+var validateFile = async (file, options = {}) => {
+  const {
+    maxBytes = Infinity,
+    allowedExtensions = [],
+    validateMagicNumbers: checkMagic = false,
+    customValidation
+  } = options;
+  const size = validateSize(file.size, maxBytes);
+  if (!size.valid) return size;
+  const extension = validateExtension(file.name, allowedExtensions);
+  if (!extension.valid) return extension;
+  if (checkMagic) {
+    const magic = await validateMagicNumbers(file);
+    if (!magic.valid) return magic;
+  }
+  if (customValidation) return customValidation(file);
+  return ok;
+};
+var validateFiles = async (files, options = {}) => Promise.all(
+  files.map(async (file) => ({
+    file,
+    result: await validateFile(file, options)
+  }))
+);
+
+// src/scopes.ts
+var ScopeError = class extends Error {
+  name = "ScopeError";
+};
+var assertDefinition = (name, scope) => {
+  if (typeof scope.path !== "function") {
+    throw new ScopeError(`Scope "${name}": "path" must be a function`);
+  }
+  if (!Number.isFinite(scope.maxBytes) || scope.maxBytes <= 0) {
+    throw new ScopeError(
+      `Scope "${name}": "maxBytes" must be a positive number`
+    );
+  }
+  if (scope.accept.length === 0) {
+    throw new ScopeError(
+      `Scope "${name}": "accept" cannot be empty \u2014 list the extensions this scope takes`
+    );
+  }
+  if (scope.category && scope.category !== "any") {
+    const allowed = FILE_CATEGORY_CONFIG[scope.category].extensions;
+    const outside = scope.accept.filter(
+      (extension) => !allowed.includes(extension)
+    );
+    if (outside.length > 0) {
+      throw new ScopeError(
+        `Scope "${name}": ${outside.join(", ")} not allowed by category "${scope.category}"`
+      );
+    }
+  }
+  if (scope.compress) {
+    const imageOnly = FILE_CATEGORY_CONFIG.image.extensions;
+    const notImages = scope.accept.filter(
+      (extension) => !imageOnly.includes(extension)
+    );
+    if (notImages.length > 0) {
+      throw new ScopeError(
+        `Scope "${name}": "compress" only applies to images, but it accepts ${notImages.join(", ")}`
+      );
+    }
+  }
+};
+var defineScopes = (scopes) => {
+  for (const [name, scope] of Object.entries(scopes)) {
+    assertDefinition(name, scope);
+  }
+  const names = Object.keys(scopes);
+  const get = (name) => {
+    const scope = scopes[name];
+    if (!scope) {
+      throw new ScopeError(
+        `Unknown scope "${name}". Declared: ${names.join(", ")}`
+      );
+    }
+    return scope;
+  };
+  return {
+    scopes,
+    names,
+    get,
+    has: (name) => name in scopes,
+    accept: (name) => toAcceptAttribute(get(name).accept)
+  };
+};
+var validateForScope = async (registry, name, file) => {
+  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
+  });
+};
+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 resolveKey = (registry, name, entityId, file) => {
+  const key = registry.get(name).path(entityId, file);
+  if (key.startsWith("/") || key.includes("..")) {
+    throw new ScopeError(`Scope "${name}" produced an unsafe key: ${key}`);
+  }
+  return key;
+};
+
+exports.FILE_CATEGORY_CONFIG = FILE_CATEGORY_CONFIG;
+exports.GB = GB;
+exports.KB = KB;
+exports.MAGIC_NUMBERS = MAGIC_NUMBERS;
+exports.MB = MB;
+exports.MIME_TYPES = MIME_TYPES;
+exports.ScopeError = ScopeError;
+exports.assertProviderSupports = assertProviderSupports;
+exports.defineScopes = defineScopes;
+exports.formatFileSize = formatFileSize;
+exports.fromMulterFile = fromMulterFile;
+exports.getFileExtension = getFileExtension;
+exports.getMimeType = getMimeType;
+exports.isKnownExtension = isKnownExtension;
+exports.resolveKey = resolveKey;
+exports.toAcceptAttribute = toAcceptAttribute;
+exports.validateExtension = validateExtension;
+exports.validateFile = validateFile;
+exports.validateFiles = validateFiles;
+exports.validateForScope = validateForScope;
+exports.validateMagicNumbers = validateMagicNumbers;
+exports.validateSize = validateSize;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants.ts","../src/file.ts","../src/validation.ts","../src/scopes.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { FileCategory, FileCategoryConfig, FileExtension } from './types'\n\nexport const KB = 1024\nexport const MB = 1024 * KB\nexport const GB = 1024 * MB\n\n/**\n * Leading bytes that identify a format regardless of its extension. The check\n * that uses them is the only defence against an executable renamed to `.pdf`,\n * since both the extension and the browser-reported MIME come from the client.\n */\nexport const MAGIC_NUMBERS: Partial<Record<FileExtension, number[]>> = {\n\tpng: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],\n\tjpg: [0xff, 0xd8, 0xff],\n\tjpeg: [0xff, 0xd8, 0xff],\n\tgif: [0x47, 0x49, 0x46, 0x38],\n\twebp: [0x52, 0x49, 0x46, 0x46], // RIFF; bytes 8-11 spell WEBP\n\tico: [0x00, 0x00, 0x01, 0x00],\n\n\tpdf: [0x25, 0x50, 0x44, 0x46], // %PDF\n\n\t// OOXML files are ZIP containers, so docx/xlsx share the PK signature.\n\tdocx: [0x50, 0x4b, 0x03, 0x04],\n\txlsx: [0x50, 0x4b, 0x03, 0x04],\n\tdoc: [0xd0, 0xcf, 0x11, 0xe0],\n\txls: [0xd0, 0xcf, 0x11, 0xe0],\n\n\t// DER/ASN.1 sequence header.\n\tcer: [0x30, 0x82],\n\tcrt: [0x30, 0x82],\n\tkey: [0x30, 0x82],\n\tpem: [0x2d, 0x2d, 0x2d, 0x2d, 0x2d], // -----\n\n\twebm: [0x1a, 0x45, 0xdf, 0xa3],\n\tavi: [0x52, 0x49, 0x46, 0x46],\n\tmp3: [0x49, 0x44, 0x33], // ID3\n\twav: [0x52, 0x49, 0x46, 0x46],\n\togg: [0x4f, 0x67, 0x67, 0x53],\n\taac: [0xff, 0xf1],\n}\n\nexport const MIME_TYPES: Record<FileExtension, string> = {\n\tpng: 'image/png',\n\tjpg: 'image/jpeg',\n\tjpeg: 'image/jpeg',\n\tsvg: 'image/svg+xml',\n\twebp: 'image/webp',\n\tgif: 'image/gif',\n\tico: 'image/x-icon',\n\theic: 'image/heic',\n\n\tcer: 'application/x-x509-ca-cert',\n\tcrt: 'application/x-x509-ca-cert',\n\tpem: 'application/x-pem-file',\n\tkey: 'application/x-pem-file',\n\n\tpdf: 'application/pdf',\n\tdoc: 'application/msword',\n\tdocx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',\n\txls: 'application/vnd.ms-excel',\n\txlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',\n\tcsv: 'text/csv',\n\ttxt: 'text/plain',\n\n\txml: 'application/xml',\n\tjson: 'application/json',\n\n\tmp4: 'video/mp4',\n\tmov: 'video/quicktime',\n\tavi: 'video/x-msvideo',\n\twebm: 'video/webm',\n\n\tmp3: 'audio/mpeg',\n\twav: 'audio/wav',\n\togg: 'audio/ogg',\n\taac: 'audio/aac',\n}\n\n/**\n * Defaults per category. A scope always narrows these; it can never widen the\n * extension list, which is what keeps `any` from leaking into a strict scope.\n */\nexport const FILE_CATEGORY_CONFIG: Record<FileCategory, FileCategoryConfig> = {\n\timage: {\n\t\textensions: ['png', 'jpg', 'jpeg', 'svg', 'webp', 'gif'],\n\t\tmaxBytes: 5 * MB,\n\t\tvalidateMagicNumbers: true,\n\t\tlabel: 'imagen',\n\t\taccept: 'image/*',\n\t},\n\tcertificate: {\n\t\textensions: ['cer', 'crt', 'pem'],\n\t\tmaxBytes: 50 * KB,\n\t\tvalidateMagicNumbers: true,\n\t\tlabel: 'certificado',\n\t\taccept: '.cer,.crt,.pem',\n\t},\n\tkey: {\n\t\textensions: ['key'],\n\t\tmaxBytes: 50 * KB,\n\t\tvalidateMagicNumbers: true,\n\t\tlabel: 'llave privada',\n\t\taccept: '.key',\n\t},\n\tpdf: {\n\t\textensions: ['pdf'],\n\t\tmaxBytes: 20 * MB,\n\t\tvalidateMagicNumbers: true,\n\t\tlabel: 'PDF',\n\t\taccept: '.pdf',\n\t},\n\tdocument: {\n\t\textensions: ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'csv', 'txt'],\n\t\tmaxBytes: 20 * MB,\n\t\tvalidateMagicNumbers: false,\n\t\tlabel: 'documento',\n\t\taccept: '.pdf,.doc,.docx,.xls,.xlsx,.csv,.txt',\n\t},\n\tdata: {\n\t\textensions: ['xml', 'json'],\n\t\tmaxBytes: 5 * MB,\n\t\tvalidateMagicNumbers: false,\n\t\tlabel: 'archivo de datos',\n\t\taccept: '.xml,.json',\n\t},\n\tvideo: {\n\t\textensions: ['mp4', 'mov', 'avi', 'webm'],\n\t\tmaxBytes: 100 * MB,\n\t\tvalidateMagicNumbers: false,\n\t\tlabel: 'video',\n\t\taccept: 'video/*',\n\t},\n\taudio: {\n\t\textensions: ['mp3', 'wav', 'ogg', 'aac'],\n\t\tmaxBytes: 20 * MB,\n\t\tvalidateMagicNumbers: false,\n\t\tlabel: 'audio',\n\t\taccept: 'audio/*',\n\t},\n\tany: {\n\t\textensions: [],\n\t\tmaxBytes: 20 * MB,\n\t\tvalidateMagicNumbers: false,\n\t\tlabel: 'archivo',\n\t\taccept: '*/*',\n\t},\n}\n","import { MIME_TYPES } from './constants'\nimport type { FileExtension, FileLike } from './types'\n\n/** Lower-case extension without the dot, or `''` when the name has none. */\nexport const getFileExtension = (fileName: string): string => {\n\tconst dot = fileName.lastIndexOf('.')\n\tif (dot < 1 || dot === fileName.length - 1) return ''\n\treturn fileName.slice(dot + 1).toLowerCase()\n}\n\nexport const getMimeType = (fileName: string): string => {\n\tconst ext = getFileExtension(fileName) as FileExtension\n\treturn MIME_TYPES[ext] ?? 'application/octet-stream'\n}\n\nexport const isKnownExtension = (value: string): value is FileExtension =>\n\tvalue in MIME_TYPES\n\nexport const formatFileSize = (bytes: number): string => {\n\tif (bytes < 1024) return `${bytes} B`\n\tconst units = ['KB', 'MB', 'GB', 'TB']\n\tlet size = bytes / 1024\n\tlet unit = 0\n\twhile (size >= 1024 && unit < units.length - 1) {\n\t\tsize /= 1024\n\t\tunit++\n\t}\n\treturn `${size.toFixed(size >= 10 ? 0 : 1)} ${units[unit]}`\n}\n\n/** Value for an `<input accept=\"…\">` built from an extension list. */\nexport const toAcceptAttribute = (extensions: FileExtension[]): string =>\n\textensions.length === 0\n\t\t? '*/*'\n\t\t: extensions.map(extension => `.${extension}`).join(',')\n\n/**\n * Adapts a multer memory-storage file to `FileLike` so server code validates\n * with the very same function the browser ran.\n */\nexport const fromMulterFile = (file: {\n\toriginalname: string\n\tsize: number\n\tmimetype: string\n\tbuffer: Uint8Array\n}): FileLike => ({\n\tname: file.originalname,\n\tsize: file.size,\n\ttype: file.mimetype,\n\tarrayBuffer: async () =>\n\t\tfile.buffer.buffer.slice(\n\t\t\tfile.buffer.byteOffset,\n\t\t\tfile.buffer.byteOffset + file.buffer.byteLength\n\t\t) as ArrayBuffer,\n})\n","import { MAGIC_NUMBERS } from './constants'\nimport { formatFileSize, getFileExtension, isKnownExtension } from './file'\nimport type {\n\tFileExtension,\n\tFileLike,\n\tValidationOptions,\n\tValidationResult,\n} from './types'\n\nconst ok: ValidationResult = { valid: true }\n\nconst fail = (\n\tcode: Exclude<ValidationResult, { valid: true }>['code'],\n\tmessage: string\n): ValidationResult => ({ valid: false, code, message })\n\nexport const validateExtension = (\n\tfileName: string,\n\tallowed: FileExtension[]\n): ValidationResult => {\n\tif (allowed.length === 0) return ok\n\n\tconst extension = getFileExtension(fileName)\n\tif (!extension) {\n\t\treturn fail('extension-not-allowed', 'El archivo no tiene extensión')\n\t}\n\tif (!allowed.includes(extension as FileExtension)) {\n\t\treturn fail(\n\t\t\t'extension-not-allowed',\n\t\t\t`Formato no permitido. Se aceptan: ${allowed.join(', ')}`\n\t\t)\n\t}\n\treturn ok\n}\n\nexport const validateSize = (\n\tsize: number,\n\tmaxBytes: number\n): ValidationResult => {\n\tif (size === 0) return fail('empty-file', 'El archivo está vacío')\n\tif (size > maxBytes) {\n\t\treturn fail(\n\t\t\t'too-large',\n\t\t\t`El archivo pesa ${formatFileSize(size)} y el máximo es ${formatFileSize(maxBytes)}`\n\t\t)\n\t}\n\treturn ok\n}\n\n/**\n * Compares the file's leading bytes against the signature its extension\n * claims. Extensions without a known signature pass — absence of a signature\n * is not evidence of tampering.\n */\nexport const validateMagicNumbers = async (\n\tfile: FileLike\n): Promise<ValidationResult> => {\n\tconst extension = getFileExtension(file.name)\n\tif (!isKnownExtension(extension)) return ok\n\n\tconst expected = MAGIC_NUMBERS[extension]\n\tif (!expected) return ok\n\n\tconst head = new Uint8Array(await file.arrayBuffer()).slice(\n\t\t0,\n\t\texpected.length\n\t)\n\tif (head.length < expected.length) {\n\t\treturn fail('magic-number-mismatch', 'El archivo está incompleto')\n\t}\n\n\tconst matches = expected.every((byte, index) => head[index] === byte)\n\treturn matches\n\t\t? ok\n\t\t: fail(\n\t\t\t\t'magic-number-mismatch',\n\t\t\t\t'El contenido del archivo no corresponde a su extensión'\n\t\t\t)\n}\n\n/**\n * Runs the checks cheapest-first so a 2 GB file is rejected on its size before\n * anything reads its bytes.\n */\nexport const validateFile = async (\n\tfile: FileLike,\n\toptions: ValidationOptions = {}\n): Promise<ValidationResult> => {\n\tconst {\n\t\tmaxBytes = Infinity,\n\t\tallowedExtensions = [],\n\t\tvalidateMagicNumbers: checkMagic = false,\n\t\tcustomValidation,\n\t} = options\n\n\tconst size = validateSize(file.size, maxBytes)\n\tif (!size.valid) return size\n\n\tconst extension = validateExtension(file.name, allowedExtensions)\n\tif (!extension.valid) return extension\n\n\tif (checkMagic) {\n\t\tconst magic = await validateMagicNumbers(file)\n\t\tif (!magic.valid) return magic\n\t}\n\n\tif (customValidation) return customValidation(file)\n\n\treturn ok\n}\n\nexport type FileValidation = {\n\tfile: FileLike\n\tresult: ValidationResult\n}\n\n/** Validates every file and reports each result; never short-circuits. */\nexport const validateFiles = async (\n\tfiles: FileLike[],\n\toptions: ValidationOptions = {}\n): Promise<FileValidation[]> =>\n\tPromise.all(\n\t\tfiles.map(async file => ({\n\t\t\tfile,\n\t\t\tresult: await validateFile(file, options),\n\t\t}))\n\t)\n","import { FILE_CATEGORY_CONFIG } from './constants'\nimport { toAcceptAttribute } from './file'\nimport type {\n\tFileLike,\n\tScopeConfig,\n\tScopeRegistry,\n\tStorageProvider,\n\tValidationResult,\n} from './types'\nimport { validateFile } from './validation'\n\n/** Thrown for a definition or wiring mistake — never for a user's bad file. */\nexport class ScopeError extends Error {\n\toverride name = 'ScopeError'\n}\n\nconst assertDefinition = (name: string, scope: ScopeConfig): void => {\n\tif (typeof scope.path !== 'function') {\n\t\tthrow new ScopeError(`Scope \"${name}\": \"path\" must be a function`)\n\t}\n\tif (!Number.isFinite(scope.maxBytes) || scope.maxBytes <= 0) {\n\t\tthrow new ScopeError(\n\t\t\t`Scope \"${name}\": \"maxBytes\" must be a positive number`\n\t\t)\n\t}\n\tif (scope.accept.length === 0) {\n\t\tthrow new ScopeError(\n\t\t\t`Scope \"${name}\": \"accept\" cannot be empty — list the extensions this scope takes`\n\t\t)\n\t}\n\n\t// A scope narrows its category, never widens it. Otherwise a 'pdf' scope\n\t// could quietly start taking executables.\n\tif (scope.category && scope.category !== 'any') {\n\t\tconst allowed = FILE_CATEGORY_CONFIG[scope.category].extensions\n\t\tconst outside = scope.accept.filter(\n\t\t\textension => !allowed.includes(extension)\n\t\t)\n\t\tif (outside.length > 0) {\n\t\t\tthrow new ScopeError(\n\t\t\t\t`Scope \"${name}\": ${outside.join(', ')} not allowed by category \"${scope.category}\"`\n\t\t\t)\n\t\t}\n\t}\n\n\tif (scope.compress) {\n\t\tconst imageOnly = FILE_CATEGORY_CONFIG.image.extensions\n\t\tconst notImages = scope.accept.filter(\n\t\t\textension => !imageOnly.includes(extension)\n\t\t)\n\t\tif (notImages.length > 0) {\n\t\t\tthrow new ScopeError(\n\t\t\t\t`Scope \"${name}\": \"compress\" only applies to images, but it accepts ${notImages.join(', ')}`\n\t\t\t)\n\t\t}\n\t}\n}\n\n/**\n * Declares every destination an app can write to. The returned registry is\n * imported by the client (to configure inputs and pre-validate) and by the\n * server (to authorize and re-validate), which is what keeps the two in sync.\n *\n * Definitions are checked eagerly: a malformed scope throws at import time,\n * not on the first upload.\n */\nexport const defineScopes = <T extends Record<string, ScopeConfig>>(\n\tscopes: T\n): ScopeRegistry<T> => {\n\tfor (const [name, scope] of Object.entries(scopes)) {\n\t\tassertDefinition(name, scope)\n\t}\n\n\tconst names = Object.keys(scopes) as (keyof T & string)[]\n\n\tconst get = (name: string): ScopeConfig => {\n\t\tconst scope = scopes[name as keyof T]\n\t\tif (!scope) {\n\t\t\tthrow new ScopeError(\n\t\t\t\t`Unknown scope \"${name}\". Declared: ${names.join(', ')}`\n\t\t\t)\n\t\t}\n\t\treturn scope\n\t}\n\n\treturn {\n\t\tscopes,\n\t\tnames,\n\t\tget,\n\t\thas: name => name in scopes,\n\t\taccept: name => toAcceptAttribute(get(name).accept),\n\t}\n}\n\n/**\n * The one validation call. Client runs it for feedback, server runs it for\n * safety, both against the same scope.\n */\nexport const validateForScope = async <T extends Record<string, ScopeConfig>>(\n\tregistry: ScopeRegistry<T>,\n\tname: string,\n\tfile: FileLike\n): Promise<ValidationResult> => {\n\tconst scope = registry.get(name)\n\tconst category = scope.category\n\t\t? FILE_CATEGORY_CONFIG[scope.category]\n\t\t: undefined\n\n\treturn validateFile(file, {\n\t\tmaxBytes: scope.maxBytes,\n\t\tallowedExtensions: scope.accept,\n\t\tvalidateMagicNumbers: category?.validateMagicNumbers ?? true,\n\t})\n}\n\n/**\n * Fails fast when a provider cannot honour what the scopes promise — a private\n * scope on a provider that cannot sign URLs is a runtime 403 waiting to happen.\n */\nexport const assertProviderSupports = <T extends Record<string, ScopeConfig>>(\n\tregistry: ScopeRegistry<T>,\n\tprovider: StorageProvider\n): void => {\n\tconst needsSigning = registry.names.filter(\n\t\tname => registry.get(name).visibility === 'private'\n\t)\n\n\tif (needsSigning.length > 0 && !provider.capabilities.signedUrl) {\n\t\tthrow new ScopeError(\n\t\t\t`Provider \"${provider.name}\" cannot sign URLs, but these scopes are private: ${needsSigning.join(', ')}`\n\t\t)\n\t}\n}\n\n/** Resolves the storage key for an upload. */\nexport const resolveKey = <T extends Record<string, ScopeConfig>>(\n\tregistry: ScopeRegistry<T>,\n\tname: string,\n\tentityId: string,\n\tfile: FileLike\n): string => {\n\tconst key = registry.get(name).path(entityId, file)\n\tif (key.startsWith('/') || key.includes('..')) {\n\t\tthrow new ScopeError(`Scope \"${name}\" produced an unsafe key: ${key}`)\n\t}\n\treturn key\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,245 @@
+/**
+ * Every type in this file must be usable from a browser and from a server.
+ * That is what lets one scope definition drive the client's guards and the
+ * server's guards without the two drifting apart.
+ */
+type ImageExtension = 'png' | 'jpg' | 'jpeg' | 'svg' | 'webp' | 'gif' | 'ico' | 'heic';
+type CertificateExtension = 'cer' | 'crt' | 'pem';
+type KeyExtension = 'key';
+type DocumentExtension = 'pdf' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'csv' | 'txt';
+type DataExtension = 'xml' | 'json';
+type VideoExtension = 'mp4' | 'mov' | 'avi' | 'webm';
+type AudioExtension = 'mp3' | 'wav' | 'ogg' | 'aac';
+type FileExtension = ImageExtension | CertificateExtension | KeyExtension | DocumentExtension | DataExtension | VideoExtension | AudioExtension;
+/** Validation preset. Picks extensions, size ceiling and header checking. */
+type FileCategory = 'image' | 'certificate' | 'key' | 'pdf' | 'document' | 'data' | 'video' | 'audio' | 'any';
+type FileCategoryConfig = {
+    extensions: FileExtension[];
+    maxBytes: number;
+    /** Read the leading bytes to catch an .exe renamed to .pdf. */
+    validateMagicNumbers: boolean;
+    /** Lower-case singular noun used in error messages. */
+    label: string;
+    /** Value for an `<input accept="…">`. */
+    accept: string;
+};
+/**
+ * The subset of the DOM `File` this package needs. A browser `File`, a Node 18+
+ * `File` and a multer memory file (via `fromMulterFile`) all satisfy it, so
+ * `validateFile` is the same call on both sides of the wire.
+ */
+type FileLike = {
+    name: string;
+    size: number;
+    /** MIME type as reported by the source. Never trusted on its own. */
+    type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+};
+type UploadStatus = 'idle' | 'validating' | 'uploading' | 'success' | 'error';
+/** Machine-readable reason a file was rejected. Pair with `message` for UI. */
+type ValidationCode = 'extension-not-allowed' | 'too-large' | 'empty-file' | 'magic-number-mismatch' | 'mime-not-allowed' | 'custom';
+type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    code: ValidationCode;
+    message: string;
+};
+type ValidationOptions = {
+    maxBytes?: number;
+    allowedExtensions?: FileExtension[];
+    validateMagicNumbers?: boolean;
+    /** Runs last, only when every built-in check passed. */
+    customValidation?: (file: FileLike) => Promise<ValidationResult>;
+};
+/**
+ * Public files are served straight from their URL; private files are only ever
+ * reachable through a signed, expiring URL minted by the server.
+ */
+type Visibility = 'public' | 'private';
+/** Client-side image pipeline applied before upload. */
+type CompressOptions = {
+    maxWidth?: number;
+    maxHeight?: number;
+    /** 0–1. Ignored by formats without lossy encoding. */
+    quality?: number;
+    /**
+     * Drop EXIF metadata. Defaults to true: camera photos carry GPS
+     * coordinates, and a public bucket is the wrong place for them.
+     */
+    stripExif?: boolean;
+};
+/**
+ * A named destination. The single source of truth for where a file lands, who
+ * may read it, and what is accepted there.
+ */
+type ScopeConfig = {
+    /**
+     * Storage key for an upload. Receives the owning entity and the incoming
+     * file so the caller controls collisions and folder shape.
+     */
+    path: (entityId: string, file: FileLike) => string;
+    visibility: Visibility;
+    /** Extensions accepted here. Narrower than the category preset, never wider. */
+    accept: FileExtension[];
+    maxBytes: number;
+    category?: FileCategory;
+    /** Hand the bytes to the app's cipher before they leave the server. */
+    encrypt?: boolean;
+    compress?: CompressOptions;
+    /** Replace the object at the same key instead of adding a new one. */
+    overwrite?: boolean;
+    /** Documentation-only today; drives lifecycle rules once adapters read it. */
+    retention?: string;
+    /** Free-form tags forwarded to the provider when it supports metadata. */
+    metadata?: Record<string, string>;
+};
+type ScopeRegistry<T extends Record<string, ScopeConfig>> = {
+    scopes: T;
+    names: (keyof T & string)[];
+    get(name: string): ScopeConfig;
+    has(name: string): boolean;
+    /** `<input accept>` string for a scope, derived from its extensions. */
+    accept(name: keyof T & string): string;
+};
+/** What the app persists after a successful upload. */
+type StoredFile = {
+    /** Provider key. The handle for delete, re-sign and download. */
+    key: string;
+    /** Public URL, or a signed expiring URL when the scope is private. */
+    url: string;
+    scope: string;
+    entityId: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+    /** Enables dedupe and integrity checks when the provider reports it. */
+    checksum?: string;
+    uploadedAt: number;
+    uploadedBy?: string;
+};
+type PutInput = {
+    key: string;
+    body: Uint8Array;
+    contentType: string;
+    visibility: Visibility;
+    metadata?: Record<string, string>;
+};
+/**
+ * What a provider can actually do. Declared rather than discovered so a scope
+ * that needs signed URLs fails at boot, not the first time a user opens a file.
+ */
+type ProviderCapabilities = {
+    signedUrl: boolean;
+    resumable: boolean;
+    rangeRead: boolean;
+};
+type SignedUrlOptions = {
+    /** Seconds until the URL stops working. */
+    expiresIn: number;
+    /** Force a download instead of inline rendering. */
+    download?: boolean;
+};
+type StorageProvider = {
+    name: string;
+    capabilities: ProviderCapabilities;
+    put(input: PutInput): Promise<{
+        key: string;
+        url: string;
+        checksum?: string;
+    }>;
+    get(key: string): Promise<Uint8Array>;
+    delete(key: string): Promise<boolean>;
+    signedUrl?(key: string, options: SignedUrlOptions): Promise<string>;
+    list(prefix: string): Promise<{
+        key: string;
+        size: number;
+    }[]>;
+};
+/** Injected cipher for `encrypt: true` scopes. The package never ships one. */
+type CryptoHooks = {
+    encrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+    decrypt: (data: Uint8Array) => Uint8Array | Promise<Uint8Array>;
+};
+
+declare const KB = 1024;
+declare const MB: number;
+declare const GB: number;
+/**
+ * Leading bytes that identify a format regardless of its extension. The check
+ * that uses them is the only defence against an executable renamed to `.pdf`,
+ * since both the extension and the browser-reported MIME come from the client.
+ */
+declare const MAGIC_NUMBERS: Partial<Record<FileExtension, number[]>>;
+declare const MIME_TYPES: Record<FileExtension, string>;
+/**
+ * Defaults per category. A scope always narrows these; it can never widen the
+ * extension list, which is what keeps `any` from leaking into a strict scope.
+ */
+declare const FILE_CATEGORY_CONFIG: Record<FileCategory, FileCategoryConfig>;
+
+/** Lower-case extension without the dot, or `''` when the name has none. */
+declare const getFileExtension: (fileName: string) => string;
+declare const getMimeType: (fileName: string) => string;
+declare const isKnownExtension: (value: string) => value is FileExtension;
+declare const formatFileSize: (bytes: number) => string;
+/** Value for an `<input accept="…">` built from an extension list. */
+declare const toAcceptAttribute: (extensions: FileExtension[]) => string;
+/**
+ * Adapts a multer memory-storage file to `FileLike` so server code validates
+ * with the very same function the browser ran.
+ */
+declare const fromMulterFile: (file: {
+    originalname: string;
+    size: number;
+    mimetype: string;
+    buffer: Uint8Array;
+}) => FileLike;
+
+/** Thrown for a definition or wiring mistake — never for a user's bad file. */
+declare class ScopeError extends Error {
+    name: string;
+}
+/**
+ * Declares every destination an app can write to. The returned registry is
+ * imported by the client (to configure inputs and pre-validate) and by the
+ * server (to authorize and re-validate), which is what keeps the two in sync.
+ *
+ * Definitions are checked eagerly: a malformed scope throws at import time,
+ * not on the first upload.
+ */
+declare const defineScopes: <T extends Record<string, ScopeConfig>>(scopes: T) => ScopeRegistry<T>;
+/**
+ * The one validation call. Client runs it for feedback, server runs it for
+ * safety, both against the same scope.
+ */
+declare const validateForScope: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, file: FileLike) => Promise<ValidationResult>;
+/**
+ * Fails fast when a provider cannot honour what the scopes promise — a private
+ * scope on a provider that cannot sign URLs is a runtime 403 waiting to happen.
+ */
+declare const assertProviderSupports: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, provider: StorageProvider) => void;
+/** Resolves the storage key for an upload. */
+declare const resolveKey: <T extends Record<string, ScopeConfig>>(registry: ScopeRegistry<T>, name: string, entityId: string, file: FileLike) => string;
+
+declare const validateExtension: (fileName: string, allowed: FileExtension[]) => ValidationResult;
+declare const validateSize: (size: number, maxBytes: number) => ValidationResult;
+/**
+ * Compares the file's leading bytes against the signature its extension
+ * claims. Extensions without a known signature pass — absence of a signature
+ * is not evidence of tampering.
+ */
+declare const validateMagicNumbers: (file: FileLike) => Promise<ValidationResult>;
+/**
+ * Runs the checks cheapest-first so a 2 GB file is rejected on its size before
+ * anything reads its bytes.
+ */
+declare const validateFile: (file: FileLike, options?: ValidationOptions) => Promise<ValidationResult>;
+type FileValidation = {
+    file: FileLike;
+    result: ValidationResult;
+};
+/** Validates every file and reports each result; never short-circuits. */
+declare const validateFiles: (files: FileLike[], options?: ValidationOptions) => Promise<FileValidation[]>;
+
+export { type AudioExtension, type CertificateExtension, type CompressOptions, type CryptoHooks, type DataExtension, type DocumentExtension, FILE_CATEGORY_CONFIG, type FileCategory, type FileCategoryConfig, type FileExtension, type FileLike, type FileValidation, GB, type ImageExtension, KB, type KeyExtension, MAGIC_NUMBERS, MB, MIME_TYPES, type ProviderCapabilities, type PutInput, type ScopeConfig, ScopeError, type ScopeRegistry, type SignedUrlOptions, type StorageProvider, type StoredFile, type UploadStatus, type ValidationCode, type ValidationOptions, type ValidationResult, type VideoExtension, type Visibility, assertProviderSupports, defineScopes, formatFileSize, fromMulterFile, getFileExtension, getMimeType, isKnownExtension, resolveKey, toAcceptAttribute, validateExtension, validateFile, validateFiles, validateForScope, validateMagicNumbers, validateSize };