Node Egress Contract

A leaf crate with no kernel under it

crates/protocol/chio-egress-contract has no internal chio-* dependencies and forbids unsafe. Without the reqwest-egress feature it has no I/O dependencies at all: validation and non-DNS enforcement need only serde, thiserror, and url. It knows nothing about capabilities, receipts, or tool manifests. Its only question is whether a target URL, its DNS answers, its redirect chain, and its response size satisfy a declared HttpEgressContract.

That question is Node content by the filing test. crates/kernel/chio-kernel-core/src/evaluate.rs lists what a pure evaluation refuses, and tool dispatch to wrapped servers over async transport is on it. The socket dispatch opens belongs to one OS process, governed by that process’s own configuration. Run two nodes and you get two contracts, each enforced locally, with nothing shared between them.

A delegated child task can carry a signed statement about the egress it intends to take, naming an egressContractId and a deny-private-network constraint, but that artifact is checked against the caller’s own route metadata and never resolved to an HttpEgressContract here: Route Plans states the boundary from the other side.

/// Typed HTTP egress contract that gates outbound HTTP from the remote
/// MCP runtime (most prominently the OAuth introspection endpoint).
/// Production deployments must populate this; absence falls back to
/// substrate fail-closed at dispatch.
pub egress_contract: Option<HttpEgressContract>,

What a contract is

pub struct HttpEgressContract {
    pub tenant_egress_namespace: String,
    pub allowed_schemes: BTreeSet<String>,
    pub allowed_authority_set: BTreeSet<String>,
    pub deny_loopback: bool,
    pub deny_link_local: bool,
    pub deny_ipv6_ula: bool,
    pub max_redirect_chain: u8,
    pub max_response_bytes: u64,
}

validate() checks shape only: a non-empty trimmed namespace, non-empty scheme and authority sets, a nonzero byte ceiling, every scheme in {http, https}, and every authority already canonical. A scheme token outside those two is rejected as InvalidContract carrying invalid HTTP egress scheme "ftp"; expected "http" or "https", so no contract can authorize ws or a custom scheme. An authority entry is rejected for a trailing dot, an embedded /, ?, #, or @, any uppercase byte, a bare trailing colon, a zero-padded port, or an uncompressed IPv6 literal: [2001:0db8::1] must be written [2001:db8::1]. A zero redirect cap is legal and means no redirect is ever followed.

prepare() runs validate() once and returns an immutable PreparedHttpEgressContract snapshot. Mutating the original struct afterward does not reach the snapshot, which prepared_contract_keeps_validated_snapshot_after_raw_mutation pins from both directions: the prepared handle still enforces the original policy, and the mutated raw contract is refused when reused. The convenience methods on the raw type re-run prepare() on every call, so a hot dispatch path should hold the prepared handle.

Address-class denial is two-tier

Every host that parses as an IP literal, and every address a domain resolves to, is sorted into one of five classes by classify_ipv4_address or classify_ipv6_address. Three classes are gated on a contract flag. One is denied whatever the contract says.

The names localhost and localhost.localdomain are not classified; enforce_loopback_hostname matches them directly and raises the same LoopbackDenied under the same flag. IPv4-mapped IPv6 is decoded before classification, in both directions, so [::ffff:10.0.0.5] is reported as 10.0.0.5 and denied. That is the only embedding the classifier unwraps.

Two consequences are worth reading twice. First, an allow-listed authority does not buy a private address: private_ipv4_literal_fails_closed_even_when_declared allow-lists 10.0.0.5 and still gets PrivateNetworkDenied. Second, the cloud metadata endpoint 169.254.169.254 is link-local, not private, so it is denied by a flag rather than unconditionally. Every constructor in the tree sets deny_link_local: true, but a hand-written contract clearing the flag and allow-listing that authority would be admitted. Which flags come off where is set out below.

The order of refusals

enforce_url denies on the first violation, in this order. The redirect ceiling is checked before the URL is even parsed.

Step 5 is weaker than it looks for a domain-name host: nothing has resolved yet, so the only name check available is the literal loopback pair. Step 6 carries the load for names, as exact set membership over normalized authorities, not a glob and not a suffix match. api.example.com.evil.test is AuthorityDenied against an allowlist holding api.example.com. The one equivalence granted is the scheme’s default port, in both directions: https://api.example.com:443/v1 matches a no-port entry, and https://api.example.com/v1 matches an api.example.com:443 entry.

enforce_url_with_dns runs all six, then resolves domain-name hosts through ToSocketAddrs and applies the address-class check to every returned address. A resolver returning nothing is DnsResolutionFailed, not a pass; a URL with neither an explicit port nor a known default port is InvalidUrl before the lookup is attempted. This is the only path in lib.rs that protects a domain name pointed at a private address. enforce_url and enforce_attempt alone do not resolve.

Dispatch under the reqwest feature

The client is not the caller’s. client_builder_with_contract builds a reqwest::Client with redirects disabled, proxying disabled, and DNS pinned to a contract-backed resolver, and the returned ContractClientBuilder exposes exactly one knob, .timeout(), so a caller who goes through it cannot re-enable redirect following or swap the resolver back out. A caller who hands send_with_contract a client of their own can, so the helper does not take it on trust: a response URL differing from the request URL returns an error naming the misconfiguration rather than accepting an unvalidated hop.

