Skip to main content

qualia_core_db/semantic_instruments/attestation/
status.rs

1//! Explicit attestation status and revocation (cold path).
2//!
3//! Revocation stops **future** reliance. It does not delete the historical
4//! claim. Withdrawal is its own attestation kind and does not auto-revoke
5//! other claims — this registry is the only revocation mechanism.
6
7use std::collections::BTreeMap;
8
9use crate::semantic_instruments::attestation::kinds::InstrumentAttestation;
10use crate::semantic_instruments::errors::InstrumentError;
11
12/// Current reliance status of an unsigned attestation claim.
13#[derive(Debug, Clone, PartialEq, Eq)]
14pub enum AttestationStatus {
15    Valid,
16    Expired,
17    Revoked { reason: String, revoked_at: u32 },
18}
19
20#[derive(Debug, Clone, PartialEq, Eq)]
21struct RevocationRecord {
22    reason: String,
23    revoked_at: u32,
24}
25
26/// Explicit revocation map keyed by `InstrumentAttestation::claim_id`.
27#[derive(Debug, Clone, Default)]
28pub struct StatusRegistry {
29    revoked: BTreeMap<String, RevocationRecord>,
30}
31
32impl StatusRegistry {
33    /// Creates a default `StatusRegistry`.
34    pub fn new() -> Self {
35        Self {
36            revoked: BTreeMap::new(),
37        }
38    }
39
40    /// Record a revocation. The attestation itself is not deleted.
41    pub fn revoke(&mut self, claim_id: &str, reason: &str, revoked_at: u32) {
42        self.revoked.insert(
43            claim_id.to_string(),
44            RevocationRecord {
45                reason: reason.to_string(),
46                revoked_at,
47            },
48        );
49    }
50
51    /// Historical claim ids that have been revoked (still listable).
52    pub fn revoked_ids(&self) -> impl Iterator<Item = &str> + '_ {
53        self.revoked.keys().map(String::as_str)
54    }
55
56    /// `StatusRegistry::status`.
57    pub fn status(&self, attestation: &InstrumentAttestation, now: u32) -> AttestationStatus {
58        if let Some(record) = self.revoked.get(&attestation.claim_id()) {
59            return AttestationStatus::Revoked {
60                reason: record.reason.clone(),
61                revoked_at: record.revoked_at,
62            };
63        }
64        if attestation.valid_until != 0 && now > attestation.valid_until {
65            return AttestationStatus::Expired;
66        }
67        AttestationStatus::Valid
68    }
69
70    /// Fail-closed future reliance. Revoked and expired claims must not be used.
71    pub fn assert_rely(
72        &self,
73        attestation: &InstrumentAttestation,
74        now: u32,
75    ) -> Result<(), InstrumentError> {
76        match self.status(attestation, now) {
77            AttestationStatus::Valid => Ok(()),
78            AttestationStatus::Expired => Err(InstrumentError::Expired),
79            AttestationStatus::Revoked { .. } => Err(InstrumentError::Revoked),
80        }
81    }
82}
83
84#[cfg(test)]
85mod tests {
86    use super::*;
87    use crate::semantic_instruments::attestation::kinds::AttestationKind;
88
89    const DIGEST: &str = "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
90
91    fn sample(kind: AttestationKind, valid_until: u32) -> InstrumentAttestation {
92        InstrumentAttestation {
93            kind,
94            release_id: "https://ns.webizen.org/demo/unit-convert/releases/1.0.0".into(),
95            content_digest: DIGEST.into(),
96            actor: "did:example:issuer".into(),
97            issued_at: 1_000,
98            valid_until,
99            origin_is_not_truth: true,
100            award_subject: String::new(),
101            assessment_release_id: String::new(),
102        }
103    }
104
105    #[test]
106    fn revoke_then_assert_rely_fails_with_revoked() {
107        let attestation = sample(AttestationKind::Authorship, 0);
108        let mut registry = StatusRegistry::new();
109        registry.revoke(&attestation.claim_id(), "key-compromise", 2_000);
110        let err = registry
111            .assert_rely(&attestation, 1_500)
112            .expect_err("revoked must not be relied on");
113        assert_eq!(err, InstrumentError::Revoked);
114        match registry.status(&attestation, 1_500) {
115            AttestationStatus::Revoked { reason, revoked_at } => {
116                assert_eq!(reason, "key-compromise");
117                assert_eq!(revoked_at, 2_000);
118            }
119            other => panic!("expected Revoked, got {other:?}"),
120        }
121    }
122
123    #[test]
124    fn revoked_ids_still_contains_the_claim() {
125        let attestation = sample(AttestationKind::Publication, 0);
126        let mut registry = StatusRegistry::new();
127        let claim = attestation.claim_id();
128        registry.revoke(&claim, "withdrawn-from-catalog", 9);
129        assert!(registry.revoked_ids().any(|id| id == claim));
130        assert_eq!(registry.revoked_ids().count(), 1);
131    }
132
133    #[test]
134    fn expiry_without_revoke_is_expired() {
135        let attestation = sample(AttestationKind::Endorsement, 100);
136        let registry = StatusRegistry::new();
137        assert_eq!(
138            registry.status(&attestation, 101),
139            AttestationStatus::Expired
140        );
141        assert_eq!(
142            registry.assert_rely(&attestation, 101),
143            Err(InstrumentError::Expired)
144        );
145        assert!(registry.revoked_ids().next().is_none());
146    }
147
148    #[test]
149    fn valid_unrevoked_is_valid() {
150        let attestation = sample(AttestationKind::TechnicalReview, 100);
151        let registry = StatusRegistry::new();
152        assert_eq!(registry.status(&attestation, 100), AttestationStatus::Valid);
153        registry
154            .assert_rely(&attestation, 50)
155            .expect("unexpired unrevoked");
156        let never_expires = sample(AttestationKind::Contribution, 0);
157        assert_eq!(
158            registry.status(&never_expires, u32::MAX),
159            AttestationStatus::Valid
160        );
161    }
162
163    #[test]
164    fn withdrawal_kind_does_not_auto_revoke_other_claims() {
165        let live = sample(AttestationKind::Authorship, 0);
166        let withdrawal = sample(AttestationKind::Withdrawal, 0);
167        let registry = StatusRegistry::new();
168        assert_eq!(registry.status(&live, 1), AttestationStatus::Valid);
169        assert_eq!(registry.status(&withdrawal, 1), AttestationStatus::Valid);
170        assert!(registry.revoked_ids().next().is_none());
171    }
172}