Skip to main content

qualia_core_db/net/peer/replication/
originals.rs

1//! Signed originals stored separately from derived projections (E06.4).
2//!
3//! Large objects are digested in 4096-byte pages with a running SHA-384.
4//! Length mismatch is [`QdnfError::Range`]. Digest mismatch is
5//! [`QdnfError::Conflict`]. This module never allocates a whole-graph buffer.
6//!
7//! E06.5: [`QnfExtensionAdopted`] is false — Q42 envelopes remain. E06.6
8//! process-kill disk tests stay honest via
9//! [`crate::net::peer::replication::crash::disk_backend_crash_injected`] (false;
10//! in-memory crash model, not an OS kill).
11
12use sha2::{Digest, Sha384};
13
14use crate::net::peer::replication::source::ScanSource;
15use crate::net::qdnf::errors::QdnfError;
16use crate::net::qdnf::types::StrongDigest;
17
18/// Page size for streaming original bytes. Not a dataset allocation.
19pub const STREAM_PAGE_BYTES: u32 = 4096;
20
21/// E06.5 format decision: QNF extension is not adopted. Q42 envelopes remain.
22#[allow(non_upper_case_globals)]
23pub const QnfExtensionAdopted: bool = false;
24
25/// Stored original identity: SHA-384 and exact length. Not a projection.
26#[repr(C)]
27#[derive(Clone, Copy, Debug, PartialEq, Eq)]
28pub struct OriginalObject {
29    pub digest: StrongDigest,
30    pub len: u32,
31}
32
33/// Digest `bytes` in [`STREAM_PAGE_BYTES`] pages. `out_buf_cap_check` is the
34/// caller-owned buffer ceiling (not allocated here).
35///
36/// [`QdnfError::Malformed`] if `bytes` is empty. [`QdnfError::Capacity`] if
37/// `bytes.len()` exceeds `out_buf_cap_check` or `u32::MAX`.
38pub fn store_original(bytes: &[u8], out_buf_cap_check: u32) -> Result<OriginalObject, QdnfError> {
39    if bytes.is_empty() {
40        return Err(QdnfError::Malformed);
41    }
42    let len = u32::try_from(bytes.len()).map_err(|_| QdnfError::Range)?;
43    if len > out_buf_cap_check {
44        return Err(QdnfError::Capacity);
45    }
46    Ok(OriginalObject {
47        digest: digest_pages(bytes),
48        len,
49    })
50}
51
52/// Copy `source` in caller-owned pages, verify `expected_len` and `expected`.
53///
54/// [`QdnfError::Malformed`] if `expected` is zero. [`QdnfError::Capacity`] if
55/// `page` is empty while `expected_len > 0`. [`QdnfError::Range`] if
56/// `source.logical_len()` or copied bytes disagree with `expected_len`.
57/// [`QdnfError::Conflict`] if the running digest disagrees with `expected`.
58pub fn stream_original(
59    source: &impl ScanSource,
60    expected_len: u32,
61    expected: StrongDigest,
62    page: &mut [u8],
63) -> Result<OriginalObject, QdnfError> {
64    if expected == StrongDigest::ZERO {
65        return Err(QdnfError::Malformed);
66    }
67    if expected_len == 0 {
68        return Err(QdnfError::Range);
69    }
70    if page.is_empty() {
71        return Err(QdnfError::Capacity);
72    }
73    if source.logical_len() != u64::from(expected_len) {
74        return Err(QdnfError::Range);
75    }
76    let digest = hash_source(source, expected_len, page)?;
77    if digest != expected {
78        return Err(QdnfError::Conflict);
79    }
80    Ok(OriginalObject {
81        digest,
82        len: expected_len,
83    })
84}
85
86/// Projection digest is never substituted for the original identity.
87#[inline]
88pub fn projection_replaces_original() -> bool {
89    false
90}
91
92fn digest_pages(bytes: &[u8]) -> StrongDigest {
93    let mut hasher = Sha384::new();
94    let mut off = 0usize;
95    while off < bytes.len() {
96        let end = core::cmp::min(off + STREAM_PAGE_BYTES as usize, bytes.len());
97        hasher.update(&bytes[off..end]);
98        off = end;
99    }
100    finish(hasher)
101}
102
103fn hash_source(
104    source: &impl ScanSource,
105    expected_len: u32,
106    page: &mut [u8],
107) -> Result<StrongDigest, QdnfError> {
108    let mut hasher = Sha384::new();
109    let mut copied = 0u32;
110    let cap = if page.len() > STREAM_PAGE_BYTES as usize {
111        STREAM_PAGE_BYTES as usize
112    } else {
113        page.len()
114    };
115    while copied < expected_len {
116        let remain = (expected_len - copied) as usize;
117        let want = if remain < cap { remain } else { cap };
118        let got = source.read_at(u64::from(copied), &mut page[..want])?;
119        if got == 0 {
120            return Err(QdnfError::Range);
121        }
122        hasher.update(&page[..got]);
123        copied = copied.checked_add(got as u32).ok_or(QdnfError::Range)?;
124        if copied > expected_len {
125            return Err(QdnfError::Range);
126        }
127    }
128    if copied != expected_len {
129        return Err(QdnfError::Range);
130    }
131    Ok(finish(hasher))
132}
133
134fn finish(hasher: Sha384) -> StrongDigest {
135    let out = hasher.finalize();
136    let mut d = StrongDigest::ZERO;
137    d.0.copy_from_slice(&out);
138    d
139}
140
141#[cfg(test)]
142mod tests {
143    use super::*;
144    use crate::crypto::network::digest::sha384;
145    use crate::net::peer::replication::source::MemorySource;
146
147    #[test]
148    fn qnf_extension_not_adopted() {
149        assert!(!QnfExtensionAdopted);
150        assert!(!projection_replaces_original());
151    }
152
153    #[test]
154    fn store_original_matches_whole_sha384() {
155        let bytes = [0x11u8; 80];
156        let orig = store_original(&bytes, 80).unwrap();
157        assert_eq!(orig.len, 80);
158        assert_eq!(orig.digest, sha384(&bytes));
159        assert_eq!(store_original(&bytes, 79), Err(QdnfError::Capacity));
160        assert_eq!(store_original(&[], 8), Err(QdnfError::Malformed));
161    }
162
163    #[test]
164    fn page_stream_digest_matches_and_mismatch_is_conflict() {
165        let mut bytes = [0u8; STREAM_PAGE_BYTES as usize + 32];
166        let mut i = 0usize;
167        while i < bytes.len() {
168            bytes[i] = i as u8;
169            i += 1;
170        }
171        let expected = sha384(&bytes);
172        let orig = store_original(&bytes, bytes.len() as u32).unwrap();
173        assert_eq!(orig.digest, expected);
174        let src = MemorySource::from_slice(&bytes);
175        let mut page = [0u8; STREAM_PAGE_BYTES as usize];
176        let streamed = stream_original(&src, bytes.len() as u32, expected, &mut page).unwrap();
177        assert_eq!(streamed.digest, orig.digest);
178        assert_eq!(streamed.len, orig.len);
179        let mut wrong = expected;
180        wrong.0[0] ^= 1;
181        assert_eq!(
182            stream_original(&src, bytes.len() as u32, wrong, &mut page),
183            Err(QdnfError::Conflict)
184        );
185        assert_eq!(
186            stream_original(&src, 16, expected, &mut page),
187            Err(QdnfError::Range)
188        );
189    }
190}