slpc 0.3.11

// Reading a container.
//
// Author: David M. Anderson
// Built with AI assistance (Claude, Anthropic)

use std::io::{Read, Seek};
use std::path::Path;

use toml_edit::DocumentMut;
use zip::ZipArchive;

use crate::error::{EntryKind, Error, Malformed, Result, Unsupported};
use crate::{central, metadata, name, Limits, METADATA_MEMBER, VERSION};

/// One member of the central directory, as far as this library cares.
///
/// Collected in a single pass at open time because `ZipArchive` lends out one
/// member at a time and re-reading the directory per lookup would be the same
/// work done repeatedly. The rewrite path walks the same list to copy members
/// through in the order they arrived.
pub(crate) struct Entry {
    raw: Vec<u8>,
    kind: EntryKind,
    /// The member's uncompressed length, kept from the same pass that read the
    /// name and the kind. It is eight bytes per member against a lookup that
    /// would otherwise need the archive, and needing the archive is what would
    /// make asking a member's size require `&mut`.
    size: u64,
    /// The CRC-32 the archive records for the member, kept from the same pass
    /// as the name and the size. Here for the reason `size` is: the central
    /// directory has it, and going back to the archive is what would make
    /// asking need `&mut`.
    crc: u32,
    /// Whether general purpose bit 0 is set on the member.
    encrypted: bool,
    /// The compression method's number, when it is one this build carries no
    /// decoder for, and `None` for every method it can decode. Kept for the
    /// same reason as `size`: the answer is in the central directory, and going
    /// back to the archive for it is what would need `&mut`.
    unsupported_method: Option<u16>,
}

/// Collect what the central directory says about every member, in one pass.
///
/// `by_index_raw` rather than `by_index`: the latter refuses a member whose
/// compression method this build was not given, which is exactly the member
/// that has to survive being listed and copied. Nothing here decompresses
/// anything.
fn entries_of<R: Read + Seek>(archive: &mut ZipArchive<R>) -> Result<Vec<Entry>> {
    let mut entries = Vec::with_capacity(archive.len());
    for i in 0..archive.len() {
        let f = archive.by_index_raw(i)?;
        entries.push(Entry {
            raw: f.name_raw().to_owned(),
            kind: EntryKind::from_mode(f.unix_mode()),
            size: f.size(),
            crc: f.crc32(),
            encrypted: f.encrypted(),
            unsupported_method: unsupported_method(f.compression()),
        });
    }
    Ok(entries)
}

/// The method's number, when it is one this build carries no decoder for.
///
/// The ZIP crate gates each `CompressionMethod` variant behind one of its own
/// features, so a method the build was not given arrives as `Unsupported`
/// carrying the number the archive stated. That is the test the crate itself
/// makes before it builds a decoder, which is what keeps
/// [`Container::check_payload_readable`] from answering differently from
/// extraction.
#[allow(deprecated)]
fn unsupported_method(method: zip::CompressionMethod) -> Option<u16> {
    match method {
        zip::CompressionMethod::Unsupported(id) => Some(id),
        _ => None,
    }
}

/// How many members of the central directory carry a given name.
///
/// A name is either absent, borne by one member, or borne by several, and SPEC
/// 2.1 has a different thing to say about each. Which error a caller raises
/// depends on which name it was looking for, so this reports and does not
/// decide.
pub(crate) enum Located {
    One(usize),
    None,
    Several(usize),
}

/// Find the one archive member whose name decodes to `want`.
///
/// Counting happens over the central directory read in `central.rs`, because
/// `ZipArchive` keys its own directory by name and cannot see a duplicate. The
/// index returned is the archive's, found by the name's raw bytes.
///
/// Matching on raw bytes is exact here, and only because the count ran first.
/// Two members can carry one byte string and decode differently only when their
/// flag bits differ over non-ASCII bytes; over ASCII both branches agree, which
/// would make them duplicates and stop this before it began.
pub(crate) fn locate(entries: &[Entry], names: &[central::Recorded], want: &str) -> Located {
    let mut matched = names.iter().filter(|n| n.decodes_to(want));
    let Some(first) = matched.next() else {
        return Located::None;
    };
    let count = 1 + matched.count();
    if count > 1 {
        return Located::Several(count);
    }
    // The archive and the central directory are the same directory, so an entry
    // counted there is an entry here.
    match entries.iter().position(|e| e.raw == first.bytes) {
        Some(i) => Located::One(i),
        None => Located::None,
    }
}

