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.
39 lines
1.9 KiB
Markdown
39 lines
1.9 KiB
Markdown
# ADR-005: SOCKS5 as Primary Interface, TUN as Add-on
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
A "VPN-like" tool needs to route traffic. There are three approaches:
|
|
|
|
1. **TUN only**: Create a TUN interface, route all OS traffic through it. Full VPN experience but requires root.
|
|
2. **SOCKS5 only**: Local SOCKS5 proxy. Applications configure proxy settings. No root needed but application support varies.
|
|
3. **SOCKS5 primary, TUN add-on**: SOCKS5 is the core interface. TUN forwards to SOCKS5.
|
|
|
|
## Decision
|
|
SOCKS5 is the primary interface. TUN is a separate process that forwards to SOCKS5 (Option 3).
|
|
|
|
SOCKS5 is the core because:
|
|
- It requires no privileges
|
|
- `curl --socks5-hostname` works everywhere
|
|
- Browsers, most CLI tools, and many applications support SOCKS5
|
|
- SOCKS5h prevents DNS leaks by resolving names server-side
|
|
- It's the interface that the NAPI wrapper and pubsub adapter build on
|
|
- TUN is only needed for "route all traffic" use cases, which are a subset of users
|
|
|
|
TUN forwards to SOCKS5 rather than directly to SSH because:
|
|
- The SOCKS5 code already handles TCP connection establishment and bidirectional proxying
|
|
- TUN's job is just IP packet → SOCKS5 connection, not IP packet → SSH channel
|
|
- The `wraith-tun` binary stays minimal (~200-500 lines)
|
|
- No root code in the core binary
|
|
|
|
## Consequences
|
|
- **Positive**: Core binary is root-free. TUN functionality is provided by the external `tun2proxy` tool (ADR-014).
|
|
- **Positive**: SOCKS5 is testable without TUN — just `curl` against it.
|
|
- **Positive**: The TUN approach is validated by tun2proxy, a well-tested existing tool. No custom TUN code to maintain.
|
|
- **Negative**: VPN-like behavior requires running `tun2proxy` alongside `wraith connect` — two processes instead of one integrated binary.
|
|
- **Negative**: SOCKS5 doesn't capture UDP (except DNS via SOCKS5h). TUN mode via tun2proxy handles this separately.
|
|
|
|
## References
|
|
- [client.md](../client.md)
|
|
- [tun-shim.md](../tun-shim.md) |