Skip to main content

qualia_core_db/domain_licence/
codec.rs

1//! Canonical byte encoding + JSON file codec for [`DomainLicence`].
2//!
3//! The canonical form is a fixed-order, little-endian, length-prefixed byte
4//! encoding of every field **except** `signature_hex` and `chain_anchors`
5//! (WIP §7-8: anchors live outside the signed envelope so they can be added
6//! post-issuance). The signature and the licence digest are computed over
7//! exactly these bytes.
8
9use sha2::{Digest, Sha256};
10
11use super::model::{DomainLicence, LicenceAmendment};
12use super::verify::LicenceError;
13
14/// Required `format` field value.
15pub const LICENCE_FORMAT: &str = "qualia-domain-licence/0.1";
16
17/// On-chain OP_RETURN marker prefixing the licence digest (WIP §4-B).
18pub const ANCHOR_OP_RETURN_PREFIX: &[u8] = b"QUALIA-LIC ";
19
20fn write_u8(buf: &mut Vec<u8>, v: u8) {
21    buf.push(v);
22}
23
24fn write_u32(buf: &mut Vec<u8>, v: u32) {
25    buf.extend_from_slice(&v.to_le_bytes());
26}
27
28fn write_u64(buf: &mut Vec<u8>, v: u64) {
29    buf.extend_from_slice(&v.to_le_bytes());
30}
31
32fn write_str(buf: &mut Vec<u8>, s: &str) {
33    write_u32(buf, s.len() as u32);
34    buf.extend_from_slice(s.as_bytes());
35}
36
37fn write_str_list(buf: &mut Vec<u8>, list: &[String]) {
38    write_u32(buf, list.len() as u32);
39    for s in list {
40        write_str(buf, s);
41    }
42}
43
44/// Canonical signed bytes for a licence (excludes `signature_hex` and
45/// `chain_anchors`).
46pub fn canonical_bytes(lic: &DomainLicence) -> Vec<u8> {
47    let mut buf = Vec::with_capacity(512);
48    write_str(&mut buf, &lic.format);
49    write_str(&mut buf, &lic.licence_id);
50    write_str(&mut buf, &lic.issuer_did);
51    write_str(&mut buf, &lic.issuer_pubkey_hex);
52    write_str_list(&mut buf, &lic.subject_domains);
53    write_str(&mut buf, &lic.domain_did);
54    match &lic.delegation {
55        Some(d) => {
56            write_u8(&mut buf, 1);
57            write_u8(&mut buf, u8::from(d.covers_subdomains));
58            write_str_list(&mut buf, &d.members);
59            write_str(&mut buf, &d.steward_agreement);
60        }
61        None => write_u8(&mut buf, 0),
62    }
63    write_str(&mut buf, &lic.licensee_did);
64    write_str(&mut buf, &lic.licensee_agent_type);
65    write_str(&mut buf, &lic.licensee_label);
66    write_str(&mut buf, &lic.licence_class);
67    write_str_list(&mut buf, &lic.capability_scope);
68    write_u64(&mut buf, lic.not_before_unix);
69    write_u64(&mut buf, lic.expires_unix);
70    match &lic.payment_evidence {
71        Some(p) => {
72            write_u8(&mut buf, 1);
73            write_str(&mut buf, &p.rail);
74            write_str(&mut buf, &p.txid);
75            write_u64(&mut buf, p.amount_sats);
76        }
77        None => write_u8(&mut buf, 0),
78    }
79    write_str(&mut buf, &lic.revocation_uri);
80    write_str(&mut buf, &lic.terms_uri);
81    buf
82}
83
84/// Canonical signed bytes for an amendment.
85pub fn amendment_canonical_bytes(amend: &LicenceAmendment) -> Vec<u8> {
86    let mut buf = Vec::with_capacity(256);
87    write_str(&mut buf, &amend.licence_id);
88    write_u32(&mut buf, amend.seq);
89    write_str_list(&mut buf, &amend.add_members);
90    write_str_list(&mut buf, &amend.remove_members);
91    write_u64(&mut buf, amend.issued_unix);
92    buf
93}
94
95/// SHA-256 digest of the canonical licence bytes — the value anchored on-chain.
96pub fn canonical_digest(lic: &DomainLicence) -> [u8; 32] {
97    Sha256::digest(&canonical_bytes(lic)).into()
98}
99
100/// Digest rendered as `"sha256:<hex>"` for `chain_anchors[].digest`.
101pub fn canonical_digest_tag(lic: &DomainLicence) -> String {
102    format!("sha256:{}", hex::encode(canonical_digest(lic)))
103}
104
105/// The OP_RETURN payload committing a licence digest on a nominated chain.
106pub fn anchor_op_return(lic: &DomainLicence) -> Vec<u8> {
107    let mut out = Vec::with_capacity(ANCHOR_OP_RETURN_PREFIX.len() + 32);
108    out.extend_from_slice(ANCHOR_OP_RETURN_PREFIX);
109    out.extend_from_slice(&canonical_digest(lic));
110    out
111}
112
113/// Serialize a licence to its `.qlic.json` file form.
114pub fn to_json(lic: &DomainLicence) -> Result<String, LicenceError> {
115    serde_json::to_string_pretty(lic).map_err(|_| LicenceError::Malformed("json encode"))
116}
117
118/// Parse a licence from its `.qlic.json` file form.
119pub fn from_json(text: &str) -> Result<DomainLicence, LicenceError> {
120    serde_json::from_str(text).map_err(|_| LicenceError::Malformed("json parse"))
121}
122
123/// Serialize an amendment to JSON.
124pub fn amendment_to_json(amend: &LicenceAmendment) -> Result<String, LicenceError> {
125    serde_json::to_string_pretty(amend).map_err(|_| LicenceError::Malformed("json encode"))
126}
127
128/// Parse an amendment from JSON.
129pub fn amendment_from_json(text: &str) -> Result<LicenceAmendment, LicenceError> {
130    serde_json::from_str(text).map_err(|_| LicenceError::Malformed("json parse"))
131}