microsandbox-network 0.4.5

//! Policy types: rules, actions, destinations, and protocol matching.
//!
//! A [`NetworkPolicy`] is a single ordered rule list plus two direction-
//! specific default actions. Each rule carries its direction
//! ([`Direction`]) — `Egress`, `Ingress`, or `Both` — which determines
//! which evaluator considers it. Rule lookup is first-match-wins per
//! direction; if no rule of the right direction matches, the direction-
//! specific default applies.
//!
//! The `Rule::destination` field is direction-dependent in interpretation.
//! In an egress rule it matches the destination the guest is reaching;
//! in an ingress rule it matches the source (peer) of the incoming
//! connection. `Rule::ports` always refers to the guest-side port
//! (destination for egress, listening port for ingress) — ingress does
//! not filter by peer source port.
//!
//! [`Rule::protocols`] and [`Rule::ports`] are sets (Vecs); a rule
//! matches if the packet's protocol is in `protocols` or `protocols` is
//! empty (any-protocol), and likewise for ports. This compresses common
//! cases like "TCP-or-UDP on 80-or-443 to Public" into a single rule.

use std::net::{IpAddr, SocketAddr};

use ipnetwork::IpNetwork;
use serde::{Deserialize, Serialize};

use crate::shared::SharedState;

use super::destination::{matches_cidr, matches_group};
use super::name::{DomainName, DomainNameError};

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

/// Network policy: single ordered rule list plus per-direction default actions.
///
/// Rules carry a [`Direction`] field that determines which evaluator
/// considers them. Egress evaluation iterates rules where
/// `direction ∈ {Egress, Both}`; ingress evaluation iterates rules where
/// `direction ∈ {Ingress, Both}`. First-match-wins within a direction.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NetworkPolicy {
    /// Default action for egress traffic not matching any rule.
    /// `Deny` paired with an implicit allow-`Public` rule reproduces
    /// today's "public internet only" reachability.
    #[serde(default = "Action::deny")]
    pub default_egress: Action,

    /// Default action for ingress traffic not matching any rule. The
    /// per-field serde default is `Deny` so partially-specified JSON
    /// fails closed; permissive presets like [`NetworkPolicy::public_only`]
    /// flip this back to `Allow` explicitly.
    #[serde(default = "Action::deny")]
    pub default_ingress: Action,

    /// Ordered list of rules, evaluated first-match-wins per direction.
    #[serde(default)]
    pub rules: Vec<Rule>,
}

/// Action to take on matched traffic.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Action {
    /// Allow the traffic.
    Allow,

    /// Silently drop.
    Deny,
}

/// A single network rule.
///
/// The `destination` field is direction-dependent: in an egress-direction
/// rule, `destination` is what the guest is reaching; in an ingress-
/// direction rule, `destination` is the source (peer) of the incoming
/// connection. `Both`-direction rules apply in either path with the
/// destination interpreted appropriately for each.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Rule {
    /// Direction this rule applies to: outbound, inbound, or either.
    pub direction: Direction,

    /// Destination filter. Direction-dependent interpretation.
    pub destination: Destination,

    /// Protocol set (empty = any protocol). The rule matches if the
    /// packet's protocol is in this set.
    #[serde(default)]
    pub protocols: Vec<Protocol>,

    /// Port-range set (empty = any port). Always the guest-side port:
    /// destination port for egress, listening port for ingress.
    #[serde(default)]
    pub ports: Vec<PortRange>,

    /// Action to take.
    pub action: Action,
}

/// Direction a rule applies to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Direction {
    /// Outbound: guest → destination. Evaluated by `evaluate_egress`.
    Egress,

    /// Inbound: peer → guest. Evaluated by `evaluate_ingress`.
    Ingress,

    /// Either direction. The rule is matched by both evaluators
    /// (egress and ingress).
    Any,
}

/// Traffic destination specification.
///
/// `Domain` and `DomainSuffix` values carry a validated [`DomainName`],
/// whose construction enforces the canonical form (lowercase ASCII,
/// leading/trailing dots stripped) once at parse time. Matching code
/// can then rely on byte equality against the DNS cache's own
/// canonical entries.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Destination {
    /// Match any destination.
    Any,

    /// IP address or CIDR block.
    Cidr(IpNetwork),

    /// Exact domain name. Matches only when a cached hostname for the
    /// destination IP equals this name.
    Domain(DomainName),

    /// Domain suffix. Matches the apex domain itself and any subdomain
    /// of it (e.g. suffix `example.com` matches `example.com` and
    /// `foo.example.com` but not `evilexample.com`).
    DomainSuffix(DomainName),

    /// Pre-defined destination group.
    Group(DestinationGroup),
}

/// Pre-defined destination groups.
///
/// Categories are disjoint with one exception: `Metadata` is a single IP
/// (`169.254.169.254`) that also falls inside the `LinkLocal` range.
/// Membership order in [`matches_group`](super::destination::matches_group)
/// gives `Metadata` precedence over `LinkLocal` for that IP. All other
/// categories are disjoint; [`Public`](Self::Public) is defined as the
/// complement of the other five.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DestinationGroup {
    /// Public internet — any address not in one of the other categories.
    Public,

    /// Loopback addresses (`127.0.0.0/8`, `::1`).
    Loopback,

    /// Private IP ranges (RFC 1918 + RFC 4193 ULA + CGN).
    Private,

    /// Link-local addresses (`169.254.0.0/16`, `fe80::/10`), excluding
    /// the metadata IP which is categorized as [`Metadata`](Self::Metadata).
    LinkLocal,

    /// Cloud metadata endpoints (`169.254.169.254`).
    Metadata,

    /// Multicast addresses (`224.0.0.0/4`, `ff00::/8`).
    Multicast,

    /// The sandbox host itself, reachable via the gateway IP and
    /// `host.microsandbox.internal`. Matches against the per-sandbox
    /// gateway IPs stored on [`SharedState`].
    Host,
}

/// Protocol filter.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Protocol {
    /// TCP.
    Tcp,

    /// UDP.
    Udp,

    /// ICMPv4.
    Icmpv4,

    /// ICMPv6.
    Icmpv6,
}

/// Port range for matching.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct PortRange {
    /// Start port (inclusive).
    pub start: u16,

    /// End port (inclusive).
    pub end: u16,
}

/// Source of the hostname used to match `Domain` / `DomainSuffix`
/// rules during an egress evaluation.
#[derive(Debug, Clone, Copy)]
pub enum HostnameSource<'a> {
    /// Hostname from a TLS ClientHello, canonicalized.
    Sni(&'a str),
    /// No SNI — match `Domain` rules via the resolved-hostname cache.
    CacheOnly,
    /// SYN time, before SNI is known. A matching `Domain` /
    /// `DomainSuffix` rule short-circuits to
    /// [`EgressEvaluation::DeferUntilHostname`].
    Deferred,
}

impl HostnameSource<'_> {
    /// Short label for tracing tags (`"sni"`, `"cache"`, `"deferred"`).
    pub fn label(&self) -> &'static str {
        match self {
            HostnameSource::Sni(_) => "sni",
            HostnameSource::CacheOnly => "cache",
            HostnameSource::Deferred => "deferred",
        }
    }
}

