onelf-format 0.4.2

//! Footer structure and serialization
//!
//! The footer is located at the end of every ONELF package and contains:
//! - Magic bytes for identification
//! - Format version
//! - Offsets to manifest, payload, and optional dictionary
//! - Checksums for integrity verification
//!
//! # Structure
//!
//! The footer is exactly 76 bytes and is organized as follows:
//!
//! ```text
//! Offset  Size    Field
//! ------  -------  -------------------
//! 0      8        Magic: "ONELF\0\x01\x00"
//! 8      2        Format version (u16)
//! 10     2        Flags (u16)
//! 12     8        Manifest offset (u64)
//! 20     8        Manifest compressed size (u64)
//! 28     8        Manifest original size (u64)
//! 36     8        Payload offset (u64)
//! 44     8        Payload total size (u64)
//! 52     8        Dictionary offset (u64)
//! 60     4        Dictionary size (u32)
//! 64     4        Manifest checksum (xxh32)
//! 68     8        End magic: "FLENONE\x00"
//! ```
//!
//! The magic bytes stay "ONELF\0\x01\x00" across versions; the version
//! field itself distinguishes formats.
//!
//! # Versions
//!
//! Version 2 means the manifest (version 3) carries `prefix_hash` and
//! `footer_hash`, so the runtime prefix and this footer are covered by a
//! hash chain rooted in the manifest; see [`crate::manifest`]. Version 1
//! files carry no such fields, so their structure cannot be checked.
//!
//! # Example
//!
//! ```ignore
//! use onelf_format::Footer;
//!
//! let footer = Footer {
//!     format_version: 2,
//!     // ... other fields
//! };
//! ```

use std::io::{self, Read, Write};

pub const FOOTER_SIZE: usize = 76;
pub const MAGIC: [u8; 8] = *b"ONELF\x00\x01\x00";
pub const END_MAGIC: [u8; 8] = *b"FLENONE\x00";

/// Footer format this build writes.
///
/// Version 2 files carry a manifest (version 3) whose header holds a
/// BLAKE3 of the runtime prefix and a BLAKE3 of this footer, making the
/// whole container structure verifiable. Version 1 remains readable so
/// old packages still run, but its prefix and footer are covered by no
/// hash at all.
pub const FORMAT_VERSION: u16 = 2;

bitflags! {
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct Flags: u16 {
        const HAS_DICT       = 1 << 0;
        const MEMFD_HINT     = 1 << 1;
        // Bit 2 was reserved for a sharun compatibility mode that never
        // shipped. It stays unused so an old package's flags read the same.
        /// Payload blocks are stored raw (no zstd). `compressed_size`
        /// equals `original_size` for every block; the runtime reads
        /// payload bytes directly without decompression.
        const STORED         = 1 << 3;
        /// The package records an update URL but carries no updater, so
        /// it is updated by something else (a package manager, a
        /// deployment system). Set only for that case, which leaves every
        /// package built before this flag existed correctly describing
        /// itself as carrying an embedded updater.
        const EXTERNAL_UPDATER = 1 << 4;
        /// Do not put the host's library directories on the search path.
        ///
        /// The runtime adds them so host GPU drivers stay reachable, but
        /// they hold the whole system's libraries, so any soname the
        /// bundle is missing is silently satisfied from the host and
        /// loaded next to the bundled libc. Set for packages that need
        /// nothing from the host.
        ///
        /// Polarity is deliberate: unset means "expose", so every package
        /// built before this flag existed keeps its behaviour.
        const NO_HOST_LIB_DIRS = 1 << 5;
        /// The launch resolver may take any bundled soname from the host,
        /// not only the driver stack's closure. See [`HostLibsPolicy`].
        const HOST_LIBS_ALWAYS = 1 << 6;
        /// The publisher asked for the persistent cache as the last
        /// execution mode. Without it the runtime stops at the runtime
        /// directory and reports failure rather than leaving an
        /// extraction on disk.
        const CACHE_REQUESTED = 1 << 7;
        /// The publisher asked for the persistent cache before every
        /// other execution mode, for an app that records its own path in
        /// files that outlive it. Set together with [`Flags::CACHE_REQUESTED`],
        /// so a runtime that predates this bit still falls back to the cache.
        const CACHE_PREFERRED = 1 << 8;
        /// The payload is a stipplefs image rather than separately compressed blocks.
        /// See [`crate::payload`] for what a block then describes.
        const STIPPLE_PAYLOAD = 1 << 9;
    }
}

