Add SOCKS5 support for outbound dialing

Author: yosebyte

README.md

@@ -60,7 +60,7 @@ The default `tls=1` creates an ephemeral self-signed certificate. Long-lived
 deployments should use `tls=2` with a PEM certificate and private key:
 
 ```bash
-nowhere 'portal://change-me@:2077?spec=nightfall&tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem'
+nowhere 'portal://change-me@:2077?tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem&spec=nightfall'
 ```
 
 ## Ecosystem

docs/configuration.md

@@ -3,42 +3,46 @@
 The Portal is configured by one URL.
 
 ```text
-portal://<shared-key>@<listen-host>:<listen-port>?tls=<mode>&spec=<spec>&alpn=<alpn>&net=<mode>&dial=<ip-or-auto>&rate=<mbps>&etar=<mbps>&crt=<path>&key=<path>&log=<level>
+portal://<shared-key>@<listen-host>:<listen-port>?log=<level>&tls=<mode>&crt=<path>&key=<path>&net=<mode>&spec=<spec>&alpn=<alpn>&rate=<mbps>&etar=<mbps>&dial=<ip-or-auto>&socks=<proxy>
 ```
 
 The URL username is the shared key. A password component is not supported. The
 listen port and a non-empty shared key are required. Unknown query parameters
 are ignored.
 
 Use percent encoding for reserved URL characters in the shared key, `spec`,
-`alpn`, and file paths.
+`alpn`, SOCKS credentials, and file paths.
 
 ## Input Rules
 
 The shared key, `spec`, and `alpn` are percent-decoded as UTF-8. A literal `+`
 in `spec` or `alpn` remains `+`; it is not converted to a space. If a query key
-appears more than once, the first occurrence is used.
+appears more than once, the first occurrence is used, except that duplicate
+`socks` parameters are rejected.
 
 | Input | Requirement | Decoded UTF-8 byte length |
 | --- | --- | --- |
 | shared key | Required and non-empty | `1..255` |
 | `spec` | Optional; empty means omitted | `1..255` when non-empty |
 | `alpn` | Optional; empty means omitted | `1..255` when non-empty |
+| SOCKS username | Required when SOCKS authentication is configured | `1..255` |
+| SOCKS password | Required when SOCKS authentication is configured | `1..255` |
 
 ## Parameters
 
 | Parameter | Default | Semantics |
 | --- | --- | --- |
+| `log` | `info` | `none`, `debug`, `info`, `warn`, `error`, or `event`. An unknown value selects `info`. |
 | `tls` | `1` | `1` creates an in-memory self-signed certificate. `2` loads PEM files from `crt` and `key`. `0` and all other values are rejected. |
+| `crt` | Empty | PEM certificate chain used by `tls=2`. |
+| `key` | Empty | PEM private key used by `tls=2`. |
+| `net` | `mix` | Selects ingress transports: `tcp` enables TLS/TCP, `udp` enables QUIC/UDP, and `mix` enables both. Missing and empty values select `mix`. |
 | `spec` | `auto` | Seed for v1 authentication material, deterministic padding, and field order. |
 | `alpn` | `now/1` | TLS and QUIC ALPN value. It does not alter authentication, padding, or frame layout. |
-| `net` | `mix` | Selects ingress transports: `tcp` enables TLS/TCP, `udp` enables QUIC/UDP, and `mix` enables both. Missing and empty values select `mix`. |
-| `dial` | `auto` | Local IP literal for outbound TCP and UDP sockets. Empty, invalid, hostname, and `auto` values select the operating-system default. |
 | `rate` | `0` | Client-to-target traffic limit in Mbps. |
 | `etar` | `0` | Target-to-client traffic limit in Mbps. |
