Skip to main content

powerio_archive/
lib.rs

1//! Bounded, model-neutral ZIP transport. See [`Archive`] for validation stages.
2
3use std::collections::BTreeMap;
4use std::io::{Cursor, Read};
5use std::sync::{
6    Arc,
7    atomic::{AtomicBool, Ordering},
8};
9
10use powerio_core::{ArtifactPath, Error};
11use zip::{
12    CompressionMethod, ZipArchive,
13    read::{ArchiveOffset, Config},
14};
15
16pub mod end_records;
17pub mod package;
18pub mod session;
19pub mod stream;
20
21mod local;
22mod preflight;
23
24/// Stable diagnostic identities for archive transport.
25pub mod codes {
26    powerio_core::diagnostic_codes! {
27        INVALID_LIMIT = "REQUEST.ARCHIVE.INVALID_LIMIT", Error,
28            "archive limits must be positive and fit this platform", category = Request;
29        MALFORMED = "READ.ARCHIVE.MALFORMED", Error,
30            "ZIP metadata or payload integrity is invalid", category = Data;
31        UNSAFE = "READ.ARCHIVE.UNSAFE", Error,
32            "the archive namespace or member layout is unsafe", category = Data;
33        LIMIT = "READ.ARCHIVE.LIMIT", Error,
34            "the archive exceeds an explicit resource limit", category = Data;
35        UNSUPPORTED = "READ.ARCHIVE.UNSUPPORTED", Error,
36            "the archive uses an unsupported transport feature", category = Data;
37        UNKNOWN_ENTRY = "REQUEST.ARCHIVE.UNKNOWN_ENTRY", Error,
38            "the selected archive member does not exist", category = Request;
39    }
40}
41
42type Result<T> = std::result::Result<T, Error>;
43fn malformed(message: impl Into<String>) -> Error {
44    Error::new(&codes::MALFORMED, message)
45}
46fn unsafe_archive(message: impl Into<String>) -> Error {
47    Error::new(&codes::UNSAFE, message)
48}
49fn limit(message: impl Into<String>) -> Error {
50    Error::new(&codes::LIMIT, message)
51}
52fn unsupported(message: impl Into<String>) -> Error {
53    Error::new(&codes::UNSUPPORTED, message)
54}
55
56/// Explicit input, entry-count, cumulative expansion, and per-member ratio caps.
57/// Defaults: 64 MiB input/expanded bytes, 4096 entries, expansion ratio 200:1.
58/// These limits do not read the environment or bound downstream model memory.
59#[derive(Clone, Copy, Debug, Eq, PartialEq)]
60pub struct ArchiveLimits {
61    input: u64,
62    entries: usize,
63    expanded: u64,
64    ratio: u64,
65}
66
67impl Default for ArchiveLimits {
68    fn default() -> Self {
69        Self {
70            input: 64 << 20,
71            entries: 4096,
72            expanded: 64 << 20,
73            ratio: 200,
74        }
75    }
76}
77impl ArchiveLimits {
78    /// Maximum compressed input length.
79    pub const fn max_input_bytes(self) -> u64 {
80        self.input
81    }
82    /// Maximum entries in one admitted archive.
83    pub const fn max_entries(self) -> usize {
84        self.entries
85    }
86    /// Maximum sum of declared expanded lengths.
87    pub const fn max_expanded_bytes(self) -> u64 {
88        self.expanded
89    }
90    /// Maximum expanded to compressed member ratio.
91    pub const fn max_ratio(self) -> u64 {
92        self.ratio
93    }
94
95    /// Set positive limits. Byte counts and the index capacity must fit this
96    /// platform. Paths additionally have fixed 4096-byte/64-segment bounds.
97    pub fn new(input: u64, entries: usize, expanded: u64, ratio: u64) -> Result<Self> {
98        if input == 0
99            || entries == 0
100            || expanded == 0
101            || ratio == 0
102            || isize::try_from(input).is_err()
103            || isize::try_from(expanded).is_err()
104            || entries
105                .checked_mul(std::mem::size_of::<ArchiveEntry>())
106                .is_none_or(|n| n > isize::MAX as usize)
107        {
108            return Err(Error::new(
109                &codes::INVALID_LIMIT,
110                "archive limits must be positive and platform sized",
111            ));
112        }
113        Ok(Self {
114            input,
115            entries,
116            expanded,
117            ratio,
118        })
119    }
120}
121
122/// An indexed member. Names retain their exact UTF-8 spelling; directories
123/// have their terminal slash removed. Indexing does not validate payload CRCs.
124#[derive(Clone, Debug)]
125pub struct ArchiveEntry {
126    path: ArtifactPath,
127    directory: bool,
128    size: u64,
129    compressed: u64,
130    index: usize,
131    flags: u16,
132    method: u16,
133    crc: u32,
134    header: usize,
135    data: usize,
136}
137impl ArchiveEntry {
138    #[must_use]
139    pub fn path(&self) -> &ArtifactPath {
140        &self.path
141    }
142    #[must_use]
143    pub const fn is_directory(&self) -> bool {
144        self.directory
145    }
146    #[must_use]
147    pub const fn size(&self) -> u64 {
148        self.size
149    }
150    #[must_use]
151    pub const fn compressed_size(&self) -> u64 {
152        self.compressed
153    }
154}
155
156/// An immutable ZIP input with a validated index and lazily verified members.
157///
158/// Opening validates namespace, counts, declared expansion, local headers,
159/// descriptors, and nonoverlapping member regions before decompressing files.
160/// Reading validates actual size and CRC before publishing/caching bytes.
161/// Repeated reads return the same immutable allocation. Nothing is extracted,
162/// executed, discovered as a case, or recursively opened as another archive.
163///
164/// The supported profile is single-volume ZIP32/ZIP64 with stored/deflated
165/// members, UTF-8 paths and no prepended executable. Ambiguous metadata end
166/// records, encryption, symlinks, special files and unsafe paths are refused.
167#[derive(Debug)]
168pub struct Archive {
169    bytes: Arc<[u8]>,
170    zip: ZipArchive<preflight::IndexReader>,
171    entries: BTreeMap<ArtifactPath, ArchiveEntry>,
172    cache: BTreeMap<ArtifactPath, Arc<[u8]>>,
173}
174impl Archive {
175    /// Index caller-owned bytes under explicit limits without filesystem I/O.
176    /// An Arc input is retained without copying. Unread payload CRCs are not
177    /// certified. Expansion limits apply to the sum of all declared members.
178    pub fn open(bytes: impl AsRef<[u8]> + Into<Arc<[u8]>>, limits: ArchiveLimits) -> Result<Self> {
179        if bytes.as_ref().len() as u64 > limits.input {
180            return Err(limit("ZIP input byte limit exceeded"));
181        }
182        let bytes = bytes.into();
183        let directory = preflight::inspect(&bytes, limits)?;
184        let indexing = Arc::new(AtomicBool::new(true));
185        let reader = preflight::IndexReader {
186            cursor: Cursor::new(Arc::clone(&bytes)),
187            indexing: Arc::clone(&indexing),
188            central_start: directory.start,
189        };
190        let mut zip = ZipArchive::with_config(
191            Config {
192                archive_offset: ArchiveOffset::Known(0),
193            },
194            reader,
195        )
196        .map_err(|e| malformed(format!("cannot index ZIP: {e}")))?;
197        indexing.store(false, Ordering::Relaxed);
198        if zip.len() != directory.headers.len()
199            || zip.central_directory_start() != directory.start as u64
200        {
201            return Err(malformed(
202                "ZIP index disagrees with its bounded central directory",
203            ));
204        }
205        let mut entries = BTreeMap::new();
206        let mut nodes = BTreeMap::new();
207        let mut expanded = 0u64;
208        let mut regions = Vec::new();
209        for (index, &(flags, method)) in directory.headers.iter().enumerate() {
210            let file = zip
211                .by_index_raw(index)
212                .map_err(|e| malformed(format!("invalid ZIP member: {e}")))?;
213            validate_type(&file, flags)?;
214            let name = std::str::from_utf8(file.name_raw())
215                .map_err(|_| unsupported("ZIP member names must be UTF-8"))?;
216            if file.name().map_err(|e| malformed(e.to_string()))?.as_ref() != name {
217                return Err(unsafe_archive(
218                    "ZIP Unicode name override disagrees with its raw name",
219                ));
220            }
221            let is_dir = file.is_dir();
222            expanded = expanded
223                .checked_add(file.size())
224                .ok_or_else(|| limit("ZIP expansion size overflow"))?;
225            if expanded > limits.expanded {
226                return Err(limit("ZIP cumulative expanded byte limit exceeded"));
227            }
228            if file.size() > 0
229                && (file.compressed_size() == 0
230                    || file.size() > file.compressed_size().saturating_mul(limits.ratio))
231            {
232                return Err(limit("ZIP member compression ratio exceeded"));
233            }
234            let path = validate_path(name, is_dir, &mut nodes)?;
235            let entry = ArchiveEntry {
236                path: path.clone(),
237                directory: is_dir,
238                size: file.size(),
239                compressed: file.compressed_size(),
240                index,
241                flags,
242                method,
243                crc: file.crc32(),
244                header: usize::try_from(file.header_start())
245                    .map_err(|_| malformed("invalid local header offset"))?,
246                data: file
247                    .data_start()
248                    .and_then(|n| usize::try_from(n).ok())
249                    .ok_or_else(|| malformed("invalid member data offset"))?,
250            };
251            regions.push(local::validate(
252                &bytes,
253                &entry,
254                name.as_bytes(),
255                directory.start,
256            )?);
257            entries.insert(path, entry);
258        }
259        local::validate_regions(&mut regions, directory.start)?;
260        Ok(Self {
261            bytes,
262            zip,
263            entries,
264            cache: BTreeMap::new(),
265        })
266    }
267
268    /// Members in deterministic path order, including explicit directories.
269    pub fn entries(&self) -> impl ExactSizeIterator<Item = &ArchiveEntry> {
270        self.entries.values()
271    }
272
273    /// Exact original ZIP bytes, including its comment and compression data.
274    #[must_use]
275    pub fn original_bytes(&self) -> Arc<[u8]> {
276        Arc::clone(&self.bytes)
277    }
278
279    /// Read and CRC-verify a member, caching only a complete valid payload.
280    pub fn read(&mut self, path: &ArtifactPath) -> Result<Arc<[u8]>> {
281        self.read_with_limit(path, u64::MAX)
282    }
283
284    /// Apply an additional per-read byte cap, including on cached members.
285    /// A refusal does not populate the cache. Zero permits only empty members.
286    pub fn read_with_limit(&mut self, path: &ArtifactPath, max_bytes: u64) -> Result<Arc<[u8]>> {
287        self.read_cancellable(path, max_bytes, &session::Cancellation::default())
288    }
289
290    /// Read with cooperative cancellation between decompressor reads.
291    pub fn read_cancellable(
292        &mut self,
293        path: &ArtifactPath,
294        max_bytes: u64,
295        cancel: &session::Cancellation,
296    ) -> Result<Arc<[u8]>> {
297        cancel.check()?;
298        let entry = self.entries.get(path).ok_or_else(|| {
299            Error::new(
300                &codes::UNKNOWN_ENTRY,
301                format!("unknown ZIP member `{path}`"),
302            )
303        })?;
304        if entry.size > max_bytes {
305            return Err(limit("ZIP member exceeds the caller's byte limit"));
306        }
307        if let Some(bytes) = self.cache.get(path) {
308            return Ok(Arc::clone(bytes));
309        }
310        let mut file = self
311            .zip
312            .by_index(entry.index)
313            .map_err(|e| malformed(format!("cannot open ZIP member `{path}`: {e}")))?;
314        let content = stream::read_declared_size(
315            &mut session::CancellableReader(&mut file, cancel),
316            &[],
317            entry.size,
318        )
319        .map_err(|failure| malformed(format!("cannot verify ZIP member `{path}`: {failure:?}")))?;
320        cancel.check()?;
321        let content: Arc<[u8]> = content.into();
322        self.cache.insert(path.clone(), Arc::clone(&content));
323        Ok(content)
324    }
325}
326
327// Store segments rather than every full ancestor prefix: namespace storage
328// stays linear in supplied name bytes even for deep, disjoint paths.
329struct NameNode {
330    id: usize,
331    spelling: String,
332    directory: bool,
333    explicit: bool,
334}
335
336fn validate_path(
337    name: &str,
338    directory: bool,
339    nodes: &mut BTreeMap<(usize, String), NameNode>,
340) -> Result<ArtifactPath> {
341    let name = if directory {
342        name.strip_suffix('/').unwrap_or(name)
343    } else {
344        name
345    };
346    let path =
347        ArtifactPath::new(name).map_err(|_| unsafe_archive("ZIP member has an unsafe path"))?;
348    let parts: Vec<_> = name.split('/').collect();
349    if parts.len() > 64 {
350        return Err(limit("ZIP member path depth exceeded"));
351    }
352    let mut parent = 0;
353    for (index, part) in parts.iter().enumerate() {
354        let stem = part
355            .split('.')
356            .next()
357            .unwrap_or_default()
358            .to_ascii_lowercase();
359        let device_number = stem
360            .strip_prefix("com")
361            .or_else(|| stem.strip_prefix("lpt"))
362            .is_some_and(|suffix| {
363                suffix.chars().count() == 1
364                    && suffix
365                        .chars()
366                        .all(|c| c.is_ascii_digit() || matches!(c, '¹' | '²' | '³'))
367            });
368        if part.ends_with(['.', ' '])
369            || part.contains(['<', '>', '"', '|', '?', '*'])
370            || matches!(stem.as_str(), "con" | "prn" | "aux" | "nul")
371            || device_number
372        {
373            return Err(unsafe_archive(
374                "ZIP path is not portable across supported platforms",
375            ));
376        }
377        let is_directory = directory || index + 1 < parts.len();
378        let next_id = nodes.len() + 1;
379        let node = nodes
380            .entry((parent, part.to_lowercase()))
381            .or_insert_with(|| NameNode {
382                id: next_id,
383                spelling: (*part).to_owned(),
384                directory: is_directory,
385                explicit: false,
386            });
387        if node.spelling != *part || node.directory != is_directory {
388            return Err(unsafe_archive(
389                "ZIP file/directory or ancestor case collision",
390            ));
391        }
392        if index + 1 == parts.len() {
393            if node.explicit {
394                return Err(unsafe_archive("duplicate ZIP member path"));
395            }
396            node.explicit = true;
397        }
398        parent = node.id;
399    }
400    Ok(path)
401}
402
403fn validate_type(file: &zip::read::ZipFile<'_, impl Read>, flags: u16) -> Result<()> {
404    if file.encrypted() || flags & (1 | 64 | 8192) != 0 {
405        return Err(unsupported("encrypted ZIP members are unsupported"));
406    }
407    if !matches!(
408        file.compression(),
409        CompressionMethod::Stored | CompressionMethod::Deflated
410    ) {
411        return Err(unsupported(
412            "only stored and deflated ZIP members are supported",
413        ));
414    }
415    if let Some(mode) = file.unix_mode() {
416        let kind = mode & 0o170_000;
417        if !matches!(kind, 0 | 0o100_000 | 0o040_000)
418            || (kind != 0 && (kind == 0o040_000) != file.is_dir())
419        {
420            return Err(unsafe_archive(
421                "ZIP links and special files are unsupported",
422            ));
423        }
424    }
425    if file.is_dir() && file.size() != 0 {
426        return Err(unsafe_archive("directory member contains file data"));
427    }
428    Ok(())
429}