Skip to main content

qualia_core_db/identity/credentials/
codecs.rs

1//! Credential transport codecs (from `0.0.19-g3-cbor-ld`) — encode/decode a
2//! [`Credential`] to alternative carriers. Uses the unified
3//! `Credential` type from the parent module (the branch's duplicate was dropped).
4
5use super::Credential;
6
7#[derive(Debug)]
8pub enum CodecError {
9    SerializationError(String),
10}
11
12/// Encode/decode a Verifiable Credential to/from a transport representation.
13pub trait CredentialCodec {
14    /// Encodes a credential.
15    fn encode(&self, credential: &Credential) -> Result<Vec<u8>, CodecError>;
16    /// Decodes a credential.
17    fn decode(&self, payload: &[u8]) -> Result<Credential, CodecError>;
18}
19
20/// OpenBadges v3 carrier: adds the OB context + type, then JSON-encodes.
21pub struct OpenBadgeCodec;
22
23const OB_CONTEXT: &str = "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json";
24
25impl CredentialCodec for OpenBadgeCodec {
26    /// Encodes a credential.
27    fn encode(&self, credential: &Credential) -> Result<Vec<u8>, CodecError> {
28        let mut c = credential.clone();
29        if !c.context.iter().any(|s| s == OB_CONTEXT) {
30            c.context.push(OB_CONTEXT.to_string());
31        }
32        if !c.types.iter().any(|s| s == "OpenBadgeCredential") {
33            c.types.push("OpenBadgeCredential".to_string());
34        }
35        serde_json::to_vec(&c)
36            .map_err(|e| CodecError::SerializationError(format!("OpenBadge encoding failed: {e}")))
37    }
38
39    /// Decodes a credential.
40    fn decode(&self, payload: &[u8]) -> Result<Credential, CodecError> {
41        let credential: Credential = serde_json::from_slice(payload).map_err(|e| {
42            CodecError::SerializationError(format!("OpenBadge decoding failed: {e}"))
43        })?;
44        if !credential.types.iter().any(|s| s == "OpenBadgeCredential") {
45            return Err(CodecError::SerializationError(
46                "Not a valid OpenBadgeCredential".to_string(),
47            ));
48        }
49        Ok(credential)
50    }
51}
52
53/// PDF carrier: embeds the credential JSON as a `/Metadata` stream in a minimal PDF.
54pub struct PdfCodec;
55
56impl CredentialCodec for PdfCodec {
57    /// Encodes a credential.
58    fn encode(&self, credential: &Credential) -> Result<Vec<u8>, CodecError> {
59        let json = serde_json::to_string(credential)
60            .map_err(|e| CodecError::SerializationError(format!("PDF encoding failed: {e}")))?;
61
62        let mut pdf = Vec::new();
63        pdf.extend_from_slice(b"%PDF-1.7\n");
64        pdf.extend_from_slice(b"%\xE2\xE3\xCF\xD3\n");
65        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
66        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
67        pdf.extend_from_slice(b"3 0 obj\n");
68        pdf.extend_from_slice(
69            format!(
70                "<< /Type /Metadata /Subtype /XML /Length {} >>\n",
71                json.len()
72            )
73            .as_bytes(),
74        );
75        pdf.extend_from_slice(b"stream\n");
76        pdf.extend_from_slice(json.as_bytes());
77        pdf.extend_from_slice(b"\nendstream\nendobj\n");
78        pdf.extend_from_slice(b"xref\n0 4\n0000000000 65535 f \n0000000015 00000 n \n0000000066 00000 n \n0000000125 00000 n \n");
79        pdf.extend_from_slice(b"trailer\n<< /Size 4 /Root 1 0 R >>\nstartxref\n250\n%%EOF\n");
80        Ok(pdf)
81    }
82
83    /// Decodes a credential.
84    fn decode(&self, payload: &[u8]) -> Result<Credential, CodecError> {
85        let s = String::from_utf8_lossy(payload);
86        if let Some(start) = s.find("stream\n{") {
87            let json_start = start + 7;
88            if let Some(end) = s[json_start..].find("\nendstream") {
89                return serde_json::from_str(&s[json_start..json_start + end]).map_err(|e| {
90                    CodecError::SerializationError(format!("PDF decoding failed: {e}"))
91                });
92            }
93        }
94        Err(CodecError::SerializationError(
95            "Could not locate VC in PDF payload".to_string(),
96        ))
97    }
98}
99
100#[cfg(test)]
101mod tests {
102    use super::*;
103    use std::collections::HashMap;
104
105    fn test_credential() -> Credential {
106        let mut subject = HashMap::new();
107        subject.insert("id".to_string(), "did:example:123".to_string());
108        subject.insert("achievement".to_string(), "Course Completion".to_string());
109        Credential {
110            context: vec!["https://www.w3.org/2018/credentials/v1".to_string()],
111            id: "http://example.edu/credentials/3732".to_string(),
112            types: vec!["VerifiableCredential".to_string()],
113            issuer: "https://example.edu/issuers/565049".to_string(),
114            issuance_date: "2010-01-01T19:23:24Z".to_string(),
115            credential_subject: subject,
116            proof: None,
117        }
118    }
119
120    #[test]
121    fn openbadge_roundtrip() {
122        let codec = OpenBadgeCodec;
123        let cred = test_credential();
124        let encoded = codec.encode(&cred).expect("encode");
125        let decoded = codec.decode(&encoded).expect("decode");
126        assert!(decoded.types.iter().any(|s| s == "OpenBadgeCredential"));
127        assert!(decoded.context.iter().any(|s| s == OB_CONTEXT));
128        assert_eq!(decoded.id, cred.id);
129    }
130
131    #[test]
132    fn pdf_roundtrip() {
133        let codec = PdfCodec;
134        let cred = test_credential();
135        let encoded = codec.encode(&cred).expect("encode");
136        assert!(encoded.starts_with(b"%PDF-1.7"));
137        assert!(encoded.ends_with(b"%%EOF\n"));
138        let decoded = codec.decode(&encoded).expect("decode");
139        assert_eq!(decoded.id, cred.id);
140        assert_eq!(decoded.issuer, cred.issuer);
141    }
142}