exarch-core 0.7.0

//! Test utilities for archive creation and validation.
//!
//! This module provides reusable helpers for creating in-memory test archives,
//! reducing code duplication across format-specific tests.
//!
//! # Panics
//!
//! All functions in this module may panic on I/O errors since they are
//! designed for test use only where panics are acceptable.

#![allow(clippy::unwrap_used)]

use std::io::Cursor;
use std::io::Write;

/// The host's relative path limit, written out per host and independent of the
/// production constant so a wrong value there is caught.
#[cfg(target_os = "linux")]
pub const HOST_PATH_LIMIT: usize = 4095;
#[cfg(target_os = "windows")]
pub const HOST_PATH_LIMIT: usize = 32767;
#[cfg(not(any(target_os = "linux", target_os = "windows")))]
pub const HOST_PATH_LIMIT: usize = 1023;

/// The most bytes a symlink target may take on the host, written out per host
/// like [`HOST_PATH_LIMIT`]: on Windows 4091 UTF-16 units of at most 3 bytes.
#[cfg(target_os = "windows")]
pub const HOST_SYMLINK_TARGET_BYTES: usize = 4091 * 3;
#[cfg(not(target_os = "windows"))]
pub const HOST_SYMLINK_TARGET_BYTES: usize = HOST_PATH_LIMIT;

/// Flips the low bit of the first byte of `marker` found in `bytes`, so stored
/// data fails its checksum.
pub fn flip_first(bytes: &mut [u8], marker: &[u8]) {
    let at = bytes
        .windows(marker.len())
        .position(|w| w == marker)
        .unwrap();
    bytes[at] ^= 0x01;
}

/// A relative path of exactly `len` bytes made of 100-byte components.
#[must_use]
pub fn path_of_len(len: usize) -> String {
    let mut parts = Vec::new();
    let mut left = len;
    while left > 0 {
        let take = left.min(100);
        parts.push("a".repeat(take));
        left = left.saturating_sub(take + 1);
    }
    parts.join("/")
}

/// Creates an in-memory TAR archive from a list of `(path, content)` entries.
///
/// All files are created with mode `0o644`.
#[must_use]
pub fn create_test_tar(entries: Vec<(&str, &[u8])>) -> Vec<u8> {
    let mut ar = tar::Builder::new(Vec::new());
    for (path, data) in entries {
        let mut header = tar::Header::new_gnu();
        header.set_size(data.len() as u64);
        header.set_mode(0o644);
        header.set_cksum();
        ar.append_data(&mut header, path, data).unwrap();
    }
    ar.into_inner().unwrap()
}

/// Creates an in-memory ZIP archive from a list of `(path, content)` entries.
///
/// Files are stored uncompressed with mode `0o644`.
#[must_use]
pub fn create_test_zip(entries: Vec<(&str, &[u8])>) -> Vec<u8> {
    use zip::write::SimpleFileOptions;
    use zip::write::ZipWriter;

    let buffer = Vec::new();
    let mut zip = ZipWriter::new(Cursor::new(buffer));

    let options = SimpleFileOptions::default()
        .compression_method(zip::CompressionMethod::Stored)
        .unix_permissions(0o644);

    for (path, data) in entries {
        zip.start_file(path, options).unwrap();
        zip.write_all(data).unwrap();
    }

    zip.finish().unwrap().into_inner()
}

/// Creates a raw in-memory ZIP with a single entry whose name is written
/// verbatim into the local file header and central directory, bypassing any
/// normalization that the `zip` crate applies via `start_file`. Use this to
/// craft entries with absolute paths or traversal sequences that
/// the `zip` crate's own writer refuses to produce.
#[must_use]
pub fn create_raw_zip_entry(entry_name: &str, content: &[u8]) -> Vec<u8> {
    use exarch_testkit::raw_zip::RawEntry;
    use exarch_testkit::raw_zip::RawZip;

    let entry = RawEntry {
        crc: 0,
        date: 0,
        ..RawEntry::stored(entry_name, content)
    };
    RawZip::new(vec![entry]).build().bytes
}

/// Builder for creating TAR test archives with files, directories, symlinks,
/// and hardlinks.
pub struct TarTestBuilder {
    builder: tar::Builder<Vec<u8>>,
}

impl TarTestBuilder {
    /// Creates a new TAR test builder.
    #[must_use]
    pub fn new() -> Self {
        Self {
            builder: tar::Builder::new(Vec::new()),
        }
    }

