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}