didbot_http/

address.rs

//! The one list of address blocks this workspace will not fetch from, and
//! the resolution that enforces it.
//!
//! Every outbound GET aimed by something this process did not write -- a
//! `client_id` a stranger posted, an OIDC issuer a token names, the service
//! endpoint inside a DID document -- is a request this server makes into
//! whatever network it is deployed in, aimed by somebody else. Resolving
//! the host first and refusing the whole set unless every address is public
//! is what keeps that from reaching this deployment's own network.

use std::net::{IpAddr, SocketAddr};
use std::sync::LazyLock;

use url::{Host, Url};

/// The address blocks an outbound fetch is refused for.
///
/// `169.254.169.254` is the one worth naming: on EC2 it answers with the
/// instance's own IAM credentials, and `didbot_dns::route53` reads it for
/// exactly that.
///
/// Written as prefixes rather than as `std::net`'s predicates because the
/// list is then the whole statement, readable against IANA's own
/// registries, and because the two predicates that would cover the IPv6
/// half (`is_unique_local`, `is_unicast_link_local`) are not stable.
pub const REFUSED_BLOCKS: &[&str] = &[
    // IPv4.
    "0.0.0.0/8",          // "this host on this network"
    "10.0.0.0/8",         // private
    "100.64.0.0/10",      // carrier-grade NAT
    "127.0.0.0/8",        // loopback
    "169.254.0.0/16",     // link-local, and the instance metadata service
    "172.16.0.0/12",      // private
    "192.0.0.0/24",       // IETF protocol assignments
    "192.0.2.0/24",       // documentation
    "192.168.0.0/16",     // private
    "198.18.0.0/15",      // benchmarking
    "198.51.100.0/24",    // documentation
    "203.0.113.0/24",     // documentation
    "224.0.0.0/4",        // multicast
    "240.0.0.0/4",        // reserved
    "255.255.255.255/32", // broadcast
    // IPv6.
    "::/128",        // unspecified
    "::1/128",       // loopback
    "64:ff9b::/96",  // NAT64
    "100::/64",      // discard-only
    "2001:db8::/32", // documentation
    "fc00::/7",      // unique local
    "fe80::/10",     // link-local
    "ff00::/8",      // multicast
];

/// [`REFUSED_BLOCKS`], parsed once.
static REFUSED: LazyLock<Vec<ipnet::IpNet>> = LazyLock::new(|| {
    REFUSED_BLOCKS
        .iter()
        .map(|block| block.parse().expect("a constant `ipnet` accepts"))
        .collect()
});

/// Whether an outbound fetch may reach `address`: true unless it falls in
/// [`REFUSED_BLOCKS`].
///
/// An IPv4-mapped IPv6 address is judged as the IPv4 address it carries, so
/// `::ffff:169.254.169.254` is not a way past the list.
pub fn is_public_address(address: IpAddr) -> bool {
    let address = address.to_canonical();
    !REFUSED.iter().any(|block| block.contains(&address))
}

/// Whether `url` names this machine and nowhere else.
///
/// `localhost` by name, or any address the standard library calls a
/// loopback address, which covers `127.0.0.0/8` and `::1` without this
/// having to enumerate either.
///
/// The host is taken from [`Url::host`] rather than [`Url::host_str`]. The
/// string form of an IPv6 host keeps the brackets the URL syntax requires,
/// `[::1]` parses as no address at all, and a check written against it
/// refuses a client listening on IPv6 loopback.
pub fn is_loopback(url: &Url) -> bool {
    match url.host() {
        Some(Host::Domain(name)) => name.eq_ignore_ascii_case("localhost"),
        Some(Host::Ipv4(address)) => address.is_loopback(),
        Some(Host::Ipv6(address)) => address.is_loopback(),
        None => false,
    }
}