    /// Adds a regular file to the archive.
    #[must_use]
    pub fn add_file(mut self, path: &str, data: &[u8]) -> Self {
        let mut header = tar::Header::new_gnu();
        header.set_size(data.len() as u64);
        header.set_mode(0o644);
        header.set_cksum();
        self.builder.append_data(&mut header, path, data).unwrap();
        self
    }

    /// Adds a directory to the archive.
    #[must_use]
    pub fn add_directory(mut self, path: &str) -> Self {
        let mut header = tar::Header::new_gnu();
        header.set_size(0);
        header.set_mode(0o755);
        header.set_entry_type(tar::EntryType::Directory);
        header.set_cksum();
        self.builder
            .append_data(&mut header, path, std::io::empty())
            .unwrap();
        self
    }

    /// Builds and returns the TAR archive data.
    #[must_use]
    pub fn build(self) -> Vec<u8> {
        self.builder.into_inner().unwrap()
    }
}

impl Default for TarTestBuilder {
    fn default() -> Self {
        Self::new()
    }
}

/// Creates a raw ZIP archive containing a single symlink entry.
///
/// The ZIP spec encodes symlink targets as uncompressed file data, with
/// `S_IFLNK` mode bits stored in the high 16 bits of the central directory's
/// external attributes field. This bypasses the zip crate writer's
/// `unix_permissions()` path, which does not set external attributes reliably.
#[must_use]
pub fn create_zip_with_symlink(link_path: &str, target: &str) -> Vec<u8> {
    use exarch_testkit::raw_zip::RawEntry;
    use exarch_testkit::raw_zip::RawZip;
    use exarch_testkit::raw_zip::SYMLINK_MODE;

    let entry = RawEntry {
        date: 0,
        external_attributes: SYMLINK_MODE << 16,
        ..RawEntry::stored(link_path, target.as_bytes())
    };
    RawZip::new(vec![entry]).build().bytes
}

/// Builder for creating ZIP test archives with files, directories, and
/// symlinks.
pub struct ZipTestBuilder {
    zip: zip::ZipWriter<Cursor<Vec<u8>>>,
}

impl ZipTestBuilder {
    /// Creates a new ZIP test builder.
    #[must_use]
    pub fn new() -> Self {
        Self {
            zip: zip::ZipWriter::new(Cursor::new(Vec::new())),
        }
    }

    /// Adds a regular file to the archive.
    #[must_use]
    pub fn add_file(mut self, path: &str, data: &[u8]) -> Self {
        use zip::write::SimpleFileOptions;

        let options = SimpleFileOptions::default()
            .compression_method(zip::CompressionMethod::Stored)
            .unix_permissions(0o644);

        self.zip.start_file(path, options).unwrap();
        self.zip.write_all(data).unwrap();
        self
    }

    /// Adds a directory to the archive.
    #[must_use]
    pub fn add_directory(mut self, path: &str) -> Self {
        use zip::write::SimpleFileOptions;

        let options = SimpleFileOptions::default().unix_permissions(0o755);
        self.zip.add_directory(path, options).unwrap();
        self
    }

    /// Builds and returns the ZIP archive data.
    #[must_use]
    pub fn build(self) -> Vec<u8> {
        self.zip.finish().unwrap().into_inner()
    }
}

impl Default for ZipTestBuilder {
    fn default() -> Self {
        Self::new()
    }
}

/// Builds a 512-byte raw ustar TAR header block, bypassing `tar::Header`'s
/// safety checks (`set_path`/`set_link_name` reject NUL bytes and other
/// adversarial values) so fixtures for security regression tests can be
/// constructed byte-for-byte.
fn raw_tar_header(name: &[u8], size: usize, typeflag: u8) -> [u8; 512] {
    let mut h = [0u8; 512];
    let name_len = name.len().min(100);
    h[..name_len].copy_from_slice(&name[..name_len]);
    h[100..108].copy_from_slice(b"0000644\0");
    h[108..116].copy_from_slice(b"0000000\0");
    h[116..124].copy_from_slice(b"0000000\0");
    h[124..136].copy_from_slice(format!("{size:011o}\0").as_bytes());
    h[136..148].copy_from_slice(b"00000000000\0");
    h[156] = typeflag;
    h[257..263].copy_from_slice(b"ustar\0");
    h[263..265].copy_from_slice(b"00");
    h[148..156].copy_from_slice(b"        ");
    let checksum: u32 = h.iter().map(|&b| u32::from(b)).sum();
    h[148..156].copy_from_slice(format!("{checksum:06o}\0 ").as_bytes());
    h
}

