zed/crates/proxy_handshake/src/proxy_handshake.rs

//! Sans-IO client handshakes for HTTP CONNECT and SOCKS proxies.
//!
//! Speaks the client side of the protocols needed to tunnel a TCP connection
//! through a proxy — HTTP CONNECT (RFC 9110 §9.3.6), SOCKS4/4a, and SOCKS5
//! (RFC 1928, with RFC 1929 username/password authentication) — as a pure
//! state machine that never touches a socket. Callers own all I/O: resolving
//! and connecting to the proxy, wrapping the connection in TLS when the proxy
//! requires it, and pumping bytes between the [`Handshake`] and their
//! transport. The `futures-io` and `tokio` features add ready-made drivers
//! for the corresponding I/O traits.
//!
//! ```
//! use proxy_handshake::{Handshake, ProxySpec, Step, Target, Url};
//!
//! let url: Url = "http://localhost:8888".parse().unwrap();
//! let spec = ProxySpec::parse(&url).unwrap();
//! let target = Target::Domain("example.com".into(), 443);
//! let mut handshake = Handshake::new(&spec, &target).unwrap();
//!
//! // The sans-IO loop: write `Send` bytes to the proxy, feed bytes the proxy
//! // sent back through `advance`, and start using the stream for the
//! // tunneled protocol once `Done` is returned.
//! let Ok(Step::Send(connect_request)) = handshake.advance(&[]) else {
//!     unreachable!()
//! };
//! assert!(connect_request.starts_with(b"CONNECT example.com:443 HTTP/1.1\r\n"));
//! ```

mod handshake;

#[cfg(feature = "futures-io")]
pub mod futures_io;
#[cfg(feature = "tokio")]
pub mod tokio;

use std::net::SocketAddr;

pub use handshake::{Handshake, Step};
pub use url::Url;

/// How to reach and authenticate with a proxy: the validated interpretation
/// of a proxy [`Url`].
///
/// A raw [`Url`] can hold any scheme, leaves default ports implicit, and
/// carries credentials percent-encoded. Parsing into a `ProxySpec` settles
/// all of that once — unsupported schemes are rejected, scheme-specific
/// default ports are applied, and credentials are decoded — so the handshake
/// and its callers never re-derive them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProxySpec {
    pub scheme: ProxyScheme,
    /// The proxy's host: a domain name or an IP address literal (without
    /// brackets for IPv6).
    pub host: String,
    pub port: u16,
    pub credentials: Option<Credentials>,
}

/// The protocol the proxy speaks, taken from the proxy URL's scheme.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProxyScheme {
    /// An HTTP CONNECT proxy (`http://` or `https://`). `tls` is whether the
    /// connection *to the proxy itself* is wrapped in TLS (an `https://`
    /// proxy URL); it is independent of any TLS the tunneled protocol layers
    /// inside the tunnel.
    Http { tls: bool },
    /// A SOCKS4 proxy (`socks4://` or `socks4a://`).
    Socks4 { remote_dns: bool },
    /// A SOCKS5 proxy (`socks5://` or `socks5h://`).
    Socks5 { remote_dns: bool },
}

/// Proxy credentials, percent-decoded from the URL's userinfo component.
#[derive(Clone, PartialEq, Eq)]
pub struct Credentials {
    pub username: String,
    pub password: String,
}

/// Redacts both fields so credentials can't leak through debug formatting of
/// any containing type. Implemented manually (rather than leaving `Debug`
/// underived) so a future `#[derive(Debug)]` on this struct is a conscious
/// choice instead of an accident.
impl std::fmt::Debug for Credentials {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Credentials")
            .field("username", &"<redacted>")
            .field("password", &"<redacted>")
            .finish()
    }
}

