seer-core 0.57.0

//! Shared SSRF protection helpers.
//!
//! `validate_public_host` rejects any hostname/IP that resolves to a reserved,
//! loopback, link-local, private, multicast, benchmarking, documentation, or
//! cloud-metadata address range. Used by every outbound leg of seer to ensure
//! user-supplied domains cannot be weaponized as an SSRF primitive.

use std::net::{IpAddr, SocketAddr};
use std::time::Duration;

use hickory_resolver::config::{ResolverConfig, GOOGLE};
use hickory_resolver::net::runtime::TokioRuntimeProvider;
use hickory_resolver::TokioResolver;
use reqwest::Url;
use std::sync::LazyLock;
use tokio::net::lookup_host;
use tracing::debug;

use crate::error::{Result, SeerError};

/// Fallback resolver used when the OS resolver (`getaddrinfo`) fails.
///
/// Points at Google DNS (8.8.8.8 / 8.8.4.4) so seer keeps working on hosts
/// with a broken or misconfigured system resolver — a common failure mode
/// on corporate Macs, active VPNs, or systems where a local dnsmasq /
/// stubby is down. `use_hosts_file = false` because the hosts file is a
/// system-DNS concept and we only consult the fallback when system DNS
/// has already failed.
///
/// Security posture: the fallback only engages when `getaddrinfo` returned
/// an error (not a result). A successful getaddrinfo — including one that
/// returns a reserved IP — is still trusted and still blocked by the
/// reserved-IP check. The pre-existing time-of-check/time-of-use window
/// between validation and the actual outbound connect is unchanged.
static FALLBACK_RESOLVER: LazyLock<Option<TokioResolver>> = LazyLock::new(|| {
    let mut builder = TokioResolver::builder_with_config(
        ResolverConfig::udp_and_tcp(&GOOGLE),
        TokioRuntimeProvider::default(),
    );
    {
        // Shared with the main DNS resolver so the two option sets cannot
        // drift; in particular this pins the server order to IPv4-first, which
        // keeps a black-holed IPv6 upstream from burning the whole budget on a
        // host with advertised-but-dead IPv6. That matters more here than
        // anywhere else: this resolver only runs when the OS resolver has
        // already failed.
        crate::dns::apply_standard_opts(builder.options_mut(), Duration::from_secs(5));
    }
    // Mirror the `LazyLock<Option<…>>` pattern used for the shared HTTP clients
    // rather than `.expect()` in a library initializer: the build is infallible
    // today (no TLS features), but a `None` here degrades to a typed DNS error
    // at the call site instead of a process panic if that ever changes.
    builder.build().ok()
});

/// Upper bound on the primary OS-resolver (`getaddrinfo`) lookup in
/// [`resolve_public_host`]. `getaddrinfo` has no built-in deadline; this cap
/// stops a single hostile/black-holed hostname from hanging a worker thread
/// indefinitely. Matches the fallback resolver's 5s per-attempt budget.
const PRIMARY_RESOLVE_TIMEOUT: Duration = Duration::from_secs(5);

