uv_redacted/
lib.rs

1use ref_cast::RefCast;
2use serde::{Deserialize, Serialize};
3use std::borrow::Cow;
4use std::fmt::{Debug, Display};
5use std::ops::{Deref, DerefMut};
6use std::str::FromStr;
7use thiserror::Error;
8use url::Url;
9
10const SENSITIVE_QUERY_PARAMETERS: &[&str] = &[
11    "X-Amz-Credential",
12    "X-Amz-Security-Token",
13    "X-Amz-Signature",
14];
15
16#[derive(Error, Debug, Clone, PartialEq, Eq)]
17pub enum DisplaySafeUrlError {
18    /// Failed to parse a URL.
19    #[error(transparent)]
20    Url(#[from] url::ParseError),
21
22    /// We parsed a URL, but couldn't disambiguate its authority
23    /// component.
24    #[error("ambiguous user/pass authority in URL (not percent-encoded?): {0}")]
25    AmbiguousAuthority(String),
26}
27
28/// A [`Url`] wrapper that redacts credentials and sensitive query parameters when displaying the URL.
29///
30/// `DisplaySafeUrl` wraps the standard [`url::Url`] type, providing functionality to mask
31/// secrets by default when the URL is displayed or logged. This helps prevent accidental
32/// exposure of sensitive information in logs and debug output.
33///
34/// # Examples
35///
36/// ```
37/// use uv_redacted::DisplaySafeUrl;
38/// use std::str::FromStr;
39///
40/// // Create a `DisplaySafeUrl` from a `&str`
41/// let mut url = DisplaySafeUrl::parse("https://user:password@example.com").unwrap();
42///
43/// // Display will mask secrets
44/// assert_eq!(url.to_string(), "https://user:****@example.com/");
45///
46/// // You can still access the username and password
47/// assert_eq!(url.username(), "user");
48/// assert_eq!(url.password(), Some("password"));
49///
50/// // And you can still update the username and password
51/// let _ = url.set_username("new_user");
52/// let _ = url.set_password(Some("new_password"));
53/// assert_eq!(url.username(), "new_user");
54/// assert_eq!(url.password(), Some("new_password"));
55///
56/// // It is also possible to remove the credentials entirely
57/// url.remove_credentials();
58/// assert_eq!(url.username(), "");
59/// assert_eq!(url.password(), None);
60/// ```
61#[derive(Clone, Eq, PartialEq, PartialOrd, Ord, Hash, Serialize, Deserialize, RefCast)]
62#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
63#[cfg_attr(feature = "schemars", schemars(transparent))]
64#[repr(transparent)]
65pub struct DisplaySafeUrl(Url);
66
67/// Check if a path or fragment contains a credential-like pattern (`:` followed by `@`).
68///
69/// This skips colons that are followed by `//`, as those indicate URL schemes (e.g., `https://`)
70/// rather than credentials. This is important for handling nested URLs like proxy URLs:
71/// `git+https://proxy.com/https://github.com/user/repo.git@branch`.
72fn has_credential_like_pattern(s: &str) -> bool {
73    let mut remaining = s;
74    while let Some(colon_pos) = remaining.find(':') {
75        let after_colon = &remaining[colon_pos + 1..];
76        // If the colon is followed by "//", consider it a URL scheme.
77        if after_colon.starts_with("//") {
78            remaining = after_colon;
79            continue;
80        }
81        // Check if there's an @ after this colon.
82        if after_colon.contains('@') {
83            return true;
84        }
85        remaining = after_colon;
86    }
87    false
88}
89
90impl DisplaySafeUrl {
91    #[inline]
92    pub fn parse(input: &str) -> Result<Self, DisplaySafeUrlError> {
93        let url = Url::parse(input)?;
94
95        Self::reject_ambiguous_credentials(input, &url)?;
96
97        Ok(Self(url))
98    }
99
100    /// Reject some ambiguous cases, e.g., `https://user/name:password@domain/a/b/c`
101    ///
102    /// In this case the user *probably* meant to have a username of "user/name", but both RFC
103    /// 3986 and WHATWG URL expect the userinfo (RFC 3986) or authority (WHATWG) to not contain a
104    /// non-percent-encoded slash or other special character.
105    ///
106    /// This ends up being moderately annoying to detect, since the above gets parsed into a
107    /// "valid" WHATWG URL where the host is `used` and the pathname is
108    /// `/name:password@domain/a/b/c` rather than causing a parse error.
109    ///
110    /// To detect it, we use a heuristic: if the password component is missing but the path or
111    /// fragment contain a `:` followed by a `@`, then we assume the URL is ambiguous.
112    fn reject_ambiguous_credentials(input: &str, url: &Url) -> Result<(), DisplaySafeUrlError> {
113        // `git://`, `http://`, and `https://` URLs may carry credentials, while `file://` URLs
114        // on Windows may contain both sigils, but it's always safe, e.g.
115        // `file://C:/Users/ferris/project@home/workspace`.
116        if url.scheme() == "file" {
117            return Ok(());
118        }
119
120        if url.password().is_some() {
121            return Ok(());
122        }
123
124        // Check for the suspicious pattern.
125        if !has_credential_like_pattern(url.path())
126            && !url
127                .fragment()
128                .map(has_credential_like_pattern)
129                .unwrap_or(false)
130        {
131            return Ok(());
132        }
133
134        // If the previous check passed, we should always expect to find these in the given URL.
135        let (Some(col_pos), Some(at_pos)) = (input.find(':'), input.rfind('@')) else {
136            if cfg!(debug_assertions) {
137                unreachable!(
138                    "`:` or `@` sign missing in URL that was confirmed to contain them: {input}"
139                );
140            }
141            return Ok(());
142        };
143
144        // Our ambiguous URL probably has credentials in it, so we don't want to blast it out in
145        // the error message. We somewhat aggressively replace everything between the scheme's
146        // ':' and the lastmost `@` with `***`.
147        let redacted_path = format!("{}***{}", &input[0..=col_pos], &input[at_pos..]);
148        Err(DisplaySafeUrlError::AmbiguousAuthority(redacted_path))
149    }
150
151    /// Create a new [`DisplaySafeUrl`] from a [`Url`].
152    ///
153    /// Unlike [`Self::parse`], this doesn't perform any ambiguity checks.
154    /// That means that it's primarily useful for contexts where a human can't easily accidentally
155    /// introduce an ambiguous URL, such as URLs being read from a request.
156    pub fn from_url(url: Url) -> Self {
157        Self(url)
158    }
159
160    /// Cast a `&Url` to a `&DisplaySafeUrl` using ref-cast.
161    #[inline]
162    pub fn ref_cast(url: &Url) -> &Self {
163        RefCast::ref_cast(url)
164    }
165
166    /// Parse a string as an URL, with this URL as the base URL.
167    #[inline]
168    pub fn join(&self, input: &str) -> Result<Self, DisplaySafeUrlError> {
169        Ok(Self(self.0.join(input)?))
170    }
171
172    /// Serialize with Serde using the internal representation of the `Url` struct.
173    #[inline]
174    pub fn serialize_internal<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
175    where
176        S: serde::Serializer,
177    {
178        self.0.serialize_internal(serializer)
179    }
180
181    /// Serialize with Serde using the internal representation of the `Url` struct.
182    #[inline]
183    pub fn deserialize_internal<'de, D>(deserializer: D) -> Result<Self, D::Error>
184    where
185        D: serde::Deserializer<'de>,
186    {
187        Ok(Self(Url::deserialize_internal(deserializer)?))
188    }
189
190    #[expect(clippy::result_unit_err)]
191    pub fn from_file_path<P: AsRef<std::path::Path>>(path: P) -> Result<Self, ()> {
192        Ok(Self(Url::from_file_path(path)?))
193    }
194
195    /// Remove the credentials from a URL, allowing the generic `git` username (without a password)
196    /// in SSH URLs, as in, `ssh://git@github.com/...`.
197    #[inline]
198    pub fn remove_credentials(&mut self) {
199        // For URLs that use the `git` convention (i.e., `ssh://git@github.com/...`), avoid dropping the
200        // username.
201        if is_ssh_git_username(&self.0) {
202            return;
203        }
204        let _ = self.0.set_username("");
205        let _ = self.0.set_password(None);
206    }
207
208    /// Returns the URL with any credentials removed.
209    pub fn without_credentials(&self) -> Cow<'_, Url> {
210        if self.0.password().is_none() && self.0.username() == "" {
211            return Cow::Borrowed(&self.0);
212        }
213
214        // For URLs that use the `git` convention (i.e., `ssh://git@github.com/...`), avoid dropping the
215        // username.
216        if is_ssh_git_username(&self.0) {
217            return Cow::Borrowed(&self.0);
218        }
219
220        let mut url = self.0.clone();
221        let _ = url.set_username("");
222        let _ = url.set_password(None);
223        Cow::Owned(url)
224    }
225
226    /// Returns [`Display`] implementation that doesn't mask credentials.
227    #[inline]
228    pub fn displayable_with_credentials(&self) -> impl Display {
229        &self.0
230    }
231}
232
233impl Deref for DisplaySafeUrl {
234    type Target = Url;
235
236    fn deref(&self) -> &Self::Target {
237        &self.0
238    }
239}
240
241impl DerefMut for DisplaySafeUrl {
242    fn deref_mut(&mut self) -> &mut Self::Target {
243        &mut self.0
244    }
245}
246
247impl Display for DisplaySafeUrl {
248    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
249        display_with_redacted_credentials(&self.0, f)
250    }
251}
252
253impl Debug for DisplaySafeUrl {
254    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
255        let url = url_with_redacted_sensitive_query_values(&self.0);
256        let url = url.as_ref();
257        // For URLs that use the `git` convention (i.e., `ssh://git@github.com/...`), avoid masking the
258        // username.
259        let (username, password) = if is_ssh_git_username(url) {
260            (url.username(), None)
261        } else if url.username() != "" && url.password().is_some() {
262            (url.username(), Some("****"))
263        } else if url.username() != "" {
264            ("****", None)
265        } else if url.password().is_some() {
266            ("", Some("****"))
267        } else {
268            ("", None)
269        };
270
271        f.debug_struct("DisplaySafeUrl")
272            .field("scheme", &url.scheme())
273            .field("cannot_be_a_base", &url.cannot_be_a_base())
274            .field("username", &username)
275            .field("password", &password)
276            .field("host", &url.host())
277            .field("port", &url.port())
278            .field("path", &url.path())
279            .field("query", &url.query())
280            .field("fragment", &url.fragment())
281            .finish()
282    }
283}
284
285impl From<DisplaySafeUrl> for Url {
286    fn from(url: DisplaySafeUrl) -> Self {
287        url.0
288    }
289}
290
291impl From<Url> for DisplaySafeUrl {
292    fn from(url: Url) -> Self {
293        Self(url)
294    }
295}
296
297impl FromStr for DisplaySafeUrl {
298    type Err = DisplaySafeUrlError;
299
300    fn from_str(input: &str) -> Result<Self, Self::Err> {
301        Self::parse(input)
302    }
303}
304
305fn is_ssh_git_username(url: &Url) -> bool {
306    matches!(url.scheme(), "ssh" | "git+ssh" | "git+https")
307        && url.username() == "git"
308        && url.password().is_none()
309}
310
311fn is_sensitive_query_parameter(key: &str) -> bool {
312    SENSITIVE_QUERY_PARAMETERS
313        .iter()
314        .any(|sensitive| key.eq_ignore_ascii_case(sensitive))
315}
316
317fn url_with_redacted_sensitive_query_values(url: &Url) -> Cow<'_, Url> {
318    if !url
319        .query_pairs()
320        .any(|(key, _value)| is_sensitive_query_parameter(&key))
321    {
322        return Cow::Borrowed(url);
323    }
324
325    let query_pairs: Vec<_> = url
326        .query_pairs()
327        .map(|(key, value)| {
328            let value = if is_sensitive_query_parameter(&key) {
329                Cow::Borrowed("****")
330            } else {
331                value
332            };
333            (key, value)
334        })
335        .collect();
336
337    let mut url = url.clone();
338    url.query_pairs_mut().clear().extend_pairs(query_pairs);
339    Cow::Owned(url)
340}
341
342fn display_with_redacted_credentials(
343    url: &Url,
344    f: &mut std::fmt::Formatter<'_>,
345) -> std::fmt::Result {
346    let url = url_with_redacted_sensitive_query_values(url);
347    let url = url.as_ref();
348    // For URLs that use the `git` convention (i.e., `ssh://git@github.com/...`), avoid dropping the
349    // username.
350    if is_ssh_git_username(url) || (url.username().is_empty() && url.password().is_none()) {
351        return write!(f, "{url}");
352    }
353
354    write!(f, "{}://", url.scheme())?;
355
356    if url.username() != "" && url.password().is_some() {
357        write!(f, "{}", url.username())?;
358        write!(f, ":****@")?;
359    } else if url.username() != "" {
360        write!(f, "****@")?;
361    } else if url.password().is_some() {
362        write!(f, ":****@")?;
363    }
364
365    write!(f, "{}", url.host_str().unwrap_or(""))?;
366
367    if let Some(port) = url.port() {
368        write!(f, ":{port}")?;
369    }
370
371    write!(f, "{}", url.path())?;
372    if let Some(query) = url.query() {
373        write!(f, "?{query}")?;
374    }
375    if let Some(fragment) = url.fragment() {
376        write!(f, "#{fragment}")?;
377    }
378
379    Ok(())
380}
381
382#[cfg(test)]
383mod tests {
384    use super::*;
385
386    #[test]
387    fn from_url_no_credentials() {
388        let url_str = "https://pypi-proxy.fly.dev/basic-auth/simple";
389        let log_safe_url =
390            DisplaySafeUrl::parse("https://pypi-proxy.fly.dev/basic-auth/simple").unwrap();
391        assert_eq!(log_safe_url.username(), "");
392        assert!(log_safe_url.password().is_none());
393        assert_eq!(log_safe_url.to_string(), url_str);
394    }
395
396    #[test]
397    fn from_url_username_and_password() {
398        let log_safe_url =
399            DisplaySafeUrl::parse("https://user:pass@pypi-proxy.fly.dev/basic-auth/simple")
400                .unwrap();
401        assert_eq!(log_safe_url.username(), "user");
402        assert!(log_safe_url.password().is_some_and(|p| p == "pass"));
403        assert_eq!(
404            log_safe_url.to_string(),
405            "https://user:****@pypi-proxy.fly.dev/basic-auth/simple"
406        );
407    }
408
409    #[test]
410    fn from_url_just_password() {
411        let log_safe_url =
412            DisplaySafeUrl::parse("https://:pass@pypi-proxy.fly.dev/basic-auth/simple").unwrap();
413        assert_eq!(log_safe_url.username(), "");
414        assert!(log_safe_url.password().is_some_and(|p| p == "pass"));
415        assert_eq!(
416            log_safe_url.to_string(),
417            "https://:****@pypi-proxy.fly.dev/basic-auth/simple"
418        );
419    }
420
421    #[test]
422    fn from_url_just_username() {
423        let log_safe_url =
424            DisplaySafeUrl::parse("https://user@pypi-proxy.fly.dev/basic-auth/simple").unwrap();
425        assert_eq!(log_safe_url.username(), "user");
426        assert!(log_safe_url.password().is_none());
427        assert_eq!(
428            log_safe_url.to_string(),
429            "https://****@pypi-proxy.fly.dev/basic-auth/simple"
430        );
431    }
432
433    #[test]
434    fn from_url_git_username() {
435        let ssh_str = "ssh://git@github.com/org/repo";
436        let ssh_url = DisplaySafeUrl::parse(ssh_str).unwrap();
437        assert_eq!(ssh_url.username(), "git");
438        assert!(ssh_url.password().is_none());
439        assert_eq!(ssh_url.to_string(), ssh_str);
440        // Test again for the `git+ssh` scheme
441        let git_ssh_str = "git+ssh://git@github.com/org/repo";
442        let git_ssh_url = DisplaySafeUrl::parse(git_ssh_str).unwrap();
443        assert_eq!(git_ssh_url.username(), "git");
444        assert!(git_ssh_url.password().is_none());
445        assert_eq!(git_ssh_url.to_string(), git_ssh_str);
446    }
447
448    #[test]
449    fn parse_url_string() {
450        let url_str = "https://user:pass@pypi-proxy.fly.dev/basic-auth/simple";
451        let log_safe_url = DisplaySafeUrl::parse(url_str).unwrap();
452        assert_eq!(log_safe_url.username(), "user");
453        assert!(log_safe_url.password().is_some_and(|p| p == "pass"));
454        assert_eq!(
455            log_safe_url.to_string(),
456            "https://user:****@pypi-proxy.fly.dev/basic-auth/simple"
457        );
458    }
459
460    #[test]
461    fn remove_credentials() {
462        let url_str = "https://user:pass@pypi-proxy.fly.dev/basic-auth/simple";
463        let mut log_safe_url = DisplaySafeUrl::parse(url_str).unwrap();
464        log_safe_url.remove_credentials();
465        assert_eq!(log_safe_url.username(), "");
466        assert!(log_safe_url.password().is_none());
467        assert_eq!(
468            log_safe_url.to_string(),
469            "https://pypi-proxy.fly.dev/basic-auth/simple"
470        );
471    }
472
473    #[test]
474    fn preserve_ssh_git_username_on_remove_credentials() {
475        let ssh_str = "ssh://git@pypi-proxy.fly.dev/basic-auth/simple";
476        let mut ssh_url = DisplaySafeUrl::parse(ssh_str).unwrap();
477        ssh_url.remove_credentials();
478        assert_eq!(ssh_url.username(), "git");
479        assert!(ssh_url.password().is_none());
480        assert_eq!(ssh_url.to_string(), ssh_str);
481        // Test again for `git+ssh` scheme
482        let git_ssh_str = "git+ssh://git@pypi-proxy.fly.dev/basic-auth/simple";
483        let mut git_shh_url = DisplaySafeUrl::parse(git_ssh_str).unwrap();
484        git_shh_url.remove_credentials();
485        assert_eq!(git_shh_url.username(), "git");
486        assert!(git_shh_url.password().is_none());
487        assert_eq!(git_shh_url.to_string(), git_ssh_str);
488    }
489
490    #[test]
491    fn displayable_with_credentials() {
492        let url_str = "https://user:pass@pypi-proxy.fly.dev/basic-auth/simple";
493        let log_safe_url = DisplaySafeUrl::parse(url_str).unwrap();
494        assert_eq!(
495            log_safe_url.displayable_with_credentials().to_string(),
496            url_str
497        );
498    }
499
500    #[test]
501    fn redact_aws_presigned_query_values() {
502        let log_safe_url = DisplaySafeUrl::parse(
503            "https://bucket.s3.amazonaws.com/dist.whl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=credential&X-Amz-Date=20260424T120000Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=signature&X-Amz-Security-Token=token",
504        )
505        .unwrap();
506
507        assert_eq!(
508            log_safe_url.to_string(),
509            "https://bucket.s3.amazonaws.com/dist.whl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=****&X-Amz-Date=20260424T120000Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=****&X-Amz-Security-Token=****"
510        );
511    }
512
513    #[test]
514    fn redact_aws_presigned_query_values_case_insensitive() {
515        let log_safe_url = DisplaySafeUrl::parse(
516            "https://bucket.s3.amazonaws.com/dist.whl?x-amz-credential=credential&x-amz-signature=signature&x-amz-security-token=token",
517        )
518        .unwrap();
519
520        assert_eq!(
521            log_safe_url.to_string(),
522            "https://bucket.s3.amazonaws.com/dist.whl?x-amz-credential=****&x-amz-signature=****&x-amz-security-token=****"
523        );
524    }
525
526    #[test]
527    fn redact_aws_presigned_query_values_with_percent_encoded_keys() {
528        let log_safe_url = DisplaySafeUrl::parse(
529            "https://bucket.s3.amazonaws.com/dist.whl?X-Amz%2DSignature=signature&safe=value",
530        )
531        .unwrap();
532
533        assert_eq!(
534            log_safe_url.to_string(),
535            "https://bucket.s3.amazonaws.com/dist.whl?X-Amz-Signature=****&safe=value"
536        );
537    }
538
539    #[test]
540    fn redact_aws_presigned_query_values_in_debug() {
541        let log_safe_url = DisplaySafeUrl::parse(
542            "https://bucket.s3.amazonaws.com/dist.whl?X-Amz-Credential=credential&X-Amz-Signature=signature",
543        )
544        .unwrap();
545
546        let debug = format!("{log_safe_url:?}");
547        assert!(debug.contains(r#"query: Some("X-Amz-Credential=****&X-Amz-Signature=****")"#));
548        assert!(!debug.contains("credential"));
549        assert!(!debug.contains("signature"));
550    }
551
552    #[test]
553    fn does_not_redact_unknown_query_values() {
554        let log_safe_url =
555            DisplaySafeUrl::parse("https://bucket.s3.amazonaws.com/dist.whl?token=secret").unwrap();
556
557        assert_eq!(
558            log_safe_url.to_string(),
559            "https://bucket.s3.amazonaws.com/dist.whl?token=secret"
560        );
561    }
562
563    #[test]
564    fn url_join() {
565        let url_str = "https://token@example.com/abc/";
566        let log_safe_url = DisplaySafeUrl::parse(url_str).unwrap();
567        let foo_url = log_safe_url.join("foo").unwrap();
568        assert_eq!(foo_url.to_string(), "https://****@example.com/abc/foo");
569    }
570
571    #[test]
572    fn log_safe_url_ref() {
573        let url_str = "https://user:pass@pypi-proxy.fly.dev/basic-auth/simple";
574        let url = DisplaySafeUrl::parse(url_str).unwrap();
575        let log_safe_url = DisplaySafeUrl::ref_cast(&url);
576        assert_eq!(log_safe_url.username(), "user");
577        assert!(log_safe_url.password().is_some_and(|p| p == "pass"));
578        assert_eq!(
579            log_safe_url.to_string(),
580            "https://user:****@pypi-proxy.fly.dev/basic-auth/simple"
581        );
582    }
583
584    #[test]
585    fn parse_url_ambiguous() {
586        for url in &[
587            "https://user/name:password@domain/a/b/c",
588            "https://user\\name:password@domain/a/b/c",
589            "https://user#name:password@domain/a/b/c",
590            "https://user.com/name:password@domain/a/b/c",
591        ] {
592            let err = DisplaySafeUrl::parse(url).unwrap_err();
593            match err {
594                DisplaySafeUrlError::AmbiguousAuthority(redacted) => {
595                    assert!(redacted.starts_with("https:***@domain/a/b/c"));
596                }
597                DisplaySafeUrlError::Url(_) => panic!("expected AmbiguousAuthority error"),
598            }
599        }
600    }
601
602    #[test]
603    fn parse_url_not_ambiguous() {
604        for url in &[
605            // https://github.com/astral-sh/uv/issues/16756
606            "file:///C:/jenkins/ython_Environment_Manager_PR-251@2/venv%201/workspace",
607            // https://github.com/astral-sh/uv/issues/17214
608            // Git proxy URLs with nested schemes should not trigger the ambiguity check
609            "git+https://githubproxy.cc/https://github.com/user/repo.git@branch",
610            "git+https://proxy.example.com/https://github.com/org/project@v1.0.0",
611            "git+https://proxy.example.com/https://github.com/org/project@refs/heads/main",
612        ] {
613            DisplaySafeUrl::parse(url).unwrap();
614        }
615    }
616
617    #[test]
618    fn credential_like_pattern() {
619        assert!(!has_credential_like_pattern(
620            "/https://github.com/user/repo.git@branch"
621        ));
622        assert!(!has_credential_like_pattern("/http://example.com/path@ref"));
623
624        assert!(has_credential_like_pattern("/name:password@domain/a/b/c"));
625        assert!(has_credential_like_pattern(":password@domain"));
626    }
627}
uv_redacted/lib.rs

uv_redacted/
lib.rs
