Give sandboxed applications stable names for configured services

Non sono indicati file di implementazione né test. Inizia dalla documentazione dell’architettura e segui la proprietà della configurazione, i controlli di egress, la ricerca delle policy e la distribuzione della configurazione della sandbox per il deployment e il connector supportati. Il lavoro è completato quando vengono soddisfatti i criteri di accettazione documentati, inclusi accesso autorizzato, isolamento, sostituzione del backend, revoca, diagnostica e autenticazione TLS fallita.

User Story

As an operator of a sandbox integration, I want an application and its OpenShell policy to use the same stable HTTPS service name when I move the configured backend, so application authors can depend on the integration while I control its deployment and access.

Problem Statement

Consider a sandboxed application that calls an operator-owned tool gateway at /mcp. Today it can use a reachable address such as https://host.openshell.internal:17771, with policy restricting the hostname, port, calling executable, and supported HTTP operations. That access already works when the service is reachable and correctly configured.

The remaining request is to separate the service identity used by the application and its policy from the backend address owned by the operator. For example:

Application and policy: https://tools.svc.openshell.internal:443
Operator's backend:    tool-gateway Service, HTTPS port 443

An origin means scheme, hostname, and effective port. The example suffix is proposed; it remains unimplemented and its final spelling is open to maintainer direction.

Private DNS, Kubernetes Service DNS, and an existing reverse proxy can already provide stable names in many deployments. This proposal is useful only where operators need the same application-facing and policy-facing service identity across their supported deployment configurations, with the binding enforced at OpenShell's sandbox boundary.

Impact / Why This Matters

An operator using different host ports or service addresses must currently distribute those addresses to application configuration and matching policy, or maintain an external stable-name/proxy arrangement. The proposed workflow moves that deployment-specific association to operator configuration. It does not claim that an existing host-and-port policy grants access to an entire host.

#1633 identifies a related reachability problem: services that must remain bound to loopback. A stable name alone does not solve it. Its CDP/WebSocket report also needs transport and process-attribution work beyond this first scope.

Proposed Design

The requested operator and application workflow is:

1. The operator associates one stable HTTPS origin with one service endpoint in a supported deployment. On Kubernetes, use the existing Service and named port; Kubernetes retains endpoint discovery and traffic distribution. The association grants no sandbox access by itself.
2. The sandbox's policy explicitly grants that exact origin, with the applicable process and HTTP restrictions. A policy grant without an available operator binding also grants no access.
3. The application calls https://tools.svc.openshell.internal/mcp. OpenShell enforces the grant and verifies the backend's configured TLS identity. The accepted request keeps its method, path, query, and body.
4. The operator changes the backend association without changing the application's URL or logical policy grant. Retargeting is a trusted administrative action that must be visible in operator diagnostics; it changes what an existing grant can reach.
5. Removing the binding or grant prevents new requests and terminates affected existing connections within a documented revocation bound. Missing, invalid, expired, or unsupported configuration denies access without falling through to an unrelated DNS/proxy path.

Initial scope is explicit-proxy HTTPS requests, HTTP/1.1, and supported HTTP streaming to one server-authenticated HTTPS endpoint, on an explicitly documented deployment/driver. One origin selects one service endpoint; the existing service platform can manage that endpoint's replicas. Sandbox request fields and middleware cannot select another destination. Workspace authorization and backend TLS identity remain mandatory.

Reuse existing configuration ownership, egress checks, and sandbox configuration delivery. Kubernetes deployments should reuse Kubernetes resources. Non-Kubernetes support should use the deployment's existing operator configuration when implemented. This proposal does not require a separate route database, administrative CRUD service, endpoint inventory, or new discovery protocol. Configuration syntax and the mechanism for associating a name with a service remain implementation decisions.

Host-loopback connectors, WebSockets/CDP, opaque TCP, inference/model routing, route-owned credentials, path rewriting, request-dependent backend selection, and universal driver support are outside the first scope. The selected driver and connector must prove a successful authorized request; reserving a name and denying every request is insufficient completion.

Acceptance Criteria

• An operator can associate an exact HTTPS origin with one existing service endpoint in a documented supported deployment; an authorized sandbox request succeeds.
• Binding and policy grant are separately required. An ungranted origin, absent binding, wrong scheme/port, unsupported protocol, or wildcard-only grant cannot initiate a service connection.
• Applications retain their configured URL and logical policy grant across an operator backend change; diagnostics identify which binding revision served the request.
• Workspace configuration, policy lookup, and sandbox delivery prevent one workspace from using another workspace's binding. Identical logical names in separate workspaces remain independently authorized.
• Process and supported HTTP restrictions still apply. Request data, middleware, redirects, and untrusted name resolution cannot substitute an unauthorized destination or weaken certificate verification.
• Removing access or rejecting a replacement binding blocks new requests and closes affected active streams within the documented bound; unavailable configuration cannot authorize traffic indefinitely.
• OpenShell-generated configuration and errors need not reveal the backend address to the sandbox. This is not a secrecy guarantee against information returned by the backend itself.
• Documentation identifies supported deployment/protocol combinations and demonstrates positive access, denial, backend replacement, revocation, and failed backend authentication. Existing DNS, Service forwarding, and load balancing retain their current owners.

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.

Checklist

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