Support native OpenShell policy evaluation with an Envoy-owned HTTP data plane

[DahuK]

User Story

We are evaluating OpenShell's native policies for agent sandboxes in an environment where Envoy must remain responsible for HTTP/TLS processing, routing, and upstream connections.

We want to author and review policies in OpenShell's existing format, and reuse its native evaluation semantics rather than translate them into a separate policy language or maintain a second evaluator in Go. We are prepared to use a trusted workload-side backend for process attribution and isolation; we are not asking an HTTP filter to replace those controls.

The workflow we need is: apply an OpenShell policy, associate it with an authenticated sandbox, and have Envoy enforce decisions produced by OpenShell's native implementation for the supported HTTP traffic.

Problem Statement

OpenShell exposes useful policy and L7 evaluation APIs, but the complete request-processing behavior remains coupled to the supervisor's proxy path. That behavior includes normalization, hard denials, trusted identity/TOFU checks, policy generation, and the ordering of request transformations and credential handling.

It is not clear how an external HTTP data plane can reuse this behavior as a supported integration without either reproducing parts of it or delegating business proxy ownership back to the supervisor. A bare allow/deny call does not describe the transport checks the external data plane must still perform.

Impact / Why This Matters

An independently implemented evaluator can drift on defaults, overlapping rules, path normalization, audit versus hard-deny behavior, or policy updates. Sharing only policy types or Rego text does not eliminate those risks.

Keeping the standard supervisor in the business traffic path is a valid alternative, but it retains proxy and upstream-connection responsibilities that this use case needs Envoy to own. The issue is that ownership split, not simply the cost of running another service.

A supported reuse path could let OpenShell retain one policy implementation while integrators take responsibility for the external transport and its enforcement guarantees.

Proposed Design

We would like to agree on a supported boundary for native policy execution with an external HTTP transport. A shared Rust execution interface, also consumed by the standard supervisor, is one possible approach. We are open to an existing extension point or another shape if it provides the same guarantees.

The intended user workflow is:

1. Author and approve a policy using the existing OpenShell policy model.
2. Select a qualified external HTTP enforcement path through an operator-controlled integration mechanism, whose configuration would be agreed with maintainers.
3. Bind the policy revision and authenticated sandbox context to that path. Do not select authority from workload-supplied headers.
4. Submit HTTP events to the native execution path and apply its decisions and supported transformations. A Rust Envoy ext_proc adapter is one candidate for this integration; the supported interface should be agreed with maintainers.
5. Keep upstream selection, TLS, and application forwarding in Envoy. Required destination, identity, and policy-validity checks must be satisfied before protected bytes are sent.
6. Report policy-load and enforcement failures explicitly; reject unsupported requirements rather than silently approximating them.

An illustrative existing policy for the first integration slice would be:

version: 1
network_policies:
  read_api:
    endpoints:
      - host: api.example.com
        port: 443
        protocol: rest
        enforcement: enforce
        access: read-only
    binaries:
      - path: /usr/bin/curl

This is not new syntax and has not been executed as an Envoy integration. Expected decisions would preserve native identity and ancestor-matching semantics: admitted identities may use the native read-only methods; writes and identities with no matching executable or ancestor are denied.

Trusted sandbox backend -- authenticated connection context --> Envoy
                                                               |
                                                           ext_proc
                                                               |
                                                    Rust native execution

Envoy -- only after required checks --> upstream

Two boundaries need explicit agreement:

• Policy context: how the integration obtains a sandbox-scoped native policy snapshot and related state without starting a competing supervisor session or creating another approval authority.
• Transport obligations: how native decisions express checks that Envoy must perform. ext_proc alone does not prove the actual resolved upstream address or TLS peer. The integration must bind checks to the actual connection attempt, including retries and connection reuse, rather than perform an unrelated DNS lookup.

For an initial slice, bounded REST/HTTP requests would be sufficient. Unsupported upgrades, arbitrary TCP, unbounded streaming, and unsupported middleware/provider requirements should be explicitly rejected. We are not requesting complete protocol parity in the first change, changes to native policy semantics, or relaxation of sandbox confirmation requirements.

Acceptance Criteria

• Existing policy documents can be consumed without rewriting their rules into a second language; unsupported requirements are reported explicitly.
• The standard supervisor retains its behavior, and the integration does not require an independently maintained implementation of the same matching and normalization semantics.
• For a declared HTTP scope, equivalent policy, identity, request, and revision inputs produce equivalent decisions and intended transformations in native and Envoy-backed tests.
• Missing/untrusted identity, malformed input, incomplete required bodies, and stale execution contexts cannot become an implicit allow. Native audit behavior remains distinct from hard-deny behavior.
• Actual upstream address and TLS checks are tied to the connection Envoy uses before application bytes or credentials are released; unmet checks fail closed.
• Policy updates and request cancellation have a documented enforcement contract, including what happens to in-flight requests. Returning a revision identifier alone is not treated as proof of revocation.
• The integration's capabilities, limitations, and required workload-side controls are documented and covered by positive and negative tests.

Alternatives Considered

Alternative	Why it does not directly provide the requested workflow
Supervisor middleware	Lets OpenShell call an external service within its proxy flow. This use case needs Envoy to call native OpenShell execution while retaining HTTP transport ownership.
Gateway interceptors or providers	Address control-plane interception and provider/credential integration, not the complete workload HTTP evaluation path. They may still be useful supporting pieces.
A custom IsolationBackend	Necessary for trusted workload-side enforcement, but does not by itself expose the supervisor's full HTTP evaluation behavior to Envoy.
Chain Envoy with the standard supervisor	Preserves native behavior, but does not provide the required separation of policy execution from business proxy ownership. We would welcome guidance if an existing composition already does.
Reimplement evaluation or translate policies into another engine	Creates a second semantic implementation and ongoing divergence risk.

Related Work and Agent Investigation

The source investigation used commit c4688aa8715ea75d6c39fe468361dbbc16c691fa; current main should be rechecked before implementation.

• OpaEngine::authorize_egress and evaluate_l7_request are public entry points. Surrounding hard-deny handling and supplied-identity validation show why calling a matcher alone is insufficient.
• #3361 and #3366 established backend-neutral confirmation. This proposal builds on that separation; it does not ask to bypass provisioning validation or remove native Linux checks.
• #1738 and #4359 are related middleware and HTTP lifecycle work. They are relevant design inputs, not evidence that Envoy PDP integration is already supported.

No complete native-versus-Envoy integration has been tested in this investigation, and no acceptance criterion above is claimed as completed.

Questions for Maintainers

1. Is this external-HTTP-data-plane use case within the intended extension direction of OpenShell?
2. Can an existing extension satisfy it, or would a shared native execution interface be an appropriate first step?
3. What is the smallest HTTP scope and conformance set you would accept for a prototype, and which existing work should it build on?

If the direction is supported, a next step could be a bounded prototype and a thin Rust adapter with shared tests, rather than a large refactor or a new general-purpose policy service in the first PR.