/// Pads `data` to a 512-byte TAR block boundary and appends it to `out`.
fn pad_tar_block(out: &mut Vec<u8>, data: &[u8]) {
    out.extend_from_slice(data);
    let rem = data.len() % 512;
    if rem != 0 {
        out.extend(std::iter::repeat_n(0u8, 512 - rem));
    }
}

/// Builds a raw ustar-format TAR archive with a PAX extended header record
/// (`{pax_key}={pax_value}`) followed by one entry of type `typeflag` named
/// `entry_name` with body `data`.
///
/// Writes headers directly rather than through `tar::Header`'s safe setters,
/// so adversarial PAX overrides — e.g. an embedded NUL byte or an empty
/// value in a `path`/`linkpath` record — can be constructed for security
/// regression tests.
#[must_use]
pub fn tar_with_pax_record(
    pax_key: &str,
    pax_value: &[u8],
    entry_name: &[u8],
    typeflag: u8,
    data: &[u8],
) -> Vec<u8> {
    // Self-referential PAX record length: "<len> <key>=<value>\n".
    let base = pax_key.len() + pax_value.len() + 3;
    let mut len = base + 1;
    loop {
        let candidate = len.to_string().len() + base;
        if candidate == len {
            break;
        }
        len = candidate;
    }
    let mut record = format!("{len} {pax_key}=").into_bytes();
    record.extend_from_slice(pax_value);
    record.push(b'\n');

    let mut tar = Vec::new();
    tar.extend_from_slice(&raw_tar_header(b"PaxHeaders/entry", record.len(), b'x'));
    pad_tar_block(&mut tar, &record);
    tar.extend_from_slice(&raw_tar_header(entry_name, data.len(), typeflag));
    pad_tar_block(&mut tar, data);
    tar.extend(std::iter::repeat_n(0u8, 1024));
    tar
}

/// Builds a raw ustar-format TAR archive with a PAX `path` record embedding
/// `pax_path` (which may contain a NUL byte) as the effective path of a
/// regular-file entry with body `data`.
#[must_use]
pub fn tar_with_pax_nul_path(pax_path: &[u8], data: &[u8]) -> Vec<u8> {
    tar_with_pax_record("path", pax_path, b"ustar_name.txt", b'0', data)
}

/// Builds a raw ustar-format TAR archive with a PAX `linkpath` record
/// embedding `pax_linkpath` (which may be empty or contain a NUL byte) as
/// the effective link target of a symlink/hardlink entry. `typeflag` is
/// `b'2'` for a symlink entry, `b'1'` for a hardlink entry.
#[must_use]
pub fn tar_with_pax_linkpath(pax_linkpath: &[u8], typeflag: u8) -> Vec<u8> {
    tar_with_pax_record("linkpath", pax_linkpath, b"link_entry", typeflag, b"")
}

