Skip to main content

qualia_core_db/container_10d/
integrity.rs

1//! Whole-file content hash + canonical-encoding integrity gates (P0.3).
2//!
3//! The `.10d` container has two integrity layers:
4//!
5//! 1. **Per-section CRC-32C** (P0.2, in [`super::section`]) — each section
6//!    descriptor carries a CRC-32C over its payload; a flipped payload bit is
7//!    caught at section read.
8//! 2. **Whole-file content hash** (P0.3, here) — a CRC-32C over the entire
9//!    file (header + section table + payloads + padding), stored in the
10//!    header's `header_crc32c` field. This catches header corruption and
11//!    table corruption that the per-section CRC cannot (e.g. a flipped
12//!    `byte_offset` in a descriptor that still points somewhere valid).
13//!
14//! The whole-file hash is computed with `header_crc32c` zeroed during
15//! computation (the standard self-referential CRC technique): on encode, the
16//! field is written zero, the CRC is computed over the full buffer, then the
17//! CRC is written into the field; on verify, the stored value is saved, the
18//! field is zeroed in-place, the CRC is recomputed, and the two are compared.
19//!
20//! **Determinism / canonical bytes.** Because [`super::section::encode_container`]
21//! produces byte-identical output for identical input (canonical section
22//! order, zeroed padding), the whole-file hash is stable across encodes and
23//! changes on any payload-byte change. This is the P0.3 "whole-file hash is
24//! stable across encodes and changes on any payload-byte change, zero-alloc
25//! over the caller buffer" gate.
26
27use crate::container_10d::crc32c::crc32c;
28use crate::container_10d::header::HEADER_BYTE_SIZE;
29
30/// Offset of the `header_crc32c` field within the header (and thus within
31/// the file, since the header is at offset 0).
32const HEADER_CRC32C_OFFSET: usize = 52;
33
34/// Integrity verification error.
35#[derive(Debug, Clone, PartialEq, Eq)]
36pub enum IntegrityError {
37    /// The whole-file CRC-32C does not match the value stored in the header.
38    WholeFileCrcMismatch { expected: u32, got: u32 },
39    /// The input is shorter than the header.
40    TooShort { got: usize },
41}
42
43impl std::fmt::Display for IntegrityError {
44    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45        match self {
46            Self::WholeFileCrcMismatch { expected, got } => write!(
47                f,
48                "10d whole-file CRC-32C mismatch: expected {expected:#010x}, got {got:#010x}"
49            ),
50            Self::TooShort { got } => write!(
51                f,
52                "10d input too short for integrity check: got {got}, need {HEADER_BYTE_SIZE}"
53            ),
54        }
55    }
56}
57
58impl std::error::Error for IntegrityError {}
59
60/// Compute the whole-file CRC-32C over `data`, treating the `header_crc32c`
61/// field (bytes 52..56) as zero. Zero-heap: operates directly over the caller
62/// buffer. Does not modify `data`.
63///
64/// This is the value that should be stored in the header's `header_crc32c`
65/// field after encoding.
66pub fn compute_whole_file_crc32c(data: &[u8]) -> u32 {
67    if data.len() < HEADER_BYTE_SIZE {
68        // A sub-header buffer: CRC over whatever is present (with the crc
69        // field region treated as zero if it's not even there).
70        return crc32c(data);
71    }
72    // CRC over [0..52] + [56..end], with [52..56] treated as zero.
73    // Compute incrementally: first the head, then four zero bytes, then the
74    // tail. This avoids allocating a modified copy.
75    let mut crc =
76        crate::container_10d::crc32c::crc32c_update(0xFFFF_FFFF, &data[..HEADER_CRC32C_OFFSET]);
77    // Four zero bytes for the crc field itself.
78    crc = crate::container_10d::crc32c::crc32c_update(crc, &[0u8, 0, 0, 0]);
79    crc = crate::container_10d::crc32c::crc32c_update(crc, &data[HEADER_CRC32C_OFFSET + 4..]);
80    !crc
81}
82
83/// Write the whole-file CRC-32C into the header's `header_crc32c` field
84/// in-place within `data`. Called by the encoder after the full file is
85/// written. Zero-heap.
86pub fn seal_whole_file_crc32c(data: &mut [u8]) {
87    if data.len() < HEADER_BYTE_SIZE {
88        return;
89    }
90    // Ensure the crc field is zero before computing (the encoder already
91    // writes it zero, but be defensive).
92    data[HEADER_CRC32C_OFFSET..HEADER_CRC32C_OFFSET + 4].copy_from_slice(&0u32.to_le_bytes());
93    let crc = compute_whole_file_crc32c(data);
94    data[HEADER_CRC32C_OFFSET..HEADER_CRC32C_OFFSET + 4].copy_from_slice(&crc.to_le_bytes());
95}
96
97/// Verify the whole-file CRC-32C stored in the header against a recomputed
98/// value. Returns `Ok(())` if they match, or an error naming both values.
99/// Zero-heap: saves the stored CRC, zeroes the field in-place, recomputes,
100/// restores the field.
101pub fn verify_whole_file_crc32c(data: &mut [u8]) -> Result<(), IntegrityError> {
102    check_whole_file_crc32c(data)
103}
104
105/// Verify the whole-file CRC-32C stored in the header against a recomputed
106/// value over an immutable slice. Returns `Ok(())` if they match.
107/// Zero-heap, read-only.
108pub fn check_whole_file_crc32c(data: &[u8]) -> Result<(), IntegrityError> {
109    if data.len() < HEADER_BYTE_SIZE {
110        return Err(IntegrityError::TooShort { got: data.len() });
111    }
112    let stored = u32::from_le_bytes(
113        data[HEADER_CRC32C_OFFSET..HEADER_CRC32C_OFFSET + 4]
114            .try_into()
115            .unwrap(),
116    );
117    let actual = compute_whole_file_crc32c(data);
118    if actual != stored {
119        return Err(IntegrityError::WholeFileCrcMismatch {
120            expected: stored,
121            got: actual,
122        });
123    }
124    Ok(())
125}
126
127#[cfg(test)]
128mod tests {
129    use super::*;
130    use crate::container_10d::header::Container10dHeader;
131    use crate::container_10d::section::{
132        encode_container, parse_section_table, AlignmentTier, SectionInput, SectionType,
133    };
134
135    #[test]
136    fn whole_file_crc_is_stable_across_two_identical_encodes() {
137        let h = Container10dHeader::proposed();
138        let mesh_payload = [0xAAu8; 100];
139        let node_payload = [0xBBu8; 40 * 3];
140        let inputs = [
141            SectionInput {
142                section_type: SectionType::QuantizedMesh,
143                alignment_tier: AlignmentTier::Word,
144                stride: 0,
145                element_count: 0,
146                payload: &mesh_payload,
147            },
148            SectionInput {
149                section_type: SectionType::Tensor10DNodes,
150                alignment_tier: AlignmentTier::CacheLine,
151                stride: 40,
152                element_count: 3,
153                payload: &node_payload,
154            },
155        ];
156        let mut out_a = [0u8; 512];
157        let mut out_b = [0u8; 512];
158        let n_a = encode_container(&h, &inputs, &mut out_a).expect("encode a");
159        let n_b = encode_container(&h, &inputs, &mut out_b).expect("encode b");
160        seal_whole_file_crc32c(&mut out_a[..n_a]);
161        seal_whole_file_crc32c(&mut out_b[..n_b]);
162        let crc_a = compute_whole_file_crc32c(&out_a[..n_a]);
163        let crc_b = compute_whole_file_crc32c(&out_b[..n_b]);
164        assert_eq!(
165            crc_a, crc_b,
166            "whole-file CRC must be stable across identical encodes"
167        );
168        // And the sealed bytes are identical.
169        assert_eq!(&out_a[..n_a], &out_b[..n_b]);
170    }
171
172    #[test]
173    fn whole_file_crc_changes_on_payload_bit_flip() {
174        let h = Container10dHeader::proposed();
175        let payload = [0xAAu8; 100];
176        let inputs = [SectionInput {
177            section_type: SectionType::QuantizedMesh,
178            alignment_tier: AlignmentTier::Word,
179            stride: 0,
180            element_count: 0,
181            payload: &payload,
182        }];
183        let mut out = [0u8; 512];
184        let n = encode_container(&h, &inputs, &mut out).expect("encode");
185        seal_whole_file_crc32c(&mut out[..n]);
186        let crc_clean = compute_whole_file_crc32c(&out[..n]);
187        // Flip a payload bit.
188        let parsed_h = Container10dHeader::parse(&out[..n]).expect("header parse");
189        let descs = parse_section_table(&out[..n], &parsed_h).expect("table parse");
190        let p_off = descs[0].byte_offset as usize;
191        out[p_off] ^= 0x01;
192        let crc_flipped = compute_whole_file_crc32c(&out[..n]);
193        assert_ne!(
194            crc_clean, crc_flipped,
195            "whole-file CRC must change on a payload bit flip"
196        );
197    }
198
199    #[test]
200    fn whole_file_crc_changes_on_header_byte_flip() {
201        let h = Container10dHeader::proposed();
202        let payload = [0xAAu8; 100];
203        let inputs = [SectionInput {
204            section_type: SectionType::QuantizedMesh,
205            alignment_tier: AlignmentTier::Word,
206            stride: 0,
207            element_count: 0,
208            payload: &payload,
209        }];
210        let mut out = [0u8; 512];
211        let n = encode_container(&h, &inputs, &mut out).expect("encode");
212        seal_whole_file_crc32c(&mut out[..n]);
213        let crc_clean = compute_whole_file_crc32c(&out[..n]);
214        // Flip a header byte (the flags field at offset 6, avoiding the crc field).
215        out[6] ^= 0x01;
216        let crc_flipped = compute_whole_file_crc32c(&out[..n]);
217        assert_ne!(
218            crc_clean, crc_flipped,
219            "whole-file CRC must change on a header byte flip"
220        );
221    }
222
223    #[test]
224    fn verify_passes_on_clean_file() {
225        let h = Container10dHeader::proposed();
226        let payload = [0xAAu8; 100];
227        let inputs = [SectionInput {
228            section_type: SectionType::QuantizedMesh,
229            alignment_tier: AlignmentTier::Word,
230            stride: 0,
231            element_count: 0,
232            payload: &payload,
233        }];
234        let mut out = [0u8; 512];
235        let n = encode_container(&h, &inputs, &mut out).expect("encode");
236        seal_whole_file_crc32c(&mut out[..n]);
237        verify_whole_file_crc32c(&mut out[..n]).expect("clean file must verify");
238    }
239
240    #[test]
241    fn verify_rejects_flipped_payload_bit() {
242        let h = Container10dHeader::proposed();
243        let payload = [0xAAu8; 100];
244        let inputs = [SectionInput {
245            section_type: SectionType::QuantizedMesh,
246            alignment_tier: AlignmentTier::Word,
247            stride: 0,
248            element_count: 0,
249            payload: &payload,
250        }];
251        let mut out = [0u8; 512];
252        let n = encode_container(&h, &inputs, &mut out).expect("encode");
253        seal_whole_file_crc32c(&mut out[..n]);
254        // Flip a payload bit.
255        let parsed_h = Container10dHeader::parse(&out[..n]).expect("header parse");
256        let descs = parse_section_table(&out[..n], &parsed_h).expect("table parse");
257        let p_off = descs[0].byte_offset as usize;
258        out[p_off] ^= 0x01;
259        let err =
260            verify_whole_file_crc32c(&mut out[..n]).expect_err("flipped bit must fail verify");
261        assert!(
262            matches!(err, IntegrityError::WholeFileCrcMismatch { .. }),
263            "{err}"
264        );
265    }
266
267    #[test]
268    fn verify_restores_the_crc_field_after_check() {
269        // verify_whole_file_crc32c zeroes the field in-place, recomputes, then
270        // restores it. The field must be unchanged after the call (whether
271        // pass or fail).
272        let h = Container10dHeader::proposed();
273        let payload = [0xAAu8; 100];
274        let inputs = [SectionInput {
275            section_type: SectionType::QuantizedMesh,
276            alignment_tier: AlignmentTier::Word,
277            stride: 0,
278            element_count: 0,
279            payload: &payload,
280        }];
281        let mut out = [0u8; 512];
282        let n = encode_container(&h, &inputs, &mut out).expect("encode");
283        seal_whole_file_crc32c(&mut out[..n]);
284        let stored_before: [u8; 4] = out[HEADER_CRC32C_OFFSET..HEADER_CRC32C_OFFSET + 4]
285            .try_into()
286            .unwrap();
287        let _ = verify_whole_file_crc32c(&mut out[..n]);
288        let stored_after: [u8; 4] = out[HEADER_CRC32C_OFFSET..HEADER_CRC32C_OFFSET + 4]
289            .try_into()
290            .unwrap();
291        assert_eq!(
292            stored_before, stored_after,
293            "verify must restore the crc field"
294        );
295    }
296
297    #[test]
298    fn bare_header_seals_and_verifies() {
299        let h = Container10dHeader::proposed();
300        let mut out = [0u8; 128];
301        let n = encode_container(&h, &[], &mut out).expect("bare encode");
302        seal_whole_file_crc32c(&mut out[..n]);
303        verify_whole_file_crc32c(&mut out[..n]).expect("bare header must verify");
304    }
305}