pith_zip/lib.rs
1//! ZIP container reading (PKZIP APPNOTE.TXT) plus a minimal XML reader
2//! for the members inside (the suite's first consumer is DOCX:
3//! `word/document.xml` in a zip).
4//!
5//! Part of the `pith` suite (pith-hash), the company split of the `modhash`
6//! zero-dependency hashing kit: the suite's only allowed dependencies are
7//! its own `pith-*` crates, so it still resolves without a single registry
8//! package. This crate reads crate `pith-inflate` for raw DEFLATE and
9//! `pith-digest` for CRC-32 verification and the shared
10//! `Error`/`Result` vocabulary.
11//!
12//! # ZIP scope (APPNOTE.TXT §4.3 and §4.4)
13//!
14//! The reader trusts the central directory at the end of the file - the
15//! structure every consumer of a zip actually honours - and only dips back
16//! to each local file header to find where the payload starts. Both
17//! `method 0` (stored) and `method 8` (raw DEFLATE) entries extract, and
18//! every extracted byte stream is verified against the entry's CRC-32
19//! before it is returned: a container reader that returns corrupt bytes
20//! hands a wrong hash to the tier-1 layer above.
21//!
22//! Real format variants outside that scope are refused with
23//! `Error::Unsupported`, never mis-decoded: ZIP64 records or sentinel
24//! fields, encrypted entries (flags bit 0, strong encryption bit 6, or the
25//! masked-local-header bit 13), multi-disk archives, and compression
26//! methods other than 0 and 8. Data descriptors (flags bit 3) are
27//! supported: the sizes and CRC are read from the central directory, and
28//! the descriptor record itself is verified after the payload.
29//!
30//! # XML scope
31//!
32//! [`XmlReader`] is a well-formed-enough tokenizer for what DOCX feeds it:
33//! elements with attributes, text nodes, the five predefined entities,
34//! decimal and hexadecimal numeric character references, comments,
35//! processing instructions and CDATA. Namespaces are passed through as
36//! ordinary `prefix:local` names - consumers match `w:t` literally.
37//! Anything not needed (DTD internals beyond a skipped `<!DOCTYPE>`,
38//! namespace resolution, schema) is skipped or refused.
39
40// `unsafe` is denied everywhere except `ffi`, the C ABI surface the
41// language SDKs bind through: raw pointers exist only at that boundary,
42// and every exported function is a documented `unsafe extern "C"` fn.
43#![deny(unsafe_code)]
44
45mod reader;
46mod xml;
47
48pub mod ffi;
49pub mod reference;
50
51pub use reader::{ZipArchive, ZipEntry};
52pub use xml::{XmlEvent, XmlReader};