Skip to main content

tea_coding_tools/web_fetch/
url_policy.rs

1use std::fmt;
2use std::net::IpAddr;
3
4use thiserror::Error;
5use url::{Host, Url};
6
7use super::MAX_FETCH_URL_BYTES;
8
9/// URL-policy failure detected before DNS or network I/O.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
11pub enum FetchUrlPolicyError {
12    /// URL syntax, length, host, or credentials are invalid.
13    #[error("web fetch URL is invalid")]
14    InvalidUrl,
15    /// URL scheme is not allowed by the selected policy.
16    #[error("web fetch URL scheme is forbidden")]
17    ForbiddenScheme,
18    /// Explicit port is not allowed by the selected policy.
19    #[error("web fetch URL port is forbidden")]
20    ForbiddenPort,
21}
22
23/// Immutable URL validation policy used before DNS resolution.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
25pub struct FetchUrlPolicy {
26    allow_loopback_http: bool,
27}
28
29impl FetchUrlPolicy {
30    /// Creates the production policy: HTTPS and the default port only.
31    #[must_use]
32    pub const fn production() -> Self {
33        Self {
34            allow_loopback_http: false,
35        }
36    }
37
38    /// Creates an explicit local-fixture policy.
39    ///
40    /// This policy permits `http` only for literal loopback addresses or
41    /// `localhost`; address validation must still permit and verify loopback.
42    /// Product configuration must use [`Self::production`].
43    #[must_use]
44    pub const fn loopback_tests() -> Self {
45        Self {
46            allow_loopback_http: true,
47        }
48    }
49
50    /// Normalizes and validates one URL without resolving its host.
51    ///
52    /// # Errors
53    ///
54    /// Rejects invalid IDNA hosts, credentials, unsupported schemes, unsafe
55    /// ports, controls, whitespace, and oversized values. Fragments are
56    /// deliberately removed because they are not part of HTTP requests or
57    /// cache keys.
58    pub fn validate(&self, value: &str) -> Result<ValidatedFetchUrl, FetchUrlPolicyError> {
59        if value.is_empty()
60            || value.len() > MAX_FETCH_URL_BYTES
61            || value
62                .chars()
63                .any(|character| character.is_control() || character.is_whitespace())
64        {
65            return Err(FetchUrlPolicyError::InvalidUrl);
66        }
67        let mut parsed = Url::parse(value).map_err(|_| FetchUrlPolicyError::InvalidUrl)?;
68        if !parsed.username().is_empty() || parsed.password().is_some() || parsed.host().is_none() {
69            return Err(FetchUrlPolicyError::InvalidUrl);
70        }
71        parsed.set_fragment(None);
72        if parsed.path().is_empty() {
73            parsed.set_path("/");
74        }
75
76        let host = canonical_host(&mut parsed)?;
77        let loopback_host = is_loopback_host(&host);
78        match parsed.scheme() {
79            "https" => {
80                if parsed.port().is_some_and(|port| port != 443) {
81                    return Err(FetchUrlPolicyError::ForbiddenPort);
82                }
83                if parsed.port() == Some(443) {
84                    parsed
85                        .set_port(None)
86                        .map_err(|()| FetchUrlPolicyError::InvalidUrl)?;
87                }
88            }
89            "http" if self.allow_loopback_http && loopback_host => {
90                if parsed.port().is_some_and(is_dangerous_port) {
91                    return Err(FetchUrlPolicyError::ForbiddenPort);
92                }
93            }
94            _ => return Err(FetchUrlPolicyError::ForbiddenScheme),
95        }
96
97        let port = parsed
98            .port_or_known_default()
99            .ok_or(FetchUrlPolicyError::InvalidUrl)?;
100        let scheme = if parsed.scheme() == "https" {
101            FetchUrlScheme::Https
102        } else {
103            FetchUrlScheme::Http
104        };
105        Ok(ValidatedFetchUrl {
106            canonical: parsed.to_string(),
107            parsed,
108            host,
109            port,
110            scheme,
111        })
112    }
113}
114
115impl Default for FetchUrlPolicy {
116    fn default() -> Self {
117        Self::production()
118    }
119}
120
121/// Validated HTTP scheme.
122#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
123pub enum FetchUrlScheme {
124    /// Plain HTTP, available only to explicit loopback fixture policies.
125    Http,
126    /// Production HTTPS.
127    Https,
128}
129
130/// Canonical URL safe to pass into DNS and per-hop transport validation.
131#[derive(Clone, PartialEq, Eq, Hash)]
132pub struct ValidatedFetchUrl {
133    canonical: String,
134    parsed: Url,
135    host: String,
136    port: u16,
137    scheme: FetchUrlScheme,
138}
139
140impl ValidatedFetchUrl {
141    /// Returns the canonical request and cache-key URL.
142    #[must_use]
143    pub fn as_str(&self) -> &str {
144        &self.canonical
145    }
146
147    /// Returns the normalized ASCII host used for DNS and TLS SNI.
148    #[must_use]
149    pub fn host(&self) -> &str {
150        &self.host
151    }
152
153    /// Returns the effective destination port.
154    #[must_use]
155    pub const fn port(&self) -> u16 {
156        self.port
157    }
158
159    /// Returns the validated scheme.
160    #[must_use]
161    pub const fn scheme(&self) -> FetchUrlScheme {
162        self.scheme
163    }
164
165    /// Resolves one redirect location against this URL.
166    ///
167    /// # Errors
168    ///
169    /// Returns an error when `Location` is malformed or violates the selected
170    /// URL policy.
171    pub fn resolve_redirect(
172        &self,
173        location: &str,
174        policy: &FetchUrlPolicy,
175    ) -> Result<Self, FetchUrlPolicyError> {
176        if location.is_empty()
177            || location.len() > MAX_FETCH_URL_BYTES
178            || location.chars().any(char::is_control)
179        {
180            return Err(FetchUrlPolicyError::InvalidUrl);
181        }
182        let resolved = self
183            .parsed
184            .join(location)
185            .map_err(|_| FetchUrlPolicyError::InvalidUrl)?;
186        policy.validate(resolved.as_str())
187    }
188
189    /// Returns whether the URL uses HTTPS.
190    #[must_use]
191    pub const fn is_https(&self) -> bool {
192        matches!(self.scheme, FetchUrlScheme::Https)
193    }
194}
195
196impl fmt::Debug for ValidatedFetchUrl {
197    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
198        formatter
199            .debug_struct("ValidatedFetchUrl")
200            .field("scheme", &self.scheme)
201            .field("host", &self.host)
202            .field("port", &self.port)
203            .field("path_bytes", &self.parsed.path().len())
204            .field("has_query", &self.parsed.query().is_some())
205            .finish_non_exhaustive()
206    }
207}
208
209fn canonical_host(parsed: &mut Url) -> Result<String, FetchUrlPolicyError> {
210    let host = match parsed.host().ok_or(FetchUrlPolicyError::InvalidUrl)? {
211        Host::Domain(domain) => {
212            let domain = domain.strip_suffix('.').unwrap_or(domain).to_owned();
213            validate_domain(&domain)?;
214            parsed
215                .set_host(Some(&domain))
216                .map_err(|_| FetchUrlPolicyError::InvalidUrl)?;
217            domain.to_ascii_lowercase()
218        }
219        Host::Ipv4(address) => address.to_string(),
220        Host::Ipv6(address) => address.to_string(),
221    };
222    Ok(host)
223}
224
225fn validate_domain(domain: &str) -> Result<(), FetchUrlPolicyError> {
226    if domain.is_empty()
227        || domain.len() > 253
228        || !domain.is_ascii()
229        || domain.split('.').any(|label| {
230            label.is_empty()
231                || label.len() > 63
232                || label.starts_with('-')
233                || label.ends_with('-')
234                || !label
235                    .bytes()
236                    .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
237        })
238    {
239        Err(FetchUrlPolicyError::InvalidUrl)
240    } else {
241        Ok(())
242    }
243}
244
245fn is_loopback_host(host: &str) -> bool {
246    host.eq_ignore_ascii_case("localhost")
247        || host
248            .parse::<IpAddr>()
249            .is_ok_and(|address| address.is_loopback())
250}
251
252fn is_dangerous_port(port: u16) -> bool {
253    matches!(
254        port,
255        1 | 7
256            | 9
257            | 11
258            | 13
259            | 15
260            | 17
261            | 19..=23
262            | 25
263            | 37
264            | 42..=43
265            | 53
266            | 69
267            | 77
268            | 79
269            | 87
270            | 95
271            | 101..=104
272            | 109..=111
273            | 113
274            | 115
275            | 117
276            | 119
277            | 123
278            | 135
279            | 137..=139
280            | 143
281            | 161
282            | 179
283            | 389
284            | 427
285            | 465
286            | 512..=515
287            | 526
288            | 530..=532
289            | 540
290            | 548
291            | 554
292            | 556
293            | 563
294            | 587
295            | 601
296            | 636
297            | 989..=990
298            | 993
299            | 995
300            | 1719..=1720
301            | 1723
302            | 2049
303            | 3659
304            | 4045
305            | 5060..=5061
306            | 6000
307            | 6566
308            | 6665..=6669
309            | 6697
310            | 10080
311    )
312}