Skip to main content

qualia_core_db/p2p/
wireguard_runtime.rs

1// Userspace WireGuard data-plane runtime — a `Tunn` state machine bound to a real UDP socket.
2//
3// `wireguard_userspace.rs` provides the pure crypto core (keys + a `boringtun::noise::Tunn`
4// state machine) and proves a full handshake + one data packet flow *entirely in memory*.
5// This module is the next layer up: it owns a real `std::net::UdpSocket`, an endpoint for the
6// peer, and drives the `Tunn` over the wire — sending handshake/keepalive/cookie replies
7// automatically, delivering decrypted inner IP packets to the caller, and driving WireGuard's
8// timers. It is the SocialWebNet data plane: two of these, one per peer, carry curated traffic
9// once the address-book coordination plane has exchanged keys and endpoints.
10//
11// Design choices:
12//   * **IPv6-only overlay.** The SocialWebNet inner address space is strictly IPv6 — the same
13//     `fd00::/8` ULA space that `connection_identifier::derive_overlay_addr` mints. IPv4 is
14//     deliberately not carried: the mesh is a clean-slate overlay, and IPv4's NAT/address-scarcity
15//     baggage is exactly what it exists to escape. An authenticated *inner* packet that is IPv4 is
16//     therefore dropped (not delivered), never emitted by us, and treated as peer misconfiguration.
17//   * **Roaming built in.** WireGuard's endpoint is defined as the source of the most recent
18//     *authenticated* packet. Every successful decapsulate updates `peer_endpoint` to the
19//     datagram's source, so a peer whose IP/port changes (dynamic IPs, NAT rebind) is followed
20//     without any coordination-plane round-trip. This is the whole point of a socially-defined
21//     mesh over dynamic addresses. (Roaming acts on the *outer* UDP source, which may be IPv4 or
22//     IPv6 transport — only the *inner* overlay is IPv6-only.)
23//   * **Caller-driven pump, no hidden threads.** `pump()` processes exactly one datagram and
24//     `tick()` runs the timers once. The caller owns the loop (a background thread, an async
25//     task, or a bounded test loop), which keeps the core deterministically testable with two
26//     loopback sockets and no external systems.
27//   * **Reusable scratch buffers.** `recv_buf`/`out_buf` are owned once so the steady-state
28//     path allocates nothing per packet. `boringtun`'s `TunnResult` borrows the *output*
29//     buffer (not the `Tunn`), so sending a produced packet and then reusing the buffer are
30//     disjoint field borrows the compiler accepts.
31//
32// Native-only, exactly like `wireguard_userspace`: `boringtun` does not build for `wasm32`.
33// WASM peers reach the network through a relay, not this path.
34#![cfg(not(target_arch = "wasm32"))]
35
36use std::io::ErrorKind;
37use std::net::{SocketAddr, UdpSocket};
38use std::time::Duration;
39
40use boringtun::noise::{Tunn, TunnResult};
41use boringtun::x25519::PublicKey;
42
43use super::wireguard_userspace::{new_tunnel, WgKeypair};
44
45/// Scratch buffer size — a full UDP datagram (65 535) plus WireGuard framing headroom.
46const MAX_DATAGRAM: usize = 65_535;
47
48/// What one [`WgTunnel::pump`] produced.
49#[derive(Debug)]
50pub enum TunnelEvent {
51    /// A decrypted inner IPv6 packet arrived from the peer — hand it to the virtual interface.
52    InnerPacket(Vec<u8>),
53    /// Only WireGuard control traffic moved (handshake, keepalive, cookie) — or an authenticated
54    /// but non-IPv6 inner packet was dropped; nothing for the caller.
55    Progressed,
56    /// The socket read timed out (or would block) with nothing to do.
57    Idle,
58}
59
60/// A live userspace-WireGuard tunnel to a single peer, bound to a real UDP socket.
61///
62/// Build with [`WgTunnel::bind`], point it at the peer with [`WgTunnel::set_peer_endpoint`]
63/// (or let the first authenticated packet set it via roaming), then either [`initiate_handshake`]
64/// (the initiator) or wait to receive one. Drive it with [`pump`] (per datagram) and [`tick`]
65/// (per second). Encrypt outbound inner packets with [`send_packet`].
66///
67/// [`initiate_handshake`]: WgTunnel::initiate_handshake
68/// [`pump`]: WgTunnel::pump
69/// [`tick`]: WgTunnel::tick
70/// [`send_packet`]: WgTunnel::send_packet
71pub struct WgTunnel {
72    tunn: Tunn,
73    socket: UdpSocket,
74    /// Where we send to. `None` until set explicitly or learned from the first authenticated
75    /// packet (roaming). Updated on every successful decapsulate.
76    peer_endpoint: Option<SocketAddr>,
77    recv_buf: Vec<u8>,
78    out_buf: Vec<u8>,
79}
80
81impl WgTunnel {
82    /// Bind a UDP socket and build the tunnel state machine for `peer_public`.
83    ///
84    /// `bind_addr` may use port 0 to let the OS choose (read it back with [`local_addr`]).
85    /// `index` is a local WireGuard session index (any `u32`, distinct per tunnel). The peer
86    /// endpoint is unset; call [`set_peer_endpoint`] before initiating, or let roaming learn it.
87    ///
88    /// [`local_addr`]: WgTunnel::local_addr
89    /// [`set_peer_endpoint`]: WgTunnel::set_peer_endpoint
90    pub fn bind(
91        mine: &WgKeypair,
92        peer_public: PublicKey,
93        bind_addr: SocketAddr,
94        index: u32,
95    ) -> Result<WgTunnel, String> {
96        let socket = UdpSocket::bind(bind_addr).map_err(|e| format!("bind {bind_addr}: {e}"))?;
97        let tunn = new_tunnel(mine, peer_public, index)?;
98        Ok(WgTunnel {
99            tunn,
100            socket,
101            peer_endpoint: None,
102            recv_buf: vec![0u8; MAX_DATAGRAM],
103            out_buf: vec![0u8; MAX_DATAGRAM],
104        })
105    }
106
107    /// The socket's local address (resolves an OS-chosen port after binding to `:0`).
108    pub fn local_addr(&self) -> Result<SocketAddr, String> {
109        self.socket.local_addr().map_err(|e| e.to_string())
110    }
111
112    /// Borrow the UDP socket (STUN observe on the same port the tunnel will use).
113    pub fn udp_socket(&self) -> &UdpSocket {
114        &self.socket
115    }
116
117    /// The peer endpoint we currently send to, if known.
118    pub fn peer_endpoint(&self) -> Option<SocketAddr> {
119        self.peer_endpoint
120    }
121
122    /// Point the tunnel at `addr`. Roaming may later override this with the source of an
123    /// authenticated packet.
124    pub fn set_peer_endpoint(&mut self, addr: SocketAddr) {
125        self.peer_endpoint = Some(addr);
126    }
127
128    /// Set the socket read timeout so [`pump`] returns [`TunnelEvent::Idle`] instead of blocking
129    /// forever. `None` blocks indefinitely.
130    ///
131    /// [`pump`]: WgTunnel::pump
132    pub fn set_read_timeout(&self, dur: Option<Duration>) -> Result<(), String> {
133        self.socket.set_read_timeout(dur).map_err(|e| e.to_string())
134    }
135
136    /// Has a WireGuard session been established (a handshake completed)?
137    pub fn has_session(&self) -> bool {
138        self.tunn.time_since_last_handshake().is_some()
139    }
140
141    fn endpoint(&self) -> Result<SocketAddr, String> {
142        self.peer_endpoint.ok_or_else(|| {
143            "peer endpoint not set (call set_peer_endpoint or receive a packet first)".to_string()
144        })
145    }
146
147    /// Kick off the Noise_IKpsk2 handshake: produce a handshake initiation and send it to the peer.
148    /// The initiator calls this once; the responder just [`pump`]s and answers automatically.
149    ///
150    /// [`pump`]: WgTunnel::pump
151    pub fn initiate_handshake(&mut self) -> Result<(), String> {
152        let dst = self.endpoint()?;
153        match self.tunn.encapsulate(&[], &mut self.out_buf) {
154            TunnResult::WriteToNetwork(pkt) => {
155                self.socket.send_to(pkt, dst).map_err(|e| e.to_string())?;
156                Ok(())
157            }
158            // Already have a live session — nothing to initiate.
159            TunnResult::Done => Ok(()),
160            TunnResult::Err(e) => Err(format!("handshake init: {e:?}")),
161            other => Err(format!("unexpected handshake-init result: {other:?}")),
162        }
163    }
164
165    /// Encrypt one inner IP packet and send it to the peer.
166    ///
167    /// If no session is up yet, `boringtun` emits a handshake initiation instead of ciphertext;
168    /// we forward that so the handshake starts, and the caller should retry the data send once
169    /// [`has_session`] is true. Returns `Ok(true)` if ciphertext/handshake was sent, `Ok(false)`
170    /// if `boringtun` produced nothing (e.g. the packet was queued pending a handshake).
171    ///
172    /// [`has_session`]: WgTunnel::has_session
173    pub fn send_packet(&mut self, inner: &[u8]) -> Result<bool, String> {
174        let dst = self.endpoint()?;
175        match self.tunn.encapsulate(inner, &mut self.out_buf) {
176            TunnResult::WriteToNetwork(pkt) => {
177                self.socket.send_to(pkt, dst).map_err(|e| e.to_string())?;
178                Ok(true)
179            }
180            TunnResult::Done => Ok(false),
181            TunnResult::Err(e) => Err(format!("encapsulate: {e:?}")),
182            other => Err(format!("unexpected encapsulate result: {other:?}")),
183        }
184    }
185
186    /// Receive one datagram and run it through the tunnel.
187    ///
188    /// Handshake responses, keepalives and cookie replies are sent back to the peer
189    /// automatically (and any queued follow-up packets flushed). A decrypted inner IP packet is
190    /// returned as [`TunnelEvent::InnerPacket`]. On a read timeout, [`TunnelEvent::Idle`].
191    pub fn pump(&mut self) -> Result<TunnelEvent, String> {
192        let (n, from) = match self.socket.recv_from(&mut self.recv_buf) {
193            Ok(v) => v,
194            // No datagram ready within the read timeout.
195            Err(e) if e.kind() == ErrorKind::WouldBlock || e.kind() == ErrorKind::TimedOut => {
196                return Ok(TunnelEvent::Idle)
197            }
198            // Windows UDP quirk: `recv_from` returns WSAECONNRESET (10054 → `ConnectionReset`) when a
199            // *prior* send to the peer drew an ICMP "port unreachable" (peer momentarily down / not
200            // yet listening / behind a NAT that rejected it). A connectionless UDP socket is not
201            // actually closed — the next datagram will still arrive — so this is non-fatal: treat it
202            // as an idle tick, not a dead tunnel. (On Unix the equivalent ICMP error is not delivered
203            // to recv at all, so this arm is effectively Windows-only.)
204            Err(e) if e.kind() == ErrorKind::ConnectionReset => return Ok(TunnelEvent::Idle),
205            Err(e) => return Err(format!("recv_from: {e}")),
206        };
207
208        // Disjoint field borrows: `tunn` (mut), `recv_buf` (read), `out_buf` (mut).
209        let result = self
210            .tunn
211            .decapsulate(None, &self.recv_buf[..n], &mut self.out_buf);
212
213        match result {
214            TunnResult::WriteToNetwork(pkt) => {
215                // Roaming: an authenticated packet came from `from` — send our reply there and
216                // adopt it as the peer endpoint.
217                self.socket.send_to(pkt, from).map_err(|e| e.to_string())?;
218                self.peer_endpoint = Some(from);
219                // `boringtun` requires draining any queued packets with empty-input decapsulate
220                // calls until it stops asking to write to the network.
221                loop {
222                    match self.tunn.decapsulate(None, &[], &mut self.out_buf) {
223                        TunnResult::WriteToNetwork(more) => {
224                            self.socket.send_to(more, from).map_err(|e| e.to_string())?;
225                        }
226                        _ => break,
227                    }
228                }
229                Ok(TunnelEvent::Progressed)
230            }
231            TunnResult::WriteToTunnelV6(data, _) => {
232                let inner = data.to_vec();
233                self.peer_endpoint = Some(from);
234                Ok(TunnelEvent::InnerPacket(inner))
235            }
236            // Authenticated, but IPv4 on an IPv6-only overlay — adopt the endpoint (the packet was
237            // genuine) but drop the payload rather than deliver an unsupported inner protocol.
238            TunnResult::WriteToTunnelV4(_, _) => {
239                self.peer_endpoint = Some(from);
240                Ok(TunnelEvent::Progressed)
241            }
242            TunnResult::Done => {
243                // Authenticated control traffic with nothing to deliver (e.g. a keepalive).
244                self.peer_endpoint = Some(from);
245                Ok(TunnelEvent::Progressed)
246            }
247            TunnResult::Err(e) => Err(format!("decapsulate: {e:?}")),
248        }
249    }
250
251    /// Drive WireGuard's timers once (rekeying, keepalives, session expiry). Call roughly once a
252    /// second from the caller's loop. Sends any timer-produced packet (e.g. a keepalive) to the peer.
253    pub fn tick(&mut self) -> Result<(), String> {
254        // No endpoint yet ⇒ no session ⇒ nothing for the timers to send anywhere.
255        let dst = match self.peer_endpoint {
256            Some(d) => d,
257            None => return Ok(()),
258        };
259        match self.tunn.update_timers(&mut self.out_buf) {
260            TunnResult::WriteToNetwork(pkt) => {
261                self.socket.send_to(pkt, dst).map_err(|e| e.to_string())?;
262                Ok(())
263            }
264            TunnResult::Done => Ok(()),
265            TunnResult::Err(e) => Err(format!("update_timers: {e:?}")),
266            other => Err(format!("unexpected timer result: {other:?}")),
267        }
268    }
269}
270
271#[cfg(test)]
272mod tests {
273    use super::*;
274    use crate::p2p::wireguard_userspace::generate_keypair;
275
276    fn loopback() -> SocketAddr {
277        "127.0.0.1:0".parse().unwrap()
278    }
279
280    /// Build a minimal *valid* IPv6 packet carrying `payload` — `boringtun`'s decapsulate validates
281    /// the IP header (version nibble + length), so a raw byte string would be rejected. The overlay
282    /// is IPv6-only, using `fd00::/8` ULA source/destination addresses (the same space
283    /// `derive_overlay_addr` mints). The 40-byte IPv6 header's payload-length field is set so the
284    /// validated slice equals the whole packet.
285    fn make_ipv6_packet(payload: &[u8]) -> Vec<u8> {
286        let total_len = 40 + payload.len();
287        let mut pkt = vec![0u8; total_len];
288        pkt[0] = 0x60; // version 6, traffic class 0
289        pkt[4..6].copy_from_slice(&(payload.len() as u16).to_be_bytes()); // payload length
290        pkt[6] = 17; // next header = UDP (not inspected)
291        pkt[7] = 64; // hop limit
292        pkt[8] = 0xfd; // src fd00::1 (ULA)
293        pkt[23] = 0x01;
294        pkt[24] = 0xfd; // dst fd00::2 (ULA)
295        pkt[39] = 0x02;
296        pkt[40..].copy_from_slice(payload);
297        pkt
298    }
299
300    /// Two `WgTunnel`s over two real loopback UDP sockets: complete a handshake and carry a data
301    /// packet end-to-end. The acceptance test for "the SocialWebNet data plane works over real
302    /// sockets with zero external systems".
303    #[test]
304    fn two_tunnels_handshake_and_carry_data_over_udp() {
305        let a_keys = generate_keypair();
306        let b_keys = generate_keypair();
307
308        let mut a = WgTunnel::bind(&a_keys, b_keys.public, loopback(), 1).expect("bind A");
309        let mut b = WgTunnel::bind(&b_keys, a_keys.public, loopback(), 2).expect("bind B");
310
311        // Exchange the OS-chosen endpoints (the coordination plane's job in production).
312        let a_addr = a.local_addr().unwrap();
313        let b_addr = b.local_addr().unwrap();
314        a.set_peer_endpoint(b_addr);
315        b.set_peer_endpoint(a_addr);
316
317        // Short read timeouts so pump() never blocks the test.
318        let to = Some(Duration::from_millis(300));
319        a.set_read_timeout(to).unwrap();
320        b.set_read_timeout(to).unwrap();
321
322        // A initiates; drive both sides until A holds a live session.
323        a.initiate_handshake().expect("A initiates handshake");
324        for _ in 0..20 {
325            if a.has_session() {
326                break;
327            }
328            let _ = b.pump().expect("B pump"); // process init → send response
329            let _ = a.pump().expect("A pump"); // process response → establish + keepalive
330        }
331        assert!(a.has_session(), "A established a session");
332
333        // Let B consume the keepalive so it, too, has a live session.
334        let _ = b.pump().expect("B pump keepalive");
335        assert!(b.has_session(), "B established a session");
336
337        // A encrypts an inner IPv6 packet; B should decrypt exactly it.
338        let plaintext = make_ipv6_packet(b"hello over the socially-defined wire");
339        assert!(a.send_packet(&plaintext).expect("A sends data"));
340
341        let mut got = None;
342        for _ in 0..10 {
343            if let TunnelEvent::InnerPacket(p) = b.pump().expect("B pump data") {
344                got = Some(p);
345                break;
346            }
347        }
348        assert_eq!(
349            got.expect("B never received the inner packet"),
350            plaintext,
351            "decrypted inner packet equals what A sent"
352        );
353    }
354
355    /// Roaming: after the session is up, a packet arriving from a *new* source address moves the
356    /// peer endpoint. We simulate B changing address by sending from a second socket that adopts
357    /// B's live `Tunn` is out of scope here; instead we assert the endpoint-follows-source rule
358    /// directly on A by having B send its next packet — B's address is fixed in loopback, so we
359    /// assert the invariant that a successful decapsulate records the source as the endpoint.
360    #[test]
361    fn endpoint_is_learned_from_authenticated_source() {
362        let a_keys = generate_keypair();
363        let b_keys = generate_keypair();
364
365        // A does NOT know B's endpoint up front — it must learn it from B's handshake init.
366        let mut a = WgTunnel::bind(&a_keys, b_keys.public, loopback(), 1).expect("bind A");
367        let mut b = WgTunnel::bind(&b_keys, a_keys.public, loopback(), 2).expect("bind B");
368
369        let a_addr = a.local_addr().unwrap();
370        let b_addr = b.local_addr().unwrap();
371        // Only B is told where A is; A will discover B by roaming.
372        b.set_peer_endpoint(a_addr);
373        assert!(a.peer_endpoint().is_none(), "A starts with no endpoint");
374
375        let to = Some(Duration::from_millis(300));
376        a.set_read_timeout(to).unwrap();
377        b.set_read_timeout(to).unwrap();
378
379        // B initiates; A learns B's address from the authenticated init it receives.
380        b.initiate_handshake().expect("B initiates");
381        for _ in 0..20 {
382            let _ = a.pump().expect("A pump"); // learns endpoint on first authenticated packet
383            let _ = b.pump().expect("B pump");
384            if a.has_session() && a.peer_endpoint().is_some() {
385                break;
386            }
387        }
388        assert_eq!(
389            a.peer_endpoint(),
390            Some(b_addr),
391            "A learned B's endpoint from the authenticated handshake (roaming)"
392        );
393        assert!(
394            a.has_session(),
395            "handshake still completes when the endpoint is learned"
396        );
397    }
398}