/// A slipcase container, open for reading.
///
/// Reading needs `Read + Seek`, because a ZIP's central directory is at the end
/// of the file and there is no way to find a member without first finding that.
pub struct Container<R> {
    pub(crate) archive: ZipArchive<R>,
    pub(crate) entries: Vec<Entry>,
    /// Every central directory name, duplicates included, for the counting the
    /// ZIP crate cannot do. Kept so a rewrite can check the metadata it is
    /// about to write against the same archive.
    pub(crate) names: Vec<central::Recorded>,
    pub(crate) metadata_index: usize,
    doc: DocumentMut,
    bytes: Vec<u8>,
    version: String,
    payload_file: String,
    /// `None` when `slipcase_version` is one this build does not implement, in
    /// which case the payload was never located. See [`Container::payload`].
    pub(crate) payload_index: Option<usize>,
}

impl Container<std::fs::File> {
    /// Open a container from a path.
    ///
    /// Named for [`std::fs::File::open`] rather than for symmetry with the
    /// packing side, because that convention is the one a reader already knows.
    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
        Self::read(std::fs::File::open(path)?)
    }

    /// Open a container from a path, under bounds of the caller's choosing.
    ///
    /// [`Container::open`] with [`Limits::default`].
    pub fn open_with<P: AsRef<Path>>(path: P, limits: Limits) -> Result<Self> {
        Self::read_with(std::fs::File::open(path)?, limits)
    }
}

impl<R: Read + Seek> Container<R> {
    /// Read a container from anything seekable.
    ///
    /// Reads the central directory and the metadata member, and nothing else.
    /// The payload is not decompressed and not read, so a container whose
    /// payload uses a compression method this build lacks still opens.
    pub fn read(reader: R) -> Result<Self> {
        Self::read_with(reader, Limits::default())
    }

    /// Read a container, spending no more on the metadata member than `limits`
    /// allows.
    ///
    /// SPEC 6: identifying a container means decompressing and parsing that
    /// member, so a reader commits the memory before it knows whether the file
    /// was a container. A member over the bound is
    /// [`Unsupported::MetadataTooLarge`], which is
    /// [`Undetermined`](crate::Verdict::Undetermined) and not a verdict against
    /// the file.
    pub fn read_with(mut reader: R, limits: Limits) -> Result<Self> {
        // Count names before the archive is built, because `ZipArchive` keys
        // its directory by name and two members sharing one arrive as a single
        // entry. SPEC 2.1 requires exactly one of each named member, which is
        // a question the crate cannot be asked.
        let names = central::names(&mut reader)?;
        reader.rewind()?;

        let mut archive = ZipArchive::new(reader)?;

        let entries = entries_of(&mut archive)?;

        let meta_index = match locate(&entries, &names, METADATA_MEMBER) {
            Located::One(i) => i,
            Located::None => return Err(Malformed::NoMetadataMember.into()),
            Located::Several(n) => return Err(Malformed::DuplicateMetadataMember(n).into()),
        };

        // Buffering here is deliberate and is not the rule the payload lives
        // under: every caller of this library wants all of this member. What it
        // is not is small, which this said until it was measured — see
        // `read_metadata_member`.
        let bytes =
            read_metadata_member(&mut archive, meta_index, entries[meta_index].size, limits)?;

        let (doc, keys) = metadata::parse(&bytes)?;
        let crate::metadata::Keys {
            version,
            payload_file,
        } = keys;

        // Everything past this point is a rule stated by version 1.0 of the
        // specification. A container declaring a version this build does not
        // implement is parsed and reported and no further, because SPEC 3
        // forbids assuming its rules are the ones written here.
        let payload_index = if version == VERSION {
            Some(locate_payload(&entries, &names, &payload_file)?)
        } else {
            None
        };

        Ok(Self {
            archive,
            entries,
            names,
            metadata_index: meta_index,
            doc,
            bytes,
            version,
            payload_file,
            payload_index,
        })
    }

    /// The `slipcase_version` as written.
    ///
    /// This and [`Container::payload_name`] describe the container as it was
    /// read. Editing the document through [`Container::metadata_mut`] does not
    /// change them; the edited document is validated when it is written back.
    pub fn version(&self) -> &str {
        &self.version
    }

