Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions reviews/zip/2026-11-11-bar-audit.md
Original file line number Diff line number Diff line change
@@ -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`.