bookclerk_plugin_manifest::egress
Shared host/egress allowlist policy (workerd JS bridge + native mediator).
Semantics match bookclerk-workerd bridge egress.js and the product rules
in docs/plugins/README.md:
- Initial request hosts must match
EgressPolicy::domains(*.prefix wildcards, orANY_PUBLIC_HOSTfor every public hostname). Hosts and patterns are IDNA ToASCII–normalized; percent-encoded hosts fail closed. - Redirect hops must stay on the fetch allowlist unless the operator
grants
EgressPolicy::allow_undeclared_public_redirects. That flag never implies loopback, RFC1918, link-local, or metadata. - Hop count is capped by
EgressPolicy::max_redirects(wiremaxRedirects). - Python + outbound workerd guests also receive
PYODIDE_EGRESS_HOSTSin consent and egress lists.
Native-behind-workerd guests use the same policy through the inherited
CONNECT mux; ambient AF_INET/AF_INET6 is denied by the sibling jail. See
crate::NetworkMode and crate::PluginManifest::validate.
| Item | Kind | Summary |
|---|---|---|
EgressPolicy |
struct | Initial-host allowlist with redirect, TCP, and address-space policy. |
PendingSettingDestination |
struct | A destination a network setting names that awaits the operator's approval (EgressPolicy::pending_settings). |
TcpGrant |
struct | One TCP grant in the injected policy (host + ports). |
host_user_agent |
function | The honest User-Agent hosts send for guest requests: bookclerk/<version> (+https://bookclerk.app). |
manifest_needs_python |
function | Returns true when the manifest declares a Python workerd guest. |
with_python_runtime_hosts |
function | Appends PYODIDE_EGRESS_HOSTS when needs_python and mode is outbound. |
consent_domains_for |
function | Builds the consent / egress domain list for a manifest. |
normalize_hostname |
function | Normalizes a hostname with IDNA ToASCII (fail closed). |
normalize_domain_pattern |
function | Normalizes an allowlist pattern (*.example.com, exact host, or ANY_PUBLIC_HOST) via IDNA, keeping an optional port. |
split_domain_entry |
function | Splits a domains allowlist entry into its host pattern and optional port. |
normalize_local_name |
function | Normalizes a EgressPolicy::local_names entry: one exact host name (IDNA-normalized, never a wildcard, a port or a restricted name such as localhost) or one local-network IP literal (crate::is_local_network, canonical spelling, IPv4-mapped IPv6 unwrapped). |
normalize_tcp_host |
function | Normalizes a TCP grant host: an exact host or *. wildcard, never ANY_PUBLIC_HOST (raw sockets are granted host by host). |
normalize_own_user_agent_host |
function | Normalizes a host that may keep a guest's own User-Agent: a normalize_tcp_host pattern with no comma once normalized. |
host_matches |
function | True when an IDNA-normalized request host is covered by an allowlist pattern. |
DEFAULT_MAX_REDIRECTS |
constant | Default redirect budget injected when building policy from network caps. |
ANY_PUBLIC_HOST |
constant | The domains entry that grants every public hostname ("*"). |
PYODIDE_EGRESS_HOSTS |
constant | Hosts Pyodide / Cloudflare Python Workers commonly fetch on first boot (runtime index + micropip). |
HOST_USER_AGENT_URL |
constant | Home page named in host_user_agent, so a site operator who sees the agent in their logs can find out what sent it. |
FETCH_DEFAULT_PORTS |
constant | Ports a fetch allowlist entry without an explicit port grants: plain HTTP and HTTPS. |
pub struct EgressPolicy {
pub mode: NetworkMode,
pub domains: Vec<String>,
pub max_redirects: u32,
pub subrequests: Option<u32>,
pub allow_undeclared_public_redirects: bool,
pub tcp: Vec<TcpGrant>,
pub address_cidrs: Vec<String>,
pub user_agent: Option<String>,
pub own_user_agent_hosts: Vec<String>,
pub local_names: Vec<String>,
pub pending_settings: Vec<PendingSettingDestination>,
}
Initial-host allowlist with redirect, TCP, and address-space policy.
Serialized as camelCase for injection into workerd EGRESS_POLICY.
Self::allows_initial— hostname must matchSelf::domainsafter IDNA normalization. IP literals also passSelf::allows_ip.Self::allows_redirect— hop budget plus either the domain allowlist orSelf::allow_undeclared_public_redirectsfor public targets.Self::allows_tcp— host + port must match a TCP grant. Fetch grants never imply TCP.Self::allows_ip— public Internet by default; extra CIDRs are explicit. Redirect-to-undeclared-public never implies private ranges.Self::allows_isolate_tunnel— the host's backstop for a workerd guest's tunnels: the union of the TCP, fetch and redirect rules.
Fields
-
mode: Network mode (denyoroutbound). Wire name:mode. -
domains: IDNA-normalized initial-request host patterns (*.cdn.example.comor exact hosts). Empty when mode is deny. Wire name:domains. -
max_redirects: Maximum redirect hops after an allowed initial request (0-based hop index must be< max_redirects). Wire name:maxRedirects. Defaults toDEFAULT_MAX_REDIRECTS. -
subrequests: Max outboundfetchcalls (initial request plus redirect hops that actually fetch).When present and finite, the workerd egress bridge enforces this counter per egress invocation. Absent means unlimited (tests / native mediator). Workerd guests always inject the clamped
[workerd].limits.subrequestsvalue viaSelf::from_manifest. Wire name:subrequests. -
allow_undeclared_public_redirects: When true, redirect hops may target undeclared public hosts.Private / loopback / link-local / metadata destinations still require an address-space grant.
-
tcp: Raw TCP grants (connect). Fetch allowlists do not imply these. -
address_cidrs: Explicit CIDR grants beyond the public Internet. -
user_agent: TheUser-Agentthe host sends on the guest's behalf.Nonemeanshost_user_agent(this build's version). Hosts set it when they inject the policy so every hop names the same build. Wire name:userAgent. -
own_user_agent_hosts: Approved hosts (exact or*.wildcard, never*) where the guest's ownUser-Agentis kept; seeSelf::keeps_own_user_agent. Wire name:ownUserAgentHosts. -
local_names: Host names that may resolve to a local-network address ([crate::is_local_network]: RFC 1918, shared CGNAT space, IPv6 ULA) without a CIDR grant; seeSelf::allows_ip_for.Each entry is one exact, IDNA-normalized host name (no wildcard, no port) or one local-network IP literal, which then grants a connection to exactly that address. The binding is to the entry: another name that resolves to the same address gains nothing. The host fills this from approved settings whose value names a host (a server address on the operator's LAN). Loopback and link-local addresses still need an explicit CIDR. Wire name:
localNames. -
pending_settings: Destinations that network settings name but the operator has not approved yet. They grant nothing: a refused connection to one says which setting names it (network_not_granted), so the operator knows what to approve. Wire name:pendingSettings.
pub fn from_network(caps: &NetworkCapabilities) -> Self
Builds a policy from network capabilities, normalizing domains.
Invalid allowlist entries cause a fail-closed Self::deny policy
(prefer Self::try_from_network when you need the error).
caps-[capabilities.network]table from the manifest.
An outbound or deny policy with normalized domains and
DEFAULT_MAX_REDIRECTS. subrequests is unset.
pub fn try_from_network(caps: &NetworkCapabilities) -> Result<Self, String>
Like Self::from_network but returns an error when any allowlist
entry fails IDNA / percent-encoding checks.
caps-[capabilities.network]table from the manifest.
Policy with deduplicated, IDNA-normalized domain patterns.
Returns a string describing the first invalid domain pattern.
pub fn from_manifest(manifest: &PluginManifest) -> Self
Builds policy from a full plugin manifest.
Appends PYODIDE_EGRESS_HOSTS for Python + outbound workerd guests
and sets subrequests from clamped [workerd].limits when present.
Invalid allowlist entries fail closed to Self::deny.
manifest- Validated (or at least deserialized) plugin descriptor.
Egress policy ready for workerd injection or consent materialization.
pub fn try_from_manifest(manifest: &PluginManifest) -> Result<Self, String>
Like Self::from_manifest but fails closed on invalid allowlist entries.
manifest- Plugin descriptor providing network caps and optional[workerd]limits.
Policy with Python runtime hosts (when applicable) and clamped
subrequest budget when [workerd] is present.
Returns a string describing the first invalid domain in
capabilities.network.domains.
pub fn with_subrequests(self, subrequests: u32) -> Self
Attaches a clamped subrequest budget (typically from
crate::WorkerdLimits::effective).
subrequests- Maximum fetch count for the workerd egress bridge.
self with subrequests set to Some(subrequests).
pub fn deny() -> Self
Returns a deny-all policy (no domains, default redirect budget, no subrequest cap).
Used when allowlist normalization fails (from_* helpers) or when
network mode is deny.
pub fn pending_setting_for(
&self,
host: &str,
port: u16,
) -> Option<&PendingSettingDestination>
The pending network setting whose destination is host:port, for a
refusal that names it.
host- The refused host, as the guest asked for it.port- The refused port.
pub fn effective_user_agent(&self) -> String
The agent the host sends: Self::user_agent or host_user_agent.
pub fn keeps_own_user_agent(&self, host: &str) -> bool
Whether a request to host keeps the guest's own User-Agent.
True only when host normalizes and matches an approved
Self::own_user_agent_hosts pattern. A * entry (however it is
spelled) never matches, so a tampered policy cannot exempt every host.
host- Request hostname (Unicode or Punycode; trailing dot ok).
true when the guest's agent may be sent to host.
pub fn user_agent_for(&self, host: &str, requested: Option<&str>) -> String
The User-Agent to put on a request to host.
host- Request hostname of this hop.requested- The agent the guest set, if any.
requested when the guest set one and Self::keeps_own_user_agent
allows it for host; otherwise Self::effective_user_agent.
pub fn mode(&self) -> NetworkMode
Returns the configured NetworkMode.
pub fn domains(&self) -> &[String]
Returns the IDNA-normalized domain allowlist (may include Pyodide hosts).
pub fn max_redirects(&self) -> u32
Returns the redirect hop budget (maxRedirects on the wire).
pub fn allows_initial(&self, host: &str) -> bool
Returns whether a direct (non-redirect) request host is permitted.
Deny mode always returns false. Outbound mode normalizes host via
normalize_hostname and matches against Self::domains.
host- Request hostname (may include a trailing dot; Unicode or Punycode). Percent-encoded hosts never match.
true when mode is outbound and the host matches an allowlist entry.
pub fn allows_ip(&self, ip: IpAddr) -> bool
True when ip is the public Internet or an explicit CIDR grant.
pub fn allows_ip_for(&self, host: &str, ip: IpAddr) -> bool
True when a connection to host may use the resolved address ip.
Self::allows_ip, plus one widening: when host is a name listed
in Self::local_names, a local-network address
(crate::is_local_network) is allowed too, so a setting that names
a LAN server by host name works when local DNS answers with a private
address. Loopback, link-local and other special addresses are never
widened this way.
Callers resolve host once, check every address with this method and
dial only an address that passed, so a later DNS answer cannot swap
in another address.
host- The name the connection was asked for (or an IP literal).ip- One resolved address for it.
true when the address may be dialed for that name.
pub fn allows_tcp(&self, host: &str, port: u16) -> bool
Raw TCP connect to host:port. Fetch domain grants do not apply.
pub fn allows_redirect(&self, host: &str, hop_index: u32) -> bool
Returns whether a redirect hop is allowed.
Deny mode always returns false. Outbound mode requires
hop_index < max_redirects. The hop host must match the fetch
allowlist unless Self::allow_undeclared_public_redirects is set,
in which case only public destinations (plus explicit CIDRs) pass.
pub fn allows_fetch(&self, host: &str, port: u16) -> bool
Whether a direct (non-redirect) fetch to host:port is permitted.
Self::allows_initial plus the port rule: an entry that names a
port grants that port only, and one that names none grants
FETCH_DEFAULT_PORTS.
host- Request hostname or IP literal.port- The request's effective port (the scheme default when the URL names none).
true when outbound mode allows the fetch.
pub fn allows_redirect_to(&self, host: &str, port: u16, hop_index: u32) -> bool
Whether a redirect hop to host:port is permitted.
Self::allows_redirect plus the port rule: a hop to a declared host
needs a port that entry grants; an undeclared public hop
(Self::allow_undeclared_public_redirects) is limited to
FETCH_DEFAULT_PORTS.
host- Hop hostname or IP literal.port- The hop's effective port.hop_index- 0-based redirect hop.
true when outbound mode allows the hop.
pub fn allows_isolate_tunnel(&self, host: &str, port: u16) -> bool
Host-side check for a CONNECT that arrives from a workerd isolate.
A workerd guest's outbound traffic leaves its jail through the host's
CONNECT proxy, one tunnel per fetch() request or connect()
socket. The jail labels nothing the host can trust, so the host can't
tell which call opened a tunnel. It therefore admits the union of what
either call may reach on that port: a TCP grant for host:port, a
fetch entry that grants host:port (Self::allows_fetch), or a
redirect hop to it (Self::allows_redirect_to at hop 0). The
resolved addresses still have to pass Self::allows_ip before the
host dials.
The isolate's own egress worker enforces the narrower per-call rules (the fetch allowlist, each redirect hop, the subrequest budget). This check is the backstop that holds when the isolate does not.
host- Tunnel target host from theCONNECTline.port- Tunnel target port from theCONNECTline.
true when outbound mode admits host:port for a workerd guest.
pub fn to_policy_json(&self) -> Value
Serializes this policy to the JSON value injected as workerd
EGRESS_POLICY (and the native helper wire form).
On unlikely serialize failure, returns a deny-shaped object with
maxRedirects set to DEFAULT_MAX_REDIRECTS.
CamelCase JSON (mode, domains, maxRedirects, optional
subrequests).
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct PendingSettingDestination {
pub setting: String,
pub destination: String,
pub host: String,
pub port: u16,
}
A destination a network setting names that awaits the operator's
approval (EgressPolicy::pending_settings).
Fields
setting: The setting key.destination: The destination as the consent form shows it (https://abs.home.lan:13378,db.home.lan:5432).host: The host: an IDNA-normalized name or canonical IP literal (no brackets).port: The port, 1-65535.
Implements: Clone, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub struct TcpGrant {
pub host: String,
pub ports: Vec<u16>,
}
One TCP grant in the injected policy (host + ports).
Fields
host: Hostname or*.wildcard (IDNA-normalized).ports: Destination ports. Empty is fail-closed.
Implements: Clone, Debug, Deserialize<'de>, Eq, Ord, PartialEq, PartialOrd, Serialize
pub fn host_user_agent() -> String
The honest User-Agent hosts send for guest requests:
bookclerk/<version> (+https://bookclerk.app).
The agent naming this build's workspace version.
pub fn manifest_needs_python(manifest: &PluginManifest) -> bool
Returns true when the manifest declares a Python workerd guest.
Detection matches [PluginManifest::declares_python]: a .py main module
or a [[modules]] row with type = "python" or a .py load-set key
(explicit path, otherwise name). Compatibility
flags are not evidence, so a JS guest cannot pull Pyodide hosts in by
listing python_workers. A .py file that exists only on disk does not
widen this list; materialize must use the same set as consent.
Native runtimes always return false.
manifest- Plugin descriptor to inspect.
true when Pyodide CDN hosts should be merged into consent/egress lists
for outbound guests.
pub fn with_python_runtime_hosts(
needs_python: bool,
mode: NetworkMode,
base: &[String],
) -> Vec<String>
Appends PYODIDE_EGRESS_HOSTS when needs_python and mode is outbound.
Existing entries that already match a Pyodide host (case-insensitive) are not duplicated.
needs_python- Typically frommanifest_needs_python.mode- Network mode; hosts are only appended forNetworkMode::Outbound.base- Already-normalized author allowlist.
A new Vec with base domains plus any missing Pyodide hosts.
pub fn consent_domains_for(manifest: &PluginManifest) -> Result<Vec<String>, String>
Builds the consent / egress domain list for a manifest.
Normalizes capabilities.network.domains via IDNA and appends Pyodide
hosts when manifest_needs_python and mode is outbound.
manifest- Plugin descriptor providing network caps and runtime hints.
Deduplicated, IDNA-normalized host patterns for operator consent UI and materialization.
Returns a string when any declared domain fails
normalize_domain_pattern.
pub fn normalize_hostname(host: &str) -> Option<String>
Normalizes a hostname with IDNA ToASCII (fail closed).
Trims ASCII whitespace and a single trailing dot. Rejects empty strings
and any host containing % (percent-encoding bypass).
host- Raw request or allowlist hostname.
ASCII/Punycode hostname, or None when IDNA fails or the input is
percent-encoded / empty.
pub fn normalize_domain_pattern(pattern: &str) -> Option<String>
Normalizes an allowlist pattern (*.example.com, exact host, or
ANY_PUBLIC_HOST) via IDNA, keeping an optional port.
The *. prefix is preserved; only the suffix is ToASCII-normalized. A bare
* stays ANY_PUBLIC_HOST and never takes a port. An entry may end in
:port (api.example.com:8443, [2001:db8::1]:8080): it then grants
that port only, while an entry without one grants the web ports 80 and
443 (see FETCH_DEFAULT_PORTS). The port must be canonical decimal
(no sign, no leading zero, 1-65535). Percent-encoded patterns and empty
patterns return None.
pattern- Author-supplied domain entry fromcapabilities.network.domains.
Normalized pattern suitable for storage on EgressPolicy::domains, or
None on failure.
pub fn split_domain_entry(entry: &str) -> Option<(&str, Option<u16>)>
Splits a domains allowlist entry into its host pattern and optional
port.
[v6] and [v6]:port carry IPv6 literals; otherwise a final :digits
is the port when the rest holds no other colon (a bare IPv6 literal has
several and no port). An entry with no port grants
FETCH_DEFAULT_PORTS.
entry- Adomainsentry, normalized or as written.
The host pattern (IPv6 without brackets) and the port, or None when a
port is present but not canonical decimal in 1-65535, or a bracket is
unterminated.
use bookclerk_plugin_manifest::split_domain_entry;
assert_eq!(split_domain_entry("abs.example.com:13378"), Some(("abs.example.com", Some(13378))));
assert_eq!(split_domain_entry("[2606:4700::1]:9000"), Some(("2606:4700::1", Some(9000))));
assert_eq!(split_domain_entry("api.example.com"), Some(("api.example.com", None)));
assert_eq!(split_domain_entry("api.example.com:0443"), None);
pub fn normalize_local_name(host: &str) -> Option<String>
Normalizes a EgressPolicy::local_names entry: one exact host name
(IDNA-normalized, never a wildcard, a port or a restricted name such as
localhost) or one local-network IP literal (crate::is_local_network,
canonical spelling, IPv4-mapped IPv6 unwrapped).
host- The host a setting value names.
The normalized entry, or None when it is neither.
pub fn normalize_tcp_host(host: &str) -> Option<String>
Normalizes a TCP grant host: an exact host or *. wildcard, never
ANY_PUBLIC_HOST (raw sockets are granted host by host).
host- Author-suppliedcapabilities.network.tcphost.
The normalized pattern, or None when it is invalid or *.
pub fn normalize_own_user_agent_host(host: &str) -> Option<String>
Normalizes a host that may keep a guest's own User-Agent: a
normalize_tcp_host pattern with no comma once normalized.
The comma check runs on the normalized form because IDNA maps some
Unicode commas (such as U+FF0C) to ,, and native guests receive the
approved hosts as one comma-separated list.
host- Author-suppliedcapabilities.network.own_user_agenthost.
The normalized pattern, or None when it is invalid, *, or would hold a
comma.
pub fn host_matches(host: &str, pattern: &str) -> bool
True when an IDNA-normalized request host is covered by an allowlist pattern.
Both sides are IDNA-normalized first; invalid hosts or patterns never
match. Wildcard patterns (*.cdn.example.com) match the bare suffix and
any subdomain (cdn.example.com, a.cdn.example.com) but not
notcdn.example.com.
host- Request hostname to test.pattern- Exact host or*.prefix wildcard pattern.
true when both normalize successfully and the host is covered by the
pattern.
use bookclerk_plugin_manifest::host_matches;
assert!(host_matches("API.Example.COM", "api.example.com"));
assert!(host_matches("www.cdn.example.com", "*.cdn.example.com"));
assert!(!host_matches("evil.com", "api.example.com"));
pub const DEFAULT_MAX_REDIRECTS: u32 = 10;
Default redirect budget injected when building policy from network caps.
Matches workerd policy injection (maxRedirects = 10). Wire JSON uses
camelCase maxRedirects.
pub const ANY_PUBLIC_HOST: &str = "*";
The domains entry that grants every public hostname ("*").
It matches any hostname but never an IP literal, and never a restricted
name such as localhost without an address grant. The resolved-address
layer still refuses private, loopback, link-local and metadata addresses,
so a public name that resolves to a private address stays unreachable.
It is a fetch grant only: a TCP grant cannot use it.
pub const PYODIDE_EGRESS_HOSTS: &[&str] = _;
Hosts Pyodide / Cloudflare Python Workers commonly fetch on first boot (runtime index + micropip).
Included in consent UI lists and EgressPolicy domain allowlists when a
workerd guest is Python and NetworkMode::Outbound. See Cloudflare
Python packages docs. Values:
cdn.jsdelivr.net, pypi.org, files.pythonhosted.org.
pub const HOST_USER_AGENT_URL: &str = "https://bookclerk.app";
Home page named in host_user_agent, so a site operator who sees the
agent in their logs can find out what sent it.
pub const FETCH_DEFAULT_PORTS: [u16; 2] = _;
Ports a fetch allowlist entry without an explicit port grants: plain HTTP and HTTPS.
Generated from crates/bookclerk-plugin-manifest at main · View as Markdown