feat(supervisor): support policy-controlled upstream host and path rewriting

Problem statement

OpenShell can inspect and transform outbound HTTP requests, enforce protocol-aware policy, and inject credentials, but it does not provide a general way to route an admitted request to a different upstream host or rewrite its URL path.

A common platform pattern exposes services through a controlled reverse proxy, authentication proxy, API gateway, private-access gateway, or protocol adapter. An application should be able to use a stable logical service URL while the platform routes the request through an operator-managed intermediary.

For example:

sandbox request:
  https://service.example/api/items?limit=10

forwarded upstream request:
  https://access-gateway.example/services/service-a/api/items?limit=10

This requires coordinated mutation of the upstream destination, HTTP authority/Host, TLS SNI, and path. Today, implementing this transparently requires an additional CONNECT adapter, TLS-terminating sidecar, custom DNS behavior, or application-specific URL configuration.

Requested capability

Support policy-controlled host and path rewriting for outbound HTTP(S) requests handled by the supervisor.

The exact configuration surface can be decided separately. Viable approaches include:

• Declarative route transformations attached to an endpoint or network policy.
• A constrained supervisor-middleware result that selects an operator-defined upstream route.
• A generalized virtual-endpoint mechanism based on the existing routed-endpoint pattern.

A route should be able to express:

• Original logical host and optional port.
• Upstream scheme, host, and port.
• Path prefix, replacement, or another well-defined path rewrite.
• Whether the original path and query string are preserved.
• The Host/authority and TLS SNI used for the upstream connection.

Example behavior:

# Illustrative only; not a proposed schema.
endpoint:
  host: service.example
  protocol: rest
  route:
    upstream: https://access-gateway.example
    path_prefix: /services/service-a

Security requirements

Routing transformations must remain part of OpenShell's security boundary:

• Evaluate sandbox network and L7 policy against the original logical destination.
• Permit only operator-approved upstream destinations; sandbox-controlled request content must not select an arbitrary host.
• Apply SSRF, DNS, IP-range, port, and TLS validation to the resolved upstream destination.
• Define credential binding explicitly so credentials intended for either the logical service or intermediary cannot be sent to an unintended endpoint.
• Perform credential injection only after routing and middleware transformations have been validated.
• Record both logical and resolved destinations in audit events and traces.
• Re-evaluate redirects so they cannot bypass either logical-service policy or upstream-route constraints.
• Fail closed when a route is missing, invalid, or resolves outside its allowed boundary.

If external middleware participates, a safer contract may be for middleware to return an opaque route identifier that OpenShell resolves through operator-owned configuration, rather than allowing middleware to return an unrestricted URL.

Initial scope

A useful first increment could cover inspected REST traffic over HTTP(S):

• Exact or suffix host matching.
• Upstream host/port replacement.
• Deterministic path-prefix or path-replacement rules.
• Preservation of method, query, body, and approved headers.
• Correct upstream Host/authority, TLS SNI, and certificate verification.
• Non-matching requests retain existing behavior.

Support for WebSocket, GraphQL, MCP/JSON-RPC, signing, and more advanced protocol transformations can follow using the same routing primitive.

Acceptance criteria

• An operator can map a logical HTTP(S) endpoint to a different upstream host and path without changing sandbox application code.
• OpenShell continues to enforce policy against the logical service and validates the physical upstream.
• Requests that do not match a configured transformation are unchanged.
• Provider credentials are not exposed to the sandbox or forwarded to an unintended host.
• Audit output identifies both the requested and resolved destinations.
• Tests cover HTTPS, path/query preservation, credential ordering, redirects, invalid routes, and SSRF rejection.
• Documentation explains the trust boundary and configuration model.

Related work

• #1733 tracks supervisor middleware, whose current contract intentionally protects routing headers and does not expose destination replacement.
• #1633 proposes supervisor-proxied host-local endpoints, but does not provide general external upstream host and path rewriting.
• #133 introduced the specialized routed-endpoint pattern for inference traffic and demonstrates that destination/path rewriting can be enforced inside the supervisor.

This RFE requests the generic routing primitive only; it does not prescribe a broader middleware RFC or a specific deployment architecture.

Start by reading the supervisor routing behavior and the specialized routed-endpoint pattern described in #133, then compare the constraints in #1733 and #1633. Define the operator-controlled route contract before implementation. Done means the acceptance criteria are covered, including HTTPS, path/query preservation, credential ordering, redirects, invalid routes, SSRF rejection, and audit output for logical and resolved destinations.