-| `crt` | Empty | PEM certificate chain used by `tls=2`. |
-| `key` | Empty | PEM private key used by `tls=2`. |
-| `log` | `info` | `none`, `debug`, `info`, `warn`, `error`, or `event`. An unknown value selects `info`. |
+| `dial` | `auto` | Local IP literal for outbound TCP and UDP sockets. Empty, invalid, hostname, and `auto` values select the operating-system default. |
+| `socks` | `none` | SOCKS5 outbound proxy as `host:port` or `user:pass@host:port`. Missing, empty, and `none` disable proxying. IPv6 endpoints require brackets. |
 
 `rate` and `etar` accept positive decimal integers. Zero, a negative value, an
 invalid value, or omission disables the corresponding direction. The conversion
@@ -135,6 +139,36 @@ invalid address lets the operating system select the source address. When an IP
 is set, the Portal considers only target addresses from the same address
 family.
 
+When `socks` is enabled, `dial` instead binds the TCP control/CONNECT
+connections and UDP relay sockets used to reach the proxy. It does not bind a
+direct connection to the final target.
+
+## SOCKS5 Outbound Proxy
+
+SOCKS5 proxying applies to every outbound target, including loopback and
+private addresses:
+
+```text
+portal://secret@:2077?socks=proxy.example:1080
+portal://secret@:2077?socks=user:pass@proxy.example:1080
+portal://secret@:2077?socks=user:p%40ss@[2001:db8::10]:1080
+```
+
+Without credentials, the Portal offers only the SOCKS5 no-authentication
+method. With credentials, it offers only username/password authentication and
+does not permit a downgrade to no authentication. Target hostnames are sent to
+the proxy without local resolution. The proxy endpoint itself is resolved by
+the Portal.
+
+TCP relays use CONNECT. Each QUIC DATAGRAM or UoT flow owns a separate UDP
+ASSOCIATE control connection and relay socket. SOCKS5 UDP fragmentation is not
+supported; fragmented responses are discarded. A proxy error closes the
+current flow and never falls back to a direct target connection.
+
+The startup URL displays only the SOCKS endpoint. Credentials are omitted, so
+an authenticated startup URL is intentionally not a round-trippable copy of
+the command line.
+
 ## Logging Level
 
 The default level is `info`:
@@ -175,11 +209,17 @@ portal://secret@:2077?net=udp
 PEM certificate with event logs:
 
 ```text
-portal://secret@:2077?tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem&log=event
+portal://secret@:2077?log=event&tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem
 ```
 
 Directional limits:
 
 ```text
 portal://secret@:2077?rate=100&etar=200
 ```
+
+Authenticated SOCKS5 outbound routing:
+
+```text
+portal://secret@:2077?socks=user:pass@proxy.example:1080
+```

docs/integrations.md

@@ -67,7 +67,7 @@ For a long-lived Portal, use a stable certificate and an explicit public
 configuration:
 
 ```text
-portal://change-me@:2077?tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem&spec=nightfall&alpn=now%2F1&net=mix
+portal://change-me@:2077?tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem&net=mix&spec=nightfall&alpn=now%2F1
 ```
 
 Certificate and private-key paths are resolved by the Nowhere child process
@@ -172,7 +172,7 @@ A Portal using `net=mix` accepts either client mode. A Portal restricted to
 Run a public Portal with a stable certificate:
 
 ```text
-portal://change-me@:2077?tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem&spec=nightfall&alpn=now%2F1&net=mix
+portal://change-me@:2077?tls=2&crt=/etc/nowhere/cert.pem&key=/etc/nowhere/key.pem&net=mix&spec=nightfall&alpn=now%2F1
 ```
 
 Import a QUIC/UDP client configuration in Anywhere:

docs/operations.md

@@ -9,11 +9,30 @@ and UDP listeners must both bind successfully. The process logs the effective
 startup URL after defaults are applied:
 
 ```text
-portal::run: starting: portal://:<port>?tls=1&spec=auto&alpn=now/1&net=mix&dial=auto&rate=0&etar=0
+portal::run: starting: portal://:<port>?tls=1&net=mix&spec=auto&alpn=now/1&rate=0&etar=0&dial=auto&socks=none
 ```
 
 Use this line when comparing intended configuration with runtime behavior. It