/// Whether a caller accepts a host that resolves into [`REFUSED_BLOCKS`].
///
/// [`PrivateAddresses::Allowed`] is a development deployment's posture --
/// a loopback zone, a loopback operator, a test stack -- and never a
/// deployment on the public internet.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PrivateAddresses {
    /// Refuse the fetch. Every deployment on the public internet.
    Refused,
    /// Fetch anyway.
    Allowed,
}

/// Why an address check did not let a fetch proceed.
#[derive(Debug, thiserror::Error)]
pub enum AddressError {
    /// Not a URL, or a URL with no host in it to resolve.
    #[error("{url:?} names no host to resolve")]
    NoHost {
        /// The URL as it was given.
        url: String,
    },
    /// The host did not resolve, or resolved to no address at all.
    #[error("resolving {host}: {message}")]
    Unresolvable {
        /// The host that did not resolve.
        host: String,
        /// What the resolver said.
        message: String,
    },
    /// The host resolves into [`REFUSED_BLOCKS`] -- this deployment's own
    /// network rather than the public internet.
    #[error("{host} resolves to an address this server will not fetch from")]
    Refused {
        /// The host that resolved there.
        host: String,
    },
    /// The pinned client could not be built.
    #[error("building a client for {host}: {message}")]
    NoClient {
        /// The host the client was for.
        host: String,
        /// What `reqwest` said.
        message: String,
    },
}

/// Every address `url`'s host answers to, refused unless every one of them
/// is public.
///
/// Every address, not the first: a name that answers with one public
/// address and one loopback address is a name aimed at this deployment's
/// own network, whichever one `reqwest` goes on to pick.
///
/// A host that resolves to nothing at all is refused here rather than left
/// to fail in the fetch, so that both outcomes cost the same and a caller
/// can map them to one answer.
///
/// The addresses come back so a caller can pin its client to them -- see
/// [`pinned_client`], which is the only way a check made here still holds
/// at connect time.
pub async fn resolve_public(
    url: &Url,
    private: PrivateAddresses,
) -> Result<Vec<SocketAddr>, AddressError> {
    let port = url.port_or_known_default().unwrap_or(443);
    let (host, addresses): (String, Vec<SocketAddr>) = match url.host() {
        Some(Host::Ipv4(address)) => (
            address.to_string(),
            vec![SocketAddr::new(address.into(), port)],
        ),
        Some(Host::Ipv6(address)) => (
            address.to_string(),
            vec![SocketAddr::new(address.into(), port)],
        ),
        Some(Host::Domain(name)) => {
            let resolved = crate::lookup_host(name, port).await.map_err(|error| {
                AddressError::Unresolvable {
                    host: name.to_owned(),
                    message: error.to_string(),
                }
            })?;
            (name.to_owned(), resolved)
        }
        None => {
            return Err(AddressError::NoHost {
                url: url.to_string(),
            })
        }
    };
    if addresses.is_empty() {
        return Err(AddressError::Unresolvable {
            host,
            message: "the name resolves to nothing".to_owned(),
        });
    }
    if private == PrivateAddresses::Refused
        && !addresses
            .iter()
            .all(|address| is_public_address(address.ip()))
    {
        return Err(AddressError::Refused { host });
    }
    Ok(addresses)
}

/// [`resolve_public`] for a caller holding its URL as text, when nothing
/// past the refusal is wanted.
pub async fn refuse_private_host(url: &str, private: PrivateAddresses) -> Result<(), AddressError> {
    let parsed = Url::parse(url).map_err(|_| AddressError::NoHost {
        url: url.to_owned(),
    })?;
    resolve_public(&parsed, private).await.map(|_| ())
}

