1use 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#[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#[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
136pub 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
153pub 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
200pub 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
269pub 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#[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}