agentplane/core/

egress.rs

//! Where this plane is permitted to connect.
//!
//! The sensitivity lattice controls *what* may leave; this controls
//! *where it may leave to*. They are different holes. A value can be perfectly
//! within its ceiling and still be posted to a host nobody granted.
//!
//! # The channel this closes
//!
//! An MCP server can advertise new tools at any time, and a model provider's
//! base URL is a string in a config file. Both are places where a *destination*
//! can appear without anybody deciding it should. That is a self-service egress
//! channel: discovery of a new capability quietly becomes permission to reach a
//! new host.
//!
//! So destinations are **granted, not discovered**. Discovering that a tool
//! exists stays fine; reaching a host nobody listed does not.
//!
//! # Deny by default, once configured
//!
//! An [`Egress`] permits nothing until told otherwise, which is the only default
//! that fails safe. But the *seam* is optional in exactly the way the policy
//! engine is: a runtime with no egress policy has none, and that is spelled
//! `None` rather than as a permissive allowlist. There is deliberately no
//! `Egress::allow_all()`, for the reason `core::policy` gives for having no
//! `AllowAll` — a deployment that wants no control should have to say so by
//! configuring nothing, not by configuring something that looks like a control
//! and is not.
//!
//! # Which drivers ask
//!
//! The HTTP model drivers do — Anthropic, `OpenAI`, `Gemini` and the
//! `OpenAI`-compatible one — each refusing an ungranted base URL before a request
//! is built, so nothing leaves and nothing is metered. Governed media fetches
//! and push webhooks ask their own, stricter question, in
//! [`netguard`](crate::netguard).
//!
//! **Bedrock does not**, and the exception is named here rather than left for a
//! reader to infer from a missing method. That driver is handed a built AWS
//! client whose endpoint the SDK will not disclose, so the only host this type
//! could be shown is one derived from the region — which an endpoint override
//! makes a fiction. Its own documentation states what stands in place of a
//! check. Any *new* driver reaching a host over HTTP is expected to take an
//! [`Egress`]; a driver that cannot must say so where it is built, because an
//! uncovered surface that says it is uncovered gets revisited and one that says
//! nothing does not.
//!
//! # Host, not URL
//!
//! Matching is on the **host**, and this type never parses a URL. URL parsing is
//! where allowlists are broken: `https://evil.example/#@allowed.example` and its
//! many cousins read one way to a careless splitter and another to a real
//! parser. The callers here already link a correct parser, so they hand over a
//! parsed host and this type does set membership on it.

use std::collections::BTreeSet;

/// The hosts this plane may connect to.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Egress {
    hosts: BTreeSet<String>,
}

impl Egress {
    /// An allowlist that permits nothing.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Grant one host.
    ///
    /// Hosts are compared case-insensitively, because DNS is, and an allowlist
    /// that can be bypassed by capitalising a letter is not one.
    #[must_use]
    pub fn allow(mut self, host: impl AsRef<str>) -> Self {
        self.hosts.insert(host.as_ref().to_ascii_lowercase());
        self
    }

    #[must_use]
    pub fn len(&self) -> usize {
        self.hosts.len()
    }

    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.hosts.is_empty()
    }

    /// Every granted host, in a stable order.
    pub fn hosts(&self) -> impl Iterator<Item = &str> {
        self.hosts.iter().map(String::as_str)
    }

    /// Whether a connection to `host` is permitted.
    ///
    /// No wildcards, and that is deliberate. `*.example.com` reads as a
    /// convenience and is a grant of every host anybody can register under a
    /// domain — including one an attacker controls the moment a subdomain is
    /// dangling. A deployment that genuinely needs many hosts lists them.
    ///
    /// # Errors
    ///
    /// [`EgressError::NotGranted`], naming the host, so an operator reading the
    /// journal can see what was attempted rather than only that something was.
    pub fn permits(&self, host: Option<&str>) -> Result<(), EgressError> {
        // A destination with no host — a relative URL, a unix socket, a
        // malformed string — cannot be checked against an allowlist, and
        // "cannot be checked" resolves to "not permitted".
        let Some(host) = host else {
            return Err(EgressError::NoHost);
        };
        if self.hosts.contains(&host.to_ascii_lowercase()) {
            return Ok(());
        }
        Err(EgressError::NotGranted {
            host: host.to_owned(),
        })
    }
}