/// Outcome of an egress evaluation. Like [`Action`] plus a deferred
/// state reachable only under [`HostnameSource::Deferred`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EgressEvaluation {
    /// Permit the connection.
    Allow,
    /// Refuse the connection.
    Deny,
    /// First match was a Domain / DomainSuffix rule and the SNI isn't
    /// known yet — accept the SYN and re-evaluate at first-flight.
    DeferUntilHostname,
}

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

impl NetworkPolicy {
    /// No network access — deny everything in both directions.
    pub fn none() -> Self {
        Self {
            default_egress: Action::Deny,
            default_ingress: Action::Deny,
            rules: vec![],
        }
    }

    /// Unrestricted network access — allow everything in both directions.
    pub fn allow_all() -> Self {
        Self {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![],
        }
    }

    /// Public internet only — allow egress to public IPs, deny private,
    /// loopback, link-local, and metadata. Ingress defaults to allow
    /// (preserves today's unfiltered published-port behavior).
    pub fn public_only() -> Self {
        Self {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule::allow_egress(Destination::Group(
                DestinationGroup::Public,
            ))],
        }
    }

    /// Non-local network access — allow public internet and private/LAN
    /// egress; deny loopback, link-local, and metadata. Ingress defaults
    /// to allow.
    pub fn non_local() -> Self {
        Self {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![
                Rule::allow_egress(Destination::Group(DestinationGroup::Public)),
                Rule::allow_egress(Destination::Group(DestinationGroup::Private)),
            ],
        }
    }

    /// Evaluate an outbound connection against the rule list.
    ///
    /// Iterates rules in order, considering only rules where
    /// `direction ∈ {Egress, Any}`. Returns the action from the first
    /// matching rule, or `default_egress` if no rule matches.
    pub fn evaluate_egress(
        &self,
        dst: SocketAddr,
        protocol: Protocol,
        shared: &SharedState,
    ) -> Action {
        self.egress_walk(
            dst.ip(),
            Some(dst.port()),
            protocol,
            shared,
            HostnameSource::CacheOnly,
        )
        .into()
    }

    /// Evaluate an outbound ICMP packet against the rule list. Like
    /// [`Self::evaluate_egress`] but skips rules with a port filter
    /// (ICMP has no ports).
    pub fn evaluate_egress_ip(
        &self,
        dst: IpAddr,
        protocol: Protocol,
        shared: &SharedState,
    ) -> Action {
        self.egress_walk(dst, None, protocol, shared, HostnameSource::CacheOnly)
            .into()
    }

    /// Evaluate an outbound connection with an explicit
    /// [`HostnameSource`] for `Domain` / `DomainSuffix` matching.
    /// Walk order and protocol/port filtering are identical across
    /// sources — only the Domain match predicate varies.
    pub fn evaluate_egress_with_source(
        &self,
        dst: SocketAddr,
        protocol: Protocol,
        shared: &SharedState,
        source: HostnameSource<'_>,
    ) -> EgressEvaluation {
        self.egress_walk(dst.ip(), Some(dst.port()), protocol, shared, source)
    }

    /// Shared rule walk for the egress public methods. `port = None`
    /// is the ICMP path; rules with a port filter are skipped there.
    fn egress_walk(
        &self,
        addr: IpAddr,
        port: Option<u16>,
        protocol: Protocol,
        shared: &SharedState,
        source: HostnameSource<'_>,
    ) -> EgressEvaluation {
        for rule in &self.rules {
            if !matches!(rule.direction, Direction::Egress | Direction::Any) {
                continue;
            }
            if !rule.protocols.is_empty() && !rule.protocols.contains(&protocol) {
                continue;
            }
            if !rule.ports.is_empty() {
                let Some(p) = port else {
                    continue;
                };
                if !rule.ports.iter().any(|range| range.contains(p)) {
                    continue;
                }
            }
            match matches_destination_with_source(&rule.destination, addr, shared, source) {
                DestinationMatch::Match => return rule.action.into(),
                DestinationMatch::Defer => return EgressEvaluation::DeferUntilHostname,
                DestinationMatch::NoMatch => continue,
            }
        }
        self.default_egress.into()
    }

    /// Evaluate an inbound connection against the rule list.
    ///
    /// Iterates rules in order, considering only rules where
    /// `direction ∈ {Ingress, Any}`. `peer` is the source of the
    /// incoming connection (peer IP and source port — only the IP is
    /// matched). `guest_port` is the guest-side listening port; rules'
    /// `ports` filter is matched against `guest_port`, not the peer's
    /// port.
    pub fn evaluate_ingress(
        &self,
        peer: SocketAddr,
        guest_port: u16,
        protocol: Protocol,
        shared: &SharedState,
    ) -> Action {
        for rule in &self.rules {
            if !matches!(rule.direction, Direction::Ingress | Direction::Any) {
                continue;
            }
            if !rule_matches(rule, peer.ip(), Some(guest_port), protocol, shared) {
                continue;
            }
            return rule.action;
        }
        self.default_ingress
    }

    /// True if any rule references a `Domain` or `DomainSuffix`
    /// destination. The TCP proxy uses this to skip its SNI peek when
    /// no rule could possibly need a hostname for evaluation.
    pub fn has_domain_rules(&self) -> bool {
        self.rules.iter().any(|r| {
            matches!(
                r.destination,
                Destination::Domain(_) | Destination::DomainSuffix(_)
            )
        })
    }

    /// Should the DNS forwarder refuse a query for `name`?
    ///
    /// Returns `true` iff the first matching Domain / DomainSuffix
    /// rule has action `Deny`. Port and protocol filters and
    /// `default_egress` are not consulted — only explicit deny rules
    /// refuse a query.
    pub fn dns_query_denied(&self, name: &DomainName) -> bool {
        for rule in &self.rules {
            if !matches!(rule.direction, Direction::Egress | Direction::Any) {
                continue;
            }
            let matched = match &rule.destination {
                Destination::Domain(d) => name.as_str() == d.as_str(),
                Destination::DomainSuffix(s) => matches_suffix(name.as_str(), s.as_str()),
                _ => false,
            };
            if matched {
                return rule.action == Action::Deny;
            }
        }
        false
    }

    /// Single-name sugar over [`Self::deny_domains`].
    pub fn deny_domain<S: AsRef<str>>(self, name: S) -> Result<Self, DomainNameError> {
        self.deny_domains([name])
    }

    /// Single-name sugar over [`Self::allow_domains`].
    pub fn allow_domain<S: AsRef<str>>(self, name: S) -> Result<Self, DomainNameError> {
        self.allow_domains([name])
    }

    /// Single-suffix sugar over [`Self::deny_domain_suffixes`].
    pub fn deny_domain_suffix<S: AsRef<str>>(self, suffix: S) -> Result<Self, DomainNameError> {
        self.deny_domain_suffixes([suffix])
    }

    /// Single-suffix sugar over [`Self::allow_domain_suffixes`].
    pub fn allow_domain_suffix<S: AsRef<str>>(self, suffix: S) -> Result<Self, DomainNameError> {
        self.allow_domain_suffixes([suffix])
    }

    /// Prepend `deny Domain(name)` egress rules. Prepending lets the
    /// deny outrank catch-all allows like `allow Public`.
    pub fn deny_domains<I, S>(self, names: I) -> Result<Self, DomainNameError>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        self.prepend_egress_rules(names, |d| Rule::deny_egress(Destination::Domain(d)))
    }

    /// Prepend `allow Domain(name)` egress rules.
    pub fn allow_domains<I, S>(self, names: I) -> Result<Self, DomainNameError>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        self.prepend_egress_rules(names, |d| Rule::allow_egress(Destination::Domain(d)))
    }

    /// Prepend `deny DomainSuffix(suffix)` egress rules. Suffixes
    /// match the apex and any subdomain (label-aligned).
    pub fn deny_domain_suffixes<I, S>(self, suffixes: I) -> Result<Self, DomainNameError>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        self.prepend_egress_rules(suffixes, |d| {
            Rule::deny_egress(Destination::DomainSuffix(d))
        })
    }

    /// Prepend `allow DomainSuffix(suffix)` egress rules.
    pub fn allow_domain_suffixes<I, S>(self, suffixes: I) -> Result<Self, DomainNameError>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        self.prepend_egress_rules(suffixes, |d| {
            Rule::allow_egress(Destination::DomainSuffix(d))
        })
    }

    fn prepend_egress_rules<I, S, F>(
        mut self,
        names: I,
        mk_rule: F,
    ) -> Result<Self, DomainNameError>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
        F: Fn(DomainName) -> Rule,
    {
        let mut new_rules = Vec::new();
        for name in names {
            let domain: DomainName = name.as_ref().parse()?;
            new_rules.push(mk_rule(domain));
        }
        new_rules.extend(std::mem::take(&mut self.rules));
        self.rules = new_rules;
        Ok(self)
    }
}

