qualia_core_db/container_10d/
integrity.rs1use crate::container_10d::crc32c::crc32c;
28use crate::container_10d::header::HEADER_BYTE_SIZE;
29
30const HEADER_CRC32C_OFFSET: usize = 52;
33
34#[derive(Debug, Clone, PartialEq, Eq)]
36pub enum IntegrityError {
37 WholeFileCrcMismatch { expected: u32, got: u32 },
39 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
60pub fn compute_whole_file_crc32c(data: &[u8]) -> u32 {
67 if data.len() < HEADER_BYTE_SIZE {
68 return crc32c(data);
71 }
72 let mut crc =
76 crate::container_10d::crc32c::crc32c_update(0xFFFF_FFFF, &data[..HEADER_CRC32C_OFFSET]);
77 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
83pub fn seal_whole_file_crc32c(data: &mut [u8]) {
87 if data.len() < HEADER_BYTE_SIZE {
88 return;
89 }
90 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
97pub fn verify_whole_file_crc32c(data: &mut [u8]) -> Result<(), IntegrityError> {
102 check_whole_file_crc32c(data)
103}
104
105pub 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 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 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 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 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 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}