mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 06:24:39 +00:00
82 lines
4.2 KiB
Markdown
82 lines
4.2 KiB
Markdown
# craft-zip
|
|
|
|
ZIP archives from untrusted files, read within limits and written. No `unsafe`.
|
|
|
|
The [`zip`](https://crates.io/crates/zip) crate does the decoding. This crate is what every
|
|
reader of a ZIP-based format (OOXML, OpenDocument, EPUB, IDML, design-tool archives) otherwise
|
|
writes again around it. Written from the ZIP specification (PKWARE APPNOTE.TXT).
|
|
|
|
Every limit is the caller's number: the crate has no defaults. Entry-name rules (which names
|
|
are safe, which spellings are one part) stay with the format that knows them.
|
|
|
|
## Reading
|
|
|
|
```rust
|
|
use craft_zip::{Archive, Compression, Limits, Writer};
|
|
|
|
# let mut w = Writer::new();
|
|
# w.add("mimetype", b"application/epub+zip", Compression::Stored)?;
|
|
# w.add("content.xml", b"<a/>", Compression::Deflated)?;
|
|
# let bytes = w.finish()?;
|
|
let mut zip = Archive::open(&bytes, Limits { max_entries: 20_000, max_total_bytes: 512 << 20 })?;
|
|
if zip.has_duplicate_names() {
|
|
// Two entries share a name; a format that must not guess which is real refuses here.
|
|
}
|
|
let part = zip.read("content.xml", 64 << 20)?; // Ok(None) when there is no such entry
|
|
assert_eq!(part.as_deref(), Some(&b"<a/>"[..]));
|
|
assert_eq!(zip.budget().used(), 4);
|
|
# Ok::<(), craft_zip::Error>(())
|
|
```
|
|
|
|
- `Archive::open` runs `check_entry_count` first. `zip` reserves room for, and parses, as many
|
|
central directory headers as the end record declares before its caller can count them, and a
|
|
ZIP64 end record can declare millions. The check finds the end records the way `zip` does and
|
|
refuses on the raw bytes.
|
|
- `Archive::read` refuses an entry that declares more than `max`, that expands past what it
|
|
declares, or that does not fit in what is left of `max_total_bytes`. At most 64 KiB is
|
|
reserved before bytes arrive, whatever the entry declares. Only a read that succeeds is
|
|
charged.
|
|
- `has_duplicate_names`: `zip` keeps one entry per name, so a central directory with more
|
|
headers than `zip` has entries repeats a name.
|
|
- `read_head(name, n)` reads the first `n` bytes only (a signature), charged to the total.
|
|
- `compressed_size` with `declared_size` gives the compression ratio an entry claims, for a
|
|
format that limits it.
|
|
- A clone shares the directory and the bytes and keeps its own count, for reading behind `&self`.
|
|
- `budget_mut` is for a caller with its own charging rule (charging a failed read, say).
|
|
- `Error::is_limit` tells a limit from a broken archive.
|
|
|
|
## Writing
|
|
|
|
`Writer::add(name, data, Compression::Stored | Deflated | Level(n))`, then `finish()`. Entries
|
|
keep their order (a stored `mimetype` goes first by being added first). Every entry has the same
|
|
1980 timestamp, so equal input gives equal bytes. An entry of 2 GiB or more is written in the
|
|
ZIP64 form. A repeated name is an error.
|
|
|
|
## Strict preflight
|
|
|
|
`preflight::preflight(bytes, limits)` checks the whole structure on the raw bytes without
|
|
allocating: exactly one end record may span the end of the file, the ZIP64 pair must agree with
|
|
it, the directory must sit exactly before the end records and be filled exactly by its entries,
|
|
single disk only, with limits on entries, directory bytes and name length. It is stricter than
|
|
`zip` (it refuses archives with data before them and archives with two plausible end records),
|
|
so `Archive::open` does not run it: a caller that wants nothing ambiguous to reach a ZIP reader
|
|
calls it first.
|
|
|
|
`preflight::read_entry(reader, declared, max, &mut budget)` is the bounded read on any
|
|
`std::io::Read`; `Budget` is a named limit with a running total.
|
|
|
|
## Where it came from
|
|
|
|
`preflight`, `read_entry` and `Budget`: the ZIP half of the craft-archive proposal (#126, #129).
|
|
`check_entry_count`: craft-opc's `guard`. Duplicate detection: craft-penpot's rule, made exact
|
|
by walking the directory. The writer: craft-opc's `ZipOut`.
|
|
|
|
## Seekable indexing
|
|
|
|
`MetadataReader::new(reader, metadata_bytes)` wraps a `Read + Seek` source without loading its
|
|
payload into memory. During ZIP indexing it admits reads only from the last `metadata_bytes`
|
|
bytes and charges repeated reads against twice that number. Call `Indexing::finish` on the
|
|
returned handle after the ZIP index has been parsed to permit normal streaming payload reads.
|
|
The caller must still enforce entry-count, declared-size and overlap limits: the wrapper only
|
|
bounds metadata reads and does not validate the archive.
|