Skip to main content

qualia_core_db/semantic_instruments/attestation/
w3c.rs

1//! W3C Verifiable Credential adapter for instrument attestations (SI-04).
2//!
3//! Signs with ML-DSA-65 via [`VcRuntime`]. A proof is origin, not truth.
4
5use std::collections::HashMap;
6
7use crate::identity::credentials::{Credential, VcError, VcRuntime};
8use crate::semantic_instruments::attestation::kinds::{AttestationKind, InstrumentAttestation};
9use crate::semantic_instruments::errors::InstrumentError;
10
11const VC_CONTEXT_V1: &str = "https://www.w3.org/2018/credentials/v1";
12const TYPE_VC: &str = "VerifiableCredential";
13const TYPE_INSTRUMENT: &str = "InstrumentAttestation";
14
15/// Issued W3C credential paired with the unsigned instrument claim it encodes.
16#[derive(Debug, Clone)]
17pub struct W3cIssued {
18    pub attestation: InstrumentAttestation,
19    pub credential: Credential,
20}
21
22/// Issue an ML-DSA-signed W3C VC whose subject is the release (or award holder).
23pub fn issue_w3c(
24    runtime: &VcRuntime,
25    key_id: Option<&str>,
26    attestation: InstrumentAttestation,
27) -> Result<W3cIssued, InstrumentError> {
28    attestation.validate()?;
29    let unsigned = encode_credential(&attestation);
30    let credential = runtime.issue(unsigned, key_id).map_err(map_vc_error)?;
31    Ok(W3cIssued {
32        attestation,
33        credential,
34    })
35}
36
37/// Verify the attached ML-DSA proof. Missing proof and tamper fail closed.
38pub fn verify_w3c(runtime: &VcRuntime, issued: &W3cIssued) -> Result<(), InstrumentError> {
39    match runtime.verify_credential(&issued.credential) {
40        Ok(true) => Ok(()),
41        Ok(false) => Err(InstrumentError::Tampered),
42        Err(err) => Err(map_vc_error(err)),
43    }
44}
45
46fn map_vc_error(err: VcError) -> InstrumentError {
47    match err {
48        VcError::MissingProof => InstrumentError::MissingProof,
49        VcError::VerificationFailed | VcError::CryptoError(_) => InstrumentError::Tampered,
50        VcError::SerializationError(msg) => InstrumentError::Canonical(msg),
51        VcError::NotImplemented => InstrumentError::Canonical("vc not implemented".into()),
52    }
53}
54
55fn encode_credential(attestation: &InstrumentAttestation) -> Credential {
56    Credential {
57        context: vec![VC_CONTEXT_V1.to_string()],
58        id: attestation.claim_id(),
59        types: vec![TYPE_VC.to_string(), TYPE_INSTRUMENT.to_string()],
60        issuer: attestation.actor.clone(),
61        issuance_date: attestation.issued_at.to_string(),
62        credential_subject: encode_subject(attestation),
63        proof: None,
64    }
65}
66
67fn encode_subject(attestation: &InstrumentAttestation) -> HashMap<String, String> {
68    let mut subject = HashMap::new();
69    let subject_id = if attestation.kind == AttestationKind::CapabilityAward {
70        attestation.award_subject.as_str()
71    } else {
72        attestation.release_id.as_str()
73    };
74    subject.insert("id".to_string(), subject_id.to_string());
75    subject.insert("kind".to_string(), attestation.kind.as_iri().to_string());
76    subject.insert(
77        "contentDigest".to_string(),
78        attestation.content_digest.clone(),
79    );
80    subject.insert("originIsNotTruth".to_string(), "true".to_string());
81    if attestation.kind == AttestationKind::CapabilityAward {
82        subject.insert(
83            "awardSubject".to_string(),
84            attestation.award_subject.clone(),
85        );
86        subject.insert(
87            "assessmentInstrument".to_string(),
88            attestation.assessment_release_id.clone(),
89        );
90    }
91    subject
92}
93
94#[cfg(test)]
95mod tests {
96    use super::*;
97    use crate::crypto::fiduciary_crypto::FiduciaryCrypto;
98
99    fn digest() -> String {
100        format!("sha256:{}", "ab".repeat(32))
101    }
102
103    fn sample(kind: AttestationKind) -> InstrumentAttestation {
104        let mut attestation = InstrumentAttestation {
105            kind,
106            release_id: "https://ns.webizen.org/demo/unit-convert/releases/1.0.0".into(),
107            content_digest: digest(),
108            actor: "did:webizen:agent:demo-seed".into(),
109            issued_at: 1_700_000_000,
110            valid_until: 0,
111            origin_is_not_truth: true,
112            award_subject: String::new(),
113            assessment_release_id: String::new(),
114        };
115        if kind == AttestationKind::CapabilityAward {
116            attestation.release_id = "https://ns.webizen.org/demo/award/releases/1.0.0".into();
117            attestation.award_subject = "did:webizen:person:learner".into();
118            attestation.assessment_release_id =
119                "https://ns.webizen.org/demo/unit-convert/releases/1.0.0".into();
120        }
121        attestation
122    }
123
124    fn signed_runtime() -> VcRuntime {
125        let mut crypto = FiduciaryCrypto::new();
126        crypto.generate_key("default".to_string()).unwrap();
127        VcRuntime::new(crypto)
128    }
129
130    #[test]
131    fn issue_verify_roundtrip() {
132        let runtime = signed_runtime();
133        let issued = issue_w3c(
134            &runtime,
135            Some("default"),
136            sample(AttestationKind::Authorship),
137        )
138        .expect("issue");
139        assert!(issued.credential.proof.is_some());
140        assert_eq!(issued.credential.context, vec![VC_CONTEXT_V1.to_string()]);
141        assert_eq!(
142            issued.credential.types,
143            vec![TYPE_VC.to_string(), TYPE_INSTRUMENT.to_string()]
144        );
145        assert_eq!(issued.credential.id, issued.attestation.claim_id());
146        assert_eq!(issued.credential.issuer, issued.attestation.actor);
147        assert_eq!(
148            issued.credential.issuance_date,
149            issued.attestation.issued_at.to_string()
150        );
151        assert_eq!(
152            issued
153                .credential
154                .credential_subject
155                .get("id")
156                .map(String::as_str),
157            Some(issued.attestation.release_id.as_str())
158        );
159        assert_eq!(
160            issued
161                .credential
162                .credential_subject
163                .get("kind")
164                .map(String::as_str),
165            Some(AttestationKind::Authorship.as_iri())
166        );
167        assert_eq!(
168            issued
169                .credential
170                .credential_subject
171                .get("originIsNotTruth")
172                .map(String::as_str),
173            Some("true")
174        );
175        verify_w3c(&runtime, &issued).expect("verify");
176    }
177
178    #[test]
179    fn tampered_issuer_fails_closed() {
180        let runtime = signed_runtime();
181        let mut issued = issue_w3c(
182            &runtime,
183            Some("default"),
184            sample(AttestationKind::Authorship),
185        )
186        .unwrap();
187        issued.credential.issuer = "https://hacker.com".to_string();
188        assert_eq!(
189            verify_w3c(&runtime, &issued),
190            Err(InstrumentError::Tampered)
191        );
192    }
193
194    #[test]
195    fn unsigned_credential_is_missing_proof() {
196        let runtime = VcRuntime::new(FiduciaryCrypto::new());
197        let attestation = sample(AttestationKind::Authorship);
198        let issued = W3cIssued {
199            credential: encode_credential(&attestation),
200            attestation,
201        };
202        assert!(issued.credential.proof.is_none());
203        assert_eq!(
204            verify_w3c(&runtime, &issued),
205            Err(InstrumentError::MissingProof)
206        );
207    }
208
209    #[test]
210    fn capability_award_subject_is_the_holder() {
211        let runtime = signed_runtime();
212        let attestation = sample(AttestationKind::CapabilityAward);
213        let holder = attestation.award_subject.clone();
214        let instrument = attestation.release_id.clone();
215        let assessment = attestation.assessment_release_id.clone();
216        let issued = issue_w3c(&runtime, Some("default"), attestation).expect("issue award");
217        let subject = &issued.credential.credential_subject;
218        assert_eq!(subject.get("id").map(String::as_str), Some(holder.as_str()));
219        assert_ne!(
220            subject.get("id").map(String::as_str),
221            Some(instrument.as_str())
222        );
223        assert_eq!(
224            subject.get("awardSubject").map(String::as_str),
225            Some(holder.as_str())
226        );
227        assert_eq!(
228            subject.get("assessmentInstrument").map(String::as_str),
229            Some(assessment.as_str())
230        );
231        verify_w3c(&runtime, &issued).expect("verify award");
232    }
233
234    #[test]
235    fn signature_as_truth_is_refused_before_issue() {
236        let runtime = signed_runtime();
237        let mut attestation = sample(AttestationKind::Endorsement);
238        attestation.origin_is_not_truth = false;
239        assert_eq!(
240            issue_w3c(&runtime, Some("default"), attestation).unwrap_err(),
241            InstrumentError::SignatureAsTruth
242        );
243    }
244}