/// Reject an IP address if it belongs to any range that is not appropriate
/// for outbound queries from a public-facing tool.
///
/// This is the single source of truth for SSRF range checks across every
/// outbound leg (RDAP, WHOIS, DNS nameservers, HTTP probes, TLS inspection,
/// webhooks). It covers, for IPv4: loopback, private (RFC 1918), link-local
/// (incl. 169.254.169.254 metadata), multicast, broadcast, 0.0.0.0/8,
/// documentation (RFC 5737), CGNAT (100.64/10), IETF 192.0.0.0/24, the
/// deprecated 6to4 relay anycast 192.88.99.0/24, benchmarking (198.18/15),
/// and 240/4; and for IPv6: loopback, multicast, unspecified, ULA (fc00::/7),
/// link-local (fe80::/10), site-local (fec0::/10), discard-only (100::/64),
/// documentation (2001:db8::/32, 3fff::/20), benchmarking (2001:2::/48),
/// Teredo (2001::/32), 6to4 (2002::/16), SRv6 SIDs (5f00::/16), NAT64
/// (64:ff9b::/96, 64:ff9b:1::/48), and the IPv4-mapped, SIIT
/// IPv4-translated and IPv4-compatible forms (re-checking the embedded IPv4).
pub fn is_reserved_ip(ip: IpAddr) -> bool {
    match ip {
        IpAddr::V4(v4) => {
            let o = v4.octets();
            v4.is_loopback()
                || v4.is_private()
                || v4.is_link_local()
                || v4.is_multicast()
                || v4.is_broadcast()
                || v4.is_unspecified()
                || v4.is_documentation()
                // 0.0.0.0/8 — "this network" (RFC 1122).
                || o[0] == 0
                // 240.0.0.0/4 — reserved (former class E).
                || o[0] >= 240
                // 100.64.0.0/10 — carrier-grade NAT / shared address space.
                || (o[0] == 100 && (o[1] & 0xC0) == 64)
                // 192.0.0.0/24 — IETF protocol assignments.
                || (o[0] == 192 && o[1] == 0 && o[2] == 0)
                // 192.88.99.0/24 — deprecated 6to4 relay anycast (RFC 7526).
                || (o[0] == 192 && o[1] == 88 && o[2] == 99)
                // 198.18.0.0/15 — network benchmark.
                || (o[0] == 198 && (o[1] == 18 || o[1] == 19))
        }
        IpAddr::V6(v6) => {
            if v6.is_loopback() || v6.is_multicast() || v6.is_unspecified() {
                return true;
            }
            let seg = v6.segments();
            // Unique-local fc00::/7
            if (seg[0] & 0xfe00) == 0xfc00 {
                return true;
            }
            // Link-local fe80::/10
            if (seg[0] & 0xffc0) == 0xfe80 {
                return true;
            }
            // Site-local fec0::/10 (RFC 3879, deprecated but still a non-global,
            // internal-only range a malicious AAAA could point at).
            if (seg[0] & 0xffc0) == 0xfec0 {
                return true;
            }
            // Documentation 2001:db8::/32 and 3fff::/20 (RFC 9637).
            if (seg[0] == 0x2001 && seg[1] == 0x0db8) || (seg[0] == 0x3fff && seg[1] & 0xf000 == 0)
            {
                return true;
            }
            // Benchmarking 2001:2::/48 (RFC 5180).
            if seg[0] == 0x2001 && seg[1] == 0x0002 && seg[2] == 0 {
                return true;
            }
            // Discard-only 100::/64 (RFC 6666).
            if seg[0] == 0x0100 && seg[1] == 0 && seg[2] == 0 && seg[3] == 0 {
                return true;
            }
            // SRv6 SIDs 5f00::/16 (RFC 9602) — segment identifiers, not hosts.
            if seg[0] == 0x5f00 {
                return true;
            }
            // 6to4 2002::/16 — embeds an IPv4 a 6to4 relay can reach (e.g.
            // 2002:a9fe:a9fe:: -> 169.254.169.254); block the whole prefix.
            if seg[0] == 0x2002 {
                return true;
            }
            // NAT64 well-known prefix 64:ff9b::/96 — a NAT64 gateway translates
            // the embedded IPv4, including private/metadata ranges.
            if seg[0] == 0x0064
                && seg[1] == 0xff9b
                && seg[2] == 0
                && seg[3] == 0
                && seg[4] == 0
                && seg[5] == 0
            {
                return true;
            }
            // NAT64 RFC 8215 local-use prefix 64:ff9b:1::/48 — same translation
            // risk as the well-known /96; block the whole /48 (issue #52).
            if seg[0] == 0x0064 && seg[1] == 0xff9b && seg[2] == 0x0001 {
                return true;
            }
            // Teredo 2001::/32 (RFC 4380) — tunnels to an obfuscated embedded
            // IPv4 via a relay, the same translation risk as 6to4/NAT64. No
            // legitimate public service is addressed from this prefix.
            if seg[0] == 0x2001 && seg[1] == 0 {
                return true;
            }
            // SIIT IPv4-translated ::ffff:0:a.b.c.d (::ffff:0:0:0/96, RFC 2765
            // / RFC 6052 §2.1) — a stateless translator reaches the embedded
            // IPv4, so re-check it like the mapped form below.
            if seg[0] == 0
                && seg[1] == 0
                && seg[2] == 0
                && seg[3] == 0
                && seg[4] == 0xffff
                && seg[5] == 0
            {
                let embedded = std::net::Ipv4Addr::from(((seg[6] as u32) << 16) | seg[7] as u32);
                if is_reserved_ip(IpAddr::V4(embedded)) {
                    return true;
                }
            }
            // IPv4-mapped (::ffff:0:0/96) — re-check the embedded IPv4.
            if v6
                .to_ipv4_mapped()
                .is_some_and(|v4| is_reserved_ip(IpAddr::V4(v4)))
            {
                return true;
            }
            // IPv4-compatible (::/96, deprecated) — high 96 bits zero, low 32
            // an IPv4. `to_ipv4_mapped()` does NOT catch this form, so re-check
            // the embedded IPv4 (catches ::169.254.169.254). :: and ::1 are
            // already handled above.
            if seg[0] == 0
                && seg[1] == 0
                && seg[2] == 0
                && seg[3] == 0
                && seg[4] == 0
                && seg[5] == 0
            {
                let embedded = std::net::Ipv4Addr::from(((seg[6] as u32) << 16) | seg[7] as u32);
                if is_reserved_ip(IpAddr::V4(embedded)) {
                    return true;
                }
            }
            false
        }
    }
}

