microsandbox_network/policy/

name.rs

//! Validated DNS name type used in [`super::Destination`] rules.
//!
//! Rules stored on a [`NetworkPolicy`] identify hosts by string, and
//! user input reaches the policy through several paths (programmatic
//! construction, JSON deserialization, CLI-supplied JSON). Each path
//! used to re-apply the same ad-hoc canonicalization (lowercase, trim
//! trailing dot, strip leading dot for suffixes) and it was easy to
//! miss — struct-literal construction, in particular, bypassed every
//! entry point and silently produced rules that never matched.
//!
//! [`DomainName`] closes that gap. The inner field is private and the
//! only way to build one is via [`str::parse`] (or serde, which routes
//! through the same parser), so the canonical form is a type-level
//! invariant rather than a convention. Matching code then collapses
//! to byte equality on the pre-canonicalized string.
//!
//! Validation is delegated to `hickory_proto::rr::Name`, which accepts
//! the real-world DNS label grammar (RFC 2181 §11) rather than the
//! stricter "preferred name syntax" of RFC 1035 §2.3.1 / RFC 1123
//! §2.1. That lets `_service._tcp.example.com`, DKIM selectors, and
//! similarly underscore-bearing names through, matching what the
//! sandbox's DNS interceptor will actually resolve on the wire.
//!
//! [`NetworkPolicy`]: super::NetworkPolicy

use std::fmt;
use std::str::FromStr;

use hickory_proto::ProtoError;
use hickory_proto::rr::Name;
use serde::{Deserialize, Serialize};

//--------------------------------------------------------------------------------------------------
// Types
//--------------------------------------------------------------------------------------------------

/// Canonical DNS name used in network policy rules.
///
/// Strictly a hostname — port suffixes, userinfo, schemes, paths,
/// queries, and fragments are rejected at parse time so a rule can
/// never end up "matching" a name no DNS responder will ever return.
///
/// Constructed via `str::parse` or `TryFrom<String>`; both route through
/// the same validation and canonicalization. The inner form is
/// lowercased ASCII with no leading or trailing dots — the same form
/// the DNS interceptor stores on the resolved-hostname cache, which
/// lets match-time comparisons be byte-equal rather than
/// case-insensitive.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
pub struct DomainName(String);

/// Errors reported when a string cannot be turned into a [`DomainName`].
#[derive(Debug, Clone, thiserror::Error)]
pub enum DomainNameError {
    /// Input was empty (or contained only dots).
    #[error("domain name is empty")]
    Empty,

    /// Input failed the DNS label grammar check (bad length, control
    /// chars, invalid UTF-8 for an ASCII name, etc.).
    #[error("invalid domain name: {0}")]
    Invalid(#[from] ProtoError),

    /// Suffix pattern resolves to a single DNS label (e.g. `com`,
    /// `local`, `internal`). A label-aware suffix matcher treats this
    /// as "match every subdomain under that TLD," which is almost
    /// never the operator's intent. Add at least one parent label
    /// (e.g. `corp.internal`, `myco.com`).
    #[error(
        "suffix `{raw}` is a single DNS label and would match every domain under that TLD; \
         add at least one parent label to scope it (e.g. `myco.{raw}`)"
    )]
    SuffixTooBroad { raw: String },
}

//--------------------------------------------------------------------------------------------------
// Methods
//--------------------------------------------------------------------------------------------------

impl DomainName {
    /// Borrow the canonical string form. The returned slice has no
    /// trailing dot and is lowercased ASCII.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Validate this name for use as a [`Destination::DomainSuffix`]
    /// target and return it unchanged on success.
    ///
    /// Returns [`DomainNameError::SuffixTooBroad`] when the name is a
    /// single DNS label (e.g. `com`, `local`, `internal`). The
    /// label-aware suffix matcher would otherwise treat such a name
    /// as "match every host under that TLD" which is almost certainly
    /// not what the operator meant. Use a multi-label suffix
    /// (`myco.com`, `corp.internal`) instead.
    ///
    /// Domains intended for exact-match rules are unaffected: use
    /// `Destination::Domain` for those.
    ///
    /// [`Destination::DomainSuffix`]: super::Destination::DomainSuffix
    pub fn try_into_suffix(self) -> Result<Self, DomainNameError> {
        if self.0.contains('.') {
            Ok(self)
        } else {
            Err(DomainNameError::SuffixTooBroad {
                raw: self.0.clone(),
            })
        }
    }
}

impl FromStr for DomainName {
    type Err = DomainNameError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        // Leading-dot acceptance is ergonomic for suffixes
        // (`.example.com`). Trailing-dot acceptance matches FQDN
        // inputs coming from DNS responses or hand-typed FQDNs.
        let trimmed = s.trim_start_matches('.').trim_end_matches('.');
        if trimmed.is_empty() {
            return Err(DomainNameError::Empty);
        }
        // Validate via hickory. We discard the parsed Name and keep
        // the lowercased ASCII string so matching is a plain `==`
        // against the cache entries.
        let _name: Name = trimmed.parse()?;
        Ok(Self(trimmed.to_ascii_lowercase()))
    }
}

