feat(security): #502 — compile-time URL/host egress allowlist

[proggeramlug]

Closes #502.

Summary

Adds a compile-time HIR pass that gives the host a static guarantee about its binary's outbound network surface. When perry.allowedHosts is set in the host package.json, every literal URL/host in a fetch(...) / net.connect(...) / net.createConnection(...) call must match a pattern in the list — otherwise the build fails before producing a binary.

Zero runtime cost — purely a compile-time HIR walk.

Cross-platform — the gate runs in the platform-agnostic compile_command driver, so every backend (LLVM / WASM / ArkTS / HarmonyOS / Glance / SwiftUI / JS) inherits the protection from one choke point.

Diagnostic example

Error: egress allowlist refused 2 call site(s):
  - /repo/main.ts: fetch → "https://evil.com/leak" (literal host not in `perry.allowedHosts`)
  - /repo/lib/foo.ts: net.connect → "x.evil.com" (literal host not in `perry.allowedHosts`)

`perry.allowedHosts` provides a static guarantee that this binary's
outbound network surface matches the declared list. Refusing the build. (#502)

Options:
- Add the offending host(s) to `perry.allowedHosts` ...
- Set `"*"` in `allowedHosts` to disable host gating ...
- For non-literal URLs, set `perry.allowDynamicHosts: true` ...

All offending sites surface in a single error (better UX than failing on the first one and asking the user to re-run). Capped at 12 entries to keep error output bounded.

Pattern syntax

• Exact host — "api.example.com".
• Subdomain wildcard — "*.cdn.example.com" matches subdomains, not the bare suffix.
• URL prefix — "https://api.acme.com/v1/*" matches path-bearing call sites; does NOT match a bare-host net.connect("api.acme.com") (path-bound entries gate path-bound calls).
• Universal — "*" matches everything (escape hatch).

Opt-in semantics

Empty allowedHosts disables the pass entirely → existing builds compile unchanged. Migration path documented:

1. Run the build once without the allowlist.
2. Inspect .perry-cache/audit.json (perry audit --sbom, security: perry audit — emit behavioral SBOM at compile time #495) to discover what egress your binary currently performs.
3. Populate allowedHosts with the surface you actually use.
4. Re-build. The gate now catches future regressions.

Non-literal URLs / hosts

Variables, expressions, and template strings with substitutions defeat the static guarantee. They're refused by default; set perry.allowDynamicHosts: true to opt in.

Test coverage

13 unit tests in perry-hir::egress::tests:

• empty_allowlist_disables_pass — opt-in invariant.
• host_pattern_exact_match, host_pattern_subdomain_wildcard, universal_escape_hatch — basic shapes.
• url_pattern_extracts_host — handles userinfo + port + path in URLs.
• url_prefix_pattern — path-bound matching.
• url_pattern_doesnt_match_bare_host — net.connect against URL-prefix entries.
• fetch_literal_records_violation / fetch_literal_matching_passes — primary fetch case.
• fetch_dynamic_url_blocked_by_default / fetch_dynamic_url_allowed_when_opted_in — non-literal + allowDynamicHosts.
• net_connect_host_checked / net_connect_no_host_implicit_localhost_allowed — net.connect with and without host.

End-to-end smoke (all four cases verified against the release binary):

• No allowedHosts → no check (legacy behavior preserved).
• allowedHosts set, host NOT in list → fails with the right diagnostic.
• Non-literal URL, no allowDynamicHosts → fails.
• Non-literal URL, allowDynamicHosts: true → compiles cleanly.

Out of scope

• http.get(url) / https.request(...) / WebSocket(url) — lower through the general-shape NativeMethodCall HIR variant (URL extraction is harder). The MVP covers the highest-volume egress shape; follow-up grafts the rest onto the same pass.
• perry audit --sbom literal_hosts integration — security: perry audit — emit behavioral SBOM at compile time #495's manifest is versioned so this is a clean follow-up that adds a new key to ModuleAudit.

Acceptance

• Host package.json perry.allowedHosts: [...] with glob/URL-prefix patterns
• All fetch / net.connect / net.createConnection call sites analyzed (http.get/https.request/WebSocket deferred — see module doc)
• Literal host not in allowlist → build fails at call site with clear message
• Non-literal host → build fails unless perry.allowDynamicHosts: true
• Pattern matching: glob-style host wildcards + URL prefix
• Stronger than runtime allowlists: violations caught before binary exists
• [deferred] perry audit literal_hosts integration — graft as a literal_hosts key in security: perry audit — emit behavioral SBOM at compile time #495's ModuleAudit (follow-up)

Notes

No Cargo.toml version bump, no CLAUDE.md version line touch, no CHANGELOG.md entry — maintainer folds those in at merge time.