Skip to main content

qualia_core_db/semantic_instruments/attestation/
kinds.rs

1//! Attestation kinds bound to an immutable instrument release digest.
2//!
3//! A signature proves origin/integrity, not substantive truth. Authorship,
4//! review, endorsement, publication, withdrawal and award issuance remain
5//! distinct predicates (`si:authoredBy` … `si:issuedBy`).
6
7use crate::semantic_instruments::errors::InstrumentError;
8
9/// One action. A single attestation carries exactly one kind.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
11#[serde(rename_all = "kebab-case")]
12pub enum AttestationKind {
13    Authorship,
14    Contribution,
15    TechnicalReview,
16    ProfessionalReview,
17    Endorsement,
18    Publication,
19    Withdrawal,
20    CapabilityAward,
21}
22
23impl AttestationKind {
24    /// Views `self` as `iri`.
25    pub const fn as_iri(self) -> &'static str {
26        match self {
27            Self::Authorship => "si:authoredBy",
28            Self::Contribution => "si:contributedBy",
29            Self::TechnicalReview => "si:technicallyReviewedBy",
30            Self::ProfessionalReview => "si:professionallyReviewedBy",
31            Self::Endorsement => "si:endorsedBy",
32            Self::Publication => "si:publishedBy",
33            Self::Withdrawal => "si:withdrawnBy",
34            Self::CapabilityAward => "si:issuedBy",
35        }
36    }
37
38    /// Parses input; error on malformed data.
39    pub fn parse(raw: &str) -> Result<Self, InstrumentError> {
40        match raw.trim() {
41            "si:authoredBy" | "authorship" => Ok(Self::Authorship),
42            "si:contributedBy" | "contribution" => Ok(Self::Contribution),
43            "si:technicallyReviewedBy" | "technical-review" => Ok(Self::TechnicalReview),
44            "si:professionallyReviewedBy" | "professional-review" => Ok(Self::ProfessionalReview),
45            "si:endorsedBy" | "endorsement" => Ok(Self::Endorsement),
46            "si:publishedBy" | "publication" => Ok(Self::Publication),
47            "si:withdrawnBy" | "withdrawal" => Ok(Self::Withdrawal),
48            "si:issuedBy" | "capability-award" => Ok(Self::CapabilityAward),
49            _ => Err(InstrumentError::InvalidAttestationKind),
50        }
51    }
52}
53
54/// Unsigned claim over a release. `origin_is_not_truth` must be true.
55#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
56pub struct InstrumentAttestation {
57    pub kind: AttestationKind,
58    pub release_id: String,
59    pub content_digest: String,
60    pub actor: String,
61    pub issued_at: u32,
62    pub valid_until: u32,
63    pub origin_is_not_truth: bool,
64    /// Learner/worker DID when `kind` is CapabilityAward; empty otherwise.
65    #[serde(default)]
66    pub award_subject: String,
67    /// Assessment instrument release; required for CapabilityAward.
68    #[serde(default)]
69    pub assessment_release_id: String,
70}
71
72impl InstrumentAttestation {
73    /// `InstrumentAttestation::validate`.
74    pub fn validate(&self) -> Result<(), InstrumentError> {
75        if !self.origin_is_not_truth {
76            return Err(InstrumentError::SignatureAsTruth);
77        }
78        if self.release_id.trim().is_empty() {
79            return Err(InstrumentError::MissingField("release_id"));
80        }
81        if !self.content_digest.starts_with("sha256:") || self.content_digest.len() != 71 {
82            return Err(InstrumentError::MissingField("content_digest"));
83        }
84        if self.actor.trim().is_empty() {
85            return Err(InstrumentError::MissingField("actor"));
86        }
87        if self.kind == AttestationKind::CapabilityAward {
88            if self.award_subject.trim().is_empty() {
89                return Err(InstrumentError::MissingField("award_subject"));
90            }
91            if self.assessment_release_id.trim().is_empty() {
92                return Err(InstrumentError::MissingField("assessment_release_id"));
93            }
94            if self.award_subject == self.assessment_release_id
95                || self.award_subject == self.release_id
96            {
97                return Err(InstrumentError::AwardIsInstrument);
98            }
99        }
100        Ok(())
101    }
102
103    /// Stable id for status/revocation maps (not a signature).
104    pub fn claim_id(&self) -> String {
105        format!(
106            "{}|{}|{}|{}|{}",
107            self.kind.as_iri(),
108            self.release_id,
109            self.content_digest,
110            self.actor,
111            self.issued_at
112        )
113    }
114}
115
116#[cfg(test)]
117mod tests {
118    use super::*;
119
120    fn digest() -> String {
121        format!("sha256:{}", "ab".repeat(32))
122    }
123
124    fn base(kind: AttestationKind) -> InstrumentAttestation {
125        InstrumentAttestation {
126            kind,
127            release_id: "https://ns.webizen.org/demo/unit-convert/releases/1.0.0".into(),
128            content_digest: digest(),
129            actor: "did:webizen:agent:demo-seed".into(),
130            issued_at: 1_700_000_000,
131            valid_until: 0,
132            origin_is_not_truth: true,
133            award_subject: String::new(),
134            assessment_release_id: String::new(),
135        }
136    }
137
138    #[test]
139    fn kinds_have_distinct_predicates() {
140        let iris = [
141            AttestationKind::Authorship.as_iri(),
142            AttestationKind::Contribution.as_iri(),
143            AttestationKind::TechnicalReview.as_iri(),
144            AttestationKind::ProfessionalReview.as_iri(),
145            AttestationKind::Endorsement.as_iri(),
146            AttestationKind::Publication.as_iri(),
147            AttestationKind::Withdrawal.as_iri(),
148            AttestationKind::CapabilityAward.as_iri(),
149        ];
150        let mut set = std::collections::BTreeSet::new();
151        for iri in iris {
152            assert!(set.insert(iri), "duplicate predicate {iri}");
153        }
154    }
155
156    #[test]
157    fn signature_as_truth_rejected() {
158        let mut a = base(AttestationKind::Authorship);
159        a.origin_is_not_truth = false;
160        assert_eq!(a.validate(), Err(InstrumentError::SignatureAsTruth));
161    }
162
163    #[test]
164    fn award_cannot_be_the_instrument() {
165        let mut a = base(AttestationKind::CapabilityAward);
166        a.award_subject = a.release_id.clone();
167        a.assessment_release_id = a.release_id.clone();
168        assert_eq!(a.validate(), Err(InstrumentError::AwardIsInstrument));
169    }
170}