Initial commit

2026-04-18 20:02:48 -05:00 · 2026-04-18 20:02:48 -05:00 · bde475921a
commit bde475921a
32 changed files with 3650 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1 @@
 /target
--- a/.projectile
+++ b/.projectile
@ -0,0 +1 @@
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,81 @@
 # Agents Guide: Whalescale
 ## Architecture: Integrated Plane
 Whalescale is a unified agent — the control plane and data plane share the same process, the same encryption sessions, and the same UDP sockets. **There is no separate WireGuard process.** All logic — discovery, NAT traversal, encryption, multipath scheduling, and TUN management — lives in one program.
 ```
 ┌──────────────────────────────────────────────┐
 │              TUN Device (IP packets)          │
 ├──────────────────────────────────────────────┤
 │         Reordering Buffer                     │
 ├──────────────────────────────────────────────┤
 │          Path Scheduler                       │
 ├───────────┬───────────┬──────────────────────┤
 │   Path 1  │   Path 2  │      Path N          │
 │  5G/UDP   │  WiFi/UDP │    IPv6/UDP          │
 ├───────────┴───────────┴──────────────────────┤
 │       Noise_IK Session Manager                │
 ├──────────────────────────────────────────────┤
 │       Whalescale Agent (single process)       │
 └──────────────────────────────────────────────┘
 ```
 **Never split logic across processes or re-introduce a WireGuard dependency.** The unified architecture exists specifically to avoid the coordination conflicts that arise when the control plane and data plane are separate.
 ## Core Technical Constraints
 * **Identity:** Uses Ed25519 keys. The Whalescale Node ID **is** the Ed25519 public key. No separate WireGuard key.
 * **Handshake:** Noise_IK, implemented in userspace via an established Rust Noise library (not the WireGuard kernel module).
 * **Discovery:** No DHT. Discovery relies on **Manual Bootstrap** → **Anchors** → **Gossip** → **LKG Cache**.
 * **Connectivity:** Best-effort UDP hole punching. Symmetric ↔ Symmetric pairs communicate via anchor relay (encrypted forwarding, not TURN).
 * **Multipath:** A single peer session can use multiple network interfaces simultaneously (e.g., 5G + WiFi) with a reordering buffer.
 * **IPv6:** Preferred transport when available. Eliminates NAT entirely. Always attempt IPv6 paths first.
 * **Anchors:** First-class concept. At least one anchor (cone NAT or public IP, stable address) is required for the network to support mobile/symmetric-NAT nodes. Recommend at least two anchors on different ISPs.
 * **No port prediction/sweeping:** Categorically ineffective against CGNAT. Do not re-implement.
 ## What Whalescale Is NOT
 * **Not a WireGuard wrapper.** Whalescale owns its data plane.
 * **Not a DHT.** No Kademlia, no distributed hash tables.
 * **Not a TURN/STUN service.** Anchor relay is packet forwarding through existing encrypted tunnels, not dedicated relay infrastructure.
 * **Not designed for internet-scale.** The target is trusted, known-peer networks (tens to low hundreds of nodes).
 ## Module Structure (Target)
 Rust workspace with the following crates:
 * `crates/whalescale-agent/` — Main entry point, event loop, configuration (binary crate)
 * `crates/whalescale-session/` — Noise_IK handshake, session state, key rotation
 * `crates/whalescale-transport/` — UDP socket management, packet framing, send/receive
 * `crates/whalescale-path/` — Path discovery, scheduling, health monitoring, reordering buffer
 * `crates/whalescale-multipath/` — Multipath scheduler (weighted round-robin), bandwidth estimation, feedback loop, reordering buffer logic, test bench framework
 * `crates/whalescale-gossip/` — Gossip protocol, LKG cache, anti-entropy, conflict resolution
 * `crates/whalescale-nat/` — NAT type detection, hole punching, UPnP/NAT-PMP/PCP
 * `crates/whalescale-anchor/` — Anchor management, relay forwarding, mutual keepalive
 * `crates/whalescale-tun/` — TUN device read/write, IP packet routing
 * `crates/whalescale-bootstrap/` — Pre-session discovery protocol, manual bootstrap
 * `crates/whalescale-crypto/` — Ed25519 key management, Noise library integration (thin wrapper)
 * `crates/whalescale-types/` — Shared types, constants, and protocol definitions
 ## Development Context
 * **Language:** Rust.
 * **Module:** `eganshub.net/whalescale`.
 * **Critical Files:**
  * `DESIGN.md`: The primary source of truth for architectural decisions.
  * `MULTIPATH.md`: Full specification for the multipath transport subsystem.
  * `ANTI_PATTERN.md`: Crucial for avoiding regressive design (e.g., trying to add a DHT, re-introducing WireGuard, or implementing port prediction).
 ## Implementation Phases
 | Phase | Scope |
 |-------|-------|
 | 1 | Noise_IK session, single path, single peer, TUN integration |
 | 2 | Multipath transport — weighted round-robin scheduler, reordering buffer, path management, feedback loop, bandwidth estimation |
 | 3 | Multi-peer session management, LKG cache, gossip |
 | 4 | NAT traversal (hole punching, UPnP/PCP, anchor signaling) |
 | 5 | LAN discovery, IPv6 preference, anchor relay |
 | 6 | Adaptive path scheduling, test bench framework, scheduler comparison |
 **Phase 2 is the novel work.** The multipath transport has significant open questions (inner TCP interaction, reordering depth tuning, scheduler optimality) that require empirical validation. See `MULTIPATH.md` §11 for the test bench specification.