Each hop costs two DNS lookups for a domain-name host. The enforce_url_with_dns call at the top of the loop resolves through the synchronous std::net::ToSocketAddrs, on the async task, then discards the answers; the pinned resolver resolves the same name again for the connect, and only that second resolution is the one the socket uses.

Redirects are replayed by hand so each hop can be re-authorized. A cross-origin hop carrying a body or a non-idempotent method is refused with a message containing cross-origin redirect method/body denied, asserted for all five redirect statuses against a POST with a body, each test also asserting the forbidden target received no request. There is no dedicated error variant: the denial arrives as HttpEgressError::InvalidUrl, so telling it from a malformed URL means matching on the message. A 307 or 308 that cannot be cloned is an error, not a silent body-less replay. Where the hop is legal, headers are dropped by should_drop_redirect_header:

The byte ceiling is enforced twice: against Content-Length when the response declares one, then against a running counter checked after every chunk. The chunked case is pinned by a test that streams 4 MiB with no Content-Length under a 64 KiB ceiling and asserts the observed count landed under an eighth of the body. What it does buffer is everything up to the ceiling: ContractResponse holds a Vec<u8> and offers no streaming reader, so max_response_bytes is also the per-request memory bound. Read the 64 MiB ceilings below with that in mind.

Three resolvers, two of them pinned

Resolution and enforcement are implemented three times, because three HTTP clients are in the tree. The crate’s ARCHITECTURE.md claims two of them are deliberately kept in sync; the third lives in chio-a2a-adapter, is not covered by that claim, and omits the hostname re-check. Two of the three close the window between the check and the connect by making the resolver that answers the connect the same one that ran the address-class check. The standalone enforce_url_with_dns does not.

chio-link uses enforce_url_with_dns as a config-time admission check and then dispatches through a pinned client. chio-settle goes further: its per-request validate_rpc_egress_contract calls plain enforce_url, on the stated grounds that a config-time lookup would be redundant, offline fragile, and open to TOCTOU drift given the pinned resolver runs anyway. The OpenAPI-to-MCP bridge has no pinned resolver to lean on: it is deliberately transport-agnostic, so invoke_tool validates pre-flight, hands the URL to a caller-supplied dispatcher closure, then refuses any 3xx status and checks the dispatcher’s self-reported observed_body_bytes. If you supply that dispatcher, the socket is yours and so is the rebinding risk.

Where the resolver is pinned, send_with_contract_refuses_loopback_resolving_host_before_connect points an allow-listed hostname at a live loopback server, keeps deny_loopback on, asserts LoopbackDenied, and then asserts the server observed no connection.

What operators actually set

There is no chio.yaml block for an egress contract. Most contracts are derived in code from the endpoint the operator already named, with the ceilings chosen by the caller. The recurring shape is an allowlist holding the configured authorities and nothing else, deny_link_local and deny_ipv6_ula hard-coded true, and a scheme set holding only the configured URL’s own scheme.

That is a sample; the devnet chain-RPC constructors in chio-anchor and chio-settle and the strict-HTTPS anchor contract in chio-control-plane follow the same pattern with their own numbers. Only chio-link carries a poison-pill fallback: fail_closed_default_egress_contract returns an allowlist of invalid.localhost with a zero redirect cap and a one-byte ceiling when no authority could be derived.

Four different ways deny_loopback comes off

deny_link_local is set true by every constructor in the tree, and only two can lower it: the CLI auth contract and the SIEM alert contract, each only when a configured endpoint is itself link-local. deny_loopback is looser, and the four rules are not equivalent.

validate_dispatchable_with_pinned_dns is named as the build-time gate for the pinned-resolver path, confirming every allowed authority is parseable by that resolver. Two things temper it. On the raw type it runs validate() and then repeats a per-authority check validate() already performs, so as the code stands it is equivalent to validate(). And only six crates call it (chio-api-protect, chio-external-guards, chio-anchor, chio-settle, chio-link, chio-control-plane); chio-guard-registry, chio-cli, and chio-siem are reqwest-backed and call plain validate().

Where the missing contract is caught

The crate ships a fail-closed entry point, HttpEgressContract::enforce_required, which turns a None contract into MissingContract. No production caller uses it: each holds its own Option and denies with a message in its own error type. The behaviour is uniform, the wording is not, and the denial lands at different points in the lifecycle.

Three callers avoid the question by typing the field as a plain HttpEgressContract rather than an Option: chio-api-protect’s proxy state, which builds one during proxy construction from the upstream URL, plus PriceOracleConfig and SettlementChainConfig. Read that the other way round when you build a new adapter: the option exists so a contract can be threaded from configuration, not so dispatch can proceed without one.

Guarantees and limits

Next Steps

• Network Guards · the Kernel half: the allowlist and SSRF verdicts computed before dispatch, and why they cannot resolve DNS
• Remote MCP Edge · the startup order that derives the auth contract from the configured identity-provider URLs
• Guard Supply Chain · registry referrer and blob reads under their own contract, and the typed denial they raise
• Fail-Closed Semantics · the pattern this page is one instance of, stated once for the whole kernel
• Node Overview · the rest of what one process owns because the kernel refuses to