@awak-app/simy-cli 0.2.3 → 0.4.0

package/src/local-task-file-capabilities.js

@@ -0,0 +1,738 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+const MIB = 1024 * 1024;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/i;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
+const ZIP_MAX_ENTRIES = 1_000;
+const ZIP_MAX_DECLARED_UNCOMPRESSED_BYTES = 200 * MIB;
+const OOXML_CONTENT_TYPES_MAX_BYTES = 2 * MIB;
+
+export const LOCAL_TASK_FILE_CAPABILITY_VERSION =
+  "local_task_file_capabilities.v1";
+export const LOCAL_TASK_ATTACHMENT_REF_VERSION =
+  "local_task_attachment_ref.v1";
+
+const RECOVERY_ACTIONS = deepFreeze({
+  choose_supported_file: {
+    id: "choose_supported_file",
+    label: "Choose another file",
+    description: "Choose a file type listed as supported by SIMY.",
+  },
+  reduce_file_size: {
+    id: "reduce_file_size",
+    label: "Use a smaller file",
+    description: "Compress, shorten, or split the file before trying again.",
+  },
+  remove_extra_files: {
+    id: "remove_extra_files",
+    label: "Use fewer files",
+    description: "Remove some files or combine them into a smaller supported file.",
+  },
+  reattach_file: {
+    id: "reattach_file",
+    label: "Attach the files again",
+    description: "Attach the original files again so SIMY can verify a fresh copy.",
+  },
+  update_cli: {
+    id: "update_cli",
+    label: "Update SIMY CLI",
+    description: "Update SIMY CLI, restart it, and attach the files again.",
+  },
+});
+
+const CATEGORY_DEFINITIONS = [
+  category("text", {
+    label: "Text",
+    description: "Plain text, Markdown, JSON, and YAML documents.",
+    inputMaxBytes: 10 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: false,
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "text_preview_or_download",
+    },
+    formats: [
+      format([".txt"], "text/plain", [], "utf8_text"),
+      format([".md", ".markdown"], "text/markdown", ["text/plain"], "utf8_text"),
+      format([".json"], "application/json", ["text/json", "text/plain"], "json"),
+      format(
+        [".yaml", ".yml"],
+        "application/yaml",
+        ["application/x-yaml", "text/yaml", "text/plain"],
+        "utf8_text",
+      ),
+    ],
+  }),
+  category("office", {
+    label: "Office document",
+    description: "Word, PowerPoint, and Rich Text documents.",
+    inputMaxBytes: 20 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: "container_may_include_relationships",
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "download",
+    },
+    formats: [
+      format(
+        [".docx"],
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ["application/octet-stream", "application/zip"],
+        "ooxml_word",
+      ),
+      format(
+        [".pptx"],
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        ["application/octet-stream", "application/zip"],
+        "ooxml_presentation",
+      ),
+      format([".rtf"], "application/rtf", ["text/rtf"], "rtf"),
+    ],
+  }),
+  category("pdf", {
+    label: "PDF",
+    description: "Portable Document Format documents.",
+    inputMaxBytes: 20 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: "may_contain_actions_or_links",
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "pdf_preview_or_download",
+    },
+    formats: [format([".pdf"], "application/pdf", [], "pdf")],
+  }),
+  category("spreadsheet", {
+    label: "Spreadsheet",
+    description: "Excel, CSV, and tab-separated data.",
+    inputMaxBytes: 20 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: "formulas_are_untrusted",
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "table_preview_or_download",
+    },
+    formats: [
+      format(
+        [".xlsx"],
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ["application/octet-stream", "application/zip"],
+        "ooxml_spreadsheet",
+      ),
+      format(
+        [".csv"],
+        "text/csv",
+        ["application/csv", "application/vnd.ms-excel", "text/plain"],
+        "utf8_text",
+      ),
+      format([".tsv"], "text/tab-separated-values", ["text/plain"], "utf8_text"),
+    ],
+  }),
+  category("image", {
+    label: "Image",
+    description: "PNG, JPEG, GIF, WebP, and SVG images.",
+    inputMaxBytes: 20 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: "svg_is_never_executed_or_inlined",
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "raster_preview_svg_download",
+    },
+    formats: [
+      format([".png"], "image/png", [], "png"),
+      format([".jpg", ".jpeg"], "image/jpeg", ["image/jpg"], "jpeg"),
+      format([".gif"], "image/gif", [], "gif"),
+      format([".webp"], "image/webp", [], "webp"),
+      format(
+        [".svg"],
+        "image/svg+xml",
+        ["application/xml", "text/xml"],
+        "svg",
+      ),
+    ],
+  }),
+  category("archive", {
+    label: "Archive",
+    description: "ZIP archives. Archive contents remain untrusted.",
+    inputMaxBytes: 20 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: "contents_not_executed",
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "download",
+    },
+    formats: [
+      format(
+        [".zip"],
+        "application/zip",
+        ["application/x-zip-compressed", "multipart/x-zip"],
+        "zip",
+      ),
+    ],
+  }),
+  category("audio", {
+    label: "Audio",
+    description: "MP3, WAV, M4A, AAC, Ogg, and FLAC audio.",
+    inputMaxBytes: 50 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: false,
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "audio_player_or_download",
+    },
+    formats: [
+      format([".mp3"], "audio/mpeg", ["audio/mp3"], "mp3"),
+      format([".wav"], "audio/wav", ["audio/x-wav"], "wav"),
+      format([".m4a"], "audio/mp4", ["audio/x-m4a"], "iso_bmff"),
+      format([".aac"], "audio/aac", [], "aac"),
+      format([".ogg"], "audio/ogg", ["application/ogg"], "ogg"),
+      format([".flac"], "audio/flac", ["audio/x-flac"], "flac"),
+    ],
+  }),
+  category("video", {
+    label: "Video",
+    description: "MP4, QuickTime, and WebM video.",
+    inputMaxBytes: 50 * MIB,
+    outputMaxBytes: 50 * MIB,
+    safety: {
+      active_content: false,
+      provider_treat_as_untrusted_data: true,
+      browser_presentation: "video_player_or_download",
+    },
+    formats: [
+      format([".mp4"], "video/mp4", [], "iso_bmff"),
+      format([".mov"], "video/quicktime", ["video/mov"], "iso_bmff"),
+      format([".webm"], "video/webm", [], "webm"),
+    ],
+  }),
+];
+
+export const LOCAL_TASK_FILE_CAPABILITY_REGISTRY = deepFreeze({
+  schema_version: LOCAL_TASK_FILE_CAPABILITY_VERSION,
+  input: {
+    max_files: 5,
+    max_total_bytes: 50 * MIB,
+    max_filename_chars: 180,
+    reference_schema_version: LOCAL_TASK_ATTACHMENT_REF_VERSION,
+    require_sha256: true,
+    require_magic_match: true,
+    device_bound: true,
+    persistence: "cli_state_managed_copy",
+  },
+  output: {
+    max_files: 50,
+    max_total_bytes: 100 * MIB,
+    max_filename_chars: 512,
+    max_manifest_bytes: 250_000,
+    require_sha256: true,
+    require_magic_match: true,
+    local_paths_public: false,
+  },
+  presentation: {
+    default: "download",
+    never_inline_active_content: true,
+    content_disposition: "attachment",
+    nosniff: true,
+  },
+  recovery_actions: RECOVERY_ACTIONS,
+  safety: {
+    filenames_are_normalized: true,
+    extension_and_mime_must_match: true,
+    magic_bytes_must_match: true,
+    hashes_are_rechecked_at_handoff: true,
+    file_content_is_untrusted_data: true,
+    executables_and_html_are_not_supported: true,
+  },
+  categories: CATEGORY_DEFINITIONS,
+});
+
+const FORMATS_BY_EXTENSION = new Map();
+for (const categoryValue of CATEGORY_DEFINITIONS) {
+  for (const formatValue of categoryValue.formats) {
+    for (const extension of formatValue.extensions) {
+      FORMATS_BY_EXTENSION.set(extension, {
+        category: categoryValue,
+        format: formatValue,
+      });
+    }
+  }
+}
+
+export class LocalTaskFileCapabilityError extends Error {
+  constructor(message, {
+    code = "local_task_file_invalid",
+    recoveryAction = RECOVERY_ACTIONS.choose_supported_file,
+    field = null,
+  } = {}) {
+    super(message);
+    this.name = "LocalTaskFileCapabilityError";
+    this.code = code;
+    this.recovery = recoveryAction.id;
+    this.recovery_action = recoveryAction;
+    this.field = field;
+  }
+}
+
+export function localTaskFileCapabilityMetadata() {
+  return structuredClone(LOCAL_TASK_FILE_CAPABILITY_REGISTRY);
+}
+
+export function normalizeLocalTaskMimeType(value) {
+  return String(value || "application/octet-stream")
+    .split(";", 1)[0]
+    .trim()
+    .toLowerCase();
+}
+
+export function canonicalMimeTypeForFilename(filename) {
+  return resolveFormat(filename).format.canonical_mime;
+}
+
+export function validateLocalTaskFile(input, {
+  direction = "input",
+  requireBytes = false,
+} = {}) {
+  const profile = LOCAL_TASK_FILE_CAPABILITY_REGISTRY[direction];
+  if (!profile || !["input", "output"].includes(direction)) {
+    throw new TypeError("direction must be input or output");
+  }
+  const name = safeFilename(input?.name, profile.max_filename_chars);
+  const { extension, category, format: fileFormat } = resolveFormat(name);
+  const suppliedMime = normalizeLocalTaskMimeType(
+    input?.mime_type ?? input?.mimeType ?? input?.type,
+  );
+  const acceptedMimes = new Set([
+    fileFormat.canonical_mime,
+    ...fileFormat.mime_aliases,
+  ]);
+  if (!acceptedMimes.has(suppliedMime)) {
+    throw fileError(
+      `The file type reported for ${name} does not match ${extension}.`,
+      "local_task_file_mime_mismatch",
+      "choose_supported_file",
+      "mime_type",
+    );
+  }
+
+  const sizeBytes = Number(input?.size_bytes ?? input?.sizeBytes);
+  const maxBytes =
+    direction === "input" ? category.input_max_bytes : category.output_max_bytes;
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 1) {
+    throw fileError(
+      `${name} has an invalid file size.`,
+      "local_task_file_size_invalid",
+      "reattach_file",
+      "size_bytes",
+    );
+  }
+  if (sizeBytes > maxBytes) {
+    throw fileError(
+      `${name} is larger than the ${formatBytes(maxBytes)} ${category.label.toLowerCase()} limit.`,
+      "local_task_file_too_large",
+      "reduce_file_size",
+      "size_bytes",
+    );
+  }
+
+  const bytes = input?.bytes === undefined ? null : Buffer.from(input.bytes);
+  if (requireBytes && !bytes) {
+    throw fileError(
+      `${name} is no longer available on this desktop.`,
+      "local_task_file_not_found",
+      "reattach_file",
+    );
+  }
+  if (bytes) {
+    if (bytes.byteLength !== sizeBytes) {
+      throw fileError(
+        `${name} changed after it was attached.`,
+        "local_task_file_size_mismatch",
+        "reattach_file",
+        "size_bytes",
+      );
+    }
+    if (!matchesMagic(fileFormat.magic, bytes)) {
+      throw fileError(
+        `${name} does not contain the expected ${category.label.toLowerCase()} format.`,
+        "local_task_file_magic_mismatch",
+        "choose_supported_file",
+      );
+    }
+  }
+
+  const suppliedSha = input?.sha256 == null
+    ? null
+    : String(input.sha256).trim().toLowerCase();
+  if (suppliedSha !== null && !SHA256_PATTERN.test(suppliedSha)) {
+    throw fileError(
+      `${name} has an invalid integrity digest.`,
+      "local_task_file_hash_invalid",
+      "reattach_file",
+      "sha256",
+    );
+  }
+  if (!bytes && suppliedSha === null) {
+    throw fileError(
+      `${name} is missing its integrity digest.`,
+      "local_task_file_hash_invalid",
+      "reattach_file",
+      "sha256",
+    );
+  }
+  const actualSha = bytes
+    ? createHash("sha256").update(bytes).digest("hex")
+    : suppliedSha;
+  if (bytes && suppliedSha && actualSha !== suppliedSha) {
+    throw fileError(
+      `${name} changed after it was attached.`,
+      "local_task_file_hash_mismatch",
+      "reattach_file",
+      "sha256",
+    );
+  }
+
+  return {
+    name,
+    extension,
+    category: category.id,
+    mime_type: fileFormat.canonical_mime,
+    size_bytes: sizeBytes,
+    sha256: actualSha,
+    capability_version: LOCAL_TASK_FILE_CAPABILITY_VERSION,
+  };
+}
+
+export function validateLocalTaskFileCollection(files, {
+  direction = "input",
+  requireBytes = false,
+} = {}) {
+  const values = Array.isArray(files) ? files : [];
+  const profile = LOCAL_TASK_FILE_CAPABILITY_REGISTRY[direction];
+  if (!profile) throw new TypeError("direction must be input or output");
+  if (values.length > profile.max_files) {
+    throw fileError(
+      `SIMY supports at most ${profile.max_files} ${direction} files.`,
+      "local_task_files_count_exceeded",
+      "remove_extra_files",
+    );
+  }
+  const validated = values.map((value) =>
+    validateLocalTaskFile(value, { direction, requireBytes }));
+  const totalBytes = validated.reduce((sum, value) => sum + value.size_bytes, 0);
+  if (totalBytes > profile.max_total_bytes) {
+    throw fileError(
+      `The ${direction} files are larger than the ${formatBytes(profile.max_total_bytes)} total limit.`,
+      "local_task_files_total_size_exceeded",
+      "remove_extra_files",
+    );
+  }
+  return validated;
+}
+
+export function localTaskFileErrorPayload(error) {
+  if (!(error instanceof LocalTaskFileCapabilityError)) {
+    return {
+      error: error instanceof Error ? error.message : String(error),
+      code: "local_task_file_invalid",
+      recovery: RECOVERY_ACTIONS.choose_supported_file.id,
+      recovery_action: RECOVERY_ACTIONS.choose_supported_file,
+    };
+  }
+  return {
+    error: error.message,
+    code: error.code,
+    recovery: error.recovery_action.id,
+    recovery_action: error.recovery_action,
+    ...(error.field ? { field: error.field } : {}),
+  };
+}
+
+function category(id, {
+  label,
+  description,
+  inputMaxBytes,
+  outputMaxBytes,
+  safety,
+  formats,
+}) {
+  return {
+    id,
+    label,
+    description,
+    input_max_bytes: inputMaxBytes,
+    output_max_bytes: outputMaxBytes,
+    presentation: safety.browser_presentation,
+    recovery_action_ids: ["choose_supported_file", "reduce_file_size"],
+    safety,
+    formats,
+  };
+}
+
+function format(extensions, canonicalMime, aliases, magic) {
+  return {
+    extensions,
+    canonical_mime: canonicalMime,
+    mime_aliases: aliases,
+    magic: {
+      policy: "required",
+      detector: magic,
+    },
+  };
+}
+
+function safeFilename(value, maxChars) {
+  const name = String(value || "").normalize("NFKC").trim();
+  if (
+    !name ||
+    name !== path.basename(name) ||
+    name === "." ||
+    name === ".." ||
+    CONTROL_CHARACTER_PATTERN.test(name)
+  ) {
+    throw fileError(
+      "The attachment has an invalid file name.",
+      "local_task_file_name_invalid",
+      "choose_supported_file",
+      "name",
+    );
+  }
+  if (name.length > maxChars) {
+    throw fileError(
+      `The file name is longer than ${maxChars} characters.`,
+      "local_task_file_name_too_long",
+      "choose_supported_file",
+      "name",
+    );
+  }
+  return name;
+}
+
+function resolveFormat(filename) {
+  const extension = path.extname(filename).toLowerCase();
+  const resolved = FORMATS_BY_EXTENSION.get(extension);
+  if (!resolved) {
+    throw fileError(
+      `${filename} is not a supported Local Task file type.`,
+      "local_task_file_extension_unsupported",
+      "choose_supported_file",
+      "name",
+    );
+  }
+  return { extension, ...resolved };
+}
+
+function matchesMagic(magicContract, bytes) {
+  const detector = magicContract.detector;
+  if (detector === "pdf") return startsWithAscii(bytes, "%PDF-");
+  if (detector === "png") {
+    return startsWithBytes(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  }
+  if (detector === "jpeg") return startsWithBytes(bytes, [0xff, 0xd8, 0xff]);
+  if (detector === "gif") {
+    return startsWithAscii(bytes, "GIF87a") || startsWithAscii(bytes, "GIF89a");
+  }
+  if (detector === "webp") {
+    return startsWithAscii(bytes, "RIFF") && asciiAt(bytes, 8, 4) === "WEBP";
+  }
+  if (detector === "svg") return safeText(bytes, (text) => /<svg(?:\s|>)/i.test(text));
+  if (detector === "rtf") return startsWithAscii(bytes, "{\\rtf");
+  if (detector === "zip") return isZip(bytes);
+  if (detector.startsWith("ooxml_")) {
+    const required = {
+      ooxml_word: {
+        root: "word/document.xml",
+        contentType:
+          "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml",
+      },
+      ooxml_presentation: {
+        root: "ppt/presentation.xml",
+        contentType:
+          "application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml",
+      },
+      ooxml_spreadsheet: {
+        root: "xl/workbook.xml",
+        contentType:
+          "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml",
+      },
+    }[detector];
+    return matchesOoxmlPackage(bytes, required);
+  }
+  if (detector === "mp3") {
+    return startsWithAscii(bytes, "ID3") ||
+      (bytes.length >= 2 && bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0);
+  }
+  if (detector === "wav") {
+    return startsWithAscii(bytes, "RIFF") && asciiAt(bytes, 8, 4) === "WAVE";
+  }
+  if (detector === "iso_bmff") return asciiAt(bytes, 4, 4) === "ftyp";
+  if (detector === "aac") {
+    return bytes.length >= 2 && bytes[0] === 0xff && (bytes[1] & 0xf6) === 0xf0;
+  }
+  if (detector === "ogg") return startsWithAscii(bytes, "OggS");
+  if (detector === "flac") return startsWithAscii(bytes, "fLaC");
+  if (detector === "webm") return startsWithBytes(bytes, [0x1a, 0x45, 0xdf, 0xa3]);
+  if (detector === "json") {
+    return safeText(bytes, (text) => {
+      try {
+        JSON.parse(text);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+  }
+  return detector === "utf8_text" && safeText(bytes, () => true);
+}
+
+function safeText(bytes, predicate) {
+  if (bytes.includes(0)) return false;
+  try {
+    return predicate(TEXT_DECODER.decode(bytes));
+  } catch {
+    return false;
+  }
+}
+
+function isZip(bytes) {
+  return (
+    startsWithBytes(bytes, [0x50, 0x4b, 0x03, 0x04]) ||
+    startsWithBytes(bytes, [0x50, 0x4b, 0x05, 0x06]) ||
+    startsWithBytes(bytes, [0x50, 0x4b, 0x07, 0x08])
+  );
+}
+
+function matchesOoxmlPackage(bytes, required) {
+  if (!required || !isZip(bytes)) return false;
+  try {
+    const entries = readZipCentralDirectory(bytes);
+    const contentTypesEntry = entries.get("[Content_Types].xml");
+    if (!contentTypesEntry || !entries.has(required.root)) return false;
+    const contentTypes = readZipEntry(bytes, contentTypesEntry, {
+      maxBytes: OOXML_CONTENT_TYPES_MAX_BYTES,
+    }).toString("utf8");
+    return contentTypes.includes(required.contentType);
+  } catch {
+    return false;
+  }
+}
+
+function readZipCentralDirectory(bytes) {
+  const minimumEocdSize = 22;
+  if (bytes.length < minimumEocdSize) throw new Error("invalid zip");
+  const searchStart = Math.max(0, bytes.length - (0xffff + minimumEocdSize));
+  let eocd = -1;
+  for (let offset = bytes.length - minimumEocdSize; offset >= searchStart; offset -= 1) {
+    if (bytes.readUInt32LE(offset) === 0x06054b50) {
+      eocd = offset;
+      break;
+    }
+  }
+  if (eocd < 0) throw new Error("zip end record not found");
+  const entryCount = bytes.readUInt16LE(eocd + 10);
+  const centralSize = bytes.readUInt32LE(eocd + 12);
+  const centralOffset = bytes.readUInt32LE(eocd + 16);
+  if (
+    entryCount === 0xffff ||
+    centralSize === 0xffffffff ||
+    centralOffset === 0xffffffff ||
+    entryCount > ZIP_MAX_ENTRIES ||
+    centralOffset + centralSize > eocd
+  ) {
+    throw new Error("unsupported zip directory");
+  }
+
+  const entries = new Map();
+  let offset = centralOffset;
+  let declaredUncompressedBytes = 0;
+  for (let index = 0; index < entryCount; index += 1) {
+    if (offset + 46 > bytes.length || bytes.readUInt32LE(offset) !== 0x02014b50) {
+      throw new Error("invalid zip directory entry");
+    }
+    const compressionMethod = bytes.readUInt16LE(offset + 10);
+    const compressedSize = bytes.readUInt32LE(offset + 20);
+    const uncompressedSize = bytes.readUInt32LE(offset + 24);
+    const filenameLength = bytes.readUInt16LE(offset + 28);
+    const extraLength = bytes.readUInt16LE(offset + 30);
+    const commentLength = bytes.readUInt16LE(offset + 32);
+    const localHeaderOffset = bytes.readUInt32LE(offset + 42);
+    const end = offset + 46 + filenameLength + extraLength + commentLength;
+    if (end > bytes.length) throw new Error("invalid zip entry bounds");
+    const name = bytes.subarray(offset + 46, offset + 46 + filenameLength).toString("utf8");
+    if (!name || name.includes("\0") || entries.has(name)) {
+      throw new Error("invalid zip entry name");
+    }
+    declaredUncompressedBytes += uncompressedSize;
+    if (declaredUncompressedBytes > ZIP_MAX_DECLARED_UNCOMPRESSED_BYTES) {
+      throw new Error("zip expansion limit exceeded");
+    }
+    entries.set(name, {
+      compressionMethod,
+      compressedSize,
+      uncompressedSize,
+      localHeaderOffset,
+    });
+    offset = end;
+  }
+  if (offset !== centralOffset + centralSize) throw new Error("invalid zip directory size");
+  return entries;
+}
+
+function readZipEntry(bytes, entry, { maxBytes }) {
+  if (
+    entry.uncompressedSize > maxBytes ||
+    entry.localHeaderOffset + 30 > bytes.length ||
+    bytes.readUInt32LE(entry.localHeaderOffset) !== 0x04034b50
+  ) {
+    throw new Error("invalid zip local entry");
+  }
+  const filenameLength = bytes.readUInt16LE(entry.localHeaderOffset + 26);
+  const extraLength = bytes.readUInt16LE(entry.localHeaderOffset + 28);
+  const dataOffset = entry.localHeaderOffset + 30 + filenameLength + extraLength;
+  const dataEnd = dataOffset + entry.compressedSize;
+  if (dataEnd > bytes.length) throw new Error("invalid zip data bounds");
+  const compressed = bytes.subarray(dataOffset, dataEnd);
+  const decoded =
+    entry.compressionMethod === 0
+      ? Buffer.from(compressed)
+      : entry.compressionMethod === 8
+        ? inflateRawSync(compressed, { maxOutputLength: maxBytes })
+        : null;
+  if (!decoded || decoded.length !== entry.uncompressedSize || decoded.length > maxBytes) {
+    throw new Error("invalid zip entry payload");
+  }
+  return decoded;
+}
+
+function startsWithAscii(bytes, value) {
+  return bytes.subarray(0, Buffer.byteLength(value)).equals(Buffer.from(value));
+}
+
+function asciiAt(bytes, offset, length) {
+  return bytes.subarray(offset, offset + length).toString("ascii");
+}
+
+function startsWithBytes(bytes, values) {
+  return bytes.length >= values.length &&
+    values.every((value, index) => bytes[index] === value);
+}
+
+function fileError(message, code, actionId, field = null) {
+  return new LocalTaskFileCapabilityError(message, {
+    code,
+    recoveryAction: RECOVERY_ACTIONS[actionId],
+    field,
+  });
+}
+
+function formatBytes(value) {
+  return value % MIB === 0 ? `${value / MIB} MiB` : `${value} bytes`;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}