feat: pluggable policy sourcing via a Policy Provider subsystem

[dvavili]

Problem Statement

OpenShell sources sandbox policy exactly one way: authored, validated, and composed inside the gateway, then enforced by the supervisor (Landlock/seccomp + proxy/OPA). Policy therefore lives entirely in the gateway's trust domain, with a single built-in implementation and no seam to source it elsewhere.

That can't serve deployments where the policy authority and the gateway are different parties — notably enterprise models needing attestation and independent audit: policy signed by a central authority in a separate trust domain; tamper-evident even against a compromised gateway; independently verifiable by auditors against a signed artifact. The built-in path structurally can't provide this — it sits inside the gateway's own trust domain.

Meanwhile OpenShell already makes compute, credentials, and identity pluggable via a driver model (a type = selector + a gRPC driver, RFC 0001). Policy is the one gateway concern that isn't.

Prior Art

The proposal has two halves — a pluggable seam, and sourcing signed policy from outside the gateway — each grounded in established systems.

Pluggable drivers with a neutral core. A thin, versioned contract at the boundary lets an ecosystem add backends without the core growing backend-specific knowledge:

• HashiCorp Nomad task drivers and Terraform providers — core defines a minimal contract; each backend implements it out-of-process; the core stays agnostic. RFC 0001 cites both as the lineage for OpenShell's own driver model.
• Kubernetes CRI / CSI — the kubelet and control plane talk to runtime and storage plugins over a stable gRPC contract and pass driver-specific config through without interpreting it, so new drivers ship independently of the Kubernetes release cycle.
• OpenShell's own out-of-tree compute driver (#1703, RFC #1344) — the gateway already dispatches to an external compute driver over a Unix socket via --compute-driver-socket. This RFC applies the same out-of-tree-over-socket shape to policy.

Sourcing signed policy from outside the consumer's trust domain. A separate process vending verified, signed policy to a local consumer over a host-local contract, backed by an authority in its own trust domain, mirrors:

• Open Policy Agent (OPA) signed bundles — a central authority signs policy bundles; a co-located OPA verifies the signature before serving decisions, so the consuming service need not trust the bundle's transport.
• SPIFFE/SPIRE — a host-local agent issues workload identities over a local socket, backed by a separate central server. The same split (local contract, separate authority, consumer verifies) is what makes attested policy tamper-evident even against a compromised gateway.

Proposed Design

Add a Policy subsystem following that same driver model:

• local (default) — today's store-backed path, unchanged.
• external — the gateway sources policy from a separate provider process over a gRPC contract (UDS now, network later).

At admission the gateway acquires a per-sandbox handle, fetches a projection (a serialized SandboxPolicy body + digest, optionally signed), verifies the signature against a configured trust store, then relays the body to the supervisor over the existing channel. Everything downstream is unchanged.

One driver per gateway, selected at startup; opt-in and additive (local stays the default).

Use Cases

Scenario	Driver	What it enables
One party owns OpenShell and policy (status quo)	local	Today's behavior — user-authored policy in the gateway, including the RFC 0002 agent-driven loop. Unchanged.
Enterprise with a central policy authority	external (attesting)	Policy signed off-host by a security team in a separate trust domain; tamper-evident against a compromised gateway and independently auditable against the signed artifact.
Fleet of gateways sharing one policy source	external (network transport)	A central provider serves many gateways, so policy is administered once and sourced consistently across the fleet.
Policy-as-code from a git or bundle server	external	A provider process pulls versioned policy from a git repo or bundle server and projects it, without building that integration into the gateway.
Per-tenant / per-user policy	external + runtime-context extensions (tenant_id, …)	The provider returns a different projection per tenant or user, scoped by the runtime context the gateway binds at admission.

Alternatives Considered

• Driver in-process / per-sandbox. Collapses the trust split — a per-sandbox provider sits inside the domain it constrains. external keeps the provider a separate process, like OpenShell's other drivers.
• Do nothing. Fine when one party owns both OpenShell and policy; leaves enterprise deployments trusting the gateway as the policy authority, with no attestation or independent audit.

Compatibility

• Additive and opt-in. local remains the default; a deployment opts in by setting type = "external". Gateways that never configure it behave exactly as today.
• No change downstream. The projection body is the existing openshell.sandbox.v1.SandboxPolicy; the supervisor, proxy, and OPA engine are untouched, so the enforcement path is unchanged.
• Wire-safe. The driver contract is versioned via surface_id / supported_surfaces; the gateway and driver reconcile at startup and fail closed on no overlap rather than enforcing a mismatched schema.
• No data migration. Switching to external changes where policy is sourced, not how it's stored or enforced; switching back to local restores the built-in path with no migration.
• Behavioral change to be explicit about. Under a non-mutating external driver, the runtime policy-mutation surface (openshell policy set/update, global policy delete, and the RFC 0002 agent-driven loop) is refused. This is intended, but it is a visible change for callers that rely on those verbs.

Definition of Done

• A policy subsystem on the gateway with a driver selector, defaulting to today's built-in path.
• An external driver that sources policy from a separate provider process, leaving the built-in local path unchanged and the default.
• The gateway verifies and enforces sourced policy end-to-end: authentic (signature verified against a configured trust store), complete (the whole policy enforced or admission refused), and unaltered (the policy-mutation surface refused when the provider is read-only).
• An in-tree example/null provider so the external path can be exercised end-to-end without a real provider behind it.
• Documentation sufficient for a third party to build a provider against the integration.

Checklist

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

[matthewgrossman]

📋 triage-agent

Triage Assessment

Classification: fixed-in-release

Summary

The gateway interceptor framework from PR #2005 functionally supersedes the requested Policy Provider subsystem. It provides remote gRPC modify/validate phases, operator-controlled bindings, fail-closed behavior, policy provenance, and a signed governance reference implementation.

Investigation

This is not the literal local/external Policy Provider abstraction proposed here, but it delivers the underlying external governance and policy-authority use case through the broader interceptor boundary. PR #2005 is contained in tag v0.0.84; because no GitHub Release was published for that tag, the first subsequent published release is v0.0.85. It is also present in current v0.0.92.

Recommendation

Closing as completed through the gateway interceptor architecture. Please open a focused follow-up if a remaining requirement cannot be expressed through interceptor bindings and provenance.