-prints effective values, not necessarily the exact command-line URL.
+prints effective values, not necessarily the exact command-line URL. When
+SOCKS5 authentication is configured, this line prints only the proxy endpoint
+and never prints the username or password.
+
+## SOCKS5 Outbound Behavior
+
+When `socks` is configured, all TCP and UDP target traffic is routed through
+that SOCKS5 server. TCP uses CONNECT. Every QUIC DATAGRAM and UoT flow uses its
+own UDP ASSOCIATE control connection and relay socket. Closing the control
+connection closes the associated flow.
+
+Target domain names are resolved by the SOCKS5 server. The Portal resolves only
+the proxy endpoint and any domain returned by the proxy for its UDP relay. If
+`dial` specifies a local IP, proxy addresses and relay sockets must use the same
+address family.
+
+Proxy connection, authentication, command, or relay failures close only the
+affected Nowhere flow. The Portal never bypasses the configured proxy by
+falling back to a direct target connection. TCP proxy setup shares
+`NOW_TCP_DIAL_TIMEOUT`; UDP proxy setup shares `NOW_UDP_DIAL_TIMEOUT`.
 
 ## Logging
 

docs/protocol.md

@@ -33,7 +33,7 @@ and **MAY** are to be interpreted as normative requirements.
 The Portal is configured with one URL:
 
 ```text
-portal://<shared-key>@<listen-host>:<listen-port>?tls=<mode>&spec=<spec>&alpn=<alpn>&net=<mode>&dial=<ip-or-auto>&rate=<mbps>&etar=<mbps>&crt=<path>&key=<path>&log=<level>
+portal://<shared-key>@<listen-host>:<listen-port>?log=<level>&tls=<mode>&crt=<path>&key=<path>&net=<mode>&spec=<spec>&alpn=<alpn>&rate=<mbps>&etar=<mbps>&dial=<ip-or-auto>&socks=<proxy>
 ```
 
 Minimal configuration:
@@ -50,28 +50,32 @@ Unknown query parameters are ignored.
 
 The shared key, `spec`, and `alpn` are percent-decoded as UTF-8. A literal `+`
 in `spec` or `alpn` remains `+`; it is not converted to a space. If a query key
-occurs more than once, the first occurrence is used.
+occurs more than once, the first occurrence is used. Duplicate `socks`
+parameters MUST be rejected.
 
 | Input | Requirement | Decoded UTF-8 byte length |
 | --- | --- | --- |
 | Shared key | Required and non-empty | `1..255` |
 | `spec` | Optional; empty is treated as omitted | `1..255` when non-empty |
 | `alpn` | Optional; empty is treated as omitted | `1..255` when non-empty |
+| SOCKS username | Required when SOCKS authentication is configured | `1..255` |
+| SOCKS password | Required when SOCKS authentication is configured | `1..255` |
 
 ### 3.2 Parameters
 
 | Parameter | Default | Semantics |
 | --- | --- | --- |
+| `log` | `info` | `none`, `debug`, `info`, `warn`, `error`, or `event`. An unknown value selects `info`. |
 | `tls` | `1` | `1` creates a self-signed certificate. `2` loads PEM files from `crt` and `key`. Other values are invalid. |
+| `crt` | Empty | PEM certificate chain used by `tls=2`. |
+| `key` | Empty | PEM private key used by `tls=2`. |
+| `net` | `mix` | Selects ingress transports. `tcp` enables TLS/TCP, `udp` enables QUIC/UDP, and `mix` enables both. Missing and empty values select `mix`; other values are invalid. |
 | `spec` | `auto` | Deterministic seed for v1 authentication, padding, and frame layouts. |
 | `alpn` | `now/1` | QUIC/TLS ALPN override. It does not alter any other protocol field. |
