bookclerk_plugin_manifest::egress

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

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:

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.

Structs

EgressPolicy

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.

Matching rules

Fields

  • mode: Network mode (deny or outbound). Wire name: mode.

  • domains: IDNA-normalized initial-request host patterns (*.cdn.example.com or 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 to DEFAULT_MAX_REDIRECTS.

  • subrequests: Max outbound fetch calls (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.subrequests value via Self::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: The User-Agent the host sends on the guest's behalf.

    None means host_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 own User-Agent is kept; see Self::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; see Self::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.

EgressPolicy::from_network

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).

Arguments
  • caps - [capabilities.network] table from the manifest.
Returns

An outbound or deny policy with normalized domains and DEFAULT_MAX_REDIRECTS. subrequests is unset.

EgressPolicy::try_from_network

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.

Arguments
  • caps - [capabilities.network] table from the manifest.
Returns

Policy with deduplicated, IDNA-normalized domain patterns.

Errors

Returns a string describing the first invalid domain pattern.

EgressPolicy::from_manifest

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.

Arguments
  • manifest - Validated (or at least deserialized) plugin descriptor.
Returns

Egress policy ready for workerd injection or consent materialization.

EgressPolicy::try_from_manifest

pub fn try_from_manifest(manifest: &PluginManifest) -> Result<Self, String>

Like Self::from_manifest but fails closed on invalid allowlist entries.

Arguments
  • manifest - Plugin descriptor providing network caps and optional [workerd] limits.
Returns

Policy with Python runtime hosts (when applicable) and clamped subrequest budget when [workerd] is present.

Errors

Returns a string describing the first invalid domain in capabilities.network.domains.

EgressPolicy::with_subrequests

pub fn with_subrequests(self, subrequests: u32) -> Self

Attaches a clamped subrequest budget (typically from crate::WorkerdLimits::effective).

Arguments
  • subrequests - Maximum fetch count for the workerd egress bridge.
Returns

self with subrequests set to Some(subrequests).

EgressPolicy::deny

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.

EgressPolicy::pending_setting_for

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.

Arguments
  • host - The refused host, as the guest asked for it.
  • port - The refused port.

EgressPolicy::effective_user_agent

pub fn effective_user_agent(&self) -> String

The agent the host sends: Self::user_agent or host_user_agent.

EgressPolicy::keeps_own_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.

Arguments
  • host - Request hostname (Unicode or Punycode; trailing dot ok).
Returns

true when the guest's agent may be sent to host.

EgressPolicy::user_agent_for

pub fn user_agent_for(&self, host: &str, requested: Option<&str>) -> String

The User-Agent to put on a request to host.

Arguments
  • host - Request hostname of this hop.
  • requested - The agent the guest set, if any.
Returns

requested when the guest set one and Self::keeps_own_user_agent allows it for host; otherwise Self::effective_user_agent.

EgressPolicy::mode

pub fn mode(&self) -> NetworkMode

Returns the configured NetworkMode.

EgressPolicy::domains

pub fn domains(&self) -> &[String]

Returns the IDNA-normalized domain allowlist (may include Pyodide hosts).

EgressPolicy::max_redirects

pub fn max_redirects(&self) -> u32

Returns the redirect hop budget (maxRedirects on the wire).

EgressPolicy::allows_initial

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.

Arguments
  • host - Request hostname (may include a trailing dot; Unicode or Punycode). Percent-encoded hosts never match.
Returns

true when mode is outbound and the host matches an allowlist entry.

EgressPolicy::allows_ip

pub fn allows_ip(&self, ip: IpAddr) -> bool

True when ip is the public Internet or an explicit CIDR grant.

EgressPolicy::allows_ip_for

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.

Arguments
  • host - The name the connection was asked for (or an IP literal).
  • ip - One resolved address for it.
Returns

true when the address may be dialed for that name.

EgressPolicy::allows_tcp

pub fn allows_tcp(&self, host: &str, port: u16) -> bool

Raw TCP connect to host:port. Fetch domain grants do not apply.

EgressPolicy::allows_redirect

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.

EgressPolicy::allows_fetch

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.

Arguments
  • host - Request hostname or IP literal.
  • port - The request's effective port (the scheme default when the URL names none).
Returns

true when outbound mode allows the fetch.

EgressPolicy::allows_redirect_to

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.

Arguments
  • host - Hop hostname or IP literal.
  • port - The hop's effective port.
  • hop_index - 0-based redirect hop.
Returns

true when outbound mode allows the hop.

EgressPolicy::allows_isolate_tunnel

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.

Arguments
  • host - Tunnel target host from the CONNECT line.
  • port - Tunnel target port from the CONNECT line.
Returns

true when outbound mode admits host:port for a workerd guest.

EgressPolicy::to_policy_json

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.

Returns

CamelCase JSON (mode, domains, maxRedirects, optional subrequests).

Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize

PendingSettingDestination

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

TcpGrant

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

Functions

host_user_agent

pub fn host_user_agent() -> String

The honest User-Agent hosts send for guest requests: bookclerk/<version> (+https://bookclerk.app).

Returns

The agent naming this build's workspace version.

manifest_needs_python

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.

Arguments

  • manifest - Plugin descriptor to inspect.

Returns

true when Pyodide CDN hosts should be merged into consent/egress lists for outbound guests.

with_python_runtime_hosts

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.

Arguments

Returns

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.

Arguments

  • manifest - Plugin descriptor providing network caps and runtime hints.

Returns

Deduplicated, IDNA-normalized host patterns for operator consent UI and materialization.

Errors

Returns a string when any declared domain fails normalize_domain_pattern.

normalize_hostname

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).

Arguments

  • host - Raw request or allowlist hostname.

Returns

ASCII/Punycode hostname, or None when IDNA fails or the input is percent-encoded / empty.

normalize_domain_pattern

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.

Arguments

  • pattern - Author-supplied domain entry from capabilities.network.domains.

Returns

Normalized pattern suitable for storage on EgressPolicy::domains, or None on failure.

split_domain_entry

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.

Arguments

  • entry - A domains entry, normalized or as written.

Returns

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.

Examples

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);

normalize_local_name

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).

Arguments

  • host - The host a setting value names.

Returns

The normalized entry, or None when it is neither.

normalize_tcp_host

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).

Arguments

  • host - Author-supplied capabilities.network.tcp host.

Returns

The normalized pattern, or None when it is invalid or *.

normalize_own_user_agent_host

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.

Arguments

  • host - Author-supplied capabilities.network.own_user_agent host.

Returns

The normalized pattern, or None when it is invalid, *, or would hold a comma.

host_matches

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.

Arguments

  • host - Request hostname to test.
  • pattern - Exact host or *. prefix wildcard pattern.

Returns

true when both normalize successfully and the host is covered by the pattern.

Examples

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"));

Constants

DEFAULT_MAX_REDIRECTS

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.

ANY_PUBLIC_HOST

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.

PYODIDE_EGRESS_HOSTS

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.

HOST_USER_AGENT_URL

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.

FETCH_DEFAULT_PORTS

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