Skip to main content

docsrs_cli/config/
validate.rs

1//! UA/contact validation and re-exports for origin allowlist / domain helpers.
2//!
3//! Fail-closed SSRF host policy lives in [`super::allowlist`]. Domain input
4//! (crate name, query, path, version) lives in [`crate::domain`] (ADR 0006).
5
6use crate::domain::AllowedOrigin;
7use crate::error::{AppError, AppResult, ErrorDetail, Subject};
8
9use super::constants::{APP_NAME, APP_VERSION, DEFAULT_CONTACT_URL, MAX_USER_AGENT_CHARS};
10
11// Re-export stdlib name check from the single domain source (DRY-L-001).
12pub use crate::domain::is_stdlib_name as is_stdlib_crate;
13
14/// Builds the default User-Agent, optionally including a contact token.
15pub fn default_user_agent(contact: Option<&str>) -> String {
16    match contact {
17        Some(c) if !c.is_empty() => {
18            if c.starts_with("http://") || c.starts_with("https://") {
19                format!("{APP_NAME}/{APP_VERSION} (+{c})")
20            } else {
21                format!("{APP_NAME}/{APP_VERSION} ({c})")
22            }
23        }
24        _ => format!("{APP_NAME}/{APP_VERSION} (+{DEFAULT_CONTACT_URL})"),
25    }
26}
27
28/// Parse an allowlisted origin (compat wrapper over [`AllowedOrigin::parse`]).
29///
30/// Prefer [`AllowedOrigin`] at call sites so the type carries the allowlist proof.
31///
32/// # Errors
33///
34/// Propagates [`crate::error::ErrorKind::Config`] from [`AllowedOrigin::parse`].
35pub fn validate_origin(raw: &str) -> AppResult<AllowedOrigin> {
36    AllowedOrigin::parse(raw)
37}
38
39/// Parse an origin with an explicit loopback policy (CLI/XDG `allow_loopback`).
40///
41/// # Errors
42///
43/// Propagates [`crate::error::ErrorKind::Config`] from [`AllowedOrigin::parse_with`].
44pub fn validate_origin_with(raw: &str, allow_loopback: bool) -> AppResult<AllowedOrigin> {
45    AllowedOrigin::parse_with(raw, allow_loopback)
46}
47
48/// Validate User-Agent: non-empty, length-capped, visible ASCII only (HTTP header).
49///
50/// # Errors
51///
52/// Returns [`crate::error::ErrorKind::Config`] when empty, over [`MAX_USER_AGENT_CHARS`], or
53/// containing control / non-ASCII bytes (would fail `HeaderValue::from_str`).
54pub fn validate_user_agent(ua: &str) -> AppResult<()> {
55    if ua.is_empty() {
56        return Err(AppError::of(ErrorDetail::Empty {
57            subject: Subject::UserAgent,
58        }));
59    }
60    if ua.chars().count() > MAX_USER_AGENT_CHARS {
61        return Err(AppError::of(ErrorDetail::TooLong {
62            subject: Subject::UserAgent,
63            limit: MAX_USER_AGENT_CHARS,
64        }));
65    }
66    // RFC 9110 field values: reject CTL and non-ASCII so HeaderValue cannot fail later.
67    if !ua.bytes().all(|b| (0x20..=0x7e).contains(&b)) {
68        return Err(AppError::of(ErrorDetail::NotVisibleAscii {
69            subject: Subject::UserAgent,
70        }));
71    }
72    Ok(())
73}
74
75/// Validate optional `contact` token embedded into the default User-Agent.
76///
77/// Same visible-ASCII policy as [`validate_user_agent`] (contact is interpolated
78/// into the UA string). Empty contact is rejected when present as `Some("")`.
79///
80/// # Errors
81///
82/// Returns [`crate::error::ErrorKind::Config`] when empty, over [`MAX_USER_AGENT_CHARS`], or
83/// not visible ASCII.
84pub fn validate_contact(contact: &str) -> AppResult<()> {
85    if contact.is_empty() {
86        return Err(AppError::of(ErrorDetail::Empty {
87            subject: Subject::Contact,
88        }));
89    }
90    if contact.chars().count() > MAX_USER_AGENT_CHARS {
91        return Err(AppError::of(ErrorDetail::TooLong {
92            subject: Subject::Contact,
93            limit: MAX_USER_AGENT_CHARS,
94        }));
95    }
96    if !contact.bytes().all(|b| (0x20..=0x7e).contains(&b)) {
97        return Err(AppError::of(ErrorDetail::NotVisibleAscii {
98            subject: Subject::Contact,
99        }));
100    }
101    Ok(())
102}