-| `net` | `mix` | Selects ingress transports. `tcp` enables TLS/TCP, `udp` enables QUIC/UDP, and `mix` enables both. Missing and empty values select `mix`; other values are invalid. |
-| `dial` | `auto` | Local IP literal for outbound TCP and UDP sockets. Empty, invalid, hostname, and `auto` values select the operating-system default. |
 | `rate` | `0` | Client-to-target rate limit in Mbps. |
 | `etar` | `0` | Target-to-client rate limit in Mbps. |
-| `crt` | Empty | PEM certificate chain used by `tls=2`. |
-| `key` | Empty | PEM private key used by `tls=2`. |
-| `log` | `info` | `none`, `debug`, `info`, `warn`, `error`, or `event`. An unknown value selects `info`. |
+| `dial` | `auto` | Local IP literal for outbound TCP and UDP sockets. Empty, invalid, hostname, and `auto` values select the operating-system default. |
+| `socks` | `none` | SOCKS5 proxy as `host:port` or `user:pass@host:port`. Missing, empty, and `none` disable proxying. |
 
 `rate` and `etar` accept positive decimal integers. Zero, a negative value, an
 invalid value, or omission disables the corresponding limit. The conversion is:
@@ -87,6 +91,12 @@ has independent client-to-target and target-to-client buckets.
 relay and UoT. QUIC supports TCP relay on bidirectional streams and UDP relay
 in DATAGRAM frames.
 
+When `socks` is configured, every target MUST use that proxy. TCP uses SOCKS5
+CONNECT. Each UDP flow uses a separate UDP ASSOCIATE and retains its control
+connection for the flow lifetime. Target domain names are encoded in SOCKS5
+requests and resolved by the proxy. Proxy failure MUST NOT fall back to direct
+target access. `dial` binds connections and relay sockets toward the proxy.
+
 ### 3.3 Listen Address
 
 An empty listen host binds separate IPv4 and IPv6 wildcard sockets on the same
@@ -359,10 +369,12 @@ The receiver MUST reject a version other than `1`, an invalid target, an
 incorrect padding length, or incorrect padding bytes. The request padding is
 not forwarded to the target.
 
-After parsing the request, the Portal resolves and connects to the target,
-optionally binding the outbound socket to `dial`. It then relays bytes in both
-directions. When one direction reaches EOF, the other direction may continue
-for at most `NOW_TCP_READ_TIMEOUT`.
+After parsing the request, the Portal either resolves and connects directly to
+the target or sends the target unchanged in a configured SOCKS5 CONNECT
+request. `dial` binds the direct target socket or the connection to the SOCKS5
+server. The Portal then relays bytes in both directions. When one direction
+reaches EOF, the other direction may continue for at most
+`NOW_TCP_READ_TIMEOUT`.
 
 ## 9. UDP Relay
 
@@ -429,7 +441,9 @@ target_len_u16 || target_utf8
 `target_len_u16` MUST be from 1 through 512, and `target_utf8` MUST satisfy
 Section 10. The Portal bounds reading the complete setup target by
 `NOW_HANDSHAKE_TIMEOUT`. It then resolves the target and opens one connected UDP
-socket, optionally binding its source address according to `dial`.
+socket, optionally binding its source address according to `dial`. With SOCKS5
+enabled, it instead creates a per-flow UDP ASSOCIATE, keeps the associated TCP
+control connection open, and sends the target in each SOCKS5 UDP packet.
 
 After setup, both directions consist only of packet frames:
 

docs/quick-start.md

@@ -40,14 +40,15 @@ This starts the Portal with these effective defaults:
 | shared key | `secret` |
 | listen host | empty host, dual-stack wildcard |
 | listen port | `2077` |
+| `log` | `info` |
 | `tls` | `1`, generated self-signed certificate |
 | `net` | `mix`, TLS/TCP and QUIC/UDP listeners |
 | `spec` | `auto` |
 | `alpn` | `now/1` |
