glm-5.1
dad8224686
Docs: - README.md: index with doc table, ADR table, lifecycle definitions - overview.md: purpose, exports, dependencies, constraints - transport.md: Transport trait, TCP/TLS/iroh implementations, stream join - client.md: SOCKS5 server, port forwarding, channel manager, reconnection - server.md: auth, channel handling, stealth mode, outbound proxy - tun-shim.md: separate privileged process, virtual DNS, --unshare mode - napi-and-pubsub.md: NAPI wrapper, pubsub event target adapter ADRs: - 001: Pluggable transport via AsyncRead+AsyncWrite trait - 002: TUN shim as separate process - 003: iroh stream via tokio::io::join - 004: SSH runs over transport, not alongside - 005: SOCKS5 as primary interface, TUN as add-on - 006(007): NAPI exposes single duplex stream Open questions: 11 items covering TLS certs, iroh relay defaults, Windows TUN, auth expansion, NAPI surface, TCP reconstruction
1.7 KiB
1.7 KiB
ADR-002: TUN Shim as Separate Process
Status
Accepted
Context
TUN interface creation requires root privileges or CAP_NET_ADMIN on Linux, Administrator on Windows, or platform-specific VPN APIs on macOS/iOS/Android. If the core wraith binary required these privileges, the attack surface of root-required code would include the entire SSH implementation, key handling, and transport negotiation.
The primary use cases (SOCKS5 proxy, port forwarding) need no privileges at all. Only the "route all traffic through TUN" use case needs root.
Decision
The TUN functionality is a separate wraith-tun binary that:
- Creates a TUN device (requires root / CAP_NET_ADMIN)
- Reads IP packets from it
- Forwards each connection to the core wraith's SOCKS5 port (127.0.0.1:1080)
- Proxies bytes between TUN packets and SOCKS5 connections
The core wraith connect binary never needs root. The wraith-tun binary is ~200-500 lines and does nothing except TUN ↔ SOCKS5 forwarding.
Consequences
- Positive: Root-required code surface is tiny and auditable.
- Positive: Core binary runs unprivileged. SOCKS5 and port forwarding work without any special permissions.
- Positive: TUN process can crash without affecting the SSH session (it just reconnects to SOCKS5).
- Positive: Matches the proven tun2proxy architecture.
- Negative: Two processes to manage instead of one. Requires process supervision (systemd, etc.).
- Negative: SOCKS5 adds a small latency overhead vs. direct TUN → SSH packet routing. This is acceptable for the security benefit.
References
- tun-shim.md
- tun2proxy — proven architecture for TUN → SOCKS5 proxy