Skip to main content

qualia_core_db/net/qdnf/clinical/mailbox/
mod.rs

1//! Encrypted mailbox: bounded ciphertext bytes, not length + digest only.
2//! Transport never asserts review.
3
4use super::{first_empty, require_active_mutual, MAX_SLOTS};
5#[cfg(test)]
6use crate::crypto::network::digest::sha384;
7use crate::net::qdnf::authority::ContactState;
8use crate::net::qdnf::errors::QdnfError;
9use crate::net::qdnf::policy_labels::VerifiedLabel;
10use crate::net::qdnf::types::StrongDigest;
11use sha2::{Digest, Sha384};
12
13mod lifecycle;
14mod slot;
15
16pub use lifecycle::Mailbox;
17pub use slot::{
18    network_asserts_clinical_review, MailboxSlot, MailboxState, MAILBOX_CIPHERTEXT_BYTES,
19    STREAM_PAGE_BYTES,
20};
21
22/// Offline queued ciphertext metadata. Expired packages stay sealed.
23#[repr(C)]
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub struct OfflineSlot {
26    pub recipient: StrongDigest,
27    pub expires_unix: u64,
28    pub ciphertext_len: u32,
29    pub ciphertext_digest: StrongDigest,
30}
31
32#[derive(Clone, Copy, Debug)]
33pub struct OfflineQueue {
34    slots: [Option<OfflineSlot>; MAX_SLOTS],
35}
36
37impl OfflineQueue {
38    /// Creates a default `OfflineQueue`.
39    pub const fn new() -> Self {
40        Self {
41            slots: [None; MAX_SLOTS],
42        }
43    }
44
45    /// Fetches an entry by key; `None` when absent.
46    pub fn get(&self, slot: usize) -> Result<OfflineSlot, QdnfError> {
47        if slot >= MAX_SLOTS {
48            return Err(QdnfError::Range);
49        }
50        self.slots[slot].ok_or(QdnfError::Closed)
51    }
52}
53
54impl Default for OfflineQueue {
55    fn default() -> Self {
56        Self::new()
57    }
58}
59
60/// Enqueues an offline message.
61pub fn enqueue_offline(
62    queue: &mut OfflineQueue,
63    slot: OfflineSlot,
64    _now: u64,
65) -> Result<usize, QdnfError> {
66    if slot.recipient == StrongDigest::ZERO
67        || slot.ciphertext_len == 0
68        || slot.ciphertext_digest == StrongDigest::ZERO
69    {
70        return Err(QdnfError::Malformed);
71    }
72    let i = first_empty(&queue.slots).ok_or(QdnfError::Capacity)?;
73    queue.slots[i] = Some(slot);
74    Ok(i)
75}
76
77/// Release a queued package. Expiry and live Active contact are checked here.
78pub fn release_queued(
79    queue: &OfflineQueue,
80    slot: usize,
81    now: u64,
82    patient_contact: ContactState,
83    clinician_contact: ContactState,
84) -> Result<(), QdnfError> {
85    let item = queue.get(slot)?;
86    if now >= item.expires_unix {
87        return Err(QdnfError::Expired);
88    }
89    require_active_mutual(patient_contact, clinician_contact)?;
90    Ok(())
91}
92
93fn digest_pages(bytes: &[u8]) -> StrongDigest {
94    let mut hasher = Sha384::new();
95    let mut off = 0usize;
96    while off < bytes.len() {
97        let end = core::cmp::min(off + STREAM_PAGE_BYTES as usize, bytes.len());
98        hasher.update(&bytes[off..end]);
99        off = end;
100    }
101    let out = hasher.finalize();
102    let mut d = StrongDigest::ZERO;
103    d.0.copy_from_slice(&out);
104    d
105}
106
107/// Digest `bytes` in [`STREAM_PAGE_BYTES`] pages.
108pub fn digest_attachment_pages(bytes: &[u8]) -> Result<StrongDigest, QdnfError> {
109    if bytes.is_empty() {
110        return Err(QdnfError::Malformed);
111    }
112    Ok(digest_pages(bytes))
113}
114
115/// Stream caller-owned pages and verify the running SHA-384.
116pub fn stream_attachment(
117    bytes: &[u8],
118    expected_len: u32,
119    expected: StrongDigest,
120    page: &mut [u8],
121) -> Result<StrongDigest, QdnfError> {
122    if expected == StrongDigest::ZERO || bytes.is_empty() {
123        return Err(QdnfError::Malformed);
124    }
125    let len = u32::try_from(bytes.len()).map_err(|_| QdnfError::Range)?;
126    if len != expected_len {
127        return Err(QdnfError::Range);
128    }
129    if page.is_empty() {
130        return Err(QdnfError::Capacity);
131    }
132    let mut hasher = Sha384::new();
133    let mut off = 0usize;
134    let cap = if page.len() > STREAM_PAGE_BYTES as usize {
135        STREAM_PAGE_BYTES as usize
136    } else {
137        page.len()
138    };
139    while off < bytes.len() {
140        let want = core::cmp::min(cap, bytes.len() - off);
141        page[..want].copy_from_slice(&bytes[off..off + want]);
142        hasher.update(&page[..want]);
143        off += want;
144    }
145    let out = hasher.finalize();
146    let mut d = StrongDigest::ZERO;
147    d.0.copy_from_slice(&out);
148    if d != expected {
149        return Err(QdnfError::Conflict);
150    }
151    Ok(d)
152}
153
154/// Patient-record association is independent of network identity.
155pub fn patient_record_associated(
156    patient: StrongDigest,
157    record: StrongDigest,
158    bound_patient: StrongDigest,
159) -> Result<(), QdnfError> {
160    if patient == StrongDigest::ZERO || record == StrongDigest::ZERO {
161        return Err(QdnfError::Malformed);
162    }
163    if patient != bound_patient {
164        return Err(QdnfError::Denied);
165    }
166    Ok(())
167}
168
169/// Reviewed interchange adapter. Networking does not encode a medical decision.
170#[repr(C)]
171#[derive(Clone, Copy, Debug, PartialEq, Eq)]
172pub struct InterchangeAdapter {
173    pub mapping_digest: StrongDigest,
174    pub retains_full_label: bool,
175}
176
177/// Exports the mailbox as interchange.
178pub fn export_interchange(
179    label: &VerifiedLabel,
180    adapter: &InterchangeAdapter,
181) -> Result<VerifiedLabel, QdnfError> {
182    if adapter.mapping_digest == StrongDigest::ZERO {
183        return Err(QdnfError::Malformed);
184    }
185    if !adapter.retains_full_label {
186        return Err(QdnfError::Denied);
187    }
188    Ok(*label)
189}
190
191#[cfg(test)]
192mod tests {
193    use super::*;
194
195    fn d(tag: u8) -> StrongDigest {
196        let mut x = StrongDigest::ZERO;
197        x.0[0] = tag;
198        x
199    }
200
201    #[test]
202    fn offline_expiry_and_inactive_contact() {
203        let mut q = OfflineQueue::new();
204        let slot = enqueue_offline(
205            &mut q,
206            OfflineSlot {
207                recipient: d(2),
208                expires_unix: 20,
209                ciphertext_len: 8,
210                ciphertext_digest: d(9),
211            },
212            1,
213        )
214        .unwrap();
215        assert!(release_queued(&q, slot, 10, ContactState::Active, ContactState::Active).is_ok());
216        assert_eq!(
217            release_queued(&q, slot, 20, ContactState::Active, ContactState::Active),
218            Err(QdnfError::Expired)
219        );
220        assert_eq!(
221            release_queued(&q, slot, 10, ContactState::Active, ContactState::Suspended),
222            Err(QdnfError::Denied)
223        );
224        assert_eq!(q.get(slot).unwrap().ciphertext_digest, d(9));
225    }
226
227    #[test]
228    fn attachment_pages_match_sha384_and_association() {
229        let bytes = [0x11u8; 80];
230        let digest = digest_attachment_pages(&bytes).unwrap();
231        assert_eq!(digest, sha384(&bytes));
232        let mut page = [0u8; STREAM_PAGE_BYTES as usize];
233        assert_eq!(
234            stream_attachment(&bytes, 80, digest, &mut page).unwrap(),
235            digest
236        );
237        let mut wrong = digest;
238        wrong.0[0] ^= 1;
239        assert_eq!(
240            stream_attachment(&bytes, 80, wrong, &mut page),
241            Err(QdnfError::Conflict)
242        );
243        assert!(patient_record_associated(d(1), d(3), d(1)).is_ok());
244        assert_eq!(
245            patient_record_associated(d(1), d(3), d(2)),
246            Err(QdnfError::Denied)
247        );
248        assert!(!network_asserts_clinical_review());
249        let mut fields = crate::net::qdnf::policy_labels::LabelFields::request(
250            crate::net::qdnf::policy_labels::Confidentiality::C2Sensitive,
251            d(1),
252        );
253        fields.audience = d(2);
254        let mut buf = [0u8; 256];
255        let n = crate::net::qdnf::policy_labels::encode_label_into(&fields, &mut buf).unwrap();
256        let lab = crate::net::qdnf::policy_labels::verify_label(fields, &buf[..n]).unwrap();
257        let adapter = InterchangeAdapter {
258            mapping_digest: d(0x44),
259            retains_full_label: true,
260        };
261        assert_eq!(export_interchange(&lab, &adapter).unwrap(), lab);
262        assert_eq!(
263            export_interchange(
264                &lab,
265                &InterchangeAdapter {
266                    mapping_digest: d(0x44),
267                    retains_full_label: false,
268                }
269            ),
270            Err(QdnfError::Denied)
271        );
272    }
273}