Phase 4: Punching Through NATs

2026-02-15

Most people's devices sit behind a NAT — a network address translator that lets -them reach the internet but prevents incoming connections. For a P2P network, -this is an existential problem: if two nodes behind NATs can't talk to each -other, the network fragments. Phase 4 continues with a full NAT traversal stack: -STUN-based discovery, coordinated hole punching, and relay fallback.

The approach follows the same pattern as most battle-tested P2P systems (WebRTC, -BitTorrent, IPFS): try the cheapest option first, escalate only when necessary. -Direct connectivity costs nothing. Hole punching costs a few coordinated -packets. Relaying costs sustained bandwidth from a third party. Tesseras tries -them in that order.

What was built

NatType classification (tesseras-core/src/network.rs) — A new NatType -enum (Public, Cone, Symmetric, Unknown) added to the core domain layer. This -type is shared across the entire stack: the STUN client writes it, the DHT -advertises it in Pong messages, and the punch coordinator reads it to decide -whether hole punching is even worth attempting (Cone-to-Cone works ~80% of the -time; Symmetric-to-Symmetric almost never works).

STUN client (tesseras-net/src/stun.rs) — A minimal STUN implementation -(RFC 5389 Binding Request/Response) that discovers a node's external address. -The codec encodes 20-byte binding requests with a random transaction ID and -decodes XOR-MAPPED-ADDRESS responses. The discover_nat() function queries -multiple STUN servers in parallel (Google, Cloudflare by default), compares the -mapped addresses, and classifies the NAT type:

Same IP and port from all servers → Public (no NAT)
Same mapped address from all servers → Cone (hole punching works)
Different mapped addresses → Symmetric (hole punching unreliable)
No responses → Unknown

Retries with exponential backoff and configurable timeouts. 12 tests covering -codec roundtrips, all classification paths, and async loopback queries.

Signed punch coordination (tesseras-net/src/punch.rs) — Ed25519 signing -and verification for PunchIntro, RelayRequest, and RelayMigrate messages. -Every introduction is signed by the initiator with a 30-second timestamp window, -preventing reflection attacks (where an attacker replays an old introduction to -redirect traffic). The payload format is target || external_addr || timestamp -— changing any field invalidates the signature. 6 unit tests plus 3 -property-based tests with proptest (arbitrary node IDs, ports, and session -tokens).

Relay session manager (tesseras-net/src/relay.rs) — Manages transparent -UDP relay sessions between NATed peers. Each session has a random 16-byte token; -peers prefix their packets with the token, the relay strips it and forwards. -Features:

Bidirectional forwarding (A→R→B and B→R→A)
Rate limiting: 256 KB/s for reciprocal peers, 64 KB/s for non-reciprocal
10-minute maximum duration for bootstrap (non-reciprocal) sessions
Address migration: when a peer's IP changes (Wi-Fi to cellular), a signed -RelayMigrate updates the session without tearing it down
Idle cleanup with configurable timeout
8 unit tests plus 2 property-based tests

DHT message extensions (tesseras-dht/src/message.rs) — Seven new message -variants added to the DHT protocol:

- - - - - - - - -

Message	Purpose
`PunchIntro`	"I want to connect to node X, here's my signed external address"
`PunchRequest`	Introducer forwards the request to the target
`PunchReady`	Target confirms readiness, sends its external address
`RelayRequest`	"Create a relay session to node X"
`RelayOffer`	Relay responds with its address and session token
`RelayClose`	Tear down a relay session
`RelayMigrate`	Update session after network change

The Pong message was extended with NAT metadata: nat_type, -relay_slots_available, and relay_bandwidth_used_kbps. All new fields use -#[serde(default)] for backward compatibility — old nodes ignore what they -don't recognize, new nodes fall back to defaults. 9 new serialization roundtrip -tests.

NatHandler trait and dispatch (tesseras-dht/src/engine.rs) — A new -NatHandler async trait (5 methods) injected into the DHT engine, following the -same dependency injection pattern as the existing ReplicationHandler. The -engine's message dispatch loop now routes all punch/relay messages to the -handler. This keeps the DHT engine protocol-agnostic while allowing the NAT -traversal logic to live in tesseras-net.

