fix(macos): restore Homebrew sandbox callbacks

[drew]

Summary

Fix macOS Homebrew gateway connectivity for the CLI and Docker Desktop or Podman Machine sandbox callbacks. Homebrew now uses the built-in IPv4 loopback listener, while the gateway reuses any reachable primary listener and creates a callback-only listener only when necessary.

Related Issue

No issue required: localized regression fix for the package-generated macOS gateway configuration.

Changes

• Register the package-managed gateway as https://localhost:17670 and normalize raw IPv6 literals for TLS server-name validation
• Generate Homebrew gateway.toml without an explicit bind_address, preserving the built-in 127.0.0.1:17670 default
• Migrate only the exact legacy IPv6 config generated by the affected formula while preserving user-edited configs
• Reuse the primary gateway listener whenever it covers a compute-driver callback address
• Add a restricted callback-only listener when the primary listener is not reachable from the sandbox topology
• Update listener, Docker, formula, installer, operator, and configuration documentation coverage

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (not run; focused driver, CLI, formula, and installer suites passed)

Additional suites:

• cargo test -p openshell-server gateway_listener_specs_ --lib
• cargo test -p openshell-driver-docker --lib
• cargo test -p openshell-driver-podman --lib
• cargo test -p openshell-cli --lib
• uv run --frozen pytest -q python/openshell/release_formula_test.py
• bash tasks/scripts/test-install-sh.sh

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2739.docs.buildwithfern.com/openshell

[krishicks]

Agent-driven review found the following, emphasis mine. I did not try to reproduce it, though.

P1 — Reusing the primary listener exposes HTTP routes to sandboxes

OpenShell/crates/openshell-server/src/gateway_listener.rs

Lines 156 to 158 in 5445a1a

	if existing.scope == GatewayListenerScope::Primary {
	return;
	}

discards the callback scope whenever the primary listener covers the callback address. Consequently, sandbox-originated connections receive GatewayListenerScope::Primary.

Sandbox JWT authorization protects gRPC methods, but it does not protect the primary HTTP router. That router includes WebSocket, authentication, and unauthenticated sandbox-service proxy routes (http.rs:180-187). A sandbox can therefore set a service-routing Host header and reach another sandbox’s exposed service through the gateway without authorization. Health and reflection also become reachable.

This removes the isolation that callback-only listeners provided. The PR should preserve callback restrictions on sandbox traffic or add equivalent HTTP-route enforcement before reusing the primary socket.

[drew]

Agent-driven review found the following, emphasis mine. I did not try to reproduce it, though.

P1 — Reusing the primary listener exposes HTTP routes to sandboxes

OpenShell/crates/openshell-server/src/gateway_listener.rs

Lines 156 to 158 in 5445a1a

	if existing.scope == GatewayListenerScope::Primary {
	return;
	}

discards the callback scope whenever the primary listener covers the callback address. Consequently, sandbox-originated connections receive GatewayListenerScope::Primary.
Sandbox JWT authorization protects gRPC methods, but it does not protect the primary HTTP router. That router includes WebSocket, authentication, and unauthenticated sandbox-service proxy routes (http.rs:180-187). A sandbox can therefore set a service-routing Host header and reach another sandbox’s exposed service through the gateway without authorization. Health and reflection also become reachable.

This removes the isolation that callback-only listeners provided. The PR should preserve callback restrictions on sandbox traffic or add equivalent HTTP-route enforcement before reusing the primary socket.

Sandboxed workloads still won't be able to access the gateway so I don't think it's valid.