    /// The value of `payload.file`.
    pub fn payload_name(&self) -> &str {
        &self.payload_file
    }

    /// The whole TOML document, unknown keys intact.
    pub fn metadata(&self) -> &DocumentMut {
        &self.doc
    }

    /// The whole TOML document, to be changed in place.
    pub fn metadata_mut(&mut self) -> &mut DocumentMut {
        &mut self.doc
    }

    /// The metadata member as stored, byte for byte.
    ///
    /// For a caller who wants a different parser, a schema validator, or a
    /// hash. Nothing else here promises to reproduce these bytes: TOML defines
    /// no canonical serialization, so re-serializing the document is not the
    /// same operation.
    pub fn metadata_bytes(&self) -> &[u8] {
        &self.bytes
    }

    /// Whether `slipcase_version` is one this build implements.
    pub(crate) fn version_is_recognised(&self) -> bool {
        self.payload_index.is_some()
    }

    /// The payload's length, uncompressed.
    ///
    /// Read from the central directory, which already carries it, so this
    /// decompresses nothing and costs no more than asking. For a caller sizing
    /// a progress bar, deciding whether a payload fits somewhere, or reporting
    /// what is in a container without extracting it.
    ///
    /// Fails the way [`Container::payload`] does for a container declaring a
    /// version this build does not implement, since in that case the payload
    /// was never located.
    ///
    /// Borrows shared rather than mutably, unlike [`Container::payload`], so it
    /// composes with [`Container::payload_name`] in one expression — which is
    /// how anything reporting what is in a container asks the question:
    ///
    /// ```no_run
    /// # fn main() -> slpc::Result<()> {
    /// let c = slpc::Container::open("report.pdf.slpc")?;
    /// println!("{} is {} bytes", c.payload_name(), c.payload_size()?);
    /// # Ok(())
    /// # }
    /// ```
    pub fn payload_size(&self) -> Result<u64> {
        let i = self
            .payload_index
            .ok_or_else(|| Unsupported::Version(self.version.clone()))?;
        Ok(self.entries[i].size)
    }

    /// The CRC-32 the archive records for the payload.
    ///
    /// Read from the central directory alongside the size, so this decompresses
    /// nothing and costs no more than asking.
    ///
    /// **A ZIP field and not a slipcase one.** SPEC 5 defines no checksum or
    /// fixity key, and this is not one arriving by another road. It is the
    /// value a ZIP writer computes over a member as it stores it and a ZIP
    /// reader verifies on the way back out, and it is recorded in every
    /// container because it is recorded in every archive. What it answers is
    /// whether a file is the one that came out of this container. What it does
    /// not answer is whether the container is the one somebody sent, and a
    /// caller wanting that needs something this crate does not offer and the
    /// specification does not define.
    ///
    /// For a caller holding a payload it extracted earlier and asking whether
    /// it has been edited since:
    ///
    /// ```no_run
    /// # fn main() -> slpc::Result<()> {
    /// let c = slpc::Container::open("report.pdf.slpc")?;
    /// let extracted = std::fs::read("report.pdf")?;
    /// if crc32fast::hash(&extracted) != c.payload_crc()? {
    ///     println!("the copy on disk is not the one in the container");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// [`Unsupported::Version`] where the container declares a version this
    /// build does not implement, since its payload was never located. Same
    /// refusal, and for the same reason, as [`Container::payload_size`].
    pub fn payload_crc(&self) -> Result<u32> {
        let i = self
            .payload_index
            .ok_or_else(|| Unsupported::Version(self.version.clone()))?;
        Ok(self.entries[i].crc)
    }

