Skip to main content

qualia_core_db/net/dns/
sdn.rs

1//! Socially Defined Network (SDN) & QDP Front-Door Engine.
2//!
3//! Provides zero-heap parsing, validation, and topological DID pointer resolution
4//! for Qualia Socially Defined Networks, Front-Door records (`_qdp.<domain>`),
5//! and bare-registrar NS record encoding (`ns*.<payload>.webizen.network`).
6//!
7//! Fully conforms to QualiaDB Rule 0-A (zero-heap in hot paths) and Rule 0-B.
8
9#![allow(dead_code)]
10
11use super::quin_records::encode_sdn_front_door;
12use crate::identifier::parse_did_q42;
13use crate::{q_hash, NQuin, PermissiveRoutingLane};
14
15/// Suffix for Webizen bare-registrar NS record encoding.
16pub const WEBIZEN_NS_SUFFIX: &str = ".webizen.network";
17
18/// View of an SDN Front-Door record pointing directly into borrowed buffers.
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub struct SdnFrontDoorView<'a> {
21    pub domain: &'a str,
22    pub front_door_did: &'a str,
23    pub did_topological_pointer: Option<u64>,
24    pub agent_type: &'a str,
25    pub identity_key_hex: Option<&'a str>,
26    pub wireguard_key_hex: Option<&'a str>,
27    pub overlay_addr: Option<&'a str>,
28    pub nym_addr: Option<&'a str>,
29    pub ecash_addr: Option<&'a str>,
30    pub profile_url: Option<&'a str>,
31}
32
33impl<'a> SdnFrontDoorView<'a> {
34    /// Empty value.
35    pub const fn empty(domain: &'a str) -> Self {
36        Self {
37            domain,
38            front_door_did: "",
39            did_topological_pointer: None,
40            agent_type: "person",
41            identity_key_hex: None,
42            wireguard_key_hex: None,
43            overlay_addr: None,
44            nym_addr: None,
45            ecash_addr: None,
46            profile_url: None,
47        }
48    }
49
50    /// Compute the appropriate PermissiveRoutingLane for this peer.
51    pub fn determine_routing_lane(&self, is_bilateral_friend: bool) -> PermissiveRoutingLane {
52        if is_bilateral_friend {
53            PermissiveRoutingLane::EnforceBilateralMicroCommons
54        } else if self.wireguard_key_hex.is_some() || self.nym_addr.is_some() {
55            PermissiveRoutingLane::EnforcePermissiveCommons
56        } else {
57            PermissiveRoutingLane::PassthroughStandard
58        }
59    }
60
61    /// Convert this Front-Door view into an authoritative Super-Quin.
62    pub fn to_quin(&self, ttl: u32, is_bilateral_friend: bool) -> Option<NQuin> {
63        let pointer = self.did_topological_pointer.unwrap_or_else(|| {
64            if self.front_door_did.starts_with("did:q42:") {
65                parse_did_q42(self.front_door_did.as_bytes())
66                    .unwrap_or_else(|_| q_hash(self.front_door_did))
67            } else {
68                q_hash(self.front_door_did)
69            }
70        });
71        let lane = self.determine_routing_lane(is_bilateral_friend);
72        Some(encode_sdn_front_door(self.domain, pointer, ttl, lane))
73    }
74}
75
76/// Zero-allocation parser for `_qdp.<domain>` TXT payload clauses.
77///
78/// Clauses are separated by `;` and structured as `qdp:<key> <val>` or `qdp:<key> "<val>"`.
79pub fn parse_front_door_txt<'a>(
80    domain: &'a str,
81    txt: &'a str,
82) -> Result<SdnFrontDoorView<'a>, &'static str> {
83    let mut view = SdnFrontDoorView::empty(domain);
84
85    for clause in txt.split(';') {
86        let clause = clause.trim();
87        if clause.is_empty() {
88            continue;
89        }
90        let Some((key, val)) = clause.split_once(|c: char| c.is_whitespace() || c == '=') else {
91            continue;
92        };
93        let key = key.trim();
94        let val = val.trim();
95
96        // Strip quotes or angle brackets
97        let clean_val = val
98            .strip_prefix('<')
99            .and_then(|s| s.strip_suffix('>'))
100            .or_else(|| val.strip_prefix('"').and_then(|s| s.strip_suffix('"')))
101            .unwrap_or(val);
102
103        match key {
104            "qdp:signer" => {
105                view.front_door_did = clean_val;
106                if clean_val.starts_with("did:q42:") {
107                    view.did_topological_pointer = parse_did_q42(clean_val.as_bytes()).ok();
108                }
109            }
110            "qdp:agentType" => {
111                view.agent_type = clean_val;
112            }
113            "qdp:identityKey" => {
114                view.identity_key_hex = Some(clean_val);
115            }
116            "qdp:wireguard" => {
117                view.wireguard_key_hex = Some(clean_val);
118            }
119            "qdp:overlay" => {
120                view.overlay_addr = Some(clean_val);
121            }
122            "qdp:nym" => {
123                view.nym_addr = Some(clean_val);
124            }
125            "qdp:ecash" => {
126                view.ecash_addr = Some(clean_val);
127            }
128            "qdp:profile" => {
129                view.profile_url = Some(clean_val);
130            }
131            _ => {}
132        }
133    }
134
135    if view.front_door_did.is_empty() {
136        return Err("missing qdp:signer in front-door record");
137    }
138
139    Ok(view)
140}
141
142/// Parse a bare-registrar NS record hostname encoding: `ns*.<did-payload>.webizen.network`.
143///
144/// Returns the extracted payload and its `did:q42:` topological pointer if valid.
145/// Zero heap allocations.
146pub fn parse_ns_encoded_did<'a>(ns_hostname: &'a str) -> Option<(&'a str, Option<u64>)> {
147    let host = ns_hostname.trim().trim_end_matches('.');
148    if !host.ends_with(WEBIZEN_NS_SUFFIX) {
149        return None;
150    }
151    let without_suffix = &host[..host.len() - WEBIZEN_NS_SUFFIX.len()];
152
153    // Strip ns1. / ns2. / ns3. / ns4.
154    let payload = if without_suffix.starts_with("ns1.") {
155        &without_suffix[4..]
156    } else if without_suffix.starts_with("ns2.") {
157        &without_suffix[4..]
158    } else if without_suffix.starts_with("ns3.") {
159        &without_suffix[4..]
160    } else if without_suffix.starts_with("ns4.") {
161        &without_suffix[4..]
162    } else {
163        without_suffix
164    };
165
166    if payload.is_empty() {
167        return None;
168    }
169
170    // Attempt topological pointer decode
171    let pointer = if payload.starts_with("did:q42:") {
172        parse_did_q42(payload.as_bytes()).ok()
173    } else {
174        // Construct standard stack buffer for did:q42: prefix
175        let mut did_buf = [0u8; 128];
176        const PREFIX: &[u8] = b"did:q42:";
177        if PREFIX.len() + payload.len() <= did_buf.len() {
178            did_buf[..PREFIX.len()].copy_from_slice(PREFIX);
179            did_buf[PREFIX.len()..PREFIX.len() + payload.len()].copy_from_slice(payload.as_bytes());
180            parse_did_q42(&did_buf[..PREFIX.len() + payload.len()]).ok()
181        } else {
182            None
183        }
184    };
185
186    Some((payload, pointer))
187}
188
189#[cfg(test)]
190mod tests {
191    use super::*;
192
193    #[test]
194    fn parse_front_door_txt_valid() {
195        let txt = r#"qdp:signer <did:q42:z6MkpTHR8VNs> ; qdp:agentType "person" ; qdp:wireguard "a1b2c3d4e5f6" ; qdp:overlay "10.42.0.1""#;
196        let view = parse_front_door_txt("example.org", txt).unwrap();
197
198        assert_eq!(view.domain, "example.org");
199        assert_eq!(view.front_door_did, "did:q42:z6MkpTHR8VNs");
200        assert!(view.did_topological_pointer.is_some());
201        assert_eq!(view.agent_type, "person");
202        assert_eq!(view.wireguard_key_hex, Some("a1b2c3d4e5f6"));
203        assert_eq!(view.overlay_addr, Some("10.42.0.1"));
204
205        let quin = view.to_quin(300, true).unwrap();
206        assert!(quin.verify_ecc_parity());
207        assert_eq!(
208            quin.identify_routing_lane(),
209            PermissiveRoutingLane::EnforceBilateralMicroCommons
210        );
211    }
212
213    #[test]
214    fn parse_ns_encoded_did_valid() {
215        let ns = "ns1.z6MkpTHR8VNs.webizen.network.";
216        let (payload, pointer) = parse_ns_encoded_did(ns).unwrap();
217        assert_eq!(payload, "z6MkpTHR8VNs");
218        assert!(pointer.is_some());
219        // Must have bit 63 set
220        assert!((pointer.unwrap() & (1u64 << 63)) != 0);
221    }
222}