zexc 1.1.2

zex native lossless compressor — CLI zexc, library zexc, files *.zex
Documentation
//! ZEX decoder — native blocks, optional AEAD, security-hardened.

use crate::algorithms::zex_native;
use crate::core::dictionary::Dictionary;
use crate::format::block::{BlockHeader, BlockType};
use crate::format::header::ZexHeader;
use crate::utils::crc::crc32;
use crate::utils::security::SecurityPolicy;
use crate::{Error, Result};
use rayon::prelude::*;
use std::io::Read;

#[cfg(feature = "encryption")]
use crate::crypto::{
    EncryptionKey, KEY_LEN, NONCE_LEN, SALT_LEN, decrypt_body, derive_key_from_password,
};

/// Decompression options.
#[derive(Debug, Clone)]
pub struct DecompressOptions {
    /// Verify CRC32 trailer when present.
    pub verify_checksum: bool,
    /// Parallel block decode when blocks are independent.
    pub threads: bool,
    /// Security policy.
    pub security: SecurityPolicy,
    /// Dictionary for history matches (must match compressor).
    pub dictionary: Option<Dictionary>,
    /// Key/password if frame is encrypted.
    #[cfg(feature = "encryption")]
    pub encryption: Option<EncryptionKey>,
}

impl Default for DecompressOptions {
    fn default() -> Self {
        Self {
            verify_checksum: true,
            threads: true,
            security: SecurityPolicy::default(),
            dictionary: None,
            #[cfg(feature = "encryption")]
            encryption: None,
        }
    }
}

/// Reusable decoder.
pub struct Decoder {
    opts: DecompressOptions,
}

impl Decoder {
    /// Create with options.
    pub fn new(opts: DecompressOptions) -> Self {
        Self { opts }
    }

    /// Strict security decoder.
    pub fn secure() -> Self {
        Self {
            opts: DecompressOptions {
                verify_checksum: true,
                threads: true,
                security: SecurityPolicy::strict(),
                dictionary: None,
                #[cfg(feature = "encryption")]
                encryption: None,
            },
        }
    }

    /// Decompress a full `.zex` buffer.
    pub fn decompress(&self, src: &[u8]) -> Result<Vec<u8>> {
        self.decompress_from_reader(&mut &src[..], src.len() as u64)
    }

    /// Decompress from any `Read`.
    pub fn decompress_from_reader<R: Read>(
        &self,
        inp: &mut R,
        compressed_hint: u64,
    ) -> Result<Vec<u8>> {
        let header = ZexHeader::read_from(inp)?;
        let pol = &self.opts.security;
        let _ = compressed_hint;

        pol.check_frame_size(header.content_size)?;

        // Dictionary id check
        if header.dictionary_id != 0 {
            match &self.opts.dictionary {
                None => {
                    return Err(Error::Dictionary(format!(
                        "frame requires dictionary id {:#x}",
                        header.dictionary_id
                    )));
                }
                Some(d) if d.id != header.dictionary_id => {
                    return Err(Error::Dictionary(format!(
                        "dictionary id mismatch: frame {:#x}, provided {:#x}",
                        header.dictionary_id, d.id
                    )));
                }
                Some(_) => {}
            }
        }

        // Materialize body (possibly decrypt first)
        let body = if header.is_encrypted() {
            #[cfg(feature = "encryption")]
            {
                self.decrypt_frame_body(inp)?
            }
            #[cfg(not(feature = "encryption"))]
            {
                return Err(Error::Decompression(
                    "encrypted frame but build lacks `encryption` feature".into(),
                ));
            }
        } else {
            let mut buf = Vec::new();
            inp.read_to_end(&mut buf)?;
            buf
        };

        self.decode_body(&header, &body)
    }

    #[cfg(feature = "encryption")]
    fn decrypt_frame_body<R: Read>(&self, inp: &mut R) -> Result<Vec<u8>> {
        let mut salt = [0u8; SALT_LEN];
        let mut nonce = [0u8; NONCE_LEN];
        inp.read_exact(&mut salt)?;
        inp.read_exact(&mut nonce)?;
        let mut ct = Vec::new();
        inp.read_to_end(&mut ct)?;

        let ek = self.opts.encryption.as_ref().ok_or_else(|| {
            Error::Decompression("encrypted frame requires --password / encryption key".into())
        })?;

        let key: [u8; KEY_LEN] = match ek {
            EncryptionKey::Raw(k) => *k,
            EncryptionKey::Password(pw) => {
                if salt.iter().all(|&b| b == 0) {
                    return Err(Error::Decompression(
                        "frame used raw key; provide 64-char hex key, not password".into(),
                    ));
                }
                derive_key_from_password(pw, &salt)?
            }
        };

        decrypt_body(&key, &nonce, &ct)
    }