/// What the launch resolver may take from the host.
///
/// Two flag bits encode three values so that a package written before
/// either bit existed reads as [`HostLibsPolicy::Auto`], which is the
/// behaviour it was built expecting: host drivers reachable, nothing else
/// promised.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostLibsPolicy {
    /// Nothing from the host.
    Never,
    /// The driver stack's host closure only.
    Auto,
    /// Any bundled soname.
    Always,
}

impl HostLibsPolicy {
    /// Decode the policy from footer flags. `NO_HOST_LIB_DIRS` wins over
    /// `HOST_LIBS_ALWAYS` when both are set, since a package that asked for
    /// nothing from the host must not get everything by a flag mix-up.
    pub fn from_flags(flags: Flags) -> Self {
        if flags.contains(Flags::NO_HOST_LIB_DIRS) {
            HostLibsPolicy::Never
        } else if flags.contains(Flags::HOST_LIBS_ALWAYS) {
            HostLibsPolicy::Always
        } else {
            HostLibsPolicy::Auto
        }
    }

    /// The flag bits that encode this policy.
    pub fn to_flags(self) -> Flags {
        match self {
            HostLibsPolicy::Never => Flags::NO_HOST_LIB_DIRS,
            HostLibsPolicy::Auto => Flags::empty(),
            HostLibsPolicy::Always => Flags::HOST_LIBS_ALWAYS,
        }
    }

    pub fn as_str(self) -> &'static str {
        match self {
            HostLibsPolicy::Never => "never",
            HostLibsPolicy::Auto => "auto",
            HostLibsPolicy::Always => "always",
        }
    }
}

#[derive(Debug, Clone)]
pub struct Footer {
    /// Format version: 1 (legacy, no structure hashes) or 2.
    pub format_version: u16,
    /// Feature flags describing optional sections and capabilities.
    pub flags: Flags,
    /// Byte offset where the compressed manifest begins.
    pub manifest_offset: u64,
    /// Size of the manifest after compression.
    pub manifest_compressed: u64,
    /// Size of the manifest before compression.
    pub manifest_original: u64,
    /// Byte offset where the payload section begins.
    pub payload_offset: u64,
    /// Total size of the payload section in bytes.
    pub payload_size: u64,
    /// Byte offset of the zstd dictionary, or 0 if absent.
    pub dict_offset: u64,
    /// Size of the zstd dictionary in bytes, or 0 if absent.
    pub dict_size: u32,
    /// xxHash32 checksum of the *uncompressed* manifest bytes, verified
    /// before the manifest is trusted.
    pub manifest_checksum: [u8; 4],
}

impl Footer {
    /// Whether the payload is stored raw (no zstd). When true the runtime
    /// must skip decompression and use payload bytes directly.
    pub fn is_stored(&self) -> bool {
        self.flags.contains(Flags::STORED)
    }

    /// Whether the payload is a stipplefs image. See [`crate::payload`].
    pub fn is_stipple(&self) -> bool {
        self.flags.contains(Flags::STIPPLE_PAYLOAD)
    }

    /// BLAKE3 over this footer's exact 76 bytes, with the four
    /// manifest-derived layout fields (`manifest_compressed`,
    /// `manifest_original`, `payload_offset`, `dict_offset`) zeroed.
    ///
    /// This is the value a format-2 manifest carries in its `footer_hash`
    /// field. The layout fields are excluded because the packer cannot
    /// know them before compressing the manifest, and the manifest cannot
    /// be compressed before this hash exists: their values are pinned
    /// indirectly instead, by the bounds checks and the entry hashes the
    /// manifest carries. The `manifest_checksum` field is included, so
    /// rewriting the manifest also changes this hash. The chain is an
    /// integrity check, not authentication: whoever rewrites a file can
    /// recompute every hash in it. Only a detached signature proves who
    /// produced a package.
    pub fn structure_hash(&self) -> [u8; 32] {
        let mut buf = [0u8; FOOTER_SIZE];
        let mut sink: &mut [u8] = &mut buf;
        // write_to cannot fail on an in-memory sink.
        self.write_to(&mut sink).ok();
        buf[20..44].fill(0);
        buf[52..60].fill(0);
        *blake3::hash(&buf).as_bytes()
    }

