Give sandboxed applications stable names for configured services

[shiju-nv]

User Story

As an OpenShell administrator, I want a sandboxed application to use a stable URL for a service I configured so that neither the application nor its network policy needs to know the service's Docker host address, Kubernetes address, or port on the gateway machine.

Problem Statement

host.openshell.internal means the machine that hosts OpenShell, not one service on that machine. If a tool gateway exposes an MCP endpoint on port 17771, sandbox code currently needs an address such as http://host.openshell.internal:17771. The application and its policy must know where the tool gateway runs. A middleware rule that matches only host.openshell.internal can also match requests for other services on the same machine.

Conceptually, an administrator configures this mapping:

name used by sandbox:  https://tools.svc.openshell.internal:443
actual service:        https://host-tool-gateway.internal:17771

The sandbox policy allows HTTPS access to tools.svc.openshell.internal on port 443, and the application sends requests to https://tools.svc.openshell.internal/mcp. The supervisor checks the policy and then uses the administrator's mapping. The sandbox never receives the actual service address.

Why must the sandbox URL be exact? The URL scheme, hostname, and port are checked together. If policy could use a wildcard hostname or several ports, permission for one service could silently include another protocol, another port, or a service registered later. Exact matching keeps the permission limited to the service the policy author reviewed.

Impact / Why This Matters

Without this feature, every host integration must expose a driver-specific hostname, duplicate proxy configuration, or use a middleware match that covers more of the host than the intended service. Policies are harder to review, and applications need different addresses when the deployment changes.

With this feature, application developers see one stable URL. Policy authors grant that exact URL. Gateway administrators can move the real service without changing sandbox code or policy. Audit logs can show both the URL the sandbox requested and the registered route OpenShell used.

Proposed Design

The route has these externally observable rules:

• The route key combines the sandbox's workspace with one exact origin. The origin contains a normalized ASCII hostname, scheme, and port. A typical origin is https://tools.svc.openshell.internal:443.
• OpenShell claims the complete *.svc.openshell.internal suffix inside each managed sandbox network namespace. Any unmatched name, scheme, port, or unsupported protocol is denied before the sandbox's hosts file, local-network name lookup, a corporate proxy, public DNS, or ordinary network access can resolve it.
• A route belongs to one workspace that cannot change, has a stable route ID, uses one connector, and has one administrator-selected actual service address in each active configuration generation. Separate workspaces may use the same sandbox-visible origin, but one workspace cannot list, change, use, or receive another workspace's route.
• Only a Platform Admin or a Workspace Admin authorized for that workspace can register or change a route. A sandbox policy can permit use of a registered origin, but sandbox code and middleware cannot create a route or change its actual service address.
• Policy checks the normalized sandbox-visible origin, the calling process, and any L7 rules. A reserved route requires one exact hostname and one effective port. Wildcard and multi-port rules for ordinary network access never enable a reserved route.
• The supervisor preserves the request method, path, query, body, and supported upgrade semantics, but none of those fields may change the route ID, connector, upstream scheme, host, port, TLS identity, or credential.
• If the actual service address uses a hostname, the connector resolves it and checks every returned IP address before the route becomes active. OpenShell stores the checked addresses with that configuration generation and connects only to those addresses. It does not let another proxy resolve the hostname again.
• OpenShell activates policy, middleware settings, and routes as one configuration generation. A missing, invalid, deleted, disallowed, or old route is denied without trying another network path. When a new generation removes access, OpenShell closes connections that still use the old generation.
• For HTTPS, the connector verifies the service certificate against the name configured by the administrator. Any connection that carries a reusable credential or trusted sandbox information must authenticate the actual service and protect the data from modification. Headers supplied by sandbox code cannot pretend to be trusted OpenShell headers.
• Errors shown to the sandbox explain the type of failure without exposing the actual service address or credentials. Trusted operator logs record the sandbox, sandbox-visible origin, route ID, connector, configuration version, and result.

