Skip to main content

libarchive_oxide_core/format/
tar.rs

1// SPDX-FileCopyrightText: 2026 libarchive_oxide contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! tar format (ustar / pax / GNU).
6//!
7//! Supports ustar, pax extensions, GNU long names and sparse maps, octal and
8//! base-256 numbers, and checksum verification.
9
10use alloc::borrow::Cow;
11use alloc::boxed::Box;
12use alloc::string::{String, ToString};
13use alloc::vec::Vec;
14use core::mem;
15
16use crate::error::{Error, Result};
17use crate::meta::{EntryKind, Timestamp, default_mode};
18use crate::metadata::{
19    ArchiveMetadata, ArchivePath, Device, EntryMetadata, EntryMetadataBuilder, EntryTimes,
20    Extension, Owner, SparseExtent,
21};
22use crate::protocol::{
23    ArchiveDecoder, ArchiveEncoder, Chunk, DecodeEvent, DecodeStep, EncodeCommand, EncodeStatus,
24    EncodeStep, EndOfInput, ProbeResult,
25};
26use crate::{ArchiveError, ErrorKind, Limits};
27
28/// tar block size. Every header and every payload is aligned to a multiple of this.
29const BLOCK: usize = 512;
30
31// ── ustar header field ranges (offsets within the 512B block).
32const F_NAME: (usize, usize) = (0, 100);
33const F_MODE: (usize, usize) = (100, 108);
34const F_UID: (usize, usize) = (108, 116);
35const F_GID: (usize, usize) = (116, 124);
36const F_SIZE: (usize, usize) = (124, 136);
37const F_MTIME: (usize, usize) = (136, 148);
38const F_CHKSUM: (usize, usize) = (148, 156);
39const O_TYPEFLAG: usize = 156;
40const F_LINKNAME: (usize, usize) = (157, 257);
41const F_MAGIC: (usize, usize) = (257, 263);
42const F_UNAME: (usize, usize) = (265, 297);
43const F_GNAME: (usize, usize) = (297, 329);
44const F_DEVMAJOR: (usize, usize) = (329, 337);
45const F_DEVMINOR: (usize, usize) = (337, 345);
46const F_PREFIX: (usize, usize) = (345, 500);
47const GNU_SPARSE_START: usize = 386;
48const GNU_SPARSE_COUNT: usize = 4;
49const GNU_SPARSE_EXTENDED: usize = 482;
50const GNU_SPARSE_REALSIZE: (usize, usize) = (483, 495);
51const GNU_SPARSE_EXT_COUNT: usize = 21;
52
53/// Overrides that a preceding header (PAX / GNU longname) imposes on the next entry or on all entries.
54type RawPaxRecord<'a> = (Cow<'a, [u8]>, Cow<'a, [u8]>);
55
56#[derive(Debug, Default, Clone)]
57struct Overrides<'a> {
58    path: Option<Cow<'a, [u8]>>,
59    linkpath: Option<Cow<'a, [u8]>>,
60    size: Option<u64>,
61    mtime: Option<Timestamp>,
62    atime: Option<Timestamp>,
63    ctime: Option<Timestamp>,
64    birthtime: Option<Timestamp>,
65    uid: Option<u64>,
66    gid: Option<u64>,
67    uname: Option<Cow<'a, [u8]>>,
68    gname: Option<Cow<'a, [u8]>>,
69    sparse_realsize: Option<u64>,
70    pax: Vec<RawPaxRecord<'a>>,
71}
72
73/// Owned overrides for the incremental tar parser.
74type OwnedOverrides = Overrides<'static>;
75
76// ── Incremental sans-IO source (Phase 4) ────────────────────────────────────────────────────────
77
78/// Which kind of extended / long header the tar parser is currently accumulating.
79#[derive(Debug, Clone, Copy)]
80enum MetaKind {
81    /// PAX `x`/`X`: extended records applying to the next entry.
82    PaxNext,
83    /// PAX `g`: global extended records applying to all subsequent entries.
84    PaxGlobal,
85    /// GNU `L`: the next entry's long name.
86    LongName,
87    /// GNU `K`: the next entry's long link target.
88    LongLink,
89}
90
91/// The tar parser driver state. `Copy` so `pull` can read it out of `self`, mutate the other
92/// fields, and write the successor back without borrow entanglement.
93#[derive(Debug, Clone, Copy)]
94enum State {
95    /// Awaiting a full 512-byte header block.
96    Header,
97    /// Streaming a real entry's payload: `remaining` data bytes, then `pad` zero bytes.
98    Payload { remaining: u64, pad: usize },
99    /// Accumulating an extended / long header record: `data` record bytes, then `pad` zero bytes.
100    Meta {
101        kind: MetaKind,
102        data: usize,
103        pad: usize,
104    },
105    /// Reading one or more old-GNU sparse extension blocks.
106    SparseExtensions { remaining: u64, pad: usize },
107    /// The archive has ended.
108    Done,
109}
110
111/// Internal state-machine result.
112enum Poll {
113    /// The state advanced; loop and drive again.
114    Continue,
115    /// Starved: waiting for more fed bytes.
116    NeedInput,
117    /// Archive terminated.
118    Done,
119    /// The current entry's payload is complete.
120    EndEntry,
121    /// A real entry header was parsed; its metadata is staged.
122    Entry,
123    /// A payload window is staged.
124    Data,
125}
126
127enum TarSourceEvent<'a> {
128    NeedInput,
129    ArchiveMetadata(ArchiveMetadata),
130    Entry {
131        metadata: Box<EntryMetadata>,
132        sparse: Vec<SparseExtent>,
133        is_sparse: bool,
134    },
135    Data(&'a [u8]),
136    EndEntry,
137    Done,
138}
139
140#[derive(Debug)]
141struct ParsedHeader {
142    kind: EntryKind,
143    path: Vec<u8>,
144    mode: u32,
145    uid: u64,
146    gid: u64,
147    modified: Option<Timestamp>,
148    link_target: Option<Vec<u8>>,
149}
150
151/// Incremental sans-IO tar reader.
152///
153/// Consumed buffer prefixes are removed between events.
154#[derive(Debug)]
155struct TarSource {
156    /// Input buffer.
157    buf: Vec<u8>,
158    /// Read position.
159    cursor: usize,
160    /// Driver state.
161    state: State,
162    /// End-of-input state.
163    finished: bool,
164    /// Overrides for the next entry.
165    pending: OwnedOverrides,
166    /// Global PAX overrides.
167    global: OwnedOverrides,
168    /// Partial extended header.
169    record: Vec<u8>,
170    /// Staged entry overrides.
171    stage_pending: OwnedOverrides,
172    /// Staged entry size.
173    stage_size: u64,
174    /// Logical entry size (different from stored size for sparse files).
175    stage_logical_size: u64,
176    /// Staged sparse data extents.
177    stage_sparse: Vec<SparseExtent>,
178    /// Whether sparse semantics apply even when the extent list is empty.
179    stage_is_sparse: bool,
180    /// Staged ustar owner names.
181    stage_uname: Vec<u8>,
182    stage_gname: Vec<u8>,
183    /// Staged device numbers.
184    stage_device: Option<Device>,
185    stage_referenced_device: Option<Device>,
186    /// Maximum data window requested by the v0.2 sparse driver.
187    payload_chunk_limit: usize,
188    /// Whether a global PAX record changed since the v0.2 driver last observed it.
189    global_changed: bool,
190    /// Staged data length.
191    stage_len: usize,
192}
193
194impl Default for TarSource {
195    fn default() -> Self {
196        Self::new()
197    }
198}
199
200impl TarSource {
201    /// A fresh source with an empty buffer.
202    #[must_use]
203    fn new() -> Self {
204        Self {
205            buf: Vec::new(),
206            cursor: 0,
207            state: State::Header,
208            finished: false,
209            pending: Overrides::default(),
210            global: Overrides::default(),
211            record: Vec::new(),
212            stage_pending: Overrides::default(),
213            stage_size: 0,
214            stage_logical_size: 0,
215            stage_sparse: Vec::new(),
216            stage_is_sparse: false,
217            stage_uname: Vec::new(),
218            stage_gname: Vec::new(),
219            stage_device: None,
220            stage_referenced_device: None,
221            payload_chunk_limit: usize::MAX,
222            global_changed: false,
223            stage_len: 0,
224        }
225    }
226
227    /// Bytes available past the cursor.
228    fn available(&self) -> usize {
229        self.buf.len() - self.cursor
230    }
231
232    fn buffered_len(&self) -> usize {
233        self.buf.len()
234    }
235
236    fn feed(&mut self, input: &[u8]) -> usize {
237        self.buf.extend_from_slice(input);
238        input.len()
239    }
240
241    const fn finish_input(&mut self) {
242        self.finished = true;
243    }
244
245    /// Removes consumed bytes and resets the cursor.
246    fn compact(&mut self) {
247        if self.cursor > 0 {
248            self.buf.drain(..self.cursor);
249            self.cursor = 0;
250        }
251    }
252
253    /// Apply a completed extended / long header record to the pending / global overrides.
254    fn apply_record(&mut self, kind: MetaKind) -> Result<()> {
255        match kind {
256            MetaKind::LongName => {
257                self.pending.path = Some(Cow::Owned(cstr(&self.record).to_vec()));
258            },
259            MetaKind::LongLink => {
260                self.pending.linkpath = Some(Cow::Owned(cstr(&self.record).to_vec()));
261            },
262            MetaKind::PaxNext => {
263                let mut parsed = Overrides::default();
264                parse_pax(&self.record, &mut parsed)?;
265                merge_owned(&mut self.pending, parsed);
266            },
267            MetaKind::PaxGlobal => {
268                let mut parsed = Overrides::default();
269                parse_pax(&self.record, &mut parsed)?;
270                merge_owned(&mut self.global, parsed);
271                self.global_changed = true;
272            },
273        }
274        Ok(())
275    }
276
277    /// Map a starvation point to [`Poll::NeedInput`] (more bytes may still arrive) or a truncation
278    /// error (input was already declared finished).
279    fn starved(&self, what: &'static str) -> Result<Poll> {
280        if self.finished {
281            Err(Error::Malformed(what))
282        } else {
283            Ok(Poll::NeedInput)
284        }
285    }
286
287    fn stage_header_metadata(
288        &mut self,
289        hdr: &[u8],
290        pending: OwnedOverrides,
291        physical_size: u64,
292    ) -> Result<()> {
293        let typeflag = hdr[O_TYPEFLAG];
294        self.stage_uname = pending
295            .uname
296            .as_ref()
297            .or(self.global.uname.as_ref())
298            .map_or_else(
299                || cstr(field(hdr, F_UNAME)).to_vec(),
300                |value| value.to_vec(),
301            );
302        self.stage_gname = pending
303            .gname
304            .as_ref()
305            .or(self.global.gname.as_ref())
306            .map_or_else(
307                || cstr(field(hdr, F_GNAME)).to_vec(),
308                |value| value.to_vec(),
309            );
310        let referenced_device = if matches!(typeflag, b'3' | b'4') {
311            Some(Device {
312                major: parse_numeric(field(hdr, F_DEVMAJOR))?,
313                minor: parse_numeric(field(hdr, F_DEVMINOR))?,
314            })
315        } else {
316            None
317        };
318        self.stage_device = None;
319        self.stage_referenced_device = referenced_device;
320        self.stage_sparse = pax_sparse_extents(&self.global, &pending)?;
321        self.stage_is_sparse = typeflag == b'S'
322            || pending.sparse_realsize.is_some()
323            || self.global.sparse_realsize.is_some()
324            || pending
325                .pax
326                .iter()
327                .chain(&self.global.pax)
328                .any(|(key, _)| key.as_ref().starts_with(b"GNU.sparse."));
329        self.stage_logical_size = pending
330            .sparse_realsize
331            .or(self.global.sparse_realsize)
332            .unwrap_or(physical_size);
333        if typeflag == b'S' {
334            self.stage_sparse.extend(parse_gnu_sparse_descriptors(
335                hdr,
336                GNU_SPARSE_START,
337                GNU_SPARSE_COUNT,
338            )?);
339            self.stage_logical_size = parse_numeric(field(hdr, GNU_SPARSE_REALSIZE))?;
340        }
341        if self.stage_is_sparse {
342            validate_sparse_extents(&self.stage_sparse, self.stage_logical_size, physical_size)?;
343        }
344        self.stage_pending = pending;
345        self.stage_size = physical_size;
346        self.payload_chunk_limit = usize::MAX;
347        Ok(())
348    }
349
350    /// Parse the next header block. Meta/long headers set up the [`State::Meta`] accumulation; a real
351    /// entry stages its overrides/size and advances to [`State::Payload`]; a zero/short block ends.
352    fn poll_header(&mut self) -> Result<Poll> {
353        if self.available() < BLOCK {
354            // A short/absent final block is a clean end of archive (mirrors the slice reader
355            // returning `None` when a whole header no longer fits).
356            if self.finished {
357                self.state = State::Done;
358                return Ok(Poll::Done);
359            }
360            return Ok(Poll::NeedInput);
361        }
362        let hdr = &self.buf[self.cursor..self.cursor + BLOCK];
363        if hdr.iter().all(|&b| b == 0) {
364            self.state = State::Done;
365            return Ok(Poll::Done);
366        }
367        verify_checksum(hdr)?;
368        let typeflag = hdr[O_TYPEFLAG];
369        let raw_size = parse_numeric(field(hdr, F_SIZE))?;
370
371        match typeflag {
372            // PAX / GNU long headers: their whole payload is a record, not entry data.
373            b'x' | b'X' | b'g' | b'L' | b'K' => {
374                let data = usize_of(raw_size)?;
375                let pad = round_up(raw_size)? - data;
376                let kind = match typeflag {
377                    b'g' => MetaKind::PaxGlobal,
378                    b'L' => MetaKind::LongName,
379                    b'K' => MetaKind::LongLink,
380                    _ => MetaKind::PaxNext,
381                };
382                self.cursor += BLOCK;
383                self.record.clear();
384                self.state = State::Meta { kind, data, pad };
385                Ok(Poll::Continue)
386            },
387            // Real entry: take `pending`, compute the size (respecting overrides), advance to the
388            // payload, and stage what [`pull`](Self::pull) needs to build the borrowed metadata.
389            _ => {
390                let pending = mem::take(&mut self.pending);
391                let hdr_start = self.cursor;
392                let size = {
393                    let hdr = &self.buf[hdr_start..hdr_start + BLOCK];
394                    pending
395                        .size
396                        .or(self.global.size)
397                        .map_or_else(|| parse_numeric(field(hdr, F_SIZE)), Ok)?
398                };
399                let pad = round_up(size)? - usize_of(size)?;
400                let header = self.buf[hdr_start..hdr_start + BLOCK].to_vec();
401                self.stage_header_metadata(&header, pending, size)?;
402                self.cursor = hdr_start + BLOCK;
403                self.state = if typeflag == b'S' && header[GNU_SPARSE_EXTENDED] != 0 {
404                    State::SparseExtensions {
405                        remaining: size,
406                        pad,
407                    }
408                } else {
409                    State::Payload {
410                        remaining: size,
411                        pad,
412                    }
413                };
414                if matches!(self.state, State::SparseExtensions { .. }) {
415                    Ok(Poll::Continue)
416                } else {
417                    Ok(Poll::Entry)
418                }
419            },
420        }
421    }
422
423    fn poll_sparse_extension(&mut self, remaining: u64, pad: usize) -> Result<Poll> {
424        if self.available() < BLOCK {
425            return self.starved("tar: truncated GNU sparse extension header");
426        }
427        let block = &self.buf[self.cursor..self.cursor + BLOCK];
428        self.stage_sparse.extend(parse_gnu_sparse_descriptors(
429            block,
430            0,
431            GNU_SPARSE_EXT_COUNT,
432        )?);
433        let extended = block[504] != 0;
434        self.cursor += BLOCK;
435        if extended {
436            self.state = State::SparseExtensions { remaining, pad };
437            return Ok(Poll::Continue);
438        }
439        validate_sparse_extents(&self.stage_sparse, self.stage_logical_size, remaining)?;
440        self.state = State::Payload { remaining, pad };
441        Ok(Poll::Entry)
442    }
443
444    /// Accumulate an extended / long header record (data bytes then padding). On completion it is
445    /// applied to the pending / global overrides and the driver returns to reading headers.
446    fn poll_meta(&mut self, kind: MetaKind, data: usize, pad: usize) -> Result<Poll> {
447        if data > 0 {
448            let avail = self.available();
449            if avail == 0 {
450                return self.starved("tar: truncated extended header");
451            }
452            let n = data.min(avail);
453            let from = self.cursor;
454            self.record.extend_from_slice(&self.buf[from..from + n]);
455            self.cursor += n;
456            self.state = State::Meta {
457                kind,
458                data: data - n,
459                pad,
460            };
461            return Ok(Poll::Continue);
462        }
463        if pad > 0 {
464            let avail = self.available();
465            if avail == 0 {
466                return self.starved("tar: truncated extended header");
467            }
468            let n = pad.min(avail);
469            self.cursor += n;
470            self.state = State::Meta {
471                kind,
472                data,
473                pad: pad - n,
474            };
475            return Ok(Poll::Continue);
476        }
477        self.apply_record(kind)?;
478        self.record = Vec::new();
479        self.state = State::Header;
480        Ok(Poll::Continue)
481    }
482
483    /// Stream a real entry's payload (data window then padding). Data windows are staged for
484    /// [`Poll::Data`]; once payload and padding are consumed the entry ends and the buffer compacts.
485    fn poll_payload(&mut self, remaining: u64, pad: usize) -> Result<Poll> {
486        if remaining > 0 {
487            let avail = self.available();
488            if avail == 0 {
489                return self.starved("tar: truncated payload");
490            }
491            let want = usize_of(remaining)?
492                .min(avail)
493                .min(self.payload_chunk_limit);
494            if want == 0 {
495                return Ok(Poll::NeedInput);
496            }
497            self.cursor += want;
498            self.state = State::Payload {
499                remaining: remaining - want as u64,
500                pad,
501            };
502            self.stage_len = want;
503            return Ok(Poll::Data);
504        }
505        if pad > 0 {
506            let avail = self.available();
507            if avail == 0 {
508                return self.starved("tar: truncated payload padding");
509            }
510            let n = pad.min(avail);
511            self.cursor += n;
512            self.state = State::Payload {
513                remaining,
514                pad: pad - n,
515            };
516            return Ok(Poll::Continue);
517        }
518        // Payload and padding consumed: end the entry. The consumed bytes are reclaimed at the
519        // top of the next `pull` (a single compaction point), keeping residency bounded.
520        self.state = State::Header;
521        Ok(Poll::EndEntry)
522    }
523
524    fn set_payload_chunk_limit(&mut self, limit: usize) {
525        self.payload_chunk_limit = limit;
526    }
527
528    fn take_global_metadata(&mut self) -> Option<ArchiveMetadata> {
529        if !mem::take(&mut self.global_changed) {
530            return None;
531        }
532        let mut metadata = ArchiveMetadata::new();
533        for (key, value) in &self.global.pax {
534            metadata = metadata.with_extension(Extension::new(
535                "pax",
536                key.as_ref().to_vec(),
537                value.as_ref().to_vec(),
538            ));
539        }
540        Some(metadata)
541    }
542
543    fn rich_metadata(&self, header: ParsedHeader) -> EntryMetadata {
544        let pending = &self.stage_pending;
545        let global = &self.global;
546        let times = EntryTimes {
547            modified: pending.mtime.or(global.mtime).or(header.modified),
548            accessed: pending.atime.or(global.atime),
549            changed: pending.ctime.or(global.ctime),
550            created: pending.birthtime.or(global.birthtime),
551        };
552        let mut builder = EntryMetadata::builder(header.kind, ArchivePath::from_bytes(header.path))
553            .size(Some(self.stage_logical_size))
554            .mode(Some(header.mode))
555            .owner(Owner {
556                uid: Some(header.uid),
557                gid: Some(header.gid),
558                user: (!self.stage_uname.is_empty()).then(|| self.stage_uname.clone()),
559                group: (!self.stage_gname.is_empty()).then(|| self.stage_gname.clone()),
560            })
561            .times(times)
562            .devices(self.stage_device, self.stage_referenced_device)
563            .link_target(header.link_target.map(ArchivePath::from_bytes));
564        for extent in &self.stage_sparse {
565            builder = builder.sparse_extent(*extent);
566        }
567        builder = add_pax_metadata(builder, &global.pax);
568        builder = add_pax_metadata(builder, &pending.pax);
569        builder.build()
570    }
571
572    fn pull_v2(&mut self) -> Result<TarSourceEvent<'_>> {
573        self.compact();
574        loop {
575            if self.global_changed {
576                let metadata = self
577                    .take_global_metadata()
578                    .ok_or(Error::InvalidState("global PAX update disappeared"))?;
579                return Ok(TarSourceEvent::ArchiveMetadata(metadata));
580            }
581            let poll = match self.state {
582                State::Done => return Ok(TarSourceEvent::Done),
583                State::Header => self.poll_header()?,
584                State::Meta { kind, data, pad } => self.poll_meta(kind, data, pad)?,
585                State::SparseExtensions { remaining, pad } => {
586                    self.poll_sparse_extension(remaining, pad)?
587                },
588                State::Payload { remaining, pad } => self.poll_payload(remaining, pad)?,
589            };
590            match poll {
591                Poll::Continue => {},
592                Poll::NeedInput => return Ok(TarSourceEvent::NeedInput),
593                Poll::Done => return Ok(TarSourceEvent::Done),
594                Poll::EndEntry => return Ok(TarSourceEvent::EndEntry),
595                Poll::Entry => {
596                    let start = match self.state {
597                        State::Payload { .. } => self
598                            .cursor
599                            .checked_sub(BLOCK)
600                            .filter(|start| {
601                                self.buf
602                                    .get(*start..*start + BLOCK)
603                                    .is_some_and(|header| verify_checksum(header).is_ok())
604                            })
605                            .unwrap_or_else(|| {
606                                self.buf
607                                    .get(..self.cursor)
608                                    .and_then(|prefix| {
609                                        prefix
610                                            .windows(BLOCK)
611                                            .rposition(|header| verify_checksum(header).is_ok())
612                                    })
613                                    .unwrap_or(0)
614                            }),
615                        _ => return Err(Error::InvalidState("tar entry was not staged")),
616                    };
617                    let header = self
618                        .buf
619                        .get(start..start + BLOCK)
620                        .ok_or(Error::Malformed("staged tar header disappeared"))?;
621                    let header = parse_source_header(header, &self.stage_pending, &self.global)?;
622                    let metadata = self.rich_metadata(header);
623                    return Ok(TarSourceEvent::Entry {
624                        metadata: Box::new(metadata),
625                        sparse: self.stage_sparse.clone(),
626                        is_sparse: self.stage_is_sparse,
627                    });
628                },
629                Poll::Data => {
630                    let from = self.cursor - self.stage_len;
631                    return Ok(TarSourceEvent::Data(&self.buf[from..self.cursor]));
632                },
633            }
634        }
635    }
636}
637
638/// v0.2 incremental tar decoder.
639///
640/// This is the first format implementation of the unified [`ArchiveDecoder`]
641/// contract. It wraps the proven tar state machine while the old entry-cursor
642/// surface is removed from the remaining formats.
643#[derive(Debug)]
644#[allow(clippy::struct_excessive_bools)]
645pub struct TarDecoder {
646    source: TarSource,
647    limits: Limits,
648    needs_input: bool,
649    input_finished: bool,
650    done: bool,
651    entries: u64,
652    entry_bytes: u64,
653    total_bytes: u64,
654    metadata_bytes: usize,
655    sparse_active: bool,
656    sparse: Vec<SparseExtent>,
657    sparse_index: usize,
658    logical_position: u64,
659    logical_size: u64,
660}
661
662impl TarDecoder {
663    /// Creates a decoder with explicit resource budgets.
664    #[must_use]
665    pub fn new(limits: Limits) -> Self {
666        Self {
667            source: TarSource::new(),
668            limits,
669            needs_input: true,
670            input_finished: false,
671            done: false,
672            entries: 0,
673            entry_bytes: 0,
674            total_bytes: 0,
675            metadata_bytes: 0,
676            sparse_active: false,
677            sparse: Vec::new(),
678            sparse_index: 0,
679            logical_position: 0,
680            logical_size: 0,
681        }
682    }
683
684    /// Incrementally probes for a ustar/PAX/GNU tar header.
685    #[must_use]
686    pub fn probe(prefix: &[u8]) -> ProbeResult<()> {
687        if prefix.len() < BLOCK {
688            ProbeResult::NeedMore { minimum: BLOCK }
689        } else if prefix[..BLOCK].iter().all(|byte| *byte == 0) {
690            // Empty tar begins with zero blocks, but so do ISO images before
691            // their sector-16 descriptor. Runtime detection must defer the
692            // ambiguous all-zero prefix long enough to check that signature.
693            const ISO_PROBE: usize = 16 * 2048 + 6;
694            if prefix.len() < ISO_PROBE {
695                ProbeResult::NeedMore { minimum: ISO_PROBE }
696            } else {
697                ProbeResult::Match(())
698            }
699        } else if verify_checksum(&prefix[..BLOCK]).is_ok() {
700            ProbeResult::Match(())
701        } else {
702            ProbeResult::NoMatch
703        }
704    }
705
706    fn check_limit_u64(
707        actual: u64,
708        limit: Option<u64>,
709        message: &'static str,
710    ) -> core::result::Result<(), ArchiveError> {
711        if limit.is_some_and(|limit| actual > limit) {
712            return Err(ArchiveError::new(ErrorKind::Limit)
713                .with_format("tar")
714                .with_context(message));
715        }
716        Ok(())
717    }
718
719    fn account_data(&mut self, length: usize) -> core::result::Result<(), ArchiveError> {
720        let length = u64::try_from(length).map_err(|_| {
721            ArchiveError::new(ErrorKind::Limit)
722                .with_format("tar")
723                .with_context("data window length exceeds u64")
724        })?;
725        self.entry_bytes = self.entry_bytes.checked_add(length).ok_or_else(|| {
726            ArchiveError::new(ErrorKind::Limit)
727                .with_format("tar")
728                .with_context("entry byte count overflow")
729        })?;
730        self.total_bytes = self.total_bytes.checked_add(length).ok_or_else(|| {
731            ArchiveError::new(ErrorKind::Limit)
732                .with_format("tar")
733                .with_context("decoded byte count overflow")
734        })?;
735        Self::check_limit_u64(
736            self.entry_bytes,
737            self.limits.entry_bytes(),
738            "entry bytes exceed limit",
739        )?;
740        Self::check_limit_u64(
741            self.total_bytes,
742            self.limits.decoded_total(),
743            "decoded bytes exceed limit",
744        )
745    }
746
747    fn entry_metadata_cost(metadata: &EntryMetadata) -> core::result::Result<usize, ArchiveError> {
748        metadata
749            .path()
750            .as_bytes()
751            .len()
752            .checked_add(
753                metadata
754                    .link_target()
755                    .map_or(0, |target| target.as_bytes().len()),
756            )
757            .and_then(|value| {
758                value.checked_add(
759                    metadata
760                        .extensions()
761                        .iter()
762                        .map(|extension| extension.key().len() + extension.value().len())
763                        .sum::<usize>(),
764                )
765            })
766            .and_then(|value| {
767                value.checked_add(
768                    metadata
769                        .xattrs()
770                        .iter()
771                        .map(|(name, value)| name.len() + value.len())
772                        .sum::<usize>(),
773                )
774            })
775            .and_then(|value| value.checked_add(metadata.acl().iter().map(Vec::len).sum::<usize>()))
776            .ok_or_else(|| {
777                ArchiveError::new(ErrorKind::Limit)
778                    .with_format("tar")
779                    .with_context("metadata accounting overflow")
780            })
781    }
782
783    fn sparse_hole<'a>(
784        &mut self,
785        output: &'a mut [u8],
786    ) -> core::result::Result<Option<DecodeStep<'a>>, ArchiveError> {
787        if !self.sparse_active {
788            self.source.set_payload_chunk_limit(usize::MAX);
789            return Ok(None);
790        }
791        while self.sparse.get(self.sparse_index).is_some_and(|extent| {
792            extent
793                .offset
794                .checked_add(extent.length)
795                .is_some_and(|end| self.logical_position == end)
796        }) {
797            self.sparse_index += 1;
798        }
799        let next_data = self
800            .sparse
801            .get(self.sparse_index)
802            .map_or(self.logical_size, |extent| extent.offset);
803        if self.logical_position < next_data {
804            if output.is_empty() {
805                return Ok(Some(DecodeStep {
806                    consumed: 0,
807                    produced: 0,
808                    event: DecodeEvent::NeedOutput,
809                }));
810            }
811            let hole = next_data - self.logical_position;
812            let count = usize::try_from(hole.min(output.len() as u64)).map_err(|_| {
813                ArchiveError::new(ErrorKind::Limit)
814                    .with_format("tar")
815                    .with_context("sparse hole exceeds address space")
816            })?;
817            output[..count].fill(0);
818            self.logical_position += count as u64;
819            self.account_data(count)?;
820            return Ok(Some(DecodeStep {
821                consumed: 0,
822                produced: count,
823                event: DecodeEvent::Data(Chunk::new(&output[..count])),
824            }));
825        }
826        if let Some(extent) = self.sparse.get(self.sparse_index) {
827            let end = extent.offset.checked_add(extent.length).ok_or_else(|| {
828                ArchiveError::new(ErrorKind::Malformed)
829                    .with_format("tar")
830                    .with_context("sparse extent overflow")
831            })?;
832            let remaining = end.saturating_sub(self.logical_position);
833            self.source
834                .set_payload_chunk_limit(usize::try_from(remaining).unwrap_or(usize::MAX));
835        } else {
836            self.source.set_payload_chunk_limit(usize::MAX);
837        }
838        Ok(None)
839    }
840}
841
842impl Default for TarDecoder {
843    fn default() -> Self {
844        Self::new(Limits::default())
845    }
846}
847
848impl ArchiveDecoder for TarDecoder {
849    #[allow(clippy::too_many_lines)]
850    fn step<'a>(
851        &'a mut self,
852        input: &'a [u8],
853        output: &'a mut [u8],
854        end: EndOfInput,
855    ) -> core::result::Result<DecodeStep<'a>, ArchiveError> {
856        if self.done {
857            if !input.is_empty() {
858                return Err(ArchiveError::new(ErrorKind::Protocol)
859                    .with_format("tar")
860                    .with_context("input supplied after archive end"));
861            }
862            return Ok(DecodeStep {
863                consumed: 0,
864                produced: 0,
865                event: DecodeEvent::Done,
866            });
867        }
868        if self
869            .limits
870            .in_flight_bytes()
871            .is_some_and(|limit| limit < BLOCK)
872        {
873            return Err(ArchiveError::new(ErrorKind::Limit)
874                .with_format("tar")
875                .with_context("in-flight limit is smaller than one tar block"));
876        }
877        if let Some(step) = self.sparse_hole(output)? {
878            return Ok(step);
879        }
880
881        let mut consumed = 0;
882        if self.needs_input && !input.is_empty() {
883            let accepted_limit = self.limits.in_flight_bytes().map_or(input.len(), |limit| {
884                limit
885                    .saturating_sub(self.source.buffered_len())
886                    .min(input.len())
887            });
888            if accepted_limit == 0 {
889                return Err(ArchiveError::new(ErrorKind::Limit)
890                    .with_format("tar")
891                    .with_context("in-flight buffer budget was exhausted"));
892            }
893            let accepted = self.source.feed(&input[..accepted_limit]);
894            if accepted > input.len() {
895                return Err(ArchiveError::new(ErrorKind::Protocol)
896                    .with_format("tar")
897                    .with_context("tar source over-consumed input"));
898            }
899            consumed = accepted;
900            self.needs_input = false;
901        }
902        if matches!(end, EndOfInput::End) && consumed == input.len() && !self.input_finished {
903            self.source.finish_input();
904            self.input_finished = true;
905        }
906
907        let event = self.source.pull_v2().map_err(ArchiveError::from)?;
908        let event = match event {
909            TarSourceEvent::NeedInput => {
910                self.needs_input = true;
911                if self.input_finished {
912                    return Err(ArchiveError::new(ErrorKind::Malformed)
913                        .with_format("tar")
914                        .with_context("unexpected end of tar input"));
915                }
916                DecodeEvent::NeedInput
917            },
918            TarSourceEvent::ArchiveMetadata(metadata) => DecodeEvent::ArchiveMetadata(metadata),
919            TarSourceEvent::Entry {
920                metadata,
921                sparse,
922                is_sparse,
923            } => {
924                let metadata = *metadata;
925                self.entries = self.entries.checked_add(1).ok_or_else(|| {
926                    ArchiveError::new(ErrorKind::Limit)
927                        .with_format("tar")
928                        .with_context("entry count overflow")
929                })?;
930                Self::check_limit_u64(
931                    self.entries,
932                    self.limits.entries(),
933                    "entry count exceeds limit",
934                )?;
935                if self
936                    .limits
937                    .path_bytes()
938                    .is_some_and(|limit| metadata.path().as_bytes().len() > limit)
939                {
940                    return Err(ArchiveError::new(ErrorKind::Limit)
941                        .with_format("tar")
942                        .with_entry(self.entries - 1, metadata.path().as_bytes())
943                        .with_context("entry path exceeds limit"));
944                }
945                let logical_size = metadata.size().unwrap_or(0);
946                Self::check_limit_u64(
947                    logical_size,
948                    self.limits.entry_bytes(),
949                    "entry size exceeds limit",
950                )?;
951                let metadata_cost = Self::entry_metadata_cost(&metadata)?;
952                self.metadata_bytes =
953                    self.metadata_bytes
954                        .checked_add(metadata_cost)
955                        .ok_or_else(|| {
956                            ArchiveError::new(ErrorKind::Limit)
957                                .with_format("tar")
958                                .with_context("metadata accounting overflow")
959                        })?;
960                if self
961                    .limits
962                    .metadata_bytes()
963                    .is_some_and(|limit| self.metadata_bytes > limit)
964                {
965                    return Err(ArchiveError::new(ErrorKind::Limit)
966                        .with_format("tar")
967                        .with_context("metadata exceeds configured limit"));
968                }
969                self.entry_bytes = 0;
970                self.sparse_active = is_sparse;
971                self.sparse = sparse;
972                self.sparse_index = 0;
973                self.logical_position = 0;
974                self.logical_size = logical_size;
975                DecodeEvent::Entry(metadata)
976            },
977            TarSourceEvent::Data(data) => {
978                if self.sparse_active {
979                    let extent = self.sparse.get(self.sparse_index).ok_or_else(|| {
980                        ArchiveError::new(ErrorKind::Malformed)
981                            .with_format("tar")
982                            .with_context("sparse payload exceeds declared extents")
983                    })?;
984                    let end = extent.offset.checked_add(extent.length).ok_or_else(|| {
985                        ArchiveError::new(ErrorKind::Malformed)
986                            .with_format("tar")
987                            .with_context("sparse extent overflow")
988                    })?;
989                    let next = self
990                        .logical_position
991                        .checked_add(data.len() as u64)
992                        .ok_or_else(|| {
993                            ArchiveError::new(ErrorKind::Limit)
994                                .with_format("tar")
995                                .with_context("sparse logical position overflow")
996                        })?;
997                    if self.logical_position < extent.offset || next > end {
998                        return Err(ArchiveError::new(ErrorKind::Malformed)
999                            .with_format("tar")
1000                            .with_context("sparse payload does not match extent map"));
1001                    }
1002                    self.logical_position = next;
1003                }
1004                let length = u64::try_from(data.len()).map_err(|_| {
1005                    ArchiveError::new(ErrorKind::Limit)
1006                        .with_format("tar")
1007                        .with_context("data window length exceeds u64")
1008                })?;
1009                self.entry_bytes = self.entry_bytes.checked_add(length).ok_or_else(|| {
1010                    ArchiveError::new(ErrorKind::Limit)
1011                        .with_format("tar")
1012                        .with_context("entry byte count overflow")
1013                })?;
1014                self.total_bytes = self.total_bytes.checked_add(length).ok_or_else(|| {
1015                    ArchiveError::new(ErrorKind::Limit)
1016                        .with_format("tar")
1017                        .with_context("decoded byte count overflow")
1018                })?;
1019                Self::check_limit_u64(
1020                    self.entry_bytes,
1021                    self.limits.entry_bytes(),
1022                    "entry bytes exceed limit",
1023                )?;
1024                Self::check_limit_u64(
1025                    self.total_bytes,
1026                    self.limits.decoded_total(),
1027                    "decoded bytes exceed limit",
1028                )?;
1029                DecodeEvent::Data(Chunk::new(data))
1030            },
1031            TarSourceEvent::EndEntry => {
1032                if self.sparse_active && self.logical_position != self.logical_size {
1033                    return Err(ArchiveError::new(ErrorKind::Malformed)
1034                        .with_format("tar")
1035                        .with_context("sparse payload ended before logical size"));
1036                }
1037                self.sparse_active = false;
1038                DecodeEvent::EndEntry
1039            },
1040            TarSourceEvent::Done => {
1041                self.done = true;
1042                DecodeEvent::Done
1043            },
1044        };
1045        Ok(DecodeStep {
1046            consumed,
1047            produced: 0,
1048            event,
1049        })
1050    }
1051}
1052
1053/// v0.2 sequential tar encoder.
1054///
1055/// Headers and alignment bytes are staged in a small metadata buffer; entry
1056/// payload bytes are copied directly from caller input to caller output.
1057#[derive(Debug)]
1058pub struct TarEncoder {
1059    limits: Limits,
1060    pending: Vec<u8>,
1061    pending_pos: usize,
1062    open: bool,
1063    entry_size: u64,
1064    remaining: u64,
1065    finishing: bool,
1066    done: bool,
1067    entries: u64,
1068    total_bytes: u64,
1069    sparse: Vec<SparseExtent>,
1070    sparse_index: usize,
1071    logical_position: u64,
1072}
1073
1074#[derive(Clone, Copy)]
1075struct HeaderView<'a> {
1076    kind: EntryKind,
1077    path: &'a [u8],
1078    mode: u32,
1079    uid: u64,
1080    gid: u64,
1081    modified: Option<Timestamp>,
1082    size: u64,
1083    link_target: Option<&'a [u8]>,
1084}
1085
1086impl<'a> HeaderView<'a> {
1087    fn from_metadata(metadata: &'a EntryMetadata, size: u64) -> Self {
1088        Self {
1089            kind: metadata.kind(),
1090            path: metadata.path().as_bytes(),
1091            mode: metadata
1092                .mode()
1093                .unwrap_or_else(|| default_mode(metadata.kind())),
1094            uid: metadata.owner().uid.unwrap_or(0),
1095            gid: metadata.owner().gid.unwrap_or(0),
1096            modified: metadata.times().modified,
1097            size,
1098            link_target: metadata.link_target().map(ArchivePath::as_bytes),
1099        }
1100    }
1101}
1102
1103impl TarEncoder {
1104    /// Creates a fresh encoder.
1105    #[must_use]
1106    pub const fn new(limits: Limits) -> Self {
1107        Self {
1108            limits,
1109            pending: Vec::new(),
1110            pending_pos: 0,
1111            open: false,
1112            entry_size: 0,
1113            remaining: 0,
1114            finishing: false,
1115            done: false,
1116            entries: 0,
1117            total_bytes: 0,
1118            sparse: Vec::new(),
1119            sparse_index: 0,
1120            logical_position: 0,
1121        }
1122    }
1123
1124    /// Queues archive-level global PAX metadata before the first entry.
1125    pub fn set_archive_metadata(
1126        &mut self,
1127        metadata: &ArchiveMetadata,
1128    ) -> core::result::Result<(), ArchiveError> {
1129        if self.open || self.entries != 0 || !self.pending.is_empty() || self.finishing || self.done
1130        {
1131            return Err(ArchiveError::new(ErrorKind::Protocol)
1132                .with_format("tar")
1133                .with_context("archive metadata must be set before the first entry"));
1134        }
1135        let mut records = Vec::new();
1136        for extension in metadata
1137            .extensions()
1138            .iter()
1139            .filter(|extension| extension.namespace() == "pax")
1140        {
1141            push_pax_record(&mut records, extension.key(), extension.value())
1142                .map_err(|error| ArchiveError::from(error).with_format("tar"))?;
1143        }
1144        if let Some(comment) = metadata.comment() {
1145            if !metadata.extensions().iter().any(|extension| {
1146                extension.namespace() == "pax" && extension.key() == b"LIBARCHIVE.comment"
1147            }) {
1148                push_pax_record(&mut records, b"LIBARCHIVE.comment", comment)
1149                    .map_err(|error| ArchiveError::from(error).with_format("tar"))?;
1150            }
1151        }
1152        if !records.is_empty() {
1153            write_pax_header(&mut self.pending, &records, b'g')
1154                .map_err(|error| ArchiveError::from(error).with_format("tar"))?;
1155            if self
1156                .limits
1157                .metadata_bytes()
1158                .is_some_and(|limit| self.pending.len() > limit)
1159            {
1160                self.pending.clear();
1161                return Err(ArchiveError::new(ErrorKind::Limit)
1162                    .with_format("tar")
1163                    .with_context("global PAX metadata exceeds configured limit"));
1164            }
1165        }
1166        Ok(())
1167    }
1168
1169    fn drain_pending(&mut self, output: &mut [u8]) -> usize {
1170        let remaining = self.pending.len().saturating_sub(self.pending_pos);
1171        let n = remaining.min(output.len());
1172        if n > 0 {
1173            output[..n].copy_from_slice(&self.pending[self.pending_pos..self.pending_pos + n]);
1174            self.pending_pos += n;
1175        }
1176        if self.pending_pos == self.pending.len() {
1177            self.pending.clear();
1178            self.pending_pos = 0;
1179        }
1180        n
1181    }
1182}
1183
1184impl ArchiveEncoder for TarEncoder {
1185    #[allow(clippy::too_many_lines)]
1186    fn step(
1187        &mut self,
1188        command: EncodeCommand<'_>,
1189        output: &mut [u8],
1190    ) -> core::result::Result<EncodeStep, ArchiveError> {
1191        if self.done {
1192            return match command {
1193                EncodeCommand::Finish => Ok(EncodeStep {
1194                    consumed: 0,
1195                    produced: 0,
1196                    status: EncodeStatus::Done,
1197                }),
1198                _ => Err(ArchiveError::new(ErrorKind::Protocol)
1199                    .with_format("tar")
1200                    .with_context("command supplied after finish")),
1201            };
1202        }
1203
1204        if !self.pending.is_empty() {
1205            let produced = self.drain_pending(output);
1206            if self.pending.is_empty() && self.finishing {
1207                self.done = true;
1208                return Ok(EncodeStep {
1209                    consumed: 0,
1210                    produced,
1211                    status: EncodeStatus::Done,
1212                });
1213            }
1214            return Ok(EncodeStep {
1215                consumed: 0,
1216                produced,
1217                status: if self.pending.is_empty() {
1218                    EncodeStatus::NeedCommand
1219                } else {
1220                    EncodeStatus::NeedOutput
1221                },
1222            });
1223        }
1224
1225        match command {
1226            EncodeCommand::BeginEntry(meta) => {
1227                if self.open {
1228                    return Err(ArchiveError::new(ErrorKind::Protocol)
1229                        .with_format("tar")
1230                        .with_context("previous entry is still open"));
1231                }
1232                let logical_size = meta.size().ok_or_else(|| {
1233                    ArchiveError::new(ErrorKind::SizeRequired)
1234                        .with_format("tar")
1235                        .with_context("tar requires a declared entry size")
1236                })?;
1237                if self
1238                    .limits
1239                    .path_bytes()
1240                    .is_some_and(|limit| meta.path().as_bytes().len() > limit)
1241                {
1242                    return Err(ArchiveError::new(ErrorKind::Limit)
1243                        .with_format("tar")
1244                        .with_context("entry path exceeds configured limit"));
1245                }
1246                if self
1247                    .limits
1248                    .entry_bytes()
1249                    .is_some_and(|limit| logical_size > limit)
1250                {
1251                    return Err(ArchiveError::new(ErrorKind::Limit)
1252                        .with_format("tar")
1253                        .with_context("entry size exceeds configured limit"));
1254                }
1255                let next_entries = self.entries.checked_add(1).ok_or_else(|| {
1256                    ArchiveError::new(ErrorKind::Limit)
1257                        .with_format("tar")
1258                        .with_context("entry count overflow")
1259                })?;
1260                if self
1261                    .limits
1262                    .entries()
1263                    .is_some_and(|limit| next_entries > limit)
1264                {
1265                    return Err(ArchiveError::new(ErrorKind::Limit)
1266                        .with_format("tar")
1267                        .with_context("entry count exceeds configured limit"));
1268                }
1269                let sparse = meta.sparse_extents();
1270                let is_sparse = !sparse.is_empty();
1271                let stored_size = if is_sparse {
1272                    let stored = sparse.iter().try_fold(0_u64, |total, extent| {
1273                        total.checked_add(extent.length).ok_or_else(|| {
1274                            ArchiveError::new(ErrorKind::Limit)
1275                                .with_format("tar")
1276                                .with_context("sparse stored size overflow")
1277                        })
1278                    })?;
1279                    validate_sparse_extents(sparse, logical_size, stored)
1280                        .map_err(|error| ArchiveError::from(error).with_format("tar"))?;
1281                    stored
1282                } else {
1283                    logical_size
1284                };
1285                let stored_meta = HeaderView::from_metadata(meta, stored_size);
1286                write_v2_header(&mut self.pending, meta, stored_meta, is_sparse)
1287                    .map_err(|error| ArchiveError::from(error).with_format("tar"))?;
1288                if self
1289                    .limits
1290                    .metadata_bytes()
1291                    .is_some_and(|limit| self.pending.len() > limit)
1292                {
1293                    return Err(ArchiveError::new(ErrorKind::Limit)
1294                        .with_format("tar")
1295                        .with_context("tar header metadata exceeds configured limit"));
1296                }
1297                self.entries = next_entries;
1298                self.remaining = logical_size;
1299                self.entry_size = stored_size;
1300                self.sparse.clear();
1301                self.sparse.extend_from_slice(sparse);
1302                self.sparse_index = 0;
1303                self.logical_position = 0;
1304                self.open = true;
1305                let produced = self.drain_pending(output);
1306                Ok(EncodeStep {
1307                    consumed: 1,
1308                    produced,
1309                    status: if self.pending.is_empty() {
1310                        EncodeStatus::NeedCommand
1311                    } else {
1312                        EncodeStatus::NeedOutput
1313                    },
1314                })
1315            },
1316            EncodeCommand::Data(input) => {
1317                if !self.open {
1318                    return Err(ArchiveError::new(ErrorKind::Protocol)
1319                        .with_format("tar")
1320                        .with_context("entry data supplied without an open entry"));
1321                }
1322                if input.len() as u64 > self.remaining {
1323                    return Err(ArchiveError::new(ErrorKind::Protocol)
1324                        .with_format("tar")
1325                        .with_context("entry data exceeds declared size"));
1326                }
1327                if input.is_empty() {
1328                    return Ok(EncodeStep {
1329                        consumed: 0,
1330                        produced: 0,
1331                        status: EncodeStatus::NeedCommand,
1332                    });
1333                }
1334                let (consumed, produced) = if self.sparse.is_empty() {
1335                    if output.is_empty() {
1336                        return Ok(EncodeStep {
1337                            consumed: 0,
1338                            produced: 0,
1339                            status: EncodeStatus::NeedOutput,
1340                        });
1341                    }
1342                    let count = input.len().min(output.len());
1343                    output[..count].copy_from_slice(&input[..count]);
1344                    self.logical_position += count as u64;
1345                    (count, count)
1346                } else {
1347                    write_sparse_data(
1348                        &self.sparse,
1349                        &mut self.sparse_index,
1350                        &mut self.logical_position,
1351                        input,
1352                        output,
1353                    )?
1354                };
1355                let next_total =
1356                    self.total_bytes
1357                        .checked_add(consumed as u64)
1358                        .ok_or_else(|| {
1359                            ArchiveError::new(ErrorKind::Limit)
1360                                .with_format("tar")
1361                                .with_context("encoded byte count overflow")
1362                        })?;
1363                if self
1364                    .limits
1365                    .decoded_total()
1366                    .is_some_and(|limit| next_total > limit)
1367                {
1368                    return Err(ArchiveError::new(ErrorKind::Limit)
1369                        .with_format("tar")
1370                        .with_context("encoded total exceeds configured limit"));
1371                }
1372                self.remaining -= consumed as u64;
1373                self.total_bytes = next_total;
1374                Ok(EncodeStep {
1375                    consumed,
1376                    produced,
1377                    status: if consumed == input.len() {
1378                        EncodeStatus::NeedCommand
1379                    } else {
1380                        EncodeStatus::NeedOutput
1381                    },
1382                })
1383            },
1384            EncodeCommand::EndEntry => {
1385                if !self.open {
1386                    return Err(ArchiveError::new(ErrorKind::Protocol)
1387                        .with_format("tar")
1388                        .with_context("end-entry supplied without an open entry"));
1389                }
1390                if self.remaining != 0 {
1391                    return Err(ArchiveError::new(ErrorKind::Protocol)
1392                        .with_format("tar")
1393                        .with_context("entry data is shorter than declared size"));
1394                }
1395                let pad = round_up(self.entry_size)
1396                    .map_err(|error| ArchiveError::from(error).with_format("tar"))?
1397                    - usize_of(self.entry_size)
1398                        .map_err(|error| ArchiveError::from(error).with_format("tar"))?;
1399                self.pending.resize(pad, 0);
1400                self.open = false;
1401                self.sparse.clear();
1402                let produced = self.drain_pending(output);
1403                Ok(EncodeStep {
1404                    consumed: 1,
1405                    produced,
1406                    status: if self.pending.is_empty() {
1407                        EncodeStatus::NeedCommand
1408                    } else {
1409                        EncodeStatus::NeedOutput
1410                    },
1411                })
1412            },
1413            EncodeCommand::Finish => {
1414                if self.open {
1415                    return Err(ArchiveError::new(ErrorKind::Protocol)
1416                        .with_format("tar")
1417                        .with_context("cannot finish with an open entry"));
1418                }
1419                self.pending.resize(2 * BLOCK, 0);
1420                self.finishing = true;
1421                let produced = self.drain_pending(output);
1422                if self.pending.is_empty() {
1423                    self.done = true;
1424                }
1425                Ok(EncodeStep {
1426                    consumed: 1,
1427                    produced,
1428                    status: if self.done {
1429                        EncodeStatus::Done
1430                    } else {
1431                        EncodeStatus::NeedOutput
1432                    },
1433                })
1434            },
1435        }
1436    }
1437}
1438
1439fn parse_source_header(
1440    hdr: &[u8],
1441    pending: &OwnedOverrides,
1442    global: &OwnedOverrides,
1443) -> Result<ParsedHeader> {
1444    let kind = kind_from_typeflag(hdr[O_TYPEFLAG]);
1445
1446    let name = cstr(field(hdr, F_NAME));
1447    let prefix = cstr(field(hdr, F_PREFIX));
1448    let is_ustar = field(hdr, F_MAGIC).starts_with(b"ustar");
1449
1450    let path = match pending.path.as_ref().or(global.path.as_ref()) {
1451        Some(path) => path.to_vec(),
1452        None => {
1453            if is_ustar && !prefix.is_empty() {
1454                join_prefix_name(prefix, name).into_owned()
1455            } else {
1456                name.to_vec()
1457            }
1458        },
1459    };
1460
1461    let link_target = match kind {
1462        EntryKind::Symlink | EntryKind::Hardlink => Some(
1463            pending
1464                .linkpath
1465                .as_ref()
1466                .or(global.linkpath.as_ref())
1467                .map_or_else(
1468                    || cstr(field(hdr, F_LINKNAME)).to_vec(),
1469                    |link| link.to_vec(),
1470                ),
1471        ),
1472        _ => None,
1473    };
1474
1475    let mtime = pending.mtime.or(global.mtime).or_else(|| {
1476        parse_numeric(field(hdr, F_MTIME))
1477            .ok()
1478            .map(|secs| Timestamp {
1479                secs: i64::try_from(secs).unwrap_or(i64::MAX),
1480                nanos: 0,
1481            })
1482    });
1483
1484    let uid = pending
1485        .uid
1486        .or(global.uid)
1487        .map_or_else(|| parse_numeric(field(hdr, F_UID)), Ok)?;
1488    let gid = pending
1489        .gid
1490        .or(global.gid)
1491        .map_or_else(|| parse_numeric(field(hdr, F_GID)), Ok)?;
1492    let mode = u32::try_from(parse_numeric(field(hdr, F_MODE))? & 0o7777).unwrap_or(0);
1493
1494    Ok(ParsedHeader {
1495        kind,
1496        path,
1497        mode,
1498        uid,
1499        gid,
1500        modified: mtime,
1501        link_target,
1502    })
1503}
1504
1505/// Merges the set fields of a freshly parsed (buffer-borrowing) `Overrides` into an
1506/// [`OwnedOverrides`], cloning each present byte string so it survives buffer compaction. Only set
1507/// fields overwrite, so a GNU `L`/`K` header and a PAX `x` header can both contribute to the same
1508/// next entry.
1509fn merge_owned(dst: &mut OwnedOverrides, src: Overrides<'_>) {
1510    if let Some(v) = src.path {
1511        dst.path = Some(Cow::Owned(v.into_owned()));
1512    }
1513    if let Some(v) = src.linkpath {
1514        dst.linkpath = Some(Cow::Owned(v.into_owned()));
1515    }
1516    if let Some(v) = src.size {
1517        dst.size = Some(v);
1518    }
1519    if let Some(v) = src.mtime {
1520        dst.mtime = Some(v);
1521    }
1522    if let Some(v) = src.atime {
1523        dst.atime = Some(v);
1524    }
1525    if let Some(v) = src.ctime {
1526        dst.ctime = Some(v);
1527    }
1528    if let Some(v) = src.birthtime {
1529        dst.birthtime = Some(v);
1530    }
1531    if let Some(v) = src.uid {
1532        dst.uid = Some(v);
1533    }
1534    if let Some(v) = src.gid {
1535        dst.gid = Some(v);
1536    }
1537    if let Some(v) = src.uname {
1538        dst.uname = Some(Cow::Owned(v.into_owned()));
1539    }
1540    if let Some(v) = src.gname {
1541        dst.gname = Some(Cow::Owned(v.into_owned()));
1542    }
1543    if let Some(v) = src.sparse_realsize {
1544        dst.sparse_realsize = Some(v);
1545    }
1546    dst.pax.extend(
1547        src.pax
1548            .into_iter()
1549            .map(|(key, value)| (Cow::Owned(key.into_owned()), Cow::Owned(value.into_owned()))),
1550    );
1551}
1552
1553// ── Helpers (free functions; they don't borrow self, avoiding borrow entanglement) ─────────────
1554
1555/// Slices out a fixed field from the header.
1556fn field(hdr: &[u8], (start, end): (usize, usize)) -> &[u8] {
1557    &hdr[start..end]
1558}
1559
1560/// Returns up to the first NUL (tar's C-string field).
1561fn cstr(field: &[u8]) -> &[u8] {
1562    let end = field.iter().position(|&b| b == 0).unwrap_or(field.len());
1563    &field[..end]
1564}
1565
1566/// Joins `prefix` + "/" + `name` (ustar's 255B path).
1567fn join_prefix_name<'a>(prefix: &'a [u8], name: &'a [u8]) -> Cow<'a, [u8]> {
1568    let mut joined = Vec::with_capacity(prefix.len() + 1 + name.len());
1569    joined.extend_from_slice(prefix);
1570    joined.push(b'/');
1571    joined.extend_from_slice(name);
1572    Cow::Owned(joined)
1573}
1574
1575/// Maps a typeflag to a typed kind. `'0'`/`'\0'`/`'7'` and unknown values are treated as regular files (tar convention).
1576fn kind_from_typeflag(tf: u8) -> EntryKind {
1577    match tf {
1578        b'5' => EntryKind::Dir,
1579        b'1' => EntryKind::Hardlink,
1580        b'2' => EntryKind::Symlink,
1581        b'3' => EntryKind::Char,
1582        b'4' => EntryKind::Block,
1583        b'6' => EntryKind::Fifo,
1584        _ => EntryKind::File,
1585    }
1586}
1587
1588/// Parses a tar numeric field (octal ASCII, or base-256 with the high bit set).
1589fn parse_numeric(field: &[u8]) -> Result<u64> {
1590    match field.first() {
1591        None => Ok(0),
1592        // base-256 (GNU extension, for large values). The high bit of the first byte is set.
1593        Some(&first) if first & 0x80 != 0 => {
1594            let mut val: u64 = u64::from(first & 0x7f);
1595            for &b in &field[1..] {
1596                // `checked_mul(256)` (not `checked_shl(8)`) is what actually detects value
1597                // overflow: shl only errors when the shift count reaches the bit width.
1598                val = val
1599                    .checked_mul(256)
1600                    .and_then(|v| v.checked_add(u64::from(b)))
1601                    .ok_or(Error::Malformed("base-256 numeric overflow"))?;
1602            }
1603            Ok(val)
1604        },
1605        // Octal ASCII. Leading/trailing spaces / NULs are ignored.
1606        _ => {
1607            let mut val: u64 = 0;
1608            let mut seen = false;
1609            for &b in field {
1610                match b {
1611                    b' ' | 0 => {
1612                        if seen {
1613                            break;
1614                        }
1615                    },
1616                    b'0'..=b'7' => {
1617                        val = val
1618                            .checked_mul(8)
1619                            .and_then(|v| v.checked_add(u64::from(b - b'0')))
1620                            .ok_or(Error::Malformed("octal numeric overflow"))?;
1621                        seen = true;
1622                    },
1623                    _ => return Err(Error::Malformed("invalid octal digit")),
1624                }
1625            }
1626            Ok(val)
1627        },
1628    }
1629}
1630
1631/// Verifies the header checksum (supports both unsigned and signed).
1632fn verify_checksum(hdr: &[u8]) -> Result<()> {
1633    let stored = parse_numeric(field(hdr, F_CHKSUM))?;
1634    let mut unsigned: u64 = 0;
1635    let mut signed: i64 = 0;
1636    for (i, &b) in hdr.iter().enumerate() {
1637        // The checksum field itself is computed as spaces (0x20).
1638        let byte = if (F_CHKSUM.0..F_CHKSUM.1).contains(&i) {
1639            b' '
1640        } else {
1641            b
1642        };
1643        unsigned += u64::from(byte);
1644        signed += i64::from(i8::from_ne_bytes([byte]));
1645    }
1646    if stored == unsigned || u64::try_from(signed).is_ok_and(|s| s == stored) {
1647        Ok(())
1648    } else {
1649        Err(Error::Malformed("header checksum mismatch"))
1650    }
1651}
1652
1653/// Converts u64 to usize (rejects oversized values on 32-bit platforms).
1654fn usize_of(v: u64) -> Result<usize> {
1655    usize::try_from(v).map_err(|_| Error::LimitExceeded("size exceeds usize"))
1656}
1657
1658/// Rounds a byte length up to the next block boundary.
1659fn round_up(size: u64) -> Result<usize> {
1660    let size = usize_of(size)?;
1661    let blocks = size
1662        .checked_add(BLOCK - 1)
1663        .ok_or(Error::Malformed("size overflow"))?
1664        / BLOCK;
1665    blocks
1666        .checked_mul(BLOCK)
1667        .ok_or(Error::Malformed("size overflow"))
1668}
1669
1670/// Parses a set of PAX extended records `"LEN KEY=VALUE\n"...` and applies them to `into`.
1671fn parse_pax<'a>(mut records: &'a [u8], into: &mut Overrides<'a>) -> Result<()> {
1672    while !records.is_empty() {
1673        // The head is the decimal total record length (including its own digits + space + KEY=VALUE + newline).
1674        let sp = records
1675            .iter()
1676            .position(|&b| b == b' ')
1677            .ok_or(Error::Malformed("pax: missing length separator"))?;
1678        let len = ascii_decimal(&records[..sp])?;
1679        // Need room for "LEN" + space + at least an empty body + newline, i.e. len >= sp + 2,
1680        // otherwise `record[sp + 1..len - 1]` below would have start > end and panic.
1681        if len < sp + 2 || len > records.len() {
1682            return Err(Error::Malformed("pax: bad record length"));
1683        }
1684        let record = &records[..len];
1685        // The KEY=VALUE part of "LEN KEY=VALUE\n" (excluding the trailing newline).
1686        let body = &record[sp + 1..record.len() - 1];
1687        let eq = body
1688            .iter()
1689            .position(|&b| b == b'=')
1690            .ok_or(Error::Malformed("pax: missing '='"))?;
1691        let key = &body[..eq];
1692        let value = &body[eq + 1..];
1693        apply_pax(key, value, into)?;
1694        records = &records[len..];
1695    }
1696    Ok(())
1697}
1698
1699/// Applies a single PAX key-value to the overrides (unknown keys are ignored).
1700fn apply_pax<'a>(key: &[u8], value: &'a [u8], into: &mut Overrides<'a>) -> Result<()> {
1701    into.pax
1702        .push((Cow::Owned(key.to_vec()), Cow::Borrowed(value)));
1703    match key {
1704        b"path" => into.path = Some(Cow::Borrowed(value)),
1705        b"linkpath" => into.linkpath = Some(Cow::Borrowed(value)),
1706        b"size" => into.size = Some(ascii_decimal_u64(value)?),
1707        b"uid" => into.uid = Some(ascii_decimal_u64(value)?),
1708        b"gid" => into.gid = Some(ascii_decimal_u64(value)?),
1709        b"mtime" => into.mtime = Some(parse_pax_time(value)?),
1710        b"atime" => into.atime = Some(parse_pax_time(value)?),
1711        b"ctime" => into.ctime = Some(parse_pax_time(value)?),
1712        b"LIBARCHIVE.creationtime" | b"SCHILY.birthtime" => {
1713            into.birthtime = Some(parse_pax_time(value)?);
1714        },
1715        b"uname" => into.uname = Some(Cow::Borrowed(value)),
1716        b"gname" => into.gname = Some(Cow::Borrowed(value)),
1717        b"GNU.sparse.size" | b"GNU.sparse.realsize" => {
1718            into.sparse_realsize = Some(ascii_decimal_u64(value)?);
1719        },
1720        _ => {},
1721    }
1722    Ok(())
1723}
1724
1725fn pax_sparse_extents(
1726    global: &OwnedOverrides,
1727    pending: &OwnedOverrides,
1728) -> Result<Vec<SparseExtent>> {
1729    let records = global.pax.iter().chain(&pending.pax);
1730    let mut map = None;
1731    let mut pairs = Vec::new();
1732    let mut offset = None;
1733    for (key, value) in records {
1734        match key.as_ref() {
1735            b"GNU.sparse.map" => map = Some(value.as_ref()),
1736            b"GNU.sparse.offset" => offset = Some(ascii_decimal_u64(value.as_ref())?),
1737            b"GNU.sparse.numbytes" => {
1738                let Some(offset) = offset.take() else {
1739                    return Err(Error::Malformed("GNU sparse length without offset"));
1740                };
1741                pairs.push(SparseExtent {
1742                    offset,
1743                    length: ascii_decimal_u64(value.as_ref())?,
1744                });
1745            },
1746            _ => {},
1747        }
1748    }
1749    if offset.is_some() {
1750        return Err(Error::Malformed("GNU sparse offset without length"));
1751    }
1752    if let Some(map) = map {
1753        pairs.clear();
1754        let mut fields = map.split(|byte| *byte == b',');
1755        while let Some(offset) = fields.next() {
1756            let length = fields
1757                .next()
1758                .ok_or(Error::Malformed("GNU sparse map has an odd field count"))?;
1759            pairs.push(SparseExtent {
1760                offset: ascii_decimal_u64(trim_ascii_space(offset))?,
1761                length: ascii_decimal_u64(trim_ascii_space(length))?,
1762            });
1763        }
1764    }
1765    Ok(pairs)
1766}
1767
1768fn parse_gnu_sparse_descriptors(
1769    block: &[u8],
1770    start: usize,
1771    count: usize,
1772) -> Result<Vec<SparseExtent>> {
1773    let mut extents = Vec::new();
1774    for index in 0..count {
1775        let offset = start
1776            .checked_add(index * 24)
1777            .ok_or(Error::Malformed("GNU sparse descriptor offset overflow"))?;
1778        let descriptor = block
1779            .get(offset..offset + 24)
1780            .ok_or(Error::Malformed("truncated GNU sparse descriptor"))?;
1781        let sparse_offset = parse_numeric(&descriptor[..12])?;
1782        let length = parse_numeric(&descriptor[12..])?;
1783        if length != 0 {
1784            extents.push(SparseExtent {
1785                offset: sparse_offset,
1786                length,
1787            });
1788        }
1789    }
1790    Ok(extents)
1791}
1792
1793fn validate_sparse_extents(
1794    extents: &[SparseExtent],
1795    logical_size: u64,
1796    stored_size: u64,
1797) -> Result<()> {
1798    let mut previous_end = 0_u64;
1799    let mut stored = 0_u64;
1800    for extent in extents {
1801        let end = extent
1802            .offset
1803            .checked_add(extent.length)
1804            .ok_or(Error::Malformed("GNU sparse extent overflow"))?;
1805        if extent.offset < previous_end || end > logical_size {
1806            return Err(Error::Malformed(
1807                "GNU sparse extents overlap or exceed logical size",
1808            ));
1809        }
1810        previous_end = end;
1811        stored = stored
1812            .checked_add(extent.length)
1813            .ok_or(Error::Malformed("GNU sparse stored size overflow"))?;
1814    }
1815    if stored != stored_size {
1816        return Err(Error::Malformed(
1817            "GNU sparse extent bytes differ from stored size",
1818        ));
1819    }
1820    Ok(())
1821}
1822
1823fn add_pax_metadata(
1824    mut builder: EntryMetadataBuilder,
1825    records: &[RawPaxRecord<'_>],
1826) -> EntryMetadataBuilder {
1827    for (key, value) in records {
1828        if let Some(name) = key.as_ref().strip_prefix(b"SCHILY.xattr.") {
1829            builder = builder.xattr(name.to_vec(), value.as_ref().to_vec());
1830        } else if matches!(
1831            key.as_ref(),
1832            b"SCHILY.acl.access"
1833                | b"SCHILY.acl.default"
1834                | b"LIBARCHIVE.acl.access"
1835                | b"LIBARCHIVE.acl.default"
1836        ) {
1837            builder = builder.acl(value.as_ref().to_vec());
1838        }
1839        builder = builder.extension(Extension::new(
1840            "pax",
1841            key.as_ref().to_vec(),
1842            value.as_ref().to_vec(),
1843        ));
1844    }
1845    builder
1846}
1847
1848fn trim_ascii_space(mut value: &[u8]) -> &[u8] {
1849    while value.first().is_some_and(u8::is_ascii_whitespace) {
1850        value = &value[1..];
1851    }
1852    while value.last().is_some_and(u8::is_ascii_whitespace) {
1853        value = &value[..value.len() - 1];
1854    }
1855    value
1856}
1857
1858/// Converts ASCII decimal to usize.
1859fn ascii_decimal(bytes: &[u8]) -> Result<usize> {
1860    if bytes.is_empty() {
1861        return Err(Error::Malformed("empty decimal"));
1862    }
1863    let mut val: usize = 0;
1864    for &b in bytes {
1865        if !b.is_ascii_digit() {
1866            return Err(Error::Malformed("invalid decimal digit"));
1867        }
1868        val = val
1869            .checked_mul(10)
1870            .and_then(|v| v.checked_add(usize::from(b - b'0')))
1871            .ok_or(Error::LimitExceeded("decimal overflow"))?;
1872    }
1873    Ok(val)
1874}
1875
1876fn ascii_decimal_u64(bytes: &[u8]) -> Result<u64> {
1877    if bytes.is_empty() {
1878        return Err(Error::Malformed("empty decimal"));
1879    }
1880    let mut value = 0_u64;
1881    for byte in bytes {
1882        if !byte.is_ascii_digit() {
1883            return Err(Error::Malformed("invalid decimal digit"));
1884        }
1885        value = value
1886            .checked_mul(10)
1887            .and_then(|current| current.checked_add(u64::from(*byte - b'0')))
1888            .ok_or(Error::LimitExceeded("decimal overflow"))?;
1889    }
1890    Ok(value)
1891}
1892
1893/// Parses a PAX mtime (`"secs"` or `"secs.nanos"`).
1894fn parse_pax_time(value: &[u8]) -> Result<Timestamp> {
1895    let negative = value.first() == Some(&b'-');
1896    let value = if negative { &value[1..] } else { value };
1897    let (secs_part, frac_part) = match value.iter().position(|&b| b == b'.') {
1898        Some(dot) => (&value[..dot], &value[dot + 1..]),
1899        None => (value, &b""[..]),
1900    };
1901    let magnitude = i64::try_from(ascii_decimal_u64(secs_part)?)
1902        .map_err(|_| Error::LimitExceeded("PAX timestamp exceeds i64"))?;
1903    // Convert up to 9 fractional digits into nanoseconds (pad with 0 if short, truncate if longer).
1904    let mut nanos: u32 = 0;
1905    for i in 0..9 {
1906        nanos *= 10;
1907        if let Some(&b) = frac_part.get(i) {
1908            if !b.is_ascii_digit() {
1909                return Err(Error::Malformed("invalid fractional second"));
1910            }
1911            nanos += u32::from(b - b'0');
1912        }
1913    }
1914    let (secs, nanos) = if negative && nanos != 0 {
1915        (
1916            magnitude
1917                .checked_neg()
1918                .and_then(|seconds| seconds.checked_sub(1))
1919                .ok_or(Error::LimitExceeded("PAX timestamp underflow"))?,
1920            1_000_000_000 - nanos,
1921        )
1922    } else if negative {
1923        (
1924            magnitude
1925                .checked_neg()
1926                .ok_or(Error::LimitExceeded("PAX timestamp underflow"))?,
1927            0,
1928        )
1929    } else {
1930        (magnitude, nanos)
1931    };
1932    Ok(Timestamp { secs, nanos })
1933}
1934
1935// ── Writer helpers (dual of the reader's field parsing) ────────────────────────────────────────
1936
1937#[allow(clippy::too_many_lines)]
1938fn write_v2_header(
1939    sink: &mut Vec<u8>,
1940    metadata: &EntryMetadata,
1941    stored: HeaderView<'_>,
1942    sparse: bool,
1943) -> Result<()> {
1944    let mut pax = Vec::new();
1945    for extension in metadata
1946        .extensions()
1947        .iter()
1948        .filter(|extension| extension.namespace() == "pax")
1949    {
1950        if sparse
1951            && matches!(
1952                extension.key(),
1953                b"GNU.sparse.map" | b"GNU.sparse.size" | b"GNU.sparse.realsize"
1954            )
1955        {
1956            continue;
1957        }
1958        push_pax_record(&mut pax, extension.key(), extension.value())?;
1959    }
1960    if let Some(user) = metadata.owner().user.as_deref() {
1961        push_pax_record(&mut pax, b"uname", user)?;
1962    }
1963    if let Some(group) = metadata.owner().group.as_deref() {
1964        push_pax_record(&mut pax, b"gname", group)?;
1965    }
1966    let times = metadata.times();
1967    for (key, timestamp) in [
1968        (b"mtime".as_slice(), times.modified),
1969        (b"atime".as_slice(), times.accessed),
1970        (b"ctime".as_slice(), times.changed),
1971        (b"LIBARCHIVE.creationtime".as_slice(), times.created),
1972    ] {
1973        if let Some(timestamp) = timestamp {
1974            let value = format_pax_timestamp(timestamp);
1975            push_pax_record(&mut pax, key, value.as_bytes())?;
1976        }
1977    }
1978    for (name, value) in metadata.xattrs() {
1979        let mut key = b"SCHILY.xattr.".to_vec();
1980        key.extend_from_slice(name);
1981        if !metadata
1982            .extensions()
1983            .iter()
1984            .any(|extension| extension.namespace() == "pax" && extension.key() == key)
1985        {
1986            push_pax_record(&mut pax, &key, value)?;
1987        }
1988    }
1989    if !metadata.acl().is_empty()
1990        && !metadata.extensions().iter().any(|extension| {
1991            extension.namespace() == "pax"
1992                && (extension.key().starts_with(b"SCHILY.acl.")
1993                    || extension.key().starts_with(b"LIBARCHIVE.acl."))
1994        })
1995    {
1996        for acl in metadata.acl() {
1997            push_pax_record(&mut pax, b"SCHILY.acl.access", acl)?;
1998        }
1999    }
2000    if let Some(comment) = metadata.comment() {
2001        push_pax_record(&mut pax, b"LIBARCHIVE.comment", comment)?;
2002    }
2003    if sparse {
2004        let mut map = String::new();
2005        for (index, extent) in metadata.sparse_extents().iter().enumerate() {
2006            if index != 0 {
2007                map.push(',');
2008            }
2009            map.push_str(&extent.offset.to_string());
2010            map.push(',');
2011            map.push_str(&extent.length.to_string());
2012        }
2013        push_pax_record(&mut pax, b"GNU.sparse.map", map.as_bytes())?;
2014        push_pax_record(
2015            &mut pax,
2016            b"GNU.sparse.realsize",
2017            metadata.size().unwrap_or(0).to_string().as_bytes(),
2018        )?;
2019    }
2020    if !pax.is_empty() {
2021        write_pax_header(sink, &pax, b'x')?;
2022    }
2023    write_header(sink, stored)?;
2024
2025    let header_start = sink
2026        .len()
2027        .checked_sub(BLOCK)
2028        .ok_or(Error::InvalidState("tar header was not emitted"))?;
2029    let header = sink
2030        .get_mut(header_start..)
2031        .ok_or(Error::InvalidState("tar header cannot be patched"))?;
2032    if let Some(user) = metadata.owner().user.as_deref() {
2033        copy_field(&mut header[F_UNAME.0..F_UNAME.1], user);
2034    }
2035    if let Some(group) = metadata.owner().group.as_deref() {
2036        copy_field(&mut header[F_GNAME.0..F_GNAME.1], group);
2037    }
2038    if matches!(metadata.kind(), EntryKind::Char | EntryKind::Block) {
2039        if let Some(device) = metadata.referenced_device() {
2040            put_octal(&mut header[F_DEVMAJOR.0..F_DEVMAJOR.1], device.major)?;
2041            put_octal(&mut header[F_DEVMINOR.0..F_DEVMINOR.1], device.minor)?;
2042        }
2043    }
2044    let header: &mut [u8; BLOCK] = header
2045        .try_into()
2046        .map_err(|_| Error::InvalidState("tar header patch length changed"))?;
2047    write_checksum(header)
2048}
2049
2050fn write_sparse_data(
2051    extents: &[SparseExtent],
2052    sparse_index: &mut usize,
2053    logical_position: &mut u64,
2054    input: &[u8],
2055    output: &mut [u8],
2056) -> core::result::Result<(usize, usize), ArchiveError> {
2057    let mut consumed = 0;
2058    let mut produced = 0;
2059    while consumed < input.len() {
2060        while extents.get(*sparse_index).is_some_and(|extent| {
2061            extent
2062                .offset
2063                .checked_add(extent.length)
2064                .is_some_and(|end| *logical_position == end)
2065        }) {
2066            *sparse_index += 1;
2067        }
2068        let Some(extent) = extents.get(*sparse_index) else {
2069            let count = input.len() - consumed;
2070            *logical_position = logical_position.checked_add(count as u64).ok_or_else(|| {
2071                ArchiveError::new(ErrorKind::Limit)
2072                    .with_format("tar")
2073                    .with_context("sparse logical position overflow")
2074            })?;
2075            consumed += count;
2076            break;
2077        };
2078        if *logical_position < extent.offset {
2079            let hole = extent.offset - *logical_position;
2080            let count =
2081                usize::try_from(hole.min((input.len() - consumed) as u64)).map_err(|_| {
2082                    ArchiveError::new(ErrorKind::Limit)
2083                        .with_format("tar")
2084                        .with_context("sparse hole exceeds address space")
2085                })?;
2086            *logical_position += count as u64;
2087            consumed += count;
2088            continue;
2089        }
2090        if produced == output.len() {
2091            break;
2092        }
2093        let end = extent.offset.checked_add(extent.length).ok_or_else(|| {
2094            ArchiveError::new(ErrorKind::Malformed)
2095                .with_format("tar")
2096                .with_context("sparse extent overflow")
2097        })?;
2098        let remaining = end.saturating_sub(*logical_position);
2099        let count = usize::try_from(remaining)
2100            .unwrap_or(usize::MAX)
2101            .min(input.len() - consumed)
2102            .min(output.len() - produced);
2103        output[produced..produced + count].copy_from_slice(&input[consumed..consumed + count]);
2104        *logical_position += count as u64;
2105        consumed += count;
2106        produced += count;
2107    }
2108    Ok((consumed, produced))
2109}
2110
2111fn push_pax_record(output: &mut Vec<u8>, key: &[u8], value: &[u8]) -> Result<()> {
2112    if key.is_empty() || key.iter().any(|byte| matches!(byte, b'=' | b'\n' | 0)) {
2113        return Err(Error::Malformed("invalid PAX key"));
2114    }
2115    let body_length = 1_usize
2116        .checked_add(key.len())
2117        .and_then(|length| length.checked_add(1))
2118        .and_then(|length| length.checked_add(value.len()))
2119        .and_then(|length| length.checked_add(1))
2120        .ok_or(Error::LimitExceeded("PAX record length overflow"))?;
2121    let mut length = body_length + 1;
2122    loop {
2123        let digits = length.to_string();
2124        let exact = body_length
2125            .checked_add(digits.len())
2126            .ok_or(Error::LimitExceeded("PAX record length overflow"))?;
2127        if exact == length {
2128            output.extend_from_slice(digits.as_bytes());
2129            output.push(b' ');
2130            output.extend_from_slice(key);
2131            output.push(b'=');
2132            output.extend_from_slice(value);
2133            output.push(b'\n');
2134            return Ok(());
2135        }
2136        length = exact;
2137    }
2138}
2139
2140fn write_pax_header(sink: &mut Vec<u8>, records: &[u8], typeflag: u8) -> Result<()> {
2141    let mut header = [0_u8; BLOCK];
2142    let name = b"././@PaxHeader";
2143    header[..name.len()].copy_from_slice(name);
2144    put_octal(&mut header[F_MODE.0..F_MODE.1], 0o644)?;
2145    put_octal(&mut header[F_UID.0..F_UID.1], 0)?;
2146    put_octal(&mut header[F_GID.0..F_GID.1], 0)?;
2147    put_octal(&mut header[F_SIZE.0..F_SIZE.1], records.len() as u64)?;
2148    put_octal(&mut header[F_MTIME.0..F_MTIME.1], 0)?;
2149    header[O_TYPEFLAG] = typeflag;
2150    header[F_MAGIC.0..F_MAGIC.0 + 5].copy_from_slice(b"ustar");
2151    header[263] = b'0';
2152    header[264] = b'0';
2153    write_checksum(&mut header)?;
2154    sink.extend_from_slice(&header);
2155    sink.extend_from_slice(records);
2156    write_zeros(sink, round_up(records.len() as u64)? - records.len())
2157}
2158
2159fn format_pax_timestamp(timestamp: Timestamp) -> String {
2160    if timestamp.nanos == 0 {
2161        return timestamp.secs.to_string();
2162    }
2163    if timestamp.secs < 0 {
2164        let integral = timestamp.secs.saturating_add(1).saturating_neg();
2165        let fraction = 1_000_000_000 - timestamp.nanos;
2166        alloc::format!("-{integral}.{fraction:09}")
2167    } else {
2168        alloc::format!("{}.{:09}", timestamp.secs, timestamp.nanos)
2169    }
2170}
2171
2172fn copy_field(field: &mut [u8], value: &[u8]) {
2173    field.fill(0);
2174    let count = field.len().min(value.len());
2175    field[..count].copy_from_slice(&value[..count]);
2176}
2177
2178/// Writes a full ustar header for `meta`, emitting GNU longname/longlink extension entries first
2179/// when the path or link target exceeds the 100-byte fields.
2180fn write_header(sink: &mut Vec<u8>, meta: HeaderView<'_>) -> Result<()> {
2181    let typeflag = typeflag_for(meta.kind)?;
2182
2183    if meta.path.len() > 100 {
2184        write_gnu_ext(sink, b'L', meta.path)?;
2185    }
2186    if let Some(link) = meta.link_target {
2187        if link.len() > 100 {
2188            write_gnu_ext(sink, b'K', link)?;
2189        }
2190    }
2191
2192    let mut h = [0u8; BLOCK];
2193    let name = &meta.path[..meta.path.len().min(100)];
2194    h[..name.len()].copy_from_slice(name);
2195    put_octal(&mut h[F_MODE.0..F_MODE.1], u64::from(meta.mode & 0o7777))?;
2196    put_octal(&mut h[F_UID.0..F_UID.1], meta.uid)?;
2197    put_octal(&mut h[F_GID.0..F_GID.1], meta.gid)?;
2198    put_octal(&mut h[F_SIZE.0..F_SIZE.1], meta.size)?;
2199    let mtime = meta
2200        .modified
2201        .map_or(0, |t| u64::try_from(t.secs.max(0)).unwrap_or(0));
2202    put_octal(&mut h[F_MTIME.0..F_MTIME.1], mtime)?;
2203    h[O_TYPEFLAG] = typeflag;
2204    if let Some(link) = meta.link_target {
2205        let l = &link[..link.len().min(100)];
2206        h[F_LINKNAME.0..F_LINKNAME.0 + l.len()].copy_from_slice(l);
2207    }
2208    h[F_MAGIC.0..F_MAGIC.0 + 5].copy_from_slice(b"ustar");
2209    h[263] = b'0';
2210    h[264] = b'0';
2211    write_checksum(&mut h)?;
2212    sink.extend_from_slice(&h);
2213    Ok(())
2214}
2215
2216/// Writes a GNU extension entry (`'L'` longname / `'K'` longlink) carrying `data` as its payload.
2217fn write_gnu_ext(sink: &mut Vec<u8>, flag: u8, data: &[u8]) -> Result<()> {
2218    let mut h = [0u8; BLOCK];
2219    let magic_name = b"././@LongLink";
2220    h[..magic_name.len()].copy_from_slice(magic_name);
2221    put_octal(&mut h[F_MODE.0..F_MODE.1], 0)?;
2222    put_octal(&mut h[F_UID.0..F_UID.1], 0)?;
2223    put_octal(&mut h[F_GID.0..F_GID.1], 0)?;
2224    let size = data.len() as u64 + 1; // include the trailing NUL
2225    put_octal(&mut h[F_SIZE.0..F_SIZE.1], size)?;
2226    put_octal(&mut h[F_MTIME.0..F_MTIME.1], 0)?;
2227    h[O_TYPEFLAG] = flag;
2228    h[F_MAGIC.0..F_MAGIC.0 + 5].copy_from_slice(b"ustar");
2229    h[263] = b'0';
2230    h[264] = b'0';
2231    write_checksum(&mut h)?;
2232    sink.extend_from_slice(&h);
2233
2234    sink.extend_from_slice(data);
2235    sink.push(0); // NUL terminator
2236    let total = data.len() + 1;
2237    write_zeros(sink, round_up(size)? - total)
2238}
2239
2240/// Computes and writes the ustar header checksum (6 octal digits + NUL + space).
2241fn write_checksum(h: &mut [u8; BLOCK]) -> Result<()> {
2242    for b in &mut h[F_CHKSUM.0..F_CHKSUM.1] {
2243        *b = b' ';
2244    }
2245    let sum: u64 = h.iter().map(|&b| u64::from(b)).sum();
2246    put_octal(&mut h[F_CHKSUM.0..F_CHKSUM.1 - 1], sum)?;
2247    h[F_CHKSUM.1 - 1] = b' ';
2248    Ok(())
2249}
2250
2251/// Writes `val` as a numeric field: zero-padded octal + NUL when it fits, otherwise the GNU
2252/// base-256 encoding (dual of [`parse_numeric`]'s two branches), so any value the reader accepts
2253/// can be written back.
2254fn put_octal(field: &mut [u8], val: u64) -> Result<()> {
2255    let n = field.len();
2256    // `n - 1` octal digits fit if the value needs at most that many.
2257    if fits_octal(val, n - 1) {
2258        field[n - 1] = 0;
2259        let mut v = val;
2260        for slot in field[..n - 1].iter_mut().rev() {
2261            *slot = b'0' + u8::try_from(v & 7).unwrap_or(0);
2262            v >>= 3;
2263        }
2264        Ok(())
2265    } else {
2266        put_base256(field, val)
2267    }
2268}
2269
2270/// Whether `val` fits in `digits` octal digits.
2271fn fits_octal(val: u64, digits: usize) -> bool {
2272    digits >= 22 || val < 1u64 << (3 * digits)
2273}
2274
2275/// Encodes `val` as GNU base-256: the first byte's high bit marks it, the value is stored
2276/// big-endian in the remaining bytes.
2277fn put_base256(field: &mut [u8], val: u64) -> Result<()> {
2278    let n = field.len();
2279    let capacity = n - 1; // bytes available after the marker byte
2280    let bytes = val.to_be_bytes();
2281    if capacity < 8 && bytes[..8 - capacity].iter().any(|&b| b != 0) {
2282        return Err(Error::Unsupported("tar: value too large for numeric field"));
2283    }
2284    field.fill(0);
2285    field[0] = 0x80;
2286    let take = capacity.min(8);
2287    field[n - take..].copy_from_slice(&bytes[8 - take..]);
2288    Ok(())
2289}
2290
2291/// Maps a typed [`EntryKind`] to a ustar typeflag byte.
2292fn typeflag_for(kind: EntryKind) -> Result<u8> {
2293    Ok(match kind {
2294        EntryKind::File => b'0',
2295        EntryKind::Dir => b'5',
2296        EntryKind::Symlink => b'2',
2297        EntryKind::Hardlink => b'1',
2298        EntryKind::Char => b'3',
2299        EntryKind::Block => b'4',
2300        EntryKind::Fifo => b'6',
2301        _ => return Err(Error::Unsupported("tar: unsupported entry kind for write")),
2302    })
2303}
2304
2305/// Appends `count` zero bytes to an encoder staging buffer.
2306fn write_zeros(sink: &mut Vec<u8>, count: usize) -> Result<()> {
2307    let new_len = sink
2308        .len()
2309        .checked_add(count)
2310        .ok_or(Error::LimitExceeded("tar output length overflow"))?;
2311    sink.resize(new_len, 0);
2312    Ok(())
2313}
2314
2315#[cfg(test)]
2316#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
2317mod tests {
2318    use super::*;
2319
2320    #[test]
2321    fn octal_and_base256() {
2322        assert_eq!(parse_numeric(b"0000644\0").unwrap(), 0o644);
2323        assert_eq!(parse_numeric(b"        ").unwrap(), 0);
2324        assert_eq!(parse_numeric(b"00000000144\0").unwrap(), 0o144);
2325        // base-256: 0x80 marker + big-endian 0x00000100 = 256.
2326        assert_eq!(parse_numeric(&[0x80, 0, 0, 1, 0]).unwrap(), 256);
2327    }
2328
2329    #[test]
2330    fn round_up_blocks() {
2331        assert_eq!(round_up(0).unwrap(), 0);
2332        assert_eq!(round_up(1).unwrap(), 512);
2333        assert_eq!(round_up(512).unwrap(), 512);
2334        assert_eq!(round_up(513).unwrap(), 1024);
2335    }
2336
2337    #[test]
2338    fn pax_time_fractional() {
2339        let t = parse_pax_time(b"1700000000.5").unwrap();
2340        assert_eq!(t.secs, 1_700_000_000);
2341        assert_eq!(t.nanos, 500_000_000);
2342    }
2343
2344    #[test]
2345    fn base256_overflow_is_rejected() {
2346        // 0x80 marker, then 0x01 followed by zeros = 1 << (8*n), which overflows u64.
2347        let field = [0x80, 0x01, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
2348        assert!(parse_numeric(&field).is_err());
2349    }
2350
2351    #[test]
2352    fn put_octal_falls_back_to_base256() {
2353        // 10 GiB does not fit the 12-byte octal size field, so base-256 is used and round-trips.
2354        let mut size = [0u8; 12];
2355        put_octal(&mut size, 10_737_418_240).unwrap();
2356        assert_eq!(size[0] & 0x80, 0x80, "base-256 marker set");
2357        assert_eq!(parse_numeric(&size).unwrap(), 10_737_418_240);
2358
2359        // A small value still uses plain octal.
2360        let mut mode = [0u8; 8];
2361        put_octal(&mut mode, 0o644).unwrap();
2362        assert_eq!(mode[0], b'0');
2363        assert_eq!(parse_numeric(&mode).unwrap(), 0o644);
2364
2365        // A uid beyond 7 octal digits round-trips via base-256.
2366        let mut uid = [0u8; 8];
2367        put_octal(&mut uid, 3_000_000).unwrap();
2368        assert_eq!(parse_numeric(&uid).unwrap(), 3_000_000);
2369    }
2370
2371    #[test]
2372    fn pax_malformed_record_does_not_panic() {
2373        let mut o = Overrides::default();
2374        // len == sp + 1: the off-by-one that used to panic in `record[sp + 1..len - 1]`.
2375        assert!(parse_pax(b"2 ", &mut o).is_err());
2376        assert!(parse_pax(b"1 ", &mut o).is_err());
2377        // A well-formed record still parses.
2378        assert!(parse_pax(b"11 path=ab\n", &mut o).is_ok());
2379        assert_eq!(o.path.as_deref(), Some(&b"ab"[..]));
2380    }
2381}