clm-kernel 0.0.17

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! MagicSignature extracted from `type_interpreter.rs` (Sprint 534 ratchet).

use serde::{Deserialize, Serialize};
use std::collections::HashSet;

/// Byte-level magic signature for fast, deterministic binary identification.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MagicSignature {
    pub offset: usize,
    pub hex: String,
    pub mask: Option<String>,
    pub description: Option<String>,
}

impl MagicSignature {
    /// Match this complete signature at its declared byte offset.
    pub fn matches(&self, data: &[u8]) -> bool {
        let clean_hex: String = self.hex.chars().filter(|c| c.is_ascii_hexdigit()).collect();
        if !clean_hex.len().is_multiple_of(2) || clean_hex.is_empty() {
            return false;
        }

        let sig_bytes = match hex::decode(&clean_hex) {
            Ok(b) => b,
            Err(_) => return false,
        };

        let required_len = self.offset + sig_bytes.len();
        if data.len() < required_len {
            return false;
        }

        let target_slice = &data[self.offset..required_len];

        if let Some(mask_str) = &self.mask {
            let clean_mask: String = mask_str.chars().filter(|c| c.is_ascii_hexdigit()).collect();
            if let Ok(mask_bytes) = hex::decode(&clean_mask) {
                for (i, (&b, &sig)) in target_slice.iter().zip(sig_bytes.iter()).enumerate() {
                    let m = if i < mask_bytes.len() { mask_bytes[i] } else { 0xff };
                    if (b & m) != sig {
                        return false;
                    }
                }
                return true;
            }
        }

        target_slice == sig_bytes.as_slice()
    }

    /// Return the number of bytes encoded by this signature.
    pub fn byte_length(&self) -> usize {
        let clean: String = self.hex.chars().filter(|c| c.is_ascii_hexdigit()).collect();
        clean.len() / 2
    }

    /// Return the matched byte count when the payload ends inside this signature.
    pub fn truncated_prefix_len(&self, data: &[u8]) -> Option<usize> {
        let clean: String = self.hex.chars().filter(|c| c.is_ascii_hexdigit()).collect();
        let pattern = hex::decode(clean).ok()?;
        if data.len() <= self.offset || data.len() >= self.offset + pattern.len() {
            return None;
        }
        let count = data.len() - self.offset;
        if count < 2 || data[self.offset..].iter().all(|byte| *byte == 0) {
            return None;
        }
        let mask = self.mask.as_ref().and_then(|value| {
            let clean: String = value.chars().filter(|c| c.is_ascii_hexdigit()).collect();
            hex::decode(clean).ok()
        });
        for index in 0..count {
            let mask_byte = mask.as_ref().and_then(|bytes| bytes.get(index)).copied().unwrap_or(0xff);
            if data[self.offset + index] & mask_byte != pattern[index] {
                return None;
            }
        }
        Some(count)
    }
}

#[derive(Debug, Clone)]
/// MIME and brand data resolved from an ISO container header.
pub struct BrandMatch {
    pub mime: String,
    pub sub_dialect: Option<String>,
    pub major_brand: Option<String>,
    pub compatible_brands: Vec<String>,
}

#[derive(Debug, Clone)]
/// MIME candidates and longest matched prefix for a partial binary signature.
pub struct TruncatedSignatureMatch {
    pub candidate_mimes: Vec<String>,
    pub matched_bytes: usize,
}

fn read_u32(data: &[u8], offset: usize) -> u32 {
    u32::from_be_bytes(data[offset..offset + 4].try_into().unwrap())
}

fn ascii4(data: &[u8], offset: usize) -> String {
    String::from_utf8_lossy(&data[offset..offset + 4]).into_owned()
}

fn read_brands(data: &[u8], start: usize, end: usize) -> Vec<String> {
    (start..end.saturating_sub(3)).step_by(4).map(|offset| ascii4(data, offset)).collect()
}