The route name and the connection check solve different problems. The route name selects the administrator's record; the connection check proves what OpenShell reached at the record's actual address:

Connection to actual service       Required behavior
HTTPS                              Verify certificate chain and configured name
Authenticated local socket         Verify the operating-system peer
HTTP inside a protected connector  Verify peers; send no reusable secret or trusted data
Plain HTTP over an ordinary network Reject; it proves no service and protects no data
Any required check fails           Deny without trying another address

Acceptance Criteria

• A gateway administrator can register one exact HTTP or HTTPS origin under *.svc.openshell.internal and map it to one actual service address through one connector in each active configuration generation.
• The issue documentation defines workspace, administrator, origin, sandbox-visible service name, actual service address, route, connector, configuration generation, middleware, and L7 policy for readers who are new to OpenShell.
• A registered route grants no access until that sandbox's policy permits the same exact origin.
• A policy entry grants no access when its exact origin has no registered route.
• Exact origin matching prevents an existing route grant from expanding to another scheme, port, or later-registered service.
• Sandbox code, request contents, DNS answers, and middleware cannot choose another actual service address; an administrator moves a service by activating a complete new configuration generation.
• A sandbox can use the registered origin only when its active policy allows the same normalized scheme, hostname, and port.
• Route uniqueness, create/read/update/delete permissions, policy lookup, and the routes sent to a supervisor all include the workspace; identical origins in two workspaces remain isolated.
• Wildcard or multi-port rules for ordinary network access, and wildcard middleware rules, cannot enable or select a reserved route.
• The sandbox never needs the actual service address or host.openshell.internal to use the route.
• OpenShell intercepts the full reserved suffix before consulting the sandbox's hosts file, local DNS, public DNS, or an ordinary proxy. Every unregistered, mismatched, or unsupported request is denied.
• Sandbox-controlled fields, middleware output, redirects, and DNS answers cannot alter the selected route or actual service address.
• When an actual service uses a hostname, OpenShell checks every returned address, stores the allowed addresses with the active configuration generation, and connects only to an unexpired stored address without asking another proxy to resolve the name again.
• OpenShell activates policy, middleware settings, and routes together for each sandbox. Removing or changing access closes keep-alive, WebSocket, SSE, and other connections that still use the old settings.
• HTTPS routes verify the configured service certificate. Every connection that carries a reusable credential or trusted sandbox information authenticates the actual service and protects the data from modification. Sandbox code cannot read route credentials.
• Existing process restrictions and HTTP or MCP request rules can restrict a registered route.
• Trusted administrator logs connect the sandbox's policy decision, exact route configuration version, and connection result without exposing secrets to the sandbox.
• Conformance tests cover canonicalization, namespace collisions, identical names in separate workspaces, wildcard and multi-port policy, scheme and port mismatches, DNS bypass attempts, header and authority smuggling, route reload and revocation races, cross-sandbox isolation, and unsupported protocols.

Alternatives Considered

Continue documenting host.openshell.internal. This still requires applications and policy authors to use the address of the whole gateway host when they intend to name one service.

Use only finer middleware selectors. Typed selectors improve middleware selection, but applications and policy still need a stable sandbox-visible service name. Middleware must not choose the actual service address.

Allow policy or middleware to specify an arbitrary upstream URL. This combines authorization with transport selection and lets a less-trusted surface choose physical destinations.

Allow wildcard reserved origins. A wildcard grant can grow when a later route is registered, so the policy no longer describes a closed set of services that its author explicitly allowed.

Let a route select among several upstreams per request. This makes OpenShell a request router and gives routing inputs more authority than the logical service grant. Operators that need load balancing can bind the route to one upstream load balancer or service-discovery endpoint.

Implement general hostname or path rewriting. That is substantially broader than the required one-to-one service binding and introduces ambiguity around paths, redirects, and request-dependent routing.

Agent Investigation

No response

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request