    /// The permission bits the archive records for the payload, where it
    /// records any.
    ///
    /// `Ok(None)` where the container says nothing, which is the common case:
    /// an archive written on a system with no notion of a Unix mode records no
    /// high bits, and a reader has no business inventing some. The ZIP crate's
    /// own `unix_mode` does invent them — `S_IFREG | 0o664` for a DOS archive,
    /// `0o444` where the read-only bit is set — so this reads the external
    /// attributes off the central directory instead and answers only when the
    /// high sixteen bits carry something.
    ///
    /// The file-type bits are masked off; [`EntryKind`] is where those are
    /// answered, and SPEC 3 already limits a payload to a regular file entry.
    /// What comes back is the permission bits alone, `0o7777` at the widest.
    ///
    /// **This is for saying, not for applying.** SPEC 3 requires that an
    /// extracted payload get the permissions a newly created file would
    /// ordinarily receive, and forbids applying what the archive recorded: a
    /// conformant container may record setuid, and honouring it would put a
    /// setuid file on disk. [`Destination`](crate::Destination) is where the
    /// writing side of that lives, and it never consults this. What this is
    /// for is telling somebody what they are holding — that a payload was
    /// executable where it came from, and that the copy they are about to get
    /// will not be.
    ///
    /// ```no_run
    /// # fn main() -> slpc::Result<()> {
    /// let c = slpc::Container::open("build.sh.slpc")?;
    /// if c.payload_mode()?.is_some_and(|m| m & 0o111 != 0) {
    ///     println!("the payload is an executable file");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// [`Unsupported::Version`] where the container declares a version this
    /// build does not implement, since its payload was never located. Same
    /// refusal, and for the same reason, as [`Container::payload_size`].
    pub fn payload_mode(&self) -> Result<Option<u32>> {
        let i = self
            .payload_index
            .ok_or_else(|| Unsupported::Version(self.version.clone()))?;
        // Matched on the raw name rather than by index. The two vectors are the
        // same directory, but the ZIP crate keys its own by name and collapses
        // duplicates, so the indices agree only in the absence of one — and
        // uniqueness having been established is exactly what a payload index
        // means, so the match is unambiguous here and would not be anywhere
        // that ran earlier.
        let raw = &self.entries[i].raw;
        let attributes = self
            .names
            .iter()
            .find(|n| n.bytes == *raw)
            .map_or(0, |n| n.external_attributes);
        let mode = attributes >> 16;
        Ok((mode != 0).then_some(mode & 0o7777))
    }

    /// Whether this build can decode the payload, and what stops it when it
    /// cannot.
    ///
    /// Read off the central directory entry collected when the container was
    /// opened, so this decompresses nothing, reads nothing further, and
    /// borrows shared. It is for a program that has to commit to extraction
    /// before performing it: a button offering to open the payload, a menu
    /// item, a plan stating what it is about to do. The alternative is to
    /// attempt the extraction and read the answer off the failure.
    ///
    /// The three refusals are [`Container::payload`]'s own, in the order it
    /// meets them. A container declaring a version this build does not
    /// implement never had its payload located, so that answer comes first. An
    /// encrypted member is next, because a member can be encrypted and
    /// compressed at once and the archive is asked about encryption first. A
    /// compression method this build carries no decoder for is last.
    ///
    /// None of the three makes the container non-conformant. SPEC 2.5 puts
    /// compression and encryption outside the conformance question, so this is
    /// a capability query and not a verdict: [`validate`](crate::validate)
    /// answers that one, and it reports such a container conformant.
    ///
    /// **`Ok` is not a promise that extraction will succeed.** It says this
    /// build knows how to decode the member. The bytes can still be truncated,
    /// fail their checksum, or fail to read, and [`Container::payload`] and the
    /// stream it returns report that if it happens.
    ///
    /// ```no_run
    /// # fn main() -> slpc::Result<()> {
    /// let c = slpc::Container::open("report.pdf.slpc")?;
    /// if let Err(why) = c.check_payload_readable() {
    ///     println!("{} cannot be opened here: {why}", c.payload_name());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn check_payload_readable(&self) -> std::result::Result<(), Unsupported> {
        let i = self
            .payload_index
            .ok_or_else(|| Unsupported::Version(self.version.clone()))?;
        if self.entries[i].encrypted {
            return Err(Unsupported::Encrypted);
        }
        if let Some(m) = self.entries[i].unsupported_method {
            return Err(Unsupported::Compression(m));
        }
        Ok(())
    }

    /// The payload, as a stream.
    ///
    /// Never buffered whole. A payload is a file of arbitrary size, and a
    /// library that handed back a `Vec<u8>` would be deciding for its caller
    /// that the file fits in memory.
    pub fn payload(&mut self) -> Result<impl Read + '_> {
        let i = self
            .payload_index
            .ok_or_else(|| Unsupported::Version(self.version.clone()))?;
        Ok(self.archive.by_index(i)?)
    }
}