Mobile reconnection types (tesseras-embedded/src/reconnect.rs) — A -three-phase reconnection state machine for mobile devices:

QuicMigration (0-2s) — try QUIC connection migration for all active peers
ReStun (2-5s) — re-discover external address via STUN
ReEstablish (5-10s) — reconnect peers that migration couldn't save

Peers are reconnected in priority order: bootstrap nodes first, then nodes -holding our fragments, then nodes whose fragments we hold, then general DHT -neighbors. A new NetworkChanged event variant was added to the FFI event -stream so the Flutter app can show reconnection progress.

Daemon NAT configuration (tesd/src/config.rs) — A new [nat] section in -the TOML config with STUN server list, relay toggle, max relay sessions, -bandwidth limits (reciprocal vs bootstrap), and idle timeout. All fields have -sensible defaults; relay is disabled by default.

Prometheus metrics (tesseras-net/src/metrics.rs) — 16 metrics across four -subsystems:

STUN: requests, failures, latency histogram
Punch: attempts/successes/failures (by NAT type pair), latency histogram
Relay: active sessions, total sessions, bytes forwarded, idle timeouts, -rate limit hits
Reconnect: network changes, attempts/successes by phase, duration -histogram

6 tests verifying registration, increment, label cardinality, and -double-registration detection.

Integration tests — Two end-to-end tests using MemTransport (in-memory -simulated network):

punch_integration.rs — Full 3-node hole-punch flow: A sends signed -PunchIntro to introducer I, I verifies and forwards PunchRequest to B, B -verifies the original signature and sends PunchReady back, A and B exchange -messages directly. Also tests that a bad signature is correctly rejected.
relay_integration.rs — Full 3-node relay flow: A requests relay from R, R -creates session and sends RelayOffer to both peers, A and B exchange -token-prefixed packets through R, A migrates to a new address mid-session, A -closes the session, and the test verifies the session is torn down and further -forwarding fails.

Property tests — 7 proptest-based tests covering: signature round-trips for -all three signed message types (arbitrary node IDs, ports, tokens), NAT -classification determinism (same inputs always produce same output), STUN -binding request validity, session token uniqueness, and relay rejection of -too-short packets.

Justfile targets — just test-nat runs all NAT traversal tests across -tesseras-net and tesseras-dht. just test-chaos is a placeholder for future -Docker Compose chaos tests with tc netem.

Architecture decisions

STUN over TURN: we implement STUN (discovery) and custom relay rather than -full TURN. TURN requires authenticated allocation and is designed for media -relay; our relay is simpler — token-prefixed UDP forwarding with rate limits. -This keeps the protocol minimal and avoids depending on external TURN servers.
Signatures on introductions: every PunchIntro is signed by the -initiator. Without this, an attacker could send forged introductions to -redirect a node's hole-punch attempts to an attacker-controlled address (a -reflection attack). The 30-second timestamp window limits replay.
Reciprocal bandwidth tiers: relay nodes give 4x more bandwidth (256 vs 64 -KB/s) to peers with good reciprocity scores. This incentivizes nodes to store -fragments for others — if you contribute, you get better relay service when -you need it.
Backward-compatible Pong extension: new NAT fields in Pong use -#[serde(default)] and Option<T>. Old nodes that don't understand these -fields simply skip them during deserialization. No protocol version bump -needed.
NatHandler as async trait: the NAT traversal logic is injected into the -DHT engine via a trait, just like ReplicationHandler. This keeps the DHT -engine focused on routing and peer management, and allows the NAT -implementation to be swapped or disabled without touching core DHT code.

What comes next

Phase 4 continued — performance tuning (connection pooling, fragment -caching, SQLite WAL), security audits, institutional node onboarding, OS -packaging
Phase 5: Exploration and Culture — public tessera browser by -era/location/theme/language, institutional curation, genealogy integration, -physical media export (M-DISC, microfilm, acid-free paper with QR)

With NAT traversal, Tesseras can connect nodes regardless of their network -topology. Public nodes talk directly. Cone-NATed nodes punch through with an -introducer's help. Symmetric-NATed or firewalled nodes relay through willing -peers. The network adapts to the real world, where most devices are behind a NAT -and network conditions change constantly.

- -