Skip to main content

qualia_core_db/bundle/stream/policy/remote/
recognition.rs

1//! Purpose-scoped recognition table. Metadata only; PinAuthority remains the key owner.
2use super::codec::DisclosureAction;
3use super::PolicyError as E;
4use crate::crypto::network::authority::PinHandle;
5use crate::crypto::network::entropy::fill_os;
6use crate::crypto::network::errors::CryptoError;
7use crate::crypto::network::object_stream::MAX_OBJECT_BYTES;
8use crate::net::qdnf::types::{Generation, OperationId, StrongDigest};
9
10pub const MAX_RECOGNIZED: usize = 8;
11
12/// Crate-local admin token analogous to LocalBootstrap. Not a wire role flag.
13pub struct RecognitionAdmin {
14    instance: [u8; 16],
15}
16
17/// Process-local selection of an enrolled controller row.
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub struct RecognitionHandle {
20    instance: [u8; 16],
21    slot: u8,
22    generation: Generation,
23}
24
25impl RecognitionHandle {
26    pub const fn generation(&self) -> Generation {
27        self.generation
28    }
29}
30
31/// Allowed ticket actions for one enrollment. Unknown bits refuse.
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub struct AllowedOps(u16);
34
35impl AllowedOps {
36    pub const METADATA_RELEASE: Self = Self(1);
37    pub const PAYLOAD_USE: Self = Self(2);
38    pub const BOTH: Self = Self(3);
39
40    pub fn from_bits(bits: u16) -> Result<Self, E> {
41        if bits == 0 || bits & !Self::BOTH.0 != 0 {
42            return Err(E::Reference);
43        }
44        Ok(Self(bits))
45    }
46
47    pub const fn bits(self) -> u16 {
48        self.0
49    }
50
51    pub const fn contains(self, action: DisclosureAction) -> bool {
52        self.0 & action.bit() != 0
53    }
54}
55
56/// Trusted host enrollment. Exact source/policy; no wildcard or delegation chain.
57#[derive(Clone, Copy, Debug)]
58pub struct RecognitionEnrollment {
59    pub pin: PinHandle,
60    pub principal: StrongDigest,
61    pub source: StrongDigest,
62    pub source_length: u64,
63    pub policy: StrongDigest,
64    pub publisher: StrongDigest,
65    pub purpose: StrongDigest,
66    pub allowed_ops: AllowedOps,
67    pub operation: OperationId,
68    pub expires_unix: u64,
69    pub max_decision_lifetime: u64,
70}
71
72/// Snapshot of a currently recognized controller. Not a disclosure grant.
73#[derive(Clone, Copy, Debug, PartialEq, Eq)]
74pub struct RecognizedController {
75    pin: PinHandle,
76    principal: StrongDigest,
77    source: StrongDigest,
78    source_length: u64,
79    policy: StrongDigest,
80    publisher: StrongDigest,
81    purpose: StrongDigest,
82    allowed_ops: AllowedOps,
83    operation: OperationId,
84    expires_unix: u64,
85    max_decision_lifetime: u64,
86    controller_generation: Generation,
87    decision_id_floor: u64,
88}
89
90impl RecognizedController {
91    pub const fn pin(&self) -> PinHandle {
92        self.pin
93    }
94    pub const fn principal(&self) -> StrongDigest {
95        self.principal
96    }
97    pub const fn source(&self) -> StrongDigest {
98        self.source
99    }
100    pub const fn source_length(&self) -> u64 {
101        self.source_length
102    }
103    pub const fn policy(&self) -> StrongDigest {
104        self.policy
105    }
106    pub const fn publisher(&self) -> StrongDigest {
107        self.publisher
108    }
109    pub const fn purpose(&self) -> StrongDigest {
110        self.purpose
111    }
112    pub const fn allowed_ops(&self) -> AllowedOps {
113        self.allowed_ops
114    }
115    pub const fn operation(&self) -> OperationId {
116        self.operation
117    }
118    pub const fn expires_unix(&self) -> u64 {
119        self.expires_unix
120    }
121    pub const fn max_decision_lifetime(&self) -> u64 {
122        self.max_decision_lifetime
123    }
124    pub const fn controller_generation(&self) -> Generation {
125        self.controller_generation
126    }
127    pub const fn decision_id_floor(&self) -> u64 {
128        self.decision_id_floor
129    }
130
131    pub fn current_at(&self, now: u64) -> Result<(), E> {
132        if now >= self.expires_unix {
133            Err(E::Crypto(CryptoError::Expired))
134        } else {
135            Ok(())
136        }
137    }
138}
139
140#[derive(Clone, Copy)]
141struct Record {
142    pin: PinHandle,
143    principal: StrongDigest,
144    source: StrongDigest,
145    source_length: u64,
146    policy: StrongDigest,
147    publisher: StrongDigest,
148    purpose: StrongDigest,
149    allowed_ops: AllowedOps,
150    operation: OperationId,
151    expires_unix: u64,
152    max_decision_lifetime: u64,
153    generation: Generation,
154    controller_generation: Generation,
155    next_decision_id: u64,
156    decision_id_floor: u64,
157}
158
159/// Fixed eight-slot table. Default deny; no implicit eviction; no key material.
160pub struct ControllerRecognition {
161    instance: [u8; 16],
162    records: [Option<Record>; MAX_RECOGNIZED],
163    next_generation: Generation,
164}
165
166impl ControllerRecognition {
167    /// Host authenticates its administrator before invoking this.
168    pub fn new_local_admin() -> Result<(Self, RecognitionAdmin), E> {
169        let mut instance = [0; 16];
170        fill_os(&mut instance).map_err(E::Crypto)?;
171        if instance == [0; 16] {
172            return Err(E::Crypto(CryptoError::EntropyFailure));
173        }
174        Ok((
175            Self {
176                instance,
177                records: core::array::from_fn(|_| None),
178                next_generation: Generation::ZERO,
179            },
180            RecognitionAdmin { instance },
181        ))
182    }
183
184    fn admin(&self, admin: &RecognitionAdmin) -> Result<(), E> {
185        if admin.instance != self.instance {
186            return Err(E::Crypto(CryptoError::Unauthorized));
187        }
188        Ok(())
189    }
190
191    pub fn install(
192        &mut self,
193        admin: &RecognitionAdmin,
194        enrollment: RecognitionEnrollment,
195        now: u64,
196    ) -> Result<RecognitionHandle, E> {
197        self.admin(admin)?;
198        validate_enrollment(enrollment, now)?;
199        for row in self.records.iter().flatten() {
200            if row.source == enrollment.source && row.policy == enrollment.policy {
201                return Err(E::Crypto(CryptoError::Conflict));
202            }
203        }
204        let slot = self
205            .records
206            .iter()
207            .position(Option::is_none)
208            .ok_or(E::Capacity)?;
209        let generation = self.next_generation.next().map_err(E::Authority)?;
210        self.records[slot] = Some(Record {
211            pin: enrollment.pin,
212            principal: enrollment.principal,
213            source: enrollment.source,
214            source_length: enrollment.source_length,
215            policy: enrollment.policy,
216            publisher: enrollment.publisher,
217            purpose: enrollment.purpose,
218            allowed_ops: enrollment.allowed_ops,
219            operation: enrollment.operation,
220            expires_unix: enrollment.expires_unix,
221            max_decision_lifetime: enrollment.max_decision_lifetime,
222            generation,
223            controller_generation: generation,
224            next_decision_id: 1,
225            decision_id_floor: 1,
226        });
227        self.next_generation = generation;
228        Ok(RecognitionHandle {
229            instance: self.instance,
230            slot: slot as u8,
231            generation,
232        })
233    }
234
235    /// Explicit replacement. Old PinHandle and decision ids do not survive.
236    pub fn rotate(
237        &mut self,
238        admin: &RecognitionAdmin,
239        handle: RecognitionHandle,
240        enrollment: RecognitionEnrollment,
241        now: u64,
242    ) -> Result<RecognitionHandle, E> {
243        self.admin(admin)?;
244        validate_enrollment(enrollment, now)?;
245        let old = *self.record(handle)?;
246        if enrollment.source != old.source
247            || enrollment.policy != old.policy
248            || enrollment.source_length != old.source_length
249        {
250            return Err(E::Reference);
251        }
252        if enrollment.pin == old.pin {
253            return Err(E::Crypto(CryptoError::Conflict));
254        }
255        let generation = self.next_generation.next().map_err(E::Authority)?;
256        let slot = handle.slot as usize;
257        self.records[slot] = Some(Record {
258            pin: enrollment.pin,
259            principal: enrollment.principal,
260            publisher: enrollment.publisher,
261            purpose: enrollment.purpose,
262            allowed_ops: enrollment.allowed_ops,
263            operation: enrollment.operation,
264            expires_unix: enrollment.expires_unix,
265            max_decision_lifetime: enrollment.max_decision_lifetime,
266            generation,
267            controller_generation: generation,
268            decision_id_floor: old.next_decision_id,
269            next_decision_id: old.next_decision_id,
270            source: old.source,
271            source_length: old.source_length,
272            policy: old.policy,
273        });
274        self.next_generation = generation;
275        Ok(RecognitionHandle {
276            instance: self.instance,
277            slot: handle.slot,
278            generation,
279        })
280    }
281
282    /// Default deny. Exact source/policy/principal/publisher/purpose/operation.
283    pub fn recognize(
284        &self,
285        principal: StrongDigest,
286        source: StrongDigest,
287        source_length: u64,
288        policy: StrongDigest,
289        publisher: StrongDigest,
290        purpose: StrongDigest,
291        operation: OperationId,
292        action: DisclosureAction,
293        now: u64,
294    ) -> Result<RecognizedController, E> {
295        if source.is_zero() || source_length == 0 || principal.is_zero() || policy.is_zero() {
296            return Err(E::Reference);
297        }
298        let row = self
299            .records
300            .iter()
301            .flatten()
302            .find(|r| {
303                r.principal == principal
304                    && r.source == source
305                    && r.source_length == source_length
306                    && r.policy == policy
307            })
308            .ok_or(E::Reference)?;
309        if row.publisher != publisher || row.purpose != purpose || row.operation != operation {
310            return Err(E::Reference);
311        }
312        if !row.allowed_ops.contains(action) {
313            return Err(E::Reference);
314        }
315        if now >= row.expires_unix {
316            return Err(E::Crypto(CryptoError::Expired));
317        }
318        Ok(snapshot(row))
319    }
320
321    pub fn consume_decision_id(
322        &mut self,
323        admin: &RecognitionAdmin,
324        handle: RecognitionHandle,
325    ) -> Result<u64, E> {
326        self.admin(admin)?;
327        let rec = self.record_mut(handle)?;
328        let id = rec.next_decision_id;
329        rec.next_decision_id = id.checked_add(1).ok_or(E::Limit)?;
330        Ok(id)
331    }
332
333    pub fn snapshot(&self, handle: RecognitionHandle) -> Result<RecognizedController, E> {
334        Ok(snapshot(self.record(handle)?))
335    }
336
337    fn record(&self, handle: RecognitionHandle) -> Result<&Record, E> {
338        if handle.instance != self.instance {
339            return Err(E::Crypto(CryptoError::Unauthorized));
340        }
341        let row = self
342            .records
343            .get(handle.slot as usize)
344            .and_then(Option::as_ref)
345            .ok_or(E::Crypto(CryptoError::Unauthorized))?;
346        if row.generation != handle.generation {
347            return Err(E::Crypto(CryptoError::StaleGeneration));
348        }
349        Ok(row)
350    }
351
352    fn record_mut(&mut self, handle: RecognitionHandle) -> Result<&mut Record, E> {
353        if handle.instance != self.instance {
354            return Err(E::Crypto(CryptoError::Unauthorized));
355        }
356        let row = self
357            .records
358            .get_mut(handle.slot as usize)
359            .and_then(Option::as_mut)
360            .ok_or(E::Crypto(CryptoError::Unauthorized))?;
361        if row.generation != handle.generation {
362            return Err(E::Crypto(CryptoError::StaleGeneration));
363        }
364        Ok(row)
365    }
366}
367
368fn snapshot(row: &Record) -> RecognizedController {
369    RecognizedController {
370        pin: row.pin,
371        principal: row.principal,
372        source: row.source,
373        source_length: row.source_length,
374        policy: row.policy,
375        publisher: row.publisher,
376        purpose: row.purpose,
377        allowed_ops: row.allowed_ops,
378        operation: row.operation,
379        expires_unix: row.expires_unix,
380        max_decision_lifetime: row.max_decision_lifetime,
381        controller_generation: row.controller_generation,
382        decision_id_floor: row.decision_id_floor,
383    }
384}
385
386fn validate_enrollment(e: RecognitionEnrollment, now: u64) -> Result<(), E> {
387    if e.principal.is_zero()
388        || e.source.is_zero()
389        || e.policy.is_zero()
390        || e.publisher.is_zero()
391        || e.purpose.is_zero()
392        || e.operation.is_zero()
393    {
394        return Err(E::Reference);
395    }
396    if e.source_length < 64 || e.source_length > MAX_OBJECT_BYTES {
397        return Err(E::Reference);
398    }
399    if e.max_decision_lifetime == 0 || e.max_decision_lifetime > super::MAX_DECISION_LEASE_SECS {
400        return Err(E::Limit);
401    }
402    if now >= e.expires_unix {
403        return Err(E::Crypto(CryptoError::Expired));
404    }
405    Ok(())
406}