Skip to main content

identity_kit/methods/web/
client.rs

1//! `ReqwestClient`: the hardened default `HttpClient`.
2
3use std::net::{IpAddr, SocketAddr};
4use std::sync::Arc;
5use std::time::Duration;
6
7use url::{Host, Url};
8
9use super::{HttpClient, HttpError, HttpResponse};
10
11/// An [`HttpClient`] over [`reqwest`] hardened for fetching DID documents from the public web.
12///
13/// [`ReqwestClient::new`] builds a client that:
14///
15/// - speaks HTTPS only, with the platform's root certificates and `rustls`;
16/// - follows no redirect, so a document is fetched from the URL its DID maps to and nowhere
17///   else: a 3xx response is returned with its `Location` in [`HttpResponse::location`], for a
18///   caller that follows redirects to fetch each target through this client again;
19/// - sends `Accept` when asked through [`HttpClient::get_accepting`], and
20///   `Accept-Encoding: gzip`, decoding a gzip-encoded body;
21/// - resolves host names itself and refuses loopback, private, link-local and other
22///   non-public addresses, so a DID cannot point the resolver at internal services;
23/// - uses no proxy, whatever `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` or the platform's
24///   settings say: a proxy resolves the host itself, so it would reach the addresses refused
25///   above;
26/// - stops reading a body over [`DEFAULT_MAX_BODY`](Self::DEFAULT_MAX_BODY) bytes, counted
27///   after decoding, so a small compressed body cannot expand past the limit;
28/// - times out after [`DEFAULT_TIMEOUT`](Self::DEFAULT_TIMEOUT).
29///
30/// [`ReqwestClient::from_client`] wraps a client the application configured itself, keeping
31/// only the HTTPS-only rule, the refusal of non-public IP literals and the body limit; the
32/// other protections are then the application's. That is also how to fetch through an egress
33/// proxy: configure it on that client, and have the proxy refuse non-public targets, since it
34/// resolves the host names.
35///
36/// # Local development and tests
37///
38/// With the feature `local-network`, [`ReqwestClient::builder`] can let a client reach
39/// a `did:web` served from the local machine or a private network, such as a test server on
40/// `127.0.0.1` or a development deployment in a docker-compose network. It is for
41/// development and tests only; enable the feature under `[dev-dependencies]`, or behind a
42/// feature of the application's own, so that a release build does not contain it.
43///
44/// - [`dangerous_allow_loopback`](ReqwestClientBuilder::dangerous_allow_loopback) allows
45///   `127.0.0.0/8` and `::1`, and
46///   [`dangerous_allow_private_network`](ReqwestClientBuilder::dangerous_allow_private_network)
47///   allows RFC 1918 and `fc00::/7`. Neither takes a `bool`: the choice is made in code.
48/// - The client resolves the host first. When every address is in an allowed range, it fetches
49///   the URL over plain `http`, on the port the URL names (443 when it names none), connecting
50///   to exactly the addresses it checked. Otherwise the rules above apply unchanged: a host with
51///   public and local addresses is held to them.
52/// - Link-local addresses (including cloud metadata endpoints such as `169.254.169.254`) and
53///   every other non-public range stay refused; redirects, the timeout and the body limit are
54///   unchanged.
55/// - Such a client [allows plain `http`](HttpClient::allows_plain_http), so the fetch helpers
56///   built on [`HttpClient`] (the DID configuration of `domain_linkage`, the presentations of
57///   `linked_vp`, the key sets of `JwksResolver`, the status list redirects) pass an `http` URL
58///   to it instead of refusing it themselves, and a local entity that publishes `http`
59///   origins or endpoints can be validated. The client still fetches such a URL only when
60///   every address of its host is in an allowed range, and refuses it otherwise.
61#[derive(Debug, Clone)]
62pub struct ReqwestClient {
63    client: reqwest::Client,
64    max_body: usize,
65    #[cfg(feature = "local-network")]
66    local: LocalNetwork,
67}
68
69impl ReqwestClient {
70    /// The largest body [`new`](Self::new) reads: 1 MiB, far above any DID document.
71    pub const DEFAULT_MAX_BODY: usize = 1 << 20;
72
73    /// The request timeout of [`new`](Self::new).
74    pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
75
76    /// A hardened client with the defaults above.
77    ///
78    /// # Errors
79    ///
80    /// [`HttpError`] when the TLS backend cannot be initialized.
81    pub fn new() -> Result<Self, HttpError> {
82        // Make `ring` the process default when nothing chose a provider yet; a provider another
83        // part of the application installed is kept.
84        let _ = rustls::crypto::ring::default_provider().install_default();
85        let client = reqwest::Client::builder()
86            .https_only(true)
87            .redirect(reqwest::redirect::Policy::none())
88            .dns_resolver(Arc::new(PublicAddresses))
89            .no_proxy()
90            .timeout(Self::DEFAULT_TIMEOUT)
91            .user_agent(concat!("identity-kit/", env!("CARGO_PKG_VERSION")))
92            .build()
93            .map_err(HttpError::new)?;
94        Ok(Self {
95            client,
96            max_body: Self::DEFAULT_MAX_BODY,
97            #[cfg(feature = "local-network")]
98            local: LocalNetwork::NONE,
99        })
100    }
101
102    /// A client over `client` as the application configured it, still HTTPS-only, refusing
103    /// non-public IP literals, and reading at most [`DEFAULT_MAX_BODY`](Self::DEFAULT_MAX_BODY)
104    /// bytes of body.
105    ///
106    /// Host names are resolved as `client` resolves them, so refusing the non-public
107    /// addresses they resolve to is the application's: with a DNS resolver like the one
108    /// [`new`](Self::new) installs, and, when `client` uses a proxy, by the proxy itself,
109    /// which resolves the host names it is asked to reach.
110    pub const fn from_client(client: reqwest::Client) -> Self {
111        Self {
112            client,
113            max_body: Self::DEFAULT_MAX_BODY,
114            #[cfg(feature = "local-network")]
115            local: LocalNetwork::NONE,
116        }
117    }
118
119    /// A builder for a client that may also reach the local network, for development and
120    /// tests; see [Local development and tests](Self#local-development-and-tests).
121    #[cfg(feature = "local-network")]
122    #[cfg_attr(docsrs, doc(cfg(feature = "local-network")))]
123    pub const fn builder() -> ReqwestClientBuilder {
124        ReqwestClientBuilder {
125            local: LocalNetwork::NONE,
126        }
127    }
128
129    /// This client reading at most `max_body` bytes of body.
130    #[must_use]
131    pub const fn with_max_body(mut self, max_body: usize) -> Self {
132        self.max_body = max_body;
133        self
134    }
135
136    /// The body limit.
137    pub const fn max_body(&self) -> usize {
138        self.max_body
139    }
140
141    /// The underlying client.
142    pub const fn client(&self) -> &reqwest::Client {
143        &self.client
144    }
145}
146
147#[async_trait::async_trait]
148impl HttpClient for ReqwestClient {
149    async fn get(&self, url: &Url) -> Result<HttpResponse, HttpError> {
150        self.fetch(url, None).await
151    }
152
153    async fn get_accepting(&self, url: &Url, media_type: &str) -> Result<HttpResponse, HttpError> {
154        self.fetch(url, Some(media_type)).await
155    }
156
157    /// `true` for a client from [`ReqwestClient::builder`] with a local range allowed (feature
158    /// `local-network`); `false` otherwise. [`get`](HttpClient::get) still fetches an `http`
159    /// URL only when every address of its host is in an allowed range.
160    fn allows_plain_http(&self, url: &Url) -> bool {
161        let _ = url;
162        #[cfg(feature = "local-network")]
163        return self.local != LocalNetwork::NONE;
164        #[cfg(not(feature = "local-network"))]
165        false
166    }
167}
168
169impl ReqwestClient {
170    /// Fetches `url`, sending `accept` as the `Accept` header when given.
171    async fn fetch(&self, url: &Url, accept: Option<&str>) -> Result<HttpResponse, HttpError> {
172        #[cfg(feature = "local-network")]
173        if let Some(response) = self.get_local(url, accept).await? {
174            return Ok(response);
175        }
176        if url.scheme() != "https" {
177            return Err(HttpError::msg(format!("`{url}` is not an HTTPS URL")));
178        }
179        // An IP literal never reaches the DNS resolver, so it is checked here.
180        let literal = match url.host() {
181            Some(Host::Ipv4(ip)) => Some(IpAddr::V4(ip)),
182            Some(Host::Ipv6(ip)) => Some(IpAddr::V6(ip)),
183            _ => None,
184        };
185        if literal.is_some_and(|ip| !is_public(ip)) {
186            return Err(HttpError::msg(format!("`{url}` is not a public address")));
187        }
188        let response = request(&self.client, url, accept)
189            .send()
190            .await
191            .map_err(HttpError::new)?;
192        read(response, self.max_body).await
193    }
194}
195
196/// A `GET` of `url` with `accept` as the `Accept` header, when given.
197fn request(client: &reqwest::Client, url: &Url, accept: Option<&str>) -> reqwest::RequestBuilder {
198    let request = client.get(url.as_str());
199    match accept {
200        Some(media_type) => request.header(reqwest::header::ACCEPT, media_type),
201        None => request,
202    }
203}
204
205/// The status, the `Location` of a redirect and at most `max_body` bytes of decoded body of
206/// `response`.
207async fn read(mut response: reqwest::Response, max_body: usize) -> Result<HttpResponse, HttpError> {
208    let status = response.status().as_u16();
209    let location = if response.status().is_redirection() {
210        response
211            .headers()
212            .get(reqwest::header::LOCATION)
213            .and_then(|location| location.to_str().ok())
214            .map(str::to_owned)
215    } else {
216        None
217    };
218    if response
219        .content_length()
220        .is_some_and(|len| len > max_body as u64)
221    {
222        return Err(HttpError::msg(format!(
223            "response body exceeds {max_body} bytes"
224        )));
225    }
226    let mut body = Vec::new();
227    while let Some(chunk) = response.chunk().await.map_err(HttpError::new)? {
228        if body.len() + chunk.len() > max_body {
229            return Err(HttpError::msg(format!(
230                "response body exceeds {max_body} bytes"
231            )));
232        }
233        body.extend_from_slice(&chunk);
234    }
235    let response = HttpResponse::new(status, body);
236    Ok(match location {
237        Some(location) => response.with_location(location),
238        None => response,
239    })
240}
241
242#[cfg(feature = "local-network")]
243pub use local::{LocalNetwork, ReqwestClientBuilder};
244
245#[cfg(feature = "local-network")]
246mod local {
247    use std::net::{IpAddr, SocketAddr};
248
249    use url::{Host, Url};
250
251    use super::{HttpError, HttpResponse, ReqwestClient, is_public, read, request};
252
253    /// The local address ranges a [`ReqwestClient`] may reach besides the public internet.
254    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
255    #[non_exhaustive]
256    pub struct LocalNetwork {
257        /// `127.0.0.0/8` and `::1`.
258        pub loopback: bool,
259        /// RFC 1918 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) and `fc00::/7`.
260        pub private: bool,
261    }
262
263    impl LocalNetwork {
264        /// No local range: the public rules only.
265        pub const NONE: Self = Self {
266            loopback: false,
267            private: false,
268        };
269
270        /// Whether `ip` is in one of the allowed local ranges. Link-local and every other
271        /// non-public range never are.
272        pub fn allows(&self, ip: IpAddr) -> bool {
273            let ip = match ip {
274                IpAddr::V6(v6) => v6.to_ipv4_mapped().map_or(ip, IpAddr::V4),
275                IpAddr::V4(_) => ip,
276            };
277            let loopback = ip.is_loopback();
278            let private = match ip {
279                IpAddr::V4(v4) => v4.is_private(),
280                IpAddr::V6(v6) => v6.is_unique_local(),
281            };
282            (self.loopback && loopback) || (self.private && private)
283        }
284
285        /// Whether every one of `addresses`, of which there is at least one, is in an allowed
286        /// local range: the host is fetched over plain `http`. Otherwise the public rules
287        /// apply.
288        pub fn all_local(&self, addresses: &[IpAddr]) -> bool {
289            !addresses.is_empty() && addresses.iter().all(|ip| self.allows(*ip))
290        }
291    }
292
293    /// Builds a [`ReqwestClient`] that may also reach the local network, for development and
294    /// tests; see [Local development and tests](ReqwestClient#local-development-and-tests).
295    ///
296    /// # Examples
297    ///
298    /// ```
299    /// use identity_kit::methods::web::ReqwestClient;
300    ///
301    /// let client = ReqwestClient::builder().dangerous_allow_loopback().build()?;
302    /// assert!(client.local_network().loopback && !client.local_network().private);
303    /// # Ok::<(), identity_kit::methods::web::HttpError>(())
304    /// ```
305    #[derive(Debug, Clone)]
306    #[must_use]
307    pub struct ReqwestClientBuilder {
308        pub(super) local: LocalNetwork,
309    }
310
311    impl ReqwestClientBuilder {
312        /// Lets the client reach `127.0.0.0/8` and `::1` over plain `http`. For development
313        /// and tests only.
314        pub const fn dangerous_allow_loopback(mut self) -> Self {
315            self.local.loopback = true;
316            self
317        }
318
319        /// Lets the client reach RFC 1918 addresses and `fc00::/7` over plain `http`. For
320        /// development and tests only.
321        pub const fn dangerous_allow_private_network(mut self) -> Self {
322            self.local.private = true;
323            self
324        }
325
326        /// The client: [`ReqwestClient::new`] plus the local ranges allowed here.
327        ///
328        /// # Errors
329        ///
330        /// [`HttpError`] when the TLS backend cannot be initialized.
331        pub fn build(self) -> Result<ReqwestClient, HttpError> {
332            let mut client = ReqwestClient::new()?;
333            client.local = self.local;
334            Ok(client)
335        }
336    }
337
338    impl ReqwestClient {
339        /// The local ranges this client may reach; [`LocalNetwork::NONE`] unless built with
340        /// [`ReqwestClient::builder`].
341        pub const fn local_network(&self) -> LocalNetwork {
342            self.local
343        }
344
345        /// Fetches `url` over plain `http` when every address of its host is in an allowed
346        /// local range; `None` when the public rules apply.
347        pub(super) async fn get_local(
348            &self,
349            url: &Url,
350            accept: Option<&str>,
351        ) -> Result<Option<HttpResponse>, HttpError> {
352            if self.local == LocalNetwork::NONE || !matches!(url.scheme(), "https" | "http") {
353                return Ok(None);
354            }
355            // An `http` or `https` URL always has a host and a port.
356            let port = url.port_or_known_default().unwrap_or(443);
357            let host = url.host().expect("an `http` or `https` URL has a host");
358            let (name, addresses): (Option<&str>, Vec<IpAddr>) = match host {
359                Host::Ipv4(ip) => (None, vec![IpAddr::V4(ip)]),
360                Host::Ipv6(ip) => (None, vec![IpAddr::V6(ip)]),
361                Host::Domain(name) => {
362                    let addresses = tokio::net::lookup_host((name, port))
363                        .await
364                        .map_err(HttpError::new)?
365                        .map(|address| address.ip())
366                        .collect();
367                    (Some(name), addresses)
368                }
369            };
370            if !self.local.all_local(&addresses) {
371                return Ok(None);
372            }
373            debug_assert!(addresses.iter().all(|ip| !is_public(*ip)));
374            let target = plain_http(url, port);
375            let mut builder = reqwest::Client::builder()
376                .no_proxy()
377                .redirect(reqwest::redirect::Policy::none())
378                .timeout(ReqwestClient::DEFAULT_TIMEOUT)
379                .user_agent(concat!("identity-kit/", env!("CARGO_PKG_VERSION")));
380            if let Some(name) = name {
381                let pinned: Vec<SocketAddr> = addresses
382                    .iter()
383                    .map(|ip| SocketAddr::new(*ip, port))
384                    .collect();
385                builder = builder.resolve_to_addrs(name, &pinned);
386            }
387            let client = builder.build().map_err(HttpError::new)?;
388            let response = request(&client, &target, accept)
389                .send()
390                .await
391                .map_err(HttpError::new)?;
392            read(response, self.max_body).await.map(Some)
393        }
394    }
395
396    /// `url` with the `http` scheme on `port`, the port the URL names or the `https` default it
397    /// implies.
398    pub(super) fn plain_http(url: &Url, port: u16) -> Url {
399        let mut target = url.clone();
400        // Scheme first: `set_port` drops a port equal to the current scheme's default, so 443
401        // set while the URL is still `https` would leave `http` on port 80.
402        target
403            .set_scheme("http")
404            .expect("an `http` or `https` URL can be `http`");
405        target
406            .set_port(Some(port))
407            .expect("a URL with a host takes a port");
408        target
409    }
410}
411
412/// A DNS resolver that keeps only public addresses.
413struct PublicAddresses;
414
415impl reqwest::dns::Resolve for PublicAddresses {
416    fn resolve(&self, name: reqwest::dns::Name) -> reqwest::dns::Resolving {
417        let host = name.as_str().to_owned();
418        Box::pin(async move {
419            let addresses: Vec<SocketAddr> = tokio::net::lookup_host((host.as_str(), 0))
420                .await?
421                .filter(|address| is_public(address.ip()))
422                .collect();
423            if addresses.is_empty() {
424                return Err(format!("`{host}` resolves to no public address").into());
425            }
426            Ok(Box::new(addresses.into_iter()) as reqwest::dns::Addrs)
427        })
428    }
429}
430
431/// Whether `ip` is a globally routable unicast address: not loopback, private, link-local,
432/// unspecified, multicast, broadcast, documentation or otherwise reserved.
433pub(crate) fn is_public(ip: IpAddr) -> bool {
434    match ip {
435        IpAddr::V4(v4) => {
436            let [a, b, ..] = v4.octets();
437            !(v4.is_unspecified()
438                || v4.is_loopback()
439                || v4.is_private()
440                || v4.is_link_local()
441                || v4.is_broadcast()
442                || v4.is_documentation()
443                || v4.is_multicast()
444                || a == 0
445                || (a == 100 && (64..=127).contains(&b)) // shared address space, RFC 6598
446                || (a == 192 && b == 0 && v4.octets()[2] == 0) // IETF protocol assignments
447                || (a == 198 && (18..=19).contains(&b)) // benchmarking, RFC 2544
448                || a >= 240) // reserved and broadcast
449        }
450        IpAddr::V6(v6) => {
451            if let Some(v4) = v6.to_ipv4_mapped() {
452                return is_public(IpAddr::V4(v4));
453            }
454            let segments = v6.segments();
455            !(v6.is_unspecified()
456                || v6.is_loopback()
457                || v6.is_multicast()
458                || v6.is_unique_local()
459                || v6.is_unicast_link_local()
460                || segments[0] == 0x2001 && segments[1] == 0x0db8 // documentation
461                || segments[0] == 0x0064 && segments[1] == 0xff9b) // NAT64 well-known prefix
462        }
463    }
464}
465
466#[cfg(test)]
467mod tests {
468    use super::*;
469
470    #[cfg(feature = "local-network")]
471    #[test]
472    fn plain_http_keeps_the_port() {
473        for (url, port, expected) in [
474            // No port: the `https` default, 443, which `http` must name explicitly.
475            (
476                "https://localhost/.well-known/did.json",
477                443,
478                "http://localhost:443/.well-known/did.json",
479            ),
480            (
481                "https://issuer/user/alice/did.json",
482                443,
483                "http://issuer:443/user/alice/did.json",
484            ),
485            (
486                "https://127.0.0.1/did.json",
487                443,
488                "http://127.0.0.1:443/did.json",
489            ),
490            ("https://[::1]/did.json", 443, "http://[::1]:443/did.json"),
491            // An explicit port is kept, including 80.
492            (
493                "https://localhost:8443/did.json",
494                8443,
495                "http://localhost:8443/did.json",
496            ),
497            (
498                "https://localhost:80/did.json",
499                80,
500                "http://localhost/did.json",
501            ),
502            // A plain `http` URL is unchanged.
503            (
504                "http://localhost:8080/did.json",
505                8080,
506                "http://localhost:8080/did.json",
507            ),
508            ("http://localhost/did.json", 80, "http://localhost/did.json"),
509        ] {
510            let url = url::Url::parse(url).unwrap();
511            let rewritten = local::plain_http(&url, port);
512            assert_eq!(rewritten.as_str(), expected, "{url}");
513            assert_eq!(rewritten.port_or_known_default(), Some(port), "{url}");
514        }
515    }
516
517    #[test]
518    fn public_addresses() {
519        for public in [
520            "93.184.216.34",
521            "2606:2800:220:1:248:1893:25c8:1946",
522            "1.1.1.1",
523            // Near misses: each matches only one half of a reserved range's condition.
524            "8.64.0.1",
525            "100.128.0.1",
526            "8.0.0.8",
527            "8.8.0.8",
528            "192.0.1.1",
529            "8.18.0.1",
530            "2001:4860:4860::8888",
531            "2600:db8::1",
532            "64:1::1",
533            "2600:ff9b::1",
534        ] {
535            assert!(is_public(public.parse().unwrap()), "{public}");
536        }
537        for private in [
538            "127.0.0.1",
539            "127.1.2.3",
540            "10.0.0.1",
541            "172.16.0.1",
542            "172.31.255.255",
543            "192.168.1.1",
544            "169.254.169.254",
545            "0.0.0.0",
546            "100.64.0.1",
547            "192.0.0.8",
548            "198.18.0.1",
549            "198.51.100.1",
550            "224.0.0.1",
551            "255.255.255.255",
552            "::1",
553            "::",
554            "fc00::1",
555            "fd12::1",
556            "fe80::1",
557            "ff02::1",
558            "2001:db8::1",
559            "64:ff9b::7f00:1",
560            "::ffff:127.0.0.1",
561            "::ffff:10.0.0.1",
562        ] {
563            assert!(!is_public(private.parse().unwrap()), "{private}");
564        }
565    }
566}