/// A [`client`](crate::client) for `url`: its host resolved once through
/// [`resolve_public`], pinned to what it resolved to so the connection
/// cannot land elsewhere, and following no redirect, which would land it
/// elsewhere all the same.
///
/// A URL whose host is already a literal address has nothing to pin --
/// there is no name, so nothing can answer differently the second time.
pub async fn pinned_client(
    url: &Url,
    private: PrivateAddresses,
) -> Result<reqwest::Client, AddressError> {
    let addresses = resolve_public(url, private).await?;
    let mut builder = crate::builder().redirect(reqwest::redirect::Policy::none());
    if let Some(Host::Domain(name)) = url.host() {
        builder = builder.resolve_to_addrs(name, &addresses);
    }
    builder.build().map_err(|error| AddressError::NoClient {
        host: url.host_str().unwrap_or_default().to_owned(),
        message: error.to_string(),
    })
}

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

    #[test]
    fn this_deployments_own_network_is_not_public() {
        for address in [
            "169.254.169.254",
            "127.0.0.1",
            "10.1.2.3",
            "172.16.0.1",
            "192.168.1.1",
            "100.64.0.1",
            "100.100.100.200",
            "0.0.0.0",
            "255.255.255.255",
            "224.0.0.1",
            "::1",
            "::",
            "fd00::1",
            "fe80::1",
            "ff02::1",
            // The IPv4-mapped spelling of the first entry: judged as the
            // IPv4 address it carries, not as an unlisted IPv6 one.
            "::ffff:169.254.169.254",
            "::ffff:10.0.0.1",
            // The blocks a predicate-based check leaves out.
            "192.0.0.1",
            "192.0.2.1",
            "198.18.0.1",
            "198.51.100.1",
            "203.0.113.1",
            "240.0.0.1",
            "64:ff9b::1",
            "100::1",
            "2001:db8::1",
        ] {
            assert!(
                !is_public_address(address.parse().expect("a literal address")),
                "{address} is fetchable"
            );
        }
        for address in [
            "8.8.8.8",
            "93.184.216.34",
            "2606:4700::1111",
            "2606:2800:220:1:248:1893:25c8:1946",
        ] {
            assert!(
                is_public_address(address.parse().expect("a literal address")),
                "{address} is not fetchable"
            );
        }
    }

    fn loopback(url: &str) -> bool {
        is_loopback(&Url::parse(url).expect("a URL"))
    }

    #[test]
    fn this_machine_by_name_or_by_number() {
        assert!(loopback("http://localhost:40831/cb"));
        assert!(loopback("http://LOCALHOST:40831/cb"));
        assert!(loopback("http://127.0.0.1:40831/cb"));
        // The whole 127/8 block, not just the one address everybody types.
        assert!(loopback("http://127.9.9.9/cb"));
        assert!(loopback("http://[::1]:40831/cb"));
    }

    #[test]
    fn anywhere_else_is_not_loopback() {
        assert!(!loopback("https://example.invalid/cb"));
        // A host that merely reads like this machine is somebody else's.
        assert!(!loopback("http://localhost.example.invalid/cb"));
        assert!(!loopback("http://10.0.0.1/cb"));
    }

    #[tokio::test]
    async fn a_literal_private_host_is_refused_without_resolving_anything() {
        let url = Url::parse("https://169.254.169.254/latest/meta-data/").expect("a URL");
        let error = resolve_public(&url, PrivateAddresses::Refused)
            .await
            .expect_err("the metadata service is refused");
        assert!(matches!(error, AddressError::Refused { .. }), "{error:?}");
    }

    #[tokio::test]
    async fn a_development_deployment_may_reach_loopback() {
        let url = Url::parse("http://127.0.0.1:8080/xrpc/x").expect("a URL");
        let addresses = resolve_public(&url, PrivateAddresses::Allowed)
            .await
            .expect("allowed");
        assert_eq!(addresses, vec![SocketAddr::from(([127, 0, 0, 1], 8080))]);
    }

    #[tokio::test]
    async fn text_that_is_not_a_url_has_no_host() {
        let error = refuse_private_host("not a url", PrivateAddresses::Refused)
            .await
            .expect_err("nothing to resolve");
        assert!(matches!(error, AddressError::NoHost { .. }), "{error:?}");
    }
}