/// Resolve a hostname and verify every resolved address is public.
/// Port is required because the primary resolution path goes through
/// `lookup_host`, which resolves services by `(host, port)`.
///
/// Uses the OS resolver (`getaddrinfo`) as the primary path and falls back
/// to hickory (Google DNS) only when the OS resolver returns an error. A
/// successful OS answer is never second-guessed: one naming a reserved
/// address is still refused, not re-resolved through the fallback.
///
/// Returns `Ok(())` when all resolved IPs are public;
/// `Err(SeerError::InvalidInput)` when the host is (or resolves to) a
/// reserved address, and `Err(SeerError::DnsError)` when it cannot be
/// resolved at all. Does NOT follow CNAMEs explicitly — relies on whichever
/// resolver answered.
pub async fn validate_public_host(host: &str, port: u16) -> Result<()> {
    resolve_public_host(host, port).await.map(|_| ())
}

/// Resolve a hostname to its public socket addresses, with hickory fallback.
///
/// Same security envelope as [`validate_public_host`] (OS resolver primary,
/// hickory fallback on OS error, reserved-IP rejection) but returns the
/// resolved [`SocketAddr`]s so callers can pass them to
/// [`tokio::net::TcpStream::connect`] without a second DNS round-trip.
///
/// Use this from any outbound-connect path so a broken system resolver
/// (corporate Macs, active VPNs, Tailscale Split-DNS claiming a domain
/// MagicDNS can't answer) doesn't take the path down.
pub async fn resolve_public_host(host: &str, port: u16) -> Result<Vec<SocketAddr>> {
    // Short-circuit: IP literal parse
    if let Ok(ip) = host.parse::<IpAddr>() {
        if is_reserved_ip(ip) {
            return Err(SeerError::InvalidInput(format!(
                "refusing to connect to reserved address: {}",
                ip
            )));
        }
        return Ok(vec![SocketAddr::new(ip, port)]);
    }

    // Cap the primary OS-resolver (`getaddrinfo`) lookup: it has no built-in
    // deadline and can hang indefinitely against a black-holed authoritative
    // server, which would pin a worker/dispatch thread forever (a cheap DoS).
    // On timeout we treat it like an OS-resolver error and fall through to the
    // hickory fallback, which is itself bounded (opts.timeout / attempts).
    let addrs: Vec<SocketAddr> =
        match tokio::time::timeout(PRIMARY_RESOLVE_TIMEOUT, lookup_host((host, port))).await {
            Ok(Ok(iter)) => iter.collect(),
            os_failure => {
                // OS resolver could not answer (error or timeout) — fall back to
                // hickory (Google DNS) so a broken/hung system resolver doesn't
                // take the whole tool down. Logged at debug! because the fallback
                // is transparent by design; NXDOMAIN for a host that genuinely
                // doesn't exist (e.g. a stale WHOIS server entry) lands here too,
                // so warn! would cry wolf on benign negative answers. If BOTH
                // resolvers fail, the DnsError below is the load-bearing
                // signal. It is a DNS failure, not invalid caller input: the
                // host is often an upstream server (a WHOIS referral), and
                // `DnsError` sanitizes to its category so that hostname and
                // the raw resolver text never reach an API/MCP client.
                let os_err = match os_failure {
                    Ok(Err(e)) => e.to_string(),
                    _ => format!(
                        "OS resolver timed out after {}s",
                        PRIMARY_RESOLVE_TIMEOUT.as_secs()
                    ),
                };
                debug!(
                    host = %host,
                    error = %os_err,
                    "OS resolver could not resolve host; trying hickory fallback"
                );
                let Some(resolver) = FALLBACK_RESOLVER.as_ref() else {
                    return Err(SeerError::DnsError(format!(
                    "DNS resolution failed for {host}: {os_err} (no fallback resolver available)"
                )));
                };
                match resolver.lookup_ip(host).await {
                    Ok(resp) => resp.iter().map(|ip| SocketAddr::new(ip, port)).collect(),
                    Err(fallback_err) => {
                        return Err(SeerError::DnsError(format!(
                            "DNS resolution failed for {host}: {os_err} (fallback: {fallback_err})"
                        )));
                    }
                }
            }
        };

    if addrs.is_empty() {
        return Err(SeerError::DnsError(format!(
            "no addresses resolved for {host}"
        )));
    }

    for sa in &addrs {
        if is_reserved_ip(sa.ip()) {
            // Keep the resolved IP out of the client-facing error: echoing it
            // turned the SSRF guard into an internal-DNS oracle (a caller could
            // learn that `internal.corp.example` resolves to 10.1.2.3). The
            // detailed reason stays in the server logs only (issue #49).
            debug!(
                host = %host,
                resolved_ip = %sa.ip(),
                "refusing host: resolves to a reserved (non-public) address"
            );
            return Err(SeerError::InvalidInput(format!(
                "{host} is not permitted (resolves to a non-public address)"
            )));
        }
    }

    Ok(addrs)
}

/// User agent for seer's own HTTP probes (status, headers, takeover, webhook).
pub(crate) const USER_AGENT: &str = concat!("Seer/", env!("CARGO_PKG_VERSION"));

