zexc 1.2.1

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

use alloc::vec::Vec;

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};
#[cfg(feature = "std")]
use rayon::prelude::*;
#[cfg(feature = "std")]
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 — `no_std`-safe, no I/O trait
    /// needed (works directly off the in-memory slice).
    pub fn decompress(&self, src: &[u8]) -> Result<Vec<u8>> {
        let header = ZexHeader::from_bytes(src)?;
        let pol = &self.opts.security;
        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(_) => {}
            }
        }

        let rest = &src[crate::format::header::HEADER_SIZE..];

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

    /// Decompress from any `Read` (`std`-only — the `no_std` core path
    /// always has the whole frame in memory already; see
    /// [`Self::decompress`]).
    #[cfg(feature = "std")]
    pub fn decompress_from_reader<R: Read>(
        &self,
        inp: &mut R,
        compressed_hint: u64,
    ) -> Result<Vec<u8>> {
        let _ = compressed_hint;
        let mut buf = Vec::new();
        inp.read_to_end(&mut buf)?;
        self.decompress(&buf)
    }

    #[cfg(feature = "encryption")]
    fn decrypt_frame_body(&self, rest: &[u8]) -> Result<Vec<u8>> {
        if rest.len() < SALT_LEN + NONCE_LEN {
            return Err(Error::Decompression(
                "encrypted frame truncated before salt+nonce".into(),
            ));
        }
        let salt: [u8; SALT_LEN] = rest[..SALT_LEN].try_into().unwrap();
        let nonce: [u8; NONCE_LEN] = rest[SALT_LEN..SALT_LEN + NONCE_LEN].try_into().unwrap();
        let ct = &rest[SALT_LEN + NONCE_LEN..];

        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 block_header_size = crate::format::block::BLOCK_HEADER_SIZE;
        let mut pos = 0usize;
        let mut blocks: Vec<(BlockType, u32, &[u8])> = Vec::new();
        loop {
            if pos + block_header_size > body.len() {
                return Err(Error::CorruptBlock("truncated block header".into()));
            }
            let bh = BlockHeader::from_bytes(&body[pos..pos + block_header_size])?;
            pos += block_header_size;
            if bh.block_type == BlockType::End {
                break;
            }
            self.opts
                .security
                .check_block(bh.compressed_size as usize, bh.uncompressed_size as usize)?;
            let payload_len = bh.compressed_size as usize;
            if pos + payload_len > body.len() {
                return Err(Error::CorruptBlock("truncated block payload".into()));
            }
            let payload = &body[pos..pos + payload_len];
            pos += payload_len;
            blocks.push((bh.block_type, bh.uncompressed_size, payload));
        }

        let expected_crc = if header.has_checksum() {
            if pos + 4 > body.len() {
                return Err(Error::CorruptBlock("truncated checksum trailer".into()));
            }
            let crc_buf: [u8; 4] = body[pos..pos + 4].try_into().unwrap();
            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);

        #[cfg_attr(not(feature = "std"), allow(unused_variables))]
        let independent = header.independent_blocks();
        #[cfg(feature = "std")]
        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<_>>>()?
        };
        // `no_std`: always sequential — no thread pool available.
        #[cfg(not(feature = "std"))]
        let decoded: Vec<Vec<u8>> = 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);
        }
    }
}