glm-5.1
13b0991fb8
Resolved all 11 open questions based on project guidance: Transport: - OQ-01/OQ-07: ACME/Let's Encrypt with domain + IP paths (ADR-008) - OQ-02: Default to n0 relay, --iroh-relay override (ADR-009) - OQ-05: Transport chaining supported natively (ADR-010) Client: - OQ-06: Programmatic-first API, no ~/.ssh/config (ADR-011) Server: - OQ-04: Ed25519 + OpenSSH cert-authority, no password auth (ADR-012) - OQ-08: fail2ban-friendly logging + built-in rate limiting (ADR-013) TUN: - OQ-03/OQ-09: Deferred entirely, recommend tun2proxy (ADR-014) - tun-shim.md marked deprecated NAPI: - OQ-10: Expose both connect() and serve() (ADR-016) - OQ-11: Use napi-rs for FFI bridge (ADR-015) Additional ADRs created during review: - ADR-006: No logging of tunnel destinations (was phantom reference) - ADR-017: Stealth mode protocol multiplexing - ADR-018: Control channel for pubsub over SSH Fixed: ADR-002 status → Superseded, ADR-007 title typo, WRAUTH_SERVER typo, ADR-005 stale wraith-tun refs, undefined ACL feature removed from server.md, --proxy semantic difference documented.
30 lines
1.7 KiB
Markdown
30 lines
1.7 KiB
Markdown
# ADR-002: TUN Shim as Separate Process
|
|
|
|
## Status
|
|
Superseded by ADR-014
|
|
|
|
## 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:
|
|
1. Creates a TUN device (requires root / CAP_NET_ADMIN)
|
|
2. Reads IP packets from it
|
|
3. Forwards each connection to the core wraith's SOCKS5 port (127.0.0.1:1080)
|
|
4. 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](../tun-shim.md)
|
|
- [tun2proxy](https://github.com/tun2proxy/tun2proxy) — proven architecture for TUN → SOCKS5 proxy |