impl TryFrom<String> for DomainName {
    type Error = DomainNameError;

    fn try_from(s: String) -> Result<Self, Self::Error> {
        s.parse()
    }
}

impl TryFrom<&str> for DomainName {
    type Error = DomainNameError;

    fn try_from(s: &str) -> Result<Self, Self::Error> {
        s.parse()
    }
}

impl From<DomainName> for String {
    fn from(name: DomainName) -> Self {
        name.0
    }
}

impl fmt::Display for DomainName {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

//--------------------------------------------------------------------------------------------------
// Tests
//--------------------------------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parses_plain_lowercase_name() {
        let name: DomainName = "pypi.org".parse().unwrap();
        assert_eq!(name.as_str(), "pypi.org");
    }

    #[test]
    fn canonicalizes_case_and_trailing_dot() {
        let name: DomainName = "PyPI.Org.".parse().unwrap();
        assert_eq!(name.as_str(), "pypi.org");
    }

    #[test]
    fn strips_leading_dot_for_suffix_ergonomics() {
        let name: DomainName = ".pythonhosted.org".parse().unwrap();
        assert_eq!(name.as_str(), "pythonhosted.org");
    }

    #[test]
    fn canonical_form_is_idempotent() {
        let once: DomainName = "Example.COM.".parse().unwrap();
        let twice: DomainName = once.as_str().parse().unwrap();
        assert_eq!(once, twice);
    }

    #[test]
    fn accepts_underscore_labels() {
        // SRV / DKIM / Kubernetes names rely on underscore labels
        // (RFC 2181 §11). Rejecting them would break real-world
        // policy inputs.
        let name: DomainName = "_http._tcp.example.com".parse().unwrap();
        assert_eq!(name.as_str(), "_http._tcp.example.com");
    }

    #[test]
    fn rejects_empty_input() {
        assert!(matches!(
            "".parse::<DomainName>(),
            Err(DomainNameError::Empty)
        ));
        assert!(matches!(
            "...".parse::<DomainName>(),
            Err(DomainNameError::Empty)
        ));
    }

    #[test]
    fn rejects_whitespace_in_labels() {
        assert!("foo bar.example".parse::<DomainName>().is_err());
    }

    #[test]
    fn serde_round_trip_preserves_canonical_form() {
        let name: DomainName = ".PyPI.Org.".parse().unwrap();
        let json = serde_json::to_string(&name).unwrap();
        assert_eq!(json, r#""pypi.org""#);
        let back: DomainName = serde_json::from_str(&json).unwrap();
        assert_eq!(back, name);
    }

    #[test]
    fn serde_deserialize_validates() {
        assert!(serde_json::from_str::<DomainName>(r#""foo bar.example""#).is_err());
        assert!(serde_json::from_str::<DomainName>(r#""""#).is_err());
    }

    #[test]
    fn try_into_suffix_accepts_multilabel_names() {
        let name: DomainName = "example.com".parse().unwrap();
        let suffix = name.try_into_suffix().unwrap();
        assert_eq!(suffix.as_str(), "example.com");

        let deep: DomainName = "api.staging.example.com".parse().unwrap();
        let suffix = deep.try_into_suffix().unwrap();
        assert_eq!(suffix.as_str(), "api.staging.example.com");
    }

    #[test]
    fn try_into_suffix_rejects_single_label_tlds() {
        for raw in ["com", "local", "internal", "intranet", "lan"] {
            let name: DomainName = raw.parse().unwrap();
            let err = name.try_into_suffix().unwrap_err();
            assert!(
                matches!(&err, DomainNameError::SuffixTooBroad { raw: r } if r == raw),
                "expected SuffixTooBroad for `{raw}`, got {err:?}"
            );
            let msg = err.to_string();
            assert!(
                msg.contains("match every domain"),
                "error message should explain blast radius, got: {msg}"
            );
        }
    }

    #[test]
    fn rejects_url_decorations() {
        for bad in [
            "bar.example:443",       // host:port
            "user@example.com",      // userinfo@host
            "user:pass@example.com", // userinfo:pass@host
            "https://example.com",   // scheme://host
            "example.com/path",      // host/path
            "example.com?q=1",       // host?query
            "example.com#frag",      // host#fragment
        ] {
            assert!(
                bad.parse::<DomainName>().is_err(),
                "expected `{bad}` to be rejected"
            );
            let json = serde_json::to_string(bad).unwrap();
            assert!(
                serde_json::from_str::<DomainName>(&json).is_err(),
                "expected serde to reject `{bad}`"
            );
        }
    }
}