/// The destination to tunnel to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Target {
    /// An unresolved host name and port: DNS resolution is delegated to the
    /// proxy. With SOCKS4 proxies this is encoded using the SOCKS4a
    /// extension, which not every SOCKS4 proxy supports.
    ///
    /// The host must be a name, not arbitrary text: strings containing ASCII
    /// control bytes are rejected by [`Handshake::new`], since they could
    /// otherwise forge protocol structure in the messages the host is
    /// embedded in.
    Domain(String, u16),
    /// An already-resolved socket address. Use this when
    /// [`ProxySpec::remote_dns`] is false, resolving the host locally first.
    Address(SocketAddr),
}

/// The size cap on an HTTP CONNECT response head; a proxy that sends more
/// than this before the blank line is misbehaving.
pub const MAX_HTTP_RESPONSE_LENGTH: usize = 8192;

#[derive(Debug, thiserror::Error)]
pub enum ProxyError {
    #[error(
        "unsupported proxy scheme `{0}` (expected http, https, socks4, socks4a, socks5, or socks5h)"
    )]
    UnsupportedScheme(String),
    #[error("proxy URL is missing a host")]
    MissingHost,
    #[error("proxy credentials are not valid UTF-8 after percent-decoding")]
    InvalidCredentials,
    #[error("SOCKS5 usernames and passwords are limited to 255 bytes")]
    CredentialsTooLong,
    #[error("SOCKS target domains are limited to 255 bytes")]
    DomainTooLong,
    #[error("target domain contains ASCII control bytes")]
    DomainContainsControlBytes,
    #[error("SOCKS4 proxies only support IPv4 targets")]
    Socks4Ipv4Only,
    #[error("SOCKS4 user ids cannot contain NUL bytes")]
    Socks4UserIdContainsNul,
    #[error("proxy sent a malformed HTTP response: {0}")]
    MalformedHttpResponse(String),
    #[error("proxy refused CONNECT with HTTP status {0}")]
    HttpConnectRefused(u16),
    #[error("HTTP response from proxy exceeded {MAX_HTTP_RESPONSE_LENGTH} bytes")]
    HttpResponseTooLarge,
    #[error("proxy replied with SOCKS version {0:#04x}")]
    UnexpectedSocksVersion(u8),
    #[error("SOCKS5 proxy rejected the offered authentication method (selected {selected:#04x})")]
    AuthMethodRejected { selected: u8 },
    #[error("SOCKS5 proxy rejected the username/password")]
    AuthenticationFailed,
    #[error("SOCKS5 proxy refused the connection: {}", socks5_refusal_message(*.0))]
    Socks5ConnectRefused(u8),
    #[error("SOCKS5 proxy sent unknown address type {0:#04x}")]
    UnknownAddressType(u8),
    #[error("SOCKS4 proxy rejected the connection (code {0:#04x})")]
    Socks4ConnectRefused(u8),
}