/// The TLS config every reqwest client is built with: what reqwest 0.13's
/// `rustls` feature builds for a default client — the OS trust store through
/// `rustls-platform-verifier`, TLS 1.2 and 1.3, ALPN `h2` then `http/1.1` —
/// on the aws-lc-rs provider named explicitly, built once.
///
/// reqwest rebuilds the verifier for every client, and on Linux that re-reads
/// the system root store from disk (~1.7 ms of blocking file I/O on an async
/// worker). The guarded fetcher builds a client per redirect hop, so a bulk
/// `status` paid that per domain and per hop. `Err` when the verifier cannot
/// be built; [`client_builder`] then lets reqwest build its own, which
/// reports the same failure.
static HTTP_TLS: LazyLock<std::result::Result<rustls::ClientConfig, String>> =
    LazyLock::new(|| {
        let provider = std::sync::Arc::new(rustls::crypto::aws_lc_rs::default_provider());
        let verifier =
            rustls_platform_verifier::Verifier::new(provider.clone()).map_err(|e| e.to_string())?;
        let mut config = rustls::ClientConfig::builder_with_provider(provider)
            .with_protocol_versions(rustls::ALL_VERSIONS)
            .map_err(|e| e.to_string())?
            .dangerous()
            .with_custom_certificate_verifier(std::sync::Arc::new(verifier))
            .with_no_client_auth();
        config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
        Ok(config)
    });

/// Starts a reqwest client for an outbound leg: an overall `timeout`,
/// redirects never followed automatically, no proxy, and the shared TLS
/// config (`HTTP_TLS`).
///
/// reqwest's own redirect policy would resolve each `Location` host itself,
/// skipping the SSRF guard and any `resolve_to_addrs` pin (redirect-based
/// SSRF); legs that need redirects follow them by hand and re-validate every
/// hop. Proxies are off for the same reason: by default reqwest honors
/// `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY`, and a proxy resolves the target
/// host itself, so the vetted, pinned addresses would never be used.
pub(crate) fn client_builder(timeout: Duration) -> reqwest::ClientBuilder {
    let builder = reqwest::Client::builder()
        .timeout(timeout)
        .redirect(reqwest::redirect::Policy::none())
        .no_proxy();
    match &*HTTP_TLS {
        Ok(tls) => builder.tls_backend_preconfigured(tls.clone()),
        Err(e) => {
            debug!(error = %e, "shared TLS config unavailable; reqwest builds its own");
            builder
        }
    }
}

/// Orders addresses IPv4 first, each family keeping its given order.
///
/// Resolvers commonly return AAAA before A, and on a host with an IPv6 route
/// but no IPv6 transit a leading IPv6 address burns the whole budget before
/// any IPv4 one is tried. IPv6 stays as the fallback, so IPv6-only hosts still
/// work. `ip` projects the address out of each element.
pub(crate) fn ipv4_first<T>(addrs: &mut [T], ip: impl Fn(&T) -> IpAddr) {
    addrs.sort_by_key(|a| ip(a).is_ipv6());
}

/// Why [`connect_any`] found no address to connect to.
#[derive(Debug)]
pub(crate) enum ConnectError {
    /// The last address tried ran out of its share of the budget.
    TimedOut,
    /// The last address tried failed outright (or there were none).
    Io(std::io::Error),
}

/// Connects to the first of `addrs` that accepts, IPv4 first, all within
/// `timeout`.
///
/// Each address gets an equal share of the budget still left, and a failure
/// or an expired share moves on to the next address. One connect over the
/// whole list under a single deadline let a black-holed first address (an
/// IPv6 route with no IPv6 transit) spend the entire budget, so a reachable
/// IPv4 address behind it was never tried.
pub(crate) async fn connect_any<T, F, Fut>(
    addrs: &[SocketAddr],
    timeout: Duration,
    connect: F,
) -> std::result::Result<T, ConnectError>
where
    F: Fn(SocketAddr) -> Fut,
    Fut: std::future::Future<Output = std::io::Result<T>>,
{
    let mut ordered = addrs.to_vec();
    ipv4_first(&mut ordered, SocketAddr::ip);
    let deadline = tokio::time::Instant::now() + timeout;
    let mut last = ConnectError::Io(std::io::Error::new(
        std::io::ErrorKind::InvalidInput,
        "no address to connect to",
    ));
    for (i, addr) in ordered.iter().enumerate() {
        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
        if remaining.is_zero() {
            break;
        }
        // `ordered.len() - i` is at least 1: the addresses not yet tried.
        let share = remaining / u32::try_from(ordered.len() - i).unwrap_or(u32::MAX);
        match tokio::time::timeout(share, connect(*addr)).await {
            Ok(Ok(stream)) => return Ok(stream),
            Ok(Err(e)) => last = ConnectError::Io(e),
            Err(_) => last = ConnectError::TimedOut,
        }
    }
    Err(last)
}