fn jp2_mime(major: &str, compatible: &[String]) -> &'static str {
    match major {
        "jp2 " => "image/jp2",
        "jpx " => "image/jpx",
        "jpm " => "image/jpm",
        _ if compatible.iter().any(|brand| brand == "jpx ") => "image/jpx",
        _ if compatible.iter().any(|brand| brand == "jp2 ") => "image/jp2",
        _ if compatible.iter().any(|brand| brand == "jpm ") => "image/jpm",
        _ => "image/jpx",
    }
}

fn isobmff_mime(major: &str, compatible: &[String]) -> &'static str {
    match major {
        "avif" | "avis" => "image/avif",
        "heic" | "heix" | "hevc" | "hevx" => "image/heic",
        "mif1" | "msf1" if compatible.iter().any(|brand| matches!(brand.as_str(), "heic" | "heix")) => "image/heic",
        "mif1" | "msf1" if compatible.iter().any(|brand| matches!(brand.as_str(), "avif" | "avis")) => "image/avif",
        "mif1" | "msf1" => "image/heif",
        "qt  " => "video/quicktime",
        "M4A " | "M4B " => "audio/mp4",
        _ => "video/mp4",
    }
}

/// Resolve ISO BMFF and JPEG 2000 brands before generic signature matching.
pub fn inspect_container_brand(data: &[u8]) -> Option<BrandMatch> {
    const JP2: &[u8] = b"\x00\x00\x00\x0cjP  \r\n\x87\n";
    if data.starts_with(JP2) {
        if data.len() < 24 || &data[16..20] != b"ftyp" {
            return Some(BrandMatch {
                mime: "image/jpx".to_string(),
                sub_dialect: None,
                major_brand: None,
                compatible_brands: Vec::new(),
            });
        }
        let size = read_u32(data, 12);
        let (major_offset, box_end) = if size == 1 {
            if data.len() < 32 {
                return Some(BrandMatch { mime: "image/jpx".to_string(), sub_dialect: None, major_brand: None, compatible_brands: Vec::new() });
            }
            let size64 = u64::from_be_bytes(data[20..28].try_into().unwrap()) as usize;
            (28, if size64 >= 20 { data.len().min(12 + size64) } else { data.len() })
        } else {
            (20, if size >= 12 { data.len().min(12 + size as usize) } else { data.len() })
        };
        let major = ascii4(data, major_offset);
        let compatible = read_brands(data, major_offset + 8, box_end);
        return Some(BrandMatch {
            mime: jp2_mime(&major, &compatible).to_string(),
            sub_dialect: Some(major.trim().to_string()),
            major_brand: Some(major),
            compatible_brands: compatible,
        });
    }

    if data.len() < 12 || &data[4..8] != b"ftyp" {
        return None;
    }
    let size = read_u32(data, 0);
    let (major_offset, box_end) = if size == 1 {
        if data.len() < 20 {
            return None;
        }
        let size64 = u64::from_be_bytes(data[8..16].try_into().unwrap()) as usize;
        (16, if size64 >= 16 { data.len().min(size64) } else { data.len() })
    } else {
        (8, if size >= 8 { data.len().min(size as usize) } else { data.len() })
    };
    let major = ascii4(data, major_offset);
    let compatible = read_brands(data, major_offset + 8, box_end);
    Some(BrandMatch {
        mime: isobmff_mime(&major, &compatible).to_string(),
        sub_dialect: Some(major.trim().to_string()),
        major_brand: Some(major),
        compatible_brands: compatible,
    })
}