impl Action {
    /// Returns `true` if this action allows the traffic.
    pub fn is_allow(self) -> bool {
        matches!(self, Action::Allow)
    }

    /// Returns `true` if this action denies the traffic.
    pub fn is_deny(self) -> bool {
        matches!(self, Action::Deny)
    }

    /// Helper for `#[serde(default)]` — returns [`Action::Allow`].
    pub fn allow() -> Self {
        Action::Allow
    }

    /// Helper for `#[serde(default)]` — returns [`Action::Deny`].
    pub fn deny() -> Self {
        Action::Deny
    }
}

impl From<Action> for EgressEvaluation {
    fn from(action: Action) -> Self {
        match action {
            Action::Allow => EgressEvaluation::Allow,
            Action::Deny => EgressEvaluation::Deny,
        }
    }
}

impl From<EgressEvaluation> for Action {
    /// `DeferUntilHostname` is unreachable here (only the SYN handler
    /// asks for deferral, and it doesn't request an `Action`). Debug
    /// builds panic; release falls back to `Deny`.
    fn from(eval: EgressEvaluation) -> Self {
        match eval {
            EgressEvaluation::Allow => Action::Allow,
            EgressEvaluation::Deny => Action::Deny,
            EgressEvaluation::DeferUntilHostname => {
                debug_assert!(
                    false,
                    "EgressEvaluation::DeferUntilHostname leaked through a CacheOnly/Sni evaluator"
                );
                Action::Deny
            }
        }
    }
}

impl Default for NetworkPolicy {
    fn default() -> Self {
        Self::public_only()
    }
}

impl Rule {
    /// Convenience: allow rule for egress, any protocol, any port.
    pub fn allow_egress(destination: Destination) -> Self {
        Self::new(Direction::Egress, destination, Action::Allow)
    }

    /// Convenience: deny rule for egress, any protocol, any port.
    pub fn deny_egress(destination: Destination) -> Self {
        Self::new(Direction::Egress, destination, Action::Deny)
    }

    /// Convenience: allow rule for ingress, any protocol, any port.
    pub fn allow_ingress(destination: Destination) -> Self {
        Self::new(Direction::Ingress, destination, Action::Allow)
    }

    /// Convenience: deny rule for ingress, any protocol, any port.
    pub fn deny_ingress(destination: Destination) -> Self {
        Self::new(Direction::Ingress, destination, Action::Deny)
    }

    /// Convenience: allow rule for either direction, any protocol, any port.
    pub fn allow_any(destination: Destination) -> Self {
        Self::new(Direction::Any, destination, Action::Allow)
    }

    /// Convenience: deny rule for either direction, any protocol, any port.
    pub fn deny_any(destination: Destination) -> Self {
        Self::new(Direction::Any, destination, Action::Deny)
    }

    fn new(direction: Direction, destination: Destination, action: Action) -> Self {
        Self {
            direction,
            destination,
            protocols: Vec::new(),
            ports: Vec::new(),
            action,
        }
    }
}

impl PortRange {
    /// Match a single port.
    pub fn single(port: u16) -> Self {
        Self {
            start: port,
            end: port,
        }
    }

    /// Match a range of ports (inclusive).
    pub fn range(start: u16, end: u16) -> Self {
        Self { start, end }
    }

    /// Returns `true` if the port falls within this range.
    pub fn contains(&self, port: u16) -> bool {
        port >= self.start && port <= self.end
    }
}

//--------------------------------------------------------------------------------------------------
// Functions
//--------------------------------------------------------------------------------------------------

/// Internal helper: does this rule match a flow's address/port/protocol?
///
/// The direction filter is applied by the caller (`evaluate_egress` /
/// `evaluate_ingress`). This function checks only protocol set, port
/// set, and destination match.
fn rule_matches(
    rule: &Rule,
    addr: IpAddr,
    port: Option<u16>,
    protocol: Protocol,
    shared: &SharedState,
) -> bool {
    if !rule.protocols.is_empty() && !rule.protocols.contains(&protocol) {
        return false;
    }
    if !rule.ports.is_empty() {
        let Some(p) = port else {
            // Caller doesn't have a port (ICMP path). Skip rules that
            // require a port match.
            return false;
        };
        if !rule.ports.iter().any(|range| range.contains(p)) {
            return false;
        }
    }
    matches_destination(&rule.destination, addr, shared)
}

/// Internal three-state result for [`matches_destination_with_source`].
/// `Defer` is reachable only when the source is
/// [`HostnameSource::Deferred`] and the destination is `Domain` or
/// `DomainSuffix`.
enum DestinationMatch {
    Match,
    NoMatch,
    Defer,
}

impl From<bool> for DestinationMatch {
    fn from(matched: bool) -> Self {
        if matched {
            DestinationMatch::Match
        } else {
            DestinationMatch::NoMatch
        }
    }
}