/// A URL's host as the SSRF guard wants it. Uses `host()` rather than
/// `host_str()` so an IPv6 literal comes back unbracketed and hits
/// [`resolve_public_host`]'s IP-literal short-circuit.
pub(crate) fn url_host(url: &Url) -> Option<String> {
    Some(match url.host()? {
        url::Host::Domain(d) => d.to_string(),
        url::Host::Ipv4(ip) => ip.to_string(),
        url::Host::Ipv6(ip) => ip.to_string(),
    })
}

/// Validates an HTTP(S) URL as an outbound target and returns the public
/// socket addresses to pin the connection to.
///
/// This is the URL-shaped entry point to the same policy
/// [`resolve_public_host`] enforces for bare hosts, and is the single
/// implementation shared by every HTTP fetch that follows a user- or
/// server-supplied URL (`status`, `headers`, `takeover`). Beyond the
/// reserved-range check it enforces three URL-level rules:
///
/// - **Scheme**: only `http`/`https`. A `file://`/`gopher://` redirect target
///   would otherwise escape the HTTP threat model entirely.
/// - **No credentials**: an embedded `user:pass@` is refused, so a redirect
///   cannot smuggle credentials into a request seer originates.
/// - **Standard ports only** (80/443): without this a redirect chain becomes a
///   port scanner against whatever the resolved host exposes.
///
/// Returns [`SeerError::HttpError`] for URL-shape violations and for a host
/// that fails the reserved-range check.
pub(crate) async fn validate_http_url(url: &Url) -> Result<Vec<SocketAddr>> {
    let scheme = url.scheme();
    if scheme != "https" && scheme != "http" {
        return Err(SeerError::HttpError(format!(
            "unsupported URL scheme: {}",
            scheme
        )));
    }

    if !url.username().is_empty() || url.password().is_some() {
        return Err(SeerError::HttpError(
            "URL credentials are not allowed".to_string(),
        ));
    }

    let host = url_host(url).ok_or_else(|| SeerError::HttpError("missing URL host".to_string()))?;
    let port = url.port_or_known_default().unwrap_or(443);

    // Standard HTTP/HTTPS ports only, for the initial URL and every redirect
    // hop alike — otherwise a redirect chain becomes a port scanner.
    if port != 80 && port != 443 {
        return Err(SeerError::HttpError(format!(
            "non-standard port {} is not allowed",
            port
        )));
    }

    resolve_public_host(&host, port)
        .await
        .map_err(|e| SeerError::HttpError(e.to_string()))
}

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

    /// The SSRF fallback resolver must carry the same options as the main
    /// resolver — most importantly the pinned server order, without which a
    /// black-holed IPv6 upstream can burn the whole budget. The two used to
    /// hold hand-copied option sets; this asserts they still share one.
    #[test]
    fn fallback_resolver_opts_match_the_shared_standard() {
        use hickory_resolver::config::{ResolverOpts, ServerOrderingStrategy};

        let mut opts = ResolverOpts::default();
        crate::dns::apply_standard_opts(&mut opts, Duration::from_secs(5));
        assert_eq!(
            opts.server_ordering_strategy,
            ServerOrderingStrategy::UserProvidedOrder
        );
        assert_eq!(opts.timeout, Duration::from_secs(5));
        assert_eq!(opts.attempts, 2);
    }

    #[test]
    fn rejects_loopback_v4() {
        assert!(is_reserved_ip("127.0.0.1".parse().unwrap()));
    }

    #[test]
    fn rejects_metadata_v4() {
        assert!(is_reserved_ip("169.254.169.254".parse().unwrap()));
    }

    #[test]
    fn rejects_rfc1918() {
        assert!(is_reserved_ip("10.0.0.1".parse().unwrap()));
        assert!(is_reserved_ip("172.16.0.1".parse().unwrap()));
        assert!(is_reserved_ip("192.168.1.1".parse().unwrap()));
    }

    #[test]
    fn rejects_cgnat() {
        assert!(is_reserved_ip("100.64.0.1".parse().unwrap()));
    }

    #[test]
    fn rejects_benchmarking() {
        assert!(is_reserved_ip("198.18.0.1".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv6_loopback() {
        assert!(is_reserved_ip("::1".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv6_ula() {
        assert!(is_reserved_ip("fd00::1".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv6_site_local() {
        // fec0::/10 (RFC 3879, deprecated) is a non-global internal range.
        assert!(is_reserved_ip("fec0::1".parse().unwrap()));
        assert!(is_reserved_ip("feff::1".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv4_mapped_loopback() {
        assert!(is_reserved_ip("::ffff:127.0.0.1".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv4_mapped_cgnat() {
        // ::ffff:100.64.0.1 must inherit the embedded IPv4's CGNAT block.
        assert!(is_reserved_ip("::ffff:100.64.0.1".parse().unwrap()));
    }

    #[test]
    fn rejects_class_e_reserved() {
        assert!(is_reserved_ip("240.0.0.1".parse().unwrap()));
        assert!(is_reserved_ip("250.1.2.3".parse().unwrap()));
    }

    #[test]
    fn rejects_this_network_0_8() {
        // 0.0.0.0/8 "this network" (RFC 1122), not just 0.0.0.0.
        assert!(is_reserved_ip("0.1.2.3".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv6_nat64_of_metadata() {
        // 64:ff9b::169.254.169.254 — NAT64 well-known prefix wrapping the
        // cloud-metadata endpoint.
        assert!(is_reserved_ip("64:ff9b::a9fe:a9fe".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv6_6to4() {
        // 2002:a9fe:a9fe:: — 6to4 encoding of 169.254.169.254.
        assert!(is_reserved_ip("2002:a9fe:a9fe::".parse().unwrap()));
    }

    #[test]
    fn rejects_teredo_and_siit_translated_forms() {
        // Teredo 2001::/32 tunnels to an embedded (obfuscated) IPv4.
        assert!(is_reserved_ip(
            "2001:0:4136:e378:8000:63bf:3fff:fdd2".parse().unwrap()
        ));
        // SIIT ::ffff:0:a.b.c.d embedding the metadata endpoint / RFC 1918.
        assert!(is_reserved_ip("::ffff:0:a9fe:a9fe".parse().unwrap()));
        assert!(is_reserved_ip("::ffff:0:a00:1".parse().unwrap()));
        // SIIT embedding a public IPv4 stays allowed.
        assert!(!is_reserved_ip("::ffff:0:808:808".parse().unwrap()));
        // 2001:db8::/32 aside, the rest of 2001::/16 is ordinary global space.
        assert!(!is_reserved_ip("2001:4860:4860::8888".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv6_nat64_rfc8215_local_use_prefix() {
        // RFC 8215 local-use NAT64 prefix 64:ff9b:1::/48 — a NAT64 gateway on
        // this prefix translates the embedded IPv4 (incl. metadata), so the
        // whole /48 must be blocked alongside the well-known /96 (issue #52).
        assert!(is_reserved_ip("64:ff9b:1::a9fe:a9fe".parse().unwrap()));
        assert!(is_reserved_ip("64:ff9b:1:ffff::1".parse().unwrap()));
        // A different second-label value is NOT the local-use prefix and is a
        // normal global-unicast address — must remain allowed.
        assert!(!is_reserved_ip("64:ff9b:2::1".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv4_compatible_metadata() {
        // ::169.254.169.254 — deprecated IPv4-compatible form embedding the
        // metadata IP (to_ipv4_mapped() does NOT catch this).
        assert!(is_reserved_ip("::a9fe:a9fe".parse().unwrap()));
    }

    #[test]
    fn rejects_ipv6_documentation() {
        assert!(is_reserved_ip("2001:db8::1".parse().unwrap()));
    }

    #[test]
    fn allows_ipv4_compatible_public() {
        // ::8.8.8.8 embeds a public IPv4 — not reserved.
        assert!(!is_reserved_ip("::808:808".parse().unwrap()));
    }

    #[test]
    fn rejects_special_purpose_ranges() {
        for ip in [
            "192.88.99.1",      // 6to4 relay anycast
            "2001:2::1",        // benchmarking /48
            "2001:2:0:ffff::1", // ...its last /64
            "3fff::1",          // documentation /20
            "3fff:fff:ffff::1", // ...its top
            "100::1",           // discard-only /64
            "5f00::1",          // SRv6 SIDs
            "5f00:ffff::1",
        ] {
            assert!(is_reserved_ip(ip.parse().unwrap()), "{ip} must be reserved");
        }
        // The neighbours stay public.
        for ip in [
            "192.88.98.1",
            "2001:3::1",
            "3fff:1000::1",
            "100:0:0:1::1",
            "5f01::1",
        ] {
            assert!(!is_reserved_ip(ip.parse().unwrap()), "{ip} must be public");
        }
    }

    #[test]
    fn ipv4_first_keeps_each_family_in_order() {
        let mut addrs: Vec<IpAddr> = ["2001:db8::1", "192.0.2.1", "2001:db8::2", "192.0.2.2"]
            .iter()
            .map(|a| a.parse().unwrap())
            .collect();
        ipv4_first(&mut addrs, |ip| *ip);
        let text: Vec<String> = addrs.iter().map(IpAddr::to_string).collect();
        assert_eq!(
            text,
            ["192.0.2.1", "192.0.2.2", "2001:db8::1", "2001:db8::2"]
        );
    }

    /// Regression: reqwest honors `HTTPS_PROXY` by default, and a proxy
    /// resolves the target itself, voiding the `resolve_to_addrs` pin.
    ///
    /// Only `HTTPS_PROXY` is set, and only while the client is built (reqwest
    /// reads it then): no other hermetic test sends `https://` through
    /// reqwest, so a client built concurrently elsewhere is unaffected.
    #[tokio::test]
    async fn client_builder_ignores_proxy_environment() {
        use tokio::net::TcpListener;

        let target = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let target_port = target.local_addr().unwrap().port();
        let proxy = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let proxy_url = format!("http://{}", proxy.local_addr().unwrap());

        std::env::set_var("HTTPS_PROXY", &proxy_url);
        let client = client_builder(Duration::from_secs(2)).build();
        std::env::remove_var("HTTPS_PROXY");
        let client = client.unwrap();

        // The target accepts and hangs up, so the handshake fails fast; only
        // where the TCP connection went matters.
        let accepted = tokio::spawn(async move { target.accept().await.is_ok() });
        let _ = client
            .get(format!("https://127.0.0.1:{target_port}/"))
            .send()
            .await;
        let direct = tokio::time::timeout(Duration::from_secs(2), accepted).await;
        assert!(matches!(direct, Ok(Ok(true))), "must connect to the target");
        let via_proxy = tokio::time::timeout(Duration::from_millis(100), proxy.accept()).await;
        assert!(via_proxy.is_err(), "must not connect through the proxy");
    }

    /// TWNIC (.tw) serves RDAP over HTTP/2 only and answers HTTP/1.1 with
    /// `426 Upgrade Required`; the client must offer `h2` in its TLS ALPN
    /// extension (the `http2` reqwest feature).
    #[tokio::test]
    async fn client_offers_http2_over_alpn() {
        use tokio::io::AsyncReadExt;
        use tokio::net::TcpListener;

        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let port = listener.local_addr().unwrap().port();
        let hello = tokio::spawn(async move {
            let (mut sock, _) = listener.accept().await.unwrap();
            let mut buf = vec![0u8; 4096];
            let n = sock.read(&mut buf).await.unwrap();
            buf.truncate(n);
            buf
        });
        let client = client_builder(Duration::from_secs(2)).build().unwrap();
        // The listener never answers; only the ClientHello it captured matters.
        let _ = tokio::time::timeout(
            Duration::from_secs(2),
            client.get(format!("https://127.0.0.1:{port}/")).send(),
        )
        .await;
        let hello = hello.await.unwrap();
        // ALPN protocol names are length-prefixed in the plaintext ClientHello.
        let offers = |proto: &[u8]| {
            let mut needle = vec![u8::try_from(proto.len()).unwrap()];
            needle.extend_from_slice(proto);
            hello.windows(needle.len()).any(|w| w == needle.as_slice())
        };
        assert!(offers(b"h2"), "ClientHello must offer h2");
        assert!(offers(b"http/1.1"), "ClientHello must still offer http/1.1");
    }

    #[test]
    fn allows_public_v4() {
        assert!(!is_reserved_ip("8.8.8.8".parse().unwrap()));
        assert!(!is_reserved_ip("1.1.1.1".parse().unwrap()));
    }

    #[test]
    fn allows_public_v6() {
        assert!(!is_reserved_ip("2606:4700:4700::1111".parse().unwrap()));
    }

    #[tokio::test]
    async fn validate_rejects_ip_literal_loopback() {
        let err = validate_public_host("127.0.0.1", 80).await.unwrap_err();
        assert!(matches!(err, SeerError::InvalidInput(_)));
    }

    #[tokio::test]
    async fn validate_rejects_ip_literal_metadata() {
        let err = validate_public_host("169.254.169.254", 80)
            .await
            .unwrap_err();
        assert!(matches!(err, SeerError::InvalidInput(_)));
    }

    #[tokio::test]
    async fn validate_allows_public_ip_literal() {
        validate_public_host("8.8.8.8", 53).await.unwrap();
    }

    #[tokio::test]
    async fn validate_http_url_unbrackets_ipv6_literals() {
        // `Url::host_str()` keeps the brackets on an IPv6 literal; the
        // `Url::host()` extraction must unbracket it so the guard's IP-literal
        // short-circuit catches it (no DNS involved).
        let url = Url::parse("https://[::1]/").unwrap();
        let err = validate_http_url(&url).await.unwrap_err();
        assert!(
            matches!(err, SeerError::HttpError(ref s) if s.contains("reserved")),
            "got: {err:?}"
        );
    }

    #[tokio::test]
    async fn validate_http_url_returns_pinnable_addrs_for_public_literal() {
        let url = Url::parse("https://8.8.8.8/").unwrap();
        let addrs = validate_http_url(&url).await.unwrap();
        assert_eq!(addrs, vec!["8.8.8.8:443".parse().unwrap()]);
    }

    #[tokio::test]
    async fn reserved_resolution_error_does_not_leak_resolved_ip() {
        // A hostname that resolves to a reserved address must be refused
        // WITHOUT echoing the resolved internal IP to the caller — that turned
        // the SSRF guard into an internal-DNS oracle (issue #49). `localhost`
        // resolves to a loopback address via the OS resolver/hosts file.
        let err = validate_public_host("localhost", 80).await.unwrap_err();
        assert!(matches!(err, SeerError::InvalidInput(_)));
        let msg = err.to_string();
        assert!(
            !msg.contains("127.0.0.1"),
            "must not leak resolved IPv4: {msg}"
        );
        assert!(!msg.contains("::1"), "must not leak resolved IPv6: {msg}");
        assert!(
            !msg.contains("resolves to reserved address"),
            "must not echo the resolved-address detail: {msg}"
        );
    }

    /// Live-network sanity check for the fallback branch.
    ///
    /// The trailing dot forces an absolute lookup so `getaddrinfo` skips
    /// the host's search-domain list (otherwise a local resolver may
    /// append a search domain and rewrite an NXDOMAIN into a real hit —
    /// e.g. ISP wildcard captive-portal behavior). `.invalid` is reserved
    /// by RFC 2606 and must NXDOMAIN in upstream DNS, so hickory's Google
    /// DNS will also fail. When both fail, the guard returns a `DnsError`
    /// whose text mentions the fallback, which proves the fallback actually
    /// ran (not just the primary path).
    #[tokio::test]
    #[ignore = "requires network — hits Google DNS via hickory fallback"]
    async fn validate_rejects_unresolvable_via_fallback() {
        let err = validate_public_host("nonexistent.host.invalid.", 443)
            .await
            .unwrap_err();
        assert!(matches!(err, SeerError::DnsError(_)), "got: {err:?}");
        let msg = format!("{err}");
        assert!(msg.contains("DNS resolution failed"), "got: {msg}");
        assert!(msg.contains("fallback"), "got: {msg}");
        // The external projection must not carry the host or resolver text.
        assert_eq!(err.sanitized_message(), "DNS resolution failed");
    }

    #[tokio::test]
    async fn connect_tries_ipv4_first() {
        let v6: SocketAddr = "[2001:db8::1]:443".parse().unwrap();
        let v4: SocketAddr = "192.0.2.1:443".parse().unwrap();
        let tried = std::sync::Mutex::new(Vec::new());
        let got = connect_any(&[v6, v4], Duration::from_secs(5), |addr| {
            tried.lock().unwrap().push(addr);
            async move { Ok::<_, std::io::Error>(addr) }
        })
        .await
        .unwrap();
        assert_eq!(got, v4);
        assert_eq!(*tried.lock().unwrap(), [v4]);
    }

    /// Regression: one connect over the whole list under one deadline let a
    /// black-holed first address spend the entire budget.
    #[tokio::test]
    async fn a_hanging_address_leaves_budget_for_the_next() {
        let dead: SocketAddr = "192.0.2.1:443".parse().unwrap();
        let live: SocketAddr = "192.0.2.2:443".parse().unwrap();
        let got = connect_any(
            &[dead, live],
            Duration::from_millis(400),
            |addr| async move {
                if addr == dead {
                    std::future::pending::<()>().await;
                }
                Ok::<_, std::io::Error>(addr)
            },
        )
        .await
        .unwrap();
        assert_eq!(got, live);

        // A refusal moves on at once; all failing reports the last failure.
        let err = connect_any(&[dead, live], Duration::from_secs(5), |_| async {
            Err::<(), _>(std::io::Error::from(std::io::ErrorKind::ConnectionRefused))
        })
        .await
        .unwrap_err();
        assert!(
            matches!(err, ConnectError::Io(ref e) if e.kind() == std::io::ErrorKind::ConnectionRefused),
            "got {err:?}"
        );

        // Every address hanging is a timeout.
        let err = connect_any(&[dead], Duration::from_millis(50), |_| async {
            std::future::pending::<std::io::Result<()>>().await
        })
        .await
        .unwrap_err();
        assert!(matches!(err, ConnectError::TimedOut), "got {err:?}");
    }

    /// The shared TLS config (`HTTP_TLS`) must keep certificate verification
    /// on: a client from `client_builder` refuses a chain that no trusted
    /// root signs, as reqwest's own config did.
    #[tokio::test]
    async fn shared_tls_config_still_verifies_certificates() {
        use crate::tls::test_support::{serve_once, CA_DER, LEAF_DER};

        assert!(HTTP_TLS.is_ok(), "{:?}", HTTP_TLS.as_ref().err());
        let addr = serve_once(&[LEAF_DER, CA_DER], rustls::ALL_VERSIONS).await;
        let client = client_builder(Duration::from_secs(5))
            .resolve("chain.test", addr)
            .build()
            .unwrap();
        let err = client
            .get(format!("https://chain.test:{}/", addr.port()))
            .send()
            .await
            .expect_err("an untrusted chain must be refused");
        let mut chain = Vec::new();
        let mut source: Option<&dyn std::error::Error> = Some(&err);
        while let Some(e) = source {
            chain.push(e.to_string());
            source = e.source();
        }
        assert!(
            chain.iter().any(|m| m.contains("invalid peer certificate")),
            "{chain:?}"
        );
    }
}