Node Egress Contract

Contract fields

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,
}

A scheme token outside http and https is InvalidContract carrying invalid HTTP egress scheme "ftp"; expected "http" or "https", so a contract authorizes neither ws nor a custom scheme. An authority entry is refused 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] is written [2001:db8::1].

A signed child-task route can name an egressContractId. That declaration is checked against route metadata, separately from this runtime contract; Route Plans covers it.

Address classes

classify_ipv4_address and classify_ipv6_address sort every address into one class.

enforce_loopback_hostname matches localhost and localhost.localdomain directly. IPv4-mapped IPv6 (::ffff:a.b.c.d) is decoded in both directions and is the one embedding the classifier unwraps; a 6to4, Teredo, NAT64, or IPv4-compatible address classifies by its IPv6 form and passes the class check, including in a DNS answer for an allow-listed hostname. The contract holds no hostname blocklist: metadata.google.internal is refused because the allowlist omits it, and name-based blocking belongs to the internal-network guard.

Dispatch under the reqwest feature

Preflight and connection resolution are separate lookups. enforce_url_with_dns resolves through std::net::ToSocketAddrs, checks the answers, and discards them. When the client connects, its contract-backed resolver performs its own lookup and returns only addresses that pass its checks. The checked preflight answers are not passed through to the socket.

Redirects are replayed by hand so each hop is authorized again. 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 confirming the forbidden target received no request. The refusal arrives as HttpEgressError::InvalidUrl, the variant a malformed URL also returns, with that message. A 307 or 308 whose body cannot be cloned is an error. On a legal hop, should_drop_redirect_header drops headers:

The byte ceiling is checked against a declared Content-Length, then against a running count after every chunk. A test streams 4 MiB with no Content-Length under a 64 KiB ceiling and confirms the observed count stayed under an eighth of the body. ContractResponse holds the body as one Vec<u8> with no streaming reader, so max_response_bytes also bounds the response-body bytes a request retains in memory.

Resolvers

Three HTTP clients in the workspace each resolve and enforce. Two close the check-to-connect window by making the resolver that answers the connect the one that ran the class check.

chio-link runs enforce_url_with_dns as a config-time admission check, then dispatches through a pinned client. chio-settle’s per-request validate_rpc_egress_contract calls plain enforce_url, because a config-time lookup would be redundant with the pinned resolver, fragile offline, and open to drift between check and use. The OpenAPI-to-MCP bridge is transport-agnostic: invoke_tool validates before dispatch, hands the URL to a caller-supplied dispatcher closure, refuses any 3xx status, and checks the dispatcher’s reported observed_body_bytes. A host that supplies the dispatcher owns its socket and the DNS rebinding risk with it.

Contract constructors

No chio.yaml block holds an egress contract. Each client builds its own, with its own ceilings, and nothing aggregates them per node.

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. chio-link alone carries a poison-pill fallback: when no authority can be derived, fail_closed_default_egress_contract returns an allowlist of invalid.localhost with a zero redirect ceiling and a one-byte ceiling.

Loopback and link-local relaxation

Every constructor sets deny_link_local, and two lower it: the CLI auth contract and the SIEM alert contract, each only when a configured endpoint is itself link-local. deny_loopback comes off under four different rules.

validate_dispatchable_with_pinned_dns is the build-time gate for the pinned-resolver path: it confirms every allowed authority parses for that resolver. chio-api-protect, chio-external-guards, chio-anchor, chio-settle, chio-link, and chio-control-plane call it; chio-guard-registry, chio-cli, and chio-siem call plain validate().

Test contracts

HttpEgressContract::permissive_for_tests turns all three class flags off, with a redirect ceiling of 4 and a 64 MiB byte ceiling, so a wiremock or local server on 127.0.0.1 is reachable. Dependent crates need it, so it is public, and its doc comment reserves it for tests. All six SIEM exporters expose a public new_plaintext_for_tests or new_with_base_url_for_tests that substitutes permissive_for_tests when the config carries no contract, where new refuses. Search your own wiring for _for_tests.

Missing-contract refusals

Tested behavior

• private_ipv4_literal_fails_closed_even_when_declared and ipv4_mapped_private_literal_fails_closed_even_when_declared: a private address is refused even when its authority is allow-listed, and a mapped IPv6 literal is reported in its IPv4 form.
• send_with_contract_aborts_oversized_chunked_body_mid_stream: a chunked response with no Content-Length aborts on a bounded prefix.
• crates/tooling/chio-conformance/tests/ssrf_external_guard_api_protect_dispatch.rs: the chio api protect proxy answers 502 with upstream error: link-local egress target denied when an upstream redirects to 169.254.169.254. A sibling test redirects to a second loopback server, which receives no request; the authority allowlist refuses that hop, since the test’s own upstream is loopback and deny_loopback is off.
• threats/ssrf_via_http_substrate.rs and ten ssrf_* negative-conformance files drive LoopbackDenied, LinkLocalDenied, Ipv6UlaDenied, RedirectLimitExceeded, and ResponseTooLarge against the production enforcement functions. Crate unit tests cover PrivateNetworkDenied.
• missing_contract_fails_closed in chio-http-core/tests/http_egress_contract.rs: enforce_required refuses a None contract.