/// Builds a raw ustar-format TAR archive with a single regular-file entry
/// whose `name` field is `name_bytes`, which may not be valid UTF-8.
///
/// Writes the header directly rather than through `tar::Header::set_path`
/// (which requires a `Path`), so arbitrary non-UTF8 byte sequences can be
/// used as the entry name for extractability regression tests.
#[must_use]
pub fn tar_with_nonutf8_name(name_bytes: &[u8], data: &[u8]) -> Vec<u8> {
    let mut tar = Vec::new();
    tar.extend_from_slice(&raw_tar_header(name_bytes, data.len(), b'0'));
    pad_tar_block(&mut tar, data);
    tar.extend(std::iter::repeat_n(0u8, 1024));
    tar
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::raw_zip::RawEntry;
    use crate::raw_zip::RawZip;

    #[test]
    fn test_create_test_tar() {
        let tar_data = create_test_tar(vec![("file.txt", b"hello")]);
        assert!(!tar_data.is_empty());
    }

    #[test]
    fn test_create_test_zip() {
        let zip_data = create_test_zip(vec![("file.txt", b"hello")]);
        assert!(!zip_data.is_empty());
    }

    #[test]
    fn test_tar_builder() {
        let tar_data = TarTestBuilder::new()
            .add_file("file.txt", b"content")
            .add_directory("dir/")
            .build();
        assert!(!tar_data.is_empty());
    }

    #[test]
    fn test_zip_builder() {
        let zip_data = ZipTestBuilder::new()
            .add_file("file.txt", b"content")
            .add_directory("dir/")
            .build();
        assert!(!zip_data.is_empty());
    }

    /// ZIP archives whose structure different readers interpret differently.
    fn structural_zip_seeds() -> Vec<(&'static str, RawZip)> {
        let hidden = RawZip::new(vec![RawEntry::stored("evil.sh", b"echo pwned\n")]).build();
        let gap = hidden.bytes[..hidden.directory_start].to_vec();

        let mut hidden_local = RawZip::new(vec![RawEntry::stored("benign.txt", b"hello")]);
        hidden_local.before_directory.clone_from(&gap);
        let mut uncounted = RawZip::new(vec![
            RawEntry::stored("benign.txt", b"hello"),
            RawEntry::stored("hidden.sh", b"echo pwned\n"),
        ]);
        uncounted.end_count = Some(1);
        let mut descriptor_gap = RawZip::new(vec![
            RawEntry::stored("a.txt", b"hello").with_descriptor(true, true),
        ]);
        descriptor_gap.before_directory = gap;

        vec![
            (
                "header-name-mismatch.bin",
                RawZip::new(vec![
                    RawEntry::stored("cron_worker.sh", b"payload")
                        .with_central_name("doc_report.pdf"),
                ]),
            ),
            (
                "duplicate-names.bin",
                RawZip::new(vec![
                    RawEntry::stored("a.txt", b"first"),
                    RawEntry::stored("a.txt", b"EVIL"),
                ]),
            ),
            ("hidden-local-header.bin", hidden_local),
            ("uncounted-central-record.bin", uncounted),
            ("descriptor-gap.bin", descriptor_gap),
        ]
    }

    /// Dumps the adversarial archives built by this module's generators into
    /// `fuzz/seeds/<target>/` so `fuzz/seed-corpus.sh` can assemble them into
    /// the fuzz corpus. `test_utils` is `pub(crate)`, so this is the only
    /// place that can reach these generators without widening crate
    /// visibility for a dev-only need. Not run by default; invoked via
    /// `cargo test -p exarch-core --lib -- --ignored dump_fuzz_seeds`.
    #[test]
    #[ignore = "generates fuzz/seeds/ on demand; not part of the default test run"]
    fn dump_fuzz_seeds() {
        let repo_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .parent()
            .and_then(std::path::Path::parent)
            .unwrap();
        let seeds = repo_root.join("fuzz/seeds");

        let write_seed = |target: &str, name: &str, data: &[u8]| {
            let dir = seeds.join(target);
            std::fs::create_dir_all(&dir).unwrap();
            std::fs::write(dir.join(name), data).unwrap();
        };

        write_seed(
            "tar",
            "basic.bin",
            &create_test_tar(vec![("file.txt", b"hello world")]),
        );
        write_seed(
            "tar",
            "builder.bin",
            &TarTestBuilder::new()
                .add_file("file.txt", b"content")
                .add_directory("dir/")
                .build(),
        );
        write_seed(
            "tar",
            "pax-record.bin",
            &tar_with_pax_record(
                "path",
                b"pax/override/path.txt",
                b"ustar_name.txt",
                b'0',
                b"data",
            ),
        );
        write_seed(
            "tar",
            "pax-nul-path.bin",
            &tar_with_pax_nul_path(b"path/with\0nul", b"data"),
        );
        write_seed(
            "tar",
            "pax-linkpath-symlink.bin",
            &tar_with_pax_linkpath(b"../../etc/passwd", b'2'),
        );
        write_seed(
            "tar",
            "pax-linkpath-hardlink.bin",
            &tar_with_pax_linkpath(b"../../etc/passwd", b'1'),
        );
        write_seed(
            "tar",
            "nonutf8-name.bin",
            &tar_with_nonutf8_name(&[0xff, 0xfe, b'/', b'x'], b"data"),
        );

        write_seed(
            "zip",
            "basic.bin",
            &create_test_zip(vec![("file.txt", b"hello world")]),
        );
        write_seed(
            "zip",
            "builder.bin",
            &ZipTestBuilder::new()
                .add_file("file.txt", b"content")
                .add_directory("dir/")
                .build(),
        );
        write_seed(
            "zip",
            "raw-traversal.bin",
            &create_raw_zip_entry("../../etc/passwd", b"data"),
        );
        write_seed(
            "zip",
            "symlink-escape.bin",
            &create_zip_with_symlink("link", "../../etc/passwd"),
        );

        for (name, zip) in structural_zip_seeds() {
            write_seed("zip", name, &zip.build().bytes);
        }
    }
}