From de464a8fc0b147a8dd281d19c6f18e5532a07af2 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 00:31:36 +0200 Subject: [PATCH] Play with friends without a server: endpoints and key in the code Ludovic can't pay for a hosted relay, so nothing depends on one now. The host's game finds how it can be reached on its own: its interface addresses (LAN, VPNs such as Tailscale or ZeroTier, IPv6), a port opened on the router for an hour at a time (PCP, then NAT-PMP, then UPnP IGD; renewed while sharing, deleted on stop) and its public address from STUN (Cloudflare's and Google's public servers by default, configurable). The invite code carries those endpoints and an 80-bit secret in base32 groups with a checksum; guests dial every endpoint at once and run the same SPAKE2 + ChaCha20-Poly1305 handshake, no rendezvous involved. When nothing can reach the host it says why and what to do (UPnP, the port to forward, a relay, a VPN; CGNAT and double NAT detected). The relay stays as something anyone can run (binary, Dockerfile, systemd unit; Railway config removed): with one configured the host also gets a short code, and the full code names the relay so guests fall back to it. No relay by default. Co-Authored-By: Claude Opus 5.5 --- Cargo.lock | 11 + crates/horizon-friends/Cargo.toml | 2 + crates/horizon-friends/src/direct.rs | 92 +- crates/horizon-friends/src/guest.rs | 126 ++- crates/horizon-friends/src/host.rs | 413 ++++++--- crates/horizon-friends/src/invite.rs | 403 +++++++++ crates/horizon-friends/src/lib.rs | 25 +- crates/horizon-friends/src/portmap.rs | 980 +++++++++++++++++++++ crates/horizon-friends/src/reach.rs | 360 ++++++++ crates/horizon-friends/src/stun.rs | 207 +++++ crates/horizon-relay/Dockerfile | 2 +- crates/horizon-relay/horizon-relay.service | 24 + crates/horizon-relay/railway.toml | 13 - crates/horizon-relay/tests/tunnel.rs | 285 +++--- docs/play-with-friends.md | 400 ++++----- 15 files changed, 2809 insertions(+), 534 deletions(-) create mode 100644 crates/horizon-friends/src/invite.rs create mode 100644 crates/horizon-friends/src/portmap.rs create mode 100644 crates/horizon-friends/src/reach.rs create mode 100644 crates/horizon-friends/src/stun.rs create mode 100644 crates/horizon-relay/horizon-relay.service delete mode 100644 crates/horizon-relay/railway.toml diff --git a/Cargo.lock b/Cargo.lock index b72a657bb..18f4db44a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1039,6 +1039,7 @@ dependencies = [ "chacha20poly1305", "getrandom 0.3.4", "hkdf", + "if-addrs", "serde", "serde_json", "sha2", @@ -1231,6 +1232,16 @@ dependencies = [ "icu_properties", ] +[[package]] +name = "if-addrs" +version = "0.13.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69b2eeee38fef3aa9b4cc5f1beea8a2444fc00e7377cafae396de3f5c2065e24" +dependencies = [ + "libc", + "windows-sys 0.59.0", +] + [[package]] name = "indexmap" version = "2.14.2" diff --git a/crates/horizon-friends/Cargo.toml b/crates/horizon-friends/Cargo.toml index 2d08a0bdd..afe5dbe62 100644 --- a/crates/horizon-friends/Cargo.toml +++ b/crates/horizon-friends/Cargo.toml @@ -15,6 +15,8 @@ sha2 = "0.10" getrandom = "0.3" # SO_REUSEADDR/SO_REUSEPORT for the direct socket (TCP simultaneous open). socket2 = { version = "0.5", features = ["all"] } +# This machine's addresses (LAN, VPNs such as Tailscale or ZeroTier, IPv6) for the code. +if-addrs = "0.13" serde = { version = "1", features = ["derive"] } serde_json = "1.0.151" diff --git a/crates/horizon-friends/src/direct.rs b/crates/horizon-friends/src/direct.rs index 86e155858..7c80822d5 100644 --- a/crates/horizon-friends/src/direct.rs +++ b/crates/horizon-friends/src/direct.rs @@ -5,7 +5,7 @@ use socket2::{Domain, Protocol, SockAddr, Socket, Type}; use std::{ io::{self, Read, Write}, - net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpListener, TcpStream, UdpSocket}, + net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpListener, TcpStream}, sync::{ Arc, atomic::{AtomicBool, Ordering}, @@ -18,6 +18,8 @@ use std::{ pub const RACE: Duration = Duration::from_millis(3000); const RETRY: Duration = Duration::from_millis(250); const MAGIC: &[u8; 4] = b"HZF1"; +/// A guest dialling an endpoint from an invite code (no relay involved). +pub const CODE_MAGIC: &[u8; 4] = b"HZF2"; fn socket_for(addr: &SocketAddr) -> io::Result { let s = Socket::new( @@ -85,47 +87,16 @@ pub fn connect_from(port: Option, to: SocketAddr, timeout: Duration) -> io: TcpStream::connect_timeout(&to, timeout) } -/// The source address the OS would use toward `to` (a UDP socket only picks -/// a route: no packet is sent). -fn route_to(to: SocketAddr) -> Option { - let bind = unspecified(to.is_ipv6(), 0); - let s = UdpSocket::bind(bind).ok()?; - s.connect(to).ok()?; - let ip = s.local_addr().ok()?.ip(); - (!ip.is_unspecified()).then_some(ip) -} - -/// The addresses this machine can be reached on, best first: toward the -/// relay (a LAN or tailnet address when the relay is near), then toward the -/// public IPv4 and IPv6 internet. Loopback only when the relay is local. -pub fn local_addresses(relay: Option) -> Vec { - let mut targets: Vec = relay.into_iter().collect(); - targets.push(SocketAddr::from(([1, 1, 1, 1], 53))); - targets.push(SocketAddr::from(( - [0x2606, 0x4700, 0x4700, 0, 0, 0, 0, 0x1111], - 53, - ))); - let local_relay = relay.is_some_and(|r| r.ip().is_loopback()); - let mut out = Vec::new(); - for t in targets { - if let Some(ip) = route_to(t) - && (local_relay || !ip.is_loopback()) - && !out.contains(&ip) - { - out.push(ip); - } - } - out -} - -/// This end's candidates: each local address with the direct port, then the -/// address the relay saw (when it is not one of them). +/// This end's candidates for a relayed session: its interface addresses +/// with the direct port (loopback when the relay is local), then the address +/// the relay saw (when it is not one of them). pub fn candidates( port: u16, relay: Option, observed: Option, ) -> Vec { - let mut out: Vec = local_addresses(relay) + let loopback = relay.is_some_and(|r| r.ip().is_loopback()); + let mut out: Vec = crate::reach::interface_addresses(loopback) .into_iter() .map(|ip| SocketAddr::new(ip, port)) .collect(); @@ -135,6 +106,7 @@ pub fn candidates( { out.push(o); } + out.truncate(crate::invite::MAX_ENDPOINTS); out } @@ -171,6 +143,52 @@ pub fn read_session(stream: &mut TcpStream) -> io::Result { } Ok(u64::from_be_bytes(theirs[4..].try_into().unwrap())) } +/// What an inbound stream on the host's direct port is. +pub enum Hello { + /// A relayed session's direct race. + Relayed(u64), + /// A guest with the invite code. + Code(u64), +} +pub fn read_hello(stream: &mut TcpStream) -> io::Result { + stream.set_read_timeout(Some(Duration::from_secs(5)))?; + let mut theirs = [0u8; 12]; + stream.read_exact(&mut theirs)?; + let session = u64::from_be_bytes(theirs[4..].try_into().unwrap()); + match &theirs[..4] { + m if m == MAGIC => Ok(Hello::Relayed(session)), + m if m == CODE_MAGIC => Ok(Hello::Code(session)), + _ => Err(io::Error::new( + io::ErrorKind::InvalidData, + "not a Horizon stream", + )), + } +} +/// The guest's side of a code session's opening: send the hello, wait for +/// its echo (proof a Horizon host listens there). +pub fn code_hello(stream: &mut TcpStream, session: u64) -> io::Result<()> { + let mut hello = [0u8; 12]; + hello[..4].copy_from_slice(CODE_MAGIC); + hello[4..].copy_from_slice(&session.to_be_bytes()); + stream.set_read_timeout(Some(Duration::from_secs(4)))?; + stream.write_all(&hello)?; + let mut theirs = [0u8; 12]; + stream.read_exact(&mut theirs)?; + if theirs != hello { + return Err(io::Error::new( + io::ErrorKind::InvalidData, + "not a Horizon host", + )); + } + Ok(()) +} +/// The host echoes a code session's hello. +pub fn answer_code(stream: &mut TcpStream, session: u64) -> io::Result<()> { + let mut hello = [0u8; 12]; + hello[..4].copy_from_slice(CODE_MAGIC); + hello[4..].copy_from_slice(&session.to_be_bytes()); + stream.write_all(&hello) +} /// Answer an inbound stream's introduction for `session`. pub fn answer(stream: &mut TcpStream, session: u64) -> io::Result<()> { let mut hello = [0u8; 12]; diff --git a/crates/horizon-friends/src/guest.rs b/crates/horizon-friends/src/guest.rs index a40361acc..4f64bb1cc 100644 --- a/crates/horizon-friends/src/guest.rs +++ b/crates/horizon-friends/src/guest.rs @@ -1,24 +1,30 @@ -//! The guest's end: find the host behind a code, agree on the key, settle -//! on a direct or relayed stream, then offer it on a loopback port the +//! The guest's end: reach the host from the code (directly, or through a +//! relay), agree on the key, then offer the session on a loopback port the //! game's client connects to like to any server. use crate::{ Code, PathMode, crypto::{self, Role}, - direct, resolve_relay, + direct, + invite::{Invite, Parsed}, + resolve_relay, session::{self, Secure}, wire::{self, ErrorCode, FromRelay, ToRelay}, }; use std::{ fmt, io, net::{Ipv4Addr, SocketAddr, TcpListener, TcpStream}, + sync::mpsc::channel, thread::JoinHandle, - time::Duration, + time::{Duration, Instant}, }; pub struct GuestConfig { - pub relay: String, - pub code: Code, - /// The game's protocol number and version name (the relay refuses a + /// The code as pasted: a full invite, or a relay's short code. + pub code: String, + /// The relay to use for short codes (the player's setting); a full + /// invite names its own. + pub relay: Option, + /// The game's protocol number and version name (a relay refuses a /// guest whose protocol differs from the host's). pub protocol: i32, pub game: String, @@ -28,8 +34,11 @@ pub struct GuestConfig { /// Why joining failed, in words for the player. #[derive(Debug)] pub enum JoinError { - /// No relay is configured in this build. - NotAvailable, + BadCode(crate::invite::CodeError), + /// A short code without a relay to resolve it. + NeedsRelay, + /// None of the code's endpoints answered, and no relay to fall back to. + NotReachable, Unreachable(String), UnknownCode, Ended, @@ -46,8 +55,16 @@ pub enum JoinError { impl fmt::Display for JoinError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { - Self::NotAvailable => write!(f, "Joining friends is not available yet in this build."), - Self::Unreachable(e) => write!(f, "Couldn't reach the invite service ({e})."), + Self::BadCode(e) => write!(f, "{e}"), + Self::NeedsRelay => write!( + f, + "This short code works through your friend's relay: add the relay's address under Join a friend, or ask for the full code." + ), + Self::NotReachable => write!( + f, + "Couldn't reach your friend's game. Ask them to read the note under their code: they may need UPnP on their router, a forwarded port, a relay or a VPN." + ), + Self::Unreachable(e) => write!(f, "Couldn't reach the relay ({e})."), Self::UnknownCode => write!( f, "No world uses this code. Check it, or ask your friend for a new one." @@ -90,10 +107,76 @@ pub struct Tunnel { pub direct: bool, } -/// Find the host, agree on the key and settle on a path. Blocks for up to a -/// few seconds (the direct race). +/// Join with what the player pasted: a full invite is dialled directly +/// (every endpoint at once), then through the relay it names, if any; a +/// short code goes through the configured relay. Blocks for a few seconds. pub fn join(config: &GuestConfig) -> Result { - let relays = resolve_relay(&config.relay).map_err(|e| JoinError::Unreachable(e.to_string()))?; + match crate::invite::parse_detailed(&config.code).map_err(JoinError::BadCode)? { + Parsed::Short(code) => { + let relay = config.relay.as_deref().ok_or(JoinError::NeedsRelay)?; + join_relay(config, relay, &code) + } + Parsed::Long(invite) => { + if config.path != PathMode::RelayOnly + && !invite.endpoints.is_empty() + && let Some(t) = join_direct(&invite)? + { + return Ok(t); + } + match &invite.relay { + Some(r) if config.path != PathMode::DirectOnly => { + join_relay(config, &r.address, &r.code) + } + _ => Err(JoinError::NotReachable), + } + } + } +} + +/// Dial every endpoint of the code; the first that answers as a Horizon +/// host gets the handshake, the others are dropped before it. +fn join_direct(invite: &Invite) -> Result, JoinError> { + let (tx, rx) = channel(); + let deadline = Instant::now() + Duration::from_secs(5); + let mut session = [0u8; 8]; + crate::fill_random(&mut session).map_err(|e| JoinError::Failed(e.to_string()))?; + let session = u64::from_le_bytes(session); + for &endpoint in &invite.endpoints { + let tx = tx.clone(); + let _ = std::thread::Builder::new() + .name("horizon-friends-dial".into()) + .spawn(move || { + if let Ok(mut s) = TcpStream::connect_timeout(&endpoint, Duration::from_secs(4)) + && direct::code_hello(&mut s, session).is_ok() + { + let _ = tx.send(s); + } + }); + } + drop(tx); + let left = deadline.saturating_duration_since(Instant::now()); + let Ok(mut stream) = rx.recv_timeout(left) else { + return Ok(None); + }; + let key = crypto::exchange(&mut stream, &invite.secret_text(), "direct", session) + .map_err(|e| JoinError::Failed(e.to_string()))?; + let secure = session::secure(stream, &key, Role::Guest).map_err(|e| { + if crypto::is_wrong_code(&e) { + JoinError::WrongCode + } else { + JoinError::Failed(e.to_string()) + } + })?; + Ok(Some(Tunnel { + secure, + direct: true, + })) +} + +/// Through a relay with its short code (its own direct race, then the +/// relay's byte stream). +fn join_relay(config: &GuestConfig, relay_url: &str, code: &Code) -> Result { + let relays = resolve_relay(relay_url).map_err(|e| JoinError::Unreachable(e.to_string()))?; let direct_allowed = config.path != PathMode::RelayOnly; let (listeners, port) = if direct_allowed { match direct::listen(0) { @@ -124,7 +207,7 @@ pub fn join(config: &GuestConfig) -> Result { &mut stream, &ToRelay::Join { v: wire::VERSION, - nameplate: config.code.nameplate.clone(), + nameplate: code.nameplate.clone(), protocol: config.protocol, game: config.game.clone(), }, @@ -143,20 +226,13 @@ pub fn join(config: &GuestConfig) -> Result { ErrorCode::HostUnreachable => JoinError::HostUnreachable, ErrorCode::Full => JoinError::Full, ErrorCode::RateLimited => JoinError::RateLimited, - ErrorCode::BadRequest => { - JoinError::Failed("the invite service refused the request".into()) - } + ErrorCode::BadRequest => JoinError::Failed("the relay refused the request".into()), }); } other => return Err(JoinError::Failed(format!("unexpected answer {other:?}"))), }; - let key = crypto::exchange( - &mut stream, - &config.code.secret, - &config.code.nameplate, - session, - ) - .map_err(|_| JoinError::HostUnreachable)?; + let key = crypto::exchange(&mut stream, &code.secret, &code.nameplate, session) + .map_err(|_| JoinError::HostUnreachable)?; let relayed = session::secure(stream, &key, Role::Guest).map_err(|e| { if crypto::is_wrong_code(&e) { JoinError::WrongCode diff --git a/crates/horizon-friends/src/host.rs b/crates/horizon-friends/src/host.rs index 567d8ff42..d7f4ae6c2 100644 --- a/crates/horizon-friends/src/host.rs +++ b/crates/horizon-friends/src/host.rs @@ -1,56 +1,76 @@ -//! The host's end: registers with the relay for a code and keeps that -//! control connection open; for each guest the relay announces, attaches a -//! new connection, agrees on the key, settles on a path and connects the -//! session to the integrated server's port. Everything runs on its own -//! threads; the game polls [`Host::poll`] and [`Host::state`]. +//! The host's end. It listens on its direct port, works out how it can be +//! reached (interfaces, a router mapping, STUN) and puts that with a fresh +//! secret into the invite code: guests with the code dial it directly, no +//! server involved. When a relay is configured (the player's own, or any +//! they trust), it also registers there for a short code and serves relayed +//! sessions (with their own direct race, then the relay as fallback). +//! Every session ends at the integrated server's port. Everything runs on +//! its own threads; the game polls [`Host::poll`] and [`Host::state`]. use crate::{ Code, PathMode, crypto::{self, Role}, - direct, resolve_relay, session, + direct, + invite::{Invite, RelayRef}, + reach::{self, Reach, Verdict}, + resolve_relay, session, wire::{self, FromRelay, ToRelay}, }; use std::{ collections::HashMap, io::{self, BufReader}, - net::{Shutdown, SocketAddr, TcpStream}, + net::{Shutdown, SocketAddr, TcpListener, TcpStream}, sync::{ Arc, Mutex, - atomic::{AtomicBool, AtomicU32, Ordering}, + atomic::{AtomicBool, AtomicU32, AtomicUsize, Ordering}, mpsc::{Receiver, Sender, channel}, }, thread::JoinHandle, time::{Duration, Instant}, }; -/// Wrong codes tried before the host retires its code for a new one. +/// Wrong short codes tried at the relay before the host retires it. pub const MAX_WRONG: u32 = 5; -/// Guests that can be connecting at once (IntegratedServer.MAX_PLAYERS). +/// Sessions open at once (IntegratedServer.MAX_PLAYERS). pub const MAX_SESSIONS: usize = 8; +/// The direct port asked for first, so a port forwarded by hand keeps +/// working from one session to the next (`HORIZON_FRIENDS_PORT`). +pub const DEFAULT_PORT: u16 = 25580; +/// Code handshakes in progress at once (scanners can't pile them up). +const MAX_HANDSHAKES: usize = 8; #[derive(Clone)] pub struct HostConfig { - pub relay: String, /// The integrated server's port (Open to LAN's). pub lan: SocketAddr, pub protocol: i32, pub game: String, + /// A relay to register with as well (short code, relay fallback). + pub relay: Option, pub path: PathMode, + /// The direct port to ask for (0: any). + pub port: u16, + pub reach: reach::Options, } -#[derive(Clone, Debug, PartialEq, Eq)] -pub enum HostState { - /// Waiting for the relay's answer. - Registering, - Sharing(Code), - /// The relay is unreachable or refused; retrying. - Retrying(String), - Stopped, +/// What the host's game shows. +#[derive(Clone, Debug, Default)] +pub struct HostState { + /// The invite code; None while the host is still finding its addresses. + pub invite: Option, + /// The relay's short code, when registered with one. + pub short: Option, + /// Who can join, and what to do when friends on the internet can't. + pub summary: String, + pub verdict: Option, + /// Why the relay isn't serving, when one is configured. + pub relay_problem: Option, + pub port: u16, } #[derive(Debug)] pub enum HostEvent { - /// A new code (the first, or after the relay restarted or wrong codes). - Code(Code), + /// A new invite code (the first, or after the relay's short code changed). + Code(String), /// A guest's session is carried directly or through the relay. Connected { session: u64, @@ -59,7 +79,7 @@ pub enum HostEvent { Disconnected { session: u64, }, - /// Someone used the nameplate with the wrong secret. + /// Someone tried a wrong code. WrongCode { count: u32, }, @@ -70,72 +90,97 @@ struct Shared { stop: AtomicBool, state: Mutex, events: Mutex>, - /// The current control connection (shut down to stop). + /// The invite (endpoints and secret), rebuilt when the relay part changes. + invite: Mutex>, + /// The current relay control connection (shut down to stop). control: Mutex>, - /// Inbound direct streams waiting for their session. + /// Inbound direct streams waiting for their relayed session. routes: Mutex, Instant)>>, - sessions: Mutex, + sessions: AtomicUsize, + handshakes: AtomicUsize, wrong: AtomicU32, + relay_wrong: AtomicU32, + reach: Mutex>, } impl Shared { fn emit(&self, e: HostEvent) { let _ = self.events.lock().unwrap().send(e); } - fn set(&self, s: HostState) { - *self.state.lock().unwrap() = s; - } fn stopped(&self) -> bool { self.stop.load(Ordering::Relaxed) } + /// Rebuild the code from the invite and the relay's short code. + fn publish(&self, short: Option) { + let text = { + let mut invite = self.invite.lock().unwrap(); + let Some(inv) = invite.as_mut() else { return }; + inv.relay = match (&short, &self.config.relay) { + (Some(code), Some(address)) => Some(RelayRef { + address: address.clone(), + code: code.clone(), + }), + _ => None, + }; + inv.encode() + }; + { + let mut s = self.state.lock().unwrap(); + if s.invite.as_deref() == Some(&text) && s.short == short { + return; + } + s.invite = Some(text.clone()); + s.short = short; + } + self.emit(HostEvent::Code(text)); + } } pub struct Host { shared: Arc, events: Receiver, - thread: Option>, - accept: Option>, + threads: Vec>, } impl Host { - /// Start sharing in the background: the code arrives as an event. + /// Start sharing in the background: the code arrives as an event once + /// the host knows its addresses (a few seconds). pub fn start(config: HostConfig) -> io::Result { let (tx, events) = channel(); - let listeners = if config.path == PathMode::RelayOnly { - None - } else { - direct::listen(0).ok() - }; + let (listeners, port) = direct::listen(config.port).or_else(|_| direct::listen(0))?; let shared = Arc::new(Shared { config, stop: AtomicBool::new(false), - state: Mutex::new(HostState::Registering), + state: Mutex::new(HostState { + port, + ..HostState::default() + }), events: Mutex::new(tx), + invite: Mutex::new(None), control: Mutex::new(None), routes: Mutex::new(HashMap::new()), - sessions: Mutex::new(0), + sessions: AtomicUsize::new(0), + handshakes: AtomicUsize::new(0), wrong: AtomicU32::new(0), + relay_wrong: AtomicU32::new(0), + reach: Mutex::new(None), }); - let port = listeners.as_ref().map(|(_, p)| *p); - let accept = match listeners { - Some((l, _)) => { - let s = shared.clone(); - Some( - std::thread::Builder::new() - .name("horizon-friends-listen".into()) - .spawn(move || route_inbound(l, s))?, - ) - } - None => None, - }; + let mut threads = Vec::new(); let s = shared.clone(); - let thread = std::thread::Builder::new() - .name("horizon-friends-host".into()) - .spawn(move || run(s, port))?; + threads.push( + std::thread::Builder::new() + .name("horizon-friends-listen".into()) + .spawn(move || route_inbound(listeners, s))?, + ); + let s = shared.clone(); + threads.push( + std::thread::Builder::new() + .name("horizon-friends-reach".into()) + .spawn(move || share(s, port))?, + ); Ok(Self { shared, events, - thread: Some(thread), - accept, + threads, }) } pub fn state(&self) -> HostState { @@ -146,22 +191,22 @@ impl Host { } /// Guests whose sessions are open (connecting or playing). pub fn sessions(&self) -> usize { - *self.shared.sessions.lock().unwrap() + self.shared.sessions.load(Ordering::Relaxed) } - /// End the code. Sessions already playing go on until the integrated - /// server closes them (stopping the LAN server ends them). + /// End the code: close the direct port, delete the router mapping, leave + /// the relay. Sessions already playing go on until the integrated server + /// closes them. pub fn stop(&mut self) { self.shared.stop.store(true, Ordering::Relaxed); if let Some(c) = self.shared.control.lock().unwrap().take() { let _ = c.shutdown(Shutdown::Both); } - if let Some(t) = self.thread.take() { + for t in self.threads.drain(..) { let _ = t.join(); } - if let Some(t) = self.accept.take() { - let _ = t.join(); + if let Some(r) = self.shared.reach.lock().unwrap().as_mut() { + r.release(); } - self.shared.set(HostState::Stopped); } } impl Drop for Host { @@ -170,30 +215,105 @@ impl Drop for Host { } } -/// Hand inbound direct streams to the session they introduce themselves for. -fn route_inbound(listeners: Vec, shared: Arc) { +/// Find the addresses, publish the code, keep the router mapping alive, +/// serve the relay when there is one. +fn share(shared: Arc, port: u16) { + let config = &shared.config; + let reach = if config.path == PathMode::RelayOnly { + Reach { + port, + ..Reach::default() + } + } else { + Reach::discover(port, &config.reach) + }; + let endpoints = if config.path == PathMode::RelayOnly { + Vec::new() + } else { + reach.endpoints() + }; + let invite = match Invite::new(port, endpoints, None) { + Ok(i) => i, + Err(_) => return, + }; + { + let mut s = shared.state.lock().unwrap(); + s.summary = if config.path == PathMode::RelayOnly { + "Friends join through the relay only.".into() + } else { + reach.summary() + }; + s.verdict = Some(reach.verdict()); + } + *shared.invite.lock().unwrap() = Some(invite); + *shared.reach.lock().unwrap() = Some(reach); + if shared.stopped() { + return; + } + shared.publish(None); + let relay = match &config.relay { + Some(r) => { + let s = shared.clone(); + let r = r.clone(); + std::thread::Builder::new() + .name("horizon-friends-relay".into()) + .spawn(move || run_relay(s, r)) + .ok() + } + None => None, + }; + // Renew the router mapping at half-lease until stopped. + while !shared.stopped() { + std::thread::sleep(Duration::from_millis(100)); + let mut reach = shared.reach.lock().unwrap(); + if let Some(m) = reach.as_mut().and_then(|r| r.mapping.as_mut()) + && m.due() + && m.renew().is_err() + { + // Try again in a minute rather than hammering the router. + m.renewed = Instant::now() - m.lifetime / 2 + Duration::from_secs(60); + } + } + if let Some(t) = relay { + let _ = t.join(); + } +} + +/// Inbound streams on the direct port: a relayed session's direct race, or +/// a guest with the code. +fn route_inbound(listeners: Vec, shared: Arc) { while !shared.stopped() { let mut idle = true; for l in &listeners { let Ok((mut s, _)) = l.accept() else { continue }; idle = false; + if shared.handshakes.load(Ordering::Relaxed) >= MAX_HANDSHAKES { + continue; + } + shared.handshakes.fetch_add(1, Ordering::Relaxed); let shared = shared.clone(); let _ = std::thread::Builder::new() .name("horizon-friends-inbound".into()) .spawn(move || { let _ = s.set_nonblocking(false); - let Ok(session) = direct::read_session(&mut s) else { - return; - }; - let route = { - let mut routes = shared.routes.lock().unwrap(); - routes.retain(|_, (_, until)| *until > Instant::now()); - routes.get(&session).map(|(tx, _)| tx.clone()) - }; - if let Some(tx) = route - && direct::answer(&mut s, session).is_ok() - { - let _ = tx.send(s); + match direct::read_hello(&mut s) { + Ok(direct::Hello::Relayed(session)) => { + shared.handshakes.fetch_sub(1, Ordering::Relaxed); + let route = { + let mut routes = shared.routes.lock().unwrap(); + routes.retain(|_, (_, until)| *until > Instant::now()); + routes.get(&session).map(|(tx, _)| tx.clone()) + }; + if let Some(tx) = route + && direct::answer(&mut s, session).is_ok() + { + let _ = tx.send(s); + } + } + Ok(direct::Hello::Code(session)) => serve_code(&shared, s, session), + Err(_) => { + shared.handshakes.fetch_sub(1, Ordering::Relaxed); + } } }); } @@ -203,13 +323,61 @@ fn route_inbound(listeners: Vec, shared: Arc) { } } -fn connect_relay(config: &HostConfig, port: Option) -> io::Result<(TcpStream, SocketAddr)> { +/// A guest who dialled an endpoint from the code: agree on the key from +/// the code's secret, then carry the session. +fn serve_code(shared: &Arc, mut s: TcpStream, session: u64) { + let secret = shared + .invite + .lock() + .unwrap() + .as_ref() + .map(Invite::secret_text); + let secured = (|| -> io::Result { + let secret = secret.ok_or_else(|| io::Error::other("not ready"))?; + direct::answer_code(&mut s, session)?; + let key = crypto::exchange(&mut s, &secret, "direct", session)?; + session::secure(s, &key, Role::Host) + })(); + shared.handshakes.fetch_sub(1, Ordering::Relaxed); + match secured { + Ok(secure) => carry(shared, session, secure, true), + Err(e) if crypto::is_wrong_code(&e) => { + let count = shared.wrong.fetch_add(1, Ordering::Relaxed) + 1; + shared.emit(HostEvent::WrongCode { count }); + } + Err(_) => {} + } +} + +/// Connect a settled session to the integrated server and carry it. +fn carry(shared: &Arc, session: u64, (r, w): session::Secure, direct: bool) { + if shared.sessions.fetch_add(1, Ordering::Relaxed) >= MAX_SESSIONS { + shared.sessions.fetch_sub(1, Ordering::Relaxed); + let _ = r.get_ref().shutdown(Shutdown::Both); + return; + } + let Ok(server) = TcpStream::connect_timeout(&shared.config.lan, Duration::from_secs(5)) else { + let _ = r.get_ref().shutdown(Shutdown::Both); + shared.sessions.fetch_sub(1, Ordering::Relaxed); + return; + }; + shared.emit(HostEvent::Connected { session, direct }); + if let Ok(t) = crate::pump(server, r, w) { + let _ = t.join(); + } + shared.sessions.fetch_sub(1, Ordering::Relaxed); + shared.emit(HostEvent::Disconnected { session }); +} + +// ----- The relay (optional) --------------------------------------------------------------------- + +fn connect_relay(relay: &str, port: Option) -> io::Result<(TcpStream, SocketAddr)> { let mut last = io::Error::other("no address"); - for relay in resolve_relay(&config.relay)? { - match direct::connect_from(port, relay, Duration::from_secs(5)) { + for address in resolve_relay(relay)? { + match direct::connect_from(port, address, Duration::from_secs(5)) { Ok(s) => { let _ = s.set_nodelay(true); - return Ok((s, relay)); + return Ok((s, address)); } Err(e) => last = e, } @@ -218,17 +386,22 @@ fn connect_relay(config: &HostConfig, port: Option) -> io::Result<(TcpStrea } /// Register, serve the control connection, register again when it drops -/// (a new code) until stopped. -fn run(shared: Arc, port: Option) { +/// (a new short code) until stopped. +fn run_relay(shared: Arc, relay: String) { let mut backoff = Duration::from_secs(1); while !shared.stopped() { - match register(&shared, port) { - Ok(()) => backoff = Duration::from_secs(1), + match register(&shared, &relay) { + Ok(()) => { + backoff = Duration::from_secs(1); + shared.state.lock().unwrap().relay_problem = None; + } Err(e) => { if shared.stopped() { break; } - shared.set(HostState::Retrying(e.to_string())); + shared.state.lock().unwrap().relay_problem = + Some(format!("Couldn't reach the relay {relay}: {e}")); + shared.publish(None); let until = Instant::now() + backoff; while Instant::now() < until && !shared.stopped() { std::thread::sleep(Duration::from_millis(50)); @@ -239,11 +412,12 @@ fn run(shared: Arc, port: Option) { } } -fn register(shared: &Arc, port: Option) -> io::Result<()> { +fn register(shared: &Arc, relay_url: &str) -> io::Result<()> { let config = &shared.config; + let port = Some(shared.state.lock().unwrap().port); // The control connection uses any port: the direct port stays free for // the attach connections, whose observed address is the one that counts. - let (mut control, relay) = connect_relay(config, None)?; + let (mut control, relay) = connect_relay(relay_url, None)?; control.set_read_timeout(Some(Duration::from_secs(70)))?; wire::send( &mut control, @@ -259,10 +433,7 @@ fn register(shared: &Arc, port: Option) -> io::Result<()> { nameplate, token, .. } => (nameplate, token), FromRelay::Error { code, .. } => { - return Err(io::Error::other(format!( - "the invite service refused: {}", - code.as_str() - ))); + return Err(io::Error::other(format!("it refused ({})", code.as_str()))); } other => return Err(io::Error::other(format!("unexpected answer {other:?}"))), }; @@ -272,15 +443,16 @@ fn register(shared: &Arc, port: Option) -> io::Result<()> { let _ = control.shutdown(Shutdown::Both); return Ok(()); } - shared.wrong.store(0, Ordering::Relaxed); - shared.set(HostState::Sharing(code.clone())); - shared.emit(HostEvent::Code(code.clone())); + shared.relay_wrong.store(0, Ordering::Relaxed); + shared.publish(Some(code.clone())); loop { let message = match wire::recv_buffered::<_, FromRelay>(&mut reader) { Ok(m) => m, Err(e) => { shared.control.lock().unwrap().take(); - return if shared.stopped() || shared.wrong.load(Ordering::Relaxed) >= MAX_WRONG { + return if shared.stopped() + || shared.relay_wrong.load(Ordering::Relaxed) >= MAX_WRONG + { Ok(()) } else { Err(e) @@ -290,23 +462,22 @@ fn register(shared: &Arc, port: Option) -> io::Result<()> { match message { FromRelay::Ping => wire::send(&mut control, &ToRelay::Pong)?, FromRelay::Join { session } => { - let mut open = shared.sessions.lock().unwrap(); - if *open >= MAX_SESSIONS { + if shared.sessions.load(Ordering::Relaxed) >= MAX_SESSIONS { continue; } - *open += 1; - drop(open); - let (shared, code, token, control) = ( + let (shared, code, token, control, relay_url) = ( shared.clone(), code.clone(), token.clone(), control.try_clone()?, + relay_url.to_owned(), ); let _ = std::thread::Builder::new() .name("horizon-friends-session".into()) .spawn(move || { - serve(&shared, &code, &token, session, port, relay, &control); - *shared.sessions.lock().unwrap() -= 1; + serve_relayed( + &shared, &relay_url, &code, &token, session, port, relay, &control, + ) }); } _ => {} @@ -314,10 +485,12 @@ fn register(shared: &Arc, port: Option) -> io::Result<()> { } } -/// One guest: attach, agree on the key, settle, connect to the integrated -/// server, carry the session until it ends. -fn serve( +/// One guest through the relay: attach, agree on the key from the short +/// code, settle on a direct or relayed stream, carry it. +#[allow(clippy::too_many_arguments)] +fn serve_relayed( shared: &Arc, + relay_url: &str, code: &Code, token: &str, session: u64, @@ -326,7 +499,7 @@ fn serve( control: &TcpStream, ) { let config = &shared.config; - let Ok((mut stream, _)) = connect_relay(config, port) else { + let Ok((mut stream, _)) = connect_relay(relay_url, port) else { return; }; let _ = stream.set_read_timeout(Some(Duration::from_secs(15))); @@ -351,11 +524,11 @@ fn serve( Ok(s) => s, Err(e) => { if crypto::is_wrong_code(&e) { - let count = shared.wrong.fetch_add(1, Ordering::Relaxed) + 1; + let count = shared.relay_wrong.fetch_add(1, Ordering::Relaxed) + 1; shared.emit(HostEvent::WrongCode { count }); if count >= MAX_WRONG { - // Retire the code: dropping the control connection ends - // it at the relay, and `run` registers a new one. + // Retire the short code: dropping the control connection + // ends it at the relay, and `run_relay` registers anew. let _ = control.shutdown(Shutdown::Both); } } @@ -363,7 +536,7 @@ fn serve( } }; let candidates = port.map_or_else(Vec::new, |p| direct::candidates(p, Some(relay), observed)); - let shared_routes = shared.clone(); + let routes = shared.clone(); let settled = session::settle( relayed, &key, @@ -373,7 +546,7 @@ fn serve( port, candidates, Box::new(move |tx, deadline, _stop| { - shared_routes + routes .routes .lock() .unwrap() @@ -381,21 +554,7 @@ fn serve( }), ); shared.routes.lock().unwrap().remove(&session); - let Ok(settled) = settled else { - return; - }; - let Ok(server) = TcpStream::connect_timeout(&config.lan, Duration::from_secs(5)) else { - let (r, _) = settled.secure; - let _ = r.get_ref().shutdown(Shutdown::Both); - return; - }; - let (r, w) = settled.secure; - shared.emit(HostEvent::Connected { - session, - direct: settled.direct, - }); - if let Ok(t) = crate::pump(server, r, w) { - let _ = t.join(); + if let Ok(settled) = settled { + carry(shared, session, settled.secure, settled.direct); } - shared.emit(HostEvent::Disconnected { session }); } diff --git a/crates/horizon-friends/src/invite.rs b/crates/horizon-friends/src/invite.rs new file mode 100644 index 000000000..be586a57a --- /dev/null +++ b/crates/horizon-friends/src/invite.rs @@ -0,0 +1,403 @@ +//! The invite code that needs no server: the host's reachable endpoints and +//! the session secret, in Crockford base32 groups with a checksum, e.g. +//! `2A7KQ-M3XPD-...`. A guest dials the endpoints directly; when the host +//! also uses a relay, the code carries the relay's address and the short +//! code too, so the guest can fall back to it without any setting. +//! +//! Layout (bytes, then base32): version (2), secret (10), the direct port +//! (u16), entries, then the first two bytes of SHA-256 over all of it. +//! Entries: `0x04` IPv4 on the direct port, `0x05` IPv4 and its own port +//! (a router mapping), `0x06`/`0x07` the same for IPv6, `0x10` a relay: +//! address length, address, then the short code's 40 bits. +use crate::code::{ALPHABET, Code, HALF}; +use sha2::{Digest, Sha256}; +use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr}; + +const VERSION: u8 = 2; +pub const SECRET: usize = 10; +/// Endpoints a code carries at most. +pub const MAX_ENDPOINTS: usize = 8; +const GROUP: usize = 5; + +/// The relay a host also registered with: where, and its short code. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct RelayRef { + pub address: String, + pub code: Code, +} + +#[derive(Clone, PartialEq, Eq)] +pub struct Invite { + pub secret: [u8; SECRET], + /// The host's direct socket: LAN, VPN and IPv6 addresses use this port. + pub port: u16, + pub endpoints: Vec, + pub relay: Option, +} +/// The secret stays out of logs. +impl std::fmt::Debug for Invite { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Invite") + .field("port", &self.port) + .field("endpoints", &self.endpoints) + .field("relay", &self.relay.as_ref().map(|r| &r.address)) + .finish_non_exhaustive() + } +} + +/// What a player pasted. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Parsed { + /// Eight symbols: a relay's short code (needs that relay). + Short(Code), + Long(Invite), +} + +/// Why a code didn't parse, for the player. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum CodeError { + Characters, + Typo, + Version, +} +impl std::fmt::Display for CodeError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(match self { + Self::Characters => { + "That isn't an invite code: codes are letters and digits in groups." + } + Self::Typo => "The code has a typo: copy it again from your friend's message.", + Self::Version => { + "This invite comes from another version of Horizon. Update both games." + } + }) + } +} + +fn symbol(c: char) -> Option { + let c = match c.to_ascii_uppercase() { + 'O' => '0', + 'I' | 'L' => '1', + c => c, + }; + ALPHABET + .iter() + .position(|&a| char::from(a) == c) + .map(|i| i as u8) +} + +fn encode32(bytes: &[u8]) -> String { + let mut out = String::with_capacity(bytes.len() * 8 / 5 + 1); + let (mut acc, mut bits) = (0u32, 0u32); + for &b in bytes { + acc = (acc << 8) | u32::from(b); + bits += 8; + while bits >= 5 { + bits -= 5; + out.push(char::from(ALPHABET[((acc >> bits) & 31) as usize])); + } + } + if bits > 0 { + out.push(char::from(ALPHABET[((acc << (5 - bits)) & 31) as usize])); + } + out +} + +fn decode32(symbols: &[u8]) -> Option> { + let mut out = Vec::with_capacity(symbols.len() * 5 / 8); + let (mut acc, mut bits) = (0u32, 0u32); + for &v in symbols { + acc = ((acc << 5) | u32::from(v)) & 0xFFFF; + bits += 5; + if bits >= 8 { + bits -= 8; + out.push((acc >> bits) as u8); + } + } + // Padding bits must be zero (a canonical encoding). + (acc & ((1 << bits) - 1) == 0).then_some(out) +} + +fn checksum(bytes: &[u8]) -> [u8; 2] { + let h = Sha256::digest(bytes); + [h[0], h[1]] +} + +/// The 40 bits of a short code (20 per half). +fn short_bits(code: &Code) -> Option { + let mut v = 0u64; + for c in code.nameplate.chars().chain(code.secret.chars()) { + v = (v << 5) | u64::from(symbol(c)?); + } + Some(v) +} +fn short_from_bits(v: u64) -> Code { + let s: String = (0..2 * HALF) + .rev() + .map(|i| char::from(ALPHABET[((v >> (5 * i)) & 31) as usize])) + .collect(); + let (n, sec) = s.split_at(HALF); + Code { + nameplate: n.to_owned(), + secret: sec.to_owned(), + } +} + +impl Invite { + /// A fresh secret from the OS random generator. + pub fn new( + port: u16, + endpoints: Vec, + relay: Option, + ) -> std::io::Result { + let mut secret = [0u8; SECRET]; + crate::fill_random(&mut secret)?; + Ok(Self { + secret, + port, + endpoints, + relay, + }) + } + /// The SPAKE2 password of direct sessions. + pub fn secret_text(&self) -> String { + encode32(&self.secret) + } + fn bytes(&self) -> Vec { + let mut b = vec![VERSION]; + b.extend_from_slice(&self.secret); + b.extend_from_slice(&self.port.to_be_bytes()); + for e in self.endpoints.iter().take(MAX_ENDPOINTS) { + let own = e.port() != self.port; + match e.ip() { + IpAddr::V4(ip) => { + b.push(if own { 0x05 } else { 0x04 }); + b.extend_from_slice(&ip.octets()); + } + IpAddr::V6(ip) => { + b.push(if own { 0x07 } else { 0x06 }); + b.extend_from_slice(&ip.octets()); + } + } + if own { + b.extend_from_slice(&e.port().to_be_bytes()); + } + } + if let Some(r) = &self.relay + && let Some(bits) = short_bits(&r.code) + && r.address.len() <= 255 + { + b.push(0x10); + b.push(r.address.len() as u8); + b.extend_from_slice(r.address.as_bytes()); + b.extend_from_slice(&bits.to_be_bytes()[3..]); + } + let sum = checksum(&b); + b.extend_from_slice(&sum); + b + } + /// The code to share, in groups of five. + pub fn encode(&self) -> String { + let text = encode32(&self.bytes()); + text.as_bytes() + .chunks(GROUP) + .map(|c| std::str::from_utf8(c).unwrap()) + .collect::>() + .join("-") + } + fn decode(bytes: &[u8]) -> Result { + if bytes.len() < 1 + SECRET + 2 + 2 { + return Err(CodeError::Characters); + } + let (body, sum) = bytes.split_at(bytes.len() - 2); + if checksum(body) != sum { + return Err(CodeError::Typo); + } + if body[0] != VERSION { + return Err(CodeError::Version); + } + let mut secret = [0u8; SECRET]; + secret.copy_from_slice(&body[1..1 + SECRET]); + let port = u16::from_be_bytes([body[1 + SECRET], body[2 + SECRET]]); + let mut rest = &body[3 + SECRET..]; + let mut take = |n: usize| -> Result<&[u8], CodeError> { + if rest.len() < n { + return Err(CodeError::Version); + } + let (a, b) = rest.split_at(n); + rest = b; + Ok(a) + }; + let mut endpoints = Vec::new(); + let mut relay = None; + while let Ok(tag) = take(1) { + let tag = tag[0]; + match tag { + 0x04..=0x07 => { + let ip = if tag < 0x06 { + let o: [u8; 4] = take(4)?.try_into().unwrap(); + IpAddr::V4(Ipv4Addr::from(o)) + } else { + let o: [u8; 16] = take(16)?.try_into().unwrap(); + IpAddr::V6(Ipv6Addr::from(o)) + }; + let p = if tag & 1 == 1 { + let p = take(2)?; + u16::from_be_bytes([p[0], p[1]]) + } else { + port + }; + endpoints.push(SocketAddr::new(ip, p)); + } + 0x10 => { + let len = usize::from(take(1)?[0]); + let address = + String::from_utf8(take(len)?.to_vec()).map_err(|_| CodeError::Version)?; + let b = take(5)?; + let bits = b.iter().fold(0u64, |v, &x| (v << 8) | u64::from(x)); + relay = Some(RelayRef { + address, + code: short_from_bits(bits), + }); + } + _ => return Err(CodeError::Version), + } + } + Ok(Self { + secret, + port, + endpoints, + relay, + }) + } +} + +/// Read what a player pasted: a short relay code or a full invite. +pub fn parse_detailed(text: &str) -> Result { + let mut symbols = Vec::with_capacity(text.len()); + for c in text.chars() { + if c.is_whitespace() || c == '-' { + continue; + } + symbols.push(symbol(c).ok_or(CodeError::Characters)?); + } + if symbols.len() == 2 * HALF { + let s: String = symbols + .iter() + .map(|&v| char::from(ALPHABET[v as usize])) + .collect(); + return Code::parse(&s) + .map(Parsed::Short) + .ok_or(CodeError::Characters); + } + let bytes = decode32(&symbols).ok_or(CodeError::Typo)?; + Invite::decode(&bytes).map(Parsed::Long) +} +pub fn parse(text: &str) -> Option { + parse_detailed(text).ok() +} + +#[cfg(test)] +mod tests { + use super::*; + + fn sample() -> Invite { + Invite { + secret: *b"0123456789", + port: 25580, + endpoints: vec![ + "203.0.113.5:41234".parse().unwrap(), + "192.168.1.20:25580".parse().unwrap(), + "100.72.51.8:25580".parse().unwrap(), + "[2001:db8::20]:25580".parse().unwrap(), + ], + relay: None, + } + } + + #[test] + fn base32_round_trips() { + for n in 0..40 { + let bytes: Vec = (0..n).map(|i| (i * 37 + 11) as u8).collect(); + let text = encode32(&bytes); + let symbols: Vec = text.chars().map(|c| symbol(c).unwrap()).collect(); + assert_eq!(decode32(&symbols).unwrap(), bytes); + } + } + + #[test] + fn codes_round_trip_and_stay_pasteable() { + let invite = sample(); + let code = invite.encode(); + assert!( + code.split('-') + .all(|g| g.len() <= GROUP && g.chars().all(|c| ALPHABET.contains(&(c as u8)))) + ); + // A home with a router mapping, a LAN, a tailnet and IPv6: 79 symbols + // in 16 groups; without IPv6, 52. + assert_eq!(code.replace('-', "").len(), 79, "{code}"); + let mut v4 = invite.clone(); + v4.endpoints.pop(); + assert_eq!(v4.encode().replace('-', "").len(), 52); + assert_eq!(parse(&code), Some(Parsed::Long(invite.clone()))); + // Case, spaces and look-alike letters don't matter. + let sloppy = code.to_lowercase().replace('-', " ").replace('0', "o"); + assert_eq!(parse(&sloppy), Some(Parsed::Long(invite))); + } + + #[test] + fn a_relay_rides_along() { + let mut invite = sample(); + invite.relay = Some(RelayRef { + address: "relay.example.org:7000".into(), + code: Code::parse("K7QM-3XPD").unwrap(), + }); + let Some(Parsed::Long(back)) = parse(&invite.encode()) else { + panic!() + }; + assert_eq!(back.relay, invite.relay); + assert_eq!(back.endpoints, invite.endpoints); + } + + #[test] + fn typos_are_caught() { + let code = sample().encode(); + let mut caught = 0; + let symbols: Vec = code.chars().collect(); + for i in (0..symbols.len()).filter(|&i| symbols[i] != '-') { + let mut changed = symbols.clone(); + changed[i] = if changed[i] == 'Z' { 'Y' } else { 'Z' }; + let text: String = changed.into_iter().collect(); + if parse_detailed(&text).is_err() { + caught += 1; + } + } + // Every single-symbol change is refused (the checksum misses one in 65536). + assert_eq!(caught, symbols.iter().filter(|&&c| c != '-').count()); + // A dropped group too. + let shorter: String = code.split('-').skip(1).collect::>().join("-"); + assert!(parse(&shorter).is_none()); + } + + #[test] + fn short_codes_and_garbage() { + assert_eq!( + parse("k7qm-3xpd"), + Some(Parsed::Short(Code::parse("K7QM-3XPD").unwrap())) + ); + assert_eq!(parse_detailed("hello world!"), Err(CodeError::Characters)); + assert!(parse("").is_none()); + // Another version is told apart from a typo. + let mut b = sample().bytes(); + b[0] = 3; + let n = b.len() - 2; + let sum = checksum(&b[..n]); + b[n..].copy_from_slice(&sum); + assert_eq!(parse_detailed(&encode32(&b)), Err(CodeError::Version)); + } + + #[test] + fn debug_hides_the_secret() { + assert!(!format!("{:?}", sample()).contains("0123456789")); + } +} diff --git a/crates/horizon-friends/src/lib.rs b/crates/horizon-friends/src/lib.rs index 9c86b10fa..ffc61721d 100644 --- a/crates/horizon-friends/src/lib.rs +++ b/crates/horizon-friends/src/lib.rs @@ -1,6 +1,9 @@ //! Play with friends: a host shares the world it opened to LAN behind an -//! invite code; guests join with the code, directly when the network allows -//! and through the relay otherwise. Both ends carry the game's TCP stream +//! invite code that holds its addresses and a secret; guests dial it +//! directly (the host opens its router port with PCP / NAT-PMP / UPnP and +//! learns its public address with STUN). A relay anyone can run +//! (`horizon-relay`) adds short codes and a fallback for networks that +//! can't be reached. Both ends carry the game's TCP stream //! unchanged between loopback ports (the integrated server on the host, a //! local port the guest's client connects to), end-to-end encrypted with a //! key only the holders of the code can derive. The design, the protocol and @@ -10,7 +13,11 @@ pub mod crypto; pub mod direct; pub mod guest; pub mod host; +pub mod invite; +pub mod portmap; +pub mod reach; mod session; +pub mod stun; pub mod wire; pub use code::Code; @@ -48,16 +55,14 @@ impl PathMode { } } -/// The relay's address: `HORIZON_RELAY_URL` at run time, else the one -/// compiled in from the same variable. None until a relay is deployed. +/// A relay from `HORIZON_RELAY_URL` (tests, or players who set it in the +/// environment); the game adds its own setting. None by default: friends +/// join from the code alone. pub fn relay_url() -> Option { - let runtime = std::env::var("HORIZON_RELAY_URL").ok(); - let compiled = option_env!("HORIZON_RELAY_URL").map(str::to_owned); - runtime - .into_iter() - .chain(compiled) + std::env::var("HORIZON_RELAY_URL") + .ok() .map(|s| s.trim().to_owned()) - .find(|s| !s.is_empty()) + .filter(|s| !s.is_empty()) } /// `host:port`, optionally written `tcp://host:port`. diff --git a/crates/horizon-friends/src/portmap.rs b/crates/horizon-friends/src/portmap.rs new file mode 100644 index 000000000..6ad9a2b94 --- /dev/null +++ b/crates/horizon-friends/src/portmap.rs @@ -0,0 +1,980 @@ +//! Opening the host's direct port on the home router, for a limited time: +//! PCP (RFC 6887), then NAT-PMP (RFC 6886) on the gateway's port 5351, then +//! UPnP IGD (SSDP discovery, then SOAP `AddPortMapping`). The mapping is +//! renewed while sharing and deleted when it stops; a crashed game's mapping +//! expires with its lease. +use std::{ + io::{self, Read, Write}, + net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpStream, ToSocketAddrs, UdpSocket}, + time::{Duration, Instant}, +}; + +/// How long a mapping is asked for; it is renewed at half-time. +pub const LEASE: Duration = Duration::from_secs(3600); +const PMP_PORT: u16 = 5351; +const DESCRIPTION: &str = "Horizon (play with friends)"; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Method { + Pcp, + NatPmp, + Upnp, +} +impl Method { + pub fn name(self) -> &'static str { + match self { + Self::Pcp => "PCP", + Self::NatPmp => "NAT-PMP", + Self::Upnp => "UPnP", + } + } +} + +#[derive(Clone, Debug)] +enum Handle { + Pmp { + gateway: SocketAddr, + client: Ipv4Addr, + nonce: [u8; 12], + }, + NatPmp { + gateway: SocketAddr, + }, + Upnp { + igd: Igd, + client: Ipv4Addr, + permanent: bool, + }, +} + +/// A port opened on the router. +#[derive(Clone, Debug)] +pub struct Mapping { + pub method: Method, + pub internal: u16, + /// The router's public side: its WAN address (unspecified when the + /// router didn't say) and the external port. + pub external: SocketAddr, + pub lifetime: Duration, + pub renewed: Instant, + handle: Handle, +} + +/// Where to ask: gateways speaking PCP/NAT-PMP, UPnP description URLs. +#[derive(Clone, Debug, Default)] +pub struct Targets { + pub pmp: Vec, + pub upnp: Vec, +} +impl Targets { + /// The default gateway's port 5351, and the IGDs answering SSDP. + pub fn discover(timeout: Duration) -> Self { + let mut pmp: Vec = default_gateway() + .into_iter() + .map(|g| SocketAddr::new(IpAddr::V4(g), PMP_PORT)) + .collect(); + let upnp = ssdp_discover(timeout); + // An IGD's own address is a gateway too. + for l in &upnp { + if let Some((host, _, _)) = split_url(l) + && let Ok(ip) = host.parse::() + { + let a = SocketAddr::new(IpAddr::V4(ip), PMP_PORT); + if !pmp.contains(&a) { + pmp.push(a); + } + } + } + Self { pmp, upnp } + } +} + +/// Open `internal` on the router for `client` (this machine's LAN address), +/// trying each method in turn. The error lists why each failed. +pub fn map( + targets: &Targets, + client: Ipv4Addr, + internal: u16, + lease: Duration, +) -> Result { + let mut why = Vec::new(); + for &gw in &targets.pmp { + let mut nonce = [0u8; 12]; + let _ = crate::fill_random(&mut nonce); + match pcp_map(gw, client, internal, internal, lease, &nonce) { + Ok((external, life)) => { + return Ok(Mapping { + method: Method::Pcp, + internal, + external, + lifetime: life, + renewed: Instant::now(), + handle: Handle::Pmp { + gateway: gw, + client, + nonce, + }, + }); + } + Err(e) => why.push(format!("PCP: {e}")), + } + match natpmp_map(gw, internal, internal, lease) { + Ok((port, life)) => { + let ip = natpmp_external(gw).map_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED), IpAddr::V4); + return Ok(Mapping { + method: Method::NatPmp, + internal, + external: SocketAddr::new(ip, port), + lifetime: life, + renewed: Instant::now(), + handle: Handle::NatPmp { gateway: gw }, + }); + } + Err(e) => why.push(format!("NAT-PMP: {e}")), + } + } + for location in &targets.upnp { + match Igd::from_location(location).and_then(|igd| upnp_map(igd, client, internal, lease)) { + Ok(m) => return Ok(m), + Err(e) => why.push(format!("UPnP: {e}")), + } + } + if why.is_empty() { + why.push("no router answered".into()); + } + Err(why.join("; ")) +} + +fn upnp_map(igd: Igd, client: Ipv4Addr, internal: u16, lease: Duration) -> io::Result { + let mut permanent = false; + let mut last = io::Error::other("no port"); + // The same port outside first (easy to forward by hand later), then others. + let mut ports = vec![internal]; + let mut r = [0u8; 2]; + for _ in 0..3 { + let _ = crate::fill_random(&mut r); + ports.push(20000 + u16::from_le_bytes(r) % 40000); + } + for port in ports { + let secs = if permanent { 0 } else { lease.as_secs() as u32 }; + match igd.add(port, internal, client, secs) { + Ok(()) => { + let ip = igd + .external_ip() + .unwrap_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED)); + return Ok(Mapping { + method: Method::Upnp, + internal, + external: SocketAddr::new(ip, port), + lifetime: if permanent { LEASE } else { lease }, + renewed: Instant::now(), + handle: Handle::Upnp { + igd, + client, + permanent, + }, + }); + } + // OnlyPermanentLeasesSupported: ask without a lease (deleted on stop). + Err(UpnpError::Code(725)) if !permanent => { + permanent = true; + match igd.add(port, internal, client, 0) { + Ok(()) => { + let ip = igd + .external_ip() + .unwrap_or(IpAddr::V4(Ipv4Addr::UNSPECIFIED)); + return Ok(Mapping { + method: Method::Upnp, + internal, + external: SocketAddr::new(ip, port), + lifetime: LEASE, + renewed: Instant::now(), + handle: Handle::Upnp { + igd, + client, + permanent, + }, + }); + } + Err(e) => last = e.into(), + } + } + // ConflictInMappingEntry and friends: another port. + Err(UpnpError::Code(c)) => last = io::Error::other(format!("error {c}")), + Err(UpnpError::Io(e)) => return Err(e), + } + } + Err(last) +} + +impl Mapping { + /// A mapping as a router would have granted it (tests elsewhere). + #[cfg(test)] + pub(crate) fn granted(method: Method, external: SocketAddr) -> Self { + Self { + method, + internal: 25580, + external, + lifetime: LEASE, + renewed: Instant::now(), + handle: Handle::NatPmp { + gateway: SocketAddr::from(([127, 0, 0, 1], 9)), + }, + } + } + /// Whether the lease is past half-time. + pub fn due(&self) -> bool { + self.renewed.elapsed() >= self.lifetime / 2 + } + pub fn renew(&mut self) -> io::Result<()> { + let internal = self.internal; + let lease = LEASE; + match &self.handle { + Handle::Pmp { + gateway, + client, + nonce, + } => { + let (external, life) = pcp_map( + *gateway, + *client, + internal, + self.external.port(), + lease, + nonce, + )?; + self.external = external; + self.lifetime = life; + } + Handle::NatPmp { gateway } => { + let (port, life) = natpmp_map(*gateway, internal, self.external.port(), lease)?; + self.external.set_port(port); + self.lifetime = life; + } + Handle::Upnp { + igd, + client, + permanent, + } => { + let secs = if *permanent { + 0 + } else { + lease.as_secs() as u32 + }; + igd.add(self.external.port(), internal, *client, secs)?; + } + } + self.renewed = Instant::now(); + Ok(()) + } + /// Delete the mapping (best effort). + pub fn remove(&self) { + match &self.handle { + Handle::Pmp { + gateway, + client, + nonce, + } => { + let _ = pcp_map(*gateway, *client, self.internal, 0, Duration::ZERO, nonce); + } + Handle::NatPmp { gateway } => { + let _ = natpmp_map(*gateway, self.internal, 0, Duration::ZERO); + } + Handle::Upnp { igd, .. } => { + let _ = igd.delete(self.external.port()); + } + } + } +} + +// ----- PCP and NAT-PMP -------------------------------------------------------------------------- + +/// Send `req` and wait for a datagram from the gateway, with RFC 6886's +/// retransmissions (250 ms, doubling), three tries. +fn exchange(gateway: SocketAddr, req: &[u8]) -> io::Result> { + let socket = UdpSocket::bind("0.0.0.0:0")?; + socket.connect(gateway)?; + let mut wait = Duration::from_millis(250); + let mut buf = [0u8; 1100]; + for _ in 0..3 { + socket.send(req)?; + socket.set_read_timeout(Some(wait))?; + match socket.recv(&mut buf) { + Ok(n) => return Ok(buf[..n].to_vec()), + Err(e) if e.kind() == io::ErrorKind::ConnectionRefused => return Err(e), + Err(_) => wait *= 2, + } + } + Err(io::Error::new(io::ErrorKind::TimedOut, "no answer")) +} + +fn mapped_v6(ip: Ipv4Addr) -> [u8; 16] { + ip.to_ipv6_mapped().octets() +} + +/// PCP MAP for TCP: the external address and the granted lifetime. A +/// zero lifetime deletes. +pub fn pcp_map( + gateway: SocketAddr, + client: Ipv4Addr, + internal: u16, + external: u16, + lease: Duration, + nonce: &[u8; 12], +) -> io::Result<(SocketAddr, Duration)> { + let mut req = vec![0u8; 60]; + req[0] = 2; + req[1] = 1; + req[4..8].copy_from_slice(&(lease.as_secs() as u32).to_be_bytes()); + req[8..24].copy_from_slice(&mapped_v6(client)); + req[24..36].copy_from_slice(nonce); + req[36] = 6; + req[40..42].copy_from_slice(&internal.to_be_bytes()); + req[42..44].copy_from_slice(&external.to_be_bytes()); + req[44..60].copy_from_slice(&mapped_v6(Ipv4Addr::UNSPECIFIED)); + let r = exchange(gateway, &req)?; + if r.len() < 2 || r[0] != 2 { + return Err(io::Error::other("not a PCP router")); + } + if r.len() < 60 || r[1] != 0x81 || &r[24..36] != nonce { + return Err(io::Error::other("bad answer")); + } + if r[3] != 0 { + return Err(io::Error::other(format!("result {}", r[3]))); + } + let life = Duration::from_secs(u64::from(u32::from_be_bytes(r[4..8].try_into().unwrap()))); + let port = u16::from_be_bytes([r[42], r[43]]); + let o: [u8; 16] = r[44..60].try_into().unwrap(); + let v6 = Ipv6Addr::from(o); + let ip = v6.to_ipv4_mapped().map_or(IpAddr::V6(v6), IpAddr::V4); + Ok((SocketAddr::new(ip, port), life)) +} + +/// NAT-PMP's external address request. +pub fn natpmp_external(gateway: SocketAddr) -> io::Result { + let r = exchange(gateway, &[0, 0])?; + if r.len() < 12 || r[0] != 0 || r[1] != 128 { + return Err(io::Error::other("bad answer")); + } + if r[2..4] != [0, 0] { + return Err(io::Error::other(format!( + "result {}", + u16::from_be_bytes([r[2], r[3]]) + ))); + } + Ok(Ipv4Addr::new(r[8], r[9], r[10], r[11])) +} + +/// NAT-PMP TCP mapping: the external port and lifetime. Zero deletes. +pub fn natpmp_map( + gateway: SocketAddr, + internal: u16, + external: u16, + lease: Duration, +) -> io::Result<(u16, Duration)> { + let mut req = [0u8; 12]; + req[1] = 2; + req[4..6].copy_from_slice(&internal.to_be_bytes()); + req[6..8].copy_from_slice(&external.to_be_bytes()); + req[8..12].copy_from_slice(&(lease.as_secs() as u32).to_be_bytes()); + let r = exchange(gateway, &req)?; + if r.len() < 16 || r[0] != 0 || r[1] != 130 { + return Err(io::Error::other("not a NAT-PMP router")); + } + if r[2..4] != [0, 0] { + return Err(io::Error::other(format!( + "result {}", + u16::from_be_bytes([r[2], r[3]]) + ))); + } + Ok(( + u16::from_be_bytes([r[10], r[11]]), + Duration::from_secs(u64::from(u32::from_be_bytes(r[12..16].try_into().unwrap()))), + )) +} + +// ----- UPnP IGD --------------------------------------------------------------------------------- + +/// `http://host:port/path` → host, port, path. +fn split_url(url: &str) -> Option<(String, u16, String)> { + let rest = url.strip_prefix("http://")?; + let (hostport, path) = match rest.find('/') { + Some(i) => (&rest[..i], &rest[i..]), + None => (rest, "/"), + }; + let (host, port) = match hostport.rsplit_once(':') { + Some((h, p)) if !h.contains(']') || h.ends_with(']') => (h, p.parse().ok()?), + _ => (hostport, 80), + }; + Some(( + host.trim_matches(|c| c == '[' || c == ']').to_owned(), + port, + path.to_owned(), + )) +} + +/// A tiny HTTP/1.1 client (Connection: close; Content-Length, chunked or +/// to the end). +fn http( + method: &str, + url: &str, + headers: &[(&str, &str)], + body: &str, +) -> io::Result<(u16, String)> { + let (host, port, path) = split_url(url).ok_or_else(|| io::Error::other("bad URL"))?; + let addr = (host.as_str(), port) + .to_socket_addrs()? + .next() + .ok_or_else(|| io::Error::other("no address"))?; + let mut s = TcpStream::connect_timeout(&addr, Duration::from_secs(3))?; + s.set_read_timeout(Some(Duration::from_secs(5)))?; + let mut req = format!( + "{method} {path} HTTP/1.1\r\nHost: {host}:{port}\r\nConnection: close\r\nContent-Length: {}\r\n", + body.len() + ); + for (k, v) in headers { + req.push_str(&format!("{k}: {v}\r\n")); + } + req.push_str("\r\n"); + req.push_str(body); + s.write_all(req.as_bytes())?; + let mut raw = Vec::new(); + s.take(1 << 20).read_to_end(&mut raw)?; + let text = String::from_utf8_lossy(&raw).into_owned(); + let (head, rest) = text + .split_once("\r\n\r\n") + .ok_or_else(|| io::Error::other("bad response"))?; + let status = head + .split_whitespace() + .nth(1) + .and_then(|c| c.parse().ok()) + .ok_or_else(|| io::Error::other("bad status"))?; + let chunked = head.lines().any(|l| { + let l = l.to_ascii_lowercase(); + l.starts_with("transfer-encoding:") && l.contains("chunked") + }); + let body = if chunked { + dechunk(rest) + } else { + rest.to_owned() + }; + Ok((status, body)) +} +fn dechunk(mut s: &str) -> String { + let mut out = String::new(); + while let Some((size, rest)) = s.split_once("\r\n") { + let Ok(n) = usize::from_str_radix(size.split(';').next().unwrap_or("").trim(), 16) else { + break; + }; + if n == 0 || rest.len() < n { + break; + } + out.push_str(&rest[..n]); + s = rest[n..].trim_start_matches("\r\n"); + } + out +} + +/// The text of the first `` (any namespace prefix) in `xml`. +fn tag<'a>(xml: &'a str, name: &str) -> Option<&'a str> { + let mut from = 0; + while let Some(i) = xml[from..].find('<') { + let start = from + i + 1; + let end = start + xml[start..].find('>')?; + let open = &xml[start..end]; + let local = open.split_whitespace().next().unwrap_or(""); + let local = local.rsplit(':').next().unwrap_or(local); + if local == name && !open.starts_with('/') { + let body = &xml[end + 1..]; + let close = body.find(" Vec { + let Ok(s) = UdpSocket::bind("0.0.0.0:0") else { + return Vec::new(); + }; + let _ = s.set_read_timeout(Some(Duration::from_millis(200))); + for st in [ + "urn:schemas-upnp-org:device:InternetGatewayDevice:1", + "urn:schemas-upnp-org:device:InternetGatewayDevice:2", + "urn:schemas-upnp-org:service:WANIPConnection:1", + ] { + let m = format!( + "M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\nST: {st}\r\nMAN: \"ssdp:discover\"\r\nMX: 2\r\n\r\n" + ); + let _ = s.send_to(m.as_bytes(), "239.255.255.250:1900"); + } + let deadline = Instant::now() + timeout; + let mut found = Vec::new(); + let mut buf = [0u8; 2048]; + while Instant::now() < deadline { + if let Ok((n, _)) = s.recv_from(&mut buf) + && let Some(l) = ssdp_location(&String::from_utf8_lossy(&buf[..n])) + && !found.contains(&l) + { + found.push(l); + } + } + found +} +pub fn ssdp_location(response: &str) -> Option { + response.lines().find_map(|l| { + let (k, v) = l.split_once(':')?; + k.trim() + .eq_ignore_ascii_case("location") + .then(|| v.trim().to_owned()) + }) +} + +enum UpnpError { + Code(u32), + Io(io::Error), +} +impl From for UpnpError { + fn from(e: io::Error) -> Self { + Self::Io(e) + } +} +impl From for io::Error { + fn from(e: UpnpError) -> Self { + match e { + UpnpError::Code(c) => io::Error::other(format!("error {c}")), + UpnpError::Io(e) => e, + } + } +} + +/// An internet gateway's connection service. +#[derive(Clone, Debug)] +pub struct Igd { + control: String, + service: String, +} +impl Igd { + /// Read the device description for a WANIPConnection (or WANPPPConnection) service. + pub fn from_location(location: &str) -> io::Result { + let (status, xml) = http("GET", location, &[], "")?; + if status != 200 { + return Err(io::Error::other(format!("description: HTTP {status}"))); + } + let (host, port, _) = split_url(location).ok_or_else(|| io::Error::other("bad URL"))?; + let base = tag(&xml, "URLBase") + .map(|b| b.trim_end_matches('/').to_owned()) + .unwrap_or_else(|| format!("http://{host}:{port}")); + for block in xml.split("").skip(1) { + let Some(service) = tag(block, "serviceType") else { + continue; + }; + if !(service.contains(":WANIPConnection:") || service.contains(":WANPPPConnection:")) { + continue; + } + let Some(control) = tag(block, "controlURL") else { + continue; + }; + let control = if control.starts_with("http://") { + control.to_owned() + } else { + format!("{base}/{}", control.trim_start_matches('/')) + }; + return Ok(Self { + control, + service: service.to_owned(), + }); + } + Err(io::Error::other("no WAN connection service")) + } + fn soap(&self, action: &str, args: &[(&str, String)]) -> Result { + let mut body = format!( + "\n", + self.service + ); + for (k, v) in args { + body.push_str(&format!("<{k}>{v}")); + } + body.push_str(&format!("")); + let soap_action = format!("\"{}#{action}\"", self.service); + let (status, reply) = http( + "POST", + &self.control, + &[ + ("Content-Type", "text/xml; charset=\"utf-8\""), + ("SOAPAction", &soap_action), + ], + &body, + )?; + if status == 200 { + return Ok(reply); + } + match tag(&reply, "errorCode").and_then(|c| c.parse().ok()) { + Some(code) => Err(UpnpError::Code(code)), + None => Err(UpnpError::Io(io::Error::other(format!("HTTP {status}")))), + } + } + fn add( + &self, + external: u16, + internal: u16, + client: Ipv4Addr, + lease: u32, + ) -> Result<(), UpnpError> { + self.soap( + "AddPortMapping", + &[ + ("NewRemoteHost", String::new()), + ("NewExternalPort", external.to_string()), + ("NewProtocol", "TCP".into()), + ("NewInternalPort", internal.to_string()), + ("NewInternalClient", client.to_string()), + ("NewEnabled", "1".into()), + ("NewPortMappingDescription", DESCRIPTION.into()), + ("NewLeaseDuration", lease.to_string()), + ], + ) + .map(|_| ()) + } + fn delete(&self, external: u16) -> Result<(), UpnpError> { + self.soap( + "DeletePortMapping", + &[ + ("NewRemoteHost", String::new()), + ("NewExternalPort", external.to_string()), + ("NewProtocol", "TCP".into()), + ], + ) + .map(|_| ()) + } + fn external_ip(&self) -> io::Result { + let r = self.soap("GetExternalIPAddress", &[])?; + tag(&r, "NewExternalIPAddress") + .and_then(|t| t.parse().ok()) + .ok_or_else(|| io::Error::other("no external address")) + } +} + +// ----- The default gateway ---------------------------------------------------------------------- + +/// The IPv4 default gateway from the OS routing table. +pub fn default_gateway() -> Option { + #[cfg(target_os = "linux")] + { + linux_gateway(&std::fs::read_to_string("/proc/net/route").ok()?) + } + #[cfg(any(target_os = "macos", target_os = "freebsd", target_os = "openbsd"))] + { + let out = std::process::Command::new("route") + .args(["-n", "get", "default"]) + .output() + .ok()?; + bsd_gateway(&String::from_utf8_lossy(&out.stdout)) + } + #[cfg(windows)] + { + let out = std::process::Command::new("route") + .args(["print", "-4", "0.0.0.0"]) + .output() + .ok()?; + windows_gateway(&String::from_utf8_lossy(&out.stdout)) + } + #[cfg(not(any( + target_os = "linux", + target_os = "macos", + target_os = "freebsd", + target_os = "openbsd", + windows + )))] + { + None + } +} +pub fn linux_gateway(table: &str) -> Option { + table.lines().skip(1).find_map(|l| { + let f: Vec<&str> = l.split_whitespace().collect(); + if f.len() > 2 && f[1] == "00000000" { + let g = u32::from_str_radix(f[2], 16).ok()?; + (g != 0).then(|| Ipv4Addr::from(g.swap_bytes())) + } else { + None + } + }) +} +pub fn bsd_gateway(text: &str) -> Option { + text.lines().find_map(|l| { + l.trim() + .strip_prefix("gateway:") + .and_then(|g| g.trim().parse().ok()) + }) +} +pub fn windows_gateway(text: &str) -> Option { + text.lines().find_map(|l| { + let f: Vec<&str> = l.split_whitespace().collect(); + (f.len() >= 3 && f[0] == "0.0.0.0" && f[1] == "0.0.0.0") + .then(|| f[2].parse().ok()) + .flatten() + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::{ + collections::HashMap, + net::TcpListener, + sync::{Arc, Mutex}, + }; + + type Table = Arc>>; + + /// A router on loopback speaking PCP (unless `pmp_only`) and NAT-PMP; + /// external port = internal + 1000, WAN address 198.51.100.7. + fn mock_pmp(pmp_only: bool) -> (SocketAddr, Table) { + let s = UdpSocket::bind("127.0.0.1:0").unwrap(); + let addr = s.local_addr().unwrap(); + let table: Table = Arc::default(); + let t = table.clone(); + std::thread::spawn(move || { + let mut buf = [0u8; 1100]; + while let Ok((n, from)) = s.recv_from(&mut buf) { + let r = &buf[..n]; + let reply = match (r[0], r.get(1)) { + (2, _) if pmp_only => vec![0, 0x81, 0, 1], + (2, Some(1)) => { + let internal = u16::from_be_bytes([r[40], r[41]]); + let life = u32::from_be_bytes(r[4..8].try_into().unwrap()); + let mut out = r.to_vec(); + out[1] = 0x81; + out[2] = 0; + out[3] = 0; + let ext = if life == 0 { + t.lock().unwrap().remove(&internal); + 0 + } else { + t.lock().unwrap().insert(internal, (internal + 1000, life)); + internal + 1000 + }; + out[42..44].copy_from_slice(&ext.to_be_bytes()); + out[44..60].copy_from_slice( + &Ipv4Addr::new(198, 51, 100, 7).to_ipv6_mapped().octets(), + ); + out + } + (0, Some(0)) => vec![0, 128, 0, 0, 0, 0, 0, 1, 198, 51, 100, 7], + (0, Some(2)) => { + let internal = u16::from_be_bytes([r[4], r[5]]); + let life = u32::from_be_bytes(r[8..12].try_into().unwrap()); + let ext = if life == 0 { + t.lock().unwrap().remove(&internal); + 0 + } else { + t.lock().unwrap().insert(internal, (internal + 1000, life)); + internal + 1000 + }; + let mut out = vec![0, 130, 0, 0, 0, 0, 0, 1]; + out.extend_from_slice(&internal.to_be_bytes()); + out.extend_from_slice(&ext.to_be_bytes()); + out.extend_from_slice(&life.to_be_bytes()); + out + } + _ => continue, + }; + let _ = s.send_to(&reply, from); + } + }); + (addr, table) + } + + #[test] + fn pcp_maps_renews_and_deletes() { + let (gw, table) = mock_pmp(false); + let targets = Targets { + pmp: vec![gw], + upnp: vec![], + }; + let mut m = map(&targets, Ipv4Addr::new(192, 168, 1, 20), 25580, LEASE).unwrap(); + assert_eq!(m.method, Method::Pcp); + assert_eq!(m.external, "198.51.100.7:26580".parse().unwrap()); + assert_eq!(table.lock().unwrap()[&25580], (26580, 3600)); + assert!(!m.due()); + m.renew().unwrap(); + m.remove(); + assert!(table.lock().unwrap().is_empty()); + } + + #[test] + fn nat_pmp_when_pcp_is_unsupported() { + let (gw, table) = mock_pmp(true); + let targets = Targets { + pmp: vec![gw], + upnp: vec![], + }; + let m = map(&targets, Ipv4Addr::new(192, 168, 1, 20), 25580, LEASE).unwrap(); + assert_eq!(m.method, Method::NatPmp); + assert_eq!(m.external, "198.51.100.7:26580".parse().unwrap()); + m.remove(); + assert!(table.lock().unwrap().is_empty()); + } + + /// An IGD on loopback: description, then SOAP. `permanent_only` answers + /// 725 to leases; `taken` ports answer 718. + fn mock_igd( + permanent_only: bool, + taken: u16, + ) -> (String, Arc>>) { + let l = TcpListener::bind("127.0.0.1:0").unwrap(); + let port = l.local_addr().unwrap().port(); + let table: Arc>> = Arc::default(); + let t = table.clone(); + std::thread::spawn(move || { + for s in l.incoming() { + let Ok(mut s) = s else { continue }; + let mut req = Vec::new(); + let mut buf = [0u8; 4096]; + // Read the headers, then Content-Length bytes. + loop { + let n = s.read(&mut buf).unwrap_or(0); + if n == 0 { + break; + } + req.extend_from_slice(&buf[..n]); + let text = String::from_utf8_lossy(&req); + if let Some((head, body)) = text.split_once("\r\n\r\n") { + let len: usize = head + .lines() + .find_map(|l| l.strip_prefix("Content-Length: ")) + .and_then(|v| v.trim().parse().ok()) + .unwrap_or(0); + if body.len() >= len { + break; + } + } + } + let text = String::from_utf8_lossy(&req).into_owned(); + let (status, body) = if text.starts_with("GET /desc.xml") { + (200, "urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1/wrongurn:schemas-upnp-org:service:WANIPConnection:1/ctl".to_owned()) + } else if text.contains("#GetExternalIPAddress") { + (200, "198.51.100.8".to_owned()) + } else if text.contains("#AddPortMapping") { + let ext: u16 = tag(&text, "NewExternalPort").unwrap().parse().unwrap(); + let int: u16 = tag(&text, "NewInternalPort").unwrap().parse().unwrap(); + let client = tag(&text, "NewInternalClient").unwrap().to_owned(); + let lease: u32 = tag(&text, "NewLeaseDuration").unwrap().parse().unwrap(); + if permanent_only && lease != 0 { + (500, "725".to_owned()) + } else if ext == taken { + (500, "718".to_owned()) + } else { + t.lock().unwrap().insert(ext, (int, client, lease)); + (200, "".to_owned()) + } + } else if text.contains("#DeletePortMapping") { + let ext: u16 = tag(&text, "NewExternalPort").unwrap().parse().unwrap(); + t.lock().unwrap().remove(&ext); + (200, "".to_owned()) + } else { + (404, String::new()) + }; + let _ = write!( + s, + "HTTP/1.1 {status} X\r\nContent-Type: text/xml\r\nTransfer-Encoding: chunked\r\n\r\n{:x}\r\n{body}\r\n0\r\n\r\n", + body.len() + ); + } + }); + (format!("http://127.0.0.1:{port}/desc.xml"), table) + } + + #[test] + fn upnp_maps_and_deletes() { + let (location, table) = mock_igd(false, 0); + let targets = Targets { + pmp: vec![], + upnp: vec![location], + }; + let client = Ipv4Addr::new(192, 168, 1, 20); + let mut m = map(&targets, client, 25580, LEASE).unwrap(); + assert_eq!(m.method, Method::Upnp); + assert_eq!(m.external, "198.51.100.8:25580".parse().unwrap()); + assert_eq!( + table.lock().unwrap()[&25580], + (25580, "192.168.1.20".into(), 3600) + ); + m.renew().unwrap(); + m.remove(); + assert!(table.lock().unwrap().is_empty()); + } + + #[test] + fn upnp_permanent_leases_and_taken_ports() { + let (location, table) = mock_igd(true, 25580); + let targets = Targets { + pmp: vec![], + upnp: vec![location], + }; + let m = map(&targets, Ipv4Addr::new(10, 0, 0, 2), 25580, LEASE).unwrap(); + // 725 → no lease; 718 on 25580 → another port. + assert_ne!(m.external.port(), 25580); + let entry = table.lock().unwrap()[&m.external.port()].clone(); + assert_eq!(entry, (25580, "10.0.0.2".into(), 0)); + m.remove(); + assert!(table.lock().unwrap().is_empty()); + } + + #[test] + fn nothing_answering_says_why() { + let quiet = UdpSocket::bind("127.0.0.1:0").unwrap(); + let targets = Targets { + pmp: vec![quiet.local_addr().unwrap()], + upnp: vec![], + }; + let e = map(&targets, Ipv4Addr::new(10, 0, 0, 2), 1, LEASE).unwrap_err(); + assert!(e.contains("PCP") && e.contains("NAT-PMP"), "{e}"); + assert_eq!( + map(&Targets::default(), Ipv4Addr::LOCALHOST, 1, LEASE).unwrap_err(), + "no router answered" + ); + } + + #[test] + fn parsers() { + assert_eq!( + ssdp_location( + "HTTP/1.1 200 OK\r\nCACHE-CONTROL: max-age=120\r\nLOCATION: http://192.168.1.1:5000/rootDesc.xml\r\nST: x\r\n\r\n" + ), + Some("http://192.168.1.1:5000/rootDesc.xml".into()) + ); + assert_eq!( + split_url("http://192.168.1.1:5000/a/b"), + Some(("192.168.1.1".into(), 5000, "/a/b".into())) + ); + assert_eq!( + split_url("http://router/"), + Some(("router".into(), 80, "/".into())) + ); + assert_eq!( + linux_gateway( + "Iface\tDestination\tGateway \tFlags\neth0\t0001A8C0\t00000000\t0001\neth0\t00000000\t0101A8C0\t0003\n" + ), + Some(Ipv4Addr::new(192, 168, 1, 1)) + ); + assert_eq!( + bsd_gateway(" route to: default\ndestination: default\n gateway: 192.168.1.254\n"), + Some(Ipv4Addr::new(192, 168, 1, 254)) + ); + assert_eq!( + windows_gateway( + "Network Destination Netmask Gateway Interface Metric\n 0.0.0.0 0.0.0.0 10.0.0.138 10.0.0.12 25\n" + ), + Some(Ipv4Addr::new(10, 0, 0, 138)) + ); + assert_eq!( + tag(" v ", "Name"), + Some("v") + ); + } +} diff --git a/crates/horizon-friends/src/reach.rs b/crates/horizon-friends/src/reach.rs new file mode 100644 index 000000000..12550a59f --- /dev/null +++ b/crates/horizon-friends/src/reach.rs @@ -0,0 +1,360 @@ +//! How a host can be reached, worked out on its own: its interface +//! addresses (LAN, VPNs such as Tailscale or ZeroTier, IPv6), a port opened +//! on the router (PCP / NAT-PMP / UPnP), and its public address from STUN. +//! The endpoints go into the invite code; the verdict tells the host what +//! friends outside its network can expect, and what to do when it's nothing. +use crate::portmap::{self, Mapping}; +use std::{ + net::{IpAddr, Ipv4Addr, SocketAddr}, + time::Duration, +}; + +/// Where the troubleshooting lives (shown to hosts nobody can reach). +pub const HELP_URL: &str = + "https://github.com/ludovic111/horizon/blob/main/docs/play-with-friends.md#troubleshooting"; + +#[derive(Clone, Debug)] +pub struct Options { + /// Ask the router to open the port. + pub map_port: bool, + pub stun: Vec, + /// Offer 127.0.0.1 too (tests with both ends on one machine). + pub loopback: bool, +} + +#[derive(Clone, Debug, Default)] +pub struct Reach { + pub port: u16, + pub local: Vec, + pub mapping: Option, + pub mapping_error: Option, + pub public_ip: Option, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Verdict { + /// The router opened the port (method name). + Mapped(&'static str), + /// This machine has the public address itself. + Public, + /// Only the LAN and VPNs reach it; `cgnat` when the router is itself + /// behind another NAT (the provider's, or a second router), so port + /// forwarding on it can't help. + LocalOnly { cgnat: bool }, +} + +/// 100.64.0.0/10 (carrier-grade NAT, also Tailscale's range) or private. +fn shared(ip: IpAddr) -> bool { + match ip { + IpAddr::V4(v4) => { + let o = v4.octets(); + v4.is_private() || (o[0] == 100 && (64..128).contains(&o[1])) + } + IpAddr::V6(_) => false, + } +} + +/// Interface names of containers and VMs, whose addresses nobody else reaches. +fn virtual_interface(name: &str) -> bool { + [ + "docker", "br-", "veth", "virbr", "vboxnet", "vmnet", "lxc", "cni", "podman", + ] + .iter() + .any(|p| name.starts_with(p)) +} + +/// This machine's addresses worth offering, best first: private IPv4 (the +/// LAN), shared IPv4 (Tailscale's 100.64/10, CGNAT), other IPv4, global +/// IPv6, unique-local IPv6 (some VPNs). No link-local; loopback on request. +pub fn interface_addresses(loopback: bool) -> Vec { + let mut found: Vec<(u8, IpAddr)> = Vec::new(); + for i in if_addrs::get_if_addrs().unwrap_or_default() { + if virtual_interface(&i.name) { + continue; + } + let ip = i.ip(); + let rank = match ip { + IpAddr::V4(v4) if v4.is_loopback() => { + if loopback { + 6 + } else { + continue; + } + } + IpAddr::V4(v4) if v4.is_link_local() || v4.is_unspecified() => continue, + IpAddr::V4(v4) if v4.is_private() => 0, + v4 @ IpAddr::V4(_) if shared(v4) => 1, + IpAddr::V4(_) => 2, + IpAddr::V6(v6) if v6.is_loopback() || v6.is_unspecified() => continue, + // fe80::/10. + IpAddr::V6(v6) if v6.segments()[0] & 0xffc0 == 0xfe80 => continue, + // fc00::/7. + IpAddr::V6(v6) if v6.segments()[0] & 0xfe00 == 0xfc00 => 4, + IpAddr::V6(_) => 3, + }; + if !found.iter().any(|(_, a)| *a == ip) { + found.push((rank, ip)); + } + } + found.sort_by_key(|(r, _)| *r); + // One IPv6 address per kind is enough (temporary addresses multiply them). + let mut out = Vec::new(); + let mut v6_kinds = Vec::new(); + for (rank, ip) in found { + if ip.is_ipv6() { + if v6_kinds.contains(&rank) { + continue; + } + v6_kinds.push(rank); + } + out.push(ip); + } + out +} + +impl Reach { + /// Find out (takes a few seconds: router discovery and STUN). + pub fn discover(port: u16, options: &Options) -> Self { + let local = interface_addresses(options.loopback); + let stun = { + let servers = options.stun.clone(); + std::thread::spawn(move || crate::stun::public_ip(&servers, Duration::from_secs(2))) + }; + let (mapping, mapping_error) = if options.map_port { + match local.iter().find_map(|ip| match ip { + IpAddr::V4(v4) if v4.is_private() => Some(*v4), + _ => None, + }) { + Some(client) => { + let targets = portmap::Targets::discover(Duration::from_millis(1500)); + match portmap::map(&targets, client, port, portmap::LEASE) { + Ok(m) => (Some(m), None), + Err(e) => (None, Some(e)), + } + } + None => ( + None, + Some("no private IPv4 address (no router to ask)".into()), + ), + } + } else { + (None, Some("port mapping is off".into())) + }; + let public_ip = stun.join().ok().flatten(); + Self { + port, + local, + mapping, + mapping_error, + public_ip, + } + } + + /// The router's public side, with the WAN address from STUN when the + /// router didn't give one. + fn mapped_endpoint(&self) -> Option { + let m = self.mapping.as_ref()?; + let ip = if m.external.ip().is_unspecified() { + self.public_ip? + } else { + m.external.ip() + }; + Some(SocketAddr::new(ip, m.external.port())) + } + + pub fn verdict(&self) -> Verdict { + if let Some(m) = &self.mapping { + let wan = m.external.ip(); + // The router's own WAN side is shared or private, or STUN sees + // another address: a second NAT upstream. + let behind = (!wan.is_unspecified() && shared(wan)) + || self + .public_ip + .is_some_and(|p| !wan.is_unspecified() && p != wan); + if !behind { + return Verdict::Mapped(m.method.name()); + } + return Verdict::LocalOnly { cgnat: true }; + } + if let Some(p) = self.public_ip + && self.local.contains(&p) + { + return Verdict::Public; + } + Verdict::LocalOnly { cgnat: false } + } + + /// The code's endpoints, best first: the router mapping (or this + /// machine's own public address), then the public address on the + /// direct port (works once the port is forwarded by hand), then the + /// interface addresses. + pub fn endpoints(&self) -> Vec { + let mut out = Vec::new(); + let mut push = |a: SocketAddr| { + if !out.contains(&a) { + out.push(a); + } + }; + if let Some(m) = self.mapped_endpoint() { + push(m); + } + if let Some(p) = self.public_ip { + push(SocketAddr::new(p, self.port)); + } + for ip in &self.local { + push(SocketAddr::new(*ip, self.port)); + } + out.truncate(crate::invite::MAX_ENDPOINTS); + out + } + + /// The LAN address a port forward should point at. + pub fn lan_ip(&self) -> Option { + self.local.iter().find_map(|ip| match ip { + IpAddr::V4(v4) if v4.is_private() => Some(*v4), + _ => None, + }) + } + + /// What the host reads under the code. + pub fn summary(&self) -> String { + match self.verdict() { + Verdict::Mapped(method) => { + let at = self.mapped_endpoint().map(|a| format!(" ({a})")).unwrap_or_default(); + format!("Friends anywhere can join: your router opened the port with {method}{at}.") + } + Verdict::Public => format!( + "Friends anywhere can join: this computer has a public address (TCP port {} must not be blocked by a firewall).", + self.port + ), + Verdict::LocalOnly { cgnat: true } => "Friends on your network or VPN can join. From the internet they can't: \ + your router is itself behind another NAT (your provider's carrier-grade NAT, CGNAT, or a second router), \ + so opening its port isn't enough. Use a relay or a VPN such as Tailscale or ZeroTier." + .to_owned(), + Verdict::LocalOnly { cgnat: false } => { + let forward = match self.lan_ip() { + Some(ip) => format!("forward TCP port {} to {ip}", self.port), + None => format!("forward TCP port {}", self.port), + }; + format!( + "Friends on your network or VPN can join. For friends on the internet: turn on UPnP on your router, \ + or {forward}, or use a relay, or a VPN such as Tailscale or ZeroTier (the code already holds \ + your VPN address)." + ) + } + } + } + + /// Delete the router mapping. + pub fn release(&mut self) { + if let Some(m) = self.mapping.take() { + m.remove(); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn reach(public: Option<&str>, local: &[&str]) -> Reach { + Reach { + port: 25580, + local: local.iter().map(|s| s.parse().unwrap()).collect(), + mapping: None, + mapping_error: Some("no router answered".into()), + public_ip: public.map(|s| s.parse().unwrap()), + } + } + + #[test] + fn endpoints_put_the_public_side_first() { + let r = reach( + Some("203.0.113.5"), + &["192.168.1.20", "100.72.51.8", "2001:db8::20"], + ); + assert_eq!( + r.endpoints(), + [ + "203.0.113.5:25580", + "192.168.1.20:25580", + "100.72.51.8:25580", + "[2001:db8::20]:25580" + ] + .map(|s| s.parse::().unwrap()) + ); + assert_eq!(r.verdict(), Verdict::LocalOnly { cgnat: false }); + let s = r.summary(); + assert!( + s.contains("forward TCP port 25580 to 192.168.1.20") && s.contains("Tailscale"), + "{s}" + ); + } + + #[test] + fn a_public_address_on_this_machine() { + let r = reach(Some("203.0.113.5"), &["203.0.113.5"]); + assert_eq!(r.verdict(), Verdict::Public); + assert_eq!( + r.endpoints(), + vec!["203.0.113.5:25580".parse::().unwrap()] + ); + } + + #[test] + fn a_router_mapping_and_what_is_behind_it() { + use crate::portmap::{Mapping, Method}; + let mut r = reach(Some("203.0.113.5"), &["192.168.1.20"]); + r.mapping = Some(Mapping::granted( + Method::Upnp, + "203.0.113.5:40123".parse().unwrap(), + )); + assert_eq!(r.verdict(), Verdict::Mapped("UPnP")); + assert_eq!( + r.endpoints()[0], + "203.0.113.5:40123".parse::().unwrap() + ); + assert!(r.summary().contains("UPnP (203.0.113.5:40123)")); + // The router didn't say its address: STUN's is used. + r.mapping = Some(Mapping::granted( + Method::NatPmp, + "0.0.0.0:40123".parse().unwrap(), + )); + assert_eq!( + r.endpoints()[0], + "203.0.113.5:40123".parse::().unwrap() + ); + // The router's WAN side is in the carrier's shared range: CGNAT. + r.mapping = Some(Mapping::granted( + Method::Pcp, + "100.80.1.2:40123".parse().unwrap(), + )); + assert_eq!(r.verdict(), Verdict::LocalOnly { cgnat: true }); + assert!(r.summary().contains("CGNAT")); + // STUN sees another address than the router's: a second NAT. + r.mapping = Some(Mapping::granted( + Method::Pcp, + "198.51.100.1:40123".parse().unwrap(), + )); + assert_eq!(r.verdict(), Verdict::LocalOnly { cgnat: true }); + } + + #[test] + fn shared_ranges() { + assert!(shared("100.72.51.8".parse().unwrap())); + assert!(shared("10.1.2.3".parse().unwrap())); + assert!(!shared("100.128.0.1".parse().unwrap())); + assert!(!shared("8.8.8.8".parse().unwrap())); + assert!( + virtual_interface("docker0") + && !virtual_interface("tailscale0") + && !virtual_interface("en0") + ); + } + + #[test] + fn interface_addresses_skip_loopback_unless_asked() { + assert!(interface_addresses(false).iter().all(|a| !a.is_loopback())); + assert!(interface_addresses(true).contains(&IpAddr::V4(Ipv4Addr::LOCALHOST))); + } +} diff --git a/crates/horizon-friends/src/stun.rs b/crates/horizon-friends/src/stun.rs new file mode 100644 index 000000000..e1716d268 --- /dev/null +++ b/crates/horizon-friends/src/stun.rs @@ -0,0 +1,207 @@ +//! The host's public IPv4 address, from a STUN Binding request (RFC 8489) +//! to public STUN servers. Only the address is used: the port a STUN server +//! sees is a UDP mapping, while the game listens on TCP. +use std::{ + io, + net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, ToSocketAddrs, UdpSocket}, + time::Duration, +}; + +/// Two independent operators, so one outage doesn't break discovery; both +/// run free public STUN for WebRTC at a global scale. Configurable with +/// `HORIZON_STUN_SERVERS` (a comma list; `none` turns STUN off). +pub const DEFAULT_SERVERS: &[&str] = &["stun.cloudflare.com:3478", "stun.l.google.com:19302"]; + +const MAGIC: u32 = 0x2112_A442; + +/// The servers to ask: `HORIZON_STUN_SERVERS`, else the defaults. +pub fn servers_from_env() -> Vec { + match std::env::var("HORIZON_STUN_SERVERS") { + Ok(v) => parse_servers(&v), + Err(_) => DEFAULT_SERVERS.iter().map(|s| (*s).to_owned()).collect(), + } +} +/// A comma list; empty or `none` means no STUN. +pub fn parse_servers(list: &str) -> Vec { + if list.trim().eq_ignore_ascii_case("none") { + return Vec::new(); + } + list.split(',') + .map(str::trim) + .filter(|s| !s.is_empty()) + .map(str::to_owned) + .collect() +} + +fn request(id: &[u8; 12]) -> [u8; 20] { + let mut m = [0u8; 20]; + m[0..2].copy_from_slice(&0x0001u16.to_be_bytes()); + m[4..8].copy_from_slice(&MAGIC.to_be_bytes()); + m[8..20].copy_from_slice(id); + m +} + +/// The mapped address in a Binding success response for transaction `id`. +pub fn parse_response(m: &[u8], id: &[u8; 12]) -> Option { + if m.len() < 20 || m[0..2] != [0x01, 0x01] || m[4..8] != MAGIC.to_be_bytes() || &m[8..20] != id + { + return None; + } + let len = usize::from(u16::from_be_bytes([m[2], m[3]])); + let attrs = m.get(20..20 + len)?; + let mut i = 0; + let mut plain = None; + while i + 4 <= attrs.len() { + let kind = u16::from_be_bytes([attrs[i], attrs[i + 1]]); + let alen = usize::from(u16::from_be_bytes([attrs[i + 2], attrs[i + 3]])); + let value = attrs.get(i + 4..i + 4 + alen)?; + let xor = kind == 0x0020; + if (xor || kind == 0x0001) && value.len() >= 8 { + let mut port = u16::from_be_bytes([value[2], value[3]]); + if xor { + port ^= (MAGIC >> 16) as u16; + } + let ip = match value[1] { + 1 => { + let mut o: [u8; 4] = value[4..8].try_into().ok()?; + if xor { + for (b, k) in o.iter_mut().zip(MAGIC.to_be_bytes()) { + *b ^= k; + } + } + IpAddr::V4(Ipv4Addr::from(o)) + } + 2 if value.len() >= 20 => { + let mut o: [u8; 16] = value[4..20].try_into().ok()?; + if xor { + let mut key = MAGIC.to_be_bytes().to_vec(); + key.extend_from_slice(id); + for (b, k) in o.iter_mut().zip(key) { + *b ^= k; + } + } + IpAddr::V6(Ipv6Addr::from(o)) + } + _ => return None, + }; + let found = SocketAddr::new(ip, port); + if xor { + return Some(found); + } + plain = Some(found); + } + i += 4 + alen.div_ceil(4) * 4; + } + plain +} + +/// Ask one server (resolved to IPv4), retrying twice. +pub fn query(server: &str, timeout: Duration) -> io::Result { + let target = server + .to_socket_addrs()? + .find(SocketAddr::is_ipv4) + .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "no IPv4 address"))?; + let socket = UdpSocket::bind("0.0.0.0:0")?; + socket.set_read_timeout(Some(timeout / 3))?; + let mut id = [0u8; 12]; + crate::fill_random(&mut id)?; + let mut buf = [0u8; 576]; + for _ in 0..3 { + socket.send_to(&request(&id), target)?; + loop { + match socket.recv_from(&mut buf) { + Ok((n, from)) if from == target => { + if let Some(a) = parse_response(&buf[..n], &id) { + return Ok(a); + } + } + Ok(_) => {} + Err(_) => break, + } + } + } + Err(io::Error::new(io::ErrorKind::TimedOut, "no STUN answer")) +} + +/// The public IPv4 address from the first server that answers. +pub fn public_ip(servers: &[String], timeout: Duration) -> Option { + servers + .iter() + .find_map(|s| query(s, timeout).ok()) + .map(|a| a.ip()) +} + +#[cfg(test)] +pub(crate) mod tests { + use super::*; + + /// A STUN server answering with XOR-MAPPED-ADDRESS = `answer`. + pub(crate) fn mock(answer: SocketAddr) -> SocketAddr { + let s = UdpSocket::bind("127.0.0.1:0").unwrap(); + let addr = s.local_addr().unwrap(); + std::thread::spawn(move || { + let mut buf = [0u8; 576]; + while let Ok((n, from)) = s.recv_from(&mut buf) { + if n < 20 { + continue; + } + let id: [u8; 12] = buf[8..20].try_into().unwrap(); + let _ = s.send_to(&response(&id, answer), from); + } + }); + addr + } + pub(crate) fn response(id: &[u8; 12], a: SocketAddr) -> Vec { + let IpAddr::V4(ip) = a.ip() else { panic!() }; + let mut attr = vec![0x00, 0x20, 0x00, 0x08, 0x00, 0x01]; + attr.extend_from_slice(&(a.port() ^ (MAGIC >> 16) as u16).to_be_bytes()); + let o = ip.octets(); + let k = MAGIC.to_be_bytes(); + attr.extend((0..4).map(|i| o[i] ^ k[i])); + let mut m = vec![0x01, 0x01]; + m.extend_from_slice(&(attr.len() as u16).to_be_bytes()); + m.extend_from_slice(&MAGIC.to_be_bytes()); + m.extend_from_slice(id); + m.extend(attr); + m + } + + #[test] + fn asks_and_reads_the_mapped_address() { + let answer: SocketAddr = "203.0.113.9:40000".parse().unwrap(); + let server = mock(answer); + assert_eq!( + query(&server.to_string(), Duration::from_secs(2)).unwrap(), + answer + ); + // The first server that answers wins; dead ones are skipped. + let dead = UdpSocket::bind("127.0.0.1:0") + .unwrap() + .local_addr() + .unwrap() + .to_string(); + assert_eq!( + public_ip(&[dead, server.to_string()], Duration::from_millis(300)), + Some(answer.ip()) + ); + } + + #[test] + fn responses_are_checked() { + let id = [7u8; 12]; + let a: SocketAddr = "198.51.100.4:1234".parse().unwrap(); + let good = response(&id, a); + assert_eq!(parse_response(&good, &id), Some(a)); + assert_eq!(parse_response(&good, &[8u8; 12]), None); + let mut error = good.clone(); + error[1] = 0x11; + assert_eq!(parse_response(&error, &id), None); + assert_eq!(parse_response(&good[..10], &id), None); + } + + #[test] + fn server_lists() { + assert_eq!(parse_servers("none"), Vec::::new()); + assert_eq!(parse_servers(" a:1 , b:2,"), vec!["a:1", "b:2"]); + } +} diff --git a/crates/horizon-relay/Dockerfile b/crates/horizon-relay/Dockerfile index 7cae743e4..8f41b4ea3 100644 --- a/crates/horizon-relay/Dockerfile +++ b/crates/horizon-relay/Dockerfile @@ -1,4 +1,4 @@ -# The Play with friends relay (docs/play-with-friends.md, "Deploying the relay"). +# The Play with friends relay, for anyone to run (docs/play-with-friends.md, "Running your own relay"). # Build context: the repository root (the workspace's manifests and lockfile): # docker build -f crates/horizon-relay/Dockerfile -t horizon-relay . FROM rust:1-slim-bookworm AS build diff --git a/crates/horizon-relay/horizon-relay.service b/crates/horizon-relay/horizon-relay.service new file mode 100644 index 000000000..dc67babdd --- /dev/null +++ b/crates/horizon-relay/horizon-relay.service @@ -0,0 +1,24 @@ +# A systemd unit for a self-hosted Play with friends relay (docs/play-with-friends.md, +# "Running your own relay"). Install the binary as /usr/local/bin/horizon-relay, copy this +# file to /etc/systemd/system/, then: systemctl enable --now horizon-relay +[Unit] +Description=Horizon play-with-friends relay +After=network-online.target +Wants=network-online.target + +[Service] +ExecStart=/usr/local/bin/horizon-relay +# The port friends reach (forward it on your router, TCP). Limits: RELAY_* in the docs. +Environment=PORT=7000 +# Environment=RELAY_SESSION_KBPS=1024 +# Environment=RELAY_TOTAL_MBPS=20 +DynamicUser=yes +NoNewPrivileges=yes +ProtectSystem=strict +ProtectHome=yes +PrivateTmp=yes +Restart=on-failure +RestartSec=5 + +[Install] +WantedBy=multi-user.target diff --git a/crates/horizon-relay/railway.toml b/crates/horizon-relay/railway.toml deleted file mode 100644 index b6916e4d4..000000000 --- a/crates/horizon-relay/railway.toml +++ /dev/null @@ -1,13 +0,0 @@ -# Railway service for the Play with friends relay. Set the service's config -# file path to crates/horizon-relay/railway.toml (docs/play-with-friends.md). -[build] -builder = "DOCKERFILE" -dockerfilePath = "crates/horizon-relay/Dockerfile" -watchPatterns = ["crates/horizon-relay/**", "crates/horizon-friends/**", "Cargo.lock"] - -[deploy] -healthcheckPath = "/health" -healthcheckTimeout = 30 -restartPolicyType = "ON_FAILURE" -restartPolicyMaxRetries = 10 -numReplicas = 1 diff --git a/crates/horizon-relay/tests/tunnel.rs b/crates/horizon-relay/tests/tunnel.rs index d988edb88..99c3eb663 100644 --- a/crates/horizon-relay/tests/tunnel.rs +++ b/crates/horizon-relay/tests/tunnel.rs @@ -1,11 +1,16 @@ -//! A relay, a host tunnel in front of an echo server standing in for the -//! integrated server, and guest tunnels, all on loopback in one process. +//! Hosts in front of an echo server standing in for the integrated server, +//! guests, and (for the relay cases) a self-hosted relay, all on loopback +//! in one process. Port mapping and STUN are off here: they have their own +//! tests against mock routers and servers in horizon-friends. use horizon_friends::{ Code, Host, HostConfig, HostEvent, JoinError, PathMode, guest::{self, GuestConfig}, + invite::{self, Invite, Parsed}, + reach, }; use horizon_relay::{Config, Relay, limits::Rates}; use std::{ + cell::RefCell, io::{Read, Write}, net::{SocketAddr, TcpListener, TcpStream}, time::{Duration, Instant}, @@ -45,25 +50,26 @@ fn generous() -> Config { } } -fn host(relay: &str, lan: SocketAddr, path: PathMode) -> (Host, Code) { - let host = Host::start(HostConfig { - relay: relay.to_owned(), - lan, +fn start(relay: Option<&str>, path: PathMode) -> Host { + Host::start(HostConfig { + lan: echo_server(), protocol: PROTOCOL, game: "26.3".into(), + relay: relay.map(str::to_owned), path, + port: 0, + reach: reach::Options { + map_port: false, + stun: Vec::new(), + loopback: true, + }, }) - .unwrap(); - let code = wait_event(&host, |e| match e { - HostEvent::Code(c) => Some(c.clone()), - _ => None, - }); - (host, code) + .unwrap() } thread_local! { /// Events polled but not yet waited for. - static BACKLOG: std::cell::RefCell> = const { std::cell::RefCell::new(Vec::new()) }; + static BACKLOG: RefCell> = const { RefCell::new(Vec::new()) }; } /// The first event (in order) that `f` picks; the others stay queued. @@ -83,10 +89,25 @@ fn wait_event(host: &Host, mut f: impl FnMut(&HostEvent) -> Option) -> T { panic!("no such host event"); } -fn join(relay: &str, code: &Code, path: PathMode) -> Result { +/// The invite once ready (and, with a relay, once it holds the short code). +fn invite_of(host: &Host, with_relay: bool) -> (String, Option) { + let deadline = Instant::now() + Duration::from_secs(10); + loop { + let s = host.state(); + if let Some(code) = s.invite + && (!with_relay || s.short.is_some()) + { + return (code, s.short); + } + assert!(Instant::now() < deadline, "no code"); + std::thread::sleep(Duration::from_millis(10)); + } +} + +fn join(code: &str, relay: Option<&str>, path: PathMode) -> Result { guest::join(&GuestConfig { - relay: relay.to_owned(), - code: code.clone(), + code: code.to_owned(), + relay: relay.map(str::to_owned), protocol: PROTOCOL, game: "26.3".into(), path, @@ -114,110 +135,174 @@ fn payload(n: usize) -> Vec { (0..n).map(|i| (i * 7 + i / 251) as u8).collect() } +fn long(code: &str) -> Invite { + match invite::parse(code) { + Some(Parsed::Long(i)) => i, + other => panic!("{other:?}"), + } +} + #[test] -fn the_direct_path_carries_the_stream() { - let (relay, address) = relay(generous()); - let (host, code) = host(&address, echo_server(), PathMode::Auto); - assert_eq!(code.nameplate.len(), 4); - let tunnel = join(&address, &code, PathMode::Auto).unwrap(); +fn the_code_alone_connects_without_any_server() { + let host = start(None, PathMode::Auto); + let (code, short) = invite_of(&host, false); + assert!(short.is_none()); + let invite = long(&code); + assert!(invite.relay.is_none()); assert!( - tunnel.direct, - "loopback ends should reach each other directly" + invite.endpoints.iter().any(|e| e.ip().is_loopback()), + "{invite:?}" ); - let data = payload(1 << 20); - round_trip(tunnel, &data); + let tunnel = join(&code, None, PathMode::Auto).unwrap(); + assert!(tunnel.direct); + round_trip(tunnel, &payload(1 << 20)); assert!(wait_event(&host, |e| match e { HostEvent::Connected { direct, .. } => Some(*direct), _ => None, })); - // Only the handshake went through the relay. - let counts = relay.counts(); - assert!(counts.relayed_bytes < 16 * 1024, "{counts:?}"); - assert_eq!(counts.hosts, 1); wait_event(&host, |e| { matches!(e, HostEvent::Disconnected { .. }).then_some(()) }); assert_eq!(host.sessions(), 0); -} - -#[test] -fn the_relay_path_carries_the_stream() { - let (relay, address) = relay(generous()); - let (host, code) = host(&address, echo_server(), PathMode::Auto); - let tunnel = join(&address, &code, PathMode::RelayOnly).unwrap(); - assert!(!tunnel.direct); - let data = payload(1 << 20); - round_trip(tunnel, &data); - assert!(!wait_event(&host, |e| match e { - HostEvent::Connected { direct, .. } => Some(*direct), - _ => None, - })); - // Both directions, encrypted and framed: a little more than twice. - let relayed = relay.counts().relayed_bytes; - assert!(relayed > 2 * data.len() as u64, "{relayed}"); - // Two guests at once, one per path. - let a = join(&address, &code, PathMode::RelayOnly).unwrap(); - let b = join(&address, &code, PathMode::Auto).unwrap(); + // Two guests at once. + let a = join(&code, None, PathMode::Auto).unwrap(); + let b = join(&code, None, PathMode::Auto).unwrap(); let ta = std::thread::spawn(move || round_trip(a, &payload(50_000))); round_trip(b, &payload(70_000)); ta.join().unwrap(); -} - -#[test] -fn the_host_can_refuse_direct_connections() { - let (_relay, address) = relay(generous()); - let (_host, code) = host(&address, echo_server(), PathMode::RelayOnly); - let tunnel = join(&address, &code, PathMode::Auto).unwrap(); - assert!(!tunnel.direct); - round_trip(tunnel, b"relay only"); - // A guest that insists on a direct path gets none. + // Without a relay, a relay-only guest has nowhere to go. assert!(matches!( - join(&address, &code, PathMode::DirectOnly), - Err(JoinError::Failed(_)) + join(&code, None, PathMode::RelayOnly), + Err(JoinError::NotReachable) )); } #[test] -fn wrong_secrets_fail_and_retire_the_code() { +fn a_short_code_through_a_self_hosted_relay() { + let (relay, address) = relay(generous()); + let host = start(Some(&address), PathMode::Auto); + let (code, short) = invite_of(&host, true); + let short = short.unwrap().to_string(); + // The full code names the relay too. + assert_eq!(long(&code).relay.unwrap().address, address); + // A short code needs the relay's address. + assert!(matches!( + join(&short, None, PathMode::Auto), + Err(JoinError::NeedsRelay) + )); + let tunnel = join(&short, Some(&address), PathMode::RelayOnly).unwrap(); + assert!(!tunnel.direct); + let data = payload(1 << 20); + round_trip(tunnel, &data); + let relayed = relay.counts().relayed_bytes; + assert!(relayed > 2 * data.len() as u64, "{relayed}"); + // The relay's own direct race (both ends on loopback): direct. + let tunnel = join(&short, Some(&address), PathMode::Auto).unwrap(); + assert!(tunnel.direct); + round_trip(tunnel, b"raced"); +} + +#[test] +fn unreachable_endpoints_fall_back_to_the_relay_in_the_code() { + let (relay, address) = relay(generous()); + let host = start(Some(&address), PathMode::Auto); + let (code, _) = invite_of(&host, true); + // The same invite with an endpoint nobody answers on. + let mut invite = long(&code); + let dead = TcpListener::bind("127.0.0.1:0") + .unwrap() + .local_addr() + .unwrap(); + invite.endpoints = vec![dead]; + let started = Instant::now(); + assert!(matches!( + join(&invite.encode(), None, PathMode::DirectOnly), + Err(JoinError::NotReachable) + )); + assert!(started.elapsed() < Duration::from_secs(6)); + let tunnel = join(&invite.encode(), None, PathMode::Auto).unwrap(); + round_trip(tunnel, b"fallback"); + assert!(relay.counts().relayed_bytes > 0); + // Without a relay in the code: the host's advice is the way out. + invite.relay = None; + assert!(matches!( + join(&invite.encode(), None, PathMode::Auto), + Err(JoinError::NotReachable) + )); +} + +#[test] +fn wrong_secrets_fail() { let (_relay, address) = relay(generous()); - let (host, code) = host(&address, echo_server(), PathMode::Auto); + let host = start(Some(&address), PathMode::Auto); + let (code, short) = invite_of(&host, true); + // A full code with another secret (re-encoded, so the checksum passes). + let mut forged = long(&code); + forged.secret[0] ^= 1; + assert!(matches!( + join(&forged.encode(), None, PathMode::DirectOnly), + Err(JoinError::WrongCode) + )); + assert_eq!( + wait_event(&host, |e| match e { + HostEvent::WrongCode { count } => Some(*count), + _ => None, + }), + 1 + ); + // Short codes: five wrong secrets retire it for a new one. + let short = short.unwrap(); let wrong = Code { - nameplate: code.nameplate.clone(), - secret: if code.secret == "0000" { + nameplate: short.nameplate.clone(), + secret: if short.secret == "0000" { "0001".into() } else { "0000".into() }, }; - for i in 1..=horizon_friends::host::MAX_WRONG { - let e = join(&address, &wrong, PathMode::Auto).err().unwrap(); + for _ in 0..horizon_friends::host::MAX_WRONG { + let e = join(&wrong.to_string(), Some(&address), PathMode::Auto) + .err() + .unwrap(); assert!(matches!(e, JoinError::WrongCode), "{e}"); - let count = wait_event(&host, |e| match e { - HostEvent::WrongCode { count } => Some(*count), - _ => None, - }); - assert_eq!(count, i); } - // A new code replaces the old one, which has ended. - let fresh = wait_event(&host, |e| match e { - HostEvent::Code(c) => Some(c.clone()), - _ => None, - }); - assert_ne!(fresh.nameplate, code.nameplate); + let deadline = Instant::now() + Duration::from_secs(10); + let fresh = loop { + if let Some(s) = host.state().short + && s.nameplate != short.nameplate + { + break s; + } + assert!(Instant::now() < deadline, "no new short code"); + std::thread::sleep(Duration::from_millis(20)); + }; assert!(matches!( - join(&address, &code, PathMode::Auto), + join(&short.to_string(), Some(&address), PathMode::Auto), Err(JoinError::Ended) )); - round_trip(join(&address, &fresh, PathMode::Auto).unwrap(), b"fresh"); + round_trip( + join(&fresh.to_string(), Some(&address), PathMode::Auto).unwrap(), + b"fresh", + ); + // The full code follows the new short code; its secret stays. + let (code2, _) = invite_of(&host, true); + assert_eq!(long(&code2).relay.unwrap().code, fresh); + assert_eq!(long(&code2).secret, long(&code).secret); } #[test] -fn unknown_codes_versions_and_ended_invites() { +fn bad_codes_unknown_codes_versions_and_ended_invites() { + assert!(matches!( + join("hello", None, PathMode::Auto), + Err(JoinError::BadCode(_)) + )); let (relay, address) = relay(generous()); - let (mut host, code) = host(&address, echo_server(), PathMode::Auto); + let mut host = start(Some(&address), PathMode::RelayOnly); + let (_, short) = invite_of(&host, true); + let short = short.unwrap(); let other = guest::join(&GuestConfig { - relay: address.clone(), - code: code.clone(), + code: short.to_string(), + relay: Some(address.clone()), protocol: PROTOCOL - 1, game: "26.2".into(), path: PathMode::Auto, @@ -233,26 +318,23 @@ fn unknown_codes_versions_and_ended_invites() { } host.stop(); assert!(matches!( - join(&address, &code, PathMode::Auto), + join(&short.to_string(), Some(&address), PathMode::Auto), Err(JoinError::Ended) )); // A nameplate nobody holds; five of them block this address for a while. let free = (0..) .map(|i| horizon_friends::code::nameplate(i * 7919)) - .find(|n| *n != code.nameplate) + .find(|n| *n != short.nameplate) .unwrap(); - let unknown = Code { - nameplate: free, - secret: "0000".into(), - }; + let unknown = format!("{free}0000"); for _ in 0..5 { assert!(matches!( - join(&address, &unknown, PathMode::Auto), + join(&unknown, Some(&address), PathMode::Auto), Err(JoinError::UnknownCode) )); } assert!(matches!( - join(&address, &code, PathMode::Auto), + join(&short.to_string(), Some(&address), PathMode::Auto), Err(JoinError::RateLimited) )); let counts = relay.counts(); @@ -284,15 +366,12 @@ fn a_host_that_never_attaches_is_unreachable() { else { panic!() }; - let code = Code { - nameplate, - secret: "0000".into(), - }; + let code = format!("{nameplate}0000"); assert!(matches!( - join(&address, &code, PathMode::Auto), + join(&code, Some(&address), PathMode::Auto), Err(JoinError::HostUnreachable) )); - // The relay announced the session; attaching late or with another token fails. + // The relay announced the session; attaching late fails. let FromRelay::Join { session } = wire::recv(&mut control).unwrap() else { panic!() }; @@ -319,8 +398,14 @@ fn relayed_bandwidth_is_capped() { session_rate: rate, ..generous() }); - let (_host, code) = host(&address, echo_server(), PathMode::RelayOnly); - let tunnel = join(&address, &code, PathMode::RelayOnly).unwrap(); + let host = start(Some(&address), PathMode::RelayOnly); + let (_, short) = invite_of(&host, true); + let tunnel = join( + &short.unwrap().to_string(), + Some(&address), + PathMode::RelayOnly, + ) + .unwrap(); let started = Instant::now(); round_trip(tunnel, &payload(600_000)); // The first 100 kB pass at once, the rest at 200 kB/s. diff --git a/docs/play-with-friends.md b/docs/play-with-friends.md index 6ea3449c8..08f1ace8d 100644 --- a/docs/play-with-friends.md +++ b/docs/play-with-friends.md @@ -1,259 +1,217 @@ -# Play with friends (invite codes) +# Play with friends -A player hosts their single-player world with one click and gets a short code such as -`K7QM-3XPD`. Friends paste the code (on the multiplayer screen in game, or on the launcher's -Play page) and join. No port forwarding, no accounts. +A player opens their single-player world to friends with one click and gets an **invite code**. +Friends paste the code (on the multiplayer screen in game, or on the launcher's Play page) and join. +There is no Horizon server in the middle and no account: the code itself says where the host is and +holds the key that encrypts the game between them. -It is built on what Open to LAN already does: the integrated server (`crates/horizon-client/src/lan`) -listens on a local TCP port and speaks the vanilla protocol. Play with friends adds a tunnel in front -of that port and a small relay service (`crates/horizon-relay`) that introduces the two ends. Neither -the integrated server nor the guest's client changes: the tunnel carries exactly the bytes vanilla's -protocol would send, between a loopback port on each side. +It is built on Open to LAN: the integrated server (`crates/horizon-client/src/lan`) listens on a local +TCP port and speaks the vanilla protocol. Play with friends puts an encrypted tunnel in front of that +port. Neither the integrated server nor the guest's client changes: the tunnel carries exactly the +bytes vanilla's protocol would send, between a loopback port on each side. ``` - guest's game host's game - ┌──────────────┐ 127.0.0.1:A ┌────────────┐ direct TCP ┌────────────┐ 127.0.0.1:LAN ┌──────────────┐ - │ client │──────────────▶│ guest │◀═══ (preferred) ════▶│ host │────────────────▶│ integrated │ - │ (unchanged) │ │ tunnel │ │ tunnel │ │ server (LAN) │ - └──────────────┘ └─────┬──────┘ └─────┬──────┘ └──────────────┘ - │ ┌──────────────────┐ │ - └─────▶│ horizon-relay │◀────────┘ - join, PAKE, │ codes, rendezvous│ register, control, - or the whole│ byte relay │ attach per guest - stream └──────────────────┘ + guest's game host's game + ┌──────────────┐ 127.0.0.1:A ┌────────────┐ TCP, end-to-end encrypted ┌────────────┐ 127.0.0.1:LAN ┌──────────────┐ + │ client │────────────▶│ guest │══════════════════════════════▶│ host │──────────────▶│ integrated │ + │ (unchanged) │ │ tunnel │ to an address from the code │ tunnel │ │ server (LAN) │ + └──────────────┘ └────────────┘ └────────────┘ └──────────────┘ + ╲ optional: a relay anyone can run ╱ + ╲──────────▶ horizon-relay (short codes, fallback) ◀╱ ``` -## What vanilla has +## How it works -Vanilla 26.3 (read with `tools/rea_vanilla.py`) has two related things, and neither is this: +**Hosting.** "Invite friends" (in Horizon's pause menu) opens the world to LAN if it isn't (Open to +LAN's defaults), then the host's game, on its own: -- **Open to LAN** (`IntegratedServer.publishServer`, `ShareToLanScreen`, `LanServerPinger`, - `PublishCommand`): the integrated server listens on a port and announces itself by multicast on the - local network. This is the baseline Horizon follows exactly: Play with friends uses the very same - server, the same `IntegratedServer.MAX_PLAYERS` (8), the same offline-mode login, game mode and - command settings as Open to LAN. Hosting through a code *is* opening to LAN, plus the tunnel. -- **Realms invite codes** (`com.mojang.realmsclient.dto.InviteCode`, `RealmsInviteCodesScreen`): - codes that add a player to a Realm, a server Mojang hosts. They need accounts and Mojang's - service; nothing in the client tunnels a local world. +1. listens on its **direct port**, TCP 25580 by default (the same port every time, so a port forwarded + by hand keeps working; another one if it is taken; `HORIZON_FRIENDS_PORT` picks it); +2. collects this computer's addresses: the LAN address, VPN addresses (Tailscale's `100.x`, ZeroTier + and others), IPv6. Container and VM bridges are left out; +3. asks the home router to open the direct port for an hour, renewed every half hour and deleted when + sharing stops: **PCP** (RFC 6887), then **NAT-PMP** (RFC 6886) on the default gateway, then **UPnP + IGD** (SSDP discovery, SOAP `AddPortMapping`). A router that only takes permanent UPnP mappings gets + one, deleted on stop the same way; +4. asks public **STUN** servers for its public IPv4 address (only the address: STUN sees UDP, the game + is TCP). Defaults: `stun.cloudflare.com:3478` and `stun.l.google.com:19302`, two independent + operators of free STUN at a global scale, so one outage doesn't break discovery. `HORIZON_STUN_SERVERS` + (a comma list, or `none`) changes them; +5. builds the **invite code**: the endpoints (the router mapping, the public address on the direct + port, the interface addresses) and a fresh 80-bit secret, in base32 with a checksum. -So the code, the relay and the screens are Horizon's own, in the launcher's design language (the -existing `ui_theme` widgets, so the redesign in flight restyles them with everything else). +**Joining.** The guest's game dials every endpoint in the code at once. The first that answers as a +Horizon host gets the handshake, the others are dropped. On the same LAN, over a VPN, with IPv6, with a +router that opened the port, or with a forwarded port, that's it: no server took part. + +**Codes.** Crockford base32 (`0-9 A-Z` without `I L O U`; input ignores case, spaces and dashes and reads +`O` as `0`, `I`/`L` as `1`) in groups of five, with a 16-bit checksum so a typo is caught before +anything is dialled: + +- a home with a router mapping, a LAN address and a tailnet address: 52 symbols + (`2A7KQ-M3XPD-…`, 11 groups); with IPv6 too, 79; +- byte layout: version, secret (10 bytes), direct port, endpoints (tag, address, own port when it + differs), an optional relay entry, the first two bytes of SHA-256 of all that. + +A code lives as long as the host shares: stopping, closing the world or quitting ends it (the direct +port closes, the router mapping is deleted). Sharing again makes a new secret. + +## When friends can't reach the host + +The host's panel says what to expect, from what the game found: + +| What the game found | What the host reads | +| --- | --- | +| The router opened the port | "Friends anywhere can join: your router opened the port with UPnP (203.0.113.5:25580)." | +| This computer has a public address | "Friends anywhere can join … (TCP port 25580 must not be blocked by a firewall)." | +| No router answered | "Friends on your network or VPN can join. For friends on the internet: turn on UPnP on your router, or forward TCP port 25580 to 192.168.1.20, or use a relay, or a VPN such as Tailscale or ZeroTier (the code already holds your VPN address)." | +| The router is behind another NAT (the router's public side is a private or `100.64/10` address, or STUN sees another address) | "… your router is itself behind another NAT (your provider's carrier-grade NAT, CGNAT, or a second router), so opening its port isn't enough. Use a relay or a VPN such as Tailscale or ZeroTier." | + +The code always holds the public address on the direct port when STUN found it, so **forwarding the +port by hand** works without a new code. A guest that can't reach any endpoint is told: "Couldn't reach +your friend's game. Ask them to read the note under their code: they may need UPnP on their router, a +forwarded port, a relay or a VPN." + +## Encryption + +The code's secret never leaves the code. Every session runs a password-authenticated key exchange +(SPAKE2 over Ed25519, RustCrypto's `spake2`) keyed by it and bound to a session number, then derives +per-direction ChaCha20-Poly1305 keys with HKDF-SHA256 from the exchange and two fresh randoms, with a +key confirmation first. A wrong code, a changed byte, a replayed or reordered frame ends the stream. +The same exchange runs over relayed sessions, where it matters most: the relay gets nothing to test +guesses against offline. + +## Privacy: who sees what + +- **Friends with the code** see the host's addresses in it (LAN, VPN, public), as with any server + address. A guest's address is seen by the host, as on any server. +- **STUN servers** see the host's public IP address and a 20-byte request, like any website it visits. + Turn them off with `HORIZON_STUN_SERVERS=none` (the code then lacks the public address unless the + router reported it). +- **The router** gets a port mapping named "Horizon (play with friends)". +- **A relay** (only if one is configured) sees the IP addresses of the host and the guests, the short + code's first half, when sessions start and end and the size of encrypted frames. It can't see the + secret, the key or the game (names, chat, the world). It logs counts every five minutes, nothing else. +- **Horizon** sees nothing: there is no Horizon service. ## Identity -Like LAN today: offline mode. A guest joins with the name their game uses; the server gives them the -offline UUID for it; the host's own profile is reserved so nobody can take the host's name. Online-mode -identity (the host checks guests against Mojang's session servers when both are signed in to a -Microsoft account) can come later on top of the same tunnel, since the tunnel carries the login -packets unchanged. Because every tunnelled guest reaches the integrated server from `127.0.0.1`, -`/ban-ip` has nothing useful to act on for them (the LAN host has no such command anyway). +Like LAN: offline mode. A guest joins with the name their game uses; the host's own profile is reserved. +Online-mode checks against Mojang's session servers can come later on top of the same tunnel. Every +tunnelled guest reaches the integrated server from `127.0.0.1`. -## Codes +## Relays (optional) -A code is 8 symbols of Crockford base32 (`0-9 A-Z` without `I L O U`), shown as two groups of four: -`K7QM-3XPD`. Input ignores case, spaces and dashes, and reads `O` as `0` and `I`/`L` as `1`. +For networks nothing can reach (CGNAT on both sides, no VPN), a **relay** carries the session: one small +binary, `horizon-relay`, that anyone can run on their own PC, a VPS, a Raspberry Pi or a free tier. +There is no default relay. With one configured: -- The first four symbols are the **nameplate** (20 bits). The relay allocates it at random among the - free ones when the host registers, and uses it to find the host. It is the only part the relay sees. -- The last four are the **secret** (20 bits). The host's game draws it from the OS random generator - and never sends it anywhere. It is the password of the key exchange below. +- the host also registers there and gets a **short code** (`K7QM-3XPD`: a 4-symbol nameplate the relay + allocates, a 4-symbol secret it never sees), and the full code names the relay and carries the short + code, so guests with the full code fall back to the relay without any setting; +- guests with only the short code need the relay's address (on the Join a friend page); +- a relayed session first races direct connections both ways (candidates exchanged encrypted, TCP + simultaneous open from the direct port), and stays on the relay only if none connects. -A code lives as long as the host keeps sharing: when the host stops sharing, closes the world or loses -its connection to the relay, the nameplate is freed (the relay keeps a bare "ended" mark for 15 minutes -so a guest gets "this invite has ended" rather than "unknown code"). +Configuring it: the **Relay** field on the Join a friend page (saved to `horizon.txt` as +`friendsRelay:host:port`, used for hosting too), or `HORIZON_RELAY_URL`. -Guessing: to join a world uninvited, someone needs an active nameplate (the relay limits resolution -attempts per address and in total, see below) and then the secret, for which each attempt is one online run of the -key exchange (20 bits: one chance in a million). After 5 failed exchanges the host's game retires the -code and shows a new one, so a nameplate found by luck is worth at most 5 tries. +### Running your own relay -## Encryption: SPAKE2, then ChaCha20-Poly1305 +The relay needs one TCP port reachable by your friends and almost nothing else (a few MB of memory, no +disk). Relayed players cost what the game sends: a join is a few MB, play is about 10–50 KB/s, flying +over new terrain up to a few hundred KB/s (capped per session). -The relay must not be able to read or change game traffic, but all the two ends share is a short -code, and the relay sees part of it. A key derived directly from the code would fall to an offline -search in seconds, so the ends run a **password-authenticated key exchange** (SPAKE2 over Ed25519, -the RustCrypto `spake2` crate, the construction magic-wormhole uses for the same problem): +**From a release or source** (any OS with Rust): -1. Over the relayed connection, each end sends one SPAKE2 message built from the secret and bound to - the nameplate and the session number. Each derives a 32-byte key `K`. With different secrets the - keys differ, and nothing in the messages helps an offline guess: a dishonest relay gets exactly one - guess per session, and a wrong guess shows up as a failed join. -2. Every stream that carries the session (the relayed one, and each direct connection tried) then - exchanges two fresh 16-byte randoms in the clear and derives its own keys with HKDF-SHA256 from `K`, - the randoms and the direction. Frames are ChaCha20-Poly1305 with a per-direction counter nonce, at - most 16 KiB of payload each. The first frame each way is a key confirmation: a wrong code or a - tampered byte ends the stream. +``` +cargo build --release -p horizon-relay +PORT=7000 ./target/release/horizon-relay +``` -What the relay **can** see: the nameplate, the IP addresses and ports of the host and of each guest -(it is their TCP peer), when sessions start and end, and the size and timing of the encrypted frames -of relayed sessions. What it **can't**: the secret half of the code, the key, the game bytes (names, -chat, positions, the world), or the candidate addresses the ends exchange (they travel encrypted). +**With Docker** (build context: the repository root): -The relay connection itself is plain TCP (a TLS front would hide the nameplate from the network -path, but adds certificates to a service that holds nothing worth hiding). +``` +docker build -f crates/horizon-relay/Dockerfile -t horizon-relay . +docker run -d --restart unless-stopped -p 7000:7000 horizon-relay +``` -## Connecting: direct first, then the relay +**As a service** (Linux, including a Raspberry Pi): copy the binary to `/usr/local/bin/horizon-relay`, +`crates/horizon-relay/horizon-relay.service` to `/etc/systemd/system/`, then +`systemctl enable --now horizon-relay`. -Every session starts through the relay, so the key exchange always has a path. Then: +Then forward TCP port 7000 on your router to that machine (or run it on a VPS with a public address), +check `curl http://
:7000/health` from outside, and give friends `
:7000`. `GET /whoami` +shows the address the relay sees for you: behind a proxy that hides client addresses (some hosting +platforms' TCP proxies), set `RELAY_PER_ADDRESS_LIMITS=0`. Run **one** instance per address: codes live +in its memory. -1. Over the encrypted relayed stream, the ends swap their **candidates**: the local addresses they can - be reached on (found by asking the OS which source address it would use toward the relay, toward - the public IPv4 internet and toward the public IPv6 internet; this finds the LAN address, a global - IPv6 address and a tailnet address when there is one) plus the address the relay saw them come - from (their public, reflexive address), all with the port of their **direct socket**. The guest's - join connection and the host's attach connection leave from that port, so the address the relay - saw is the NAT's mapping of it. (The host's long-lived control connection uses another port, so - it never holds the direct port's connection to the relay.) -2. Both ends then dial every candidate of the other at once, for up to 3 seconds, retrying every 250 - ms, from their direct socket's port (`SO_REUSEADDR`/`SO_REUSEPORT`, so the same port also listens and - carried the relay connection). Dialling from both sides at once is **TCP simultaneous open**: each - side's outgoing SYN opens its own NAT for the other's, which gets through NATs that map a local port - to the same public port for every destination (most home routers) and stateful firewalls (IPv6). - On the same LAN, on a tailnet, with IPv6 or with a forwarded port the plain dial wins first. -3. Each direct stream that connects is authenticated with the session key as above. The guest keeps - the first one that passes, says so over the relayed stream, and both ends close the rest. If none - passes in time, the session stays on the relayed stream: the relay copies the encrypted bytes. +Settings, all optional: -Why TCP and not UDP hole punching with QUIC: punching UDP succeeds more often across NATs (published -measurements put it around 80% against 60–65% for TCP), but it needs a reliable transport over UDP, -which means QUIC (an async runtime and a QUIC/TLS stack in the game) for a stream that then still needs -the same end-to-end layer. The relay fallback makes every session connect either way; the direct path -only saves latency and relay bandwidth. The tunnel takes any byte stream (`Read + Write`), so a QUIC -transport can be added later beside the TCP one without touching the rest. +| Variable | Default | | +| --- | --- | --- | +| `PORT` | 7000 | the TCP port (also answers `GET /health` and `GET /whoami`) | +| `RELAY_BIND` | all addresses | listen on one address only (e.g. a tailnet address) | +| `RELAY_MAX_HOSTS` | 1000 | short codes at once | +| `RELAY_MAX_BRIDGES` | 200 | relayed streams at once | +| `RELAY_MAX_PENDING_PER_HOST` | 8 | guests joining one host at the same time | +| `RELAY_SESSION_KBPS` | 1024 | KiB/s each way per relayed stream | +| `RELAY_TOTAL_MBPS` | 100 | Mbit/s for everything relayed | +| `RELAY_GLOBAL_UNKNOWN_PER_MIN` | 120 | unknown short codes a minute, all clients together | +| `RELAY_PER_ADDRESS_LIMITS` | 1 | per-address rate limits (see below) | +| `RELAY_PROXY_PROTOCOL` | 0 | read the client address from a PROXY protocol v1 line | -The reflexive candidate is only as good as the relay's view of addresses: if the hosting platform's -TCP proxy hides client addresses (Railway's documentation doesn't say), the relay sees the proxy's -and that candidate simply never connects; the LAN, IPv6, tailnet and forwarded-port paths still work. -`GET /whoami` on the relay shows what it sees, to check after deploying. +Fixed limits: per client address (IPv6 by /64), 6 host registrations a minute (burst 3), 12 joins a +minute (burst 6), 5 unknown short codes in 10 minutes block joins for 10 minutes; a relayed stream idle +for 120 s is closed (the game's keep-alive sends every 15 s); a first line must arrive within 10 s; +hosts answer pings within 60 s; five wrong secrets on a short code and the host retires it for a new one. -`HORIZON_FRIENDS_PATH=relay` skips the direct attempts (players who don't want to share their address -with the other end, and the tests); `=direct` refuses the relay fallback (tests). +### The relay protocol -## The relay protocol - -One TCP port. The first line of each connection is a JSON object (at most 4 KiB, within 10 seconds); -a connection whose first bytes are `GET ` gets an HTTP answer instead (`GET /health`, for the hosting -platform's health check), so one port serves both. +One TCP port. The first line of each connection is a JSON object (at most 4 KiB, within 10 seconds); a +connection starting with `GET ` gets an HTTP answer instead. | From | Line | Meaning | | --- | --- | --- | -| host | `{"op":"host","v":1,"protocol":P,"game":"26.3"}` | register; the relay answers `{"op":"registered","nameplate":"K7QM","token":T,"observed":"ip:port"}` | -| guest | `{"op":"join","v":1,"nameplate":"K7QM","protocol":P,"game":"26.3"}` | resolve; the relay announces the session to the host, waits for its attach, then answers `{"op":"bridged","session":S,"observed":…}` or `{"op":"error","code":…}` | -| relay → host | `{"op":"join","session":S}` | a guest wants in: open a new connection and attach | -| host | `{"op":"attach","v":1,"session":S,"token":T}` (new connection) | the relay pairs it with the guest's connection, answers `{"op":"bridged","session":S,"observed":…}` to both, then copies bytes | -| relay ↔ host | `{"op":"ping"}` / `{"op":"pong"}` | every 20 s; a host silent for 60 s is dropped and its code ends | +| host | `{"op":"host","v":1,"protocol":P,"game":"26.3"}` | register; answer `{"op":"registered","nameplate":"K7QM","token":T,"observed":"ip:port"}` | +| guest | `{"op":"join","v":1,"nameplate":"K7QM","protocol":P,"game":"26.3"}` | resolve; the relay announces the session to the host and waits for its attach, then answers `{"op":"bridged","session":S,"observed":…}` or `{"op":"error","code":…}` | +| relay → host | `{"op":"join","session":S}` | open a new connection and attach | +| host | `{"op":"attach","v":1,"session":S,"token":T}` | paired with the guest; both get `bridged`, then raw bytes | +| relay ↔ host | `{"op":"ping"}` / `{"op":"pong"}` | every 20 s | -Error codes the guest can get: `unknown_code`, `ended` (the host stopped sharing), `version_mismatch` -(with the host's game version: the relay compares protocol numbers, so a guest on another Minecraft -version is told before anything else happens), `host_unreachable` (the host didn't attach within 10 -seconds), `full` (the host has 8 guests connecting or the relay is at capacity), `rate_limited`, -`bad_request`. +Errors: `unknown_code`, `ended` (kept 15 minutes after a host leaves), `version_mismatch` (with the +host's version), `host_unreachable`, `full`, `rate_limited`, `bad_request`. -After `bridged`, the stream is the session: the SPAKE2 messages, then the encrypted frames. +## Troubleshooting -## Limits - -All set by environment variables on the relay (defaults in brackets): - -- `RELAY_MAX_HOSTS` [1000] codes at once; `RELAY_MAX_BRIDGES` [200] relayed streams at once; - `RELAY_MAX_PENDING_PER_HOST` [8] guests joining one host at the same time. -- Per client address (IPv6 grouped by /64): 6 host registrations a minute (burst 3); 12 joins a minute - (burst 6); 5 unknown codes in 10 minutes block joins from that address for 10 minutes. - `RELAY_PER_ADDRESS_LIMITS=0` turns these off for a proxy that shows every client as one address; - `RELAY_PROXY_PROTOCOL=1` reads the client's address from a PROXY protocol v1 line instead. -- For everyone together: `RELAY_GLOBAL_UNKNOWN_PER_MIN` [120] unknown codes a minute (burst 30); past - it, joins are refused as rate limited before the code is looked up, so a refusal says nothing about - whether a code exists. Even if one attacker had the whole budget: with 1000 worlds shared, an active - nameplate turns up about every 9 minutes, and each is worth 5 one-in-a-million tries before its - code is retired, so a break-in takes on the order of thousands of years. -- `RELAY_SESSION_KBPS` [1024] KiB/s each way per relayed stream; `RELAY_TOTAL_MBPS` [100] Mbit/s for - the whole relay; a relayed stream with no byte either way for 120 s is closed (the game's keep-alive - sends one every 15 s, so only dead streams idle). -- A first line must arrive within 10 s; hosts answer pings within 60 s. - -## Privacy - -No accounts. The relay keeps only what a live session needs, in memory: active nameplates and the -host connection behind each, pending sessions, rate-limit counters per address (forgotten after 10 -minutes). It logs **counts** every 5 minutes (hosts, relayed streams, joins, unknown codes, -rate-limited requests, relayed bytes) and nothing else: no addresses, no codes, no names. -`/health` answers counts too. - -A direct connection shows each player's IP address to the other, as a LAN game or a server address -would. `HORIZON_FRIENDS_PATH=relay` avoids it at the cost of relay bandwidth. - -## What players see - -Host (pause menu, Horizon style): **Invite friends** beside Open to LAN. It opens the world to the -network if it isn't (same settings as Open to LAN), registers with the relay and shows the code with a -**Copy** button, the friends connected, and **Stop sharing**. Stopping sharing ends the code; it leaves -Open to LAN as it was before sharing started. - -Guest: **Join a friend** on the multiplayer screen (a code field) and a **Join a friend** row on the -launcher's Play page, which starts the game straight into the join. Errors are plain: "No world uses -this code", "This invite has ended", "The code doesn't match (check the last four characters)", -"Your friend's game didn't answer", "Your friend plays Minecraft X; you have Y". - -Configuration: `HORIZON_RELAY_URL=host:port` at run time, else the address compiled in from the same -variable at build time. **Empty by default**: until a relay is deployed, the buttons say "Not available -yet" and do nothing else. - -## Failure modes - -| Failure | What happens | -| --- | --- | -| Relay down or not configured | Host: "Couldn't reach the invite service" (the world stays open to LAN if it was). Guest: same message. | -| Host closes the world / quits / loses the network | The relay drops the code ("ended"); connected guests see the usual disconnect. | -| Relay restarts | Codes end; hosts reconnect and get a **new** code (shown in the panel). Direct sessions keep running; relayed ones drop. | -| Direct attempt half works (one SYN through) | Only authenticated streams count; the rest are closed after 3 s. | -| A guest's NAT blocks everything but the relay | Relayed, at most `RELAY_SESSION_KBPS`. | -| Wrong secret | That guest gets "The code doesn't match"; after 5, the host gets a new code. | -| Guest on another version | Refused by the relay before any key exchange, with both versions in the message. | - -## Deploying the relay - -**Needs Ludovic**: nothing is deployed yet, and the game's default relay address is empty. - -The relay is one static binary, `horizon-relay`, with no disk state; it fits Railway's smallest -instance. Files: `crates/horizon-relay/Dockerfile` (build context: the repository root) and -`crates/horizon-relay/railway.toml`. - -1. New Railway service from the `ludovic111/horizon` repository; in its settings set the config file - path to `crates/horizon-relay/railway.toml` (it selects the Dockerfile and the health check). -2. Variables: `PORT=7000` (the relay listens on `$PORT`); optionally the limits above. **One - replica only** (`numReplicas = 1` in `railway.toml`): codes live in the relay's memory, and the - TCP proxy spreads connections over replicas at random. -3. Networking: add a **TCP proxy** to port 7000. Railway gives an address like - `example.proxy.rlwy.net:12345`. (An HTTP domain is not needed; the health check reaches the service - directly on `$PORT`.) -4. Health check: `GET /health` on `$PORT` (in `railway.toml`), answers `200` with counts. -5. Check addresses: `curl http:///whoami` from a home connection. If it shows your - public address, keep the defaults. If it shows a Railway address, set `RELAY_PER_ADDRESS_LIMITS=0` - (the global limits remain) and expect fewer direct connections across NATs. -6. Point the game at it: set the repository variable `HORIZON_RELAY_URL` to the TCP proxy address so - release builds compile it in, or test first with `HORIZON_RELAY_URL=… horizon-client`. - -Cost and bandwidth: the relay idles at a few MB of memory and no CPU. Sessions that connect directly -cost a few kilobytes of relay traffic each. A relayed player costs what the game sends: joining (the -chunks around the spawn) is a few MB, playing is roughly 10–50 KB/s, flying over new terrain up to a -few hundred KB/s (capped at `RELAY_SESSION_KBPS`). A relayed player-hour is therefore around 50–200 MB -of egress; 100 relayed player-hours a month is 5–20 GB. Check Railway's current egress, memory and -CPU prices against that; `RELAY_TOTAL_MBPS` bounds the worst case. +- **"Friends on your network or VPN can join"**: turn on UPnP (sometimes "UPnP IGD" or "NAT-PMP") in + the router's settings and share again; or forward TCP port 25580 (the panel shows the port and your + LAN address) to this computer; or install Tailscale or ZeroTier on both computers (the code already + holds the VPN address); or run a relay. +- **CGNAT / a second router**: port forwarding on your own router can't help. Use a VPN or a relay (on a + machine with a public address, e.g. a VPS). +- **"Couldn't reach your friend's game"** (guest): the host's note under the code says why. A firewall + on the host computer can also block the direct port: allow `horizon-client` on private and public + networks. +- **"The code has a typo"**: copy it again; codes are only letters and digits in groups of five. +- **"This short code works through your friend's relay"**: enter the relay's address under Join a + friend, or ask for the full code. +- **"Your friend plays Minecraft X; you have Y"**: both need the same game version. ## Testing -- Rust unit tests: codes (alphabet, normalisation, parsing), frames and the key exchange (wrong secret, - tampering, nonce order), rate limiters and bandwidth buckets. -- `crates/horizon-relay/tests/tunnel.rs`: a relay, a host tunnel in front of an echo server standing in - for the integrated server, and guest tunnels, in one process: direct path, forced relay path, wrong - secret (and the 5-strike new code), unknown and ended codes, version mismatch, rate limits. -- `tools/test_friends.py`: a relay, a host Horizon with an integrated world and a guest Horizon, through - the direct path and the forced relay path; chat, movement and a placed block seen by both. -- Two machines over the tailnet (relay on one, host and guest on two others). - -## Pull requests - -1. `horizon-friends` (codes, wire, key exchange, tunnel ends) and `horizon-relay` (the service, its - Dockerfile and Railway config) with their tests. Nothing player-facing. -2. Host: Invite friends in the pause menu, `horizon-ctl friends …`. -3. Guest: Join a friend in game and in the launcher, `tools/test_friends.py`. +- Unit tests (`horizon-friends`): code format (round trips, every single-symbol typo caught, versions), + STUN against a mock server, PCP / NAT-PMP against a mock router (map, renew, delete; NAT-PMP when PCP + is unsupported), UPnP against a mock IGD (description, chunked replies, `AddPortMapping`, permanent-only + leases (725), taken ports (718), `DeletePortMapping`), the verdicts and endpoint order, gateway + parsing for Linux, macOS and Windows, the key exchange and frames (wrong secret, tampering), the direct + race. +- `crates/horizon-relay/tests/tunnel.rs`: the code alone with no server (1 MiB, two guests at once); a + self-hosted relay with the short code (relayed, then its direct race); dead endpoints falling back to + the relay named in the code; wrong secrets (full and short codes, the short code retired after five); + unknown and ended codes, version mismatch, rate limits, bandwidth caps, `/health`. +- `tools/test_friends.py`: real games: a host Horizon sharing a world and a guest Horizon joining over + plain LAN (`--baseline`), with the **code alone** (no relay running), and through a **locally run + relay** with the short code; chat, movement and blocks both ways, then the ended invite. +- Two machines over a tailnet with the code alone (`--role host` on one, `--role guest --code …` on the + other).