/// Check if an IP / hostname source matches a destination specification.
///
/// IP-based destinations (`Any`, `Cidr`, `Group`) ignore `source` since
/// they decide on the address alone. `Domain` / `DomainSuffix` consult
/// `source`:
///
/// - [`HostnameSource::Sni`]: byte-equality against the canonicalized
///   SNI string (or label-aware suffix match).
/// - [`HostnameSource::CacheOnly`]: query the resolved-hostname cache
///   on `shared` for any prior resolution of `addr` that matches.
/// - [`HostnameSource::Deferred`]: short-circuits to
///   [`DestinationMatch::Defer`].
fn matches_destination_with_source(
    dest: &Destination,
    addr: IpAddr,
    shared: &SharedState,
    source: HostnameSource<'_>,
) -> DestinationMatch {
    match dest {
        Destination::Any => DestinationMatch::Match,
        Destination::Cidr(network) => matches_cidr(network, addr).into(),
        Destination::Group(group) => matches_group(*group, addr, shared).into(),
        Destination::Domain(domain) => match source {
            HostnameSource::Sni(name) => (name == domain.as_str()).into(),
            HostnameSource::CacheOnly => shared
                .any_resolved_hostname(addr, |hostname| hostname == domain.as_str())
                .into(),
            HostnameSource::Deferred => DestinationMatch::Defer,
        },
        Destination::DomainSuffix(suffix) => match source {
            HostnameSource::Sni(name) => matches_suffix(name, suffix.as_str()).into(),
            HostnameSource::CacheOnly => shared
                .any_resolved_hostname(addr, |hostname| matches_suffix(hostname, suffix.as_str()))
                .into(),
            HostnameSource::Deferred => DestinationMatch::Defer,
        },
    }
}

/// Cache-only destination match used by the ingress evaluator. Wraps
/// [`matches_destination_with_source`] with [`HostnameSource::CacheOnly`]
/// since ingress has no SNI concept.
fn matches_destination(dest: &Destination, addr: IpAddr, shared: &SharedState) -> bool {
    matches!(
        matches_destination_with_source(dest, addr, shared, HostnameSource::CacheOnly),
        DestinationMatch::Match,
    )
}

/// Label-aware suffix match on pre-canonicalized strings.
///
/// `hostname` is the lowercased-no-trailing-dot form the DNS cache
/// stores; `suffix` is a [`DomainName`]'s inner string, which shares
/// the same canonical form. Matches either the apex domain itself or
/// any subdomain (label-aligned, so `evilexample.com` does not match
/// suffix `example.com`). A plain `==` would miss the apex-vs-subdomain
/// asymmetry, which is why this helper still exists.
fn matches_suffix(hostname: &str, suffix: &str) -> bool {
    if hostname == suffix {
        return true;
    }
    if hostname.len() > suffix.len() + 1 {
        let (prefix, tail) = hostname.split_at(hostname.len() - suffix.len());
        return prefix.ends_with('.') && tail == suffix;
    }
    false
}

#[cfg(test)]
mod tests {
    use std::net::{Ipv4Addr, Ipv6Addr};
    use std::time::Duration;

    use super::*;
    use crate::shared::ResolvedHostnameFamily;

    const PYPI_V4: &str = "151.101.0.223";
    const FILES_V4: &str = "151.101.64.223";
    const CLOUDFLARE_V6: &str = "2606:4700:4700::1111";

    fn ip(s: &str) -> IpAddr {
        s.parse().unwrap()
    }

    fn sock(ip_str: &str, port: u16) -> SocketAddr {
        SocketAddr::new(ip(ip_str), port)
    }

    /// Insert a resolved hostname into the cache.
    fn cache(shared: &SharedState, host: &str, family: ResolvedHostnameFamily, ip_str: &str) {
        shared.cache_resolved_hostname(host, family, [ip(ip_str)], Duration::from_secs(60));
    }

    /// Build a shared state that has one IPv4 resolved hostname cached.
    fn shared_with_host(host: &str, ip_str: &str) -> SharedState {
        let shared = SharedState::new(4);
        cache(&shared, host, ResolvedHostnameFamily::Ipv4, ip_str);
        shared
    }

    /// Build a shared state with gateway IPs set, for `Group::Host` tests.
    fn shared_with_gateway() -> (SharedState, Ipv4Addr, Ipv6Addr) {
        let shared = SharedState::new(4);
        let v4 = Ipv4Addr::new(100, 96, 0, 1);
        let v6 = Ipv6Addr::new(0xfd42, 0x6d73, 0x62, 0, 0, 0, 0, 1);
        shared.set_gateway_ips(Some(v4), Some(v6));
        (shared, v4, v6)
    }

    fn egress_tcp(policy: &NetworkPolicy, ip_str: &str, shared: &SharedState) -> Action {
        policy.evaluate_egress(sock(ip_str, 443), Protocol::Tcp, shared)
    }

