zipnative MCP — ZIP creation, inspection, secure extraction & verification

The ZIP checksum (IEEE 802.3 CRC-32, the engine's slice-by-8 implementation) of inline bytes / text or a sandbox file (streamed in 1 MiB chunks). `seed` continues a running CRC across consecutive chunks; `expect` compares against a known value (`matches`). Use it to cross-check an entry's crc32 from list_zip_entries against a file on disk.

Write a ZIP from inline entries (`dataBase64` | `text` | `sourcePath` in the sandbox, or `directory:true`). Reproducible by default: canonical order (raw UTF-8 name bytes), DOS-epoch timestamps, UTF-8 names, constant attributes — `defaultDate:'now'` or per-entry `date` opts out (ZIP_TIMESTAMP_NOT_PINNED diagnostic). `compression` {method store|deflate, level 0–9, deterministic:true = pinned pure-TS encoder ⇒ identical bytes on every runtime} at archive or entry level; `order:'insertion'` for EPUB / JAR (mimetype first, stored); `comment`, per-entry comment / unixMode / externalAttributes / raw extraFields. `stream:true` on a sourcePath feeds the file through addStream (data-descriptor layout, bounded memory). `parallel` compresses with the worker pool — byte-identical output. Zip64 is emitted exactly when a field overflows. Output base64 (≤ 50 MiB) or a sandbox file (streamed, never overwritten); `summary.deterministic` is true ONLY with compression.deterministic:true (cross-runtime identity); a default call is reproducible on the same runtime (`deflateTier` 'node-zlib') and reports false; `sha256` (includeSha256, base64 and file modes) is the proof. Every archive it writes is ISO/IEC 21320-1 conformant (CI-validated).

Offline preflight (no archive needed): server / engine / tool-API versions, the deflate tier in use and the pinned deterministic tier, runtime codecs (node:zlib, CompressionStream, DecompressionStream) and worker threads, the codec registry, the engine's default `limits`, the operator ceilings (ZIPNATIVE_MCP_MAX_UNCOMPRESSED_BYTES, ZIPNATIVE_MCP_MAX_ENTRIES, ZIPNATIVE_MCP_WORKERS), every server cap, whether the sandbox and the cache are enabled, the 39 frozen ZIP_* error codes and 11 diagnostic codes, and the engine exports this server deliberately does not expose (with why). `network` is always 'none'. Call it first in a session, or whenever a cap / ceiling refusal needs interpreting.

Produce a LOCAL GitHub issue draft + compliance report for zipnative / zipnative-mcp and NEVER submit it — the agent drafts, a human reviews and files it under their own identity (Human-In-The-Loop contract, .github/AGENT_RULES.md). No GitHub write path and no network path exist in this server. The draft is checked against the zero-dependency + reproduction policy; a violation (new runtime dependency, missing reproduction, duplicateSearchPerformed:false) throws GOVERNANCE_VIOLATION. targetRepo 'zipnative' for engine behaviour (parsing, writing, limits, codecs), 'zipnative-mcp' for wrapper behaviour (schemas, sandbox, transport). Returns markdown inline (outputMode:'file' also writes a .md inside the sandbox). Use it only after reproducing a defect — for questions read describe_engine / AGENTS.md instead. Present the draft AND the report to the user, then STOP.

Extract with every engine guard ON unless you name the relaxation: zip-slip / absolute / drive / UNC / NUL / ADS / Windows-device names → ZIP_PATH_TRAVERSAL (rejectTraversal:false SKIPS them, listed in `skipped`; an unsafe path is never emitted); symlinks → ZIP_SYMLINK_REJECTED (rejectSymlinks:false extracts the target text as data, never a link); duplicate sanitized paths → ZIP_EXTRACT_DUPLICATE_PATH (onDuplicate 'first' | 'last'); declared sizes / ratios beyond `limits` → ZIP_LIMIT_EXCEEDED; overlapping entries and central/local divergence are always refused. `filter` keeps a subset. outputMode 'base64' (default) returns files inline (≤ 16 MiB each, ≤ 32 MiB total; includeData:false = dry run of the plan); 'file' streams into a relative `outputDir` inside ZIPNATIVE_MCP_OUTPUT_DIR (never overwrites) and returns resource links. Directories are implied by paths (emptyDirectories:true creates the explicit ones). The dry run opens eagerly: an overlapping, offset-into-CD or Zip64-spoofed archive is refused before any plan is returned. Prefer read_zip_entry for a single file.

Decompress a raw DEFLATE (RFC 1951) stream — e.g. the payload from read_zip_entry mode:'raw' — with a MANDATORY `maxOutput` bound through zipnative's resumable inflater (constant memory, exact `bytesConsumed`, trailing bytes reported as `leftover`; ZIP_INFLATE_OUTPUT_OVERFLOW past the bound). method 'store' is a bounded pass-through; a numeric method id selects a registered codec (none beyond 0 / 8 in this server → ZIP_UNSUPPORTED_METHOD). Output base64 (≤ 50 MiB) or a sandbox file. Use it only for a raw payload or a bare deflate stream; to read an entry's content prefer read_zip_entry mode:'data'.

Read-only archive report in ONE call: size, entry / file / directory counts, Zip64, comment, compressed vs uncompressed totals, per-method counts, encrypted / symlink / data-descriptor / Zip64 / cp437 / duplicate / unsafe-name counts, date range, a `determinism` verdict (epoch timestamps + canonical order + UTF-8 flags ⇒ reproducible; `canonicalLayout` = no data descriptors) and every engine diagnostic (prepended SFX data, name mismatches, …). Opens EAGERLY by default: every entry's real extent is checked up front — overlapping entries, entries reaching into the central directory or past EOF, and Zip64 spoofing — and refused with their ZIP_* code rather than summarised (a method / CRC / size divergence between central and local headers is caught by verify_zip and on read, not here). `check:[…]` / `assert:{…}` turn it into a CI gate → `checks[]` + `checksPassed`. Token-frugal: verbosity:'summary', fields:[…]. Input: zipBase64 or zipPath (sandbox).

Read-only central-directory inventory without decompressing anything: every entry (duplicates included) in directory order as a full row — name + encoding, sizes, ratio, CRC-32, method, timestamp, decoded flags, Unix mode, symlink, Zip64, data descriptor, host system, offsets, named extra fields, the sanitized path an extraction would use (null = unsafe name), comment. `filter` selects by exact names / prefix / globs; `offset` + `limit` page (default 200, max 2000, `hasMore`). Prefer inspect_zip for a one-shot summary and read_zip_entry / extract_zip for content. Token-frugal: verbosity:'summary' → names only; fields:[…].

Edit an existing archive without recompressing anything: operations add / replace / remove / rename / setComment applied in order. mode 'append' (default) = save(): the original bytes stay verbatim and edits are appended — fast and byte-preserving, BUT removed or replaced payloads REMAIN in the file (data remanence: recoverable by anyone; a ZIP_DEAD_BYTES_RATIO diagnostic fires past 50 % dead bytes, and 7-Zip is known to read the stale payload). mode 'compact' = saveCompact(): canonical rewrite, still no recompression, removed data truly gone, SFX prefix dropped. No edits and an unchanged comment return the same bytes (`summary.noOp`). Archives with duplicate entry names are refused — prefer create_zip for a full rebuild or when the source has duplicate names. Output base64 or a sandbox file.

Read ONE entry without extracting the archive, by `name` (exact; the last duplicate wins) or `index` (central-directory position — disambiguates duplicates). mode 'data' (default): decompressed content as base64 or UTF-8 `text` (encoding:'utf8'; ENTRY_NOT_UTF8 otherwise), CRC-verified; a `range` {offset,length} reads a byte window through the chunked stream (bounded memory, no CRC). mode 'raw': the compressed payload verbatim (feed it to inflate_raw). mode 'verify': CRC / size / local-header agreement only. Inline cap 16 MiB per entry (ENTRY_TOO_LARGE → use a range or extract_zip file mode). Encrypted entries → ZIP_UNSUPPORTED_ENCRYPTION (no decryption in this engine).

Apply zipnative's single traversal gate `sanitizeEntryPath()` to a list of names: the safe '/'-separated relative form each maps to (join it under your extraction root — never the raw name), or null with the rule that fired (empty, NUL byte, absolute, drive letter, UNC, '..' traversal, NTFS alternate data stream ':', Windows reserved device name CON/NUL/COM1…). Use it when you extract with another tool or plan an external filesystem sink. No archive needed.

Walk LOCAL headers in stream order with bounded memory (zipnative's central-directory-less reader). The only tool that works on a truncated archive or a stream cut mid-way (it cannot skip an SFX prefix: the stream must start at a local header) — and the only one whose result is NOT authoritative: forward iteration trusts local headers ALONE, so a hostile archive can present different content here than inspect_zip / list_zip_entries report (the upload-scanner differential). Prefer those tools whenever the whole archive is available; use this one for forensics (`tolerateTruncation:true` returns the partial inventory + `error`). data 'none' skips payloads, 'verify' decompresses to check CRCs, 'include' returns them (inline caps). `stoppedAt` tells you whether a central directory was reached. Names are NOT sanitized — `sanitizedPath` shows what the extraction gate would use.

Deep verification in one call — zipnative's verifyZip report verbatim: eager structural validation, then every entry's CRC-32 / size / local-header agreement. `ok` is true when the structure is valid AND every verifiable entry passed. This tool NEVER fails for a problem with the archive: a structural refusal lands in `error` {code: ZIP_*, message}; an unverifiable entry is `skipped` ('encrypted' | 'stream-only-codec') and does not fail the archive, while an entry whose method has no codec here (anything but 0 store / 8 deflate) is reported FAILED, not skipped — the engine's verdict verbatim. Only caller mistakes (bad limits, bad input) are isError. `entries:'failed'` keeps the rows you act on; `verbosity:'summary'` keeps the verdict + counts. Verify before you trust: run it on any archive from an untrusted source before extract_zip.