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}