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}