Skip to main content

qualia_core_db/sensing/
revocation.rs

1//! Bounded revocation snapshot verification for sensing authorization.
2//!
3//! An absent receipt is meaningful only after an external authority confirms a
4//! complete, current, anti-rollback checkpoint. This module verifies bounded
5//! contents and signatures; it does not implement durable checkpoint storage.
6
7use sha2::{Digest, Sha256};
8
9use crate::governance::consent_contract::{ConsentGrant, RevocationReceipt};
10
11use super::authorization::{AuthorizationError, RevocationAuthority, TrustedUnixClock};
12
13pub const MAX_REVOCATION_RECEIPTS: usize = 32;
14const SNAPSHOT_DOMAIN: &[u8] = b"qualia:revocation-snapshot:v1\0";
15
16#[derive(Clone, Copy, Debug, PartialEq, Eq)]
17pub enum RevocationSnapshotError {
18    TooManyReceipts,
19    WrongGrant,
20    InvalidReceipt,
21    DuplicateReceipt,
22    CheckpointMismatch,
23    SnapshotDigestMismatch,
24    AuthorityUnavailable,
25    UnknownCheckpoint,
26}
27
28/// Fixed-size checkpoint claims supplied by storage/ledger code. The fields are
29/// untrusted until a `RevocationCheckpointAuthority` accepts them.
30#[derive(Clone, Copy, Debug, PartialEq, Eq)]
31pub struct RevocationCheckpoint {
32    grant_id: [u8; 32],
33    grant_digest: [u8; 32],
34    sequence: u64,
35    record_count: u8,
36    snapshot_digest: [u8; 32],
37}
38
39impl RevocationCheckpoint {
40    pub const fn new(
41        grant_id: [u8; 32],
42        grant_digest: [u8; 32],
43        sequence: u64,
44        record_count: u8,
45        snapshot_digest: [u8; 32],
46    ) -> Self {
47        Self {
48            grant_id,
49            grant_digest,
50            sequence,
51            record_count,
52            snapshot_digest,
53        }
54    }
55
56    pub const fn grant_id(self) -> [u8; 32] {
57        self.grant_id
58    }
59    pub const fn grant_digest(self) -> [u8; 32] {
60        self.grant_digest
61    }
62    pub const fn sequence(self) -> u64 {
63        self.sequence
64    }
65    pub const fn record_count(self) -> u8 {
66        self.record_count
67    }
68    pub const fn snapshot_digest(self) -> [u8; 32] {
69        self.snapshot_digest
70    }
71}
72
73/// External trusted store/ledger checkpoint verifier. It must authenticate the
74/// checkpoint, prove snapshot completeness (including absence), enforce freshness
75/// against persisted anti-rollback state, and fail closed if any part is unknown.
76pub trait RevocationCheckpointAuthority {
77    fn verify_current_complete(
78        &self,
79        grant: &ConsentGrant,
80        checkpoint: &RevocationCheckpoint,
81        receipts: &[RevocationReceipt],
82        current_time_unix: u64,
83    ) -> Result<(), RevocationSnapshotError>;
84}
85
86/// Verified view for one grant and one accepted checkpoint. Construction is only
87/// possible after local receipt checks and the external completeness/freshness gate.
88pub struct VerifiedRevocationSnapshot<'g, 'r, 'a> {
89    grant: &'g ConsentGrant,
90    grant_id: [u8; 32],
91    grant_digest: [u8; 32],
92    checkpoint: RevocationCheckpoint,
93    receipts: &'r [RevocationReceipt],
94    authority: &'a dyn RevocationCheckpointAuthority,
95}
96
97impl<'g, 'r, 'a> VerifiedRevocationSnapshot<'g, 'r, 'a> {
98    pub fn verify(
99        grant: &'g ConsentGrant,
100        checkpoint: RevocationCheckpoint,
101        receipts: &'r [RevocationReceipt],
102        authority: &'a dyn RevocationCheckpointAuthority,
103        clock: &mut dyn TrustedUnixClock,
104    ) -> Result<Self, RevocationSnapshotError> {
105        if receipts.len() > MAX_REVOCATION_RECEIPTS {
106            return Err(RevocationSnapshotError::TooManyReceipts);
107        }
108        let grant_digest = grant.compute_digest();
109        if checkpoint.grant_id != grant.grant_id
110            || checkpoint.grant_digest != grant_digest
111            || usize::from(checkpoint.record_count) != receipts.len()
112            || grant.grant_id == [0; 32]
113        {
114            return Err(RevocationSnapshotError::CheckpointMismatch);
115        }
116        if snapshot_digest(grant, receipts) != checkpoint.snapshot_digest {
117            return Err(RevocationSnapshotError::SnapshotDigestMismatch);
118        }
119        for (index, receipt) in receipts.iter().enumerate() {
120            if receipt.grant_id != grant.grant_id {
121                return Err(RevocationSnapshotError::WrongGrant);
122            }
123            if receipts[..index]
124                .iter()
125                .any(|previous| previous.receipt_id == receipt.receipt_id)
126            {
127                return Err(RevocationSnapshotError::DuplicateReceipt);
128            }
129            receipt
130                .verify_against_grant(grant)
131                .map_err(|_| RevocationSnapshotError::InvalidReceipt)?;
132        }
133        let now = clock
134            .now_unix()
135            .map_err(|_| RevocationSnapshotError::AuthorityUnavailable)?;
136        authority.verify_current_complete(grant, &checkpoint, receipts, now)?;
137        Ok(Self {
138            grant,
139            grant_id: grant.grant_id,
140            grant_digest,
141            checkpoint,
142            receipts,
143            authority,
144        })
145    }
146
147    pub const fn grant_id(&self) -> [u8; 32] {
148        self.grant_id
149    }
150    pub const fn grant_digest(&self) -> [u8; 32] {
151        self.grant_digest
152    }
153    pub const fn checkpoint(&self) -> RevocationCheckpoint {
154        self.checkpoint
155    }
156    fn receipt_present(&self) -> bool {
157        !self.receipts.is_empty()
158    }
159}
160
161impl RevocationAuthority for VerifiedRevocationSnapshot<'_, '_, '_> {
162    fn is_revoked(
163        &self,
164        grant_id: &[u8; 32],
165        grant_digest: &[u8; 32],
166        current_time_unix: u64,
167    ) -> Result<bool, AuthorizationError> {
168        if grant_id != &self.grant_id || grant_digest != &self.grant_digest {
169            return Err(AuthorizationError::RevocationUnknown);
170        }
171        self.authority
172            .verify_current_complete(
173                self.grant,
174                &self.checkpoint,
175                self.receipts,
176                current_time_unix,
177            )
178            .map_err(|_| AuthorizationError::RevocationUnknown)?;
179        Ok(self.receipt_present())
180    }
181}
182
183/// Deterministic digest over the ordered, bounded receipt slice and grant.
184/// Checkpoint verifiers must use the same ordering and versioned domain.
185pub fn snapshot_digest(grant: &ConsentGrant, receipts: &[RevocationReceipt]) -> [u8; 32] {
186    let mut hash = Sha256::new();
187    hash.update(SNAPSHOT_DOMAIN);
188    hash.update(grant.grant_id);
189    hash.update(grant.compute_digest());
190    hash.update((receipts.len() as u32).to_be_bytes());
191    for receipt in receipts {
192        hash.update(receipt.compute_digest());
193        hash.update(receipt.signature);
194    }
195    hash.finalize().into()
196}