-| `dial` | `auto` |
 | `rate` | `0`, disabled |
 | `etar` | `0`, disabled |
-| `log` | `info` |
+| `dial` | `auto` |
+| `socks` | `none`, direct outbound connections |
 
 The startup log prints the effective URL after parsing. Treat that line as the
 operator-facing source of truth for the running process.

src/common/mod.rs

@@ -6,6 +6,7 @@
 mod config;
 mod logger;
 mod network;
+mod socks;
 mod tls;
 
 pub use config::{
@@ -16,4 +17,5 @@ pub use config::{
 };
 pub use logger::{LogLevel, Logger};
 pub use network::{bind_udp_addrs, dial_tcp_from_local_ip, dial_udp_from_local_ip};
+pub(crate) use socks::{OutboundDialer, OutboundUdpSocket, SocksConfig};
 pub use tls::{TLSMode, new_server_configs};

src/common/network.rs

@@ -95,15 +95,15 @@ pub async fn dial_udp_from_local_ip(
         .map_err(|_| anyhow!("common::util::dial_udp_from_local_ip: dial timeout"))?
 }
 
-fn parse_local_ip(dialer_ip: &str) -> Option<IpAddr> {
+pub(super) fn parse_local_ip(dialer_ip: &str) -> Option<IpAddr> {
     if dialer_ip == DEFAULT_DIALER_IP {
         None
     } else {
         dialer_ip.parse::<IpAddr>().ok()
     }
 }
 
-fn filter_addrs(
+pub(super) fn filter_addrs(
     addrs: impl Iterator<Item = SocketAddr>,
     local_ip: Option<IpAddr>,
 ) -> Vec<SocketAddr> {
@@ -117,7 +117,10 @@ fn filter_addrs(
         .collect()
 }
 
-async fn connect_tcp_addr(local_ip: Option<IpAddr>, target: SocketAddr) -> Result<TcpStream> {
+pub(super) async fn connect_tcp_addr(
+    local_ip: Option<IpAddr>,
+    target: SocketAddr,
+) -> Result<TcpStream> {
     if let Some(ip) = local_ip {
         let socket = if target.is_ipv4() {
             TcpSocket::new_v4()
@@ -138,7 +141,10 @@ async fn connect_tcp_addr(local_ip: Option<IpAddr>, target: SocketAddr) -> Resul
     }
 }
 
-async fn connect_udp_addr(local_ip: Option<IpAddr>, target: SocketAddr) -> Result<UdpSocket> {
+pub(super) async fn connect_udp_addr(
+    local_ip: Option<IpAddr>,
+    target: SocketAddr,
+) -> Result<UdpSocket> {
     let bind_addr = match local_ip {
         Some(ip) => SocketAddr::new(ip, 0),
         None if target.is_ipv4() => SocketAddr::from(([0, 0, 0, 0], 0)),

src/common/socks.rs

@@ -0,0 +1,27 @@
+// Copyright (C) 2026 NodePassProject <https://github.com/NodePassProject>
+// SPDX-License-Identifier: GPL-3.0-only
+
+//! SOCKS5 configuration and direct-or-proxied outbound dialing.
+
+#[path = "socks/config.rs"]
+mod config;
+#[path = "socks/outbound.rs"]
+mod outbound;
+#[path = "socks/protocol.rs"]
+mod protocol;
+#[path = "socks/udp.rs"]
+mod udp;
+
+pub(crate) use config::SocksConfig;
+pub(crate) use outbound::OutboundDialer;
+pub(crate) use udp::OutboundUdpSocket;
+
+#[cfg(test)]
+use protocol::{
+    ADDRESS_IPV4, AUTH_NONE, AUTH_PASSWORD, COMMAND_CONNECT, COMMAND_UDP_ASSOCIATE, SOCKS_VERSION,
+    SocksAddress, encode_address, parse_udp_header, read_address,
+};
+
+#[cfg(test)]
+#[path = "../tests/common/socks.rs"]
+mod tests;