/// Find binary signatures whose available bytes match only a prefix.
pub fn detect_truncated_signature<F>(
    data: &[u8],
    signatures: &[(MagicSignature, String)],
    is_binary_mime: F,
) -> Option<TruncatedSignatureMatch>
where
    F: Fn(&str) -> bool,
{
    if data.len() < 2 {
        return None;
    }
    let mut candidates = HashSet::new();
    let mut matched_bytes = 0;
    if data.len() >= 8 && data.len() < 20 && &data[4..8] == b"ftyp" && read_u32(data, 0) == 1 {
        candidates.insert("video/mp4".to_string());
        matched_bytes = data.len();
    }
    for (signature, mime) in signatures {
        if !is_binary_mime(mime) {
            continue;
        }
        let allowed = signature.offset == 0
            || (signature.offset == 4 && data.len() > 4 && data.starts_with(b"\x00\x00"));
        if !allowed {
            continue;
        }
        if let Some(count) = signature.truncated_prefix_len(data) {
            candidates.insert(mime.clone());
            matched_bytes = matched_bytes.max(count);
        }
    }
    if candidates.is_empty() {
        return None;
    }
    let mut candidate_mimes: Vec<String> = candidates.into_iter().collect();
    candidate_mimes.sort();
    Some(TruncatedSignatureMatch { candidate_mimes, matched_bytes })
}

/// Classify structured text with the canonical syntax probes.
pub fn probe_structured_text(text: &str) -> Option<(String, String, f32)> {
    if ((text.starts_with('{') && text.ends_with('}')) || (text.starts_with('[') && text.ends_with(']')))
        && serde_json::from_str::<serde_json::Value>(text).is_ok()
    {
        for (key, mime, rule) in [
            ("\"mcard_version\"", "application/vnd.mcard+json", "structured_mcard_probe"),
            ("\"pcard_version\"", "application/vnd.pcard+json", "structured_pcard_probe"),
            ("\"vcard_version\"", "application/vnd.vcard+json", "structured_vcard_probe"),
        ] {
            if text.contains(key) {
                return Some((mime.to_string(), rule.to_string(), 0.99));
            }
        }
        return Some(("application/json".to_string(), "structured_json_probe".to_string(), 0.98));
    }
    let lower = text.to_lowercase();
    let lower_sample: String = text.chars().take(512).collect::<String>().to_lowercase();
    if text.starts_with("<?xml") || lower_sample.contains("<svg") {
        if lower.contains("<svg") {
            return Some(("image/svg+xml".to_string(), "structured_svg_probe".to_string(), 0.96));
        }
        return Some(("application/xml".to_string(), "structured_xml_probe".to_string(), 0.92));
    }
    if lower_sample.contains("<!doctype html") || lower_sample.contains("<html") {
        return Some(("text/html".to_string(), "structured_html_probe".to_string(), 0.95));
    }
    if text.starts_with("---") && text[3..].contains("\n---") {
        return Some(("text/markdown".to_string(), "markdown_frontmatter_probe".to_string(), 0.90));
    }
    if text.contains("\\documentclass") || text.contains("\\begin{tikzpicture}") || text.contains("\\begin{document}") {
        if text.contains("\\begin{tikzpicture}") {
            return Some(("text/x-tikz".to_string(), "structured_tikz_probe".to_string(), 0.95));
        }
        return Some(("text/x-tex".to_string(), "structured_latex_probe".to_string(), 0.92));
    }
    None
}

/// Normalize an explicit extension or extract it from a filename.
pub fn resolve_extension(filename: Option<&str>, ext_hint: Option<&str>) -> Option<String> {
    let mut target = ext_hint.unwrap_or("").trim().to_lowercase();
    if target.is_empty()
        && let Some(name) = filename
            && let Some(index) = name.rfind('.') {
                target = name[index..].trim().to_lowercase();
            }
    if target.is_empty() {
        None
    } else if target.starts_with('.') {
        Some(target)
    } else {
        Some(format!(".{target}"))
    }
}

/// Classify bytes by null-byte presence and the canonical non-text threshold.
pub fn is_binary_payload(data: &[u8]) -> bool {
    if data.is_empty() {
        return false;
    }
    let sample = &data[..data.len().min(4096)];
    if sample.contains(&0) {
        return true;
    }
    let non_text = sample.iter().filter(|&&byte| byte < 9 || (byte > 13 && byte < 32) || byte > 127).count();
    (non_text as f32 / sample.len() as f32) > 0.30
}