Secure, Fast, and Extensible Sandbox runtime for AI agents.
Add OSEP-0025: credential vault provider SPI and delegated credential resolution
高然19d96cdf367e
diff --git a/oseps/0025-credential-vault-provider-spi.md b/oseps/0025-credential-vault-provider-spi.mdnew file mode 100644index 000000000..a9eb410ee--- /dev/null+++ b/oseps/0025-credential-vault-provider-spi.md@@ -0,0 +1,414 @@+---+title: Credential Vault Exchange and Delegated Header Resolution+authors:+ - "@Pangjiping"+creation-date: 2026-10-28+last-updated: 2026-10-28+status: draft+---++# OSEP-0025: Credential Vault Exchange and Delegated Header Resolution++<!-- toc -->+- [Summary](#summary)+- [Motivation](#motivation)+ - [Goals](#goals)+ - [Non-Goals](#non-goals)+- [Requirements](#requirements)+- [Proposal](#proposal)+ - [Notes/Constraints/Caveats](#notesconstraintscaveats)+ - [Risks and Mitigations](#risks-and-mitigations)+- [Design Details](#design-details)+ - [Credential and Binding Model](#credential-and-binding-model)+ - [API](#api)+ - [Usage Demos](#usage-demos)+ - [Request Handling](#request-handling)+ - [Resolver Contract](#resolver-contract)+ - [Example Instantiations](#example-instantiations)+ - [Fast Sandbox Profile](#fast-sandbox-profile)+ - [Observability](#observability)+ - [Relationship to Prior OSEPs](#relationship-to-prior-oseps)+- [Test Plan](#test-plan)+- [Drawbacks](#drawbacks)+- [Alternatives](#alternatives)+- [Infrastructure Needed](#infrastructure-needed)+- [Upgrade & Migration Strategy](#upgrade--migration-strategy)+<!-- /toc -->++## Summary++Credential Vault (OSEP-0012) brokers static credentials: callers deliver inline values, and the vault injects headers rendered once per revision. This proposal adds one dynamic building block. An **exchange credential** declares a header-resolver service — a local Unix socket or a remote HTTPS endpoint — and a binding whose auth references it resolves matched requests through that service. When a bound request arrives, the egress asks the resolver for fresh headers and injects the response. The resolver is a black box: the vault does not know how it is started, what identity scheme it implements, or how it caches. Exchange traffic inherits every OSEP-0012 policy invariant unchanged: binding match, egress alignment, ambiguity fail-closed, revisions, audit, redaction.++## Motivation++Two gaps remain after OSEP-0012.++First, identity-derived credentials (SPIFFE-compatible SVIDs, STS tokens, OAuth2 client-credentials grants) are short-lived and computed from request context — an audience derived from the destination, or a signature bound to the request's method, path, and headers. They cannot be delivered as a static value at vault creation and cannot be pre-rendered at revision time.++Second, sandboxes that need such identities today use ad-hoc mitm addons and per-sandbox signing daemons. Those paths bypass binding validation, egress policy alignment, ambiguity checks, audit, and fail-closed semantics, and they require the sandbox application to cooperate (for example by setting an opt-in header). Credential policy effectively leaks into application code.++### Goals++1. Add an `exchange` credential source: a declarative pointer to a header-resolver service, addressed by a URI (`unix://` socket or `https://` endpoint).+2. Add an exchange auth form on bindings — an auth that omits `type` and only references an exchange credential — which routes matched requests to that credential's resolver for per-request header resolution.+3. One transport-agnostic resolver contract; the egress proxies each request to the resolver and injects the returned headers.+4. Fail closed on resolution error or timeout; redact per request; never expose or persist exchanged material.+5. The subject is supplied by the egress on every resolution, so one resolver can serve many sandboxes; identical model in sidecar and fast-sandbox profiles.+6. Zero behavior change for vaults that use only `inline` credentials.++### Non-Goals++1. Becoming a general secret manager (unchanged from OSEP-0012).+2. Dictating resolver internals — how it is started, deployed, what identity scheme it implements, how it caches or rotates. The vault contract starts and ends at the resolver endpoint.+3. Putting credential scope or audience policy into the vault API; a resolver derives scope from request context itself.+4. Injecting at connection level (mTLS/X509-SVID); injection remains HTTP header substitution, as in OSEP-0012's MVP.+5. Adding new sandbox-facing lifecycle APIs; callers continue to use the existing egress Credential Vault API.++## Requirements++| ID | Requirement | Priority |+|----|-------------|----------|+| R1 | A new `exchange` credential source carries a resolver endpoint URI (`unix://` or `https://`); `inline` behavior is unchanged; unknown types are rejected | Must Have |+| R2 | Binding auth that omits `type` and references an exchange credential resolves headers per request through that credential's resolver | Must Have |+| R3 | Auth with a static `type` binds only to static sources; typeless auth binds only to exchange sources; cross-references are rejected at validation | Must Have |+| R4 | Resolution runs only inside the egress process trust boundary; sandboxes must not be able to obtain credential material by calling the resolver directly | Must Have |+| R5 | Resolution failure or timeout fails closed: 407 for non-streamed requests, kill for streamed requests | Must Have |+| R6 | The subject is derived by egress from connection observables (client IP) and passed to the resolver; no protocol surface accepts a client-declared subject | Must Have |+| R7 | Behavior is identical in sidecar and fast-sandbox profiles; the resolver contract carries the subject | Must Have |+| R8 | Vault reads, diagnostics, and logs never expose exchanged credential material | Must Have |+| R9 | Every header returned by a resolver is redacted per request — by name, by value, and by rendered variants — in response headers; resolver-supplied redaction hints are additive only, never authoritative | Must Have |+| R10 | Audit events record the credential (resolver) name, decision, and target host; never credential values | Must Have |+| R11 | The vault enforces only a resolution timeout; resolver-internal caching and refresh are invisible to the contract | Must Have |+| R12 | Exchanged material is never persisted to disk; restart recovery requires only policy | Must Have |+| R13 | Exchange binding hosts join the credential-bound TLS decrypt set (OSEP-0023) in both profiles | Should Have |++## Proposal++### Notes/Constraints/Caveats++1. **Additive by construction.** Sandboxes that use only `inline` credentials observe zero behavior change; static credential behavior is untouched.+2. **Resolver reachability is part of the trust model.** A sandbox that can mint credentials by calling the resolver directly bypasses the entire policy plane. `unix://` resolvers are scoped by socket permissions; `https://` resolvers must require caller authentication (for example an egress-only token provisioned through operator configuration, never through the sandbox).+3. **The subject is an opaque routing key, not a delegation.** The vault performs no identity delegation; the subject→identity authorization mapping belongs to the resolver's operator domain, which configures and audits it.+4. **Resolver outage means denial, never bypass.** An unreachable or slow resolver is indistinguishable from a policy denial for exchange bindings.+5. **Per-request latency is bounded.** The vault applies a fixed resolution timeout; whether the resolver served a cached token or performed a fresh signature is invisible to the contract.+6. **Version skew fails closed.** A runtime component that does not support exchange must reject a vault containing exchange bindings outright; a dynamic binding must never silently degrade into an empty static binding or a missing vault.+7. **One slow resolver affects only its matched requests.** Resolution is per request with a bounded timeout; unrelated traffic through the same egress is never blocked waiting on a resolver.++### Risks and Mitigations++| Risk | Impact | Mitigation |+|------|--------|------------|+| Sandbox calls the resolver directly and mints credentials | Full policy bypass | `unix://` socket permissions; `https://` resolvers require caller authentication provisioned outside the sandbox (R4) |+| Client forges subject identity | Cross-subject credential use | Subject never accepted from the addon protocol; resolved from client IP with the existing authoritative mapping |+| Exchanged values leak through reads or diagnostics | Credential exposure | Resolution output exists per request only; redacted by name and value; never persisted |+| Resolver outage breaks exchange-bound traffic | Availability regression | Documented as fail-closed semantics; operators monitor resolver health; static bindings are unaffected |++## Design Details++### Credential and Binding Model++The OSEP-0012 split is preserved: a **credential** is a service definition (what to exchange with), a **binding** is a policy (when to exchange). One exchange credential can serve many bindings.++```mermaid+flowchart LR+ subgraph C["🗂️ Credential — service definition"]+ E["source.type: exchange<br/>endpoint: unix:///run/spi/spi.sock<br/>or https://resolver.internal"]+ end+ subgraph B["📋 Binding — policy"]+ M["match: hosts · paths · methods<br/>auth → credential (no type = exchange)"]+ end+ M -->|"per request, resolved by egress"| E+ classDef cred fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue+ classDef binding fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen+ class C cred+ class B binding+```++### API++Endpoints are unchanged from OSEP-0012. Only schemas grow.++| Operation | Behavior |+|---|---|+| `POST /credential-vault` | Create the vault with credentials and bindings; activates the initial revision |+| `GET /credential-vault` (+ `/credentials`, `/bindings`) | Sanitized metadata; never returns values |+| `PATCH /credential-vault` | Atomic runtime mutation with optional `expectedRevision` |+| `DELETE /credential-vault` | Revoke the vault and all runtime material |++Schema delta:++```jsonc+{+ "credentials": [+ { "name": "gh-token", "source": { "type": "inline", "value": "..." } }, // static, unchanged+ { "name": "spi-signer",+ "source": { "type": "exchange", "endpoint": "unix:///run/spi/spi.sock" } }, // local resolver+ { "name": "corp-resolver",+ "source": { "type": "exchange", "endpoint": "https://header-resolver.internal" } }+ ],+ "bindings": [+ { "name": "github-read",+ "match": { "hosts": ["api.github.com"], "methods": ["GET"], "paths": ["/repos/*"] },+ "auth": { "type": "bearer", "credential": "gh-token" } },+ { "name": "internal-api",+ "match": { "hosts": ["*.internal.example.com"], "paths": ["/*"] },+ "auth": { "credential": "spi-signer" } }+ ]+}+```++Validation rules:++- Auth objects that declare a `type` (`bearer`, `basic`, `apiKey`, `customHeaders`) must reference static sources; auth objects without `type` are exchange references and must reference exchange sources. Cross-references fail with 400. `type` is omitted for exchange because the resolver produces the complete header set — there is no render shape to select, and the referenced credential's source already determines the behavior.+- The endpoint URI scheme must be `unix://` or `https://`; other schemes fail with 400.+- Header names returned by a resolver pass the same hop-by-hop rejection set as static injection.+- All existing rules apply unchanged: egress allow coverage, ambiguity fail-closed, `expectedRevision` optimistic concurrency, sanitized read responses.++Field semantics — the user-facing reading of the model:++| Field | Meaning |+|---|---|+| `source.type: "exchange"` | This credential is a resolver service definition, not a static value; validation cross-locks it against static auth types |+| `source.endpoint` | Where to exchange, per request. The URI scheme selects the transport: `unix://` is HTTP over a Unix socket, `https://` is TLS |+| `match` | When to exchange: the hosts, paths, and methods that trigger resolution |+| `auth.credential` (no `type`) | Which resolver to use when triggered; "when" and "where" are decoupled so one resolver can serve many bindings. No `type` field: the resolver produces the complete header set, so there is no render shape to declare |+| binding `name` | Audit identifier surfaced in logs and metrics |++In short: `match` declares which requests, `endpoint` declares where to exchange, and the credential name welds the two together.++### Usage Demos++**Demo 1 — local signing resolver (UDS).** A SPIFFE-compatible signing service runs next to the egress and exposes a socket. One `POST /credential-vault` wires it up:++```jsonc+POST /credential-vault+{+ "credentials": [+ { "name": "spi-signer",+ "source": { "type": "exchange", "endpoint": "unix:///run/spi/spi.sock" } }+ ],+ "bindings": [+ { "name": "internal-api",+ "match": { "hosts": ["*.internal.example.com"], "paths": ["/*"] },+ "auth": { "credential": "spi-signer" } }+ ]+}+```++Sandbox code stays unchanged:++```python+requests.get("https://api.internal.example.com/v1/foo")+```++The request arrives at the upstream with fresh `Authorization` and signature headers. The sandbox process never sees or holds them. If the resolver is down, the request is denied (407) — never forwarded uncredentialed.++**Demo 2 — shared HTTPS resolver, one credential serving many bindings.** A centrally operated resolver behind TLS. The same credential backs different policies:++```jsonc+POST /credential-vault+{+ "credentials": [+ { "name": "corp-resolver",+ "source": { "type": "exchange", "endpoint": "https://header-resolver.internal" } }+ ],+ "bindings": [+ { "name": "team-a",+ "match": { "hosts": ["api.team-a.internal"], "paths": ["/*"] },+ "auth": { "credential": "corp-resolver" } },+ { "name": "team-b",+ "match": { "hosts": ["*.team-b.internal"], "methods": ["GET", "POST"], "paths": ["/v1/*"] },+ "auth": { "credential": "corp-resolver" } }+ ]+}+```++Both teams' hosts exchange through one service; per-sandbox identity selection happens inside the resolver, keyed on the subject the egress supplies.++**Demo 3 — runtime mutation.** Bindings can be added to a running sandbox atomically:++```jsonc+PATCH /credential-vault+{+ "expectedRevision": 7,+ "bindings": {+ "add": [+ { "name": "registry",+ "match": { "hosts": ["registry.internal"], "paths": ["/v2/*"] },+ "auth": { "credential": "corp-resolver" } }+ ]+ }+}+```++The response carries the acknowledged revision (8) and sanitized metadata. Reads never include values.++### Request Handling++The interaction view below is the complete implementation story: state reads (snapshot) and per-request resolution are separate interactions; exchange bindings carry only a marker until a request actually arrives.++```mermaid+flowchart TD+ A(["🚀 bound request arrives"]) --> C{"binding match"}+ C -->|"no match"| Z(["✅ ordinary egress, untouched"])+ C -->|"static (bearer, apiKey, …)"| S["inject pre-rendered headers<br/>(today's path, unchanged)"]+ C -->|"exchange"| R["resolve via credential endpoint"]+ R --> OK{"resolve ok?"}+ OK -->|"yes"| I["inject returned headers<br/>+ per-request redactions"]+ I --> FWD(["✅ forward"])+ S --> FWD+ OK -->|"no: error / timeout / revision mismatch"| F(["❌ fail closed:<br/>407 non-streamed · kill streamed"])+ classDef ok fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen+ classDef proc fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue+ classDef err fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black+ class Z,FWD ok+ class A,C,S,R,I proc+ class F err+```++```mermaid+sequenceDiagram+ autonumber+ participant App as 🧩 Sandbox app+ participant Egr as ⚙️ egress (vault + proxy)+ participant Res as 🔀 resolver (UDS or HTTPS)+ participant Up as 🌐 upstream++ App->>Egr: outbound HTTPS (transparent intercept)+ Egr->>Egr: binding match → exchange → subject from client IP+ Egr->>Res: POST {subject, credential, binding, request}+ Note over Res: identity scheme, signing, caching — all resolver-internal+ Res-->>Egr: 200 {headers, redactions}+ Egr->>Up: forward with exchanged headers+ Up-->>Egr: response+ Egr-->>App: response (exchanged values redacted by name and value)++ alt non-200 / timeout / revision mismatch+ Egr--xApp: non-streamed → 407 · streamed → kill (fail closed, never pass-through)+ end+```++Failure semantics: non-200, timeout, or revision mismatch is a per-request denial. It never degrades to pass-through and never poisons subsequent requests. Every resolution is bound to its snapshot generation and subject: a result that arrives after its request was cancelled, its binding deleted, or its sandbox replaced is discarded and never injected, including for a successor that reuses the same revision number.++### Resolver Contract++The same JSON-over-HTTP contract applies to both transports: HTTP over a Unix socket for `unix://`, plain HTTPS for `https://`. This is the only surface a resolver implements.++```jsonc+// egress → resolver+{+ "subject": "sbx-…", // authoritative, filled by egress; resolvers key identity on it+ "credential": "spi-signer",+ "binding": "internal-api",+ "destination": { // validated outbound destination, not the client-controlled Host+ "scheme": "https",+ "authority": "api.internal.example.com:443",+ "sni": "api.internal.example.com"+ },+ "request": { "method": "GET", "host": "api.internal.example.com",+ "path": "/v1/foo", "headers": { } }+}++// 200 — "redactions" is optional and additive: the egress redacts every+// returned header (name, value, rendered variants) regardless of this field+{+ "headers": { "authorization": "Bearer ...", "x-signature": "..." },+ "redactions": { "authorization": ["Bearer ..."] }+}+```++The `destination` block reflects the validated outbound destination as verified by the egress (scheme, authority including port, and SNI), so a resolver can bind a proof to the connection identity and distinguish `http://host` from `https://host`. Header names in the response are validated before injection.++Hard requirements on a resolver endpoint, none of which dictate an implementation:++| Requirement | Rationale |+|---|---|+| Reachable only by the egress process (socket permissions, or caller authentication for HTTPS) | trust boundary; prevents sandbox-side credential minting (R4) |+| Concurrent-safe, read-only | the egress issues parallel resolves |+| Responds within the vault resolution timeout | the vault fails closed beyond it |+| Per-request semantics | input includes request context; output differs per request |+| Absent/unreachable = denial | no fallback to uncredentialed pass-through |++Authentication material for `https://` resolvers is provisioned through operator configuration of the egress, never through the vault API and never into the sandbox.++### Example Instantiations++A SPIFFE-compatible signing service behind a local socket is the first target deployment: the credential points at its socket, the service fetches SVIDs and signs proof headers per request. The same contract is served unchanged by a remote `https://` resolver, which allows one centrally operated signing service shared by many egress instances and sandboxes.++### Fast Sandbox Profile++- Behavior is identical to the sidecar profile; the subject lets one shared resolver distinguish sandboxes.+- Exchanged material is never written to disk; after an egress restart, bindings and resolver references reactivate from persisted policy and material re-resolves on demand.+- Exchange binding hosts join the credential-bound TLS decrypt set (OSEP-0023).++### Observability++Audit events gain fields, never values: `credential` (resolver name), `resolution` (`resolved | denied | timeout`), `target_host`, `subject`. Metrics use only closed outcome attributes (`resolution` outcome, latency buckets) — the credential name is tenant-provided and must never become a metric dimension, keeping time-series cardinality bounded per OSEP-0010; it lives in audit logs only.++### Relationship to Prior OSEPs++- **OSEP-0012**: this proposal adds one source discriminator and a typeless auth form. Every policy invariant is inherited, not restated; the static path is untouched.+- **OSEP-0023**: exchange binding hosts feed the credential-bound TLS decrypt set; resolution failures deny at the HTTP layer exactly as static denials do.++## Test Plan++### Integration Tests++- Static path regression: inline-only vaults behave byte-for-byte as before.+- Exchange happy path with both transports (UDS and HTTPS): resolve → inject → upstream sees fresh headers.+- Fail-closed matrix: resolver down, timeout, and revision mismatch each deny without pass-through.+- Subject isolation: no protocol surface accepts a subject string; the resolver always receives the egress-derived subject.+- Resolver access control: a sandbox process cannot obtain credential material by calling the resolver directly.+- Redaction: injected dynamic values are removed from response headers by name and value; logs contain no values.+- Restart recovery: exchange bindings reactivate from persisted policy; no material on disk before or after.++### E2E Tests++- A SPIFFE-compatible signing service behind a UDS endpoint: sandbox process calls a bound host with no credential material and the request arrives with valid fresh headers.+- A remote HTTPS resolver shared across sandboxes: subject-derived identity selection works per sandbox.+- A sandbox that cannot reach the resolver receives denials for exchange bindings while static bindings keep working.++## Drawbacks++- Exchange bindings add a per-request resolver hop (bounded by the resolution timeout; resolvers cache internally).+- Exchange-bound availability now depends on resolver health; this is inherent to brokered identity but is a real operational change.+- HTTPS resolver caller authentication is new operator configuration to get right.++## Alternatives++### App-Driven Header Signing (status quo for identity workloads)++Per-sandbox signing daemons plus mitm addons that the application opts into by header. Rejected as the general mechanism: no policy plane, no audit, application cooperation required, identity scope uncontrolled.++### Pre-Rendering Exchanged Material at Revision Time++Rejected: request-derived scope makes the material set unbounded before the request exists; per-request signatures cannot be computed pre-request; reuse of pre-rendered output would break proof-of-possession properties (the signature is bound to one request, so reuse is invalid by construction) and weaken fail-closed (stale material keeps flowing after resolver failure until TTL). A fixed-scope, non-signing token could be modeled as a static-with-rotation source — an allowed optimization for resolvers that choose it, not a replacement for resolution.++### Addon-Direct Resolver Calls++The addon would resolve directly against the signing service, fragmenting validation, revision consistency, redaction, and audit across processes, with no subject dimension. Rejected.++### Treat Identity Tokens as Inline Values with External Refreshers++Callers would run their own refresh loops and re-POST values. This reintroduces the plaintext-delivery path OSEP-0012 removed and loses per-request binding. Rejected.++## Infrastructure Needed++- Egress: `exchange` source type, typeless auth form, resolver proxy (UDS and HTTPS clients) — no new component or image.+- Lifecycle server and spec: extend the `Credential.source` schema (today fixed to inline) and the binding auth union (today requires `type`) for the fast-sandbox relay path, including sanitization, server-side merge, and regenerated SDKs.+- Operator configuration surface for the resolution timeout.+- Documentation and one example per transport.++No new required external service is introduced by this proposal.++## Upgrade & Migration Strategy++The proposal is additive and opt-in. Sandboxes that use only `inline` credentials are unaffected.++1. Land the schema and resolver proxy behind the existing `[egress.credential_vault].enabled` gate.+2. Extend the lifecycle server path (source/auth schema, sanitization, merge, regenerated SDKs) so exchange requests survive the fast-sandbox relay round-trip instead of failing server-side validation.+3. Validate against a local UDS signing service.+4. Migrate operator templates from bespoke per-sandbox signing addons to exchange credentials and retire those addons.+5. Document operator guidance: narrow binding scopes and resolver health monitoring.++Scope note: the first implementation targets the Fast Sandbox use case with one publicly testable resolver and explicitly rejects unsupported combinations (per the version-skew caveat above). Full OSEP-0023 integration depth, recovery/drain hardening, body signing, and soak/performance matrices are follow-up work and do not block this proposal.diff --git a/oseps/README.md b/oseps/README.mdindex 642cfc814..3b3b141a5 100644--- a/oseps/README.md+++ b/oseps/README.md@@ -30,3 +30,4 @@ This is the complete list of OpenSandbox Enhancement Proposals:| [OSEP-0022](0022-multi-sandbox-egress-control-plane.md) | Multi-Sandbox Egress Control Plane | implementing | 2026-08-21 || [OSEP-0023](0023-credential-bound-tls-interception.md) | Credential-Bound TLS Interception | implementing | 2026-09-09 || [OSEP-0024](0024-auto-pause-and-wake-on-access-for-fast-sandbox.md) | Auto-Pause and Wake-on-Access for Fast Sandbox | implementing | 2026-10-12 |+| [OSEP-0025](0025-credential-vault-provider-spi.md) | Credential Vault Exchange and Delegated Header Resolution | draft | 2026-10-28 |