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.
2.6 KiB
ADR-014: Defer TUN Implementation, Recommend Local SOCKS5 + tun2proxy
Status
Accepted
Context
The original plan included a TUN shim (wraith-tun) as Phase 3 — a separate root-requiring process that creates a TUN device and forwards IP packets through wraith's SOCKS5 port. This would provide VPN-like "route all traffic" behavior.
However, TUN implementation has significant complexities:
- Platform differences (Linux TUN, macOS utun, Windows wintun.dll)
- TCP reconstruction in userspace (smoltcp or tun2proxy's ip-stack)
- Virtual DNS handling
- Root/CAP_NET_ADMIN requirements
- TUN is easy to get wrong and hard to debug
The core SOCKS5 interface already works for the vast majority of use cases. For users who truly need VPN-like "route all traffic" behavior, tun2proxy is an existing, well-tested tool that does exactly this: creates a TUN device and routes traffic through a SOCKS5 proxy.
Decision
Defer TUN implementation entirely. Remove wraith-tun from the architecture. Instead:
- Core interface: wraith's local SOCKS5 proxy (always available, no root required)
- VPN-like behavior: Users who need it run
tun2proxy --proxy socks5://127.0.0.1:1080alongsidewraith connect - Documentation: Recommend tun2proxy in the README/wiki for "route all traffic" use cases
This removes TUN from the project scope while still providing a path to VPN-like behavior. If demand justifies it later, wraith-tun can be added as a thin wrapper around tun2proxy's pattern.
The tun feature flag and wraith-tun binary are removed from the architecture. The tun-rs dependency is removed.
Consequences
- Positive: Significantly reduces project scope and complexity. No TUN code to write, test, or maintain across platforms.
- Positive: tun2proxy is already well-tested for this exact use case.
- Positive: Core binary remains unprivileged. No root code anywhere in the project.
- Positive: Cleaner architecture — wraith only does SSH tunneling + SOCKS5. tun2proxy does TUN.
- Negative: Users need two tools instead of one for VPN-like behavior. Mitigated by documentation.
- Negative: tun2proxy is an external dependency in practice, though it's widely available in package managers.
- Negative: No first-class Windows/macOS TUN story. tun2proxy handles these platforms but users need to install it separately.
References
- tun-shim.md — this spec is now deprecated
- ADR-002 — superseded; TUN is no longer in scope
- ADR-005 — SOCKS5 is still the primary interface; TUN forwarding is now external