Add Envoy as an alternative network proxy backend

[ChrisJBurns]

Summary

Network isolation today starts three auxiliary containers per workload: an egress Squid proxy, an ingress Squid proxy, and a dnsmasq DNS container. The two Squid containers are logically one gateway — splitting them into two processes is an implementation artifact. This PR introduces an Envoy-based backend that consolidates both into a single container, reducing the auxiliary count from 3 to 2.

Selected with TOOLHIVE_NETWORK_PROXY=envoy. Squid remains the default; this is opt-in and experimental.

What changed

• pkg/container/docker/networkproxy.go — new networkProxy interface with SetupProxies(ctx, proxySpec) (proxyResult, error). Extracts proxy concerns out of deployOps so backends are swappable. newNetworkProxy reads TOOLHIVE_NETWORK_PROXY; fails loudly on unknown values.
• pkg/container/docker/squid.go — existing Squid logic re-homed behind a squidProxy backend. No behaviour change on the default path.
• pkg/container/docker/envoy.go — envoyProxy backend. Generates a protobuf-JSON Envoy bootstrap with two listeners (egress forward proxy on :3128, ingress reverse proxy), writes it to a 0600 temp file, and starts a single envoyproxy/envoy-distroless container.
• pkg/container/docker/client.go — wires networkProxy into Client; calls SetupProxies before createMcpContainer so env vars can be injected. Also fixes two pre-existing copy-before-mutate bugs in addEgressEnvVars and generatePortBindings.
• docs/arch/14-envoy-network-proxy.md — architecture doc explaining the design, Squid vs Envoy comparison, and known limitations.

Envoy egress filter chain

HTTP_PROXY → Envoy :3128
  HCM (CONNECT upgrade enabled)
  ├── RBAC DENY  — gateway IP (L3 CIDR) + gateway hostnames (L7 :authority prefix)
  ├── RBAC ALLOW — outbound allowlist from permission profile
  ├── dynamic_forward_proxy
  └── router

CONNECT route matcher is present so HTTPS tunnels through correctly. Gateway deny uses both L3 CIDR (destination_ip) for direct-IP connections and L7 :authority prefix matching for hostname-based connections — covering both plain HTTP and HTTPS CONNECT where the authority includes the port (e.g. host.docker.internal:443).

Type of change

• New feature
• Refactoring

Test plan

• task lint-fix passes
• task test passes for pkg/container/docker/... with -race
• task build passes
• Unit tests for networkProxy interface, newNetworkProxy factory, egress RBAC generation, ingress listener, bootstrap file mode, admin loopback, and the mandatory empty-policy deny-all guard
• Manually tested with TOOLHIVE_NETWORK_PROXY=envoy thv run io.github.stacklok/fetch:
  • External HTTPS (https://example.com) — allowed ✓
  • External HTTP (http://example.com) — allowed ✓
  • Docker bridge gateway IP — denied ✓
  • host.docker.internal — denied ✓
  • gateway.docker.internal — denied ✓

Special notes for reviewers

Squid is unchanged and remains the default. Nothing changes for users who do not set TOOLHIVE_NETWORK_PROXY=envoy.

The Envoy config is hand-rolled protobuf-JSON (typed Go structs). Unit tests validate the Go-level struct shape; Envoy validates the full config at container start. The architecture doc (docs/arch/14-envoy-network-proxy.md) covers known limitations including the tag-pinned image, CONNECT log timing, and the absence of AllowPort translation.

Generated with Claude Code

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.