    fn allow_rule(dest: Destination) -> NetworkPolicy {
        NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule::allow_egress(dest)],
        }
    }

    /// Outbound TCP/443 allow rule pinned to a specific hostname,
    /// used by the multi-rule default-deny scenarios below.
    fn allow_domain_tcp_443(domain: &str) -> Rule {
        Rule {
            direction: Direction::Egress,
            destination: Destination::Domain(domain.parse().unwrap()),
            protocols: vec![Protocol::Tcp],
            ports: vec![PortRange::single(443)],
            action: Action::Allow,
        }
    }

    #[test]
    fn exact_domain_rules_match_resolved_hostnames() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = allow_rule(Destination::Domain("pypi.org".parse().unwrap()));
        assert!(egress_tcp(&policy, PYPI_V4, &shared).is_allow());
    }

    #[test]
    fn exact_domain_rules_normalize_user_input() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = allow_rule(Destination::Domain("PyPI.Org.".parse().unwrap()));
        assert!(egress_tcp(&policy, PYPI_V4, &shared).is_allow());
    }

    #[test]
    fn suffix_rules_match_resolved_hostnames() {
        let shared = shared_with_host("files.pythonhosted.org", FILES_V4);
        let policy = allow_rule(Destination::DomainSuffix(
            ".pythonhosted.org".parse().unwrap(),
        ));
        assert!(egress_tcp(&policy, FILES_V4, &shared).is_allow());
    }

    #[test]
    fn suffix_rules_normalize_user_input() {
        let shared = shared_with_host("files.pythonhosted.org", FILES_V4);
        let policy = allow_rule(Destination::DomainSuffix(
            ".PythonHosted.Org.".parse().unwrap(),
        ));
        assert!(egress_tcp(&policy, FILES_V4, &shared).is_allow());
    }

    #[test]
    fn unresolved_domain_rules_do_not_match_by_ip_alone() {
        let shared = SharedState::new(4);
        let policy = allow_rule(Destination::Domain("pypi.org".parse().unwrap()));
        assert!(egress_tcp(&policy, PYPI_V4, &shared).is_deny());
    }

    #[test]
    fn exact_domain_rules_match_resolved_hostnames_for_icmp() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = allow_rule(Destination::Domain("pypi.org".parse().unwrap()));
        assert!(
            policy
                .evaluate_egress_ip(ip(PYPI_V4), Protocol::Icmpv4, &shared)
                .is_allow()
        );
    }

    #[test]
    fn deserialized_policies_normalize_domain_values() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy: NetworkPolicy = serde_json::from_str(
            r#"{
                "default_egress": "deny",
                "default_ingress": "allow",
                "rules": [
                    {
                        "direction": "egress",
                        "destination": { "domain": "PyPI.Org." },
                        "action": "allow"
                    }
                ]
            }"#,
        )
        .unwrap();
        assert!(egress_tcp(&policy, PYPI_V4, &shared).is_allow());
    }

    /// Default-deny policy with explicit allow rules for multiple
    /// hostnames on TCP/443. Both hostnames resolve via DNS first,
    /// populating the cache, and the subsequent connects must be
    /// allowed through the Domain rules.
    #[test]
    fn default_deny_allows_multiple_domain_rules_after_dns() {
        let shared = SharedState::new(4);
        cache(&shared, "pypi.org", ResolvedHostnameFamily::Ipv4, PYPI_V4);
        cache(
            &shared,
            "files.pythonhosted.org",
            ResolvedHostnameFamily::Ipv4,
            FILES_V4,
        );

        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![
                allow_domain_tcp_443("pypi.org"),
                allow_domain_tcp_443("files.pythonhosted.org"),
            ],
        };

        assert!(
            policy
                .evaluate_egress(sock(PYPI_V4, 443), Protocol::Tcp, &shared)
                .is_allow(),
            "pypi.org:443 should be allowed after DNS resolution"
        );
        assert!(
            policy
                .evaluate_egress(sock(FILES_V4, 443), Protocol::Tcp, &shared)
                .is_allow(),
            "files.pythonhosted.org:443 should be allowed after DNS resolution"
        );
    }

    /// Cache has `pypi.org` -> IP, but the policy only allows
    /// `example.com`. A connection to `pypi.org`'s IP must not be
    /// allowed through the unrelated rule.
    #[test]
    fn domain_rule_does_not_match_other_cached_hostnames() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = allow_rule(Destination::Domain("example.com".parse().unwrap()));
        assert!(egress_tcp(&policy, PYPI_V4, &shared).is_deny());
    }

    /// A suffix `.pythonhosted.org` must also match the apex domain
    /// `pythonhosted.org` itself (a common source of confusion with
    /// naive suffix matching that checks only `.ends_with`).
    #[test]
    fn suffix_rule_matches_apex_domain_itself() {
        let shared = shared_with_host("pythonhosted.org", FILES_V4);
        let policy = allow_rule(Destination::DomainSuffix(
            ".pythonhosted.org".parse().unwrap(),
        ));
        assert!(egress_tcp(&policy, FILES_V4, &shared).is_allow());
    }

    /// `.pythonhosted.org` must not match `evilpythonhosted.org`: a
    /// naive `ends_with` check would pass, but the label-boundary
    /// guard (dot before the suffix) must reject it.
    #[test]
    fn suffix_rule_does_not_false_match_adjacent_domain() {
        let shared = shared_with_host("evilpythonhosted.org", FILES_V4);
        let policy = allow_rule(Destination::DomainSuffix(
            ".pythonhosted.org".parse().unwrap(),
        ));
        assert!(egress_tcp(&policy, FILES_V4, &shared).is_deny());
    }

    /// Shared-IP mitigation via rule ordering: a specific allow-Domain
    /// rule listed before a broad deny-Cidr rule must win under
    /// first-match-wins semantics, even when both would match the
    /// destination.
    #[test]
    fn allow_rule_before_deny_wins_on_shared_ip() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![
                Rule::allow_egress(Destination::Domain("pypi.org".parse().unwrap())),
                Rule {
                    direction: Direction::Egress,
                    destination: Destination::Cidr("151.101.0.0/16".parse().unwrap()),
                    protocols: Vec::new(),
                    ports: Vec::new(),
                    action: Action::Deny,
                },
            ],
        };
        assert!(egress_tcp(&policy, PYPI_V4, &shared).is_allow());
    }

    /// UDP traffic (e.g., QUIC over port 443) must match Domain rules
    /// the same way TCP does, since both go through `evaluate_egress`.
    #[test]
    fn udp_egress_consults_domain_cache() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule {
                direction: Direction::Egress,
                destination: Destination::Domain("pypi.org".parse().unwrap()),
                protocols: vec![Protocol::Udp],
                ports: vec![PortRange::single(443)],
                action: Action::Allow,
            }],
        };
        assert!(
            policy
                .evaluate_egress(sock(PYPI_V4, 443), Protocol::Udp, &shared)
                .is_allow()
        );
    }

    /// Resolving only A (IPv4) must not grant access over IPv6, and
    /// vice versa. The family partition in the cache key guarantees
    /// independent refresh/expiry per address family.
    #[test]
    fn ipv4_and_ipv6_caches_are_independent() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = allow_rule(Destination::Domain("pypi.org".parse().unwrap()));
        assert!(
            egress_tcp(&policy, PYPI_V4, &shared).is_allow(),
            "cached IPv4 address should match"
        );
        assert!(
            egress_tcp(&policy, CLOUDFLARE_V6, &shared).is_deny(),
            "uncached IPv6 address must not match through an IPv4-only cache entry"
        );
    }

    // -- Group::Host -------------------------------------------------------

    #[test]
    fn group_host_matches_gateway_v4() {
        let (shared, gw4, _) = shared_with_gateway();
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::deny_egress(Destination::Group(
                DestinationGroup::Host,
            ))],
        };
        let dst = SocketAddr::new(IpAddr::V4(gw4), 80);
        assert_eq!(
            policy.evaluate_egress(dst, Protocol::Tcp, &shared),
            Action::Deny
        );
    }

    #[test]
    fn group_host_matches_gateway_v6() {
        let (shared, _, gw6) = shared_with_gateway();
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::deny_egress(Destination::Group(
                DestinationGroup::Host,
            ))],
        };
        let dst = SocketAddr::new(IpAddr::V6(gw6), 80);
        assert_eq!(
            policy.evaluate_egress(dst, Protocol::Tcp, &shared),
            Action::Deny
        );
    }

    #[test]
    fn group_host_does_not_match_other_ips() {
        let (shared, _, _) = shared_with_gateway();
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::deny_egress(Destination::Group(
                DestinationGroup::Host,
            ))],
        };
        let dst = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(8, 8, 8, 8)), 80);
        assert_eq!(
            policy.evaluate_egress(dst, Protocol::Tcp, &shared),
            Action::Allow
        );
    }

    #[test]
    fn public_only_preset_denies_host_gateway() {
        let (shared, gw4, gw6) = shared_with_gateway();
        let policy = NetworkPolicy::public_only();

        let v4 = SocketAddr::new(IpAddr::V4(gw4), 80);
        assert_eq!(
            policy.evaluate_egress(v4, Protocol::Tcp, &shared),
            Action::Deny,
            "default policy should deny host via IPv4 gateway"
        );

        let v6 = SocketAddr::new(IpAddr::V6(gw6), 80);
        assert_eq!(
            policy.evaluate_egress(v6, Protocol::Tcp, &shared),
            Action::Deny,
            "default policy should deny host via IPv6 gateway (ULA fd42::/8)"
        );
    }

    #[test]
    fn allow_all_preset_permits_host_gateway() {
        let (shared, gw4, _) = shared_with_gateway();
        let policy = NetworkPolicy::allow_all();
        let v4 = SocketAddr::new(IpAddr::V4(gw4), 80);
        assert_eq!(
            policy.evaluate_egress(v4, Protocol::Tcp, &shared),
            Action::Allow
        );
    }

    #[test]
    fn group_host_allow_overrides_private_deny_when_ordered_first() {
        let (shared, gw4, _) = shared_with_gateway();
        let mut policy = NetworkPolicy::public_only();
        policy.rules.insert(
            0,
            Rule::allow_egress(Destination::Group(DestinationGroup::Host)),
        );

        let v4 = SocketAddr::new(IpAddr::V4(gw4), 80);
        assert_eq!(
            policy.evaluate_egress(v4, Protocol::Tcp, &shared),
            Action::Allow
        );

        let other_private = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(10, 0, 0, 5)), 80);
        assert_eq!(
            policy.evaluate_egress(other_private, Protocol::Tcp, &shared),
            Action::Deny,
            "non-host private destinations should still be blocked"
        );
    }

    /// Ingress default is Allow; empty ingress-applicable rules means
    /// all inbound traffic is permitted (today's unfiltered published-
    /// port behavior).
    #[test]
    fn default_ingress_allows_unfiltered_with_no_rules() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy::default();
        let peer = sock("198.51.100.10", 54321);
        assert!(
            policy
                .evaluate_ingress(peer, 8080, Protocol::Tcp, &shared)
                .is_allow()
        );
    }

    /// Single rule with `direction: Ingress` only fires for ingress
    /// evaluation, never for egress.
    #[test]
    fn ingress_rule_does_not_fire_on_egress() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Deny,
            rules: vec![Rule::allow_ingress(Destination::Group(
                DestinationGroup::Private,
            ))],
        };
        // Egress to a private IP: ingress rule doesn't apply, falls to default_egress = Deny.
        assert!(
            policy
                .evaluate_egress(sock("10.0.0.5", 443), Protocol::Tcp, &shared)
                .is_deny()
        );
        // Ingress from a private peer: rule fires, allowed.
        assert!(
            policy
                .evaluate_ingress(sock("10.0.0.5", 54321), 8080, Protocol::Tcp, &shared)
                .is_allow()
        );
    }

    /// `Direction::Any` rule fires for evaluation in either direction.
    #[test]
    fn any_direction_rule_matches_egress_and_ingress() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::deny_any(Destination::Cidr(
                "1.2.3.4/32".parse().unwrap(),
            ))],
        };
        // Egress to 1.2.3.4: Any rule fires.
        assert!(
            policy
                .evaluate_egress(sock("1.2.3.4", 443), Protocol::Tcp, &shared)
                .is_deny()
        );
        // Ingress from 1.2.3.4: Any rule fires.
        assert!(
            policy
                .evaluate_ingress(sock("1.2.3.4", 54321), 8080, Protocol::Tcp, &shared)
                .is_deny()
        );
        // Egress to a different IP: rule doesn't match, falls to default_egress = Allow.
        assert!(
            policy
                .evaluate_egress(sock("8.8.8.8", 443), Protocol::Tcp, &shared)
                .is_allow()
        );
    }

    /// Wire-format casing: every field name and enum tag must serialize
    /// in snake_case, and the serializer's output must round-trip back to
    /// an equivalent value.
    #[test]
    fn serde_round_trip_uses_snake_case() {
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![
                Rule {
                    direction: Direction::Egress,
                    destination: Destination::Group(DestinationGroup::LinkLocal),
                    protocols: vec![Protocol::Tcp, Protocol::Icmpv4],
                    ports: vec![],
                    action: Action::Allow,
                },
                Rule {
                    direction: Direction::Any,
                    destination: Destination::DomainSuffix(".example.com".parse().unwrap()),
                    protocols: vec![],
                    ports: vec![],
                    action: Action::Deny,
                },
            ],
        };
        let json = serde_json::to_string(&policy).unwrap();

        // Field names: snake_case directly from Rust source (no rename needed).
        assert!(json.contains("\"default_egress\""), "JSON: {json}");
        assert!(json.contains("\"default_ingress\""), "JSON: {json}");
        // Enum tags: snake_case via rename_all on each enum.
        assert!(json.contains("\"egress\""), "JSON: {json}");
        assert!(json.contains("\"any\""), "JSON: {json}");
        assert!(json.contains("\"allow\""), "JSON: {json}");
        assert!(json.contains("\"deny\""), "JSON: {json}");
        assert!(json.contains("\"link_local\""), "JSON: {json}");
        assert!(json.contains("\"domain_suffix\""), "JSON: {json}");
        assert!(json.contains("\"icmpv4\""), "JSON: {json}");
        assert!(json.contains("\"tcp\""), "JSON: {json}");
        // No PascalCase residue.
        assert!(!json.contains("\"Egress\""), "JSON: {json}");
        assert!(!json.contains("\"Allow\""), "JSON: {json}");
        assert!(!json.contains("\"LinkLocal\""), "JSON: {json}");
        assert!(!json.contains("\"DomainSuffix\""), "JSON: {json}");
        // No camelCase residue.
        assert!(!json.contains("\"linkLocal\""), "JSON: {json}");
        assert!(!json.contains("\"domainSuffix\""), "JSON: {json}");
        assert!(!json.contains("\"defaultEgress\""), "JSON: {json}");

        // Round-trip back: must parse and produce a structurally equivalent value.
        let back: NetworkPolicy = serde_json::from_str(&json).unwrap();
        assert_eq!(back.rules.len(), policy.rules.len());
        assert!(matches!(back.default_egress, Action::Deny));
        assert!(matches!(back.default_ingress, Action::Allow));
        assert!(matches!(back.rules[0].direction, Direction::Egress));
        assert!(matches!(back.rules[1].direction, Direction::Any));
    }

    /// Multi-protocol rule: TCP-or-UDP both match.
    #[test]
    fn multi_protocol_rule_matches_any_listed() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule {
                direction: Direction::Egress,
                destination: Destination::Group(DestinationGroup::Public),
                protocols: vec![Protocol::Tcp, Protocol::Udp],
                ports: vec![PortRange::single(443)],
                action: Action::Allow,
            }],
        };
        assert!(
            policy
                .evaluate_egress(sock("8.8.8.8", 443), Protocol::Tcp, &shared)
                .is_allow()
        );
        assert!(
            policy
                .evaluate_egress(sock("8.8.8.8", 443), Protocol::Udp, &shared)
                .is_allow()
        );
        // Different protocol — doesn't match, falls to default_egress.
        assert!(
            policy
                .evaluate_egress(sock("8.8.8.8", 443), Protocol::Icmpv4, &shared)
                .is_deny()
        );
    }

    /// Multi-port rule: 80 OR 443 both match.
    #[test]
    fn multi_port_rule_matches_any_listed() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule {
                direction: Direction::Egress,
                destination: Destination::Group(DestinationGroup::Public),
                protocols: vec![Protocol::Tcp],
                ports: vec![PortRange::single(80), PortRange::single(443)],
                action: Action::Allow,
            }],
        };
        assert!(
            policy
                .evaluate_egress(sock("8.8.8.8", 80), Protocol::Tcp, &shared)
                .is_allow()
        );
        assert!(
            policy
                .evaluate_egress(sock("8.8.8.8", 443), Protocol::Tcp, &shared)
                .is_allow()
        );
        // Different port — doesn't match, falls to default_egress.
        assert!(
            policy
                .evaluate_egress(sock("8.8.8.8", 8080), Protocol::Tcp, &shared)
                .is_deny()
        );
    }

    /// The `Public` group matches IPs that are not in any of the other
    /// categories.
    #[test]
    fn public_group_matches_complement_of_other_categories() {
        let shared = SharedState::new(4);
        let policy = allow_rule(Destination::Group(DestinationGroup::Public));

        // Public IPs (8.8.8.8, an arbitrary non-private routable) are allowed.
        assert!(egress_tcp(&policy, "8.8.8.8", &shared).is_allow());
        // Private IPs are not in Public.
        assert!(egress_tcp(&policy, "10.0.0.5", &shared).is_deny());
        // Loopback is not in Public.
        assert!(egress_tcp(&policy, "127.0.0.1", &shared).is_deny());
        // Metadata is not in Public.
        assert!(egress_tcp(&policy, "169.254.169.254", &shared).is_deny());
    }

    //----------------------------------------------------------------------------------------------
    // dns_query_denied
    //----------------------------------------------------------------------------------------------

    fn deny_domain_policy(dest: Destination) -> NetworkPolicy {
        NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::deny_egress(dest)],
        }
    }

    fn name(s: &str) -> DomainName {
        s.parse().expect("valid domain name")
    }

    #[test]
    fn dns_query_denied_matches_exact_domain() {
        let policy = deny_domain_policy(Destination::Domain(name("evil.com")));
        assert!(policy.dns_query_denied(&name("evil.com")));
        assert!(!policy.dns_query_denied(&name("good.com")));
    }

    #[test]
    fn dns_query_denied_matches_suffix_apex_and_subdomain() {
        let policy = deny_domain_policy(Destination::DomainSuffix(name(".evil.com")));
        assert!(
            policy.dns_query_denied(&name("evil.com")),
            "apex must match"
        );
        assert!(
            policy.dns_query_denied(&name("foo.evil.com")),
            "subdomain must match"
        );
        assert!(
            policy.dns_query_denied(&name("deep.sub.evil.com")),
            "deeper subdomain must match"
        );
    }

    #[test]
    fn dns_query_denied_does_not_match_disjoint_suffix() {
        let policy = deny_domain_policy(Destination::DomainSuffix(name(".evil.com")));
        assert!(!policy.dns_query_denied(&name("notevil.com")));
    }

    #[test]
    fn dns_query_denied_ignores_cidr_group_any_rules() {
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![
                Rule::deny_egress(Destination::Any),
                Rule::deny_egress(Destination::Cidr("10.0.0.0/8".parse().unwrap())),
                Rule::deny_egress(Destination::Group(DestinationGroup::Public)),
            ],
        };
        assert!(!policy.dns_query_denied(&name("anything.example")));
    }

    #[test]
    fn dns_query_denied_first_match_wins_when_allow_precedes_deny() {
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![
                Rule::allow_egress(Destination::Domain(name("evil.com"))),
                Rule::deny_egress(Destination::DomainSuffix(name(".evil.com"))),
            ],
        };
        // Allow rule comes first; DNS resolution must proceed.
        assert!(!policy.dns_query_denied(&name("evil.com")));
        // Deny suffix still catches subdomains the allow rule didn't cover.
        assert!(policy.dns_query_denied(&name("foo.evil.com")));
    }

    #[test]
    fn dns_query_denied_ignores_port_and_protocol_filters() {
        // A narrow rule (only TCP/443) must still refuse DNS — DNS does
        // not carry a destination port.
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule {
                direction: Direction::Egress,
                destination: Destination::Domain(name("evil.com")),
                protocols: vec![Protocol::Tcp],
                ports: vec![PortRange::single(443)],
                action: Action::Deny,
            }],
        };
        assert!(policy.dns_query_denied(&name("evil.com")));
    }

    #[test]
    fn dns_query_denied_ignores_default_egress() {
        // Deny-by-default with no Domain rules: DNS proceeds.
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![],
        };
        assert!(!policy.dns_query_denied(&name("anything.example")));
    }

    #[test]
    fn dns_query_denied_skips_ingress_only_rules() {
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::deny_ingress(Destination::Domain(name("evil.com")))],
        };
        assert!(!policy.dns_query_denied(&name("evil.com")));
    }

    #[test]
    fn dns_query_denied_any_direction_rule_applies() {
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::deny_any(Destination::Domain(name("evil.com")))],
        };
        assert!(policy.dns_query_denied(&name("evil.com")));
    }

    //----------------------------------------------------------------------------------------------
    // evaluate_egress_with_source / HostnameSource
    //----------------------------------------------------------------------------------------------

    /// Cache says IP X corresponds to `evil.com`; policy allows
    /// `pypi.org`; SNI says `pypi.org`. SNI must take precedence over
    /// the cache and the connection must be allowed. (Fixes over-block.)
    #[test]
    fn hostname_source_sni_ignores_dns_cache() {
        let shared = shared_with_host("evil.com", PYPI_V4);
        let policy = allow_rule(Destination::Domain(name("pypi.org")));
        let eval = policy.evaluate_egress_with_source(
            sock(PYPI_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Sni("pypi.org"),
        );
        assert_eq!(eval, EgressEvaluation::Allow);
    }

    /// Cache says IP X corresponds to `pypi.org`; policy allows
    /// `pypi.org`; SNI says `evil.com`. The cache would over-allow,
    /// but SNI is authoritative — connection denied. (Fixes over-allow.)
    #[test]
    fn hostname_source_sni_denies_when_cache_would_allow() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = allow_rule(Destination::Domain(name("pypi.org")));
        let eval = policy.evaluate_egress_with_source(
            sock(PYPI_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Sni("evil.com"),
        );
        assert_eq!(eval, EgressEvaluation::Deny);
    }

    /// Deferred mode: a matching `Domain` rule short-circuits the walk
    /// with `DeferUntilHostname` regardless of the rule's action.
    #[test]
    fn deferred_returns_defer_for_first_matching_domain_rule() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule::allow_egress(Destination::Domain(name("pypi.org")))],
        };
        let eval = policy.evaluate_egress_with_source(
            sock(PYPI_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Deferred,
        );
        assert_eq!(eval, EgressEvaluation::DeferUntilHostname);
    }

    /// An earlier matching IP-layer allow wins before the deferred
    /// Domain rule is reached — SYN proceeds without deferral.
    #[test]
    fn deferred_returns_allow_for_earlier_matching_cidr_allow() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![
                Rule::allow_egress(Destination::Cidr("151.101.0.0/16".parse().unwrap())),
                Rule::allow_egress(Destination::Domain(name("pypi.org"))),
            ],
        };
        let eval = policy.evaluate_egress_with_source(
            sock(PYPI_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Deferred,
        );
        assert_eq!(eval, EgressEvaluation::Allow);
    }

    /// An earlier matching IP-layer deny wins before any Domain rule —
    /// SYN dropped at the IP layer.
    #[test]
    fn deferred_returns_deny_for_earlier_matching_cidr_deny() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![
                Rule::deny_egress(Destination::Cidr("151.101.0.0/16".parse().unwrap())),
                Rule::allow_egress(Destination::Domain(name("pypi.org"))),
            ],
        };
        let eval = policy.evaluate_egress_with_source(
            sock(PYPI_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Deferred,
        );
        assert_eq!(eval, EgressEvaluation::Deny);
    }

    /// Domain rules pruned by the protocol or port filter never match
    /// in `Deferred` mode — they don't trigger deferral, the walk falls
    /// through to whatever comes next (here, the default action).
    #[test]
    fn deferred_skips_domain_rule_pruned_by_protocol_or_port_filter() {
        let shared = SharedState::new(4);
        let policy = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule {
                direction: Direction::Egress,
                destination: Destination::Domain(name("pypi.org")),
                protocols: vec![Protocol::Udp], // wrong protocol
                ports: vec![],
                action: Action::Allow,
            }],
        };
        let eval = policy.evaluate_egress_with_source(
            sock(PYPI_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Deferred,
        );
        assert_eq!(eval, EgressEvaluation::Deny);

        let policy_port = NetworkPolicy {
            default_egress: Action::Deny,
            default_ingress: Action::Allow,
            rules: vec![Rule {
                direction: Direction::Egress,
                destination: Destination::Domain(name("pypi.org")),
                protocols: vec![],
                ports: vec![PortRange::single(80)], // wrong port
                action: Action::Allow,
            }],
        };
        let eval = policy_port.evaluate_egress_with_source(
            sock(PYPI_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Deferred,
        );
        assert_eq!(eval, EgressEvaluation::Deny);
    }

    /// `evaluate_egress_with_source(CacheOnly)` reproduces the exact
    /// behaviour of the back-compat `evaluate_egress` wrapper.
    #[test]
    fn cache_only_source_matches_evaluate_egress_wrapper() {
        let shared = shared_with_host("pypi.org", PYPI_V4);
        let policy = allow_rule(Destination::Domain(name("pypi.org")));
        let dst = sock(PYPI_V4, 443);

        let wrapper = policy.evaluate_egress(dst, Protocol::Tcp, &shared);
        let with_source = policy.evaluate_egress_with_source(
            dst,
            Protocol::Tcp,
            &shared,
            HostnameSource::CacheOnly,
        );
        assert_eq!(wrapper, Action::Allow);
        assert_eq!(with_source, EgressEvaluation::Allow);
    }

    /// `Sni` against a `DomainSuffix` rule: label-aware suffix match
    /// applied directly to the SNI string, no cache consulted.
    #[test]
    fn hostname_source_sni_matches_domain_suffix() {
        let shared = SharedState::new(4); // empty cache
        let policy = allow_rule(Destination::DomainSuffix(name(".pythonhosted.org")));
        let eval = policy.evaluate_egress_with_source(
            sock(FILES_V4, 443),
            Protocol::Tcp,
            &shared,
            HostnameSource::Sni("files.pythonhosted.org"),
        );
        assert_eq!(eval, EgressEvaluation::Allow);
    }

    /// `From<EgressEvaluation> for Action` debug-panics on
    /// `DeferUntilHostname`; in release it falls back to `Deny`. The
    /// debug panic is what makes the wrapper safe.
    #[test]
    #[should_panic(expected = "DeferUntilHostname")]
    fn defer_through_action_conversion_debug_panics() {
        let _: Action = EgressEvaluation::DeferUntilHostname.into();
    }

    //----------------------------------------------------------------------------------------------
    // NetworkPolicy::deny_domains / deny_domain_suffixes (and allow_*)
    //----------------------------------------------------------------------------------------------

    #[test]
    fn deny_domains_prepends_one_rule_per_name() {
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![Rule::allow_egress(Destination::Group(
                DestinationGroup::Public,
            ))],
        };
        let policy = policy
            .deny_domains(["evil.com", "tracker.example"])
            .unwrap();
        assert_eq!(policy.rules.len(), 3);
        // Prepended in input order; existing allow Public moves to the back.
        assert!(matches!(
            &policy.rules[0],
            Rule { action: Action::Deny, destination: Destination::Domain(d), .. }
                if d.as_str() == "evil.com"
        ));
        assert!(matches!(
            &policy.rules[1],
            Rule { action: Action::Deny, destination: Destination::Domain(d), .. }
                if d.as_str() == "tracker.example"
        ));
        assert!(matches!(
            &policy.rules[2].destination,
            Destination::Group(DestinationGroup::Public),
        ));
    }

    /// Prepending matters: appended denies are shadowed by an earlier
    /// `allow Public` rule when the denied domain resolves to a public
    /// IP. Verifies the helper makes the deny actually fire.
    #[test]
    fn deny_domains_outranks_existing_allow_public() {
        let shared = shared_with_host("evil.com", PYPI_V4);
        let policy = NetworkPolicy::default().deny_domains(["evil.com"]).unwrap();
        assert!(egress_tcp(&policy, PYPI_V4, &shared).is_deny());
    }

    #[test]
    fn deny_domain_suffixes_prepends_suffix_rules() {
        let policy = NetworkPolicy {
            default_egress: Action::Allow,
            default_ingress: Action::Allow,
            rules: vec![],
        };
        let policy = policy.deny_domain_suffixes([".evil.com"]).unwrap();
        assert!(matches!(
            &policy.rules[0],
            Rule {
                action: Action::Deny,
                destination: Destination::DomainSuffix(_),
                ..
            }
        ));
    }

    #[test]
    fn allow_domains_and_deny_domains_chain() {
        let policy = NetworkPolicy::default()
            .deny_domains(["evil.com"])
            .unwrap()
            .allow_domains(["pypi.org"])
            .unwrap();
        // Last call prepends, so allow pypi.org comes before deny evil.com.
        assert!(matches!(
            &policy.rules[0],
            Rule { action: Action::Allow, destination: Destination::Domain(d), .. }
                if d.as_str() == "pypi.org"
        ));
        assert!(matches!(
            &policy.rules[1],
            Rule { action: Action::Deny, destination: Destination::Domain(d), .. }
                if d.as_str() == "evil.com"
        ));
    }

    #[test]
    fn deny_domains_invalid_input_returns_error() {
        let result = NetworkPolicy::default().deny_domains(["not a domain!"]);
        assert!(result.is_err());
    }

    #[test]
    fn deny_domains_empty_input_is_noop() {
        let before = NetworkPolicy::default();
        let after = before.clone().deny_domains(Vec::<&str>::new()).unwrap();
        assert_eq!(after.rules.len(), before.rules.len());
    }

    #[test]
    fn singular_domain_helpers_match_plural_one_element_form() {
        let plural = NetworkPolicy::default().deny_domains(["evil.com"]).unwrap();
        let singular = NetworkPolicy::default().deny_domain("evil.com").unwrap();
        assert_eq!(plural.rules.len(), singular.rules.len());
        assert!(matches!(
            (&plural.rules[0], &singular.rules[0]),
            (
                Rule { destination: Destination::Domain(a), .. },
                Rule { destination: Destination::Domain(b), .. },
            ) if a == b
        ));
    }

    #[test]
    fn singular_domain_suffix_helper_chains() {
        let policy = NetworkPolicy::default()
            .deny_domain("evil.com")
            .unwrap()
            .deny_domain_suffix(".tracking.example")
            .unwrap();
        // Last call prepends, so the suffix rule sits at index 0.
        assert!(matches!(
            &policy.rules[0].destination,
            Destination::DomainSuffix(_),
        ));
        assert!(matches!(
            &policy.rules[1].destination,
            Destination::Domain(_),
        ));
    }
}