--- a/ANTI_PATTERN.md
+++ b/ANTI_PATTERN.md
@ -0,0 +1,121 @@
 # Whalescale: Anti-Pattern & Risk Document
 This document outlines the architectural boundaries of the Whalescale project. It identifies approaches that have been explicitly rejected, potential design pitfalls, and the non-obvious risks inherent in a peer-to-peer VPN with best-effort NAT traversal.
 ## 1. Rejected Approaches
 ### 1.1 Centralized Discovery (DHT/Kademlia)
 * **Why Rejected:** Whalescale targets a high-trust, known-client environment. DHTs introduce complexity, latency in discovery, and reliance on bootstrap nodes that act as pseudo-gateways. The gossip + anchor model provides discovery with lower complexity for the intended network scale.
 ### 1.2 Dedicated TURN/STUN Infrastructure
 * **Why Rejected:** The core mission is to avoid dependency on dedicated infrastructure. Whalescale does not use STUN servers for address observation (peers observe each other) or TURN servers for relay (anchor nodes relay encrypted packets through existing tunnels). The same functionality emerges from the P2P mesh without requiring separately operated services.
 ### 1.3 WireGuard Kernel Module as Data Plane
 * **Why Rejected:** WireGuard manages peer endpoints autonomously (roaming silently overrides programmatic `wg set`), creating an unresolvable conflict with the control plane. It has no multipath capability, no extensibility for control messages, and binds a single UDP socket per interface. The custom userspace Noise_IK transport provides identical cryptographic security while allowing full control over endpoint management, multipath, and integrated control messaging.
 ### 1.4 TCP-Based Connectivity
 * **Why Rejected:** TCP is unsuitable for P2P hole punching due to the strict state requirements of the protocol. UDP is the only viable transport for NAT traversal.
 ### 1.5 Port Prediction / Port Sweeping
 * **Why Rejected:** Port prediction is architecturally defeated by CGNAT. A CGNAT device shares a single public IP across thousands of subscribers; the external port assigned depends on every other subscriber's concurrent activity, making sequential prediction infeasible. Port sweeping (e.g., ±50 ports) covers a negligible fraction of the CGNAT port range (typically 10,000–60,000+) and wastes battery and bandwidth with near-zero success probability. This mechanism has been removed entirely. Symmetric ↔ Symmetric connectivity is handled via anchor relay instead.
 ### 1.6 Flow-Level Scheduling for Multipath
 * **Why Rejected:** Flow-level scheduling (all packets from a 5-tuple go to the same path) avoids reordering but cannot aggregate bandwidth for single flows. The primary use case — a mobile device streaming video over 5G + WiFi — is a single flow that needs more bandwidth than either path alone provides. Flow-level scheduling would make multipath useful only for failover, not aggregation.
 ### 1.7 Per-Path Reliability / Retransmission
 * **Why Rejected:** Adding retransmission at the multipath layer creates double retransmission for inner TCP (inner TCP retransmits, then Whalescale retransmits the same data), wasting bandwidth and increasing latency. It also breaks inner UDP semantics — inner UDP expects unreliable delivery, and adding reliability at the transport layer introduces unpredictable latency spikes. Whalescale is an unreliable VPN transport; retransmission is the inner protocol's responsibility.
 ### 1.8 Layer 2 Bonding
 * **Why Rejected:** Bonding network interfaces at layer 2 (e.g., Linux bonding driver) requires both interfaces to be on the same physical network segment and does not work across heterogeneous paths like 5G + WiFi. It also requires kernel-level configuration and cannot leverage path-specific scheduling intelligence (knowing that one path has lower latency, another has higher bandwidth).
 ## 2. Bad Design Decisions (What to Avoid)
 ### 2.1 Treating Anchors as Optional
 * **Risk:** The anchor-first topology is the load-bearing wall of the connectivity model. If all cached endpoints for mobile nodes become stale and no anchor is reachable, the network cannot re-converge. Anchors are not just "nice to have" — they are the mechanism by which mobile peers re-enter the network after IP changes.
 * **Rule:** The system must treat anchors as a first-class concept, track anchor availability, and warn when only one anchor remains.
 ### 2.2 Ignoring UPnP/NAT-PMP/PCP
 * **Risk:** Relying solely on hole punching leads to low connection success rates. Proactive port mapping converts a cone NAT into an effectively public endpoint — the highest-value NAT traversal mechanism available.
 * **Rule:** Every Whalescale node must attempt UPnP/NAT-PMP/PCP port mapping on startup.
 ### 2.3 Wall-Clock Timestamps in Gossip
 * **Risk:** Clock skew between nodes makes wall-clock timestamps unreliable for conflict resolution. Two nodes observing the same peer at different times with skewed clocks will produce conflicting "latest" states.
 * **Rule:** Use monotonically increasing sequence numbers (Lamport-style) for ordering gossip updates. Self-attested endpoints always win over third-party observations.
 ### 2.4 Excessive Gossip Frequency
 * **Risk:** Unbounded gossip leads to broadcast storms, consuming bandwidth and CPU on mobile devices.
 * **Rule:** Gossip must use bounded fanout (random subset of neighbors, not all), periodic anti-entropy for convergence, and per-peer rate limiting.
 ### 2.5 Fighting WireGuard's Endpoint Management
 * **Risk:** If WireGuard is used, its autonomous roaming will silently override programmatic `wg set` calls, causing the control plane's view of peer endpoints to diverge from reality.
 * **Rule:** This is why Whalescale owns its data plane. If WireGuard compatibility mode is used (single-path, WireGuard wire format), endpoint management must still be driven by Whalescale with WireGuard's roaming suppressed or monitored.
 ### 2.6 Implementing Crypto from Scratch
 * **Risk:** The Noise_IK handshake and transport encryption must be implemented using an established, audited Rust Noise library. Rolling custom crypto is a security catastrophe.
 * **Rule:** Use `snow` or equivalent. Only the transport, scheduling, and multipath logic should be original code.
 ### 2.7 Ignoring LAN-Local Communication
 * **Risk:** Two nodes on the same LAN that communicate through NAT hairpinning suffer unnecessary latency and dependency on the router's hairpin implementation (which is often broken). They should discover each other and communicate directly on the LAN.
 * **Rule:** Implement LAN-local discovery (mDNS or broadcast) and bypass NAT for same-network peers.
 ### 2.8 Adding Per-Path Congestion Control Without Understanding Double-CC
 * **Risk:** The inner traffic (especially TCP) already has its own congestion control. If Whalescale also implements per-path congestion control, the two controllers interfere: congestion on one Whalescale path causes inner TCP to reduce its rate across the entire connection, even if other Whalescale paths are uncongested. This is the "coupled congestion control" problem from MPTCP, but Whalescale cannot solve it the way MPTCP does (by modifying the inner TCP's congestion controller) because the inner TCP is inside the encrypted tunnel.
 * **Rule:** The multipath scheduler uses bandwidth estimation and path health monitoring (RTT, loss rate) for scheduling decisions, NOT congestion control. Do not implement send-rate limiting at the Whalescale layer. Let the inner traffic's own congestion control drive the data rate.
 ### 2.9 Ignoring the Reordering Buffer Under Path Failure
 * **Risk:** When a path fails, packets in flight on that path are lost. If the reordering buffer doesn't flush the gaps from the failed path, it blocks indefinitely waiting for packets that will never arrive. This stalls all traffic through the session.
 * **Rule:** Path failure must trigger immediate gap flush for the failed path's in-flight packets. The reordering buffer must have a bounded maximum depth and force-skip gaps that exceed the timeout.
 ### 2.10 Setting VPN MTU to a Single Path's MTU in a Multipath Session
 * **Risk:** If the VPN MTU is set to the MTU of the fastest path, and a slower path has a smaller MTU, full-size packets sent on the slower path will be fragmented or dropped. This causes silent throughput degradation and inner TCP retransmissions.
 * **Rule:** VPN MTU must be the minimum across all active paths. Recalculate when paths are added or removed.
 ### 2.11 Assuming Multipath Always Improves Performance
 * **Risk:** With paths that have very different latencies (e.g., 20ms WiFi + 200ms satellite), aggressive packet-level scheduling creates deep reordering that the buffer must absorb. The added reordering delay may reduce inner TCP goodput below what single-path (WiFi only) would achieve. The scheduler's reordering depth constraint should prevent this, but the constraint itself limits bandwidth aggregation.
 * **Rule:** Multipath performance must be validated with test benching, not assumed. The scheduler must be willing to deprioritize or skip paths that cause more harm than benefit.
 ## 3. Non-Obvious Risks & Negative Aspects
 ### 3.1 The Battery Drain Problem (Mobile Nodes)
 * **Challenge:** Recovery Mode probing is radio-intensive. Mobile devices aggressively trying to reconnect will deplete battery.
 * **Mitigation:** Exponential backoff (1s → 2s → 4s → ... → 60s cap). Prefer reaching an anchor first (single probe, high probability of success) before attempting other cached endpoints.
 ### 3.2 The Split-Brain Network State
 * **Challenge:** Two network segments can become isolated. Nodes in each segment believe the other segment's nodes are dead.
 * **Mitigation:** Periodic anti-entropy exchanges (slow timer, e.g., every 5 minutes) with random peers. When segments reconnect, self-attested endpoints with sequence numbers provide unambiguous conflict resolution — the higher sequence number wins regardless of which segment produced it.
 ### 3.3 Gossip-Based DoS (Malicious Node)
 * **Challenge:** A connected but malicious node can flood the network with fake observed-endpoint gossip for legitimate peers, pointing them to blackhole addresses.
 * **Mitigation:** Self-attested endpoints are signed by the peer's own Ed25519 key. A peer's own declaration of its address is always authoritative over any third-party observation. Observed endpoints from third parties are advisory hints only, never authoritative.
 ### 3.4 Single Anchor as Single Point of Failure
 * **Challenge:** If the network has only one anchor and it goes offline, mobile nodes lose their reconnection mechanism. The gossip protocol cannot help because mobile nodes behind symmetric NAT cannot be reached by other mobile nodes.
 * **Mitigation:** Recommend at least two anchors on different ISPs. Detect and warn when only one anchor remains. Dual-anchor mutual keepalive keeps both anchors' addresses current.
 ### 3.5 Permanent Partition of Mobile Nodes
 * **Challenge:** A mobile node that loses all cached endpoints (e.g., all peers have rotated IPs simultaneously) cannot re-enter the network without out-of-band resynchronization.
 * **Mitigation:** This is an accepted limitation, not a bug. The system should clearly communicate this state to the user and require manual re-bootstrap. Mitigate probability by maintaining connections to multiple anchors on different networks.
 ### 3.6 Userspace Performance Ceiling
 * **Challenge:** Userspace crypto and transport tops out around 1–2 Gbps on modern hardware, compared to ~4 Gbps for WireGuard in the kernel.
 * **Assessment:** Acceptable for the intended use case (mobile, home, small office networks). If performance becomes critical, a kernel bypass path (e.g., AF_XDP) could be added later without changing the architecture.
 ### 3.7 Relay Amplification
 * **Challenge:** Anchor relay for symmetric ↔ symmetric pairs means the anchor's bandwidth is consumed forwarding traffic between two nodes that cannot connect directly. If many mobile pairs rely on the same anchor, the anchor becomes a bottleneck.
 * **Mitigation:** The relay is encrypted packet forwarding, not decryption/re-encryption, so CPU cost is minimal. Bandwidth cost is real. Distribute relay load across multiple anchors. Long-term, encourage IPv6 adoption to eliminate the relay need.
 ### 3.8 Bootstrap Protocol Exposure
 * **Challenge:** Pre-session bootstrap messages (PATH_PROBE, PATH_PROBE_REPLY) are unencrypted. An observer can learn node IP addresses and who is attempting to connect to whom.
 * **Assessment:** This is metadata only — no user data or session keys are exposed. Full authentication and encryption begin with the Noise_IK handshake immediately after bootstrap. This tradeoff is inherent to any system that must establish connectivity before authenticating.
 ### 3.9 Inner TCP Fast Retransmit from Reordering
 * **Challenge:** The multipath reordering buffer may not release packets before the inner TCP's loss detection triggers (3 duplicate ACKs → fast retransmit). This causes unnecessary retransmissions that waste bandwidth on all paths. With MAX_REORDERING_DEPTH = 128, Linux auto-tunes `tcp_reordering` to tolerate this, but Windows and macOS may not.
 * **Mitigation:** The reordering buffer's adaptive timeout (based on measured path latency spread) is the primary defense — if it delivers packets fast enough, inner TCP never sees reordering. The sender-side reordering depth constraint prevents fast paths from getting too far ahead. Test benching will quantify the actual false retransmit rate on different inner TCP stacks.
 ### 3.10 Reordering Buffer Memory Under High Throughput
 * **Challenge:** At high packet rates with paths that have large RTT differences, the reordering buffer can hold many packets simultaneously. At 100,000 packets/sec with 128-packet depth and 1500 bytes/packet: ~192KB per session. For 50 concurrent peer sessions: ~9.6MB. This is acceptable, but pathological cases (many sessions, all with high throughput) should be monitored.
 * **Mitigation:** The MAX_REORDERING_DEPTH = 128 provides a hard memory bound per session. The force-skip mechanism ensures the buffer cannot grow beyond this limit.
 ### 3.11 Multipath Scheduler Oscillation
 * **Challenge:** If bandwidth estimates fluctuate rapidly (e.g., due to bursty cross-traffic on a shared WiFi link), path weights may oscillate, causing the scheduler to repeatedly shift traffic between paths. This creates reordering patterns that are harder for the buffer to absorb than steady-state scheduling.
 * **Mitigation:** Use a rolling 1-second window for bandwidth estimation (not instantaneous). Apply hysteresis to weight changes — only change a path's weight when the new estimate differs by more than 20% from the current weight.
--- a/Cargo.lock
+++ b/Cargo.lock
@ -0,0 +1,942 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
 version = 4
 [[package]]
 name = "aead"
 version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
 dependencies = [
 "crypto-common",
 "generic-array",
 ]
 [[package]]
 name = "aes"
 version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
 dependencies = [
 "cfg-if",
 "cipher",
 "cpufeatures",
 ]
 [[package]]
 name = "aes-gcm"
 version = "0.10.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
 dependencies = [
 "aead",
 "aes",
 "cipher",
 "ctr",
 "ghash",
 "subtle",
 ]
 [[package]]
 name = "base64ct"
 version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 [[package]]
 name = "blake2"
 version = "0.10.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
 dependencies = [
 "digest",
 ]
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
 dependencies = [
 "generic-array",
 ]
 [[package]]
 name = "cc"
 version = "1.2.60"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
 dependencies = [
 "find-msvc-tools",
 "shlex",
 ]
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 [[package]]
 name = "chacha20"
 version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818"
 dependencies = [
 "cfg-if",
 "cipher",
 "cpufeatures",
 ]
 [[package]]
 name = "chacha20poly1305"
 version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "10cd79432192d1c0f4e1a0fef9527696cc039165d729fb41b3f4f4f354c2dc35"
 dependencies = [
 "aead",
 "chacha20",
 "cipher",
 "poly1305",
 "zeroize",
 ]
 [[package]]
 name = "cipher"
 version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
 "crypto-common",
 "inout",
 "zeroize",
 ]
 [[package]]
 name = "const-oid"
 version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
 dependencies = [
 "libc",
 ]
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
 dependencies = [
 "generic-array",
 "typenum",
 ]
 [[package]]
 name = "ctr"
 version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
 dependencies = [
 "cipher",
 ]
 [[package]]
 name = "curve25519-dalek"
 version = "4.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be"
 dependencies = [
 "cfg-if",
 "cpufeatures",
 "curve25519-dalek-derive",
 "digest",
 "fiat-crypto",
 "rustc_version",
 "subtle",
 "zeroize",
 ]
 [[package]]
 name = "curve25519-dalek-derive"
 version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
 [[package]]
 name = "der"
 version = "0.7.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb"
 dependencies = [
 "const-oid",
 "zeroize",
 ]
 [[package]]
 name = "digest"
 version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
 "block-buffer",
 "crypto-common",
 "subtle",
 ]
 [[package]]
 name = "ed25519"
 version = "2.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "115531babc129696a58c64a4fef0a8bf9e9698629fb97e9e40767d235cfbcd53"
 dependencies = [
 "pkcs8",
 "signature",
 ]
 [[package]]
 name = "ed25519-dalek"
 version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "70e796c081cee67dc755e1a36a0a172b897fab85fc3f6bc48307991f64e4eca9"
 dependencies = [
 "curve25519-dalek",
 "ed25519",
 "rand_core",
 "serde",
 "sha2",
 "subtle",
 "zeroize",
 ]
 [[package]]
 name = "fiat-crypto"
 version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d"
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 [[package]]
 name = "generic-array"
 version = "0.14.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
 dependencies = [
 "typenum",
 "version_check",
 ]
 [[package]]
 name = "getrandom"
 version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
 dependencies = [
 "cfg-if",
 "libc",
 "wasi",
 ]
 [[package]]
 name = "getrandom"
 version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 dependencies = [
 "cfg-if",
 "libc",
 "r-efi",
 "wasip2",
 ]
 [[package]]
 name = "ghash"
 version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
 dependencies = [
 "opaque-debug",
 "polyval",
 ]
 [[package]]
 name = "inout"
 version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
 dependencies = [
 "generic-array",
 ]
 [[package]]
 name = "libc"
 version = "0.2.185"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
 [[package]]
 name = "mio"
 version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1"
 dependencies = [
 "libc",
 "wasi",
 "windows-sys 0.61.2",
 ]
 [[package]]
 name = "once_cell"
 version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 [[package]]
 name = "opaque-debug"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 [[package]]
 name = "pkcs8"
 version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f950b2377845cebe5cf8b5165cb3cc1a5e0fa5cfa3e1f7f55707d8fd82e0a7b7"
 dependencies = [
 "der",
 "spki",
 ]
 [[package]]
 name = "poly1305"
 version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf"
 dependencies = [
 "cpufeatures",
 "opaque-debug",
 "universal-hash",
 ]
 [[package]]
 name = "polyval"
 version = "0.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
 dependencies = [
 "cfg-if",
 "cpufeatures",
 "opaque-debug",
 "universal-hash",
 ]
 [[package]]
 name = "ppv-lite86"
 version = "0.2.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
 dependencies = [
 "zerocopy",
 ]
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
 dependencies = [
 "unicode-ident",
 ]
 [[package]]
 name = "quote"
 version = "1.0.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
 dependencies = [
 "proc-macro2",
 ]
 [[package]]
 name = "r-efi"
 version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 [[package]]
 name = "rand"
 version = "0.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
 dependencies = [
 "libc",
 "rand_chacha",
 "rand_core",
 ]
 [[package]]
 name = "rand_chacha"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
 dependencies = [
 "ppv-lite86",
 "rand_core",
 ]
 [[package]]
 name = "rand_core"
 version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
 dependencies = [
 "getrandom 0.2.17",
 ]
 [[package]]
 name = "ring"
 version = "0.17.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
 dependencies = [
 "cc",
 "cfg-if",
 "getrandom 0.2.17",
 "libc",
 "untrusted",
 "windows-sys 0.52.0",
 ]
 [[package]]
 name = "rustc_version"
 version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
 dependencies = [
 "semver",
 ]
 [[package]]
 name = "semver"
 version = "1.0.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
 [[package]]
 name = "serde"
 version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
 dependencies = [
 "serde_core",
 "serde_derive",
 ]
 [[package]]
 name = "serde_core"
 version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
 dependencies = [
 "serde_derive",
 ]
 [[package]]
 name = "serde_derive"
 version = "1.0.228"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
 [[package]]
 name = "sha2"
 version = "0.10.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
 dependencies = [
 "cfg-if",
 "cpufeatures",
 "digest",
 ]
 [[package]]
 name = "shlex"
 version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 [[package]]
 name = "signature"
 version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 dependencies = [
 "rand_core",
 ]
 [[package]]
 name = "snow"
 version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "599b506ccc4aff8cf7844bc42cf783009a434c1e26c964432560fb6d6ad02d82"
 dependencies = [
 "aes-gcm",
 "blake2",
 "chacha20poly1305",
 "curve25519-dalek",
 "getrandom 0.3.4",
 "ring",
 "rustc_version",
 "sha2",
 "subtle",
 ]
 [[package]]
 name = "socket2"
 version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e"
 dependencies = [
 "libc",
 "windows-sys 0.61.2",
 ]
 [[package]]
 name = "spki"
 version = "0.7.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d91ed6c858b01f942cd56b37a94b3e0a1798290327d1236e4d9cf4eaca44d29d"
 dependencies = [
 "base64ct",
 "der",
 ]
 [[package]]
 name = "subtle"
 version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 [[package]]
 name = "syn"
 version = "2.0.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
 dependencies = [
 "proc-macro2",
 "quote",
 "unicode-ident",
 ]
 [[package]]
 name = "thiserror"
 version = "1.0.69"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
 dependencies = [
 "thiserror-impl",
 ]
 [[package]]
 name = "thiserror-impl"
 version = "1.0.69"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
 [[package]]
 name = "tokio"
 version = "1.52.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b67dee974fe86fd92cc45b7a95fdd2f99a36a6d7b0d431a231178d3d670bbcc6"
 dependencies = [
 "libc",
 "mio",
 "pin-project-lite",
 "socket2",
 "tokio-macros",
 "windows-sys 0.61.2",
 ]
 [[package]]
 name = "tokio-macros"
 version = "2.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
 [[package]]
 name = "tracing"
 version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
 "pin-project-lite",
 "tracing-attributes",
 "tracing-core",
 ]
 [[package]]
 name = "tracing-attributes"
 version = "0.1.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
 [[package]]
 name = "tracing-core"
 version = "0.1.36"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
 dependencies = [
 "once_cell",
 ]
 [[package]]
 name = "typenum"
 version = "1.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 [[package]]
 name = "universal-hash"
 version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
 dependencies = [
 "crypto-common",
 "subtle",
 ]
 [[package]]
 name = "untrusted"
 version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
 [[package]]
 name = "version_check"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 [[package]]
 name = "wasip2"
 version = "1.0.2+wasi-0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
 dependencies = [
 "wit-bindgen",
 ]
 [[package]]
 name = "whalescale-agent"
 version = "0.1.0"
 dependencies = [
 "whalescale-anchor",
 "whalescale-bootstrap",
 "whalescale-crypto",
 "whalescale-gossip",
 "whalescale-multipath",
 "whalescale-nat",
 "whalescale-path",
 "whalescale-session",
 "whalescale-transport",
 "whalescale-tun",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-anchor"
 version = "0.1.0"
 dependencies = [
 "whalescale-gossip",
 "whalescale-transport",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-bootstrap"
 version = "0.1.0"
 dependencies = [
 "whalescale-crypto",
 "whalescale-transport",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-crypto"
 version = "0.1.0"
 dependencies = [
 "curve25519-dalek",
 "ed25519-dalek",
 "rand",
 "rand_core",
 "snow",
 "thiserror",
 "whalescale-types",
 "x25519-dalek",
 ]
 [[package]]
 name = "whalescale-gossip"
 version = "0.1.0"
 dependencies = [
 "whalescale-crypto",
 "whalescale-transport",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-multipath"
 version = "0.1.0"
 dependencies = [
 "whalescale-path",
 "whalescale-transport",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-nat"
 version = "0.1.0"
 dependencies = [
 "whalescale-transport",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-path"
 version = "0.1.0"
 dependencies = [
 "whalescale-transport",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-session"
 version = "0.1.0"
 dependencies = [
 "rand",
 "thiserror",
 "tokio",
 "tracing",
 "whalescale-crypto",
 "whalescale-transport",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-transport"
 version = "0.1.0"
 dependencies = [
 "thiserror",
 "tokio",
 "whalescale-crypto",
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-tun"
 version = "0.1.0"
 dependencies = [
 "whalescale-types",
 ]
 [[package]]
 name = "whalescale-types"
 version = "0.1.0"
 [[package]]
 name = "windows-link"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 [[package]]
 name = "windows-sys"
 version = "0.52.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
 dependencies = [
 "windows-targets",
 ]
 [[package]]
 name = "windows-sys"
 version = "0.61.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
 "windows-link",
 ]
 [[package]]
 name = "windows-targets"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
 dependencies = [
 "windows_aarch64_gnullvm",
 "windows_aarch64_msvc",
 "windows_i686_gnu",
 "windows_i686_gnullvm",
 "windows_i686_msvc",
 "windows_x86_64_gnu",
 "windows_x86_64_gnullvm",
 "windows_x86_64_msvc",
 ]
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
 [[package]]
 name = "windows_i686_gnu"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
 [[package]]
 name = "windows_i686_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
 [[package]]
 name = "windows_i686_msvc"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 [[package]]
 name = "wit-bindgen"
 version = "0.51.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
 [[package]]
 name = "x25519-dalek"
 version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c7e468321c81fb07fa7f4c636c3972b9100f0346e5b6a9f2bd0603a52f7ed277"
 dependencies = [
 "curve25519-dalek",
 "rand_core",
 "serde",
 "zeroize",
 ]
 [[package]]
 name = "zerocopy"
 version = "0.8.48"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eed437bf9d6692032087e337407a86f04cd8d6a16a37199ed57949d415bd68e9"
 dependencies = [
 "zerocopy-derive",
 ]
 [[package]]
 name = "zerocopy-derive"
 version = "0.8.48"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "70e3cd084b1788766f53af483dd21f93881ff30d7320490ec3ef7526d203bad4"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
 [[package]]
 name = "zeroize"
 version = "1.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
 dependencies = [
 "zeroize_derive",
 ]
 [[package]]
 name = "zeroize_derive"
 version = "1.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn",
 ]
--- a/Cargo.toml
+++ b/Cargo.toml
@ -0,0 +1,35 @@
 [workspace]
 resolver = "2"
 members = [
    "crates/whalescale-agent",
    "crates/whalescale-session",
    "crates/whalescale-transport",
    "crates/whalescale-path",
    "crates/whalescale-multipath",
    "crates/whalescale-gossip",
    "crates/whalescale-nat",
    "crates/whalescale-anchor",
    "crates/whalescale-tun",
    "crates/whalescale-bootstrap",
    "crates/whalescale-crypto",
    "crates/whalescale-types",
 ]
 [workspace.package]
 version = "0.1.0"
 edition = "2024"
 license = "Proprietary"
 [workspace.dependencies]
 whalescale-agent = { path = "crates/whalescale-agent" }
 whalescale-session = { path = "crates/whalescale-session" }
 whalescale-transport = { path = "crates/whalescale-transport" }
 whalescale-path = { path = "crates/whalescale-path" }
 whalescale-multipath = { path = "crates/whalescale-multipath" }
 whalescale-gossip = { path = "crates/whalescale-gossip" }
 whalescale-nat = { path = "crates/whalescale-nat" }
 whalescale-anchor = { path = "crates/whalescale-anchor" }
 whalescale-tun = { path = "crates/whalescale-tun" }
 whalescale-bootstrap = { path = "crates/whalescale-bootstrap" }
 whalescale-crypto = { path = "crates/whalescale-crypto" }
 whalescale-types = { path = "crates/whalescale-types" }
--- a/DESIGN.md
+++ b/DESIGN.md
@ -0,0 +1,240 @@
 # Whalescale: Design Document
 ## 1. Introduction
 Whalescale is a peer-to-peer (P2P) VPN architecture designed to provide secure, end-to-end encrypted connectivity without centralized gateway servers, proprietary relay services, or discovery infrastructure. The core mission is to restore peer-to-peer as a first-class networking mode on an internet that has increasingly moved away from it, using best-effort mechanisms that work with the existing CGNAT-ridden world while preferring IPv6 wherever available.
 Whalescale uses an **Integrated Plane Architecture** — the control and data planes share the same transport, the same encryption session, and the same process. There is no separate WireGuard process to coordinate with, no second NAT traversal problem for a control channel, and no conflict over endpoint management.
 ```
 ┌──────────────────────────────────────────────┐
 │              TUN Device (IP packets)          │
 ├──────────────────────────────────────────────┤
 │         Reordering Buffer                     │
 ├──────────────────────────────────────────────┤
 │          Path Scheduler                       │
 ├───────────┬───────────┬──────────────────────┤
 │   Path 1  │   Path 2  │      Path N          │
 │  5G/UDP   │  WiFi/UDP │    IPv6/UDP          │
 ├───────────┴───────────┴──────────────────────┤
 │       Noise_IK Session Manager                │
 ├──────────────────────────────────────────────┤
 │       Whalescale Agent (unified process)      │
 │       Control + Data in one encrypted session │
 └──────────────────────────────────────────────┘
 ```
 ## 2. Core Principles
 * **Direct Connectivity First:** All data traffic is peer-to-peer whenever possible. No middleman handles user data.
 * **Encrypted Relay as Fallback:** When direct P2P is physically impossible (symmetric NAT on both sides), traffic is relayed through an anchor node. The relay sees only encrypted ciphertext — it is a packet forwarder, not a MITM.
 * **Trust-Based Initialization:** Connectivity begins through out-of-band, manual configuration of known, trusted endpoints.
 * **IPv6 Preferred:** IPv6 with globally routable addresses is the preferred transport. It eliminates NAT entirely for nodes that have it. IPv4 with NAT traversal is the fallback.
 * **Multipath Native:** A single peer session can utilize multiple network interfaces simultaneously (e.g., 5G + WiFi) for bandwidth aggregation and resilience.
 * **Anchor-First Topology:** The network assumes at least one anchor node is present. Anchors are the load-bearing walls of the connectivity model.
 ## 3. Architecture
 ### 3.1 Identity & Security
 * **Cryptographic Identity:** Every node is identified by a unique Ed25519 public key. The Whalescale Node ID **is** the public key. There is no separate WireGuard key.
 * **Noise_IK Handshake:** Whalescale implements the Noise Protocol Framework's Noise_IK pattern natively — the same handshake pattern used by WireGuard — for mutual authentication and end-to-end encryption. This is implemented in userspace using an established Rust Noise library, not via the WireGuard kernel module.
 * **Zero-Trust Transport:** Even when traffic is relayed through an anchor, the payload remains encrypted with the keys of the two end-nodes. The relay forwards opaque ciphertext.
 * **Key Rotation:** Symmetric transport keys are rotated on the same schedule as WireGuard (after 2^64 packets or 2 minutes, whichever comes first).
 ### 3.2 The Data Plane: Custom Transport
 Whalescale owns its data plane entirely. It does not use the WireGuard kernel module.
 **Why not WireGuard:**
 * WireGuard binds one UDP socket per interface and manages peer endpoints autonomously (roaming overrides programmatic `wg set` calls), creating an unresolvable conflict with the control plane.
 * WireGuard has no multipath concept — one tunnel, one path, per peer.
 * WireGuard has no extensibility mechanism — control messages cannot be embedded in its sessions.
 * WireGuard is a kernel module — its state machine cannot be modified or coordinated with.
 **What Whalescale implements instead:**
 * **Noise_IK handshake** (same cryptographic security properties as WireGuard)
 * **Userspace UDP transport** with full control over endpoint management
 * **Multipath scheduling** — multiple UDP paths per peer session
 * **Integrated control messages** — control and data share the same encrypted session
 * **TUN device integration** — reads IP packets from the OS, encrypts and sends; receives, decrypts and writes back
 **WireGuard compatibility:** The Noise_IK implementation uses WireGuard's exact wire format for handshake and transport messages in single-path mode. This allows a Whalescale node to interoperate with a vanilla WireGuard node for basic connectivity. Extended multipath features require Whalescale on both ends.
 ### 3.3 Multipath Transport
 A single peer session can utilize multiple network paths simultaneously for **bandwidth aggregation and resilience**. A "path" is a 4-tuple: `(local_ip:port, remote_ip:port)`. All paths share a single Noise_IK session and a single global sequence space.
 **Design choice: Packet-level scheduling.** Every outbound IP packet from the TUN device may be sent on any available path. The receiver reassembles packets in global sequence order via a reordering buffer before delivering to its TUN device. This enables bandwidth aggregation for single flows (the primary use case: 5G + WiFi on a mobile device).
 **Key components:**
 * **Reordering buffer** — per-session buffer that reassembles packets by global sequence number. Per-gap adaptive timeouts based on measured path latency spread. Late packets (arriving after gap skip) are dropped. Maximum depth of 128 packets.
 * **Weighted round-robin scheduler** — distributes packets across paths proportional to estimated bandwidth. Credit-based system ensures fair proportional distribution. Sender-side reordering depth constraint prevents fast paths from getting too far ahead.
 * **Path bandwidth estimation** — rolling 1-second window over ACKed bytes per path. New paths start with minimum weight and ramp up after probing.
 * **Feedback loop** — periodic ACK messages carry per-path statistics (packets received, estimated latency, loss count) to inform scheduling decisions. ACKs are for scheduling only, not reliability.
 * **Path health model** — three states (healthy, degraded, failed) with corresponding scheduler actions (full weight, reduced weight, removal).
 **Inner TCP interaction:** Packet-level scheduling creates reordering that inner TCP may misinterpret as loss. The reordering buffer is the primary mitigation — if it delivers in order, inner TCP is unaware of multipath. With MAX_REORDERING_DEPTH = 128, Linux's auto-tuned `tcp_reordering` (up to 127) generally tolerates the reordering without false fast retransmits. Non-Linux platforms may see occasional false retransmits — this is an accepted tradeoff that test benching will quantify.
 **Full specification:** See `MULTIPATH.md` for detailed wire format, reordering buffer behavior, scheduler algorithm, bandwidth estimation, feedback loop, path failure detection, path lifecycle, and test bench framework.
 ### 3.4 The Control Plane: Integrated Messaging
 Control messages ride inside the same encrypted Noise_IK session as data. There is no separate control channel, no second set of UDP sockets, and no second NAT traversal problem.
 **Control Message Types:**
 | Message | Purpose |
 |---------|---------|
 | `PATH_ANNOUNCE` | "I have these local interfaces / observed external addresses" |
 | `PATH_PROBE` | NAT traversal probe + RTT measurement |
 | `PATH_PROBE_REPLY` | Response with observed external address |
 | `GOSSIP_UPDATE` | Peer location metadata (see §3.6) |
 | `HEARTBEAT` | Keep NAT mappings alive; detect path failure |
 **Bootstrapping a new session:** Before a Noise_IK session is established, control messages use a separate lightweight bootstrap protocol on a well-known UDP port. Once the Noise_IK handshake completes, all subsequent control messages move into the encrypted session.
 ### 3.5 Connection Lifecycle
 1. **Manual Bootstrap:** The user provides the `IP:Port` (or hostname) and `Identity Fingerprint` of an anchor or known peer. The fingerprint is the full Ed25519 public key or a cryptographically secure shorthand (e.g., base32-encoded hash with collision resistance).
 2. **NAT Traversal:**
    * **IPv6:** If both nodes have IPv6 with globally routable addresses, connect directly — no NAT traversal needed.
    * **IPv4 UDP Hole Punching:** Both nodes simultaneously send UDP packets to each other's last known endpoints to create NAT mappings.
    * **Signaling via Anchor:** If direct punching fails, the node uses existing active connections (typically to an anchor) to exchange observed connection metadata with the target peer.
 3. **Noise_IK Handshake:** Once a path is established, the Noise_IK handshake completes, authenticating both peers and establishing a symmetric encryption session.
 4. **Path Expansion:** After the initial path is established, additional paths (other interfaces, IPv6) are discovered and added to the session via `PATH_ANNOUNCE` and `PATH_PROBE` messages.
 5. **Established State:** The session is maintained via persistent `HEARTBEAT` messages (which double as NAT keepalives) and continuous path health monitoring.
 ### 3.6 Peer Discovery & State Management
 There is no DHT. Discovery relies on **Anchors**, **LKG Caching**, and **Gossip**.
 #### Anchor Nodes
 An anchor is a node that:
 * Is behind a **cone-type NAT** (full cone, restricted cone, or port-restricted cone) or has **no NAT at all** (public IP), such that its external port accepts packets from any source.
 * Has an **IP address that is stable** on the timescale of days or weeks, not minutes.
 * Is **reachable at its cached address** by nodes that have previously connected to it.
 Examples: a cloud VPS, a home desktop on a typical ISP (not CGNAT), a home server behind a router with UPnP-enabled port mapping.
 **Anchor liveness:** Anchors are a first-class concept. The network tracks anchor availability. If a node detects it is the only remaining anchor, it warns the user. The system recommends at least two anchors on different ISPs to avoid simultaneous IP change events.
 **Anchor relay:** When two symmetric-NAT nodes need to communicate, an anchor forwards their encrypted packets. This is not a TURN server — it is an existing Whalescale peer performing packet forwarding on already-established tunnels. The anchor sees only Noise_IK ciphertext.
 #### LKG Cache
 Every node maintains a persistent local database of every peer it has successfully connected to, including:
 * Peer ID (Ed25519 public key)
 * All known endpoints (IP:Port) for each path, with sequence numbers
 * Last successful connection timestamp
 * Whether the peer is an anchor
 #### Gossip Protocol
 When a node's connection state changes, this information is gossiped to active neighbors.
 **Gossip Payload:**
 ```
 {
  PeerID:        Ed25519 public key of the peer being described
  Endpoints:     [{ IP, Port, PathType (IPv4/IPv6/LAN) }]
  SeqNo:         Monotonically increasing sequence number (per-peer)
  SelfAttested:  bool — true if this is the peer describing itself
  Signature:     Ed25519 signature over the above fields
 }
 ```
 **Conflict Resolution:**
 * **Self-attested endpoints always win.** A peer's own declaration of its address is authoritative over any third-party observation.
 * **Sequence numbers, not timestamps.** Wall-clock timestamps are unreliable due to clock skew. Monotonically increasing sequence numbers (Lamport-style) provide unambiguous ordering.
 * **All self-attested updates are signed.** A peer signs its own endpoint declarations with its private key. This prevents malicious nodes from injecting false self-attested addresses for other peers.
 * **Observed endpoints (third-party) are advisory.** They are used as hints for connection attempts but are never treated as authoritative.
 **Gossip Mechanics:**
 * **Bounded fanout:** Each gossip message is sent to a random subset of active neighbors (not all of them), preventing broadcast storms.
 * **Periodic anti-entropy:** On a slow timer (e.g., every 5 minutes), nodes exchange full state summaries with a random peer to converge on missed updates. This uses a lightweight merkle-tree or hash-diff mechanism.
 * **Throttled propagation:** Gossip messages are rate-limited per peer to avoid bandwidth waste on mobile connections.
 ### 3.7 NAT Traversal Strategy
 **IPv6 (Preferred):** If both nodes have IPv6 with globally routable addresses, connect directly. No NAT, no hole punching. This is the primary path for mobile-to-mobile connectivity and should be attempted first.
 **IPv4 NAT Traversal:**
 | NAT Type Pair | Strategy | Outcome |
 |---------------|----------|---------|
 | Cone ↔ Any | Cone node's port is reachable; other node initiates | Direct P2P |
 | Symmetric ↔ Cone | Symmetric node initiates to cone node's known endpoint | Direct P2P |
 | Symmetric ↔ Symmetric | No direct path possible | Anchor relay |
 | Any ↔ Public | Direct connection | Direct P2P |
 **Proactive Port Mapping:**
 Implementation of **UPnP**, **NAT-PMP**, and **PCP** to request persistent port forwarding on supported routers. This converts a cone NAT into an effectively public endpoint and is the highest-value NAT traversal mechanism.
 **NAT Type Detection:**
 Nodes detect their own NAT type by comparing their local endpoint against the externally observed endpoint reported by peers via `PATH_PROBE_REPLY`. If the external port changes depending on the destination, the NAT is symmetric.
 **LAN-Local Discovery:**
 When two Whalescale nodes are on the same LAN, they should discover each other directly via mDNS/broadcast or by observing matching public IP addresses, and communicate on the LAN without traversing NAT at all. This avoids hairpin NAT (which many routers implement incorrectly or not at all).
 **What is NOT implemented:**
 * **Port prediction / port sweeping:** Architecturally defeated by CGNAT. The external port assigned by a CGNAT depends on every other subscriber's concurrent activity, making prediction infeasible. Port sweeping wastes battery and bandwidth with near-zero success probability. Removed entirely.
 ### 3.8 Connection Recovery
 To handle mobile IP changes and NAT timeouts:
 **Recovery Mode (Disconnected Peer):**
 1. Upon connection loss, the node enters Recovery Mode.
 2. It attempts to re-establish contact with each cached endpoint in its LKG Cache, starting with anchors.
 3. For each anchor, the node sends a UDP packet to the anchor's last known endpoint. Since the mobile node is initiating outward, this traverses any NAT type.
 4. Once an anchor is reached, the anchor can signal the mobile node's new address to other peers.
 5. Intelligent backoff: probe intervals increase exponentially (1s → 2s → 4s → ... → 60s cap) to conserve battery on mobile devices.
 **Passive Acceptance (Connected Peer):**
 1. Anchors and stable nodes continuously listen on their mapped ports.
 2. When a valid, authenticated packet arrives from a known PeerID on a new endpoint, the node immediately accepts the new path and updates its LKG cache.
 3. The new endpoint is gossiped to other neighbors.
 **Dual-Anchor Mutual Keepalive:**
 Two anchor nodes on different ISPs maintain each other's current addresses via periodic probes. If one anchor's IP changes, the other detects the change on the next successful probe and gossips the new address. The network re-converges as long as at least one anchor remains reachable.
 ### 3.9 Failure Modes & Honest Limitations
 **Permanent Partition:** If all cached endpoints for a peer become stale and no anchor can reach that peer, the connection is lost until out-of-band resynchronization occurs. Mobile devices are most susceptible to this.
 **Symmetric ↔ Symmetric:** Two nodes both behind symmetric CGNAT cannot establish a direct P2P connection. They must communicate via anchor relay. This is not a limitation of the design — it is a fundamental property of symmetric NAT that no amount of coordination can overcome.
 **Single Anchor Failure:** If the network's only anchor goes offline, mobile nodes lose their reconnection mechanism. The system must warn when only one anchor remains.
 **Userspace Performance:** The custom data plane runs in userspace, topping out around 1–2 Gbps on modern hardware (vs. WireGuard kernel's ~4 Gbps). This is acceptable for the intended use case (mobile, home, small office networks).
 ## 4. Network Stack
 ### 4.1 Whalescale Agent (Unified Process)
 * **Transport Layer:** UDP (one socket per local network interface).
 * **Encryption:** Noise_IK (userspace, via established Rust Noise library).
 * **Multipath:** Multiple UDP paths per peer session, with reordering buffer.
 * **Responsibilities:** Peer discovery, NAT traversal, signaling, encrypted transport, path scheduling, IP packet encapsulation, TUN device management.
 ### 4.2 Bootstrap Protocol (Pre-Session)
 * **Transport Layer:** UDP on a well-known port.
 * **Purpose:** Exchange initial endpoint metadata before Noise_IK handshake is established.
 * **Messages:** `PATH_PROBE`, `PATH_PROBE_REPLY`, and session initiation.
 * **Security:** Bootstrap messages are unencrypted but carry no sensitive data (only IP:port observations). Full authentication occurs during the Noise_IK handshake.
 ## 5. Implementation Phases
 | Phase | Scope | Goal |
 |-------|-------|------|
 | 1 | Noise_IK session, single path, single peer, TUN integration | Basic VPN tunnel between two nodes |
 | 2 | Multipath transport — weighted round-robin scheduler, reordering buffer, path management, feedback loop, bandwidth estimation | Bandwidth aggregation across multiple interfaces |
 | 3 | Multi-peer session management, LKG cache, gossip | Small mesh network |
 | 4 | NAT traversal (hole punching, UPnP/PCP, anchor signaling) | Cross-NAT connectivity |
 | 5 | LAN discovery, IPv6 preference, anchor relay | Production robustness |
 | 6 | Adaptive path scheduling, test bench framework, scheduler comparison | Optimize multipath performance |
 **Phase 2 is where the novel work lives.** The multipath transport has significant open questions (inner TCP interaction, reordering depth tuning, scheduler optimality) that require empirical validation. The test bench framework in Phase 6 will compare scheduler variants and parameter settings against real workloads. See `MULTIPATH.md` §11 for the full test bench specification.
--- a/MULTIPATH.md
+++ b/MULTIPATH.md
@ -0,0 +1,512 @@
 # Whalescale: Multipath Transport Specification
 ## 1. Overview
 Whalescale multipath allows a single peer session to utilize multiple network paths simultaneously for bandwidth aggregation and resilience. Each path is a 4-tuple `(local_ip:port, remote_ip:port)` carried over UDP. All paths share a single Noise_IK encryption session and a single global sequence space.
 **Design choice:** Packet-level scheduling with reordering. Every packet from the TUN device is assigned a global sequence number and may be sent on any available path. The receiver reassembles packets in sequence order before delivering to its TUN device.
 **Alternative: Flow-level scheduling.** All packets from the same 5-tuple go to the same path. No reordering buffer needed. Inner TCP behaves normally. But a single flow can never exceed one path's capacity — no bandwidth aggregation for the common case of a mobile device streaming video over 5G + WiFi.
 **Alternative: Hybrid (flow-level default, packet-level for large flows).** Requires flow classification, state tracking, and both scheduling paths. Adds complexity without fully avoiding reordering problems. Deferring the hard problem doesn't eliminate it.
 **Rationale for packet-level:** The primary use case — bandwidth aggregation for single flows on multi-interface mobile devices — requires packet-level scheduling. The reordering complexity is the price of this capability. Test benching will validate whether the inner TCP interaction cost is acceptable in practice.
 ## 2. Packet Format
 ### 2.1 Whalescale Transport Header (Inside Noise_IK Encryption)
 ```
 Offset  Size    Field
 0       4       Session ID
 4       8       Global Sequence Number
 12      1       Path ID
 13      1       Type
 14      2       Payload Length
 16      var     Payload
 ```
 | Field | Size | Description |
 |-------|------|-------------|
 | Session ID | 32 bits | Identifies the peer session. Allows demultiplexing when multiple sessions share a socket. |
 | Global Sequence | 64 bits | Monotonically increasing per-session. Used for reordering. 64-bit avoids wraparound (2^64 packets at any realistic rate will never wrap). |
 | Path ID | 8 bits | Identifies which path carried this packet. Receiver uses this for per-path statistics. Up to 256 paths per session (far more than needed). |
 | Type | 8 bits | Packet type: `DATA (0x01)`, `CONTROL (0x02)`, `ACK (0x03)`, `PROBE (0x04)` |
 | Payload Length | 16 bits | Length of payload in bytes. Max 65535 bytes. |
 | Payload | variable | For DATA: an IP packet read from TUN. For CONTROL/ACK/PROBE: structured control message. |
 **Design choice:** 64-bit global sequence number.
 **Alternative: 32-bit sequence number.** Wraps at ~4 billion packets. At 100,000 packets/sec (reasonable for a 1 Gbps VPN tunnel with small packets), wraparound occurs in ~11 hours. Handling wraparound correctly in the reordering buffer is subtle and error-prone.
 **Rationale:** 64-bit eliminates the wraparound problem entirely. The 4-byte overhead per packet is negligible.
 ### 2.2 ACK Packet Payload
 ```
 Offset  Size    Field
 0       8       Highest Contiguous Sequence (HCS)
 8       2       ACK Path Count
 10      var     Per-path ACK entries (see below)
 Per-path entry:
 Offset  Size    Field
 0       1       Path ID
 1       8       Packets received on this path (since last ACK)
 9       4       Estimated one-way latency (microseconds)
 13      2       Packets lost on this path (since last ACK)
 15      1       Flags (0x01 = path degraded, 0x02 = path failed)
 ```
 The receiver sends ACKs to the sender for scheduling feedback. These are NOT reliability ACKs — there is no retransmission. They inform the sender's scheduling decisions.
 **Design choice:** Per-path statistics in ACKs.
 **Alternative: Sequence-level ACKs (like TCP SACK).** Would enable retransmission-style reliability. Rejected because Whalescale is an unreliable transport — inner TCP handles its own retransmission.
 **Alternative: Aggregate ACKs only (no per-path info).** Simpler but deprives the sender of the information needed to adjust per-path weights intelligently.
 **Rationale:** Per-path statistics allow the sender to detect asymmetric performance and adjust scheduling weights. The overhead is small (15 bytes per path per ACK).
 ## 3. Reordering Buffer
 ### 3.1 Overview
 The receiver maintains one reordering buffer per peer session. Packets are inserted at their global sequence position. Contiguous sequences starting from the next expected delivery position are released to the TUN device.
 ### 3.2 Timeout Mechanism
 Each missing sequence number gets a deadline:
 ```
 deadline[seq] = time_of_previous_delivery + REORDERING_TIMEOUT
 ```
 Where `time_of_previous_delivery` is the timestamp when the packet preceding the gap was delivered to TUN, and `REORDERING_TIMEOUT` is calculated as:
 ```
 REORDERING_TIMEOUT = max(
    slowest_path_one_way_latency - fastest_path_one_way_latency,
    MIN_REORDERING_TIMEOUT
 )
 MIN_REORDERING_TIMEOUT = 5ms
 ```
 One-way latency is estimated as `path_RTT / 2` for each path.
 **Design choice:** Per-gap deadlines with adaptive timeout.
 **Alternative: Fixed global timeout.** One timeout value for the entire buffer (e.g., 50ms). Simple but wasteful — fast gaps wait too long, slow gaps don't wait long enough.
 **Alternative: No timeout, wait indefinitely.** A missing packet blocks all subsequent delivery forever. Only acceptable with reliability (retransmission), which Whalescale doesn't provide.
 **Rationale:** Per-gap deadlines are the most correct approach — each gap waits only as long as the slowest path could reasonably deliver the missing packet. The adaptive timeout based on measured path latency spread ensures the buffer doesn't wait longer than necessary.
 ### 3.3 Gap Skip Behavior
 When a gap's deadline expires:
 1. Mark the missing sequence number as skipped.
 2. Deliver all contiguous packets after the gap to the TUN device.
 3. If the missing packet arrives later, **drop it.** The inner protocol (TCP) will retransmit if the data was needed. Inner UDP never expected reliability.
 **Design choice:** Drop late packets after gap skip.
 **Alternative: Deliver late packets out-of-order.** Would create a second reordering event for the inner TCP. Worse than dropping — inner TCP handles loss (via retransmission) better than reordering (via false fast retransmits).
 **Alternative: Never skip gaps, buffer grows unbounded.** A genuinely lost packet blocks all future delivery. Unacceptable.
 ### 3.4 Buffer Depth Limit
 The reordering buffer has a maximum depth of `MAX_REORDERING_DEPTH = 128` packets. This limits memory usage and bounds the maximum reordering that the inner traffic can observe.
 When the buffer is full (128 packets waiting for a gap):
 1. The oldest gap is force-skipped.
 2. All contiguous packets after it are delivered.
 3. This may cause the inner TCP to see a loss event.
 **Design choice:** Aggressive depth of 128 packets.
 **Alternative: Conservative depth (8-16 packets).** Minimizes inner TCP disruption but severely limits bandwidth aggregation. A 16-packet buffer at 1500 bytes/packet is only 24KB — this fills in under 1ms at even moderate data rates, effectively preventing the scheduler from using slower paths.
 **Alternative: Moderate depth (32-64 packets).** Better bandwidth utilization with moderate reordering. Likely sufficient for paths with small RTT differences (e.g., 5G and WiFi both under 50ms).
 **Alternative: Unlimited depth.** No forced skips. Only gap deadlines cause skips. But a sustained high-rate flow with one dead path would cause the buffer to grow without bound.
 **Rationale for 128:** Linux auto-tunes `tcp_reordering` up to 127 based on observed reordering. With MAX_REORDERING_DEPTH = 128, Linux inner TCP will generally tolerate the reordering without false fast retransmits. Non-Linux stacks (Windows, macOS) may see some false retransmits — this is a known tradeoff that test benching will quantify.
 ### 3.5 Buffer Memory
 At 1500 bytes per packet and depth 128: ~192KB per peer session. For a network of 50 peers: ~9.6MB. Acceptable.
 ## 4. Scheduler
 ### 4.1 Weighted Round-Robin
 The scheduler assigns a weight to each path proportional to its estimated bandwidth. It uses a credit system to distribute packets across paths according to these weights.
 **Algorithm:**
 Each path maintains:
 - `weight`: integer, proportional to estimated bandwidth
 - `credits`: integer, number of packets this path is owed
 **On each scheduling decision (send one packet):**
 ```
 1. Select the path with the highest credits among paths with credits > 0.
 2. Tie-break: lowest estimated one-way latency.
 3. Decrement selected path's credits by 1.
 4. If no path has credits > 0, replenish all paths and retry.
 ```
 **Credit replenishment (runs when all credits are exhausted, or periodically):**
 ```
 For each path:
    credits += weight
 ```
 **Weight calculation:**
 ```
 For each path:
    estimated_bw = measured bytes/sec over rolling window (1 second)
    weight = max(1, round(estimated_bw / BASE_RATE))
 BASE_RATE = estimated bandwidth of the slowest active path
 ```
 This ensures the slowest path always has weight ≥ 1, and faster paths are weighted proportionally.
 **Design choice:** Weighted round-robin with credits.
 **Alternative: Strict round-robin.** Every path gets one packet in turn. Simple but ignores bandwidth differences — a 100 Mbps path gets the same packet rate as a 10 Mbps path, causing the fast path to be underutilized and the slow path to queue.
 **Alternative: minRTT (always send on fastest path).** Minimal reordering, no buffer complexity. But a single flow can't exceed one path's capacity. Defeats the purpose of multipath.
 **Alternative: Deadline-aware scheduling.** Assign each packet a "latest acceptable delivery time" based on reordering constraints, then pick the path that delivers soonest within the deadline. More optimal but requires latency prediction per path and is harder to reason about and debug.
 **Alternative: BLEST (Blocked Estimation Scheduling from MPTCP).** Estimates how many packets can be sent on a slow path before they'd block the reordering buffer. Designed for reliable transport with retransmission — its estimates assume packets will eventually be delivered, which is true in MPTCP but not in Whalescale's unreliable transport.
 **Rationale:** Weighted round-robin is simple, predictable, and adjustable. It's the right starting point for test benching — easy to implement, easy to reason about, and easy to replace with a more sophisticated scheduler later. The credit system ensures proportional bandwidth utilization without requiring per-packet latency prediction.
 ### 4.2 Reordering Depth Constraint
 Before sending a packet on the selected path, the scheduler checks:
 ```
 reordering_depth = number of packets in-flight on slower paths that haven't been ACKed yet
 if reordering_depth > MAX_REORDERING_DEPTH:
    // Don't send on this path — it would advance too far ahead
    // Try the next-best path, or wait
 ```
 This prevents the fast path from getting so far ahead that the reordering buffer would exceed its depth limit.
 **Design choice:** Global reordering depth limit applied at the sender.
 **Alternative: No sender-side constraint, rely entirely on receiver buffer depth limit.** Simpler sender, but receiver must force-skip gaps more often, causing more inner TCP disruption.
 **Alternative: Per-flow reordering depth limits.** Different limits for different inner flows based on their observed tolerance. Requires flow classification and per-flow state — complex.
 **Rationale:** The sender-side constraint is a backpressure mechanism — it prevents the problem rather than reacting to it. Complementary to the receiver's depth limit.
 ### 4.3 Path Priority
 When credit counts are equal (or on tie-break), the scheduler prefers:
 1. IPv6 paths over IPv4 paths (no NAT, lower latency variance)
 2. Lower one-way latency
 3. Higher estimated bandwidth
 This ensures IPv6 is preferred when available and performant.
 ## 5. Path Bandwidth Estimation
 ### 5.1 Rolling Window Measurement
 Each path tracks bytes sent and acknowledged over a rolling 1-second window. Estimated bandwidth is:
 ```
 estimated_bw = bytes_acked_in_last_second / 1.0
 ```
 **Design choice:** Simple rolling window over ACKed bytes.
 **Alternative: Packet-pair estimation.** Send two probe packets back-to-back, measure inter-arrival time at receiver. More responsive to sudden bandwidth changes but noisy and requires probe traffic.
 **Alternative: BBR-style bandwidth estimation.** Model bandwidth and RTT, adapt sending rate. Designed for congestion control, not for scheduling weights. Overkill for this purpose.
 **Alternative: Sender-side bytes-sent only.** No ACK feedback needed. But doesn't account for loss — a path may have packets sent but dropping, inflating the estimate.
 **Rationale:** Rolling window over ACKed bytes accounts for loss (lost packets aren't ACKed), is simple to implement, and provides stable estimates for scheduling weights. The 1-second window smooths transient fluctuations. Test benching should compare responsiveness of different window sizes (250ms, 500ms, 1s, 2s).
 ### 5.2 Initial Bandwidth Estimate
 When a path is first added, its bandwidth is unknown. Initial behavior:
 1. Start with `weight = 1` (minimum, same as the slowest path).
 2. Send probe traffic (`PROBE` packets) to measure initial RTT.
 3. After the first ACK round-trip, set `weight` based on the initial throughput measurement.
 4. Allow full scheduling after 2-3 ACK rounds (2-3 seconds) when estimates stabilize.
 This prevents a new path from being overloaded before its capacity is known.
 ## 6. Feedback Loop
 ### 6.1 ACK Frequency
 ACKs are sent:
 - Every 100ms (periodic), OR
 - Every 200 DATA packets received (volume-based), whichever comes first.
 **Design choice:** Dual trigger (time and volume).
 **Alternative: Pure periodic (fixed interval).** At high packet rates, 100ms between ACKs means the sender's view of the receiver's state is 100ms stale. At low packet rates, periodic ACKs waste bandwidth.
 **Alternative: Pure volume-based (every N packets).** At low packet rates, ACKs may not be sent for seconds. At high rates, ACKs may be sent too frequently, consuming bandwidth.
 **Rationale:** The dual trigger ensures ACKs are sent frequently enough for good scheduling decisions (time-based floor) and not too frequently at high rates (volume-based ceiling).
 ### 6.2 What the Sender Does with ACKs
 On receiving an ACK:
 1. **Update per-path stats:** packets received, estimated latency, loss count, flags.
 2. **Recalculate path weights** based on updated bandwidth estimates.
 3. **Check reordering depth:** If `Highest Contiguous Sequence` isn't advancing, the reordering buffer is backing up. Reduce credits on fast paths to allow slow paths to catch up.
 4. **Detect path degradation:** If a path is flagged as degraded, reduce its weight. If flagged as failed, remove it from scheduling.
 ### 6.3 What the Sender Does WITHOUT ACKs
 If no ACK is received from a peer for `3 × ACK_INTERVAL` (300ms), the sender:
 1. Probes all paths with `PROBE` packets.
 2. If some paths respond and others don't, degrade the non-responsive paths.
 3. If no paths respond, the entire session may be down — trigger connection recovery.
 ## 7. Inner TCP Interaction
 ### 7.1 The Problem
 When Whalescale reorders packets across paths, the inner TCP (running inside the VPN tunnel) may interpret out-of-order delivery as loss:
 - **3 duplicate ACKs → fast retransmit:** Wastes bandwidth on redundant retransmission.
 - **Retransmission timeout → congestion window collapse:** Severe throughput degradation lasting seconds.
 ### 7.2 Mitigation: Reordering Buffer
 The primary mitigation. If the buffer delivers packets in order to the TUN device, the inner TCP never knows multipath is happening. The buffer must release the missing packet before the inner TCP's loss detection triggers.
 ### 7.3 Known Tradeoff: Aggressive Reordering Depth
 With `MAX_REORDERING_DEPTH = 128`:
 - **Linux inner TCP:** Auto-tunes `tcp_reordering` up to 127. Will generally tolerate 128 out-of-order packets without false fast retransmits. Well-behaved.
 - **Windows inner TCP:** `TcpReordering` is not well-documented but generally tolerates moderate reordering. May see some false retransmits with 128-packet reordering.
 - **macOS inner TCP:** Similar to Windows — moderate tolerance, some false retransmits likely.
 - **Inner UDP:** Not affected — UDP has no reordering detection. Application-level jitter buffers handle it.
 **Design choice:** Accept some false retransmits on non-Linux platforms as a performance tradeoff.
 **Alternative: Conservative depth (8-16).** Eliminates false retransmits on all platforms but severely limits bandwidth aggregation. Not worth the cost for the primary use case.
 **Rationale:** Linux is the primary deployment target (servers, embedded, Android). Windows/macOS are secondary. The performance gain from aggressive multipath outweighs occasional false retransmits.
 ### 7.4 Monitoring
 The reordering buffer tracks:
 - **Gap skip rate:** How often gaps are force-skipped (indicates reordering exceeding the timeout)
 - **Late packet drop rate:** How often late packets arrive after their gap was skipped (indicates timeout was too short)
 - **Average buffer depth:** How many packets are typically in the buffer (indicates path latency spread)
 These metrics are exposed via the agent's status interface and should be used during test benching to evaluate scheduler performance and tune parameters.
 ### 7.5 Open Research Question
 Can Whalescale infer the inner TCP's RTT estimate from packet timing patterns (e.g., observing burst patterns that indicate TCP congestion window growth)? If so, the reordering timeout could be set relative to the inner TCP's RTT, providing a tighter bound. This is uncharted territory — test benching with packet captures will determine if the signal is extractable.
 ## 8. MTU Handling
 ### 8.1 Strategy: Minimum Path MTU
 The VPN interface MTU is set to the minimum MTU across all active paths for a given session:
 ```
 vpn_mtu = min(path_mtu for all active paths in session)
 vpn_mtu -= TRANSPORT_OVERHEAD  // Whalescale header + Noise_IK overhead
 ```
 When paths are added or removed, the VPN MTU is recalculated. If a path with a smaller MTU is added, the VPN MTU decreases. If the smallest-MTU path is removed, the VPN MTU increases.
 **Design choice:** Minimum path MTU across all paths.
 **Alternative: Per-path MTU with fragmentation.** Send full-size packets on high-MTU paths, fragment on low-MTU paths. Maximizes throughput on high-MTU paths but fragmentation is expensive, increases loss sensitivity (any fragment loss loses the whole packet), and interacts badly with inner TCP MSS negotiation.
 **Alternative: Per-path MTU with inner MSS clamping.** Advertise different MSS to different inner TCP connections based on which path they'd use. Requires flow-level scheduling (contradicts packet-level design) and deep packet inspection of inner TCP SYN packets.
 **Rationale:** Minimum path MTU is simple, correct, and the performance cost is small (a few percent of capacity). The added complexity of per-path MTU is not justified for the target use case.
 ### 8.2 Path MTU Discovery
 On path establishment:
 1. Start with the local network interface MTU (e.g., 1500 for Ethernet, 1492 for PPPoE).
 2. Subtract UDP/IP overhead (28 bytes for IPv4, 48 bytes for IPv6).
 3. Subtract Whalescale transport header (16 bytes) and Noise_IK overhead.
 4. Optionally send PMTU probes (increasingly large PROBE packets) to confirm the path can carry the estimated MTU. If a probe is not acknowledged, reduce the path MTU.
 ### 8.3 VPN MTU Changes
 When the VPN MTU changes:
 - Notify the OS via the TUN device's MTU setting.
 - Inner TCP connections will adapt to the new MSS on new connections. Existing connections continue with their negotiated MSS — packets may need fragmentation at the Whalescale layer if they exceed the new path MTU. This is a rare event (only when a new, smaller-MTU path is added mid-session).
 ## 9. Path Failure Detection
 ### 9.1 Heartbeat-Based Detection
 Each path sends a `HEARTBEAT` control message every 1 second. If 3 consecutive heartbeats on a path are not acknowledged (3 seconds without any traffic on that path), the path is marked as **failed**.
 ### 9.2 Data-Driven Detection
 If no packets (DATA or CONTROL) have been received on a path for `2 × path_estimated_RTT`, and the heartbeat timer hasn't triggered yet, send an immediate `PROBE`. If no response within another `path_estimated_RTT`, mark the path as **degraded**.
 ### 9.3 Degradation vs. Failure
 | State | Definition | Scheduler Action |
 |-------|-----------|-----------------|
 | Healthy | Normal RTT and loss | Full weight |
 | Degraded | High RTT or elevated loss | Reduced weight (50% of estimated bandwidth) |
 | Failed | No traffic for 3 heartbeats | Removed from scheduling entirely |
 **Design choice:** Three-state path health model.
 **Alternative: Binary (healthy/failed).** Simpler but doesn't handle the common case of a path that's slow (e.g., cellular handover) but still working. Prematurely removing a path wastes its remaining bandwidth and forces all traffic onto other paths.
 **Alternative: Continuous weight based on loss rate.** No discrete states — weight is a continuous function of measured loss. More granular but harder to reason about and debug.
 **Rationale:** The three-state model captures the important distinction between "slow but working" and "actually dead." Degraded paths still contribute bandwidth at reduced scheduling intensity.
 ### 9.4 Buffer Flush on Path Failure
 When a path is marked as failed:
 1. The receiver force-skips all gaps attributed to the failed path.
 2. The sender removes the path from scheduling and redistributes weight to remaining paths.
 3. Any packets in flight on the failed path at the time of failure detection are assumed lost.
 This is critical — without flushing, the reordering buffer blocks indefinitely waiting for packets from a dead path.
 ### 9.5 Path Recovery
 A failed path is not permanently removed. It is moved to a recovery queue:
 1. The sender periodically (every 30 seconds) sends a `PROBE` to the failed path's last known endpoint.
 2. If the probe is answered, the path is re-added as degraded, with weight = 1.
 3. Normal bandwidth estimation resumes. If the path performs well, it transitions to healthy.
 This handles the case where a path fails due to temporary network issues (e.g., WiFi reconnect) and recovers later.
 ## 10. Path Lifecycle
 ### 10.1 Discovery
 Candidate paths are discovered through:
 1. **Local interface enumeration:** The agent lists all local network interfaces and their addresses (IPv4 and IPv6).
 2. **Anchor-observed addresses:** Anchor nodes report the external IP:port they observe for a peer.
 3. **PATH_ANNOUNCE messages:** Connected peers advertise their available interfaces and observed external addresses to each other.
 4. **LAN discovery:** mDNS or broadcast for same-network peers.
 ### 10.2 NAT Traversal
 For each candidate path:
 1. If the remote endpoint is known (from PATH_ANNOUNCE or LKG cache), send a `PATH_PROBE` to that endpoint.
 2. If behind NAT, perform UDP hole punching as described in DESIGN.md §3.7.
 3. If UPnP/NAT-PMP/PCP is available, request a port mapping proactively.
 ### 10.3 Probing
 Before a path is used for data, it must be probed:
 1. Send `PATH_PROBE` packets, measure RTT from the response.
 2. Send a small burst of DATA packets at a conservative rate to estimate initial bandwidth.
 3. After 2-3 probe rounds (2-3 seconds), the path transitions to active.
 ### 10.4 Monitoring
 Active paths are continuously monitored:
 - **RTT:** Measured from PROBE round-trips and from data packet timing.
 - **Loss rate:** Tracked from ACK feedback (packets sent vs. packets acknowledged per path).
 - **Throughput:** Rolling 1-second window of bytes ACKed.
 ### 10.5 Addition
 When a new path is added to a session:
 1. Assign it a Path ID.
 2. Start with weight = 1, credits = 0.
 3. Begin probing (RTT measurement, initial bandwidth estimate).
 4. After probing completes, set weight based on estimated bandwidth and begin scheduling.
 5. Recalculate VPN MTU if the new path has a smaller MTU than the current minimum.
 ### 10.6 Removal
 When a path is removed from a session:
 1. Stop scheduling new packets on the path.
 2. Wait for in-flight packets to be acknowledged (up to `path_RTT` timeout).
 3. Force-skip any gaps from unacknowledged packets.
 4. Remove the path from the session.
 5. Recalculate VPN MTU.
 6. Redistribute weight to remaining paths.
 ### 10.7 Interface Events
 The agent monitors OS-level network interface events:
 - **Interface up:** Begin discovery and NAT traversal for new paths on this interface.
 - **Interface down:** Remove all paths associated with this interface, flush their gaps.
 - **Address change:** Treat as a new path candidate (new address) + removal of old path (old address).
 - **IPv6 address added:** Immediately attempt IPv6 path — this is high-priority due to NAT elimination.
 ## 11. Test Bench Framework
 The multipath subsystem has significant open questions that require empirical validation. The following scenarios should be benchmarked:
 ### 11.1 Scheduler Comparison
 Implement each scheduler as a swappable component and measure:
 | Scheduler | Metrics |
 |-----------|---------|
 | Weighted round-robin (chosen) | Throughput, reordering depth, inner TCP goodput |
 | Strict round-robin | Same metrics (expected: lower throughput on asymmetric paths) |
 | minRTT | Same metrics (expected: no aggregation, minimal reordering) |
 | BLEST-adapted | Same metrics (expected: better on asymmetric paths, but designed for reliable transport) |
 | Random (baseline) | Same metrics (lower bound on performance) |
 ### 11.2 Reordering Depth Tuning
 Vary `MAX_REORDERING_DEPTH` across {8, 16, 32, 64, 128, 256} and measure:
 - Inner TCP goodput (iperf3 inside the tunnel)
 - Inner TCP retransmit rate (captured from inner TCP stats)
 - Gap skip rate (from Whalescale reordering buffer metrics)
 - End-to-end latency for inner UDP traffic
 ### 11.3 Path Latency Spread
 Test with paths of different RTT spreads:
 - Same-RTT paths (e.g., two WiFi connections): minimal reordering expected
 - Moderate spread (e.g., 20ms WiFi + 50ms 5G): common real-world case
 - Large spread (e.g., 20ms WiFi + 200ms satellite): extreme case, high reordering
 - One path with high jitter: tests timeout calculation robustness
 ### 11.4 Path Failure Scenarios
 - Sudden path failure (disconnect WiFi during transfer)
 - Gradual degradation (increasing loss rate on one path)
 - Path recovery (WiFi reconnect after failure)
 - All-but-one path failure (stress test for failover)
 ### 11.5 Inner Traffic Types
 - Single long-lived TCP flow (iperf3): tests reordering impact on TCP congestion control
 - Multiple concurrent TCP flows: tests scheduler fairness
 - UDP traffic (VoIP, gaming): tests latency and jitter impact
 - Mixed TCP + UDP: tests scheduler prioritization
 ### 11.6 Real-World Mobile Scenarios
 - 5G + WiFi on a mobile device (the primary use case)
 - WiFi + Ethernet on a laptop
 - IPv4 + IPv6 dual-stack (IPv6 preferred, IPv4 fallback)
 - Cellular handover between towers (path RTT changes mid-flow)
--- a/crates/whalescale-agent/Cargo.toml
+++ b/crates/whalescale-agent/Cargo.toml
@ -0,0 +1,17 @@
 [package]
 name = "whalescale-agent"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-session.workspace = true
 whalescale-transport.workspace = true
 whalescale-path.workspace = true
 whalescale-multipath.workspace = true
 whalescale-gossip.workspace = true
 whalescale-nat.workspace = true
 whalescale-anchor.workspace = true
 whalescale-tun.workspace = true
 whalescale-bootstrap.workspace = true
 whalescale-crypto.workspace = true
 whalescale-types.workspace = true
--- a/crates/whalescale-agent/src/main.rs
+++ b/crates/whalescale-agent/src/main.rs
@ -0,0 +1,4 @@
 fn main() {
    println!("Hello from Whalescale agent");
 }
--- a/crates/whalescale-anchor/Cargo.toml
+++ b/crates/whalescale-anchor/Cargo.toml
@ -0,0 +1,9 @@
 [package]
 name = "whalescale-anchor"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-gossip.workspace = true
 whalescale-transport.workspace = true
 whalescale-types.workspace = true
--- a/crates/whalescale-anchor/src/lib.rs
+++ b/crates/whalescale-anchor/src/lib.rs
@ -0,0 +1 @@
 //! Anchor management, relay forwarding, mutual keepalive
--- a/crates/whalescale-bootstrap/Cargo.toml
+++ b/crates/whalescale-bootstrap/Cargo.toml
@ -0,0 +1,9 @@
 [package]
 name = "whalescale-bootstrap"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-crypto.workspace = true
 whalescale-transport.workspace = true
 whalescale-types.workspace = true
--- a/crates/whalescale-bootstrap/src/lib.rs
+++ b/crates/whalescale-bootstrap/src/lib.rs
@ -0,0 +1 @@
 //! Pre-session discovery protocol, manual bootstrap
--- a/crates/whalescale-crypto/Cargo.toml
+++ b/crates/whalescale-crypto/Cargo.toml
@ -0,0 +1,16 @@
 [package]
 name = "whalescale-crypto"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-types.workspace = true
 snow = "0.10"
 curve25519-dalek = "4"
 ed25519-dalek = { version = "2", features = ["rand_core"] }
 x25519-dalek = { version = "2", features = ["static_secrets"] }
 rand = "0.8"
 thiserror = "1"
 [dev-dependencies]
 rand_core = "0.6"
--- a/crates/whalescale-crypto/src/lib.rs
+++ b/crates/whalescale-crypto/src/lib.rs
@ -0,0 +1,707 @@
 //! Ed25519 key management and Noise library integration.
 use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
 use rand::rngs::OsRng;
 use thiserror::Error;
 use whalescale_types::{NodeId, PROLOGUE};
 use x25519_dalek::{PublicKey as X25519PublicKey, StaticSecret as X25519StaticSecret};
 /// Errors from crypto operations
 #[derive(Error, Debug)]
 pub enum CryptoError {
    #[error("snow error: {0}")]
    Snow(#[from] snow::Error),
    #[error("invalid key: {0}")]
    InvalidKey(&'static str),
    #[error("invalid payload: {0}")]
    InvalidPayload(&'static str),
    #[error("handshake not complete")]
    HandshakeIncomplete,
    #[error("decryption failed")]
    DecryptionFailed,
    #[error("session exhausted")]
    SessionExhausted,
 }
 /// Convert an Ed25519 public key to X25519 public key
 /// Uses Montgomery form: ed25519 -> Curve25519
 pub fn ed25519_to_x25519_public(ed25519_public: &[u8; 32]) -> [u8; 32] {
    let verifying_key =
        VerifyingKey::from_bytes(ed25519_public).expect("invalid ed25519 public key");
    // Convert Ed25519 point to Montgomery u-coordinate
    // This is the standard conversion used by libsodium and others
    let montgomery_u = curve25519_dalek::edwards::CompressedEdwardsY(verifying_key.to_bytes())
        .decompress()
        .map(|edwards| edwards.to_montgomery())
        .map(|montgomery| montgomery.0);
    match montgomery_u {
        Some(u) => u,
        None => {
            // Invalid point - return zeros (this should never happen with valid keys)
            [0u8; 32]
        }
    }
 }
 /// Convert an Ed25519 private key to X25519 private key
 /// The Ed25519 private key (32 bytes) is expanded via SHA-512
 /// The first 32 bytes are the scalar, which we use directly for X25519
 pub fn ed25519_to_x25519_private(ed25519_private: &[u8; 32]) -> [u8; 32] {
    use ed25519_dalek::SecretKey;
    let secret_key = SecretKey::from(*ed25519_private);
    let signing_key = SigningKey::from(&secret_key);
    // Get the scalar bytes directly from the expanded secret key
    // For ed25519-dalek 2.x, we access via to_scalar_bytes()
    signing_key.to_scalar_bytes()
 }
 /// Identity keypair: Ed25519 for identity, derived X25519 for Noise DH
 #[derive(Clone)]
 pub struct IdentityKeypair {
    ed25519_signing: SigningKey,
    ed25519_verifying: VerifyingKey,
    x25519_static: X25519StaticSecret,
 }
 impl IdentityKeypair {
    /// Generate a new identity keypair
    pub fn generate() -> Self {
        let mut csprng = OsRng;
        let signing_key = SigningKey::generate(&mut csprng);
        let verifying_key = signing_key.verifying_key();
        // Derive X25519 key from Ed25519 private key
        let ed25519_private = signing_key.to_scalar_bytes();
        let x25519_static = X25519StaticSecret::from(ed25519_private);
        Self {
            ed25519_signing: signing_key,
            ed25519_verifying: verifying_key,
            x25519_static,
        }
    }
    /// Load from existing Ed25519 private key (32 bytes)
    pub fn from_private_key(private_key: &[u8; 32]) -> Self {
        let secret_key = ed25519_dalek::SecretKey::from(*private_key);
        let signing_key = SigningKey::from(&secret_key);
        let verifying_key = signing_key.verifying_key();
        let ed25519_private = signing_key.to_scalar_bytes();
        let x25519_static = X25519StaticSecret::from(ed25519_private);
        Self {
            ed25519_signing: signing_key,
            ed25519_verifying: verifying_key,
            x25519_static,
        }
    }
    /// Get the NodeId (Ed25519 public key)
    pub fn node_id(&self) -> NodeId {
        NodeId::new(self.ed25519_verifying.to_bytes())
    }
    /// Get Ed25519 public key bytes
    pub fn ed25519_public(&self) -> [u8; 32] {
        self.ed25519_verifying.to_bytes()
    }
    /// Get X25519 public key bytes
    pub fn x25519_public(&self) -> [u8; 32] {
        X25519PublicKey::from(&self.x25519_static).to_bytes()
    }
    /// Get X25519 private key bytes (for Noise)
    pub fn x25519_private(&self) -> [u8; 32] {
        // X25519StaticSecret doesn't expose the bytes directly
        // We need to re-derive from our stored Ed25519-derived scalar
        // For this, we recompute from the Ed25519 signing key
        self.ed25519_signing.to_scalar_bytes()
    }
    /// Sign a message with Ed25519
    pub fn sign(&self, message: &[u8]) -> [u8; 64] {
        let signature: Signature = self.ed25519_signing.sign(message);
        signature.to_bytes()
    }
    /// Verify a signature
    pub fn verify(
        public_key: &[u8; 32],
        message: &[u8],
        signature: &[u8; 64],
    ) -> Result<(), CryptoError> {
        let verifying_key = VerifyingKey::from_bytes(public_key)
            .map_err(|_| CryptoError::InvalidKey("invalid public key"))?;
        let sig = Signature::from_bytes(signature);
        verifying_key
            .verify(message, &sig)
            .map_err(|_| CryptoError::InvalidPayload("signature verification failed"))
    }
 }
 /// Noise handshake state wrapper for initiator
 pub struct NoiseInitiator {
    state: snow::HandshakeState,
    remote_public_key: [u8; 32],
 }
 impl NoiseInitiator {
    /// Create a new initiator with remote static X25519 public key
    pub fn new(
        identity: &IdentityKeypair,
        remote_x25519_public: &[u8; 32],
    ) -> Result<Self, CryptoError> {
        let params: snow::params::NoiseParams = "Noise_IK_25519_ChaChaPoly_BLAKE2s"
            .parse()
            .map_err(|_| CryptoError::InvalidKey("invalid noise params"))?;
        let private_key = identity.x25519_private();
        let builder = snow::Builder::new(params)
            .prologue(PROLOGUE)?
            .local_private_key(&private_key)?
            .remote_public_key(remote_x25519_public);
        let state = builder?.build_initiator()?;
        Ok(Self {
            state: state,
            remote_public_key: *remote_x25519_public,
        })
    }
    /// Perform one step of the handshake
    /// Returns: (bytes to send, optional transport if handshake complete)
    pub fn step(
        &mut self,
        payload: &[u8],
    ) -> Result<(Vec<u8>, Option<NoiseTransport>), CryptoError> {
        if self.state.is_handshake_finished() {
            return Err(CryptoError::HandshakeIncomplete);
        }
        let mut buf = vec![0u8; 65535];
        let len = self.state.write_message(payload, &mut buf)?;
        buf.truncate(len);
        if self.state.is_handshake_finished() {
            let transport = self.state.into_stateless_transport_mode()?;
            Ok((buf, Some(NoiseTransport { inner: transport })))
        } else {
            Ok((buf, None))
        }
    }
    /// Check if handshake is complete
    pub fn is_complete(&self) -> bool {
        self.state.is_handshake_finished()
    }
    /// Get remote public key
    pub fn remote_public_key(&self) -> &[u8; 32] {
        &self.remote_public_key
    }
 }
 /// Noise handshake state wrapper for responder
 pub struct NoiseResponder {
    state: snow::HandshakeState,
    remote_public_key: Option<[u8; 32]>,
 }
 impl NoiseResponder {
    /// Create a new responder (waits for remote public key during handshake)
    pub fn new(identity: &IdentityKeypair) -> Result<Self, CryptoError> {
        let params: snow::params::NoiseParams = "Noise_IK_25519_ChaChaPoly_BLAKE2s"
            .parse()
            .map_err(|_| CryptoError::InvalidKey("invalid noise params"))?;
        let private_key = identity.x25519_private();
        let builder = snow::Builder::new(params)
            .prologue(PROLOGUE)?
            .local_private_key(&private_key);
        let state = builder?.build_responder()?;
        Ok(Self {
            state,
            remote_public_key: None,
        })
    }
    /// Perform one step of the handshake
    /// Returns: (bytes to send, optional transport if handshake complete)
    pub fn step(
        &mut self,
        payload: &[u8],
    ) -> Result<(Vec<u8>, Option<NoiseTransport>), CryptoError> {
        if self.state.is_handshake_finished() {
            return Err(CryptoError::HandshakeIncomplete);
        }
        let mut buf = vec![0u8; 65535];
        let len = self.state.read_message(payload, &mut buf)?;
        buf.truncate(len);
        // Store the remote public key if we just processed the first message
        if self.remote_public_key.is_none() {
            // In Noise_IK, the initiator's static key is sent in the first message
            // Snow doesn't expose this directly, but it's authenticated after read_message
            // For now, we rely on the handshake completing successfully
            // In a real implementation, we'd want to extract the initiator's public key
            self.remote_public_key = Some([0u8; 32]); // Placeholder
        }
        if self.state.is_handshake_finished() {
            let transport = self.state.into_stateless_transport_mode()?;
            Ok((buf, Some(NoiseTransport { inner: transport })))
        } else {
            Ok((buf, None))
        }
    }
    /// Check if handshake is complete
    pub fn is_complete(&self) -> bool {
        self.state.is_handshake_finished()
    }
    /// Get remote public key (available after first handshake message)
    pub fn remote_public_key(&self) -> Option<&[u8; 32]> {
        self.remote_public_key.as_ref()
    }
 }
 /// Noise transport state (post-handshake encryption/decryption)
 pub struct NoiseTransport {
    inner: snow::StatelessTransportState,
 }
 impl NoiseTransport {
    /// Encrypt a payload with the given nonce/sequence number
    /// Returns: ciphertext + 16-byte AEAD tag
    pub fn encrypt(&self, nonce: u64, plaintext: &[u8]) -> Result<Vec<u8>, CryptoError> {
        // Allocate a buffer large enough for ciphertext + 16-byte AEAD tag
        let mut buf = vec![0u8; plaintext.len() + 16];
        let len = self
            .inner
            .write_message(nonce, plaintext, &mut buf)
            .map_err(|_| CryptoError::InvalidPayload("encryption failed"))?;
        buf.truncate(len);
        Ok(buf)
    }
    /// Decrypt a payload with the given nonce/sequence number
    /// Returns: plaintext
    pub fn decrypt(&self, nonce: u64, ciphertext: &[u8]) -> Result<Vec<u8>, CryptoError> {
        // Allocate a buffer large enough for plaintext (ciphertext - tag)
        let mut buf = vec![0u8; ciphertext.len()];
        let len = self
            .inner
            .read_message(nonce, ciphertext, &mut buf)
            .map_err(|_| CryptoError::DecryptionFailed)?;
        buf.truncate(len);
        Ok(buf)
    }
    /// Rekey the outgoing direction (sender)
    pub fn rekey_outgoing(&self) {
        // Note: snow's StatelessTransportState doesn't have rekey methods
        // We need to manually manage rekeying through the snow state
        // For Phase 1, we'll implement rekey by creating a new session
        // This is a stub - full rekey implementation in session layer
    }
    /// Rekey the incoming direction (receiver)
    pub fn rekey_incoming(&self) {
        // Same as above - stub for now
    }
    /// Check if nonce space is exhausted
    pub fn is_exhausted(&self) -> bool {
        // In stateless mode, we manage nonces externally (64-bit)
        // Exhaustion at 2^64 is not practically reachable
        false
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn test_identity_keypair_generation() {
        let keypair = IdentityKeypair::generate();
        let node_id = keypair.node_id();
        assert_eq!(node_id.as_bytes().len(), 32);
        // Verify keys are non-zero
        assert!(!keypair.ed25519_public().iter().all(|&b| b == 0));
        assert!(!keypair.x25519_public().iter().all(|&b| b == 0));
    }
    #[test]
    fn test_key_conversion_consistency() {
        // Generate an Ed25519 keypair
        let identity = IdentityKeypair::generate();
        let ed25519_pub = identity.ed25519_public();
        let x25519_pub = identity.x25519_public();
        // Convert Ed25519 public to X25519 and verify it matches
        let converted = ed25519_to_x25519_public(&ed25519_pub);
        assert_eq!(x25519_pub, converted);
    }
    #[test]
    fn test_sign_and_verify() {
        let identity = IdentityKeypair::generate();
        let message = b"test message";
        let signature = identity.sign(message);
        // Verify with correct key
        let result = IdentityKeypair::verify(&identity.ed25519_public(), message, &signature);
        assert!(result.is_ok());
        // Verify with wrong message
        let result =
            IdentityKeypair::verify(&identity.ed25519_public(), b"wrong message", &signature);
        assert!(result.is_err());
    }
    #[test]
    fn test_noise_ik_handshake_in_memory() {
        // Generate two identities
        let identity_a = IdentityKeypair::generate();
        let identity_b = IdentityKeypair::generate();
        // A initiates to B (A knows B's X25519 public key)
        let mut initiator = NoiseInitiator::new(&identity_a, &identity_b.x25519_public()).unwrap();
        // B responds
        let mut responder = NoiseResponder::new(&identity_b).unwrap();
        // Step 1: A -> B (handshake init)
        let (msg1, transport_a) = initiator.step(b"").unwrap();
        assert!(transport_a.is_none()); // Not complete yet
        // Step 2: B processes init, sends response
        let (msg2, transport_b) = responder.step(&msg1).unwrap();
        assert!(transport_b.is_some()); // Responder is done
        let transport_b = transport_b.unwrap();
        // Step 3: A processes response
        // For initiator, we need a new mechanism to read the response
        // Since initiator consumed itself in step(), we need to handle this differently
        // In the actual implementation, the initiator would keep state
        // For this test, we verify the responder is ready
        // Note: The current API design has a limitation - the initiator's step()
        // method consumes the handshake state. We need a different approach.
        // For now, we verify the responder side works.
    }
    #[test]
    fn test_full_handshake_roundtrip() {
        // This test demonstrates the full handshake flow
        // using snow's lower-level API directly
        let identity_a = IdentityKeypair::generate();
        let identity_b = IdentityKeypair::generate();
        let params: snow::params::NoiseParams =
            "Noise_IK_25519_ChaChaPoly_BLAKE2s".parse().unwrap();
        // Create initiator
        let mut initiator = snow::Builder::new(params.clone())
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_a.x25519_private())
            .unwrap()
            .remote_public_key(&identity_b.x25519_public())
            .unwrap()
            .build_initiator()
            .unwrap();
        // Create responder
        let mut responder = snow::Builder::new(params)
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_b.x25519_private())
            .unwrap()
            .build_responder()
            .unwrap();
        // Message 1: Initiator -> Responder
        let mut msg1 = vec![0u8; 65535];
        let len1 = initiator.write_message(b"", &mut msg1).unwrap();
        msg1.truncate(len1);
        assert!(!initiator.is_handshake_finished());
        // Responder processes message 1
        let mut payload1 = vec![0u8; 65535];
        let len1_resp = responder.read_message(&msg1, &mut payload1).unwrap();
        payload1.truncate(len1_resp);
        assert!(!responder.is_handshake_finished());
        // Message 2: Responder -> Initiator
        let mut msg2 = vec![0u8; 65535];
        let len2 = responder.write_message(b"", &mut msg2).unwrap();
        msg2.truncate(len2);
        assert!(responder.is_handshake_finished());
        // Initiator processes message 2
        let mut payload2 = vec![0u8; 65535];
        let len2_resp = initiator.read_message(&msg2, &mut payload2).unwrap();
        payload2.truncate(len2_resp);
        assert!(initiator.is_handshake_finished());
        // Both sides have completed the handshake
        // Convert to transport mode
        let transport_a = initiator.into_stateless_transport_mode().unwrap();
        let transport_b = responder.into_stateless_transport_mode().unwrap();
        // Test encryption/decryption
        let plaintext = b"hello from A to B";
        let nonce = 1u64;
        let mut ciphertext_buf = vec![0u8; plaintext.len() + 16];
        let ct_len = transport_a
            .write_message(nonce, plaintext, &mut ciphertext_buf)
            .unwrap();
        ciphertext_buf.truncate(ct_len);
        let mut decrypted_buf = vec![0u8; ciphertext_buf.len()];
        let pt_len = transport_b
            .read_message(nonce, &ciphertext_buf, &mut decrypted_buf)
            .unwrap();
        decrypted_buf.truncate(pt_len);
        assert_eq!(plaintext.as_slice(), decrypted_buf.as_slice());
    }
    #[test]
    fn test_transport_encryption_roundtrip() {
        let identity_a = IdentityKeypair::generate();
        let identity_b = IdentityKeypair::generate();
        let params: snow::params::NoiseParams =
            "Noise_IK_25519_ChaChaPoly_BLAKE2s".parse().unwrap();
        // Complete handshake
        let mut initiator = snow::Builder::new(params.clone())
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_a.x25519_private())
            .unwrap()
            .remote_public_key(&identity_b.x25519_public())
            .unwrap()
            .build_initiator()
            .unwrap();
        let mut responder = snow::Builder::new(params)
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_b.x25519_private())
            .unwrap()
            .build_responder()
            .unwrap();
        // Exchange handshake messages
        let mut msg1 = vec![0u8; 65535];
        let len1 = initiator.write_message(b"", &mut msg1).unwrap();
        msg1.truncate(len1);
        let mut payload1 = vec![0u8; 65535];
        responder.read_message(&msg1, &mut payload1).unwrap();
        let mut msg2 = vec![0u8; 65535];
        let len2 = responder.write_message(b"", &mut msg2).unwrap();
        msg2.truncate(len2);
        let mut payload2 = vec![0u8; 65535];
        initiator.read_message(&msg2, &mut payload2).unwrap();
        let transport_a = initiator.into_stateless_transport_mode().unwrap();
        let transport_b = responder.into_stateless_transport_mode().unwrap();
        // Test bidirectional encryption
        for i in 0..100 {
            let plaintext_a = format!("A message {}", i);
            let nonce_a = i as u64;
            let mut ciphertext_a_buf = vec![0u8; plaintext_a.len() + 16];
            let ct_a_len = transport_a
                .write_message(nonce_a, plaintext_a.as_bytes(), &mut ciphertext_a_buf)
                .unwrap();
            ciphertext_a_buf.truncate(ct_a_len);
            let mut decrypted_a_buf = vec![0u8; ciphertext_a_buf.len()];
            let pt_a_len = transport_b
                .read_message(nonce_a, &ciphertext_a_buf, &mut decrypted_a_buf)
                .unwrap();
            decrypted_a_buf.truncate(pt_a_len);
            assert_eq!(plaintext_a.as_bytes(), decrypted_a_buf.as_slice());
            let plaintext_b = format!("B message {}", i);
            let nonce_b = (i + 1000) as u64;
            let mut ciphertext_b_buf = vec![0u8; plaintext_b.len() + 16];
            let ct_b_len = transport_b
                .write_message(nonce_b, plaintext_b.as_bytes(), &mut ciphertext_b_buf)
                .unwrap();
            ciphertext_b_buf.truncate(ct_b_len);
            let mut decrypted_b_buf = vec![0u8; ciphertext_b_buf.len()];
            let pt_b_len = transport_a
                .read_message(nonce_b, &ciphertext_b_buf, &mut decrypted_b_buf)
                .unwrap();
            decrypted_b_buf.truncate(pt_b_len);
            assert_eq!(plaintext_b.as_bytes(), decrypted_b_buf.as_slice());
        }
    }
    #[test]
    fn test_wrong_key_fails() {
        let identity_a = IdentityKeypair::generate();
        let identity_b = IdentityKeypair::generate();
        let identity_c = IdentityKeypair::generate();
        let params: snow::params::NoiseParams =
            "Noise_IK_25519_ChaChaPoly_BLAKE2s".parse().unwrap();
        // A tries to talk to B, but we verify with C's key
        let mut initiator = snow::Builder::new(params.clone())
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_a.x25519_private())
            .unwrap()
            .remote_public_key(&identity_b.x25519_public())
            .unwrap()
            .build_initiator()
            .unwrap();
        let mut responder = snow::Builder::new(params)
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_b.x25519_private())
            .unwrap()
            .build_responder()
            .unwrap();
        // Exchange handshake
        let mut msg1 = vec![0u8; 65535];
        let len1 = initiator.write_message(b"", &mut msg1).unwrap();
        msg1.truncate(len1);
        let mut payload1 = vec![0u8; 65535];
        responder.read_message(&msg1, &mut payload1).unwrap();
        let mut msg2 = vec![0u8; 65535];
        let len2 = responder.write_message(b"", &mut msg2).unwrap();
        msg2.truncate(len2);
        let mut payload2 = vec![0u8; 65535];
        initiator.read_message(&msg2, &mut payload2).unwrap();
        let transport_a = initiator.into_stateless_transport_mode().unwrap();
        let transport_b = responder.into_stateless_transport_mode().unwrap();
        // Try to decrypt with wrong nonce
        let plaintext = b"test";
        let mut ciphertext_buf = vec![0u8; plaintext.len() + 16];
        let ct_len = transport_a
            .write_message(1, plaintext, &mut ciphertext_buf)
            .unwrap();
        ciphertext_buf.truncate(ct_len);
        // Wrong nonce
        let mut decrypted_buf = vec![0u8; ciphertext_buf.len()];
        let result = transport_b.read_message(2, &ciphertext_buf, &mut decrypted_buf);
        assert!(result.is_err());
    }
    #[test]
    fn test_tampered_ciphertext() {
        let identity_a = IdentityKeypair::generate();
        let identity_b = IdentityKeypair::generate();
        let params: snow::params::NoiseParams =
            "Noise_IK_25519_ChaChaPoly_BLAKE2s".parse().unwrap();
        let mut initiator = snow::Builder::new(params.clone())
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_a.x25519_private())
            .unwrap()
            .remote_public_key(&identity_b.x25519_public())
            .unwrap()
            .build_initiator()
            .unwrap();
        let mut responder = snow::Builder::new(params)
            .prologue(PROLOGUE)
            .unwrap()
            .local_private_key(&identity_b.x25519_private())
            .unwrap()
            .build_responder()
            .unwrap();
        // Complete handshake
        let mut msg1 = vec![0u8; 65535];
        let len1 = initiator.write_message(b"", &mut msg1).unwrap();
        msg1.truncate(len1);
        let mut payload1 = vec![0u8; 65535];
        responder.read_message(&msg1, &mut payload1).unwrap();
        let mut msg2 = vec![0u8; 65535];
        let len2 = responder.write_message(b"", &mut msg2).unwrap();
        msg2.truncate(len2);
        let mut payload2 = vec![0u8; 65535];
        initiator.read_message(&msg2, &mut payload2).unwrap();
        let transport_a = initiator.into_stateless_transport_mode().unwrap();
        let transport_b = responder.into_stateless_transport_mode().unwrap();
        let plaintext = b"test message";
        let mut ciphertext_buf = vec![0u8; plaintext.len() + 16];
        let ct_len = transport_a
            .write_message(1, plaintext, &mut ciphertext_buf)
            .unwrap();
        ciphertext_buf.truncate(ct_len);
        // Tamper with ciphertext
        ciphertext_buf[10] ^= 0xFF;
        let mut decrypted_buf = vec![0u8; ciphertext_buf.len()];
        let result = transport_b.read_message(1, &ciphertext_buf, &mut decrypted_buf);
        assert!(result.is_err());
    }
    #[test]
    fn test_private_key_load() {
        // Generate a keypair
        let original = IdentityKeypair::generate();
        let original_node_id = original.node_id();
        // Extract private key (ed25519)
        let private_key = original.ed25519_signing.to_scalar_bytes();
        // Load from private key
        let loaded = IdentityKeypair::from_private_key(&private_key);
        let loaded_node_id = loaded.node_id();
        // Should be identical
        assert_eq!(original_node_id, loaded_node_id);
        assert_eq!(original.ed25519_public(), loaded.ed25519_public());
        assert_eq!(original.x25519_public(), loaded.x25519_public());
    }
 }
--- a/crates/whalescale-gossip/Cargo.toml
+++ b/crates/whalescale-gossip/Cargo.toml
@ -0,0 +1,9 @@
 [package]
 name = "whalescale-gossip"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-crypto.workspace = true
 whalescale-transport.workspace = true
 whalescale-types.workspace = true
--- a/crates/whalescale-gossip/src/lib.rs
+++ b/crates/whalescale-gossip/src/lib.rs
@ -0,0 +1 @@
 //! Gossip protocol, LKG cache, anti-entropy, conflict resolution
--- a/crates/whalescale-multipath/Cargo.toml
+++ b/crates/whalescale-multipath/Cargo.toml
@ -0,0 +1,9 @@
 [package]
 name = "whalescale-multipath"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-path.workspace = true
 whalescale-transport.workspace = true
 whalescale-types.workspace = true
--- a/crates/whalescale-multipath/src/lib.rs
+++ b/crates/whalescale-multipath/src/lib.rs
@ -0,0 +1,2 @@
 //! Multipath scheduler (weighted round-robin), bandwidth estimation,
 //! feedback loop, reordering buffer logic, test bench framework
--- a/crates/whalescale-nat/Cargo.toml
+++ b/crates/whalescale-nat/Cargo.toml
@ -0,0 +1,8 @@
 [package]
 name = "whalescale-nat"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-transport.workspace = true
 whalescale-types.workspace = true
--- a/crates/whalescale-nat/src/lib.rs
+++ b/crates/whalescale-nat/src/lib.rs
@ -0,0 +1 @@
 //! NAT type detection, hole punching, UPnP/NAT-PMP/PCP
--- a/crates/whalescale-path/Cargo.toml
+++ b/crates/whalescale-path/Cargo.toml
@ -0,0 +1,8 @@
 [package]
 name = "whalescale-path"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-transport.workspace = true
 whalescale-types.workspace = true
--- a/crates/whalescale-path/src/lib.rs
+++ b/crates/whalescale-path/src/lib.rs
@ -0,0 +1 @@
 //! Path discovery, scheduling, health monitoring
--- a/crates/whalescale-session/Cargo.toml
+++ b/crates/whalescale-session/Cargo.toml
@ -0,0 +1,16 @@
 [package]
 name = "whalescale-session"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-crypto.workspace = true
 whalescale-transport.workspace = true
 whalescale-types.workspace = true
 tokio = { version = "1", features = ["time"] }
 thiserror = "1"
 tracing = "0.1"
 [dev-dependencies]
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "time"] }
 rand = "0.8"
--- a/crates/whalescale-session/src/lib.rs
+++ b/crates/whalescale-session/src/lib.rs
@ -0,0 +1 @@
 //! Noise_IK handshake, session state, key rotation
--- a/crates/whalescale-transport/Cargo.toml
+++ b/crates/whalescale-transport/Cargo.toml
@ -0,0 +1,13 @@
 [package]
 name = "whalescale-transport"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-crypto.workspace = true
 whalescale-types.workspace = true
 tokio = { version = "1", features = ["net", "rt"] }
 thiserror = "1"
 [dev-dependencies]
 tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
--- a/crates/whalescale-transport/src/lib.rs
+++ b/crates/whalescale-transport/src/lib.rs
@ -0,0 +1,393 @@
 //! UDP socket management, packet framing, send/receive.
 use std::net::SocketAddr;
 use tokio::net::UdpSocket;
 use whalescale_types::{
    HandshakeInit, HandshakeResponse, MessageType, ParseError, TransportHeader,
 };
 use thiserror::Error;
 /// Transport error type
 #[derive(Error, Debug)]
 pub enum TransportError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("parse error: {0}")]
    Parse(#[from] ParseError),
    #[error("invalid message type: {0}")]
    InvalidMessageType(u8),
    #[error("packet too large: {0} bytes")]
    PacketTooLarge(usize),
 }
 /// A raw packet as decoded from the wire
 #[derive(Debug, Clone, PartialEq)]
 pub enum RawPacket {
    HandshakeInit {
        version: u8,
        sender_session_id: u32,
        noise_payload: Vec<u8>,
    },
    HandshakeResponse {
        version: u8,
        sender_session_id: u32,
        receiver_session_id: u32,
        noise_payload: Vec<u8>,
    },
    Transport {
        header: TransportHeader,
        encrypted_payload: Vec<u8>,
    },
 }
 /// Packet codec for encoding/decoding Whalescale packets
 pub struct PacketCodec;
 impl PacketCodec {
    /// Encode a handshake initiation message
    pub fn encode_handshake_init(
        version: u8,
        sender_session_id: u32,
        noise_payload: &[u8],
    ) -> Vec<u8> {
        let init = HandshakeInit {
            version,
            sender_session_id,
            noise_payload: noise_payload.to_vec(),
        };
        init.encode()
    }
    /// Encode a handshake response message
    pub fn encode_handshake_response(
        version: u8,
        sender_session_id: u32,
        receiver_session_id: u32,
        noise_payload: &[u8],
    ) -> Vec<u8> {
        let response = HandshakeResponse {
            version,
            sender_session_id,
            receiver_session_id,
            noise_payload: noise_payload.to_vec(),
        };
        response.encode()
    }
    /// Encode a transport packet (header + encrypted payload)
    pub fn encode_transport(
        session_id: u32,
        sequence: u64,
        path_id: u8,
        packet_type: whalescale_types::PacketType,
        encrypted_payload: &[u8],
    ) -> Vec<u8> {
        let header = TransportHeader::new(
            session_id,
            sequence,
            path_id,
            packet_type,
            encrypted_payload.len() as u16,
        );
        let mut result = Vec::with_capacity(TransportHeader::SIZE + encrypted_payload.len());
        result.push(MessageType::Transport as u8);
        result.extend_from_slice(&header.to_bytes());
        result.extend_from_slice(encrypted_payload);
        result
    }
    /// Decode a raw packet from bytes
    pub fn decode(raw: &[u8]) -> Result<RawPacket, TransportError> {
        if raw.is_empty() {
            return Err(TransportError::Parse(ParseError("empty packet")));
        }
        let msg_type = MessageType::try_from(raw[0])
            .map_err(|_| TransportError::InvalidMessageType(raw[0]))?;
        match msg_type {
            MessageType::HandshakeInit => {
                let init = HandshakeInit::decode(raw)?;
                Ok(RawPacket::HandshakeInit {
                    version: init.version,
                    sender_session_id: init.sender_session_id,
                    noise_payload: init.noise_payload,
                })
            }
            MessageType::HandshakeResponse => {
                let response = HandshakeResponse::decode(raw)?;
                Ok(RawPacket::HandshakeResponse {
                    version: response.version,
                    sender_session_id: response.sender_session_id,
                    receiver_session_id: response.receiver_session_id,
                    noise_payload: response.noise_payload,
                })
            }
            MessageType::Transport => {
                if raw.len() < 1 + TransportHeader::SIZE {
                    return Err(TransportError::Parse(ParseError("transport packet too short")));
                }
                let header = TransportHeader::from_bytes(&raw[1..1 + TransportHeader::SIZE])?;
                let encrypted_payload = raw[1 + TransportHeader::SIZE..].to_vec();
                // Verify payload length matches header
                if encrypted_payload.len() != header.payload_length as usize {
                    return Err(TransportError::Parse(
                        ParseError("payload length mismatch")
                    ));
                }
                Ok(RawPacket::Transport {
                    header,
                    encrypted_payload,
                })
            }
            _ => Err(TransportError::InvalidMessageType(raw[0])),
        }
    }
 }
 /// UDP transport wrapper
 pub struct UdpTransport {
    socket: UdpSocket,
 }
 impl UdpTransport {
    /// Bind to a local address
    pub async fn bind(addr: SocketAddr) -> Result<Self, TransportError> {
        let socket = UdpSocket::bind(addr).await?;
        Ok(Self { socket })
    }
    /// Send data to a specific address
    pub async fn send_to(&self, addr: SocketAddr, data: &[u8]) -> Result<usize, TransportError> {
        let len = self.socket.send_to(data, addr).await?;
        Ok(len)
    }
    /// Receive data and the sender address
    pub async fn recv_from(&self) -> Result<(SocketAddr, Vec<u8>), TransportError> {
        let mut buf = vec![0u8; 65535];
        let (len, addr) = self.socket.recv_from(&mut buf).await?;
        buf.truncate(len);
        Ok((addr, buf))
    }
    /// Get the local address we're bound to
    pub fn local_addr(&self) -> Result<SocketAddr, TransportError> {
        Ok(self.socket.local_addr()?)
    }
    /// Get the underlying socket
    pub fn socket(&self) -> &UdpSocket {
        &self.socket
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use whalescale_types::{PacketType, PROTOCOL_VERSION};
    #[test]
    fn test_encode_decode_handshake_init() {
        let encoded = PacketCodec::encode_handshake_init(
            PROTOCOL_VERSION,
            0xDEADBEEF,
            &[1, 2, 3, 4, 5],
        );
        let decoded = PacketCodec::decode(&encoded).unwrap();
        match decoded {
            RawPacket::HandshakeInit {
                version,
                sender_session_id,
                noise_payload,
            } => {
                assert_eq!(version, PROTOCOL_VERSION);
                assert_eq!(sender_session_id, 0xDEADBEEF);
                assert_eq!(noise_payload, vec![1, 2, 3, 4, 5]);
            }
            _ => panic!("expected handshake init"),
        }
    }
    #[test]
    fn test_encode_decode_handshake_response() {
        let encoded = PacketCodec::encode_handshake_response(
            PROTOCOL_VERSION,
            0xCAFEBABE,
            0xDEADBEEF,
            &[10, 20, 30],
        );
        let decoded = PacketCodec::decode(&encoded).unwrap();
        match decoded {
            RawPacket::HandshakeResponse {
                version,
                sender_session_id,
                receiver_session_id,
                noise_payload,
            } => {
                assert_eq!(version, PROTOCOL_VERSION);
                assert_eq!(sender_session_id, 0xCAFEBABE);
                assert_eq!(receiver_session_id, 0xDEADBEEF);
                assert_eq!(noise_payload, vec![10, 20, 30]);
            }
            _ => panic!("expected handshake response"),
        }
    }
    #[test]
    fn test_encode_decode_transport() {
        let encrypted_payload = vec![0u8; 100];
        let encoded = PacketCodec::encode_transport(
            0x12345678,
            0x0102030405060708,
            0x01,
            PacketType::Data,
            &encrypted_payload,
        );
        let decoded = PacketCodec::decode(&encoded).unwrap();
        match decoded {
            RawPacket::Transport {
                header,
                encrypted_payload: payload,
            } => {
                assert_eq!(header.session_id, 0x12345678);
                assert_eq!(header.sequence, 0x0102030405060708);
                assert_eq!(header.path_id, 0x01);
                assert_eq!(header.packet_type, PacketType::Data);
                assert_eq!(header.payload_length, 100);
                assert_eq!(payload.len(), 100);
            }
            _ => panic!("expected transport packet"),
        }
    }
    #[test]
    fn test_decode_empty_packet() {
        let result = PacketCodec::decode(&[]);
        assert!(matches!(result, Err(TransportError::Parse(_))));
    }
    #[test]
    fn test_decode_invalid_message_type() {
        let result = PacketCodec::decode(&[0x00]);
        assert!(matches!(result, Err(TransportError::InvalidMessageType(0x00))));
    }
    #[test]
    fn test_decode_transport_too_short() {
        // Transport packet needs at least 1 + 16 = 17 bytes
        let result = PacketCodec::decode(&[0x04, 0x00]);
        assert!(matches!(result, Err(TransportError::Parse(_))));
    }
    #[test]
    fn test_payload_length_mismatch() {
        // Create a transport packet with wrong payload length
        let mut encoded = PacketCodec::encode_transport(
            1,
            1,
            0,
            PacketType::Data,
            &[1, 2, 3],
        );
        // Corrupt the payload length field to mismatch actual payload
        // Payload length is at offset 15 (after message type byte + header)
        encoded[15] = 0xFF; // Set to 255, but actual payload is 3 bytes
        let result = PacketCodec::decode(&encoded);
        assert!(matches!(result, Err(TransportError::Parse(_))));
    }
    #[test]
    fn test_all_packet_types() {
        let types = vec![
            PacketType::Data,
            PacketType::Control,
            PacketType::Ack,
            PacketType::Probe,
            PacketType::Heartbeat,
        ];
        for (i, packet_type) in types.iter().enumerate() {
            let encoded = PacketCodec::encode_transport(
                i as u32,
                i as u64,
                i as u8,
                *packet_type,
                &vec![i as u8],
            );
            let decoded = PacketCodec::decode(&encoded).unwrap();
            match decoded {
                RawPacket::Transport { header, .. } => {
                    assert_eq!(header.packet_type, *packet_type);
                }
                _ => panic!("expected transport packet"),
            }
        }
    }
    #[tokio::test]
    async fn test_udp_transport_send_recv() {
        let transport_a = UdpTransport::bind("127.0.0.1:0".parse().unwrap()).await.unwrap();
        let transport_b = UdpTransport::bind("127.0.0.1:0".parse().unwrap()).await.unwrap();
        let addr_a = transport_a.local_addr().unwrap();
        let addr_b = transport_b.local_addr().unwrap();
        // Send from A to B
        let data = b"hello from A";
        transport_a.send_to(addr_b, data).await.unwrap();
        // Receive at B
        let (recv_addr, recv_data) = transport_b.recv_from().await.unwrap();
        assert_eq!(recv_addr, addr_a);
        assert_eq!(recv_data, data.to_vec());
        // Send from B to A
        let data = b"hello from B";
        transport_b.send_to(addr_a, data).await.unwrap();
        // Receive at A
        let (recv_addr, recv_data) = transport_a.recv_from().await.unwrap();
        assert_eq!(recv_addr, addr_b);
        assert_eq!(recv_data, data.to_vec());
    }
    #[test]
    fn test_transport_header_offsets() {
        // Verify the wire format matches expectations
        let encoded = PacketCodec::encode_transport(
            0x01020304,
            0x05060708090A0B0C,
            0x0D,
            PacketType::Heartbeat,
            &[0xEE, 0xFF],
        );
        // First byte should be MessageType::Transport
        assert_eq!(encoded[0], 0x04);
        // Next 16 bytes should be the header
        assert_eq!(&encoded[1..5], &[0x01, 0x02, 0x03, 0x04]); // session_id
        assert_eq!(&encoded[5..13], &[0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C]); // sequence
        assert_eq!(encoded[13], 0x0D); // path_id
        assert_eq!(encoded[14], 0x05); // packet_type = Heartbeat
        assert_eq!(&encoded[15..17], &[0x00, 0x02]); // payload_length = 2
        // Remaining bytes should be the payload
        assert_eq!(&encoded[17..], &[0xEE, 0xFF]);
    }
 }
--- a/crates/whalescale-tun/Cargo.toml
+++ b/crates/whalescale-tun/Cargo.toml
@ -0,0 +1,7 @@
 [package]
 name = "whalescale-tun"
 version.workspace = true
 edition.workspace = true
 [dependencies]
 whalescale-types.workspace = true
--- a/crates/whalescale-tun/src/lib.rs
+++ b/crates/whalescale-tun/src/lib.rs
@ -0,0 +1 @@
 //! TUN device read/write, IP packet routing
--- a/crates/whalescale-types/Cargo.toml
+++ b/crates/whalescale-types/Cargo.toml
@ -0,0 +1,6 @@
 [package]
 name = "whalescale-types"
 version.workspace = true
 edition.workspace = true
 [dependencies]
--- a/crates/whalescale-types/src/lib.rs
+++ b/crates/whalescale-types/src/lib.rs
@ -0,0 +1,477 @@
 //! Shared types, constants, and protocol definitions for Whalescale.
 use std::fmt;
 use std::net::SocketAddr;
 use std::str::FromStr;
 /// Protocol constants
 pub const PROLOGUE: &[u8] = b"whalescale-v1";
 pub const PROTOCOL_VERSION: u8 = 0x01;
 pub const MAX_PACKET_SIZE: usize = 65535;
 pub const TRANSPORT_HEADER_SIZE: usize = 16;
 pub const AEAD_TAG_SIZE: usize = 16;
 pub const REPLAY_WINDOW_SIZE: usize = 2048;
 pub const VPN_MTU_DEFAULT: u16 = 1440;
 pub const HANDSHAKE_TIMEOUT_SECS: u64 = 5;
 pub const REKEY_INTERVAL_SECS: u64 = 120;
 pub const KEEPALIVE_INTERVAL_SECS: u64 = 25;
 pub const MAX_HANDSHAKE_ATTEMPTS: u32 = 20;
 /// NodeId is a 32-byte Ed25519 public key
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct NodeId([u8; 32]);
 impl NodeId {
    pub const fn new(bytes: [u8; 32]) -> Self {
        Self(bytes)
    }
    pub fn as_bytes(&self) -> &[u8; 32] {
        &self.0
    }
    pub fn into_bytes(self) -> [u8; 32] {
        self.0
    }
    /// Format as base32 fingerprint (first 10 chars)
    pub fn fingerprint(&self) -> String {
        // Simple hex encoding for now - base32 can be added later
        format!("{}", hex::encode(&self.0[..16]))
    }
 }
 impl fmt::Display for NodeId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.fingerprint())
    }
 }
 impl FromStr for NodeId {
    type Err = ParseError;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let bytes = hex::decode(s)
            .map_err(|_| ParseError("invalid hex encoding"))?;
        if bytes.len() != 32 {
            return Err(ParseError("NodeId must be 32 bytes"));
        }
        let mut arr = [0u8; 32];
        arr.copy_from_slice(&bytes);
        Ok(Self(arr))
    }
 }
 impl From<[u8; 32]> for NodeId {
    fn from(bytes: [u8; 32]) -> Self {
        Self(bytes)
    }
 }
 /// Session identifier (4 bytes, random on creation)
 pub type SessionId = u32;
 /// Global sequence number (64-bit, monotonically increasing)
 pub type SequenceNumber = u64;
 /// Path identifier (8-bit, up to 256 paths per session)
 pub type PathId = u8;
 /// Message type discriminant (first byte of any Whalescale packet)
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(u8)]
 pub enum MessageType {
    HandshakeInit = 0x01,
    HandshakeResponse = 0x02,
    Transport = 0x04,
 }
 impl TryFrom<u8> for MessageType {
    type Error = ParseError;
    fn try_from(value: u8) -> Result<Self, Self::Error> {
        match value {
            0x01 => Ok(Self::HandshakeInit),
            0x02 => Ok(Self::HandshakeResponse),
            0x04 => Ok(Self::Transport),
            _ => Err(ParseError("unknown message type")),
        }
    }
 }
 /// Packet type within transport header
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(u8)]
 pub enum PacketType {
    Data = 0x01,
    Control = 0x02,
    Ack = 0x03,
    Probe = 0x04,
    Heartbeat = 0x05,
 }
 impl TryFrom<u8> for PacketType {
    type Error = ParseError;
    fn try_from(value: u8) -> Result<Self, Self::Error> {
        match value {
            0x01 => Ok(Self::Data),
            0x02 => Ok(Self::Control),
            0x03 => Ok(Self::Ack),
            0x04 => Ok(Self::Probe),
            0x05 => Ok(Self::Heartbeat),
            _ => Err(ParseError("unknown packet type")),
        }
    }
 }
 /// Transport header (16 bytes)
 ///
 /// Format:
 /// - 4 bytes: Session ID
 /// - 8 bytes: Global Sequence Number
 /// - 1 byte: Path ID
 /// - 1 byte: Packet Type
 /// - 2 bytes: Payload Length
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct TransportHeader {
    pub session_id: SessionId,
    pub sequence: SequenceNumber,
    pub path_id: PathId,
    pub packet_type: PacketType,
    pub payload_length: u16,
 }
 impl TransportHeader {
    pub const SIZE: usize = 16;
    pub fn new(
        session_id: SessionId,
        sequence: SequenceNumber,
        path_id: PathId,
        packet_type: PacketType,
        payload_length: u16,
    ) -> Self {
        Self {
            session_id,
            sequence,
            path_id,
            packet_type,
            payload_length,
        }
    }
    pub fn to_bytes(&self) -> [u8; Self::SIZE] {
        let mut buf = [0u8; Self::SIZE];
        buf[0..4].copy_from_slice(&self.session_id.to_be_bytes());
        buf[4..12].copy_from_slice(&self.sequence.to_be_bytes());
        buf[12] = self.path_id;
        buf[13] = self.packet_type as u8;
        buf[14..16].copy_from_slice(&self.payload_length.to_be_bytes());
        buf
    }
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, ParseError> {
        if bytes.len() < Self::SIZE {
            return Err(ParseError("transport header too short"));
        }
        let session_id = u32::from_be_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);
        let sequence = u64::from_be_bytes([
            bytes[4], bytes[5], bytes[6], bytes[7],
            bytes[8], bytes[9], bytes[10], bytes[11],
        ]);
        let path_id = bytes[12];
        let packet_type = PacketType::try_from(bytes[13])?;
        let payload_length = u16::from_be_bytes([bytes[14], bytes[15]]);
        Ok(Self {
            session_id,
            sequence,
            path_id,
            packet_type,
            payload_length,
        })
    }
 }
 /// Handshake initiation message envelope
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct HandshakeInit {
    pub version: u8,
    pub sender_session_id: SessionId,
    pub noise_payload: Vec<u8>,
 }
 impl HandshakeInit {
    pub fn encode(&self) -> Vec<u8> {
        let mut buf = Vec::with_capacity(6 + self.noise_payload.len());
        buf.push(MessageType::HandshakeInit as u8);
        buf.push(self.version);
        buf.extend_from_slice(&self.sender_session_id.to_be_bytes());
        buf.extend_from_slice(&self.noise_payload);
        buf
    }
    pub fn decode(bytes: &[u8]) -> Result<Self, ParseError> {
        if bytes.len() < 6 {
            return Err(ParseError("handshake init too short"));
        }
        let msg_type = MessageType::try_from(bytes[0])?;
        if msg_type != MessageType::HandshakeInit {
            return Err(ParseError("expected handshake init"));
        }
        let version = bytes[1];
        let sender_session_id = u32::from_be_bytes([bytes[2], bytes[3], bytes[4], bytes[5]]);
        let noise_payload = bytes[6..].to_vec();
        Ok(Self {
            version,
            sender_session_id,
            noise_payload,
        })
    }
 }
 /// Handshake response message envelope
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct HandshakeResponse {
    pub version: u8,
    pub sender_session_id: SessionId,
    pub receiver_session_id: SessionId,
    pub noise_payload: Vec<u8>,
 }
 impl HandshakeResponse {
    pub fn encode(&self) -> Vec<u8> {
        let mut buf = Vec::with_capacity(10 + self.noise_payload.len());
        buf.push(MessageType::HandshakeResponse as u8);
        buf.push(self.version);
        buf.extend_from_slice(&self.sender_session_id.to_be_bytes());
        buf.extend_from_slice(&self.receiver_session_id.to_be_bytes());
        buf.extend_from_slice(&self.noise_payload);
        buf
    }
    pub fn decode(bytes: &[u8]) -> Result<Self, ParseError> {
        if bytes.len() < 10 {
            return Err(ParseError("handshake response too short"));
        }
        let msg_type = MessageType::try_from(bytes[0])?;
        if msg_type != MessageType::HandshakeResponse {
            return Err(ParseError("expected handshake response"));
        }
        let version = bytes[1];
        let sender_session_id = u32::from_be_bytes([bytes[2], bytes[3], bytes[4], bytes[5]]);
        let receiver_session_id = u32::from_be_bytes([bytes[6], bytes[7], bytes[8], bytes[9]]);
        let noise_payload = bytes[10..].to_vec();
        Ok(Self {
            version,
            sender_session_id,
            receiver_session_id,
            noise_payload,
        })
    }
 }
 /// Peer configuration (from config file)
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PeerConfig {
    pub public_key: NodeId,
    pub endpoint: SocketAddr,
    pub persistent_keepalive: Option<std::time::Duration>,
 }
 /// Parse error type
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ParseError(pub &'static str);
 impl fmt::Display for ParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "parse error: {}", self.0)
    }
 }
 impl std::error::Error for ParseError {}
 /// Simple hex encoding/decoding for NodeId
 mod hex {
    pub fn encode(bytes: &[u8]) -> String {
        bytes.iter().map(|b| format!("{:02x}", b)).collect()
    }
    pub fn decode(s: &str) -> Result<Vec<u8>, ()> {
        if s.len() % 2 != 0 {
            return Err(());
        }
        let mut result = Vec::with_capacity(s.len() / 2);
        for chunk in s.as_bytes().chunks(2) {
            let hex_str = std::str::from_utf8(chunk).map_err(|_| ())?;
            let byte = u8::from_str_radix(hex_str, 16).map_err(|_| ())?;
            result.push(byte);
        }
        Ok(result)
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn test_transport_header_roundtrip() {
        let header = TransportHeader::new(
            0x12345678,
            0x0102030405060708,
            0x01,
            PacketType::Data,
            1500,
        );
        let bytes = header.to_bytes();
        assert_eq!(bytes.len(), 16);
        let decoded = TransportHeader::from_bytes(&bytes).unwrap();
        assert_eq!(header, decoded);
    }
    #[test]
    fn test_transport_header_too_short() {
        let result = TransportHeader::from_bytes(&[0u8; 15]);
        assert!(result.is_err());
    }
    #[test]
    fn test_packet_type_roundtrip() {
        let types = vec![
            PacketType::Data,
            PacketType::Control,
            PacketType::Ack,
            PacketType::Probe,
            PacketType::Heartbeat,
        ];
        for packet_type in types {
            let byte = packet_type as u8;
            let decoded = PacketType::try_from(byte).unwrap();
            assert_eq!(packet_type, decoded);
        }
    }
    #[test]
    fn test_invalid_packet_type() {
        assert!(PacketType::try_from(0x00).is_err());
        assert!(PacketType::try_from(0x06).is_err());
        assert!(PacketType::try_from(0xff).is_err());
    }
    #[test]
    fn test_handshake_init_roundtrip() {
        let init = HandshakeInit {
            version: PROTOCOL_VERSION,
            sender_session_id: 0xDEADBEEF,
            noise_payload: vec![1, 2, 3, 4, 5],
        };
        let encoded = init.encode();
        let decoded = HandshakeInit::decode(&encoded).unwrap();
        assert_eq!(init.version, decoded.version);
        assert_eq!(init.sender_session_id, decoded.sender_session_id);
        assert_eq!(init.noise_payload, decoded.noise_payload);
    }
    #[test]
    fn test_handshake_response_roundtrip() {
        let response = HandshakeResponse {
            version: PROTOCOL_VERSION,
            sender_session_id: 0xCAFEBABE,
            receiver_session_id: 0xDEADBEEF,
            noise_payload: vec![10, 20, 30, 40, 50],
        };
        let encoded = response.encode();
        let decoded = HandshakeResponse::decode(&encoded).unwrap();
        assert_eq!(response.version, decoded.version);
        assert_eq!(response.sender_session_id, decoded.sender_session_id);
        assert_eq!(response.receiver_session_id, decoded.receiver_session_id);
        assert_eq!(response.noise_payload, decoded.noise_payload);
    }
    #[test]
    fn test_node_id_hex() {
        let bytes = [0u8; 32];
        let node_id = NodeId::new(bytes);
        let hex = format!("{}", node_id);
        assert_eq!(hex, "00000000000000000000000000000000");
    }
    #[test]
    fn test_node_id_parse() {
        let hex = "aabbccdd" .repeat(8); // 64 hex chars = 32 bytes
        let node_id = NodeId::from_str(&hex).unwrap();
        assert_eq!(node_id.as_bytes().len(), 32);
    }
    #[test]
    fn test_invalid_node_id_length() {
        let hex = "aabbcc"; // too short
        assert!(NodeId::from_str(hex).is_err());
    }
    #[test]
    fn test_message_type_roundtrip() {
        assert_eq!(MessageType::try_from(0x01).unwrap(), MessageType::HandshakeInit);
        assert_eq!(MessageType::try_from(0x02).unwrap(), MessageType::HandshakeResponse);
        assert_eq!(MessageType::try_from(0x04).unwrap(), MessageType::Transport);
    }
    #[test]
    fn test_invalid_message_type() {
        assert!(MessageType::try_from(0x00).is_err());
        assert!(MessageType::try_from(0x03).is_err());
        assert!(MessageType::try_from(0x05).is_err());
    }
    #[test]
    fn test_handshake_init_too_short() {
        assert!(HandshakeInit::decode(&[0x01, 0x01]).is_err());
    }
    #[test]
    fn test_handshake_response_too_short() {
        assert!(HandshakeResponse::decode(&[0x02, 0x01]).is_err());
    }
    #[test]
    fn test_transport_header_field_values() {
        let header = TransportHeader::from_bytes(&[
            0x00, 0x00, 0x00, 0x01, // session_id = 1
            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, // sequence = 2
            0x03, // path_id = 3
            0x01, // packet_type = Data
            0x00, 0x10, // payload_length = 16
        ]).unwrap();
        assert_eq!(header.session_id, 1);
        assert_eq!(header.sequence, 2);
        assert_eq!(header.path_id, 3);
        assert_eq!(header.packet_type, PacketType::Data);
        assert_eq!(header.payload_length, 16);
    }
    #[test]
    fn test_constants() {
        assert_eq!(PROLOGUE, b"whalescale-v1");
        assert_eq!(PROTOCOL_VERSION, 0x01);
        assert_eq!(TRANSPORT_HEADER_SIZE, 16);
        assert_eq!(AEAD_TAG_SIZE, 16);
        assert_eq!(TRANSPORT_HEADER_SIZE + AEAD_TAG_SIZE, 32);
    }
 }
		`@ -0,0 +1 @@`
							`//! Anchor management, relay forwarding, mutual keepalive`
		`@ -0,0 +1 @@`
							`//! Pre-session discovery protocol, manual bootstrap`
		`@ -0,0 +1 @@`
							`//! Gossip protocol, LKG cache, anti-entropy, conflict resolution`
		`@ -0,0 +1,2 @@`
							`//! Multipath scheduler (weighted round-robin), bandwidth estimation,`
							`//! feedback loop, reordering buffer logic, test bench framework`
		`@ -0,0 +1 @@`
							`//! NAT type detection, hole punching, UPnP/NAT-PMP/PCP`
		`@ -0,0 +1 @@`
							`//! Path discovery, scheduling, health monitoring`
		`@ -0,0 +1 @@`
							`//! Noise_IK handshake, session state, key rotation`
		`@ -0,0 +1 @@`
							`//! TUN device read/write, IP packet routing`