/// The metadata document of a byte stream, asking no conformance question.
///
/// Reads the member SPEC 2.1 names and parses it, requiring of that member what
/// SPEC 2.2 requires: one of it, valid TOML, UTF-8. It looks for neither
/// required key and never locates a payload.
///
/// This exists because a container can be non-conformant somewhere else
/// entirely and still carry a metadata document worth reading: `payload.file`
/// naming no member, naming several, or naming something SPEC 2.3 forbids all
/// leave a document that parsed cleanly, and [`Container::read`] returns an
/// error over the payload before a caller can reach it. A program showing a
/// person what is in a file wants to show them that document.
///
/// It is not a verdict and must not be used as one: a document coming back
/// says nothing about whether the container conforms. Ask
/// [`validate`](crate::validate) for that, which is the only function here that
/// answers the question SPEC 3 constrains.
pub fn metadata_of<R: Read + Seek>(reader: R) -> Result<DocumentMut> {
    metadata_of_with(reader, Limits::default())
}

/// The metadata document alone, under bounds of the caller's choosing.
///
/// [`metadata_of`] with [`Limits::default`]. It reaches the same member by the
/// same route and is exposed to the same thing, so a caller that bounds one
/// and not the other has bounded nothing.
pub fn metadata_of_with<R: Read + Seek>(mut reader: R, limits: Limits) -> Result<DocumentMut> {
    let names = central::names(&mut reader)?;
    reader.rewind()?;

    let mut archive = ZipArchive::new(reader)?;
    let entries = entries_of(&mut archive)?;

    let i = match locate(&entries, &names, METADATA_MEMBER) {
        Located::One(i) => i,
        Located::None => return Err(Malformed::NoMetadataMember.into()),
        Located::Several(n) => return Err(Malformed::DuplicateMetadataMember(n).into()),
    };

    let bytes = read_metadata_member(&mut archive, i, entries[i].size, limits)?;
    metadata::document(&bytes)
}

/// Decompress the metadata member, stopping at the bound SPEC 6 requires.
///
/// The recorded size is read first because it refuses the ordinary hostile case
/// without inflating a byte. It is not the guarantee: measured against
/// `zip` 8.6, a central directory rewritten to declare 100 bytes for a member
/// that inflates to 209,715,259 still inflated in full and still cost 621 MB
/// resident. Nothing in ZIP checks the two against each other, so the bound has
/// to be applied to the bytes as they arrive, and the recorded size is worth
/// exactly one cheap refusal.
///
/// `limit + 1` so that reaching the bound is a refusal rather than a silent
/// truncation: a document cut off at the limit would parse to something the
/// container does not say.
fn read_metadata_member<R: Read + Seek>(
    archive: &mut ZipArchive<R>,
    index: usize,
    declared: u64,
    limits: Limits,
) -> Result<Vec<u8>> {
    let limit = limits.metadata_bytes;
    let too_large = || Unsupported::MetadataTooLarge { limit, declared };
    if declared > limit {
        return Err(too_large().into());
    }

    let mut bytes = Vec::new();
    let mut member = archive.by_index(index)?;
    member.by_ref().take(limit + 1).read_to_end(&mut bytes)?;
    if bytes.len() as u64 > limit {
        return Err(too_large().into());
    }
    Ok(bytes)
}

/// Find the member `payload.file` names, and check it may be a payload.
pub(crate) fn locate_payload(
    entries: &[Entry],
    names: &[central::Recorded],
    payload_file: &str,
) -> Result<usize> {
    name::check_payload_name(payload_file)?;

    let i = match locate(entries, names, payload_file) {
        Located::One(i) => i,
        Located::None => return Err(Malformed::NoPayloadMember(payload_file.to_owned()).into()),
        Located::Several(count) => {
            return Err(Malformed::DuplicatePayloadMember {
                name: payload_file.to_owned(),
                count,
            }
            .into())
        }
    };

    // SPEC 2.3 requires a regular file entry, so every other type an archive
    // can record is excluded rather than just symbolic links.
    if entries[i].kind != EntryKind::Regular {
        return Err(Error::Malformed(Malformed::PayloadNotARegularFile {
            name: payload_file.to_owned(),
            kind: entries[i].kind,
        }));
    }
    Ok(i)
}