Skip to main content

qualia_core_db/net/qdnf/policy_labels/
egress.rs

1//! Egress and materialisation admission. Every sink uses the same checks.
2
3use super::flow::JobLabelContext;
4use super::projection::{project_sink, DerivedSink};
5use super::types::{Confidentiality, LabelFields};
6use crate::net::qdnf::errors::QdnfError;
7use crate::net::qdnf::types::StrongDigest;
8use crate::{q_hash, NQuin};
9
10/// Host callers that must not grow a private egress path.
11#[repr(u8)]
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub enum EgressCaller {
14    Vibe = 1,
15    Poet = 2,
16    BackgroundWorker = 3,
17    DelegatedTool = 4,
18}
19
20/// Admit an egress sink. Recipient, compartment, purpose and environment are
21/// all checked. A missing check is [`QdnfError::Denied`]. Digests only.
22pub fn admit_egress(
23    job: &JobLabelContext,
24    recipient: StrongDigest,
25    compartment: StrongDigest,
26    purpose: StrongDigest,
27    env_profile: u8,
28) -> Result<(), QdnfError> {
29    let fields = job.current();
30    if fields.confidentiality.is_unknown() {
31        return Err(QdnfError::Denied);
32    }
33    check_recipient(fields, recipient)?;
34    check_compartment(fields, compartment)?;
35    check_purpose(fields, purpose)?;
36    check_environment(fields.confidentiality, env_profile)?;
37    Ok(())
38}
39
40/// Vibe, Poet, background workers and delegated tools share [`admit_egress`].
41pub fn admit_caller_egress(
42    job: &JobLabelContext,
43    _caller: EgressCaller,
44    sink: DerivedSink,
45    recipient: StrongDigest,
46    compartment: StrongDigest,
47    purpose: StrongDigest,
48    env_profile: u8,
49) -> Result<(), QdnfError> {
50    let _projected = project_sink(job, sink)?;
51    admit_egress(job, recipient, compartment, purpose, env_profile)
52}
53
54/// Storing a more-sensitive object under a weaker cache key is Denied.
55pub fn admit_cache_insert(
56    key_level: Confidentiality,
57    stored: Confidentiality,
58) -> Result<(), QdnfError> {
59    let key_rank = key_level.lattice_rank().map_err(|_| QdnfError::Denied)?;
60    let stored_rank = stored.lattice_rank().map_err(|_| QdnfError::Denied)?;
61    if stored_rank > key_rank {
62        return Err(QdnfError::Denied);
63    }
64    Ok(())
65}
66
67/// Zero-heap egress decision descriptor for QualiaDB `NQuin` enumeration (`NET-21`).
68#[repr(C)]
69#[derive(Clone, Copy, Debug, PartialEq, Eq)]
70pub struct EgressAuditReceipt {
71    pub caller: EgressCaller,
72    pub sink: DerivedSink,
73    pub confidentiality: Confidentiality,
74    pub recipient: StrongDigest,
75    pub compartment: StrongDigest,
76    pub purpose: StrongDigest,
77    pub env_profile: u8,
78    pub allowed: bool,
79}
80
81fn fold_digest_60(d: &StrongDigest, seed: u64) -> u64 {
82    let mut h = seed ^ 0xcbf2_9ce4_8422_2325u64;
83    let mut i = 0usize;
84    while i < d.0.len() {
85        h ^= d.0[i] as u64;
86        h = h.wrapping_mul(0x0100_0000_01b3);
87        i += 1;
88    }
89    h & 0x0FFF_FFFF_FFFF_FFFF
90}
91
92/// Enumerate an [`EgressAuditReceipt`] into a canonical 48-byte [`NQuin`] with 5-field XOR parity.
93pub fn enumerate_egress_audit_quin(
94    receipt: &EgressAuditReceipt,
95    context_hash: u64,
96    clock_epoch: u64,
97) -> NQuin {
98    let s0 = fold_digest_60(&receipt.recipient, receipt.caller as u64);
99    let s1 = fold_digest_60(&receipt.compartment, s0 ^ ((receipt.sink as u64) << 8));
100    let subject = fold_digest_60(&receipt.purpose, s1);
101    let predicate = q_hash("urn:qualia:q42:network:egressDecision") & 0x0FFF_FFFF_FFFF_FFFF;
102    let object = if receipt.allowed {
103        q_hash("urn:qualia:q42:network:EgressAllow") & 0x0FFF_FFFF_FFFF_FFFF
104    } else {
105        q_hash("urn:qualia:q42:network:EgressDeny") & 0x0FFF_FFFF_FFFF_FFFF
106    };
107    let context = if context_hash != 0 {
108        context_hash
109    } else {
110        q_hash("urn:qualia:q42:profile:network:1") & 0x0FFF_FFFF_FFFF_FFFF
111    };
112    let lamport = (clock_epoch & 0x1FFF_FFFF) << 32;
113    let low = (receipt.caller as u64)
114        | ((receipt.sink as u64) << 8)
115        | ((receipt.env_profile as u64) << 16)
116        | ((receipt.allowed as u64) << 24);
117    let metadata = lamport | low;
118    let parity = subject ^ predicate ^ object ^ context ^ metadata;
119    NQuin {
120        subject,
121        predicate,
122        object,
123        context,
124        metadata,
125        parity,
126    }
127}
128
129/// Evaluate [`admit_caller_egress`] and always emit a 5-field parity-verified [`NQuin`] audit record.
130pub fn admit_caller_egress_with_quin(
131    job: &JobLabelContext,
132    caller: EgressCaller,
133    sink: DerivedSink,
134    recipient: StrongDigest,
135    compartment: StrongDigest,
136    purpose: StrongDigest,
137    env_profile: u8,
138    context_hash: u64,
139    clock_epoch: u64,
140) -> (Result<(), QdnfError>, NQuin) {
141    let decision = admit_caller_egress(job, caller, sink, recipient, compartment, purpose, env_profile);
142    let receipt = EgressAuditReceipt {
143        caller,
144        sink,
145        confidentiality: job.current().confidentiality,
146        recipient,
147        compartment,
148        purpose,
149        env_profile,
150        allowed: decision.is_ok(),
151    };
152    let quin = enumerate_egress_audit_quin(&receipt, context_hash, clock_epoch);
153    (decision, quin)
154}
155
156/// Batch-enumerate egress decisions into caller-supplied [`NQuin`]s with 5-field XOR parity.
157pub fn enumerate_egress_decisions_to_quins(
158    receipts: &[EgressAuditReceipt],
159    context_hash: u64,
160    clock_epoch: u64,
161    out: &mut [NQuin],
162) -> usize {
163    let n = receipts.len().min(out.len());
164    let mut i = 0usize;
165    while i < n {
166        out[i] = enumerate_egress_audit_quin(
167            &receipts[i],
168            context_hash,
169            clock_epoch.saturating_add(i as u64),
170        );
171        i += 1;
172    }
173    n
174}
175
176fn check_recipient(fields: &LabelFields, recipient: StrongDigest) -> Result<(), QdnfError> {
177    if recipient.is_zero() {
178        return Err(QdnfError::Denied);
179    }
180    if fields.confidentiality.requires_audience() && fields.audience.is_zero() {
181        return Err(QdnfError::Denied);
182    }
183    if !fields.audience.is_zero() && recipient != fields.audience {
184        return Err(QdnfError::Unauthorized);
185    }
186    Ok(())
187}
188
189fn check_compartment(fields: &LabelFields, compartment: StrongDigest) -> Result<(), QdnfError> {
190    if fields.compartment_count == 0 {
191        return Ok(());
192    }
193    if compartment.is_zero() {
194        return Err(QdnfError::Denied);
195    }
196    if !contains(fields.compartments(), compartment) {
197        return Err(QdnfError::Denied);
198    }
199    Ok(())
200}
201
202fn check_purpose(fields: &LabelFields, purpose: StrongDigest) -> Result<(), QdnfError> {
203    if fields.purpose_count == 0 {
204        return Ok(());
205    }
206    if purpose.is_zero() {
207        return Err(QdnfError::Denied);
208    }
209    if !contains(fields.purposes(), purpose) {
210        return Err(QdnfError::Denied);
211    }
212    Ok(())
213}
214
215fn check_environment(conf: Confidentiality, env_profile: u8) -> Result<(), QdnfError> {
216    if env_profile == 0 {
217        return Err(QdnfError::Denied);
218    }
219    let need = match conf {
220        Confidentiality::C0Public | Confidentiality::C1Private => 1u8,
221        Confidentiality::C2Sensitive => 2,
222        Confidentiality::C3Compartmented => 3,
223        Confidentiality::Unknown => return Err(QdnfError::Denied),
224    };
225    if env_profile < need {
226        return Err(QdnfError::Denied);
227    }
228    Ok(())
229}
230
231fn contains(items: &[StrongDigest], item: StrongDigest) -> bool {
232    let mut i = 0usize;
233    while i < items.len() {
234        if items[i] == item {
235            return true;
236        }
237        i += 1;
238    }
239    false
240}
241
242#[cfg(test)]
243mod tests {
244    use super::*;
245    use crate::net::qdnf::policy_labels::types::LabelFields;
246
247    fn digest(b: u8) -> StrongDigest {
248        let mut d = StrongDigest::ZERO;
249        d.0[0] = b;
250        d.0[47] = 1;
251        d
252    }
253
254    fn c2_job() -> JobLabelContext {
255        let mut fields = LabelFields::request(Confidentiality::C2Sensitive, digest(1));
256        fields.audience = digest(9);
257        fields.compartment_count = 1;
258        fields.compartments[0] = digest(4);
259        fields.purpose_count = 1;
260        fields.purposes[0] = digest(5);
261        JobLabelContext::new(fields).unwrap()
262    }
263
264    #[test]
265    fn matching_egress_admits() {
266        let job = c2_job();
267        assert!(admit_egress(&job, digest(9), digest(4), digest(5), 2).is_ok());
268    }
269
270    #[test]
271    fn missing_recipient_is_denied() {
272        let job = c2_job();
273        assert_eq!(
274            admit_egress(&job, StrongDigest::ZERO, digest(4), digest(5), 2),
275            Err(QdnfError::Denied)
276        );
277    }
278
279    #[test]
280    fn missing_environment_is_denied() {
281        let job = c2_job();
282        assert_eq!(
283            admit_egress(&job, digest(9), digest(4), digest(5), 0),
284            Err(QdnfError::Denied)
285        );
286    }
287
288    #[test]
289    fn weak_environment_for_c2_is_denied() {
290        let job = c2_job();
291        assert_eq!(
292            admit_egress(&job, digest(9), digest(4), digest(5), 1),
293            Err(QdnfError::Denied)
294        );
295    }
296
297    #[test]
298    fn wrong_compartment_is_denied() {
299        let job = c2_job();
300        assert_eq!(
301            admit_egress(&job, digest(9), digest(8), digest(5), 2),
302            Err(QdnfError::Denied)
303        );
304    }
305
306    #[test]
307    fn vibe_poet_worker_use_same_function() {
308        let job = c2_job();
309        for caller in [
310            EgressCaller::Vibe,
311            EgressCaller::Poet,
312            EgressCaller::BackgroundWorker,
313            EgressCaller::DelegatedTool,
314        ] {
315            assert!(admit_caller_egress(
316                &job,
317                caller,
318                DerivedSink::Export,
319                digest(9),
320                digest(4),
321                digest(5),
322                2,
323            )
324            .is_ok());
325        }
326    }
327
328    #[test]
329    fn cache_c2_under_c0_key_is_denied() {
330        assert_eq!(
331            admit_cache_insert(Confidentiality::C0Public, Confidentiality::C2Sensitive),
332            Err(QdnfError::Denied)
333        );
334        assert!(
335            admit_cache_insert(Confidentiality::C2Sensitive, Confidentiality::C2Sensitive).is_ok()
336        );
337    }
338
339    #[test]
340    fn covert_metadata_sink_inherits() {
341        let job = c2_job();
342        for sink in [DerivedSink::Log, DerivedSink::Receipt, DerivedSink::Backup] {
343            let projected = project_sink(&job, sink).unwrap();
344            assert_eq!(projected.confidentiality, Confidentiality::C2Sensitive);
345            assert!(admit_caller_egress(
346                &job,
347                EgressCaller::BackgroundWorker,
348                sink,
349                digest(9),
350                digest(4),
351                digest(5),
352                2,
353            )
354            .is_ok());
355        }
356    }
357
358    #[test]
359    fn delegated_tool_egress_uses_admit_egress() {
360        let job = c2_job();
361        assert_eq!(
362            admit_caller_egress(
363                &job,
364                EgressCaller::DelegatedTool,
365                DerivedSink::QueryResult,
366                StrongDigest::ZERO,
367                digest(4),
368                digest(5),
369                2,
370            ),
371            Err(QdnfError::Denied)
372        );
373    }
374
375    #[test]
376    fn egress_audit_quins_carry_five_field_parity_for_allow_and_deny() {
377        let job = c2_job();
378        let (allow_res, allow_q) = admit_caller_egress_with_quin(
379            &job,
380            EgressCaller::Vibe,
381            DerivedSink::Export,
382            digest(9),
383            digest(4),
384            digest(5),
385            2,
386            0,
387            42,
388        );
389        assert!(allow_res.is_ok());
390        assert_eq!(
391            allow_q.parity,
392            allow_q.subject ^ allow_q.predicate ^ allow_q.object ^ allow_q.context ^ allow_q.metadata
393        );
394        assert!(allow_q.verify_ecc_parity());
395
396        let (deny_res, deny_q) = admit_caller_egress_with_quin(
397            &job,
398            EgressCaller::DelegatedTool,
399            DerivedSink::QueryResult,
400            StrongDigest::ZERO,
401            digest(4),
402            digest(5),
403            2,
404            0,
405            43,
406        );
407        assert_eq!(deny_res, Err(QdnfError::Denied));
408        assert!(deny_q.verify_ecc_parity());
409        assert_ne!(allow_q.object, deny_q.object);
410    }
411}