tea_coding_tools/web_fetch/
url_policy.rs1use std::fmt;
2use std::net::IpAddr;
3
4use thiserror::Error;
5use url::{Host, Url};
6
7use super::MAX_FETCH_URL_BYTES;
8
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
11pub enum FetchUrlPolicyError {
12 #[error("web fetch URL is invalid")]
14 InvalidUrl,
15 #[error("web fetch URL scheme is forbidden")]
17 ForbiddenScheme,
18 #[error("web fetch URL port is forbidden")]
20 ForbiddenPort,
21}
22
23#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
25pub struct FetchUrlPolicy {
26 allow_loopback_http: bool,
27}
28
29impl FetchUrlPolicy {
30 #[must_use]
32 pub const fn production() -> Self {
33 Self {
34 allow_loopback_http: false,
35 }
36 }
37
38 #[must_use]
44 pub const fn loopback_tests() -> Self {
45 Self {
46 allow_loopback_http: true,
47 }
48 }
49
50 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#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
123pub enum FetchUrlScheme {
124 Http,
126 Https,
128}
129
130#[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 #[must_use]
143 pub fn as_str(&self) -> &str {
144 &self.canonical
145 }
146
147 #[must_use]
149 pub fn host(&self) -> &str {
150 &self.host
151 }
152
153 #[must_use]
155 pub const fn port(&self) -> u16 {
156 self.port
157 }
158
159 #[must_use]
161 pub const fn scheme(&self) -> FetchUrlScheme {
162 self.scheme
163 }
164
165 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 #[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}