Files

glm-5.1 13b0991fb8 Resolve all architecture open questions, add 13 ADRs, update specs

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.

2026-06-01 17:31:28 +00:00

1.9 KiB

Raw Blame History

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:

TUN only: Create a TUN interface, route all OS traffic through it. Full VPN experience but requires root.
SOCKS5 only: Local SOCKS5 proxy. Applications configure proxy settings. No root needed but application support varies.
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.

1.9 KiB Raw Blame History