Module net_guard 

Network-safety primitives shared across crates that must reject SSRF and local/private targets. Lives in zeroclaw-infra so both the tool layer (zeroclaw-tools domain guard) and its zeroclaw-channels consumers read one implementation.

Everything here operates on plain data — host strings, IP addresses, and pattern lists — so no consumer needs a tool-specific or config-specific type to ask “may this process reach that destination”. DNS resolution is deliberately not part of this module: callers resolve, then hand the resolved addresses here for validation.

The pieces are:

• normalize_domain / normalize_allowed_domains: turn operator-authored allowlist entries into canonical bare hosts.
• host_matches_allowlist: match a request host against those entries.
• normalize_egress_pattern / normalize_egress_patterns / egress_host_matches: the strict, deny-by-default grammar and matcher used by plugin egress policy, where the permissive tool-layer semantics above would be a footgun.
• normalize_host: canonicalize one request host, strictly.
• is_cloud_metadata_ip, is_private_or_local_host, is_non_global_v4, is_non_global_v6: address-class classification.
• Nat64Prefix / parse_nat64_prefixes: the operator-declared, network-specific RFC 6052 NAT64 prefixes deployed on this host’s network.
• validate_resolved_ips_are_public / validate_resolved_ips_exclude_metadata: post-resolution SSRF checks.
• ResolvedDestination / PrivateNetworkAccess / NetworkGuardError: a validated answer set that a caller dials instead of resolving again, with a typed rejection reason.

NAT64 and the validation boundary

The address-class predicates are deliberately prefix-unaware: they know only the address forms that are the same on every network (IPv4-mapped, the deprecated IPv4-compatible form, 6to4, and the RFC 6052 well-known prefix 64:ff9b::/96). A network-specific NAT64 prefix is chosen per deployment and cannot be inferred from an address, so it is supplied by the caller and consulted by the validators, which are the actual egress boundary.

Structs

Nat64Prefix

One operator-declared, network-specific NAT64 prefix.

ResolvedDestination

A normalized host and the exact address set that passed network policy.

Enums

NetworkGuardError

Why a host or its resolved address set is unsafe to dial.

PrivateNetworkAccess

Whether an authorized destination may resolve to private/local addresses.

Functions

egress_host_matches

Strict egress matching: the deny-by-default sibling of host_matches_allowlist.

egress_pattern_contains

Return whether an egress grant contains every destination matched by a carveout pattern.

host_matches_allowlist

True when host matches any entry in a normalized allowed list.

is_cloud_metadata_ip

True when ip is a known cloud instance-metadata service address.

is_known_cloud_metadata_endpoint

True when ip is a provider-documented metadata endpoint, rather than another address in the metadata-sensitive IPv4 link-local range.

is_non_global_v4

True when an IPv4 address is not globally routable (loopback, RFC 1918, link-local, CGNAT, documentation, benchmarking, reserved, multicast).

is_non_global_v6

True when an IPv6 address is not globally routable (loopback, ULA, link-local, site-local, documentation, multicast, unallocated/reserved, or an IPv4-embedded non-global v4).

is_private_or_local_host

True when host is loopback, private, link-local, a documentation/ benchmark range, or one of the localhost / *.local name forms. Accepts bracketed IPv6 ([::1]), ignores DNS root-label dots, and is case-insensitive.

normalize_allowed_domains

Normalize a whole allowlist, sorted and deduplicated.

normalize_domain

Normalize a single allowlist entry to a canonical bare host.

normalize_egress_pattern

Canonicalize one egress allowlist entry, or explain why it is rejected.

normalize_egress_patterns

Validate and canonicalize a whole egress allowlist, sorted and deduplicated.

normalize_host

Normalize a DNS host or IP literal for policy matching and SNI selection.

parse_nat64_prefixes

Parse a whole operator-authored NAT64 prefix list, sorted and deduplicated.

validate_resolved_ips_are_public

Reject a resolution that contains any metadata or non-globally-routable address. This is the default post-resolution SSRF check.

validate_resolved_ips_exclude_metadata

Reject a resolution that contains a known metadata address, but permit other private and loopback addresses. For callers that carry an explicit operator opt-in for private destinations; the known metadata endpoints remain blocked regardless.