Skip to main content

qualia_core_db/did_qi/
document_decode.rs

1//! QCDE-1 decode and §10.3 locator ingest for Qualia Identifier documents.
2//!
3//! Create/Update encode in [`super::document`]. Read reconstructs every member
4//! that encoder emits. Foreign JSON is scanned for Direct locator field names
5//! before it is treated as a document.
6
7use super::document::{AkaEntry, QiDocument, MAX_AKA, MAX_SERVICES};
8use super::id::decode_b58;
9use super::service::{CscpMailbox, Disclosure, LocatorClass, RelayHint, MAX_HINTS};
10use super::QiError;
11
12const FORBIDDEN_KEYS: [&[u8]; 16] = [
13    b"\"ipv4\":",
14    b"\"ipv6\":",
15    b"\"ip\":",
16    b"\"host\":",
17    b"\"hostname\":",
18    b"\"port\":",
19    b"\"socketAddress\":",
20    b"\"socket\":",
21    b"\"addr\":",
22    b"\"multiaddr\":",
23    b"\"peerAddr\":",
24    b"\"directLocator\":",
25    b"\"wss\":",
26    b"\"quic\":",
27    b"\"udp\":",
28    b"\"tcp\":",
29];
30
31/// `needle` occurs anywhere in `buf`.
32fn contains(buf: &[u8], needle: &[u8]) -> bool {
33    find_from(buf, 0, needle).is_some()
34}
35
36/// First index of `needle` at or after `from`.
37fn find_from(buf: &[u8], from: usize, needle: &[u8]) -> Option<usize> {
38    if needle.is_empty() || from > buf.len() {
39        return None;
40    }
41    let mut i = from;
42    while i + needle.len() <= buf.len() {
43        if &buf[i..i + needle.len()] == needle {
44            return Some(i);
45        }
46        i += 1;
47    }
48    None
49}
50
51/// Slice of `buf` immediately following the first `key` occurrence.
52fn after<'a>(buf: &'a [u8], key: &[u8]) -> Option<&'a [u8]> {
53    find_from(buf, 0, key).map(|i| &buf[i + key.len()..])
54}
55
56/// Leading token up to the first `,`/`}`/`]`/whitespace delimiter.
57fn take_token(s: &[u8]) -> &[u8] {
58    let mut i = 0;
59    while i < s.len() && s[i] != b'"' {
60        i += 1;
61    }
62    &s[..i]
63}
64
65/// `true` when the token at `s` spells `true`.
66fn parse_bool_at(s: &[u8]) -> bool {
67    s.starts_with(b"true")
68}
69
70/// Leading decimal digits at `s` as u32 (0 on no digits).
71fn parse_u32_at(s: &[u8]) -> u32 {
72    let mut v = 0u32;
73    let mut i = 0;
74    while i < s.len() && s[i].is_ascii_digit() {
75        v = v.saturating_mul(10).saturating_add((s[i] - b'0') as u32);
76        i += 1;
77    }
78    v
79}
80
81/// `true` when the document's services carry the relay-only
82/// disclosure marker.
83fn json_is_relay_only(buf: &[u8]) -> bool {
84    contains(buf, b"ApprovedRelaysOnly")
85        || contains(buf, b"QualifiedMultiHop")
86        || contains(buf, b"Isolated")
87}
88
89/// Slice spanning the `service` array body.
90fn service_slice(buf: &[u8]) -> &[u8] {
91    match find_from(buf, 0, b"\"service\":") {
92        Some(i) => &buf[i..],
93        None => &[],
94    }
95}
96
97/// Dotted-quad shape check (four 0–255 octets) — rejected as a
98/// locator.
99fn looks_like_ipv4(s: &[u8]) -> bool {
100    let mut dots = 0u8;
101    let mut digits = 0u8;
102    let mut i = 0;
103    while i < s.len() {
104        match s[i] {
105            b'0'..=b'9' => {
106                digits = digits.saturating_add(1);
107                if digits > 3 {
108                    return false;
109                }
110            }
111            b'.' => {
112                if digits == 0 {
113                    return false;
114                }
115                dots = dots.saturating_add(1);
116                digits = 0;
117            }
118            _ => return false,
119        }
120        i += 1;
121    }
122    dots == 3 && digits > 0
123}
124
125/// Colon-separated IPv6 shape check — rejected as a locator.
126fn looks_like_ipv6(s: &[u8]) -> bool {
127    if s.is_empty() || s.len() > 45 {
128        return false;
129    }
130    let mut colons = 0u8;
131    let mut i = 0;
132    while i < s.len() {
133        match s[i] {
134            b'0'..=b'9' | b'a'..=b'f' | b'A'..=b'F' | b':' | b'.' => {}
135            _ => return false,
136        }
137        if s[i] == b':' {
138            colons = colons.saturating_add(1);
139        }
140        i += 1;
141    }
142    colons >= 2
143}
144
145/// `host:port` shape check — direct network endpoints are forbidden
146/// locators in this profile.
147fn looks_like_host_port(s: &[u8]) -> bool {
148    if let Some(colon) = s.iter().position(|&c| c == b':') {
149        if colon == 0 || colon + 1 >= s.len() {
150            return false;
151        }
152        let host = &s[..colon];
153        let port = &s[colon + 1..];
154        if host.windows(2).any(|w| w == b"::") || looks_like_ipv6(s) {
155            return false;
156        }
157        if host.is_empty() || port.is_empty() || port.len() > 5 {
158            return false;
159        }
160        port.iter().all(|c| c.is_ascii_digit())
161            && host
162                .iter()
163                .all(|c| c.is_ascii_alphanumeric() || *c == b'.' || *c == b'-')
164    } else {
165        false
166    }
167}
168
169/// `true` when any quoted string in the service object is a
170/// forbidden locator (IP/host-port form).
171fn quoted_strings_forbidden(service: &[u8]) -> bool {
172    let mut i = 0;
173    while i < service.len() {
174        if service[i] == b'"' {
175            i += 1;
176            let start = i;
177            while i < service.len() && service[i] != b'"' {
178                i += 1;
179            }
180            let val = &service[start..i];
181            if looks_like_ipv4(val) || looks_like_ipv6(val) || looks_like_host_port(val) {
182                if !val.starts_with(b"did:") && !val.starts_with(b"http") {
183                    return true;
184                }
185            }
186            if i < service.len() {
187                i += 1;
188            }
189            continue;
190        }
191        i += 1;
192    }
193    false
194}
195
196/// Spec §10.3 items 1–4 on QCDE-1 / JSON-LD bytes (encode output and foreign ingest).
197pub fn reject_forbidden_locators(buf: &[u8]) -> Result<(), QiError> {
198    if !json_is_relay_only(buf) {
199        return Ok(());
200    }
201    if contains(buf, b"\"locatorKind\":\"direct\"") || contains(buf, b"\"publicDht\":true") {
202        return Err(QiError::DirectLocatorForbidden);
203    }
204    let mut k = 0;
205    while k < FORBIDDEN_KEYS.len() {
206        if contains(buf, FORBIDDEN_KEYS[k]) {
207            return Err(QiError::DirectLocatorForbidden);
208        }
209        k += 1;
210    }
211    if quoted_strings_forbidden(service_slice(buf)) {
212        return Err(QiError::DirectLocatorForbidden);
213    }
214    Ok(())
215}
216
217/// Decode then §10.3-scan. Use this for foreign JSON (Vector 4).
218pub fn ingest_unsigned_json(buf: &[u8], out: &mut QiDocument) -> Result<(), QiError> {
219    reject_forbidden_locators(buf)?;
220    decode_canonical(buf, out)
221}
222
223/// Decode a `z…` multibase string back to its 32 raw bytes.
224fn decode_mb32(mb: &[u8], out: &mut [u8; 32]) -> Result<(), QiError> {
225    if mb.first() != Some(&b'z') || mb.len() < 2 {
226        return Err(QiError::MalformedDocument);
227    }
228    decode_b58(&mb[1..], out).map(|_| ())
229}
230
231/// Decode a `z…` multibase Ed25519 key — strips and verifies the
232/// `0xed01` multicodec prefix.
233fn decode_pk_multibase(mb: &[u8], pk: &mut [u8; 32]) -> Result<(), QiError> {
234    if mb.first() != Some(&b'z') || mb.len() < 2 {
235        return Err(QiError::MalformedDocument);
236    }
237    let mut raw = [0u8; 34];
238    decode_b58(&mb[1..], &mut raw)?;
239    if raw[0] != 0xed || raw[1] != 0x01 {
240        return Err(QiError::MalformedDocument);
241    }
242    pk.copy_from_slice(&raw[2..]);
243    Ok(())
244}
245
246/// ASCII hex digit → nibble value; `QiError` on non-hex.
247fn hex_nibble(c: u8) -> Result<u8, QiError> {
248    match c {
249        b'0'..=b'9' => Ok(c - b'0'),
250        b'a'..=b'f' => Ok(c - b'a' + 10),
251        b'A'..=b'F' => Ok(c - b'A' + 10),
252        _ => Err(QiError::MalformedDocument),
253    }
254}
255
256/// Decode a 64-char hex string to 32 bytes.
257fn decode_hex32(s: &[u8], out: &mut [u8; 32]) -> Result<(), QiError> {
258    if s.len() != 64 {
259        return Err(QiError::MalformedDocument);
260    }
261    let mut i = 0;
262    while i < 32 {
263        out[i] = (hex_nibble(s[i * 2])? << 4) | hex_nibble(s[i * 2 + 1])?;
264        i += 1;
265    }
266    Ok(())
267}
268
269/// Parse the `alsoKnownAs` array into the fixed `aka` slots —
270/// bounded, errors on overflow.
271fn parse_aka(buf: &[u8], out: &mut QiDocument) -> Result<(), QiError> {
272    let Some(rest) = after(buf, b"\"alsoKnownAs\":") else {
273        return Ok(());
274    };
275    let mut i = 0;
276    while i < rest.len() && rest[i] != b'[' {
277        i += 1;
278    }
279    if i >= rest.len() {
280        return Err(QiError::MalformedDocument);
281    }
282    i += 1;
283    let mut n = 0usize;
284    loop {
285        while i < rest.len() && (rest[i] == b' ' || rest[i] == b'\n' || rest[i] == b',') {
286            i += 1;
287        }
288        if i >= rest.len() {
289            return Err(QiError::MalformedDocument);
290        }
291        if rest[i] == b']' {
292            out.aka_count = n as u8;
293            return Ok(());
294        }
295        if rest[i] != b'"' {
296            return Err(QiError::MalformedDocument);
297        }
298        i += 1;
299        let tok = take_token(&rest[i..]);
300        if n >= MAX_AKA {
301            return Err(QiError::MalformedDocument);
302        }
303        out.aka[n] = AkaEntry::from_slice(tok)?;
304        n += 1;
305        i += tok.len();
306        if i < rest.len() && rest[i] == b'"' {
307            i += 1;
308        }
309    }
310}
311
312/// Parse the disclosure token (`approved-relays-only` / public).
313fn parse_disclosure(s: &[u8]) -> Result<Disclosure, QiError> {
314    if s.starts_with(b"DirectPermitted") {
315        Ok(Disclosure::DirectPermitted)
316    } else if s.starts_with(b"ApprovedRelaysOnly") {
317        Ok(Disclosure::ApprovedRelaysOnly)
318    } else if s.starts_with(b"QualifiedMultiHop") {
319        Ok(Disclosure::QualifiedMultiHop)
320    } else if s.starts_with(b"Isolated") {
321        Ok(Disclosure::Isolated)
322    } else {
323        Err(QiError::MalformedDocument)
324    }
325}
326
327/// Parse the locator class token into `LocatorClass`.
328fn parse_kind(s: &[u8]) -> Result<LocatorClass, QiError> {
329    if s.starts_with(b"mailbox") {
330        Ok(LocatorClass::Mailbox)
331    } else if s.starts_with(b"relayHint") {
332        Ok(LocatorClass::RelayHint)
333    } else if s.starts_with(b"direct") {
334        Ok(LocatorClass::Direct)
335    } else {
336        Err(QiError::MalformedDocument)
337    }
338}
339
340/// Parse the `hints` object into the mailbox (relay priorities,
341/// disclosures).
342fn parse_hints(obj: &[u8], mailbox: &mut CscpMailbox) -> Result<(), QiError> {
343    let Some(rest) = after(obj, b"\"relayHints\":") else {
344        return Ok(());
345    };
346    let mut i = 0;
347    while i < rest.len() && rest[i] != b'[' {
348        i += 1;
349    }
350    if i >= rest.len() {
351        return Ok(());
352    }
353    i += 1;
354    let mut n = 0usize;
355    loop {
356        while i < rest.len() && (rest[i] == b' ' || rest[i] == b'\n' || rest[i] == b',') {
357            i += 1;
358        }
359        if i >= rest.len() {
360            return Err(QiError::MalformedDocument);
361        }
362        if rest[i] == b']' {
363            mailbox.hint_count = n as u8;
364            return Ok(());
365        }
366        if rest[i] != b'{' {
367            return Err(QiError::MalformedDocument);
368        }
369        let start = i;
370        let mut depth = 1i32;
371        i += 1;
372        while i < rest.len() && depth > 0 {
373            if rest[i] == b'{' {
374                depth += 1;
375            } else if rest[i] == b'}' {
376                depth -= 1;
377            }
378            i += 1;
379        }
380        let hint_obj = &rest[start..i];
381        let hid = after(hint_obj, b"\"hintId\":\"")
382            .map(take_token)
383            .ok_or(QiError::MalformedDocument)?;
384        let hx = after(hint_obj, b"\"operatorHashHex\":\"")
385            .map(take_token)
386            .ok_or(QiError::MalformedDocument)?;
387        let mut op = [0u8; 32];
388        decode_hex32(hx, &mut op)?;
389        if n >= MAX_HINTS {
390            return Err(QiError::MalformedDocument);
391        }
392        mailbox.hints[n] = RelayHint::new(hid, op)?;
393        n += 1;
394    }
395}
396
397/// Parse one service object into a `CscpMailbox` (endpoint, kind,
398/// hints).
399fn parse_mailbox(obj: &[u8]) -> Result<CscpMailbox, QiError> {
400    let mut m = CscpMailbox::mailbox([0u8; 32], Disclosure::DirectPermitted);
401    if let Some(rest) = after(obj, b"\"contactKeyMultibase\":\"") {
402        decode_mb32(take_token(rest), &mut m.contact_key)?;
403    }
404    if let Some(rest) = after(obj, b"\"disclosure\":\"") {
405        m.disclosure = parse_disclosure(take_token(rest))?;
406    }
407    if let Some(rest) = after(obj, b"\"generation\":") {
408        m.generation = parse_u32_at(rest);
409    }
410    if let Some(rest) = after(obj, b"\"locatorKind\":\"") {
411        m.kind = parse_kind(take_token(rest))?;
412    }
413    if let Some(rest) = after(obj, b"\"publicDht\":") {
414        m.public_dht = parse_bool_at(rest);
415    }
416    parse_hints(obj, &mut m)?;
417    Ok(m)
418}
419
420/// Next `{…}` object in an array starting at `from` — returns its
421/// end index and body slice.
422fn next_object<'a>(arr: &'a [u8], from: usize) -> Option<(usize, &'a [u8])> {
423    let mut i = from;
424    while i < arr.len() {
425        if arr[i] == b']' {
426            return None;
427        }
428        if arr[i] == b'{' {
429            let start = i;
430            let mut depth = 1i32;
431            i += 1;
432            while i < arr.len() && depth > 0 {
433                if arr[i] == b'{' {
434                    depth += 1;
435                } else if arr[i] == b'}' {
436                    depth -= 1;
437                }
438                i += 1;
439            }
440            return Some((i, &arr[start..i]));
441        }
442        i += 1;
443    }
444    None
445}
446
447/// Parse the `service` array into the fixed `services` slots —
448/// mailbox objects plus the hostname-alias entry.
449fn parse_services(buf: &[u8], out: &mut QiDocument) -> Result<(), QiError> {
450    let Some(svc_at) = find_from(buf, 0, b"\"service\":") else {
451        return Ok(());
452    };
453    let rest = &buf[svc_at + b"\"service\":".len()..];
454    let mut i = 0;
455    while i < rest.len() && rest[i] != b'[' {
456        i += 1;
457    }
458    if i >= rest.len() {
459        return Ok(());
460    }
461    i += 1;
462    let mut mailboxes = 0usize;
463    while let Some((next, obj)) = next_object(rest, i) {
464        i = next;
465        if contains(obj, b"\"type\":\"CscpMailbox\"") {
466            if mailboxes >= MAX_SERVICES {
467                return Err(QiError::MalformedDocument);
468            }
469            out.services[mailboxes] = parse_mailbox(obj)?;
470            mailboxes += 1;
471        } else if contains(obj, b"\"type\":\"HostnameAlias\"") {
472            if let Some(rest) = after(obj, b"\"didWeb\":\"") {
473                out.hostname_did_web = AkaEntry::from_slice(take_token(rest))?;
474                out.has_hostname_alias = true;
475            }
476        }
477    }
478    out.service_count = mailboxes as u8;
479    Ok(())
480}
481
482/// Reconstruct a `QiDocument` from QCDE-1 the encoder emits (F1).
483pub fn decode_canonical(buf: &[u8], out: &mut QiDocument) -> Result<(), QiError> {
484    *out = QiDocument::empty();
485    reject_forbidden_locators(buf)?;
486    if let Some(rest) = after(buf, b"\"generation\":") {
487        out.generation = parse_u32_at(rest);
488    }
489    if let Some(rest) = after(buf, b"\"deactivated\":") {
490        out.deactivated = parse_bool_at(rest);
491    }
492    if let Some(rest) = after(buf, b"\"createdUnix\":") {
493        out.created_unix = parse_u32_at(rest);
494    }
495    if let Some(rest) = after(buf, b"\"previousDigest\":\"") {
496        decode_mb32(take_token(rest), &mut out.previous_digest)?;
497        out.has_previous = true;
498    }
499    if let Some(rest) = after(buf, b"\"publicKeyMultibase\":\"") {
500        decode_pk_multibase(take_token(rest), &mut out.controller_pk)?;
501    }
502    parse_aka(buf, out)?;
503    parse_services(buf, out)?;
504    out.validate()
505}
506
507/// Extract `proof.proofValue` (multibase-z of 64-octet Ed25519 signature).
508pub fn extract_proof_sig(buf: &[u8]) -> Result<[u8; 64], QiError> {
509    let rest = after(buf, b"\"proofValue\":\"").ok_or(QiError::BadSignature)?;
510    let mb = take_token(rest);
511    if mb.first() != Some(&b'z') || mb.len() < 2 {
512        return Err(QiError::BadSignature);
513    }
514    let mut sig = [0u8; 64];
515    decode_b58(&mb[1..], &mut sig).map_err(|_| QiError::BadSignature)?;
516    Ok(sig)
517}