feat(gateway): add local-domain service routing

[pimlock]

Summary

Adds the first pass of gateway-owned domain routing for sandbox-local HTTP and WebSocket services. This is a draft PR for review and iteration; it includes the working spike implementation plus docs/tests captured so far, but still needs cleanup and E2E validation before it is ready to merge.

Related Issue

Linear: OS-153, OS-163, OS-164

Changes

• Adds ExposeService API plumbing and persisted service_endpoint metadata for named sandbox endpoints.
• Adds openshell service expose <sandbox> <service> --target-port <port> to create browser-facing endpoint URLs.
• Adds host-first gateway routing for <sandbox>--<service>.<cluster>.<suffix> before normal gateway HTTP routes, so sandbox app paths like /auth are preserved.
• Proxies HTTP requests to sandbox-local loopback ports through supervisor target-port relays.
• Adds explicit WebSocket upgrade forwarding for domain-routed services.
• Strips gateway/client auth credentials before forwarding requests into sandbox apps.
• Adds local-domain gateway config, cert SAN/deployment wiring, and docs for service exposure, gateway proxying, and browser certificates.
• Preserves gateway TLS/plaintext and domain routing values during fast deploy.

Missing Pieces / Cleanup Required

• Reconcile the RFC direction with this spike implementation before marking ready for review. The RFC now scopes the main design to local gateways and treats remote gateway access as an appendix.
• Rename or remove remaining local-domain product-facing terminology where the RFC lands on different naming.
• Align domain configuration with the existing gateway additional-domain mechanism instead of keeping special-purpose routing config.
• Add endpoint lifecycle commands and UX: list, delete, status, readiness, and clearer error messages.
• Decide authorization/policy semantics for who can expose an endpoint and who can access it.
• Tighten URL parsing and validation around accepted suffixes, aliases, embedded separators, and custom domains.
• Update docs to match final terminology and remove spike-specific browser certificate guidance if local plaintext/loopback becomes the default local path.
• OCSF logging in all the relevant places.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Targeted checks run during the spike:

• cargo fmt --all
• cargo check -p openshell-bootstrap -p openshell-server -p openshell-cli
• cargo check -p openshell-cli
• helm lint deploy/helm/openshell
• cargo test -p openshell-cli gateway_proxy --lib
• cargo test -p openshell-cli service_url_for_gateway --lib
• cargo test -p openshell-server local_domain --lib
• bash -n tasks/scripts/cluster-deploy-fast.sh

Still required before merge:

• Full mise run pre-commit
• Full mise run test or equivalent CI suite
• E2E coverage for local gateway HTTP routing
• E2E coverage for local gateway WebSocket routing
• E2E coverage for auth header/cookie stripping
• E2E coverage for target-port relay through the sandbox network namespace
• E2E coverage for gateway proxy if remote proxy remains in scope

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

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

[github-actions]

Label test:e2e applied, but pull-request/1101 is at {"messa while the PR head is bb1ef60. A maintainer needs to comment /ok to test bb1ef6055f96af573b821024b6da27a7aec614d7 to refresh the mirror. Once the mirror catches up, re-run Branch E2E Checks from the Actions tab.

[pimlock]

/ok to test bb1ef60