Skip to main content

qualia_core_db/p2p/
social_qdnf.rs

1//! QDNF QFrames over the SocialWebNet userspace-WireGuard mesh.
2//!
3//! Lives in `p2p/`, not `net/qdnf/`: the QDNF tree must not import IP sockets.
4//! WireGuard stays the labelled SocialWebNet transition carrier. Inner packets
5//! remain IPv6 (boringtun drops non-IPv6). QFrames therefore ride the existing
6//! overlay datagram on [`ports::QDNF`]. Chat on [`ports::CHAT`] is unchanged.
7//!
8//! This adapter is **not** Native Independent and does not use libp2p.
9
10#![cfg(not(target_arch = "wasm32"))]
11
12use crate::net::qdnf::bearer::contract::{check_frame_mtu, Bearer, RecvMeta};
13use crate::net::qdnf::bearer::mtu::MIN_QDNF_MTU;
14use crate::net::qdnf::errors::QdnfError;
15use crate::net::qdnf::registries::BearerProfile;
16use crate::net::qdnf::types::{ObservedLocator, ScopeEpoch};
17
18use super::mesh_datagram::{decode_datagram_ref, ports};
19use super::social_webnet::SocialWebNet;
20
21/// QFrame MTU on this overlay. Inner IPv6+UDP adds 48 bytes; 1280 keeps the
22/// encapsulated datagram inside a typical 1500-byte outer path.
23pub const SOCIAL_QDNF_MTU: u16 = MIN_QDNF_MTU;
24
25/// Idle `pump_all` turns before [`SocialQdnfLink::recv`] returns WouldBlock.
26const MAX_RECV_IDLE: usize = 24;
27
28/// SocialWebNet's data plane does not import or construct a libp2p Swarm.
29pub const fn uses_libp2p() -> bool {
30    false
31}
32
33/// Outer carrier is userspace WireGuard (`boringtun`), as in the SocialWebNet profile.
34pub const fn carrier_is_wireguard() -> bool {
35    true
36}
37
38/// Labelled IP/WG transition. Must not be claimed as Native Independent.
39pub const fn native_independent() -> bool {
40    BearerProfile::WireGuardTransitionV1.native_independent()
41}
42
43/// One peer's QDNF overlay on an existing WireGuard tunnel.
44///
45/// `recv` pumps the mesh and consumes inner packets. Use it on a dedicated
46/// test/control path; production chat demuxes [`ports::CHAT`] from `pump_all`
47/// / `MeshService` inbound and ignores this port.
48pub struct SocialQdnfLink<'a> {
49    mesh: &'a mut SocialWebNet,
50    peer_id: &'a str,
51    local: ObservedLocator,
52    remote: ObservedLocator,
53    scope: ScopeEpoch,
54    mtu: u16,
55}
56
57impl<'a> SocialQdnfLink<'a> {
58    /// Attach QDNF to an already-peered tunnel (`peer_id` must exist).
59    pub fn attach(
60        mesh: &'a mut SocialWebNet,
61        peer_id: &'a str,
62        local: ObservedLocator,
63        remote: ObservedLocator,
64        scope: ScopeEpoch,
65        mtu: u16,
66    ) -> Result<Self, QdnfError> {
67        if mtu < MIN_QDNF_MTU {
68            return Err(QdnfError::Range);
69        }
70        Ok(Self {
71            mesh,
72            peer_id,
73            local,
74            remote,
75            scope,
76            mtu,
77        })
78    }
79
80    /// QDNF locator.
81    pub fn locator(&self) -> ObservedLocator {
82        self.local
83    }
84}
85
86/// Copy a QDNF overlay payload from a decrypted inner IPv6 packet into `out`.
87///
88/// `Ok(None)` means the packet is not a QDNF datagram (chat/presence/other).
89pub fn copy_qdnf_frame(inner: &[u8], out: &mut [u8]) -> Result<Option<usize>, QdnfError> {
90    let Some((_src, dst, payload)) = decode_datagram_ref(inner) else {
91        return Ok(None);
92    };
93    if dst != ports::QDNF {
94        return Ok(None);
95    }
96    if payload.len() > out.len() {
97        return Err(QdnfError::Capacity);
98    }
99    out[..payload.len()].copy_from_slice(payload);
100    Ok(Some(payload.len()))
101}
102
103impl Bearer for SocialQdnfLink<'_> {
104    fn profile(&self) -> BearerProfile {
105        BearerProfile::WireGuardTransitionV1
106    }
107
108    fn mtu(&self) -> u16 {
109        self.mtu
110    }
111
112    fn scope(&self) -> ScopeEpoch {
113        self.scope
114    }
115
116    fn send(&mut self, dest: &ObservedLocator, frame: &[u8]) -> Result<usize, QdnfError> {
117        check_frame_mtu(frame.len(), self.mtu)?;
118        if dest.as_slice() != self.remote.as_slice() {
119            return Err(QdnfError::Unauthorized);
120        }
121        let sent = self
122            .mesh
123            .send_qdnf_frame(self.peer_id, frame)
124            .map_err(|_| QdnfError::Closed)?;
125        if !sent {
126            return Err(QdnfError::WouldBlock);
127        }
128        Ok(frame.len())
129    }
130
131    fn recv(&mut self, out: &mut [u8]) -> Result<(usize, RecvMeta), QdnfError> {
132        let mut idles = 0usize;
133        loop {
134            let events = self.mesh.pump_all();
135            let mut progressed = false;
136            for evt in events {
137                let pkt = match evt {
138                    Ok(pkt) => pkt,
139                    Err(_) => return Err(QdnfError::Closed),
140                };
141                progressed = true;
142                if pkt.peer_id != self.peer_id {
143                    continue;
144                }
145                if let Some(n) = copy_qdnf_frame(&pkt.inner, out)? {
146                    return Ok((
147                        n,
148                        RecvMeta {
149                            observed_source: self.remote,
150                            scope: self.scope,
151                            mtu: self.mtu,
152                        },
153                    ));
154                }
155            }
156            if progressed {
157                continue;
158            }
159            idles += 1;
160            if idles >= MAX_RECV_IDLE {
161                return Err(QdnfError::WouldBlock);
162            }
163        }
164    }
165
166    fn shutdown(&mut self) -> Result<(), QdnfError> {
167        Ok(())
168    }
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174    use crate::crypto::network::digest::sha384;
175    use crate::net::qdnf::frame::{decode_frame, encode_frame, FrameHeader, MAGIC};
176    use crate::net::qdnf::registries::{FrameType, NextProtocol};
177    use crate::net::qdnf::session::handshake::handshake_over_fragments;
178    use crate::net::qdnf::types::StrongDigest;
179    use crate::p2p::mesh_datagram::{decode_datagram, encode_datagram};
180    use crate::p2p::social_webnet::SocialWebNet;
181    use crate::p2p::wireguard_userspace::generate_keypair;
182    use std::time::Duration;
183
184    fn loc(b: u8) -> ObservedLocator {
185        ObservedLocator::from_slice(&[b]).unwrap()
186    }
187
188    fn ids() -> (StrongDigest, StrongDigest) {
189        (sha384(b"did:q42:social-a"), sha384(b"did:q42:social-b"))
190    }
191
192    fn peered_meshes() -> (SocialWebNet, SocialWebNet) {
193        let a_keys = generate_keypair();
194        let b_keys = generate_keypair();
195        let (a_pub, b_pub) = (a_keys.public_hex(), b_keys.public_hex());
196        let to = Some(Duration::from_millis(50));
197        let mut a = SocialWebNet::new(a_keys, "127.0.0.1".parse().unwrap(), to);
198        let mut b = SocialWebNet::new(b_keys, "127.0.0.1".parse().unwrap(), to);
199        let a_local = a.add_peer("b", &b_pub, None).unwrap();
200        let b_local = b.add_peer("a", &a_pub, None).unwrap();
201        a.set_peer_endpoint("b", b_local).unwrap();
202        b.set_peer_endpoint("a", a_local).unwrap();
203        a.initiate_handshake("b").unwrap();
204        for _ in 0..40 {
205            if a.has_session("b") && b.has_session("a") {
206                break;
207            }
208            let _ = b.pump_all();
209            let _ = a.pump_all();
210        }
211        assert!(a.has_session("b"), "A WireGuard session");
212        let _ = b.pump_all();
213        assert!(b.has_session("a"), "B WireGuard session");
214        (a, b)
215    }
216
217    #[test]
218    fn honesty_flags_label_wireguard_not_libp2p_or_native() {
219        assert!(!uses_libp2p());
220        assert!(carrier_is_wireguard());
221        assert!(!native_independent());
222        assert!(!BearerProfile::WireGuardTransitionV1.native_independent());
223    }
224
225    #[test]
226    #[serial_test::serial]
227    fn two_meshes_exchange_a_qframe_over_wireguard() {
228        let scope = ScopeEpoch { scope: 1, epoch: 1 };
229        let (mut a, mut b) = peered_meshes();
230        let dest_b = loc(0x02);
231        let dest_a = loc(0x01);
232        let mut a_link =
233            SocialQdnfLink::attach(&mut a, "b", dest_a, dest_b, scope, SOCIAL_QDNF_MTU).unwrap();
234        let header = FrameHeader::new(FrameType::DiscoveryBeacon, NextProtocol::QLink);
235        let mut wire = [0u8; 128];
236        let n = encode_frame(&header, &[], &mut wire).unwrap();
237        assert_eq!(a_link.send(&dest_b, &wire[..n]).unwrap(), n);
238
239        let mut b_link =
240            SocialQdnfLink::attach(&mut b, "a", dest_b, dest_a, scope, SOCIAL_QDNF_MTU).unwrap();
241        assert_eq!(b_link.profile(), BearerProfile::WireGuardTransitionV1);
242        let mut out = [0u8; 256];
243        let (got, meta) = b_link.recv(&mut out).expect("B received a QFrame");
244        assert_eq!(got, n);
245        assert_eq!(&out[..4], &MAGIC);
246        let (decoded, _, _) = decode_frame(&out[..got]).unwrap();
247        assert_eq!(decoded.frame_type, FrameType::DiscoveryBeacon);
248        assert_eq!(decoded.next_protocol, NextProtocol::QLink);
249        assert_eq!(meta.observed_source, dest_a);
250        assert!(!a_link.profile().native_independent());
251    }
252
253    #[test]
254    #[serial_test::serial]
255    fn chat_and_qdnf_demux_on_the_same_tunnel() {
256        let (mut a, mut b) = peered_meshes();
257        assert!(a
258            .send_datagram("b", ports::CHAT, ports::CHAT, b"hello chat")
259            .unwrap());
260        let header = FrameHeader::new(FrameType::DiscoveryBeacon, NextProtocol::QLink);
261        let mut wire = [0u8; 128];
262        let n = encode_frame(&header, &[], &mut wire).unwrap();
263        assert!(a.send_qdnf_frame("b", &wire[..n]).unwrap());
264
265        let mut chat = None;
266        let mut qdnf = None;
267        for _ in 0..40 {
268            for evt in b.pump_all() {
269                let Ok(pkt) = evt else { continue };
270                if let Some(d) = decode_datagram(&pkt.inner) {
271                    if d.dst_port == ports::CHAT {
272                        chat = Some(d.payload);
273                    } else if d.dst_port == ports::QDNF {
274                        qdnf = Some(d.payload);
275                    }
276                }
277            }
278            if chat.is_some() && qdnf.is_some() {
279                break;
280            }
281        }
282        assert_eq!(chat.as_deref(), Some(b"hello chat".as_slice()));
283        let frame = qdnf.expect("QDNF datagram");
284        assert_eq!(&frame[..4], &MAGIC);
285        assert_eq!(frame.len(), n);
286    }
287
288    #[test]
289    #[serial_test::serial]
290    fn fragmented_handshake_over_wireguard_overlay() {
291        let scope = ScopeEpoch { scope: 1, epoch: 1 };
292        let (mut a, mut b) = peered_meshes();
293        let dest_b = loc(0x02);
294        let dest_a = loc(0x01);
295        let mut a_link =
296            SocialQdnfLink::attach(&mut a, "b", dest_a, dest_b, scope, SOCIAL_QDNF_MTU).unwrap();
297        let mut b_link =
298            SocialQdnfLink::attach(&mut b, "a", dest_b, dest_a, scope, SOCIAL_QDNF_MTU).unwrap();
299        let (id_a, id_b) = ids();
300        let done =
301            handshake_over_fragments(&mut a_link, &mut b_link, &dest_b, &dest_a, &id_a, &id_b)
302                .expect("QSession handshake over WG overlay");
303        assert!(done.client_fragments >= 2);
304        assert!(done.server_fragments >= 2);
305        assert_ne!(
306            done.keys.initiator_to_responder,
307            done.keys.responder_to_initiator
308        );
309    }
310
311    #[test]
312    fn unused_overlay_inner_is_not_a_qdnf_frame() {
313        let pkt = encode_datagram(ports::CHAT, ports::CHAT, b"not qdnf");
314        let mut out = [0u8; 64];
315        assert_eq!(copy_qdnf_frame(&pkt, &mut out).unwrap(), None);
316    }
317}