diff --git a/reviews/zip/2026-11-11-bar-audit.md b/reviews/zip/2026-11-11-bar-audit.md new file mode 100644 index 0000000..0d28871 --- /dev/null +++ b/reviews/zip/2026-11-11-bar-audit.md @@ -0,0 +1,61 @@ +# Verified Bar review: Proven-Commons/zip (`1cbcc1f`) + +- **Target repository:** [Proven-Commons/zip](https://github.com/Proven-Commons/zip) at commit [`1cbcc1f`](https://github.com/Proven-Commons/zip/tree/1cbcc1ffe4c2572d9507286250e5250679d9b0e4) +- **Cross-checked repository:** [Proven-Commons/tar](https://github.com/Proven-Commons/tar) (open work on path predicates; see tar bar audit) +- **Playbook standard:** `playbook/verified-bar.md` (Verified Bar v2) in this repo +- **Date:** 2026-11-11 (mapping corrected 2026-11-20 against the pinned tree) +- **Verdict:** The reader at `1cbcc1f` is a pilot, not verified: there is no `bar.toml`, parsing is tested rather than proved, and extraction is in-memory only (`README.md`, `ZipPilot/Archive.lean` module header). Treat items below as review concerns to test or prove, not as verified production defects, until each has a pinned fixture and a recorded command output. + +## Summary + +At `1cbcc1f` the proved surface is the path gate and in-memory extraction in `ZipPilot/Path.lean` and `ZipPilot/Archive.lean` (`gate_sound`, `cleanComponents_sound`, `extractAll_safe`, `extractArchive_safe`). Header layout, CRC-32, inflation, and `parseArchive` are covered by differential tests (`tests/run_tests.py`, `tests/TEST-RESULTS.md`), not by proof. There is no ZIP writer and no `encode`/`parseArchive` round-trip theorem. The CLI (`Main.lean`) lists entries or prints a manifest; it does not write files to disk. + +Earlier versions of this note cited `Zip/Safe.lean`, `Zip/Parse.lean`, `SafeName`, `SafeEntry`, `SafeArchive`, and `extractSafe`, which do not exist at `1cbcc1f`. The mapping below uses the actual modules. + +## Findings + +### Z-F1 (High, CONCERN — differential UNVERIFIED here): NUL and control bytes in entry names + +- **Location:** `ZipPilot/Header.lean` (`bytesToName`), `ZipPilot/Path.lean` (`gate`, `gate_sound`). +- **Mechanism at `1cbcc1f`:** Names come from `String.fromUTF8?` (`bytesToName`). Invalid UTF-8 becomes `""`, which the gate rejects. A name that decodes with embedded `U+0000` is a valid Lean `String`; `gate_sound` only rules out `..`, empty components, `.`, absolute `/`, and an empty relative path. It does not forbid other control characters or NUL. `README.md` notes that whether backslashes should be rejected is still open; backslashes are ordinary characters, not separators. +- **Cross-library note:** Tar's `PlainName` work (tar PR #6) is a separate predicate; aligning NUL/control-byte rules across formats is still worth doing. +- **Earlier audit overclaim:** There is no archive-wide name-uniqueness (`Nodup`) check in `parseArchive`; a claim that duplicate logical names collide only because of Lean's `Nodup` is unsupported at this revision. +- **Status:** Reasonable hazard from the decoder and gate statement. This report does not include the binary fixture, Lean invocation, or `zipfile` output requested in review; label **UNVERIFIED** until those are committed beside the finding. +- **Suggested direction:** Reject `c.val < 0x20` and `c.val = 0x7F` in components (or in the full name before split), and add differential tests against Python `zipfile` and POSIX truncation behaviour. + +### Z-F2 (Low, NOT APPLICABLE as stated): `'/'` inside split components + +- **Location:** `ZipPilot/Path.lean` (`components` uses `String.splitOn "/"`; `gate_sound`). +- **At `1cbcc1f`:** Relative components are produced only by splitting on `/`, so no component string contains `/` unless the split implementation changes. The gap described in the tar audit (a single component holding `..` path text) does not apply the same way here. +- **Status:** Drop as a zip finding at this revision unless a concrete name shows otherwise. + +### Z-F3 (Medium, CONCERN — extraction consequence UNVERIFIED): Central-directory mode bits not classified + +- **Location:** `ZipPilot/Header.lean` (`parseCentralHeader` reads `externalFileAttributes` from the record but does not store or interpret them in `CentralEntry`). `ZipPilot/Archive.lean` (`extractAll`). +- **Mechanism at `1cbcc1f`:** `extractAll` emits `(dest ++ gated relative path, bytes)` in memory. `Main.lean` only prints a manifest; it does not create files or symlinks on disk (`README.md` "What is not proved"). +- **Status:** Ignoring `externalFileAttributes` is real for a downstream writer that honours UNIX modes. It is not a demonstrated symlink-creation bug in this implementation. **UNVERIFIED** for end-to-end filesystem extraction; frame any fix around classifying entry kind before bytes are handed to an I/O layer. + +### Z-F4 (High, CONCERN — overlap UNVERIFIED): No disjoint `localOffset` or aggregate output budget + +- **Location:** `ZipPilot/Archive.lean` (`parseArchive`, `readEntry`), `ZipPilot/Header.lean` (`CentralEntry`). +- **Mechanism at `1cbcc1f`:** `parseCentral` accepts every header that passes field checks; there is no check that entry byte ranges are pairwise disjoint or that total uncompressed size is bounded across the archive. Per-entry guards exist before inflate: `maxUncompressedSize` (256 MiB) and `maxInflateRatio` (1000:1) in `readEntry`. Central and local names must match (`readEntry` line 73). +- **Status:** Overlapping offsets are a plausible amplification concern but were not reproduced in this correction pass (no 188-byte fixture, no recorded `zip-pilot` or test run). **UNVERIFIED** until a fixture and command output are added. +- **Suggested direction:** Add archive-level disjoint-interval and total-uncompressed bounds if the threat model requires them. + +### Z-F5 (Low, NOT APPLICABLE at `1cbcc1f`): No verified-bar layout yet + +- **Location:** Repository root at `1cbcc1f` has no `bar.toml` and no `[spec].code` list. +- **At `1cbcc1f`:** `Main.lean` is the CLI entry point; whether it belongs in a future `[spec].code` block is a bar-adoption question, not a defect in the zip tree as it stands. +- **Status:** Revisit when the library adopts the mission template and records spec scope in `bar.toml`. + +## What was wrong in the first draft + +- Cited modules and predicates (`Zip/Safe.lean`, `SafeName`, `extractSafe`, `gate_sound` on a safe archive type) do not exist at `1cbcc1f`. +- Stated proved `parseArchive`/`encode` round trips; the README explicitly says parsing is tested and there is no ZIP writer. +- Marked several items **VERIFIED** without committed fixtures or Lean commands on this revision. + +## Suggested next steps + +1. Keep status **in-progress** on zip until bar item 1 (spec approval) and the parsing proof scope are decided. +2. For each remaining **CONCERN**, add a minimal binary fixture under `reviews/zip/fixtures/` (or the zip repo's `tests/`), the exact command (`python3 tests/run_tests.py` subset, `zip-pilot manifest`, or a small Lean example), and observed output before upgrading to **VERIFIED**. +3. When tightening the gate (NUL, backslash policy), update `SPEC.md` and re-run the recorded differential suite in `tests/TEST-RESULTS.md`. \ No newline at end of file