alknet/docs/architecture/questions/067-iroh-proxy-support.md

OQ-67: iroh Proxy Support (Direct-Connection Peer Exposure)

• Origin: docs/architecture/decisions/090-client-dial-socks5-proxy-seam.md §5; docs/architecture/crates/client/README.md §"SOCKS5 proxy (ADR-090)".
• Status: resolved (by the iroh-proxy POC and ADR-090 §5 amendment, 2026-07-16)
• Door type: one-way (the force-relay-only decision is a deployment tradeoff: relay-bounded availability, no direct fallback)
• Priority: medium
• Impacts (now closed): A client that dials over iroh direct (hole-punched) connections and wants to hide its real IP from the peer. Did 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 (ADR-090). Did NOT block the relay-mediated iroh path. The gap was the iroh direct path: when iroh hole-punches a direct QUIC connection, the peer sees the client's real IP. Resolved by eliminating the direct path when a proxy is configured — force relay-only.
• Investigation (completed): Worked through the iroh socket stack to determine whether iroh exposes a socket abstraction analogous to quinn's AsyncUdpSocket + new_with_abstract_socket. Result: it does not. iroh uses a quinn fork (noq) that has new_with_abstract_socket, but iroh calls it internally with its own Transport multiplexer and keeps noq_endpoint() as pub(crate). The IP/direct transport binds its own netwatch::UdpSocket with no injection point. The only public socket-injection surface (unstable-custom-transports, CustomTransport) operates on a separate CustomAddr address space that iroh's hole-punching does not route through — wrong shape. The quinn POC's Socks5UdpSocket does not transfer to iroh. Making SOCKS5-UDP-over-iroh-direct work would require forking iroh.
• What is decided (ADR-090 §5, amended 2026-07-16): dial_iroh with a proxy configured forces relay-only via three stable public iroh Builder knobs: clear_ip_transports() (no IP/direct transport is bound), addr_filter(AddrFilter::relay_only()) (no direct IPs published), and proxy_url(http://...) (relay WebSocket tunneled through an HTTP CONNECT proxy). The peer sees the relay's IP; the relay sees the proxy's IP; the client's real IP is hidden on both surfaces. The POC (/workspace/iroh-proxy-poc, docs/research/iroh-proxy-poc/findings.md) validates this end-to-end: selected_is_relay=true, selected_is_ip=false, any_direct_ip_path=false, 45-byte echo through the proxied relay, 5/5 runs clean. No iroh fork required — all three knobs are unconditional public APIs.
• What is open: the direct-path SOCKS5-UDP option (Option 1) is not pursued. It requires forking iroh (no public IP-transport socket-injection hook; CustomTransport is the wrong address space), for a use case that is currently hypothetical (direct-path peer-IP privacy with direct-path latency). The quinn POC's Socks5UdpSocket remains the reference shape if iroh ever exposes an IP-transport socket hook upstream — tracked informally, not as an OQ (no concrete use case). The proxy_url coverage gap on pkarr/DoH (see below) is a separate gap, not this OQ's direct-path question.
• Correction to this OQ's original premises: the original "What is decided" section stated iroh's proxy_url "proxies iroh's HTTP(S) traffic (relay connections, DNS-over-HTTPS, pkarr publishing)." Tracing iroh 1.0.2, this is only partially true: proxy_url flows only to the relay transport actor and is used only for the relay's WebSocket connection (an HTTP CONNECT handshake). It does not flow to the pkarr publisher (uses the pkarr crate directly, not reqwest), nor to the DNS-over-HTTPS resolver (uses hickory-resolver directly), nor to the reqwest client builder (util.rs:80-91 has no .proxy() call). proxy_url covers the relay WebSocket exposure surface only. For alknet's privacy model this is fine because the recommended configuration is force relay-only: with clear_ip_transports(), QAD (QUIC address discovery) is disabled, and peer-IP exposure is fully handled by the relay path. If a deployment needs pkarr/DoH proxied too, that is a separate gap (a small upstream contribution to wire reqwest's .proxy() into iroh's util::reqwest_client_builder), not this OQ.
• The HTTP-to-SOCKS5 bridge: iroh's proxy_url expects an HTTP CONNECT proxy, but Socks5ProxyConfig (ADR-090) is SOCKS5. The integration runs a tiny local HTTP-to-SOCKS5 bridge (~80 lines, the POC's src/proxy.rs is the template) in the alknet client process when Socks5ProxyConfig is set and the iroh path is used. iroh's proxy_url is pointed at http://127.0.0.1:<local-port>. This unifies on a single Socks5ProxyConfig and is invisible to the operator. Behind the socks5 feature flag.
• What is given up: force relay-only forgoes iroh's direct-connection latency advantage (the relay adds one network hop). For the hub deployment (hub runs its own relay), this is negligible. Relay availability becomes a hard dependency — with clear_ip_transports(), if the relay is down, the client cannot connect at all. This is the intended privacy/availability tradeoff; a caller that prefers availability over privacy for the iroh path simply does not set the proxy.
• Resolution: Force relay-only (Option 2) is the default. Validated by the iroh-proxy POC, uses only stable public iroh APIs, requires no fork, and fully closes the peer-IP-exposure gap (by eliminating the direct path when a proxy is configured). Option 1 (SOCKS5 UDP ASSOCIATE over iroh's direct path) is not feasible without forking iroh and is not pursued (no concrete use case justifies the fork maintenance burden). The Socks5ProxyConfig covers all three dials uniformly: UDP ASSOCIATE for dial_quic, CONNECT for dial_tcp_tls, and force-relay-only + HTTP-to-SOCKS5 bridge for dial_iroh. See ADR-090 §5 (amended 2026-07-16).
• Cross-references: ADR-090 (§5 — resolves this OQ with the force-relay-only decision + HTTP-to-SOCKS5 bridge), ADR-089 (§3 — iroh shares the key, not the config; proxy_url is set at the assembly layer), ADR-087 (§3 — the iroh exception on the client side), docs/research/quinn-quic-proxy/findings.md (the quinn-over-SOCKS5 PoC — the reference shape Option 1 would need; does not transfer to iroh), docs/research/iroh-proxy-poc/findings.md (the iroh-proxy POC findings — the investigation that resolved this OQ).