/// Errors from a driver establishing a tunnel: either the proxy conversation
/// failed or the transport did.
#[cfg(any(feature = "futures-io", feature = "tokio"))]
#[derive(Debug, thiserror::Error)]
pub enum EstablishError {
    #[error(transparent)]
    Proxy(#[from] ProxyError),
    #[error(transparent)]
    Io(#[from] std::io::Error),
}

impl ProxySpec {
    /// Parses a proxy URL with an `http`, `https`, `socks4`, `socks4a`,
    /// `socks5`, or `socks5h` scheme. Missing ports default by scheme (80,
    /// 443, or 1080). Credentials in the userinfo component are
    /// percent-decoded, per RFC 3986 §3.2.1.
    pub fn parse(url: &Url) -> Result<Self, ProxyError> {
        let scheme = match url.scheme() {
            "http" => ProxyScheme::Http { tls: false },
            "https" => ProxyScheme::Http { tls: true },
            "socks4" => ProxyScheme::Socks4 { remote_dns: false },
            "socks4a" => ProxyScheme::Socks4 { remote_dns: true },
            "socks5" => ProxyScheme::Socks5 { remote_dns: false },
            "socks5h" => ProxyScheme::Socks5 { remote_dns: true },
            other => return Err(ProxyError::UnsupportedScheme(other.to_string())),
        };

        let host = match url.host().ok_or(ProxyError::MissingHost)? {
            url::Host::Domain(domain) => domain.to_string(),
            url::Host::Ipv4(ip) => ip.to_string(),
            url::Host::Ipv6(ip) => ip.to_string(),
        };
        let default_port = match scheme {
            ProxyScheme::Http { tls: false } => 80,
            ProxyScheme::Http { tls: true } => 443,
            ProxyScheme::Socks4 { .. } | ProxyScheme::Socks5 { .. } => 1080,
        };
        let port = url.port().unwrap_or(default_port);

        let credentials = if url.username().is_empty() && url.password().is_none() {
            None
        } else {
            Some(Credentials {
                username: decode_userinfo(url.username())?,
                password: decode_userinfo(url.password().unwrap_or_default())?,
            })
        };

        Ok(Self {
            scheme,
            host,
            port,
            credentials,
        })
    }

    /// Whether the target should be handed to the proxy as a host name
    /// ([`Target::Domain`]) instead of being resolved locally. True for HTTP
    /// CONNECT and the `socks4a`/`socks5h` schemes, matching curl's scheme
    /// semantics.
    pub fn remote_dns(&self) -> bool {
        match self.scheme {
            ProxyScheme::Http { .. } => true,
            ProxyScheme::Socks4 { remote_dns } | ProxyScheme::Socks5 { remote_dns } => remote_dns,
        }
    }

    /// Whether the connection to the proxy itself must be wrapped in TLS
    /// before the handshake starts (an `https://` proxy URL).
    pub fn tls(&self) -> bool {
        matches!(self.scheme, ProxyScheme::Http { tls: true })
    }
}

/// Decodes one component (username or password) of a URL's userinfo, which
/// RFC 3986 §3.2.1 defines as percent-encoded: the proxy must be sent the
/// decoded form.
fn decode_userinfo(component: &str) -> Result<String, ProxyError> {
    percent_encoding::percent_decode_str(component)
        .decode_utf8()
        .map(|decoded| decoded.into_owned())
        .map_err(|_| ProxyError::InvalidCredentials)
}

/// Matches `host` against a `NO_PROXY`-style exclusion list: comma-separated
/// entries that are `*`, an exact host, or a domain suffix (bare, with a
/// leading dot, or with a leading `*.`). Entries may carry a `:port`, which
/// is ignored — exclusion is by host. CIDR ranges are not supported.
pub fn no_proxy_matches(no_proxy: &str, host: &str) -> bool {
    no_proxy
        .split(',')
        .map(str::trim)
        .filter(|entry| !entry.is_empty())
        .any(|entry| {
            if entry == "*" {
                return true;
            }
            // Bare IPv6 literals also contain colons, so only strip a port
            // when there is exactly one colon and the suffix parses as one.
            let entry = match entry.rsplit_once(':') {
                Some((prefix, suffix))
                    if !prefix.contains(':') && suffix.parse::<u16>().is_ok() =>
                {
                    prefix
                }
                _ => entry,
            };
            let entry = entry.strip_prefix("*.").unwrap_or(entry);
            let entry = entry.strip_prefix('.').unwrap_or(entry);
            host.eq_ignore_ascii_case(entry)
                || (host.len() > entry.len()
                    && host.as_bytes()[host.len() - entry.len() - 1] == b'.'
                    && host[host.len() - entry.len()..].eq_ignore_ascii_case(entry))
        })
}

/// Human-readable descriptions of the SOCKS5 reply field's error codes,
/// verbatim from RFC 1928 §6.
fn socks5_refusal_message(code: u8) -> String {
    match code {
        0x01 => "general SOCKS server failure".to_string(),
        0x02 => "connection not allowed by ruleset".to_string(),
        0x03 => "network unreachable".to_string(),
        0x04 => "host unreachable".to_string(),
        0x05 => "connection refused".to_string(),
        0x06 => "TTL expired".to_string(),
        0x07 => "command not supported".to_string(),
        0x08 => "address type not supported".to_string(),
        other => format!("unknown error code {other:#04x}"),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parse_applies_default_ports_by_scheme() {
        assert_eq!(parse("http://proxy.example.com").port, 80);
        assert_eq!(parse("https://proxy.example.com").port, 443);
        assert_eq!(parse("socks4://proxy.example.com").port, 1080);
        assert_eq!(parse("socks5://proxy.example.com").port, 1080);
        assert_eq!(parse("http://proxy.example.com:3128").port, 3128);
    }

    #[test]
    fn parse_maps_schemes() {
        assert_eq!(parse("http://p").scheme, ProxyScheme::Http { tls: false });
        assert_eq!(parse("https://p").scheme, ProxyScheme::Http { tls: true });
        assert_eq!(
            parse("socks4://p").scheme,
            ProxyScheme::Socks4 { remote_dns: false }
        );
        assert_eq!(
            parse("socks4a://p").scheme,
            ProxyScheme::Socks4 { remote_dns: true }
        );
        assert_eq!(
            parse("socks5://p").scheme,
            ProxyScheme::Socks5 { remote_dns: false }
        );
        assert_eq!(
            parse("socks5h://p").scheme,
            ProxyScheme::Socks5 { remote_dns: true }
        );
    }

    #[test]
    fn parse_rejects_unknown_scheme() {
        let url: Url = "ftp://proxy.example.com".parse().unwrap();
        let Err(error) = ProxySpec::parse(&url) else {
            panic!("expected parsing to fail");
        };
        assert!(matches!(error, ProxyError::UnsupportedScheme(scheme) if scheme == "ftp"));
    }

    #[test]
    fn parse_percent_decodes_credentials() {
        let spec = parse("http://user:p%40ss@proxy.example.com:8080");
        let credentials = spec.credentials.unwrap();
        assert_eq!(credentials.username, "user");
        assert_eq!(credentials.password, "p@ss");
    }

    #[test]
    fn parse_supports_username_only_credentials() {
        let spec = parse("socks4://userid@proxy.example.com");
        let credentials = spec.credentials.unwrap();
        assert_eq!(credentials.username, "userid");
        assert_eq!(credentials.password, "");
    }

    #[test]
    fn parse_unbrackets_ipv6_hosts() {
        assert_eq!(parse("http://[::1]:8080").host, "::1");
    }

    #[test]
    fn remote_dns_follows_scheme() {
        assert!(parse("http://p").remote_dns());
        assert!(parse("https://p").remote_dns());
        assert!(!parse("socks4://p").remote_dns());
        assert!(parse("socks4a://p").remote_dns());
        assert!(!parse("socks5://p").remote_dns());
        assert!(parse("socks5h://p").remote_dns());
    }

    #[test]
    fn credentials_debug_output_is_redacted() {
        let credentials = Credentials {
            username: "user".to_string(),
            password: "hunter2".to_string(),
        };
        let debug_output = format!("{credentials:?}");
        assert!(!debug_output.contains("hunter2"));
        assert!(debug_output.contains("<redacted>"));
    }

    #[test]
    fn no_proxy_matching() {
        assert!(no_proxy_matches("example.com", "example.com"));
        assert!(no_proxy_matches("example.com", "sub.example.com"));
        assert!(no_proxy_matches(".example.com", "sub.example.com"));
        assert!(no_proxy_matches("*.example.com", "sub.example.com"));
        assert!(no_proxy_matches("other.org, example.com", "example.com"));
        assert!(no_proxy_matches("example.com:443", "example.com"));
        assert!(no_proxy_matches("*", "anything.at.all"));
        assert!(no_proxy_matches("EXAMPLE.com", "example.COM"));
        assert!(no_proxy_matches("::1", "::1"));

        assert!(!no_proxy_matches("example.com", "notexample.com"));
        assert!(!no_proxy_matches("example.com", "example.org"));
        assert!(!no_proxy_matches("", "example.com"));
        assert!(!no_proxy_matches("sub.example.com", "example.com"));
    }

    fn parse(url: &str) -> ProxySpec {
        ProxySpec::parse(&url.parse().unwrap()).unwrap()
    }
}