# 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`](#egresspolicydomains) (`*.`
  prefix wildcards, or [`ANY_PUBLIC_HOST`](#any_public_host) for 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`](#egresspolicy). That flag
  never implies loopback, RFC1918, link-local, or metadata.
- Hop count is capped by [`EgressPolicy::max_redirects`](#egresspolicymax_redirects) (wire
  `maxRedirects`).
- **Python + outbound** workerd guests also receive
  [`PYODIDE_EGRESS_HOSTS`](#pyodide_egress_hosts) in 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`](/docs/internals/crates/bookclerk_plugin_manifest/types/index.md#networkmode) and [`crate::PluginManifest::validate`](/docs/internals/crates/bookclerk_plugin_manifest/types/index.md#pluginmanifestvalidate).

| Item | Kind | Summary |
| --- | --- | --- |
| [`EgressPolicy`](#egresspolicy) | struct | Initial-host allowlist with redirect, TCP, and address-space policy. |
| [`PendingSettingDestination`](#pendingsettingdestination) | struct | A destination a network setting names that awaits the operator's approval (`EgressPolicy::pending_settings`). |
| [`TcpGrant`](#tcpgrant) | struct | One TCP grant in the injected policy (`host` + `ports`). |
| [`host_user_agent`](#host_user_agent) | function | The honest `User-Agent` hosts send for guest requests: `bookclerk/<version> (+https://bookclerk.app)`. |
| [`manifest_needs_python`](#manifest_needs_python) | function | Returns `true` when the manifest declares a Python workerd guest. |
| [`with_python_runtime_hosts`](#with_python_runtime_hosts) | function | Appends `PYODIDE_EGRESS_HOSTS` when `needs_python` and mode is outbound. |
| [`consent_domains_for`](#consent_domains_for) | function | Builds the consent / egress domain list for a manifest. |
| [`normalize_hostname`](#normalize_hostname) | function | Normalizes a hostname with IDNA ToASCII (fail closed). |
| [`normalize_domain_pattern`](#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`](#split_domain_entry) | function | Splits a `domains` allowlist entry into its host pattern and optional port. |
| [`normalize_local_name`](#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`](#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`](#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`](#host_matches) | function | True when an IDNA-normalized request host is covered by an allowlist pattern. |
| [`DEFAULT_MAX_REDIRECTS`](#default_max_redirects) | constant | Default redirect budget injected when building policy from network caps. |
| [`ANY_PUBLIC_HOST`](#any_public_host) | constant | The `domains` entry that grants every public hostname (`"*"`). |
| [`PYODIDE_EGRESS_HOSTS`](#pyodide_egress_hosts) | constant | Hosts Pyodide / Cloudflare Python Workers commonly fetch on first boot (runtime index + micropip). |
| [`HOST_USER_AGENT_URL`](#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`](#fetch_default_ports) | constant | Ports a fetch allowlist entry without an explicit port grants: plain HTTP and HTTPS. |

## Structs

### EgressPolicy

```rust
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

- [`Self::allows_initial`](#egresspolicyallows_initial) — hostname must match [`Self::domains`](#egresspolicydomains) after
  IDNA normalization. IP literals also pass [`Self::allows_ip`](#egresspolicyallows_ip).
- [`Self::allows_redirect`](#egresspolicyallows_redirect) — hop budget plus either the domain allowlist
  or [`Self::allow_undeclared_public_redirects`](#egresspolicy) for **public** targets.
- [`Self::allows_tcp`](#egresspolicyallows_tcp) — host + port must match a TCP grant. Fetch grants
  never imply TCP.
- [`Self::allows_ip`](#egresspolicyallows_ip) — public Internet by default; extra CIDRs are
  explicit. Redirect-to-undeclared-public never implies private ranges.
- [`Self::allows_isolate_tunnel`](#egresspolicyallows_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 (`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`](#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`](#egresspolicyfrom_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`](#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`](#egresspolicykeeps_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`](#egresspolicyallows_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

```rust
pub fn from_network(caps: &NetworkCapabilities) -> Self
```

Builds a policy from network capabilities, normalizing domains.

Invalid allowlist entries cause a fail-closed [`Self::deny`](#egresspolicydeny) policy
(prefer [`Self::try_from_network`](#egresspolicytry_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`](#default_max_redirects). `subrequests` is unset.

#### EgressPolicy::try_from_network

```rust
pub fn try_from_network(caps: &NetworkCapabilities) -> Result<Self, String>
```

Like [`Self::from_network`](#egresspolicyfrom_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

```rust
pub fn from_manifest(manifest: &PluginManifest) -> Self
```

Builds policy from a full plugin manifest.

Appends [`PYODIDE_EGRESS_HOSTS`](#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`](#egresspolicydeny).

##### Arguments

* `manifest` - Validated (or at least deserialized) plugin descriptor.

##### Returns

Egress policy ready for workerd injection or consent materialization.

#### EgressPolicy::try_from_manifest

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

Like [`Self::from_manifest`](#egresspolicyfrom_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

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

Attaches a clamped subrequest budget (typically from
[`crate::WorkerdLimits::effective`](/docs/internals/crates/bookclerk_plugin_manifest/types/index.md#workerdlimitseffective)).

##### Arguments

* `subrequests` - Maximum fetch count for the workerd egress bridge.

##### Returns

`self` with `subrequests` set to `Some(subrequests)`.

#### EgressPolicy::deny

```rust
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

```rust
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

```rust
pub fn effective_user_agent(&self) -> String
```

The agent the host sends: [`Self::user_agent`](#egresspolicy) or [`host_user_agent`](#host_user_agent).

#### EgressPolicy::keeps_own_user_agent

```rust
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`](#egresspolicy) 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

```rust
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`](#egresspolicykeeps_own_user_agent)
allows it for `host`; otherwise [`Self::effective_user_agent`](#egresspolicyeffective_user_agent).

#### EgressPolicy::mode

```rust
pub fn mode(&self) -> NetworkMode
```

Returns the configured [`NetworkMode`](/docs/internals/crates/bookclerk_plugin_manifest/types/index.md#networkmode).

#### EgressPolicy::domains

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

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

#### EgressPolicy::max_redirects

```rust
pub fn max_redirects(&self) -> u32
```

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

#### EgressPolicy::allows_initial

```rust
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`](#normalize_hostname) and matches against [`Self::domains`](#egresspolicydomains).

##### 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

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

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

#### EgressPolicy::allows_ip_for

```rust
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`](#egresspolicyallows_ip), plus one widening: when `host` is a name listed
in [`Self::local_names`](#egresspolicy), a local-network address
([`crate::is_local_network`](/docs/internals/crates/bookclerk_plugin_manifest/address/index.md#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

```rust
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

```rust
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`](#egresspolicy) is set,
in which case only public destinations (plus explicit CIDRs) pass.

#### EgressPolicy::allows_fetch

```rust
pub fn allows_fetch(&self, host: &str, port: u16) -> bool
```

Whether a direct (non-redirect) fetch to `host:port` is permitted.

[`Self::allows_initial`](#egresspolicyallows_initial) plus the port rule: an entry that names a
port grants that port only, and one that names none grants
[`FETCH_DEFAULT_PORTS`](#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

```rust
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`](#egresspolicyallows_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`](#egresspolicy)) is limited to
[`FETCH_DEFAULT_PORTS`](#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

```rust
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`](#egresspolicyallows_fetch)), or a
redirect hop to it ([`Self::allows_redirect_to`](#egresspolicyallows_redirect_to) at hop 0). The
resolved addresses still have to pass [`Self::allows_ip`](#egresspolicyallows_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

```rust
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`](#default_max_redirects).

##### Returns

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

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

### PendingSettingDestination

```rust
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`](#egresspolicy)).

**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

```rust
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

```rust
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

```rust
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

```rust
pub fn with_python_runtime_hosts(
    needs_python: bool,
    mode: NetworkMode,
    base: &[String],
) -> Vec<String>
```

Appends [`PYODIDE_EGRESS_HOSTS`](#pyodide_egress_hosts) when `needs_python` and mode is outbound.

Existing entries that already match a Pyodide host (case-insensitive) are
not duplicated.

#### Arguments

* `needs_python` - Typically from [`manifest_needs_python`](#manifest_needs_python).
* `mode` - Network mode; hosts are only appended for
  [`NetworkMode::Outbound`](/docs/internals/crates/bookclerk_plugin_manifest/types/index.md#networkmode).
* `base` - Already-normalized author allowlist.

#### Returns

A new `Vec` with base domains plus any missing Pyodide hosts.

### consent_domains_for

```rust
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`](#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_domain_pattern).

### normalize_hostname

```rust
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

```rust
pub fn normalize_domain_pattern(pattern: &str) -> Option<String>
```

Normalizes an allowlist pattern (`*.example.com`, exact host, or
[`ANY_PUBLIC_HOST`](#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`](#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`](#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`](#egresspolicydomains), or
`None` on failure.

### split_domain_entry

```rust
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`](#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

```rust
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

```rust
pub fn normalize_local_name(host: &str) -> Option<String>
```

Normalizes a [`EgressPolicy::local_names`](#egresspolicy) 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`](/docs/internals/crates/bookclerk_plugin_manifest/address/index.md#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

```rust
pub fn normalize_tcp_host(host: &str) -> Option<String>
```

Normalizes a TCP grant host: an exact host or `*.` wildcard, never
[`ANY_PUBLIC_HOST`](#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

```rust
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`](#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

```rust
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

```rust
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

```rust
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

```rust
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

```rust
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`](#egresspolicy) domain allowlists when a
workerd guest is Python **and** [`NetworkMode::Outbound`](/docs/internals/crates/bookclerk_plugin_manifest/types/index.md#networkmode). See Cloudflare
Python packages docs. Values:
`cdn.jsdelivr.net`, `pypi.org`, `files.pythonhosted.org`.

### HOST_USER_AGENT_URL

```rust
pub const HOST_USER_AGENT_URL: &str = "https://bookclerk.app";
```

Home page named in [`host_user_agent`](#host_user_agent), so a site operator who sees the
agent in their logs can find out what sent it.

### FETCH_DEFAULT_PORTS

```rust
pub const FETCH_DEFAULT_PORTS: [u16; 2] = _;
```

Ports a fetch allowlist entry without an explicit port grants: plain HTTP
and HTTPS.