    fn decode_body(&self, header: &ZexHeader, body: &[u8]) -> Result<Vec<u8>> {
        let mut cur = body;
        let mut blocks: Vec<(BlockType, u32, Vec<u8>)> = Vec::new();
        loop {
            let bh = BlockHeader::read_from(&mut cur)?;
            if bh.block_type == BlockType::End {
                break;
            }
            self.opts
                .security
                .check_block(bh.compressed_size as usize, bh.uncompressed_size as usize)?;
            let mut payload = vec![0u8; bh.compressed_size as usize];
            std::io::Read::read_exact(&mut cur, &mut payload)?;
            blocks.push((bh.block_type, bh.uncompressed_size, payload));
        }

        let expected_crc = if header.has_checksum() {
            let mut crc_buf = [0u8; 4];
            std::io::Read::read_exact(&mut cur, &mut crc_buf)?;
            Some(u32::from_le_bytes(crc_buf))
        } else {
            None
        };

        let dict = self
            .opts
            .dictionary
            .as_ref()
            .map(|d| d.data.as_slice())
            .filter(|_| header.dictionary_id != 0);

        let independent = header.independent_blocks();
        let decoded: Vec<Vec<u8>> = if self.opts.threads && independent && blocks.len() > 1 {
            blocks
                .par_iter()
                .map(|(ty, unc, payload)| decode_block(*ty, payload, *unc as usize, dict))
                .collect::<Result<Vec<_>>>()?
        } else {
            blocks
                .iter()
                .map(|(ty, unc, payload)| decode_block(*ty, payload, *unc as usize, dict))
                .collect::<Result<Vec<_>>>()?
        };

        let total: usize = decoded.iter().map(|b| b.len()).sum();
        if total as u64 > self.opts.security.max_output {
            return Err(Error::InvalidParameter(format!(
                "output {total} exceeds max_output {}",
                self.opts.security.max_output
            )));
        }

        let mut out = Vec::with_capacity(total);
        for b in decoded {
            out.extend_from_slice(&b);
        }

        if header.content_size != u64::MAX && out.len() as u64 != header.content_size {
            return Err(Error::SizeMismatch {
                expected: header.content_size,
                actual: out.len() as u64,
            });
        }

        if let Some(expected) = expected_crc {
            if self.opts.verify_checksum {
                let actual = crc32(&out);
                if actual != expected {
                    return Err(Error::ChecksumMismatch { expected, actual });
                }
            }
        }

        Ok(out)
    }
}

fn decode_block(ty: BlockType, payload: &[u8], unc: usize, dict: Option<&[u8]>) -> Result<Vec<u8>> {
    match ty {
        BlockType::Raw => {
            if payload.len() != unc {
                return Err(Error::SizeMismatch {
                    expected: unc as u64,
                    actual: payload.len() as u64,
                });
            }
            Ok(payload.to_vec())
        }
        BlockType::Zex => zex_native::decompress_with_history(payload, unc, dict),
        BlockType::End => Err(Error::CorruptBlock("unexpected end block payload".into())),
    }
}

/// One-shot decompress with defaults.
pub fn decompress(src: &[u8]) -> Result<Vec<u8>> {
    Decoder::new(DecompressOptions::default()).decompress(src)
}

/// Decompress with options.
pub fn decompress_with_options(src: &[u8], opts: &DecompressOptions) -> Result<Vec<u8>> {
    Decoder::new(opts.clone()).decompress(src)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::core::encoder::{CompressOptions, compress};
    use crate::format::header::CompressionMode;

    #[test]
    fn checksum_detects_corruption() {
        let src = b"checksum corruption detection payload 12345".repeat(10);
        let c = compress(&src, &CompressOptions::default()).unwrap();
        let mut bad = c.clone();
        if bad.len() > 40 {
            let i = bad.len() / 2;
            bad[i] ^= 0xFF;
        }
        assert!(decompress(&bad).is_err());
    }

    #[test]
    fn modes_roundtrip() {
        let src: Vec<u8> = (0..10_000u32).flat_map(|i| i.to_le_bytes()).collect();
        for mode in [
            CompressionMode::Turbo,
            CompressionMode::Balanced,
            CompressionMode::Max,
        ] {
            let opts = CompressOptions::default().mode(mode).level(4);
            let c = compress(&src, &opts).unwrap();
            let d = decompress(&c).unwrap();
            assert_eq!(d, src);
        }
    }
}