/// Why a connection was refused before it was made.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum EgressError {
    #[error(
        "'{host}' is not a granted destination; a host reachable without being \
         listed is a self-service egress channel"
    )]
    NotGranted { host: String },

    #[error("the destination has no host, so it cannot be checked against the allowlist")]
    NoHost,
}

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

    #[test]
    fn a_fresh_allowlist_permits_nothing() {
        let e = Egress::new();
        assert!(e.permits(Some("api.anthropic.com")).is_err());
        assert!(e.is_empty());
    }

    #[test]
    fn a_granted_host_is_permitted() {
        let e = Egress::new().allow("api.anthropic.com");
        assert!(e.permits(Some("api.anthropic.com")).is_ok());
    }

    #[test]
    fn an_ungranted_host_is_refused_and_named() {
        let e = Egress::new().allow("api.anthropic.com");
        let err = e.permits(Some("evil.example")).expect_err("not granted");
        assert_eq!(
            err,
            EgressError::NotGranted {
                host: "evil.example".to_owned()
            }
        );
        assert!(err.to_string().contains("evil.example"));
    }

    /// DNS is case-insensitive; an allowlist that is not can be walked past.
    #[test]
    fn matching_is_case_insensitive() {
        let e = Egress::new().allow("API.Anthropic.COM");
        assert!(e.permits(Some("api.anthropic.com")).is_ok());
        assert!(e.permits(Some("API.ANTHROPIC.COM")).is_ok());
    }

    /// A grant is exactly one host. No wildcards, no suffix matching.
    #[test]
    fn a_grant_does_not_extend_to_subdomains() {
        let e = Egress::new().allow("example.com");
        assert!(e.permits(Some("evil.example.com")).is_err());
        assert!(e.permits(Some("example.com.evil.test")).is_err());
        assert!(
            e.permits(Some("notexample.com")).is_err(),
            "a suffix comparison would have let this through"
        );
    }

    /// Unparseable means unpermitted.
    #[test]
    fn a_destination_with_no_host_is_refused() {
        let e = Egress::new().allow("example.com");
        assert_eq!(e.permits(None), Err(EgressError::NoHost));
    }

    /// **Every refusal is a whole sentence, so no caller has to splice one.**
    ///
    /// This type is wrapped by three error vocabularies — a tool's, a peer
    /// discovery's, a model driver's — and each of them once joined its own
    /// clause to this one and produced something ungrammatical: *…the transport
    /// for server 'ledger' reaches 'evil.example' is not a granted destination*,
    /// and *this client may not connect to ''evil.example' is not a granted
    /// destination…'*. The message an operator reads at 03:00 is the product
    /// this crate ships as much as the refusal is.
    ///
    /// A caller cannot be stopped from splicing by a test here. What can be
    /// pinned is the premise the callers rely on: the sentence stands alone, so
    /// the fix is always to give it its own clause rather than to reword it.
    #[test]
    fn a_refusal_is_a_sentence_that_stands_on_its_own() {
        for e in [
            Egress::new().permits(Some("evil.example")).unwrap_err(),
            Egress::new().permits(None).unwrap_err(),
        ] {
            let text = e.to_string();
            assert!(
                !text.ends_with(' ') && !text.starts_with(' '),
                "a wrapped message must not depend on the caller's spacing: {text:?}"
            );
            // The tell of a fragment: it opens with a verb or a connective, so
            // whatever precedes it has to supply the subject.
            for fragment in ["is ", "was ", "which ", "that ", "and ", "because "] {
                assert!(
                    !text.starts_with(fragment),
                    "the message opens with `{fragment}` and is therefore a \
                     fragment — a caller must splice it into a sentence of its \
                     own to read at all: {text:?}"
                );
            }
        }
    }

    #[test]
    fn grants_are_listable_for_an_operator() {
        let e = Egress::new().allow("b.example").allow("a.example");
        assert_eq!(
            e.hosts().collect::<Vec<_>>(),
            vec!["a.example", "b.example"]
        );
        assert_eq!(e.len(), 2);
    }
}