    pub fn write_to<W: Write>(&self, w: &mut W) -> io::Result<()> {
        w.write_all(&MAGIC)?; // 8
        w.write_all(&self.format_version.to_le_bytes())?; // 2
        w.write_all(&self.flags.bits().to_le_bytes())?; // 2
        w.write_all(&self.manifest_offset.to_le_bytes())?; // 8
        w.write_all(&self.manifest_compressed.to_le_bytes())?; // 8
        w.write_all(&self.manifest_original.to_le_bytes())?; // 8
        w.write_all(&self.payload_offset.to_le_bytes())?; // 8
        w.write_all(&self.payload_size.to_le_bytes())?; // 8
        w.write_all(&self.dict_offset.to_le_bytes())?; // 8
        w.write_all(&self.dict_size.to_le_bytes())?; // 4
        w.write_all(&self.manifest_checksum)?; // 4
        w.write_all(&END_MAGIC)?; // 8
        Ok(()) // = 76
    }

    pub fn read_from<R: Read>(r: &mut R) -> io::Result<Self> {
        let mut buf = [0u8; FOOTER_SIZE];
        r.read_exact(&mut buf)?;
        Self::from_bytes(&buf)
    }

    pub fn from_bytes(buf: &[u8; FOOTER_SIZE]) -> io::Result<Self> {
        if buf[0..8] != MAGIC {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "invalid onelf magic",
            ));
        }
        if buf[68..76] != END_MAGIC {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                "invalid onelf end magic",
            ));
        }

        let format_version = u16::from_le_bytes(buf[8..10].try_into().unwrap());
        if format_version != 1 && format_version != FORMAT_VERSION {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!("unsupported format version: {}", format_version),
            ));
        }

        let flags_raw = u16::from_le_bytes(buf[10..12].try_into().unwrap());
        let flags = Flags::from_bits_retain(flags_raw);

        Ok(Footer {
            format_version,
            flags,
            manifest_offset: u64::from_le_bytes(buf[12..20].try_into().unwrap()),
            manifest_compressed: u64::from_le_bytes(buf[20..28].try_into().unwrap()),
            manifest_original: u64::from_le_bytes(buf[28..36].try_into().unwrap()),
            payload_offset: u64::from_le_bytes(buf[36..44].try_into().unwrap()),
            payload_size: u64::from_le_bytes(buf[44..52].try_into().unwrap()),
            dict_offset: u64::from_le_bytes(buf[52..60].try_into().unwrap()),
            dict_size: u32::from_le_bytes(buf[60..64].try_into().unwrap()),
            manifest_checksum: buf[64..68].try_into().unwrap(),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample() -> Footer {
        Footer {
            format_version: FORMAT_VERSION,
            flags: Flags::HAS_DICT | Flags::STORED,
            manifest_offset: 0x1122,
            manifest_compressed: 0x33,
            manifest_original: 0x44,
            payload_offset: 0x55,
            payload_size: 0x66,
            dict_offset: 0x77,
            dict_size: 0x88,
            manifest_checksum: [1, 2, 3, 4],
        }
    }

    #[test]
    fn footer_roundtrips() {
        let f = sample();
        let mut buf = Vec::new();
        f.write_to(&mut buf).unwrap();
        assert_eq!(buf.len(), FOOTER_SIZE);
        let back = Footer::from_bytes(&buf.try_into().unwrap()).unwrap();
        assert_eq!(back.format_version, f.format_version);
        assert_eq!(back.flags, f.flags);
        assert_eq!(back.manifest_offset, f.manifest_offset);
        assert_eq!(back.dict_size, f.dict_size);
        assert_eq!(back.manifest_checksum, f.manifest_checksum);
    }

    #[test]
    fn malformed_footers_error_without_panic() {
        let mut buf = Vec::new();
        sample().write_to(&mut buf).unwrap();

        // Bad start magic.
        let mut bad = buf.clone();
        bad[0] ^= 0xff;
        assert!(Footer::from_bytes(&bad.clone().try_into().unwrap()).is_err());

        // Bad end magic.
        let mut bad = buf.clone();
        bad[68] ^= 0xff;
        assert!(Footer::from_bytes(&bad.clone().try_into().unwrap()).is_err());

        // Unsupported version: 0 and anything past the current one.
        for version in [0u16, 3u16, 99u16] {
            let mut bad = buf.clone();
            bad[8..10].copy_from_slice(&version.to_le_bytes());
            assert!(Footer::from_bytes(&bad.try_into().unwrap()).is_err());
        }

        // Both readable versions decode.
        for version in [1u16, FORMAT_VERSION] {
            let mut ok = buf.clone();
            ok[8..10].copy_from_slice(&version.to_le_bytes());
            assert!(Footer::from_bytes(&ok.try_into().unwrap()).is_ok());
        }
    }

    #[test]
    fn structure_hash_pins_everything_but_the_size_fields() {
        let f = sample();
        let h = f.structure_hash();

        // The three manifest-derived layout fields may differ (the packer
        // fills them in after this hash is taken) without moving the hash.
        let mut grown = f.clone();
        grown.manifest_compressed += 7;
        grown.manifest_original += 7;
        grown.payload_offset += 7;
        grown.dict_offset += 7;
        assert_eq!(grown.structure_hash(), h);

        // Every other field is pinned: a change to any of them shows up.
        let mut other = f.clone();
        other.payload_size += 1;
        assert_ne!(other.structure_hash(), h);
        let mut other = f.clone();
        other.manifest_checksum = [9, 9, 9, 9];
        assert_ne!(other.structure_hash(), h);
        let mut other = f.clone();
        other.flags = Flags::empty();
        assert_ne!(other.structure_hash(), h);
        let mut other = f.clone();
        other.manifest_offset += 1;
        assert_ne!(other.structure_hash(), h);
    }

    #[test]
    fn host_libs_policy_decodes_every_encoding() {
        assert_eq!(
            HostLibsPolicy::from_flags(Flags::empty()),
            HostLibsPolicy::Auto
        );
        assert_eq!(
            HostLibsPolicy::from_flags(Flags::NO_HOST_LIB_DIRS),
            HostLibsPolicy::Never
        );
        assert_eq!(
            HostLibsPolicy::from_flags(Flags::HOST_LIBS_ALWAYS),
            HostLibsPolicy::Always
        );
        assert_eq!(
            HostLibsPolicy::from_flags(Flags::NO_HOST_LIB_DIRS | Flags::HOST_LIBS_ALWAYS),
            HostLibsPolicy::Never
        );
        for policy in [
            HostLibsPolicy::Never,
            HostLibsPolicy::Auto,
            HostLibsPolicy::Always,
        ] {
            assert_eq!(HostLibsPolicy::from_flags(policy.to_flags()), policy);
        }
    }

    #[test]
    fn host_libs_policy_ignores_unknown_bits() {
        let unknown = Flags::from_bits_retain(1 << 15);
        assert_eq!(HostLibsPolicy::from_flags(unknown), HostLibsPolicy::Auto);
        assert_eq!(
            HostLibsPolicy::from_flags(unknown | Flags::HOST_LIBS_ALWAYS),
            HostLibsPolicy::Always
        );
        let mut buf = Vec::new();
        let mut f = sample();
        f.flags = unknown | Flags::CACHE_REQUESTED;
        f.write_to(&mut buf).unwrap();
        let back = Footer::from_bytes(&buf.try_into().unwrap()).unwrap();
        assert!(back.flags.contains(Flags::CACHE_REQUESTED));
        assert_eq!(back.flags.bits() & (1 << 15), 1 << 15);
    }
}