Skip to main content

qualia_core_db/did_qi/
id.rs

1//! Parse and format `did:qi:` identifiers (spec §6).
2//!
3//! Method-specific-id is multibase Bitcoin base58btc (`z` prefix) of a 32-byte
4//! SHA-256 genesis payload digest. Hot path: no `String` / `Box` / `Vec`.
5
6use super::QiError;
7
8/// 32-byte genesis digest. The DID string is `did:qi:z` + base58btc(this).
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub struct DidQi(pub [u8; 32]);
11
12/// Spec §6.3: at most 57 ASCII octets; 64 leaves headroom.
13pub const MAX_DID_TEXT: usize = 64;
14
15const PREFIX: &[u8] = b"did:qi:";
16const MULTIBASE_Z: u8 = b'z';
17pub(crate) const B58: &[u8; 58] = b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
18
19/// Formats `did:qi:z<base58btc(digest)>` into `out`; `BufferTooSmall` when undersized.
20pub fn format_did(id: &DidQi, out: &mut [u8]) -> Result<usize, QiError> {
21    let mut digits = [0u8; 64];
22    let n = encode_b58(&id.0, &mut digits)?;
23    let total = PREFIX.len() + 1 + n;
24    if out.len() < total {
25        return Err(QiError::BufferTooSmall);
26    }
27    out[..PREFIX.len()].copy_from_slice(PREFIX);
28    out[PREFIX.len()] = MULTIBASE_Z;
29    out[PREFIX.len() + 1..total].copy_from_slice(&digits[..n]);
30    Ok(total)
31}
32
33/// Parses a `did:qi:` string; rejects other methods and non-canonical base58 encodings.
34pub fn parse_did(s: &[u8]) -> Result<DidQi, QiError> {
35    if starts_ignore_ascii(s, b"did:q42:")
36        || starts_ignore_ascii(s, b"did:hcai:")
37        || starts_ignore_ascii(s, b"did:hcinet:")
38        || starts_ignore_ascii(s, b"did:hci:")
39        || starts_ignore_ascii(s, b"did:qualia:")
40    {
41        return Err(QiError::RejectedMethod);
42    }
43    if !starts_ignore_ascii(s, PREFIX) {
44        return Err(QiError::InvalidPrefix);
45    }
46    let rest = &s[PREFIX.len()..];
47    if rest.first() != Some(&MULTIBASE_Z) || rest.len() < 2 {
48        return Err(QiError::MalformedId);
49    }
50    let payload = &rest[1..];
51    let mut id = [0u8; 32];
52    decode_b58(payload, &mut id)?;
53    let mut round = [0u8; 64];
54    let n = encode_b58(&id, &mut round)?;
55    if &round[..n] != payload {
56        return Err(QiError::MalformedId);
57    }
58    Ok(DidQi(id))
59}
60
61fn starts_ignore_ascii(s: &[u8], prefix: &[u8]) -> bool {
62    if s.len() < prefix.len() {
63        return false;
64    }
65    let mut i = 0;
66    while i < prefix.len() {
67        if s[i].to_ascii_lowercase() != prefix[i] {
68            return false;
69        }
70        i += 1;
71    }
72    true
73}
74
75/// Bitcoin base58btc-encodes `input` into `out`.
76pub(crate) fn encode_b58(input: &[u8], out: &mut [u8]) -> Result<usize, QiError> {
77    let leading = input.iter().take_while(|b| **b == 0).count();
78    let mut acc = [0u8; 128];
79    let mut acc_len = 1usize;
80    for &byte in input {
81        let mut carry = byte as u32;
82        for slot in acc.iter_mut().take(acc_len) {
83            carry += (*slot as u32) << 8;
84            *slot = (carry % 58) as u8;
85            carry /= 58;
86        }
87        while carry > 0 {
88            if acc_len >= acc.len() {
89                return Err(QiError::Encoding);
90            }
91            acc[acc_len] = (carry % 58) as u8;
92            acc_len += 1;
93            carry /= 58;
94        }
95    }
96    let mut high = acc_len;
97    while high > 0 && acc[high - 1] == 0 {
98        high -= 1;
99    }
100    let total = leading + high;
101    if out.len() < total {
102        return Err(QiError::BufferTooSmall);
103    }
104    for i in 0..leading {
105        out[i] = b'1';
106    }
107    for i in 0..high {
108        out[leading + i] = B58[acc[high - 1 - i] as usize];
109    }
110    Ok(total)
111}
112
113/// Bitcoin base58btc-decodes `input` into `out`.
114pub(crate) fn decode_b58(input: &[u8], out: &mut [u8]) -> Result<usize, QiError> {
115    if input.is_empty() || out.is_empty() {
116        return Err(QiError::MalformedId);
117    }
118    let mut acc = [0u8; 64];
119    if out.len() > acc.len() {
120        return Err(QiError::BufferTooSmall);
121    }
122    for &ch in input {
123        let digit = B58
124            .iter()
125            .position(|&c| c == ch)
126            .ok_or(QiError::MalformedId)?;
127        let mut carry = digit as u16;
128        for slot in acc.iter_mut().rev().take(out.len()) {
129            let v = (*slot as u16) * 58 + carry;
130            *slot = (v & 0xff) as u8;
131            carry = v >> 8;
132        }
133        if carry != 0 {
134            return Err(QiError::MalformedId);
135        }
136    }
137    let start = acc.len() - out.len();
138    out.copy_from_slice(&acc[start..]);
139    Ok(out.len())
140}
141
142#[cfg(test)]
143mod tests {
144    use super::*;
145
146    #[test]
147    fn parse_did_rejects_did_q42() {
148        assert_eq!(parse_did(b"did:q42:ptr/00"), Err(QiError::RejectedMethod));
149    }
150
151    #[test]
152    fn parse_did_rejects_did_hcai() {
153        assert_eq!(
154            parse_did(b"did:hcai:zDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu"),
155            Err(QiError::RejectedMethod)
156        );
157    }
158
159    #[test]
160    fn parse_did_rejects_hci_qualia_and_hostname() {
161        assert_eq!(
162            parse_did(b"did:hci:zDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu"),
163            Err(QiError::RejectedMethod)
164        );
165        assert_eq!(
166            parse_did(b"did:hcinet:zDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu"),
167            Err(QiError::RejectedMethod)
168        );
169        assert_eq!(
170            parse_did(b"did:qualia:zDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu"),
171            Err(QiError::RejectedMethod)
172        );
173        assert_eq!(
174            parse_did(b"did:qi:example.invalid"),
175            Err(QiError::MalformedId)
176        );
177    }
178
179    #[test]
180    fn parse_did_ascii_case_folds_prefix_not_multibase() {
181        let folded = b"DID:QI:zDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu";
182        let expected = parse_did(b"did:qi:zDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu").unwrap();
183        assert_eq!(parse_did(folded).unwrap(), expected);
184        assert_eq!(
185            parse_did(b"did:qi:ZDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu"),
186            Err(QiError::MalformedId)
187        );
188    }
189
190    #[test]
191    fn spec_vector_did_round_trip() {
192        let mut raw = [0u8; 32];
193        let hex = b"bc845eeecf604e7909e67af54a85f047ce7863c24706ef1b9441567861c1491c";
194        for i in 0..32 {
195            raw[i] = hex_byte(hex[i * 2], hex[i * 2 + 1]);
196        }
197        let id = DidQi(raw);
198        let mut buf = [0u8; MAX_DID_TEXT];
199        let n = format_did(&id, &mut buf).unwrap();
200        assert_eq!(
201            &buf[..n],
202            b"did:qi:zDgtiZgtgfbh7upfLB47yVTWLdSN4CcoaPHok9sew2BVu"
203        );
204        assert_eq!(parse_did(&buf[..n]).unwrap(), id);
205    }
206
207    fn hex_byte(a: u8, b: u8) -> u8 {
208        fn n(c: u8) -> u8 {
209            match c {
210                b'0'..=b'9' => c - b'0',
211                b'a'..=b'f' => c - b'a' + 10,
212                _ => 0,
213            }
214        }
215        (n(a) << 4) | n(b)
216    }
217}