1use 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
24pub 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#[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 pub const fn max_input_bytes(self) -> u64 {
80 self.input
81 }
82 pub const fn max_entries(self) -> usize {
84 self.entries
85 }
86 pub const fn max_expanded_bytes(self) -> u64 {
88 self.expanded
89 }
90 pub const fn max_ratio(self) -> u64 {
92 self.ratio
93 }
94
95 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#[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#[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 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 pub fn entries(&self) -> impl ExactSizeIterator<Item = &ArchiveEntry> {
270 self.entries.values()
271 }
272
273 #[must_use]
275 pub fn original_bytes(&self) -> Arc<[u8]> {
276 Arc::clone(&self.bytes)
277 }
278
279 pub fn read(&mut self, path: &ArtifactPath) -> Result<Arc<[u8]>> {
281 self.read_with_limit(path, u64::MAX)
282 }
283
284 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 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
327struct 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}