Skip to main content

qualia_core_db/governance/
cohort_access_gate.rs

1//! Permission-Scoped Query, Explanation & Derivative Access Gate (`C4–C5`).
2//!
3//! Enforces sensitivity tiers in `context[56..63]` (`PUBLIC=0`, `RESTRICTED=1`, `CLASSIFIED=2`)
4//! and human principal / delegated-agent authority (`AUTH-H1..H6`) across source queries,
5//! cohort estimates, inference explanations, error logs, and HMC export bundles.
6//!
7//! Invariant (`C4`): Aggregation or estimation never auto-declassifies restricted inputs.
8
9use core::fmt;
10use crate::NQuin;
11
12pub const SENSITIVITY_SHIFT: u32 = 56;
13pub const SENSITIVITY_PUBLIC: u8 = 0;
14pub const SENSITIVITY_RESTRICTED: u8 = 1;
15pub const SENSITIVITY_CLASSIFIED: u8 = 2;
16pub const CONTEXT_GRAPH_MASK: u64 = 0x00FF_FFFF_FFFF_FFFF;
17pub const SENSITIVITY_MASK: u64 = 0xFFu64 << SENSITIVITY_SHIFT;
18
19/// Scoped grant binding a human principal and an optional delegated agent.
20///
21/// Direct human action sets `agent_did_hash = 0`. Delegated action sets `agent_did_hash != 0`.
22/// Missing human principal (`human_principal_did_hash = 0`) is always denied (`AUTH-H1..H6`).
23#[repr(C)]
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub struct PrincipalAndAgentGrant {
26    pub human_principal_did_hash: u64,
27    pub agent_did_hash: u64,
28    pub authorized_context_hash: u64,
29    pub max_sensitivity_class: u8,
30    pub allow_derivative_export: bool,
31    pub allow_explanation_trace: bool,
32    pub issued_epoch: u64,
33    pub expiry_epoch: u64,
34    pub revoked: bool,
35}
36
37impl PrincipalAndAgentGrant {
38    #[inline]
39    pub const fn direct_human(human: u64, ctx: u64, sens: u8, issued: u64, expiry: u64) -> Self {
40        Self {
41            human_principal_did_hash: human,
42            agent_did_hash: 0,
43            authorized_context_hash: ctx,
44            max_sensitivity_class: sens,
45            allow_derivative_export: true,
46            allow_explanation_trace: true,
47            issued_epoch: issued,
48            expiry_epoch: expiry,
49            revoked: false,
50        }
51    }
52
53    #[inline]
54    pub const fn delegated_agent(
55        human: u64, agent: u64, ctx: u64, sens: u8, deriv: bool, trace: bool, issued: u64, expiry: u64,
56    ) -> Self {
57        Self {
58            human_principal_did_hash: human,
59            agent_did_hash: agent,
60            authorized_context_hash: ctx,
61            max_sensitivity_class: sens,
62            allow_derivative_export: deriv,
63            allow_explanation_trace: trace,
64            issued_epoch: issued,
65            expiry_epoch: expiry,
66            revoked: false,
67        }
68    }
69
70    #[inline(always)]
71    pub const fn is_direct_human(&self) -> bool { self.agent_did_hash == 0 }
72    #[inline(always)]
73    pub const fn is_delegated_agent(&self) -> bool { self.agent_did_hash != 0 }
74}
75
76/// Zero-heap receipt returned after filtering a candidate cohort NQuin slice.
77#[repr(C)]
78#[derive(Clone, Copy, Debug, PartialEq, Eq)]
79pub struct CohortAccessReceipt {
80    pub admitted_count: usize,
81    pub redacted_count: usize,
82    pub inherited_max_sensitivity: u8,
83}
84
85impl CohortAccessReceipt {
86    #[inline(always)]
87    pub const fn is_all_admitted(&self) -> bool { self.redacted_count == 0 }
88    #[inline(always)]
89    pub const fn total_examined(&self) -> usize { self.admitted_count + self.redacted_count }
90}
91
92#[derive(Clone, Copy, Debug, PartialEq, Eq)]
93pub enum AccessGateError {
94    MissingHumanPrincipal,
95    GrantRevoked,
96    GrantExpired { current_epoch: u64, expiry_epoch: u64 },
97    GrantNotYetValid { current_epoch: u64, issued_epoch: u64 },
98    InvalidEpochRange { issued_epoch: u64, expiry_epoch: u64 },
99    SensitivityExceeded { quin_sensitivity: u8, max_sensitivity: u8 },
100    ContextUnauthorized { requested_context: u64, authorized_context: u64 },
101    DeclassificationForbidden { required_sensitivity: u8, target_sensitivity: u8 },
102    ExplanationTraceForbidden,
103    DerivativeExportForbidden,
104    OutputBufferTooSmall { required: usize, available: usize },
105}
106
107impl fmt::Display for AccessGateError {
108    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
109        match self {
110            Self::MissingHumanPrincipal => write!(f, "Missing or unauthenticated human principal (DID hash 0)"),
111            Self::GrantRevoked => write!(f, "Principal or agent grant has been revoked"),
112            Self::GrantExpired { current_epoch, expiry_epoch } => write!(f, "Grant expired at {} (current {})", expiry_epoch, current_epoch),
113            Self::GrantNotYetValid { current_epoch, issued_epoch } => write!(f, "Grant not valid until {} (current {})", issued_epoch, current_epoch),
114            Self::InvalidEpochRange { issued_epoch, expiry_epoch } => write!(f, "issued_epoch {} > expiry_epoch {}", issued_epoch, expiry_epoch),
115            Self::SensitivityExceeded { quin_sensitivity, max_sensitivity } => write!(f, "Quin sensitivity {} > max {}", quin_sensitivity, max_sensitivity),
116            Self::ContextUnauthorized { requested_context, authorized_context } => write!(f, "Context {:014x} unauthorized (authorized {:014x})", requested_context, authorized_context),
117            Self::DeclassificationForbidden { required_sensitivity, target_sensitivity } => write!(f, "Declassification forbidden: input sensitivity {} > target {}", required_sensitivity, target_sensitivity),
118            Self::ExplanationTraceForbidden => write!(f, "Explanation trace forbidden by grant"),
119            Self::DerivativeExportForbidden => write!(f, "Derivative export forbidden by grant"),
120            Self::OutputBufferTooSmall { required, available } => write!(f, "Output buffer too small: required {}, available {}", required, available),
121        }
122    }
123}
124
125impl std::error::Error for AccessGateError {}
126
127#[inline(always)]
128pub const fn extract_sensitivity_class(context: u64) -> u8 { ((context >> SENSITIVITY_SHIFT) & 0xFF) as u8 }
129#[inline(always)]
130pub const fn extract_graph_context_hash(context: u64) -> u64 { context & CONTEXT_GRAPH_MASK }
131#[inline(always)]
132pub const fn pack_context_with_sensitivity(graph_hash_56bit: u64, sensitivity: u8) -> u64 {
133    (graph_hash_56bit & CONTEXT_GRAPH_MASK) | ((sensitivity as u64) << SENSITIVITY_SHIFT)
134}
135
136/// Validates that the grant has an authentic human principal, is within its validity epoch,
137/// and has not been revoked.
138pub fn verify_grant_active(grant: &PrincipalAndAgentGrant, current_epoch: u64) -> Result<(), AccessGateError> {
139    if grant.human_principal_did_hash == 0 { return Err(AccessGateError::MissingHumanPrincipal); }
140    if grant.revoked { return Err(AccessGateError::GrantRevoked); }
141    if grant.issued_epoch > grant.expiry_epoch {
142        return Err(AccessGateError::InvalidEpochRange { issued_epoch: grant.issued_epoch, expiry_epoch: grant.expiry_epoch });
143    }
144    if current_epoch < grant.issued_epoch {
145        return Err(AccessGateError::GrantNotYetValid { current_epoch, issued_epoch: grant.issued_epoch });
146    }
147    if current_epoch > grant.expiry_epoch {
148        return Err(AccessGateError::GrantExpired { current_epoch, expiry_epoch: grant.expiry_epoch });
149    }
150    Ok(())
151}
152
153/// Zero-heap filter for candidate cohort Quins before query evaluation or statistical estimation.
154pub fn filter_authorized_cohort_quins(
155    quins: &[NQuin],
156    grant: &PrincipalAndAgentGrant,
157    current_epoch: u64,
158    out: &mut [NQuin],
159) -> Result<CohortAccessReceipt, AccessGateError> {
160    verify_grant_active(grant, current_epoch)?;
161
162    let mut admitted_count = 0;
163    let mut redacted_count = 0;
164    let mut inherited_max_sensitivity = SENSITIVITY_PUBLIC;
165
166    for q in quins {
167        let quin_sens = extract_sensitivity_class(q.context);
168        let quin_graph = extract_graph_context_hash(q.context);
169
170        let context_ok = grant.authorized_context_hash == 0
171            || quin_graph == grant.authorized_context_hash
172            || (quin_sens == SENSITIVITY_PUBLIC && quin_graph == 0);
173
174        let sensitivity_ok = quin_sens <= grant.max_sensitivity_class;
175
176        if context_ok && sensitivity_ok {
177            if admitted_count >= out.len() {
178                return Err(AccessGateError::OutputBufferTooSmall {
179                    required: admitted_count + 1,
180                    available: out.len(),
181                });
182            }
183            out[admitted_count] = *q;
184            admitted_count += 1;
185            if quin_sens > inherited_max_sensitivity {
186                inherited_max_sensitivity = quin_sens;
187            }
188        } else {
189            redacted_count += 1;
190        }
191    }
192
193    Ok(CohortAccessReceipt {
194        admitted_count,
195        redacted_count,
196        inherited_max_sensitivity,
197    })
198}
199
200/// Enforces C4: Aggregation or estimation never auto-declassifies restricted inputs.
201///
202/// If any source Quin has sensitivity `> target_export_sensitivity`, fails closed with
203/// `DeclassificationForbidden`. Requires derivative or explanation export permissions.
204pub fn authorize_derivative_or_explanation_export(
205    source_quins: &[NQuin],
206    grant: &PrincipalAndAgentGrant,
207    target_export_sensitivity: u8,
208    is_explanation_trace: bool,
209    current_epoch: u64,
210) -> Result<u64, AccessGateError> {
211    verify_grant_active(grant, current_epoch)?;
212
213    if is_explanation_trace {
214        if !grant.allow_explanation_trace {
215            return Err(AccessGateError::ExplanationTraceForbidden);
216        }
217    } else if !grant.allow_derivative_export {
218        return Err(AccessGateError::DerivativeExportForbidden);
219    }
220
221    let mut required_sensitivity = SENSITIVITY_PUBLIC;
222    for q in source_quins {
223        let quin_sens = extract_sensitivity_class(q.context);
224        let quin_graph = extract_graph_context_hash(q.context);
225
226        if grant.authorized_context_hash != 0
227            && quin_graph != grant.authorized_context_hash
228            && !(quin_sens == SENSITIVITY_PUBLIC && quin_graph == 0)
229        {
230            return Err(AccessGateError::ContextUnauthorized {
231                requested_context: quin_graph,
232                authorized_context: grant.authorized_context_hash,
233            });
234        }
235
236        if quin_sens > required_sensitivity {
237            required_sensitivity = quin_sens;
238        }
239    }
240
241    if required_sensitivity > grant.max_sensitivity_class {
242        return Err(AccessGateError::SensitivityExceeded {
243            quin_sensitivity: required_sensitivity,
244            max_sensitivity: grant.max_sensitivity_class,
245        });
246    }
247
248    if required_sensitivity > target_export_sensitivity {
249        return Err(AccessGateError::DeclassificationForbidden {
250            required_sensitivity,
251            target_sensitivity: target_export_sensitivity,
252        });
253    }
254
255    let mut auth_token = grant.human_principal_did_hash
256        ^ grant.agent_did_hash.rotate_left(17)
257        ^ ((target_export_sensitivity as u64) << SENSITIVITY_SHIFT)
258        ^ grant.authorized_context_hash.rotate_left(7)
259        ^ current_epoch;
260
261    for q in source_quins {
262        auth_token = auth_token.wrapping_mul(0x1000_0000_1B3) ^ q.parity ^ q.context;
263    }
264
265    let salt = if is_explanation_trace { 0x5452_4143_4530_3031 } else { 0x4445_5249_5630_3031 };
266    Ok(auth_token ^ salt)
267}
268
269/// Point check for single-Quin read access under an active grant.
270pub fn validate_quin_access(
271    quin: &NQuin,
272    grant: &PrincipalAndAgentGrant,
273    current_epoch: u64,
274) -> Result<u8, AccessGateError> {
275    verify_grant_active(grant, current_epoch)?;
276    let quin_sens = extract_sensitivity_class(quin.context);
277    let quin_graph = extract_graph_context_hash(quin.context);
278
279    let context_ok = grant.authorized_context_hash == 0
280        || quin_graph == grant.authorized_context_hash
281        || (quin_sens == SENSITIVITY_PUBLIC && quin_graph == 0);
282
283    if !context_ok {
284        return Err(AccessGateError::ContextUnauthorized {
285            requested_context: quin_graph,
286            authorized_context: grant.authorized_context_hash,
287        });
288    }
289    if quin_sens > grant.max_sensitivity_class {
290        return Err(AccessGateError::SensitivityExceeded {
291            quin_sensitivity: quin_sens,
292            max_sensitivity: grant.max_sensitivity_class,
293        });
294    }
295    Ok(quin_sens)
296}
297
298// ── Unit Tests ──────────────────────────────────────────────────────────────
299
300#[cfg(test)]
301mod tests {
302    use super::*;
303
304    const HUMAN_DID: u64 = 0x0011_2233_4455_6677;
305    const AGENT_DID: u64 = 0x0088_99AA_BBCC_DDEE;
306    const CTX_CORPUS: u64 = 0x0000_AABB_CCDD_EEFF;
307    const CTX_OTHER: u64 = 0x0000_1111_2222_3333;
308
309    fn test_quin(subject: u64, context_hash: u64, sensitivity: u8) -> NQuin {
310        let mut q = NQuin {
311            subject,
312            predicate: 0x1000,
313            object: 0x2000,
314            context: pack_context_with_sensitivity(context_hash, sensitivity),
315            metadata: 0,
316            parity: 0,
317        };
318        q.recalculate_parity();
319        q
320    }
321
322    #[test]
323    fn test_context_sensitivity_packing_roundtrip() {
324        let p1 = pack_context_with_sensitivity(CTX_CORPUS, SENSITIVITY_RESTRICTED);
325        assert_eq!((extract_sensitivity_class(p1), extract_graph_context_hash(p1)), (SENSITIVITY_RESTRICTED, CTX_CORPUS));
326
327        let p2 = pack_context_with_sensitivity(CTX_CORPUS, SENSITIVITY_CLASSIFIED);
328        assert_eq!((extract_sensitivity_class(p2), extract_graph_context_hash(p2)), (SENSITIVITY_CLASSIFIED, CTX_CORPUS));
329    }
330
331    #[test]
332    fn test_valid_human_and_delegated_agent_read_authorized_cohort() {
333        let quins = [
334            test_quin(1, CTX_CORPUS, SENSITIVITY_PUBLIC),
335            test_quin(2, CTX_CORPUS, SENSITIVITY_RESTRICTED),
336            test_quin(3, 0, SENSITIVITY_PUBLIC),
337        ];
338        let mut out = [NQuin::default(); 4];
339
340        let human = PrincipalAndAgentGrant::direct_human(HUMAN_DID, CTX_CORPUS, SENSITIVITY_RESTRICTED, 100, 200);
341        let rec = filter_authorized_cohort_quins(&quins, &human, 150, &mut out).unwrap();
342        assert_eq!((rec.admitted_count, rec.redacted_count, rec.inherited_max_sensitivity), (3, 0, SENSITIVITY_RESTRICTED));
343
344        let agent = PrincipalAndAgentGrant::delegated_agent(HUMAN_DID, AGENT_DID, CTX_CORPUS, SENSITIVITY_RESTRICTED, true, true, 100, 200);
345        let rec_ag = filter_authorized_cohort_quins(&quins, &agent, 150, &mut out).unwrap();
346        assert_eq!(rec_ag.admitted_count, 3);
347    }
348
349    #[test]
350    fn test_negative_declassification_forbidden_on_restricted_or_classified_cohort() {
351        let cohort_r = [test_quin(1, CTX_CORPUS, SENSITIVITY_PUBLIC), test_quin(2, CTX_CORPUS, SENSITIVITY_RESTRICTED)];
352        let grant = PrincipalAndAgentGrant::direct_human(HUMAN_DID, CTX_CORPUS, SENSITIVITY_CLASSIFIED, 100, 200);
353
354        let err = authorize_derivative_or_explanation_export(&cohort_r, &grant, SENSITIVITY_PUBLIC, false, 150).unwrap_err();
355        assert_eq!(err, AccessGateError::DeclassificationForbidden { required_sensitivity: SENSITIVITY_RESTRICTED, target_sensitivity: SENSITIVITY_PUBLIC });
356
357        let cohort_c = [test_quin(1, CTX_CORPUS, SENSITIVITY_CLASSIFIED)];
358        let err2 = authorize_derivative_or_explanation_export(&cohort_c, &grant, SENSITIVITY_RESTRICTED, false, 150).unwrap_err();
359        assert_eq!(err2, AccessGateError::DeclassificationForbidden { required_sensitivity: SENSITIVITY_CLASSIFIED, target_sensitivity: SENSITIVITY_RESTRICTED });
360    }
361
362    #[test]
363    fn test_negative_missing_principal_expired_or_revoked_fails_closed() {
364        let quins = [test_quin(1, CTX_CORPUS, SENSITIVITY_PUBLIC)];
365        let mut out = [NQuin::default(); 2];
366
367        let invalid_p = PrincipalAndAgentGrant::delegated_agent(0, AGENT_DID, CTX_CORPUS, SENSITIVITY_PUBLIC, true, true, 100, 200);
368        assert_eq!(filter_authorized_cohort_quins(&quins, &invalid_p, 150, &mut out).unwrap_err(), AccessGateError::MissingHumanPrincipal);
369
370        let exp = PrincipalAndAgentGrant::direct_human(HUMAN_DID, CTX_CORPUS, SENSITIVITY_PUBLIC, 100, 200);
371        assert_eq!(filter_authorized_cohort_quins(&quins, &exp, 201, &mut out).unwrap_err(), AccessGateError::GrantExpired { current_epoch: 201, expiry_epoch: 200 });
372
373        let mut rev = exp;
374        rev.revoked = true;
375        assert_eq!(filter_authorized_cohort_quins(&quins, &rev, 150, &mut out).unwrap_err(), AccessGateError::GrantRevoked);
376
377        let mut bad_epoch = exp;
378        bad_epoch.issued_epoch = 500;
379        bad_epoch.expiry_epoch = 200;
380        assert_eq!(verify_grant_active(&bad_epoch, 150).unwrap_err(), AccessGateError::InvalidEpochRange { issued_epoch: 500, expiry_epoch: 200 });
381    }
382
383    #[test]
384    fn test_negative_unauthorized_explanation_trace_fails_closed() {
385        let quins = [test_quin(1, CTX_CORPUS, SENSITIVITY_PUBLIC)];
386        let grant_no_trace = PrincipalAndAgentGrant::delegated_agent(HUMAN_DID, AGENT_DID, CTX_CORPUS, SENSITIVITY_PUBLIC, true, false, 100, 200);
387        let err = authorize_derivative_or_explanation_export(&quins, &grant_no_trace, SENSITIVITY_PUBLIC, true, 150).unwrap_err();
388        assert_eq!(err, AccessGateError::ExplanationTraceForbidden);
389    }
390
391    #[test]
392    fn test_derivative_export_forbidden_and_context_isolation() {
393        let quins = [test_quin(1, CTX_CORPUS, SENSITIVITY_PUBLIC)];
394        let no_export = PrincipalAndAgentGrant::delegated_agent(HUMAN_DID, AGENT_DID, CTX_CORPUS, SENSITIVITY_PUBLIC, false, true, 100, 200);
395        assert_eq!(authorize_derivative_or_explanation_export(&quins, &no_export, SENSITIVITY_PUBLIC, false, 150).unwrap_err(), AccessGateError::DerivativeExportForbidden);
396
397        let foreign_quins = [test_quin(1, CTX_OTHER, SENSITIVITY_RESTRICTED)];
398        let grant_corpus = PrincipalAndAgentGrant::direct_human(HUMAN_DID, CTX_CORPUS, SENSITIVITY_RESTRICTED, 100, 200);
399        let err_ctx = authorize_derivative_or_explanation_export(&foreign_quins, &grant_corpus, SENSITIVITY_RESTRICTED, false, 150).unwrap_err();
400        assert_eq!(err_ctx, AccessGateError::ContextUnauthorized { requested_context: CTX_OTHER, authorized_context: CTX_CORPUS });
401    }
402
403    #[test]
404    fn test_redaction_and_buffer_overflow_handling() {
405        let quins = [test_quin(1, CTX_CORPUS, SENSITIVITY_PUBLIC), test_quin(2, CTX_CORPUS, SENSITIVITY_CLASSIFIED)];
406        let grant = PrincipalAndAgentGrant::direct_human(HUMAN_DID, CTX_CORPUS, SENSITIVITY_RESTRICTED, 100, 200);
407
408        let mut out = [NQuin::default(); 2];
409        let rec = filter_authorized_cohort_quins(&quins, &grant, 150, &mut out).unwrap();
410        assert_eq!((rec.admitted_count, rec.redacted_count, rec.inherited_max_sensitivity, out[0].subject), (1, 1, SENSITIVITY_PUBLIC, 1));
411
412        let mut tiny_out = [];
413        assert_eq!(filter_authorized_cohort_quins(&quins, &grant, 150, &mut tiny_out).unwrap_err(), AccessGateError::OutputBufferTooSmall { required: 1, available: 0 });
414    }
415
416    #[test]
417    fn test_successful_derivative_export_auth_token() {
418        let quins = [test_quin(1, CTX_CORPUS, SENSITIVITY_PUBLIC), test_quin(2, CTX_CORPUS, SENSITIVITY_RESTRICTED)];
419        let grant = PrincipalAndAgentGrant::direct_human(HUMAN_DID, CTX_CORPUS, SENSITIVITY_RESTRICTED, 100, 200);
420
421        let tok = authorize_derivative_or_explanation_export(&quins, &grant, SENSITIVITY_RESTRICTED, false, 150).unwrap();
422        let trace_tok = authorize_derivative_or_explanation_export(&quins, &grant, SENSITIVITY_RESTRICTED, true, 150).unwrap();
423        assert!(tok != 0 && trace_tok != 0 && tok != trace_tok);
424    }
425}