alknet/docs/architecture/decisions/090-client-dial-socks5-proxy-seam.md

ADR-090: Client-Dial SOCKS5 Proxy Seam

Status

Accepted (adds a capability to ADR-089's AlknetClient; raises OQ-67 for iroh)

Context

The privacy gap

A native client (AlknetClient, ADR-089) that dials a hub directly exposes its real IP address to the hub (and to any relay on the path). This is the same privacy exposure iroh documents for its own direct-connection case: without a proxy, the peer and the relay see one's real IP. A client that wants to keep its real IP private from the hub — the primary use case — needs to route the dial through a trusted proxy that terminates the network path and presents its own IP to the hub.

This is a first-class client capability, not a niche feature. The old (alknet-main) client had a ConnectOptions.proxy: Option<String> field for exactly this, and the iroh transport builder already took a proxy_url parameter. But the old client's proxy support was incomplete: the TCP/TLS transports never consumed the proxy field (TcpStream::connect went direct), and only iroh's proxy_url was wired. ADR-089's AlknetClient is the greenfield rewrite, and this is the time to make the proxy a real, uniform, tested capability rather than an aspirational field.

Two distinct SOCKS5 uses — do not conflate

There are two unrelated SOCKS5 concepts in the alknet design space. This ADR is about one of them; naming both prevents a conflation that would distort the scope.

1. Client-dial proxy (this ADR). The client routes its outbound dial to the hub through a SOCKS5 proxy. The client owns the proxy config; the hub sees the proxy's IP. This is transport-layer privacy for the establishment side. Lives in alknet-client (the dial seam, ADR-089).

2. SOCKS5-over-channels handler (the planned alknet-socks5 crate, not yet specced — ADR-085 scope table). One side offers a SOCKS5 proxy service to the other over a channels data channel (ALPN alknet/socks5). The offering side runs a SOCKS5 server backed by channels direct-tcpip-equivalent opens; the consuming side tunnels it locally and uses it like any SOCKS5 server. This is a service, not a client-dial concern. Lives in alknet-socks5 (foundational handler, rides inside channels). Out of scope here.

The two compose without coupling: a client that wants both privacy on its dial and a SOCKS5 service from the hub sets its dial Socks5ProxyConfig (this ADR) to its local SOCKS5 endpoint, and that endpoint may itself be a local tunnel to the hub's alknet/socks5 channels service. The dial proxy doesn't know the SOCKS5 server is a channels handler; the channels handler doesn't know its client is an AlknetClient dial. The composition is at the SOCKS5 protocol level, not the alknet type level. This ADR concerns only #1.

QUIC-over-SOCKS5 is validated

The central technical question — can a quinn QUIC dial go through a SOCKS5 proxy? — is settled by a de-risking PoC. QUIC is UDP; SOCKS5 UDP ASSOCIATE (RFC 1928 §6/§7) carries UDP datagrams; quinn exposes a public socket abstraction (quinn::AsyncUdpSocket) and a public constructor (quinn::Endpoint::new_with_abstract_socket) that accept any impl. A SOCKS5 UDP ASSOCIATE tunnel implemented as an AsyncUdpSocket is the exact extension point. The PoC (/workspace/quinn-proxy-poc, docs/research/quinn-quic-proxy/findings.md) runs end-to-end: a quinn client completes the QUIC handshake and exchanges stream data with all UDP traffic tunneled through a fast-socks5 proxy (5/5 runs clean). The identical pattern is in production in BotBrowser (QUIC/HTTP3 + STUN over SOCKS5 UDP ASSOCIATE in Chromium's network stack).

The PoC surfaced two real, acceptable limitations:

• ECN is lost across the proxy. The SOCKS5 UDP header carries no ECN bits, so the proxied QUIC path falls back to non-ECN congestion control. A performance cost on congested links, not a correctness issue — QUIC degrades gracefully. For alknet's call/channels traffic (low-bandwidth, latency-sensitive, not throughput-critical), the cost is negligible. Anyone who chooses to route through a proxy already accepts added latency and the loss of path optimizations; this is an expected cost of the privacy choice, not a surprise.
• The proxy must support UDP ASSOCIATE. Not every SOCKS5 proxy does (notably ssh -D does not). This is a deployment requirement, not a code problem. The dial surfaces a clear error when the proxy rejects UDP ASSOCIATE; the operator chooses a UDP-capable proxy. The fallback policy (fall back to dial_tcp_tls, or fail closed) is a caller concern — see §6.

The per-datagram framing overhead (6–22 bytes of SOCKS5 header per datagram, ~0.4–1.8% of a typical QUIC datagram) and the one extra TCP control connection keeping the UDP association alive are both negligible.

Why SOCKS5 only (no HTTP CONNECT)

SOCKS5 supports both TCP (CONNECT, RFC 1928 §3) and UDP (UDP ASSOCIATE, §6) within one protocol. HTTP CONNECT is TCP-only with no UDP equivalent. Supporting only SOCKS5 means one ProxyConfig shape covers both dial_quic (UDP ASSOCIATE) and dial_tcp_tls (CONNECT); adding HTTP CONNECT would add an enum variant that only one of the three dials could use, for no privacy gain (SOCKS5 CONNECT does what HTTP CONNECT does). The old code supported both, but the greenfield rewrite has no backward-compatibility obligation, and the simplicity of a single proxy protocol is worth more than the marginal compatibility benefit of HTTP CONNECT. SOCKS5 is the sole proxy protocol.

Decision

1. The proxy config is a first-class dial parameter on AlknetClient

AlknetClient gains an optional Socks5ProxyConfig. Following the no-env-vars invariant (ADR-014), the config comes from Capabilities / the assembly layer, never from ALL_PROXY / HTTPS_PROXY env vars. (The old alknet-main client had a proxy: Option<String> field on ConnectOptions; this ADR makes the concept real, typed, and uniformly honored across the dials, where the old code's TCP/TLS transports silently ignored it.)

pub struct Socks5ProxyConfig {
    /// The proxy's TCP address (where the SOCKS5 control connection
    /// connects). For UDP ASSOCIATE (the QUIC dial), the proxy replies
    /// with a UDP relay address that may differ; the dial uses that.
    pub addr: SocketAddr,
    /// Optional username/password auth (RFC 1929). None = no-auth.
    pub credentials: Option<Socks5Credentials>,
}

pub struct Socks5Credentials {
    pub username: String,
    pub password: String,
}

The config's crate location is an implementation detail (it can live in alknet-client, alknet-core, or alknet-tls alongside the other client config types), same as the CallCredentials location is an implementation detail per ADR-089 §5. The shape is decided; the crate home is two-way-door.

2. AlknetClient holds the proxy; each dial applies it

AlknetClient holds an Option<Socks5ProxyConfig> set via a builder method, mirroring the with_quinn / with_iroh / with_tcp_tls builder pattern:

impl AlknetClient {
    /// Set the SOCKS5 proxy for all subsequent dials. When set, every
    /// dial routes its transport through this proxy: UDP ASSOCIATE for
    /// `dial_quic`, CONNECT for `dial_tcp_tls`. `dial_iroh` is the
    /// exception — see OQ-67.
    pub fn with_socks5_proxy(mut self, proxy: Socks5ProxyConfig) -> Self;
}

The proxy is set once on the client (all dials use it), not per-dial. Rationale: the proxy is a client-level privacy posture, not a per-connection choice — a client that wants to hide its IP wants to hide it on every dial. The per-dial alternative (each dial_* takes an Option<&Socks5ProxyConfig>) is more flexible but rarely what a caller wants, and it complicates the QUIC path where the proxy must be built into the quinn::Endpoint (transport handle) rather than applied per connect. A future per-dial override is a two-way-door addition; the client-level default is the one-way-door surface.

The builder-method placement mirrors AlknetEndpoint's builder (ADR-083): the assembly layer builds the transport handles and hands them to the client; the proxy is another pre-built handle. The symmetry holds — AlknetEndpoint takes pre-built server transports; AlknetClient takes pre-built client transports + a proxy.

3. dial_quic routes QUIC through SOCKS5 UDP ASSOCIATE

When a proxy is configured, dial_quic does not call quinn::Endpoint::client. It performs the SOCKS5 UDP ASSOCIATE handshake (TCP control connection to the proxy, optional auth, receive the UDP relay address), wraps the result in a Socks5UdpSocket (the AsyncUdpSocket impl from the PoC), and builds the quinn::Endpoint via new_with_abstract_socket with that socket. The TLS config (TlsClientConfig, ADR-087), the ALPN negotiation, the Connection construction (Connection::from_quinn_with_alpn, ADR-065), and the credential handshake are all unchanged — the proxy is below all of them.

The Socks5UdpSocket implementation (~250 lines, validated by the PoC) lives in alknet-client behind a socks5 feature flag. It is the establishment concern (how the client reaches the hub), not a protocol concern (what runs on the Connection). The Connection/dispatch/ credentials stay proxy-unaware.

Without a proxy, dial_quic is unchanged from ADR-089 — quinn::Endpoint::client with a raw kernel UDP socket. The proxy is a strict addition; the no-proxy path is the zero-cost default.

impl AlknetClient {
    #[cfg(feature = "quinn")]
    pub async fn dial_quic(
        &self,
        addr: SocketAddr,
        server_name: &str,
        alpn: &[u8],
        credentials: &CallCredentials,
    ) -> Result<Connection, ClientDialError> {
        let tls_config = TlsClientConfig::new(/* ... */)?;
        let client_config = quinn::ClientConfig::new(tls_config.for_quinn());
        let endpoint = match &self.socks5 {
            Some(proxy) => build_proxied_quinn_endpoint(proxy).await?,
            None => quinn::Endpoint::client("0.0.0.0:0".parse().unwrap())?,
        };
        let conn = endpoint.connect_with(client_config, addr, server_name)?.await?;
        Ok(Connection::from_quinn_with_alpn(conn, alpn.to_vec()))
    }
}

#[cfg(feature = "socks5")]
async fn build_proxied_quinn_endpoint(
    proxy: &Socks5ProxyConfig,
) -> Result<quinn::Endpoint, ClientDialError> {
    // 1. TCP control connection to proxy.addr.
    // 2. SOCKS5 UDP ASSOCIATE handshake (with optional auth).
    // 3. Socks5UdpSocket::from_datagram on the result.
    // 4. quinn::Endpoint::new_with_abstract_socket with the Socks5UdpSocket.
}

4. dial_tcp_tls routes TCP through SOCKS5 CONNECT

When a proxy is configured, dial_tcp_tls connects a TcpStream to the proxy's address, performs the SOCKS5 CONNECT handshake (RFC 1928 §3) to the target addr, then wraps the resulting stream in TlsConnector as before. This is the straightforward TCP proxy case — SOCKS5 CONNECT is TCP-native. The TlsClientConfig, the SNI, the ALPN, and the Connection::from_bidi (ADR-065) are all unchanged.

Without a proxy, dial_tcp_tls is unchanged — TcpStream::connect(addr) then TlsConnector::connect. Same zero-cost default as dial_quic.

5. dial_iroh is the exception — deferred (OQ-67)

iroh's proxy_url (set at iroh::Endpoint construction) proxies iroh's HTTP(S) traffic — relay connections, DNS-over-HTTPS, pkarr publishing — through the proxy. This hides the client's IP from iroh's relay, which is a distinct privacy goal from hiding it from the peer. iroh's relay already hides the client's IP from the peer (the peer sees the relay's IP, by design), so proxy_url covers both exposure surfaces for the relay-mediated path without touching iroh's QUIC socket.

The open case is iroh's direct (hole-punched) connection: if iroh establishes a direct QUIC connection to the peer, the peer sees the client's real IP. Wrapping iroh's QUIC in SOCKS5 UDP ASSOCIATE is a different integration than the quinn POC — iroh has its own socket stack, not quinn::AsyncUdpSocket — and whether to force relay-only when a proxy is configured vs. wrap iroh's QUIC is an open question. See OQ-67.

For now, dial_iroh does not consume Socks5ProxyConfig. The iroh endpoint is built by the assembly layer (ADR-089 §3 — iroh shares the key, not the config); if the assembly layer sets iroh's proxy_url, the relay-exposure surface is covered. The peer-exposure surface for iroh direct connections is deferred to OQ-67. This does not block the first hub deployment — the hub's outbound worker dials (the hub-as-client case, ADR-087 §5) use QUIC or TCP+TLS, both of which honor the proxy.

6. Fallback policy is a caller concern, not a dial decision

When a proxy is configured and the proxy rejects UDP ASSOCIATE (the QUIC case) or CONNECT (the TCP case), dial_quic / dial_tcp_tls return an error. The dial does not silently fall back to a direct connection — that would defeat the privacy posture the caller configured the proxy to enforce. A caller that wants "try proxy, fall back to direct" composes it: catch the error, dial on an AlknetClient without the proxy set. Because the proxy is set once on the client (§2), this requires two AlknetClient instances — one built with with_socks5_proxy, one without — and the caller dials the proxy-less one on fallback. A future per-dial proxy override (§2, two-way-door) would remove the need for a second client, but the two-instance pattern is the composition the current API supports. The fallback policy is the caller's, not the dial's, because the dial cannot know whether the caller's privacy requirement permits a direct fallback. This mirrors ADR-089's "no transport fallback" stance — the dial is one-shot; the fallback policy is a caller concern.

The ClientDialError (ADR-089) gains one variant:

pub enum ClientDialError {
    // ... existing variants ...

    /// SOCKS5 proxy failure — handshake rejected, UDP ASSOCIATE
    /// unsupported, auth failed, or the proxy closed the control
    /// connection. The dial did not reach the remote; the caller
    /// decides whether to fall back to a direct dial or surface the
    /// error.
    #[error("SOCKS5 proxy: {0}")]
    Proxy(String),
}

Proxy(String) takes String (not the proxy crate's error type) for the same reason Connect(String) and Handshake(String) do per ADR-089 — the proxy error source type (fast-socks5 or a vendored impl) is an implementation detail; the category is in the variant. The string content is an implementation detail.

7. Feature gates

[features]
default = []
quinn = ["dep:quinn", "alknet-tls/quinn"]
tcp = ["dep:tokio-rustls", "alknet-tls/tcp"]
iroh = ["dep:iroh"]
socks5 = ["dep:fast-socks5"]   # enables the proxied dial paths

socks5 is independent of the transport features — it enables the proxy code path that dial_quic (UDP ASSOCIATE) and dial_tcp_tls (CONNECT) use when a proxy is configured. Enabling socks5 without quinn or tcp is a no-op (no dial uses it). Enabling quinn + socks5 enables proxied QUIC; tcp + socks5 enables proxied TCP+TLS. The fast-socks5 dep is behind socks5, so deployments that don't use a proxy don't pay the dep.

8. The socks5 crate dependency

The PoC uses fast-socks5 (v1.0.0, maintained by anyip.io, a residential proxy provider) for the SOCKS5 client handshake and the test server. The client-side surface used is small (Socks5Datagram::bind / bind_with_password, new_udp_header, the header parsing). Whether to keep fast-socks5 as a dep or vendor the ~100 lines of SOCKS5 handshake

• header framing is a two-way-door implementation detail. This ADR records that fast-socks5 is the starting choice (it's the validated choice from the PoC); vendoring is a future option if the dep becomes a concern. The AsyncUdpSocket impl (Socks5UdpSocket, ~250 lines) is alknet's own code regardless — it's the integration glue, not the SOCKS5 protocol implementation.

What this does NOT change

• AlknetEndpoint (ADR-083) — the server side is unchanged. The server accepts connections arriving from a proxy's IP, which is just normal QUIC/TCP. No proxy-specific code on the server.
• TlsClientConfig (ADR-087) — the client-side TLS config is unchanged. The proxy is below the TLS layer; the TLS handshake happens over the proxied transport exactly as it happens over a direct one.
• CallClient::spawn_dispatch / ChannelClient::from_connection (ADR-017, ADR-080) — the take-over APIs are unchanged. They consume the Connection the dial produces; they don't know it came through a proxy.
• The Connection type (ADR-065, ADR-070) — unchanged. A proxied QUIC connection still yields a Connection::from_quinn_with_alpn; a proxied TCP+TLS connection still yields a Connection::from_bidi. The Connection is proxy-unaware.
• The CallCredentials / RemoteIdentity (ADR-089) — unchanged. The credential bundle the dial takes is unaffected by the proxy.
• The hub's supervise_worker (hub README §"Dial") — the closure seam is unchanged. A hub that wants its outbound worker dials to go through a proxy builds its AlknetClient with with_socks5_proxy; the supervise_worker closure calls dial_quic / dial_tcp_tls and the proxy is applied transparently. The hub does not need to know the proxy exists.
• alknet-socks5 (the channels data-channel handler, ADR-085) — unchanged and out of scope. The two SOCKS5 concepts compose at the SOCKS5 protocol level, not the alknet type level (see §"Two distinct SOCKS5 uses" above).

Consequences

Positive:

• The privacy gap is closed for QUIC and TCP+TLS dials. A native client that wants to hide its real IP from the hub configures a SOCKS5 proxy; dial_quic and dial_tcp_tls route through it. The hub sees the proxy's IP. This is the capability the old ConnectOptions.proxy field aspired to but never delivered for TCP/TLS.
• The QUIC proxy is real, not theoretical. The PoC (/workspace/quinn-proxy-poc, 5/5 runs clean) and BotBrowser's production use validate the AsyncUdpSocket + UDP ASSOCIATE approach. The ECN loss is an accepted, documented cost of the privacy choice, not a hidden limitation.
• The proxy is uniform across the rustls dials. One Socks5ProxyConfig covers both dial_quic (UDP ASSOCIATE) and dial_tcp_tls (CONNECT). SOCKS5's TCP+UDP coverage is the reason a single proxy protocol suffices — no HTTP CONNECT variant needed.
• The proxy is invisible above the dial. Connection, dispatch, credentials, TLS config, the hub's supervise_worker closure — none know a proxy is in the path. The proxy is purely an establishment concern, localized to alknet-client.
• The no-proxy path is the zero-cost default. dial_quic and dial_tcp_tls without a configured proxy are byte-identical to ADR-089. The socks5 feature and the fast-socks5 dep are opt-in; deployments that don't use a proxy pay nothing.
• The two SOCKS5 concepts compose. A client using the hub's alknet/socks5 channels service for privacy points its dial Socks5ProxyConfig at the local tunnel end. No special integration; the composition is at the SOCKS5 protocol level.

Negative:

• iroh direct connections are not proxied by this ADR. dial_iroh does not consume Socks5ProxyConfig; iroh's proxy_url (set at the assembly layer) covers the relay-exposure surface, but a direct iroh connection exposes the client's real IP to the peer. This is OQ-67. It does not block the first hub deployment (hub outbound dials use QUIC/TCP+TLS), but it is a gap for iroh-direct privacy.
• The socks5 feature and fast-socks5 dep are new. A new optional feature and a new optional dep. The cost is contained (off by default, only pulled when a deployment uses a proxy), but it is a new entry in the feature matrix.
• ECN loss on proxied QUIC. The proxied QUIC path loses Explicit Congestion Notification. This is a performance cost on congested links, not a correctness issue. It is an inherent property of SOCKS5 UDP ASSOCIATE (the header has no ECN bits), not an alknet choice. Documented and accepted.
• Proxy must support UDP ASSOCIATE for the QUIC dial. A deployment requirement. ssh -D does not work; a UDP-capable SOCKS5 daemon (dante, fast-socks5-based, etc.) is needed. The dial surfaces a clear error when the proxy lacks UDP support; the operator chooses a compatible proxy.

Door type

One-way (proxy as a dial capability + the Socks5ProxyConfig shape). The proxy being a first-class dial parameter on AlknetClient is structural — every outbound-dialing role (hub, worker, hub-worker) that wants privacy depends on it. The Socks5ProxyConfig shape and the with_socks5_proxy builder method are one-way — changing them after consumers exist is a rewrite. The Proxy variant on ClientDialError is one-way (it's a public error variant). The socks5 feature name and the fast-socks5 dep choice are two-way (the feature can be renamed pre-1.0; the dep can be vendored later). The Socks5UdpSocket internal implementation is two-way. The iroh proxy question (OQ-67) is two-way until decided. The fallback policy (caller's concern, not the dial's) is one-way — once the dial refuses to silently fall back, callers rely on that for their privacy posture.

References

• PoC: /workspace/quinn-proxy-poc — run cargo run -r. Load-bearing file: src/socks5_udp_socket.rs (~250 lines). 5/5 runs clean.
• Research findings: docs/research/quinn-quic-proxy/findings.md — the full write-up: the AsyncUdpSocket extension point, the SOCKS5 UDP ASSOCIATE mechanism, the PoC topology, the limitations (ECN, UDP ASSOCIATE requirement), the alternatives rejected (fork quinn, QUIC-in-TCP, HTTP CONNECT, userspace QUIC-over-TCP, wait for upstream), and the integration sketch.
• ADR-089 — AlknetClient, the dial seam this ADR adds the proxy capability to. The three dials (dial_quic / dial_tcp_tls / dial_iroh) are the surfaces the proxy applies to.
• ADR-087 — TlsClientConfig, unchanged by the proxy (the TLS handshake happens over the proxied transport).
• ADR-083 — AlknetEndpoint, unchanged (the server accepts connections from a proxy's IP as normal).
• ADR-065 — Connection::from_quinn_with_alpn / from_bidi, unchanged (the Connection is proxy-unaware).
• ADR-014 — the no-env-vars invariant; the proxy config comes from Capabilities / the assembly layer, not env vars.
• ADR-085 — the scope table naming alknet-socks5 (the channels data-channel handler, distinct from this ADR's client-dial proxy).
• RFC 1928 (SOCKS5) §3 (CONNECT), §6/§7 (UDP ASSOCIATE + UDP request header).
• RFC 1929 (SOCKS5 username/password auth).
• BotBrowser UDP-over-SOCKS5 (deepwiki.com/botswin/BotBrowser/6.4-udp-over-socks5) — production implementation of the identical pattern in Chromium's network stack.
• OQ-67 (raised by this ADR) — iroh proxy support (direct-connection peer exposure).