@mseep/open-computer-use 1.0.0

package/docs/architecture/components/01-mcp-gateway.md

@@ -0,0 +1,80 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-03
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+compliance: []
+threat-model: 06-threat-model.md
+contract: contracts/mcp/2025-06-18/ocu-constraints.schema.json
+adr: []
+---
+
+The agent-facing inbound terminator: it authenticates the MCP caller, validates the tool-call, and hands a session request to the Control/operator API. Audience: engineers and security reviewers implementing or auditing the inbound MCP edge.
+
+# Component-01: MCP gateway
+
+## Purpose
+
+Terminates inbound MCP tool-calls and authenticates the caller, then forwards a metadata-only session request to the Control/operator API ([`05-c4-container.md`](../05-c4-container.md) §3). It is a Conformist to the public MCP revision and runs no agent loop, so the calling client owns the loop and the model; the gateway holds no caller token past the request, no upstream credential, and no lifecycle or kill-switch route.
+
+## Boundaries
+
+Intra-container, the gateway is one process with three internal stages on each request:
+
+| Internal stage | What it does |
+|---|---|
+| transport listener | terminates the MCP connection and validates the bearer audience |
+| schema validation | applies the MCP base schema, then the OCU constraint profile |
+| forwarding | issues a service-identity request to the Control/operator API |
+
+The inbound caller edge, the gateway→Control/operator API edge, and the gateway→Audit pipeline fan-in are the boundaries `05-c4-container.md` §4 names (their `F1`/`F5`/`F10` flow labels are defined in [`05-c4-container.md`](../05-c4-container.md) §4); this spec adds only which internal stage terminates each.
+
+Owned state: none that outlives a request. The gateway holds the in-flight request, the negotiated protocol revision for the connection, and its own service-identity signing material; it persists no session registry (that is the Control/operator API), no caller token after the response, and no customer payload. It provably does NOT hold an upstream credential, a Custody credential lease, a Storage-mount handle, the session denylist, or any route that resolves to a lifecycle or kill-switch operation — the operator surface sits in a separate container reachable only on operator-only ingress ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §8).
+
+Token classes ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §8 owns the taxonomy): the gateway validates the inbound external bearer as a relying party, presents a Generic internal token on the forward to the Control/operator API, and mints or holds neither a Session JWT nor a Custody credential lease. The wire contract is the OCU constraint profile over MCP revision 2025-06-18 ([`ocu-constraints.schema.json`](../../../contracts/mcp/2025-06-18/ocu-constraints.schema.json)); it is a conform-not-define overlay, so field types, the error envelope, and the numeric caps live in the schema. The schema does not encode three facts: the gateway terminates the MCP socket and applies the base schema before the profile; the bearer is carried on the transport, never in the JSON-RPC body or URI query; and the caller token is never forwarded onto the Control/operator API leg or into the sandbox.
+
+## Invariants
+
+Each holds independent of the caller and is falsifiable by the named check.
+
+- Every inbound tool-call is validated against the MCP base schema then the OCU profile before any forward, and an unknown field or out-of-bound payload is rejected pre-buffer with a structured deny, never partially acted on (schema-validation + property-test, NFR-SEC-51, NFR-SEC-46).
+- The bearer must name this MCP server in its audience claim or the request is refused with the relying-party challenge; identity is never read from the request body (schema-validation + unit-test, NFR-SEC-09).
+- The caller bearer never appears on the forward leg, in a forwarded argument, or in any path reaching the sandbox; the forward carries only the gateway's own service identity (code-path audit + integration-test, NFR-SEC-09, NFR-SEC-26).
+- No gateway code path resolves to a lifecycle, denylist, or kill-switch route, and no rendered deploy manifest grants the gateway a network route to the operator ingress on either shelf (IaC-policy assertion, NFR-SEC-52).
+- Outbound errors and discovery responses are size-bounded and carry a stable reason class plus a correlation id only — never a session id, `container_name`, internal host/route, or stack detail (schema-validation + property-test, NFR-SEC-51).
+- The negotiated protocol revision is pinned per connection; a request whose `MCP-Protocol-Version` is missing or unnegotiable is rejected rather than silently downgraded (schema-validation + unit-test, NFR-IC-04).
+- Tool execution is serialized per session by default; parallelism is opt-in per skill (integration-test, NFR-IC-05).
+- The gateway holds at most a configured number of open connections per audience-validated caller; excess is refused, not queued, and a single caller cannot consume more than its configured share of the listener fd table (chaos-test, NFR-SEC-53).
+
+## Failure modes
+
+Each row traces to one P1 STRIDE row in [`06-threat-model.md`](../06-threat-model.md) §3.2 and repeats that row's controlling NFR; fail-closed is the default on every authentication and forward boundary. A1 is the in-sandbox guest; A2 is the external caller (the reaching actor on the gateway's P1 element).
+
+| Trace | Reaching actor | What goes wrong | Recovery behaviour | Controlling NFR |
+|---|---|---|---|---|
+| P1-S1 | A2 | Replayed, forged, or wrong-audience bearer presented to open or address sessions | Validate as relying party; refuse with the resource-metadata challenge | NFR-SEC-09 |
+| P1-S2 | A2 | Gateway service identity escalated on the forward so the Control/operator API treats the request as more privileged | The forward carries the gateway service principal only, which holds no operator scopes | NFR-SEC-26 |
+| P1-T1 | A2 | On-path rewrite of tool-call parameters in flight | Validate audience and schema before acting; downstream authority is the host-derived identity, not the body | NFR-SEC-33 |
+| P1-T2 | A2 | Forwarded body claims another tenant's `session_id`/`container_name` to bind or read a session it does not own | The body id is a hint cross-checked host-side; the Control/operator API derives the binding, so a forged id grants no reach | NFR-SEC-43 |
+| P1-R1 | A2 | Caller denies issuing a tool-call/session-create; no independent record attributes the action | Emit an OCSF event on fan-in per terminated request with the validated caller identity | NFR-SEC-03 |
+| P1-I1 | A2 | Verbose MCP errors or discovery leak session ids, `container_name`, tenant ids, or the operator surface | Emit a stable reason class + correlation id only, size-bounded; discovery exposes only the declared tool surface | NFR-SEC-51 |
+| P1-D1 | A2 | Flood of the MCP surface exhausts gateway connections/CPU and pressures the lifecycle plane via the forward | Per-caller connection/fd ceiling refuses excess; the separate runnable unit means saturation cannot reach operator ingress or the kill-switch | NFR-COST-06, NFR-SEC-01, NFR-SEC-53 |
+| P1-E2 | A2 | Caller invokes a tool or action beyond its authorization; the gateway authenticates but does not yet decide per-action authz | Audience-validated authN bounds who reaches the surface; host-attested identity blocks cross-session addressing downstream; per-action authz is the residual | NFR-SEC-49 |
+
+Residual, by [`06-threat-model.md`](../06-threat-model.md) §5 register: per-action authorization (P1-E2) is specified by NFR-SEC-49 but not yet enforced at the gateway — tracked at [#187](https://github.com/Wide-Moat/open-computer-use/issues/187). The identifier-minimization measurement behind P1-I1/P1-R1 is tracked at [#149](https://github.com/Wide-Moat/open-computer-use/issues/149). The gateway↛operator network separation that bounds P1-S2 and P1-D1 is verified by the NFR-SEC-52 IaC-policy assertion; the gateway is the agent-path side of the two-container split whose escalation row (P2-E1) is owned with the Control/operator API.
+
+## Operational concerns
+
+Config surface: the inbound listener bind and transport, the bearer relying-party metadata (issuer, audience, resource-metadata URL), the pinned MCP revision, the per-caller connection/fd ceiling and per-tenant calls-min quota (NFR-COST-06, NFR-SEC-53), and the gateway's own caps on error/result/argument size — each an enforced default the operator may retune within the NFR-SEC-46/51 floor. Observability: the gateway emits OCSF on the fan-in flow for every terminated request with the validated caller identity, and an OCSF rejection event on a connection-ceiling refusal ([`audit/audit-fanin`](../../../contracts/audit/audit-fanin.asyncapi.yaml), NFR-SEC-03). Scaling axis: single instance per deployment (not per session); capacity is bounded by the per-caller ceiling and the MCP request success-rate target (NFR-PERF-01). Upgrade/rotation: the gateway carries no semver — its revision is the date string negotiated on `initialize`, and a peer that cannot negotiate the revision is the breaking signal rather than an HTTP deprecation header (NFR-IC-04); the service-identity signing key rotates on the inter-component identity cadence ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §8).
+
+Shelf delta ([`05-c4-container.md`](../05-c4-container.md) §5): the minimal shelf runs the gateway as a single co-located process whose service identity is a host-local signing key and whose caller authN is a host-rooted local credential; the full shelf schedules a single instance whose service identity is a customer-PKI workload identity and whose caller authN is the customer-IdP-asserted relying-party flow (NFR-COMP-29). The invariants above are boundary properties and hold on both shelves; only the identity substrate and listener scheduling change.
+
+## Open questions
+
+1. Does NFR-IC-04 bind only the Control/operator API and internal RPC, leaving the MCP edge governed solely by date-revision negotiation, or does it need an explicit MCP-edge clause? — [#207](https://github.com/Wide-Moat/open-computer-use/issues/207).
+2. Per-action / per-tool authorization at the gateway (deny-by-default keyed on caller, tool name, action parameters) — [#187](https://github.com/Wide-Moat/open-computer-use/issues/187).
+3. Outbound error/discovery identifier-minimization and size-bound enforcement at the gateway decoder — [#149](https://github.com/Wide-Moat/open-computer-use/issues/149).
+4. Whether the per-session sequential-execution serializer (the NFR-IC-05 carrier, today a gateway behaviour with no wire field) needs its own versioned conformance fixture so opt-in parallelism is testable independently of the MCP profile ([#239](https://github.com/Wide-Moat/open-computer-use/issues/239)).

package/docs/architecture/components/02-control-operator-api.md

@@ -0,0 +1,80 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-05-31
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+compliance: []
+threat-model: 06-threat-model.md
+contract: null
+adr: [0004]
+---
+
+The operator-facing lifecycle terminator: it owns session lifecycle, quota, the session denylist, and the kill-switch, reachable only on operator/lifecycle ingress and never from the agent-facing MCP surface. Audience: engineers wiring the operator plane or auditing the kill-switch path.
+
+# Component-02: Control / operator API
+
+## Purpose
+
+Owns session lifecycle, quota, the session denylist, and the kill-switch ([`05-c4-container.md`](../05-c4-container.md) §3). It is the operator side of the Control plane split into two runnable units so the kill-switch is unreachable from the agent path by network policy rather than an in-process guard; it is the sole author of the session denylist that the Egress trust-edge reads and that the Control plane checks host-side on every Compute-plane control RPC (`F6`) ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §7).
+
+## Boundaries
+
+Intra-container, this is one process with three internal components behind a single operator/lifecycle ingress that is a distinct deployable from the MCP gateway:
+
+| Internal component | What it does |
+|---|---|
+| lifecycle controller | terminates session create/status/destroy (gateway service identity) and operator session ops; host-dials the Session sandbox to set up and tear down |
+| denylist + kill-switch authority | terminates operator force-kill, denylist edits, and signed SOAR revoke; authors the denylist and signals a host-initiated stop |
+| quota accountant | checks per-caller create-rate and per-tenant counters on create; refuses excess |
+
+The operator/lifecycle ingress, the SOAR-revoke ingress, the gateway→Control session set-up edge, the Control→Session sandbox host-dial, and the Control→Audit fan-in are the boundaries `05-c4-container.md` §4 names (their `F2`/`F4`/`F5`/`F6`/`F10` flow labels are defined in [`05-c4-container.md`](../05-c4-container.md) §4); this spec adds only which internal component terminates each.
+
+Owned state: the session registry (live sessions, their `container_name` binding, tenant, quota counters) and the denylist (kill-switch state), of which this container is sole custodian — no other component can mutate either, and the guest holds no handle that reaches them. It provably does NOT hold an upstream credential or backend storage key (the upstream credential reaches the Egress trust-edge over Envoy SDS; the backend storage key sits with the Storage broker, [`02-trust-boundaries.md`](../02-trust-boundaries.md) §2), and holds no Storage-mount handle.
+
+Token classes ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §8 owns the taxonomy and TTLs): this container mints the Session JWT (per-session, bound to `container_name`) toward the Session sandbox on the host-dialled control channel, accepts a Generic internal token authenticating the inbound gateway service identity on session set-up, and accepts an operator credential on ingress (the operator-auth substrate is fixed by [ADR-0004](../adr/0004-operator-authentication-substrate.md)). The wire surface is unfrozen: the operator REST and SOAR-revoke surfaces (OpenAPI 3.1) and the gateway→Control session set-up RPC (Protobuf/gRPC) are OCU-`define` in [`08-contracts.md`](../08-contracts.md) §1, but their schema files are not yet built ([#205](https://github.com/Wide-Moat/open-computer-use/issues/205)), so `contract: null`. Two listeners back this container — operator/lifecycle ingress and gateway service-identity ingress; the kill-switch route exists only on the former. The customer-IdP assertion on ingress is relying-party, not an OCU-defined surface.
+
+## Invariants
+
+Each holds independent of the caller and is falsifiable by the named check. Cross-cutting properties (zone membership, in-transit encryption, retention floor, isolation tier) are Layer 3 and not restated.
+
+- No MCP-surface route resolves to a lifecycle, denylist, or kill-switch route, and no rendered deploy manifest grants the gateway a network route to the operator ingress on either shelf (IaC-policy assertion, NFR-SEC-52).
+- The kill-switch and revoke path holds its SLA while the control plane is saturated, including a flood on the operator/SOAR ingress itself; the lifecycle/revoke route carries reserved capacity or admission priority distinct from the create path (chaos test with an adversarial concurrent-load dimension, NFR-SEC-55, with the ≤30 s p99 value owned by NFR-SEC-01).
+- A body-supplied session/tenant/`container_name` id is a hint, never the authority; the binding the host acts on (the host-dial, the registry write) is host-derived, so a gateway or guest naming another session's id cannot bind or address it (integration-test: forge-another-session attempt fails, NFR-SEC-43).
+- The gateway service identity reaching this container carries no operator scope; force-kill, denylist edit, and quota override are unreachable with that audience (unit + integration-test on the audience-to-route map, NFR-SEC-26).
+- Every privileged operator/SOAR action in the NFR-SEC-45 enumerated set emits a chain-linked OCSF event before acknowledgement, and the action is denied if the audit write fails (fail-closed); the enumerated set is the versioned fixture owned by NFR-SEC-45, with system-initiated lifecycle transitions owned by NFR-SEC-72 (per-release integration-test driving every action + a negative test asserting deny on audit-sink failure, NFR-SEC-45).
+- Per-caller create-rate and per-tenant quota are enforced before a session is created; excess is refused, not queued, and agent-side create flooding cannot starve the operator/revoke route because the two ingresses are distinct (quota integration + connection-flood chaos test, NFR-COST-06, NFR-SEC-53).
+- All TTL and revocation windows (Session JWT, denylist propagation) are computed against a monotonic clock immune to wall-clock setback; a setback ≥ a window neither extends a token nor defers a revoke (red-team clock-rollback harness, NFR-SEC-48).
+
+## Failure modes
+
+Each row traces to one P2 STRIDE row in [`06-threat-model.md`](../06-threat-model.md) §3 and repeats that row's controlling NFR; fail-closed is the default on the denylist, revoke, and audit-write boundaries. A1 is the in-sandbox guest; A2 is the external caller / gateway service identity; A3 is the operator/SOAR principal.
+
+| Trace | Reaching actor | What goes wrong | Recovery behaviour | Controlling NFR |
+|---|---|---|---|---|
+| P2-E1 | A2, A1 | Agent-path principal probes for an operator or kill-switch route | No lifecycle/kill-switch route resolves; gateway→operator-ingress reachability is denied at deploy time and a missed route fails CI, not runtime | NFR-SEC-52 |
+| P2-T2 | A1 | Guest stalls or drops the host-dialled control RPC to defeat the stop | The denylist is read host-side and the kill-switch is a host-initiated stop, not a cooperative guest action; an unreachable channel grants no new authority (fail-closed) | NFR-SEC-01 |
+| P2-D1 | A2, A1 | Concurrent flood of session-create and operator/SOAR calls aims to starve revoke | The create path sheds at the per-caller/per-tenant quota and fails-closed; the revoke route holds reserved capacity so the kill-switch stays within SLA, with RTO/RPO the post-failure backstop | NFR-SEC-55, NFR-REL-01 |
+| P2-R1 | A3, A2 | Operator force-kill / denylist edit / quota override leaves no independent record | The action is denied if its audit event fails to write; it does not take effect un-recorded | NFR-SEC-45 |
+| P2-R2 | A2 | SOAR revoke disputed or replayed | The call is verified by signature against the SOAR principal before acting and emits an OCSF event bound to that principal; an unverifiable call is rejected | NFR-COMP-27, NFR-SEC-45 |
+| P2-I1 | A2, A3 | Registry/quota enumeration across tenants | Audience-scoping returns only the caller's own sessions and host-attested binding blocks cross-session reads; the control plane carries no customer payload | NFR-IC-04 |
+
+Residual, by [`06-threat-model.md`](../06-threat-model.md) §5 register: the stop-SLA accounting behind P2-T2 assumes a trustworthy host clock — trusted-time theme, [#185](https://github.com/Wide-Moat/open-computer-use/issues/185). Saturation/spill behaviour and a measurable containment target for P2-D1 fold into the resource-exhaustion theme, [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). The mandatorily-audited action set behind P2-R1/P2-R2 is the privileged-operator-audit theme tracked at [#186](https://github.com/Wide-Moat/open-computer-use/issues/186). The no-customer-payload gate behind P2-I1 is not yet a measurable target, [#149](https://github.com/Wide-Moat/open-computer-use/issues/149).
+
+The denylist this container authors also gates the Egress trust-edge: a revoked session is refused lease injection at the edge (the deny-signal half of [`02-trust-boundaries.md`](../02-trust-boundaries.md) §7). That enforcement behaviour lives in the Egress trust-edge spec; here the invariant is only sole authorship of the denylist the edge reads.
+
+## Operational concerns
+
+Config surface: the operator/lifecycle ingress listener and the gateway service-identity listener are distinct network endpoints (the NFR-SEC-52 separation); per-caller create-rate, per-tenant concurrent-session and calls/min ceilings (NFR-COST-06), and the reserved lifecycle/revoke capacity (NFR-SEC-55) are the principal knobs. Observability: this container emits OCSF on the audit fan-in for session create/destroy, every enumerated privileged action (NFR-SEC-45), and quota rejections, into the hash-chained pipeline ([`audit/audit-fanin`](../../../contracts/audit/audit-fanin.asyncapi.yaml), NFR-SEC-03); the audit-write is on the critical path of a privileged action (fail-closed), not a side-channel. Scaling axis: one instance per deployment (not per session); the single-instance minimal shelf is in scope for the kill-switch-under-saturation target (NFR-SEC-55), so the capacity model reserves admission priority for the revoke route rather than scaling out, and RTO/RPO of this plane is NFR-REL-01. Upgrade/rotation: the RPC surface (session create/destroy/exec/fs) is versioned — a breaking change requires a major version plus deprecation header, CI-enforced by `buf breaking` / `oasdiff` (NFR-IC-04, [`08-contracts.md`](../08-contracts.md) §4); Session JWT rotation is mint-fresh-before-expiry, not extension, on the JWT TTL window in [`02-trust-boundaries.md`](../02-trust-boundaries.md) §8.
+
+Shelf delta ([`05-c4-container.md`](../05-c4-container.md) §5): the minimal shelf co-locates this container with a host-rooted local operator credential and a host-local Session-JWT signing key; the full shelf schedules it with a customer-IdP-asserted operator identity (NFR-COMP-29) and a customer-PKI-rooted signer. The invariants above are boundary properties and hold on both shelves; only the operator-auth substrate and the JWT signer change, never the gateway↛operator separation, the host-attested binding, or the fail-closed audit-write. Retention of the audit events this container emits is the platform floor owned by the Audit pipeline (NFR-COMP-01). The operator-auth substrate is fixed by [ADR-0004](../adr/0004-operator-authentication-substrate.md).
+
+## Open questions
+
+1. Minimum scope of the gateway's internal token on the session set-up edge, and per-tool/per-action authorization on operator actions — [#187](https://github.com/Wide-Moat/open-computer-use/issues/187).
+2. Measurable no-customer-payload gate on the control plane — [#149](https://github.com/Wide-Moat/open-computer-use/issues/149).
+3. Saturation/spill behaviour and a measurable containment target for the create and operator/SOAR ingress under sustained adversarial load — [#188](https://github.com/Wide-Moat/open-computer-use/issues/188).
+4. Trusted-time floor for Session-JWT TTL and denylist-propagation windows — [#185](https://github.com/Wide-Moat/open-computer-use/issues/185).
+5. Operator-auth substrate (PAM-JIT integration, full vs minimal shelf) is fixed by [ADR-0004](../adr/0004-operator-authentication-substrate.md); the multi-party-approval residual is tracked at [#225](https://github.com/Wide-Moat/open-computer-use/issues/225).

package/docs/architecture/components/04-storage-broker.md

@@ -0,0 +1,104 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-03
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+compliance: []
+threat-model: 06-threat-model.md
+contract: [contracts/storage/mount-config.schema.json, contracts/storage/file-ops.schema.json, contracts/storage/file-artifact-api.schema.json]
+adr: [0002, 0010, 0011]
+---
+
+The host-side object-store client that custodies the backend credential and resolves file authorization for the guest mount and an external data-plane client, so neither holds a backend key. Audience: engineers and security reviewers implementing or auditing the storage surface.
+
+# Component-04: Storage broker
+
+## Purpose
+
+Custodies the backend object-store credential and resolves file authorization for two callers — the guest mount and an external data-plane client ([`05-c4-container.md`](../05-c4-container.md) §3). Both faces are components inside one container, sharing one backend credential and one storage-lane backend leg ([NFR-SEC-85](../manifesto/02-nfrs.md)); the `downloadable` axis is resolved at read on both faces, not stamped at write.
+
+## Boundaries
+
+Intra-container, the broker is one process whose two faces call a shared authorization resolver and a single object-store client. The inter-container edges — the broker→sandbox mount, the broker→edge→backend leg, the broker→audit fan-in, and the data-plane-client→broker crossing — are the boundaries [`05-c4-container.md`](../05-c4-container.md) §4 names (their `F7`/`F9`/`F10`/`F11` flow labels are defined in [`05-c4-container.md`](../05-c4-container.md) §4); this spec adds only the intra-container split below.
+
+```mermaid
+flowchart LR
+    SM[South-face mount adapter]
+    NF[North-face file/artifact API + SPA + preview-render]
+    AUTHZ[Three-axis authz resolver]
+    OSC[Object-store client + backend signer]
+    SM --> AUTHZ
+    NF --> AUTHZ
+    AUTHZ --> OSC
+```
+
+The south-face mount adapter terminates the `filesystem_id`-scoped file-operation interface from the guest; the north-face component terminates the file/artifact API plus the authenticated SPA and the preview-render path. The files surface is one entry in the data-plane UI's descriptor-driven view list ([ADR-0002](../adr/0002-session-view-descriptor.md)); the broker serves that entry, while the descriptor shell and the deferred live-view surfaces sit outside this container. Both call one authz resolver, which calls one object-store client — the sole component that speaks the backend protocol and signs every backend request. The substrate under the mount (FUSE / virtio-fs / 9p) and the message-set transport are component-spec choices, not contract.
+
+### Owned state
+
+| Owns (sole custodian) | Provably does NOT hold |
+|---|---|
+| The backend object-store credential | No upstream-API credential (that reaches the Egress trust-edge over Envoy SDS) |
+| The `filesystem_id` → backend prefix mapping | No kill-switch state and no route to the denylist (those are the Control / operator API) |
+| Per-object `downloadable` disposition, resolved at read | No second outbound path; a direct broker→backend dial bypassing the edge is forbidden (NFR-SEC-16) |
+| The north-face first-party session minted after embed-token verify | No long-lived caller identity: it verifies a peer-minted embed token, it does not issue it |
+
+The guest holds only the Storage-mount handle (a `filesystem_id`); the data-plane client presents only an embed token. The Storage-mount handle is canonical in [`02-trust-boundaries.md`](../02-trust-boundaries.md) §8 (session-scoped); the embed token is a peer-minted relying-party credential, not an OCU §8 class — its `exp` is fixed by NFR-SEC-82 — referenced, not restated. The backend signature is produced once, in the object-store client; the egress edge forwards the broker-signed leg on a storage-dedicated lane allow-list-only without TLS termination ([NFR-SEC-85](../manifesto/02-nfrs.md)). The frozen field types, error envelope, and embed/CSP/CSRF wire detail live in the three bound schema files ([`mount-config`](../../../contracts/storage/mount-config.schema.json), [`file-ops`](../../../contracts/storage/file-ops.schema.json), [`file-artifact-api`](../../../contracts/storage/file-artifact-api.schema.json)).
+
+## Invariants
+
+Each rule holds independent of the caller and is falsifiable by the named check. Cross-cutting properties (zone membership, in-transit encryption, retention floor, runtime tier) are Layer 3 and excluded here.
+
+1. No file-op or API call resolves a path or object handle outside the request's host-attested `filesystem_id` prefix; traversal, symlink, absolute-path, and URL-shaped handles are rejected before any backend call (property-test, NFR-SEC-25).
+2. No request the guest or data-plane client issues names a backend object directly; the broker maps a file-op verb / API intent to a request signed with its own credential, and a caller-supplied session/tenant id is a hint cross-checked against host-attested identity, never the identity itself (property-test, NFR-SEC-43).
+3. `downloadable` is resolved broker-side at read on both faces from the host-attested session, never from a client-supplied claim; a non-downloadable object is readable in-session but yields no egress-eligible artifact, and `intent=preview` stays read-only and non-downloadable regardless of stored tag (property-test, NFR-SEC-73).
+4. Three-axis authorization (scope `filesystem_id` + intent `read`/`write`/`preview` + downloadable) is re-derived broker-side per request, deny-by-default keyed on the authenticated caller; a `preview`-authorized caller cannot invoke `download`/`write` (property-test, NFR-SEC-49).
+5. A north-face inbound body above the configured ceiling is rejected pre-buffer, never partially staged; archive bodies are validated (uncompressed-total / entry-count / ratio / traversal / symlink) before extraction and content-classified on ingest before becoming mount-visible (schema-validation + property-test, NFR-SEC-78, NFR-SEC-80, NFR-SEC-81).
+6. The north face accepts no request without a signature-valid, in-audience, unexpired embed token before any session state is set, then 401s a missing/invalid session with no anonymous fallback, requires a server-validated CSRF token on every state-mutating call, and sends `CSP: frame-ancestors` from the per-deployment allowlist on every UI/artifact response (schema-validation, NFR-SEC-82, NFR-SEC-83, NFR-SEC-84). The header values are fixed in [`08-contracts.md`](../08-contracts.md) §3 and the bound schema.
+7. No OCU upstream secret crosses to the browser; the embed token is peer-minted and the backend credential never leaves the object-store client (unit-test + property-test, NFR-SEC-82).
+8. Every file-activity on either face emits an OCSF File System Activity event into the hash-chained pipeline before the operation is acknowledged; an audit-write failure denies the operation (fail-closed) (unit-test, NFR-SEC-79).
+9. For a multi-tenant deployment the broker is instantiated per tenant — one broker principal per tenant filesystem scope; a multiplexed broker is admitted only on a single-tenant `trusted_operator` shelf (IaC-policy assertion, NFR-SEC-76).
+10. A long-lived host-local backend credential is admitted only where `workload_trust_profile = trusted_operator` and the deployment is single-tenant; any other profile or a multi-tenant deployment requires the STS-scoped-per-session credential, and admission rejects otherwise (per-profile admission test, NFR-SEC-60).
+
+## Failure modes
+
+Each row traces to one P4 STRIDE row in [`06-threat-model.md`](../06-threat-model.md) §3; the Trace column points at the row for threat detail, the Recovery column carries the container-internal contract. The reaching actor is A1 (in-sandbox guest) on the south/backend legs and A2 (external data-plane client) on the north face. Fail-closed is the default on every authz, audit, and ingest boundary.
+
+| Failure | Trace | Recovery behaviour |
+|---|---|---|
+| Guest crafts traversal/symlink/oversized file-op to escape the prefix | P4-T1 (NFR-SEC-25 + SEC-46) | Resolve inside the host-attested prefix and reject pre-backend; oversized write rejected pre-buffer at the max-object ceiling, never partially staged. |
+| Cross-session read of leftover content on a reused mount, or list beyond prefix | P4-I2 (NFR-SEC-54 + SEC-13 + SEC-64 + SEC-25 + SEC-73) | Erase-before-reuse zeroizes a recycled substrate before a session-2 handle binds (NFR-SEC-54), the per-session DEK is destroyed on session end (NFR-SEC-13), page-cache/backend residue is dropped before the next session runs (NFR-SEC-64), and list/read stays prefix-confined (NFR-SEC-25 + SEC-73). |
+| Guest floods file-ops / huge writes / fd exhaustion against a shared broker | P4-D1 (NFR-SEC-46) | Per-session file-ops/s, in-flight-bytes, and fd ceilings throttle fail-closed, not broker-wide degradation. Residual: resource-exhaustion theme, [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). |
+| Guest drives backend traffic to exhaust STS quota / blow up backend cost | P4-D2 (NFR-SEC-85 + SEC-16) | A network backend engine's traffic traverses the storage-dedicated lane ([NFR-SEC-85](../manifesto/02-nfrs.md)) as one observable destination and the bypass dial is forbidden, so the leg is policy-gated; a local-volume engine ([ADR-0010](../adr/0010-storage-backend-pluggable-adapter.md)) has no network leg, so per-session file-op ceilings (P4-D1) are the gate. Residual: per-session backend rate ceiling — resource-exhaustion theme, [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). |
+| Guest smuggles a backend key/prefix through a file-op argument (confused deputy) | P4-E1 (NFR-SEC-25 + SEC-43 + SEC-76) | The broker signs with its own credential against the host-attested mapping; broker-per-tenant bounds the deputy. Residual: per-action authz, [#187](https://github.com/Wide-Moat/open-computer-use/issues/187). |
+| Broker opens a direct backend dial bypassing the storage lane | P4-E2 (NFR-SEC-85 + SEC-16) | The bypass dial is refused; a network backend engine's leg must traverse the storage-dedicated lane ([NFR-SEC-85](../manifesto/02-nfrs.md)) — out-of-process from the broker, so a compromised broker cannot silence it — while a local-volume engine ([ADR-0010](../adr/0010-storage-backend-pluggable-adapter.md)) opens no network leg to bypass. Residual: the lane is pass-through, so deep content DLP on legitimately-written objects stays broker-side (NFR-SEC-81) — content-blind theme, [#182](https://github.com/Wide-Moat/open-computer-use/issues/182). |
+| Data-plane client replays / forges / frames the embed token | P4-S3 (NFR-SEC-82 + SEC-83) | Verify before minting a first-party session; `frame-ancestors` allowlist denies cross-origin framing. Residual: no replay-binding (`jti`/nonce) within TTL — embed-token replay, [#217](https://github.com/Wide-Moat/open-computer-use/issues/217). |
+| Cross-site forgery against the first-party cookie / token leak via `Referer` | P4-T3 (NFR-SEC-84 + SEC-82) | First-party cookie with server-validated CSRF token on every mutating call; 401 on missing/invalid session. Residual: token-pattern + `exp`-in-URL hardening, [#187](https://github.com/Wide-Moat/open-computer-use/issues/187). |
+| Forged/swapped id read, preview leak via `postMessage('*')`, or `downloadable=false` bytes shipped | P4-I3 (NFR-SEC-49 + SEC-73 + SEC-83) | Three-axis authz re-derived from the host-attested session; preview read-only and non-downloadable; framing closed by the allowlist. Residual: per-object authz granularity, [#187](https://github.com/Wide-Moat/open-computer-use/issues/187); preview-render parser isolation, [#218](https://github.com/Wide-Moat/open-computer-use/issues/218). |
+| North-face inbound-byte flood: pre-auth verify-cost, oversized upload, zip-bomb preview | P4-D3 (NFR-SEC-78 + SEC-80) | Body capped and rejected pre-buffer on a file/UI ingress distinct from the MCP listener; archive validated before extraction; content classified on ingest. Residual: pre-auth verify-cost flood — resource-exhaustion theme, [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). |
+| North-face upload/download/delete/preview later disputed | P4-R2 (NFR-SEC-79 + SEC-09) | OCSF File System Activity event per operation, fail-closed, under host-attested identity, before the response is issued. Residual: binding OCSF `actor` to the embed-asserted principal, [#181](https://github.com/Wide-Moat/open-computer-use/issues/181). |
+| Client flips intent/tag to escalate `preview`→`download`/`write`, or crafted id drives SSRF/path escape | P4-E3 (NFR-SEC-49 + SEC-73 + SEC-80) | Lease scoped to verb + exact prefix, failing at the backend not only at policy; preview stays read-only; traversal/polyglot rejected pre-extraction. Residual: per-action granularity, [#187](https://github.com/Wide-Moat/open-computer-use/issues/187). |
+| Compromised/impersonated broker reaches backend objects outside any live session | P4-S2 (NFR-SEC-25) | Full shelf: STS-scoped-per-session backend creds, so only the narrow per-session role is assumable. Residual: minimal-shelf host-local credential is broader (whole-bucket on broker-host compromise), admitted only under single-tenant `trusted_operator` (NFR-SEC-60) — called out by the shelf split (§Operational concerns). |
+| Backend credential disclosed via process compromise / memory scrape / leak onto mount | P4-I1 (NFR-SEC-25 + SEC-33) | Credential host-side only, no object-store protocol toward the guest; full shelf narrows the held secret to an STS-scoped-per-session credential. Residual: minimal-shelf long-lived host-local credential, [#187](https://github.com/Wide-Moat/open-computer-use/issues/187). |
+
+P4-S1 (south-face spoofing, NFR-SEC-43 + SEC-25), P4-T2 (backend leg in transit, NFR-SEC-05 + SEC-33), and P4-R1 (south-face attribution, NFR-SEC-43 + SEC-03 + SEC-25) are MITIGATED in §4 and are not live failure modes here.
+
+## Operational concerns
+
+Config surface: the `filesystem_id`→prefix map, the north-face ingress binding (distinct from the MCP listener), the embed-token issuer/audience, the `frame-ancestors` per-deployment allowlist, and the inbound-body / archive ceilings (NFR-SEC-78, NFR-SEC-80; literal defaults fixed in [`08-contracts.md`](../08-contracts.md) §3). Observability is the OCSF File System Activity stream (invariant 8) plus per-session rate counters.
+
+The container emits OCSF on the audit fan-in flow F10, fail-closed, per the audit contract ([`audit-fanin`](../../../contracts/audit/audit-fanin.asyncapi.yaml)) and NFR-SEC-03 / NFR-SEC-79 — both faces author the same File System Activity event class.
+
+Scaling axis: per-tenant instantiation (NFR-SEC-76) — one broker principal per tenant filesystem scope. Whether that principal is also per-sandbox-host or per-deployment, and whether that changes the container diagram, is open ([#175](https://github.com/Wide-Moat/open-computer-use/issues/175)). Capacity is bounded by the per-session file-op and inbound-byte ceilings (NFR-SEC-46, NFR-SEC-78); a one-per-host broker serving many sessions is a shared DoS surface, which is why those ceilings are per-session, not per-broker.
+
+Shelf delta (from [`05-c4-container.md`](../05-c4-container.md) §5): the minimal shelf holds a host-local backend credential, admitted only under `workload_trust_profile = trusted_operator` and single-tenant (NFR-SEC-60); the full shelf uses a customer-PKI workload identity with STS scoped per session (NFR-SEC-25). All invariants hold on both shelves; only the credential substrate and its blast radius (P4-S2 / P4-I1 residual) change. The backend engine is a pluggable adapter behind the object-store client ([ADR-0010](../adr/0010-storage-backend-pluggable-adapter.md)): a local-volume engine (the solo-reference, no network leg) and an S3 engine are both present from day one, and the egress-transit invariant applies only to a network engine's leg. The broker runs at the [NFR-SEC-02](../manifesto/02-nfrs.md) hardened-`runc` floor (seccomp BPF + Landlock + cap-drop ALL + read-only rootfs), profile-independent: it executes no agent-issued code, so it carries no `workload_trust_profile` tier axis (that axis is the sandbox's, [NFR-SEC-38](../manifesto/02-nfrs.md)) and no separate tier ladder. Its blast-radius is bounded by the credential substrate ([NFR-SEC-60](../manifesto/02-nfrs.md) / [NFR-SEC-25](../manifesto/02-nfrs.md)) and host-peer accept ([NFR-SEC-76](../manifesto/02-nfrs.md)), not by a runtime-tier ladder. The cardinality question — one broker per deployment or per sandbox host — stays open ([#175](https://github.com/Wide-Moat/open-computer-use/issues/175)).
+
+## Open questions
+
+1. Is the broker one instance per deployment or one per sandbox host, and does the answer change the container diagram? — [#175](https://github.com/Wide-Moat/open-computer-use/issues/175).
+2. Embed-token replay-binding (`jti`/nonce single-use or token↔channel binding) within the `exp` window — [#217](https://github.com/Wide-Moat/open-computer-use/issues/217).
+3. Preview-render parser isolation for untrusted artifact bodies on the north face — [#218](https://github.com/Wide-Moat/open-computer-use/issues/218).
+4. Per-action / per-object authorization granularity and minimum lease scope beyond resource-class — [#187](https://github.com/Wide-Moat/open-computer-use/issues/187).

package/docs/architecture/components/05-session-sandbox.md

@@ -0,0 +1,93 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-05-31
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+compliance: []
+threat-model: 06-threat-model.md
+contract: contracts/exec/exec-channel.schema.json
+adr: [0003]
+---
+
+Internal design of the per-session execution container, for engineers implementing and auditing the guest agent and its host-side edges. The guest agent is the process that constitutes this container ([`05-c4-container.md`](../05-c4-container.md) §3): it is PID 1 and dies with the session.
+
+# Component-05: Session sandbox
+
+## Purpose
+
+Executes one session's tool-calls in an isolated runtime that holds no standing upstream secret and reaches the network only through the Egress trust-edge ([`05-c4-container.md`](../05-c4-container.md) §3). Spec scope is the intra-container split — the guest agent, the host-side exec supervisor, and the mount and egress edges the guest sees — not the inter-container flows Layer 6 already fixes.
+
+## Boundaries
+
+Intra-container, the container is one process tree rooted at the guest agent (PID 1). Two host-side mediators sit outside the guest's network yet terminate the channels the guest uses: a per-session exec supervisor (terminates the exec WebSocket, spawns and reaps guest processes, bounds stdio) and the runtime supervisor (the user-space-kernel sentry on the gVisor tier, the VMM on the microVM tier, the host kernel on runc). The mount and egress edges are owned by other containers (Storage broker, Egress trust-edge); the guest holds only the handle and the route, never the credential.
+
+| Direction | What crosses | Internal terminator | Note |
+|---|---|---|---|
+| host → guest | exec/PTY+CDP control union + stdin frames | exec supervisor (host-dialled; non-host peer dropped at accept) | one WebSocket per session; envelope frozen in [`exec/exec-channel`](../../../contracts/exec/exec-channel.schema.json) |
+| guest → host | stdout/stderr binary frames + result/EOF | exec supervisor | length-prefixed, bounded per call (Invariants) |
+| host → guest | Session JWT (selects session identity) | guest agent | Session JWT class, TTL per [`02-trust-boundaries.md`](../02-trust-boundaries.md) §8 |
+| broker → guest | file-operation mount + Storage-mount handle | guest agent (mount client) | guest names file-op verbs, never the object-store protocol; substrate is named by role |
+| guest → edge | outbound network leg | guest agent | guest carries no long-lived upstream secret on this leg; the edge attaches upstream authorization ([ADR-0005](../adr/0005-egress-credential-delivery-envoy-sds.md), [ADR-0007](../adr/0007-egress-auth-mechanism.md)) keyed on a presented scoped credential, never on the route's network origin; this route is the container's sole egress (invariant 4) |
+| guest → audit | OCSF tool-call events (fan-in flow F10, defined in [`05-c4-container.md`](../05-c4-container.md) §4) | exec supervisor / runtime-monitor | host-authored, not guest-authored (Operational concerns) |
+
+The inbound exec/PTY+CDP edge, the broker mount edge, and the outbound egress leg are the boundaries [`05-c4-container.md`](../05-c4-container.md) §4 names; their `F6`/`F7`/`F8` flow labels are defined in [`05-c4-container.md`](../05-c4-container.md) §4.
+
+Owned state: the live process tree and its scratch/tmpfs, the per-process resource counters the exec supervisor keeps, and the guest's in-memory Session JWT and Storage-mount handle for the life of the session. It provably does NOT hold any upstream/backend credential, the Custody credential lease, the session denylist, or any kill-switch route — those sit host-side of the guest. The guest resolves no name for the Control plane or the Storage broker; those are reached over the host-opened off-network channel, so no guest-side lookup exists to retarget.
+
+The contract carries the tagged-JSON control union and out-of-band binary stdio frames; field types and the bounded-reason error envelope live in the schema and are not restated. The schema does not encode two facts: the exec supervisor — not the guest — terminates the socket, and the runtime tier is selected by `workload_trust_profile`, not by the contract. The schema records the spawn-time environment fields; it does not pin which component enforces the strip — that actor is the host supervisor (Invariants).
+
+## Invariants
+
+Each is falsifiable by the named check; cross-cutting zone, egress-mode, retention, and isolation-tier-menu properties stay in Layer 3.
+
+1. The guest agent is PID 1 and the container holds no process or token that outlives the session; teardown kills the process tree and destroys the cgroup (integration-test, NFR-REL-11).
+2. The exec/PTY+CDP channel is a single host-dialled socket per session; a connection from any non-host peer is dropped at accept before any frame is parsed (accept-time negative-test, NFR-SEC-76 — the accept-time enforcement of NFR-SEC-43, scoped here to the Control listener).
+3. Guest-originated code cannot reach the control/exec channel through the guest's own network stack, and a guest with in-sandbox root cannot present another session's identity (integration negative-test: guest-stack dial fails, forge-another-session fails — NFR-SEC-43).
+4. The container has exactly one outbound network route and it is the Egress trust-edge; there is no second NIC or route (IaC-policy assertion, NFR-SEC-27).
+5. Inter-sandbox reachability is disabled by default; tenant A's sandbox cannot reach tenant B's without an explicit policy (NetworkPolicy + integration-test, NFR-SEC-22).
+6. Every container carries `no-new-privileges`, cap-drop ALL with minimal add-back, seccomp BPF, read-only rootfs, user-namespace mapping (host UID 0 ≠ guest UID 0), and pids/cpu/mem cgroup limits; `docker.sock` is never mounted (admission-gate, NFR-SEC-14).
+7. The configured runtime tier matches the deployment's declared `workload_trust_profile` per the pairing matrix; a mismatch is an admission-time hard error (admission test fixture, NFR-SEC-38).
+8. A guest-spawned process inherits no host secret: the host supervisor strips the deny-pattern env set (`*_TOKEN`/`*_SECRET`/`*_PASSWORD`/`API_KEY`) at fork and injects only declared vars; no secret rides on argv (spawn-time fixture + property-test, NFR-SEC-75).
+9. Per-stream stdout/stderr over the exec channel is framed, length-prefixed, and bounded per call; on reaching the ceiling the supervisor stops forwarding, emits a truncation marker with a dropped-byte count, and never buffers unbounded guest output into host memory or the audit pipeline (red-team output-flood suite, NFR-SEC-74).
+10. Per-sandbox resource use is contained beyond the cgroup ceiling — scratch disk quota and deterministic OOM scoping (the breaching sandbox is the victim) — so one sandbox's flood holds co-resident sandboxes within the noisy-neighbour latency budget (red-team noisy-neighbour suite, NFR-SEC-46).
+11. No session-scoped secret is present in guest RAM or disk at snapshot-create time, and on resume the guest re-derives a fresh host-attested identity and reseeds entropy and unique IDs so no two guests restored from one image share a token, nonce, RNG stream, or `boot_id` (offline image-extraction scan + N-fork uniqueness test, NFR-SEC-44 + NFR-SEC-71).
+12. Every TTL/expiry decision the guest is subject to reads a monotonic clock immune to wall-clock setback, and on resume the wall clock is corrected before any time-bound check runs (red-team clock-rollback harness, NFR-SEC-48 + NFR-SEC-63 — theme [#185](https://github.com/Wide-Moat/open-computer-use/issues/185), owned by [`02-trust-boundaries.md`](../02-trust-boundaries.md)).
+
+## Failure modes
+
+Each row traces to one P5 STRIDE row in [`06-threat-model.md`](../06-threat-model.md) §3.1 and repeats that row's controlling NFR; the threat narrative, rating, and regulator cell stay there. A1 (the in-sandbox guest holding root) is the reaching actor for the §3.1 rows; A3 (post-escape or host foothold) for the at-rest snapshot row.
+
+| Trace | Reaching actor | Container-internal recovery behaviour | Controlling NFR |
+|---|---|---|---|
+| P2-T2 | A1 | Guest stalls or drops the host-dialled control RPC to outlive a revoke/kill. Recovery is owned by the Control/operator API ([`02-control-operator-api.md`](02-control-operator-api.md)): the F6 denylist/kill-switch check is host-side, so an unreachable channel grants the guest no new authority. | NFR-SEC-01 |
+| P5-D1 | A1 | Guest exhausts node resources (fork-bomb, disk fill, memory pressure). Fail-closed via the cgroup PID/CPU/mem ceiling plus scratch quota and deterministic OOM scoping — the offender is the OOM/quota victim, co-residents hold SLO. Residual: per-session quota precision — resource-exhaustion theme [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). | NFR-SEC-14 + NFR-SEC-46 + NFR-SEC-74 |
+| P5-D2 | A1 | Guest floods the edge to deny outbound for itself and co-tenants. Single forward route, deny-by-default; fail-closed drops outbound if the proxy is unreachable rather than bypassing. Residual: per-session egress rate-limit unstated — resource-exhaustion theme [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). | NFR-SEC-05 + NFR-SEC-27 |
+| P5-I1 | A1 | Guest mounts a microarchitectural side-channel against a co-resident tenant. Per-tier posture: the shared-kernel residual is declared-not-eliminated; the reduced tier pins SMT-off, current microcode, and single-tenant scheduling for flagged sessions. Residual: a measurable cross-tenant target — side-channel theme [#183](https://github.com/Wide-Moat/open-computer-use/issues/183), [#148](https://github.com/Wide-Moat/open-computer-use/issues/148). | NFR-SEC-58 |
+| P5-I3 | A1 | Guest tunnels tenant data to an allow-listed destination over the content-blind transparent pass-through rung. The container's only recovery is a single deny-by-default forward route plus a payload-independent egress-byte / destination-cardinality tripwire emitted to audit and SOAR; deep content inspection runs on the egress-wide-bump leg ([ADR-0007](../adr/0007-egress-auth-mechanism.md)), owned by the Egress trust-edge ([`06-egress-trust-edge.md`](06-egress-trust-edge.md), F8). Residual: content-blind transparent egress — theme [#182](https://github.com/Wide-Moat/open-computer-use/issues/182). | NFR-SEC-57 |
+| P5-I4 | A1 | A guest-spawned process inherits a host-env secret, or a secret on argv leaks via `/proc/<pid>/cmdline`. Allowlist-only env injection with the deny-pattern strip at fork; secrets pass via env or fd, never argv. | NFR-SEC-75 + NFR-SEC-43 |
+| P5-T1 | A1 | With root the guest suppresses, fabricates, or reorders the OCSF events it would author for its own in-sandbox actions. The guest is never the authoritative source: a host-side mediation layer and a not-guest-disableable runtime-monitor session author the record out of band. Residual: purely in-sandbox actions with no host-side side-effect — guest-self-audit theme [#181](https://github.com/Wide-Moat/open-computer-use/issues/181). | NFR-SEC-47 |
+| P5-R1 | A1 | An in-sandbox action cannot be non-repudiably attributed because its only candidate record originates inside the guest. Out-of-band host-authored evidence supplies the record and the monotonic-clock envelope orders accepted events. Residual: the in-sandbox-evidence gap (theme [#181](https://github.com/Wide-Moat/open-computer-use/issues/181)) plus the clock-trust dependency (theme [#185](https://github.com/Wide-Moat/open-computer-use/issues/185)). | NFR-SEC-47 + NFR-SEC-48 |
+| P5-I2 | A3 | A snapshot/hibernation image freezes a live Session JWT and mount handle at rest; an image read recovers a usable token before TTL. The image is taken at minimal-init before session material is layered, live token buffers are zeroized before a retained hibernate, and a single-restore guard prevents fork replay. Residual: a live secret in an off-cycle image — snapshot theme [#184](https://github.com/Wide-Moat/open-computer-use/issues/184). | NFR-SEC-44 + NFR-SEC-66 |
+
+The host-facing default is fail-closed on every boundary the guest can pressure: an unreachable exec channel, a dropped egress route, and a failed teardown each deny authority rather than degrade open. Sandbox escape to the host kernel and the exec/PTY+CDP channel-spoof variants are MITIGATED in [`06-threat-model.md`](../06-threat-model.md) §4 (NFR-SEC-02/14, NFR-SEC-43) and are not live rows here.
+
+## Operational concerns
+
+Scaling axis is per session — one container per session `[1..N]`, lifecycle bound to the session ([`05-c4-container.md`](../05-c4-container.md) §3). Capacity is governed by the host substrate and the per-sandbox cgroup ceiling (NFR-SEC-14); session-create targets ≤500 ms p99 warm-pool-hit (NFR-PERF-02), ≤2 s p99 cold-start (NFR-PERF-03), with ≤400 ms p99 on the user-space-kernel substrate (NFR-PERF-08). Compute-plane RTO for new sessions is ≤30 min with in-flight state non-durable (NFR-REL-02); stateful hibernate/resume/snapshot/fork is demonstrated end-to-end (NFR-REL-08). Cooperative shutdown is `terminationGracePeriodSeconds=30`, SIGTERM→5 s→SIGKILL, tmpdir clean ≤10 s (NFR-REL-11); teardown then runs a host-driven ordered finalizer that revokes the lease, drops the outbound route, and scrubs writable surfaces before kill, independent of guest cooperation (NFR-SEC-65). A guest that ran a session is destroyed, never re-pooled (NFR-SEC-68); a warm-pool claim re-derives a fresh host-attested identity and discards the pre-warm placeholder (NFR-SEC-69).
+
+Config surface: the runtime tier (set by `workload_trust_profile`, validated at admission — NFR-SEC-38), the cgroup/quota ceilings (NFR-SEC-14, NFR-SEC-46), the per-stream stdio ceiling (default ≤8 MiB/stream, retunable per tier — NFR-SEC-74), the spawn-time env allowlist (NFR-SEC-75), and the exec-channel capability flags negotiated in the handshake (trace, compression — see the contract). Concurrency on the exec channel is sequential-default with opt-in parallelism (NFR-IC-05); PTY and CDP multiplex one socket per session (NFR-IC-03).
+
+Observability: the container emits OCSF on fan-in flow F10, but the in-sandbox tool-call events are host-authored by the exec supervisor and the runtime-monitor — never the guest — per the audit contract and NFR-SEC-47 + NFR-SEC-03; the guest is not a trusted audit source for its own actions. A tier-downgrade of a running deployment fires `config.trust_profile.downgraded` within ≤30 s (NFR-SEC-39).
+
+Shelf delta ([`05-c4-container.md`](../05-c4-container.md) §5, [`02-trust-boundaries.md`](../02-trust-boundaries.md) §8): the boundary invariants above hold on both shelves and only the substrate changes. The runtime supervisor that backs invariants 2–3, 9, and 11 is the host kernel with UDS peer-credential checks on the container tiers and the VMM with vsock on the microVM tier; the predicates (host-dialled channel, bounded stdio, no live secret in the image) do not change. The runtime-tier substrate and packaging pick is a future ADR; the FLEX-02 runtime ladder fixes the tier set, not the implementation.
+
+## Open questions
+
+1. Does the Session sandbox stay one container with internal components, or split into sub-containers once the workload-trust tier and guest-agent protocol are specified? — [#174](https://github.com/Wide-Moat/open-computer-use/issues/174).
+2. Is workload-trust tier grading (`workload_trust_profile`, AP-13) a sub-context of its own, distinct from the session-lifecycle language inside Agent Execution? — [#168](https://github.com/Wide-Moat/open-computer-use/issues/168).
+3. A measurable cross-tenant side-channel target on the shared-kernel tier ("tenant A cannot observe tenant B") is not yet an NFR scenario. — [#183](https://github.com/Wide-Moat/open-computer-use/issues/183), [#148](https://github.com/Wide-Moat/open-computer-use/issues/148).
+4. Out-of-band evidence for purely in-sandbox actions with no host-side side-effect, and host-attested binding of the OCSF source at ingestion. — [#181](https://github.com/Wide-Moat/open-computer-use/issues/181).
+5. Deterministic per-session erasure ordering and the live-secret-in-off-cycle-image residual on teardown/snapshot. — [#184](https://github.com/Wide-Moat/open-computer-use/issues/184).

package/docs/architecture/components/06-egress-trust-edge.md

@@ -0,0 +1,95 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-03
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+compliance: []
+threat-model: 06-threat-model.md
+contract: null
+adr: [0005, 0006, 0007, 0008, 0011]
+---
+
+The sandbox's sole outbound network path: it enforces a deny-by-default destination allow-list, emits a structured deny reason, and on the legs that need it attaches the upstream authorization received over Envoy SDS so the guest carries no long-lived upstream secret on the egress leg. Audience: engineers and security reviewers wiring or auditing egress policy.
+
+# Component-06: Egress trust-edge proxy
+
+## Purpose
+
+The single outbound path for the sandbox: it resolves each destination against a deny-by-default allow-list and, on a bump-rung leg only, originates the upstream connection so it can attach the authorization received over Envoy SDS that the guest never holds ([`05-c4-container.md`](../05-c4-container.md) §3). The destination-to-rung binding is per-destination state held only at the edge, so one egress process serves a transparent-pass-through leg and an egress-wide-bump leg at once.
+
+## Boundaries
+
+The intra-container view. The inbound sandbox leg, the broker backend leg, and the audit fan-in are the boundaries [`05-c4-container.md`](../05-c4-container.md) §4 names; their `F8`/`F9`/`F10` flow labels are defined in [`05-c4-container.md`](../05-c4-container.md) §4. The upstream credential arrives over Envoy SDS, an external input to the edge, not an internal OCU boundary. Token classes are owned by [`02-trust-boundaries.md`](../02-trust-boundaries.md) §8; TTLs are not repeated here.
+
+The edge is the off-the-shelf Envoy proxy with three internal faces and one external input:
+
+| Internal face | What it does |
+|---|---|
+| sandbox listener | accepts the guest's outbound request on the network-bound default route — the request carries no long-lived upstream secret; a presented scoped credential, if any, gates injection |
+| upstream originator | resolves the destination, and on a bump-rung leg terminates and re-originates the TLS with the authorization attached by Envoy's `credential_injector` filter |
+| audit emitter | emits an OCSF allow/deny event, denials carrying the `x-deny-reason` vocabulary |
+
+The credential receiver is Envoy's SDS client: it receives the upstream credential over Secret Discovery Service (SDS, gRPC xDS) from the SDS source and binds it for injection on the outbound leg. The source is a static file (solo deployments) or a customer-provided SDS-compatible store (enterprise deployments); its lifecycle is the source's, per [ADR-0005](../adr/0005-egress-credential-delivery-envoy-sds.md).
+
+Owned state: the destination allow-list (resolved-IP + SNI rules) and the per-destination rung binding (transparent pass-through vs egress-wide bump). The edge receives the credential from SDS at injection time, attaches it for the upstream leg, and drops it after the connection terminates; it holds no credential at rest and no rotation or revocation responsibility ([NFR-SEC-29](../manifesto/02-nfrs.md)). It authors no denylist and holds no kill-switch route — the denylist is the Control/operator API's; the edge reads it as a deny signal. It holds no object-store credential — the broker signs its own backend leg ([NFR-SEC-25](../manifesto/02-nfrs.md)), and the broker backend leg (F9) traverses a storage-dedicated lane on the edge, distinct from the guest egress lane ([NFR-SEC-85](../manifesto/02-nfrs.md)), with no TLS termination, so the broker-produced signature is forwarded byte-intact.
+
+Token classes ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §8 owns the taxonomy): the edge presents the SDS-delivered authorization upstream; the guest-facing leg carries no long-lived upstream secret — at most a short-lived scoped credential the guest presents to gate injection, never the upstream key. The upstream credential is delivered by Envoy SDS, off-the-shelf and external to OCU, not an OCU-defined wire surface. The outbound leg (F8) is a network property with no wire schema by design ([NFR-SEC-27](../manifesto/02-nfrs.md)); the broker backend leg (F9) is conform on its storage-dedicated lane ([NFR-SEC-16](../manifesto/02-nfrs.md), [NFR-SEC-85](../manifesto/02-nfrs.md)). The downloadable axis reaches the edge as a broker-resolved deny signal, not a field the guest's outbound request carries ([NFR-SEC-73](../manifesto/02-nfrs.md)).
+
+## Invariants
+
+Each rule holds independent of the caller and is falsifiable by the named check. Egress *posture* (the §7 rung ladder), in-transit-encryption carve-outs, and zone membership are Layer 3 properties, not invariants here.
+
+- Every outbound connection resolves through this process; the sandbox has no route out other than F8 (network-policy IaC assertion, [NFR-SEC-27](../manifesto/02-nfrs.md)).
+- A destination not matched by an allow-list rule is dropped before the TLS handshake at the SNI pre-filter, with no partial connect (integration test, [NFR-SEC-08](../manifesto/02-nfrs.md), [NFR-SEC-17](../manifesto/02-nfrs.md)).
+- The proxy-owned resolver is the sole resolution authority: a guest-supplied A/AAAA cannot override it for an egress destination, and the mandatory deny-set is filtered on resolved IP at connect, never on DNS resolution (unit test per rejection class + in-guest rebind negative test, [NFR-SEC-12](../manifesto/02-nfrs.md)).
+- Every denied connection is a machine-parseable object carrying the `x-deny-reason` vocabulary, never free text (schema-validation, [NFR-SEC-17](../manifesto/02-nfrs.md)).
+- Injection is reachable only on the edge-originated upstream leg of a bump-rung destination; the guest→edge leg and every transparent-pass-through leg carry no upstream credential (integration test asserting no credential in the guest, [NFR-SEC-23](../manifesto/02-nfrs.md), [NFR-SEC-27](../manifesto/02-nfrs.md)).
+- Injection is gated on a scoped credential the request presents, never on its network origin alone: a request reaching a bump-rung destination but presenting no scoped credential is forwarded with none attached — "inject because traffic came from sandbox X" is the forbidden anti-pattern ([ADR-0007](../adr/0007-egress-auth-mechanism.md), tightening P6-E2; bare-request negative test, [NFR-SEC-23](../manifesto/02-nfrs.md), [NFR-SEC-29](../manifesto/02-nfrs.md)).
+- The injected authorization never reaches a guest-visible response surface; it is stripped before any response crosses back to the guest leg (integration test, [NFR-SEC-23](../manifesto/02-nfrs.md)).
+- When the denylist names a session, the edge attaches no credential for it, independent of the credential's own validity window (integration test, [NFR-SEC-04](../manifesto/02-nfrs.md), [NFR-SEC-29](../manifesto/02-nfrs.md)).
+- An outbound leg for an object the broker resolved `downloadable=false` is denied with a structured reason at every egress rung (edge integration test, [NFR-SEC-73](../manifesto/02-nfrs.md)).
+- A destination tagged allow-list-only is forwarded byte-intact; the edge never terminates or re-signs the broker backend leg (integration test, [NFR-SEC-16](../manifesto/02-nfrs.md), [NFR-SEC-25](../manifesto/02-nfrs.md)).
+- Denylist-propagation timing reads a monotonic clock, so a wall-clock setback cannot stall the revoke signal past its window (clock-rollback red-team harness, [NFR-SEC-48](../manifesto/02-nfrs.md), [NFR-SEC-63](../manifesto/02-nfrs.md)).
+
+## Failure modes
+
+Each row traces to one P6/P5 STRIDE row in [`06-threat-model.md`](../06-threat-model.md) §3 and repeats that row's controlling NFR; the actor labels are owned by [`06-threat-model.md`](../06-threat-model.md) §2 (A1 in-sandbox guest, A3 host-side). Fail-closed is the default on every egress, injection, and deny boundary.
+
+| Trace | Reaching actor | What goes wrong | Recovery behaviour | Controlling NFR |
+|---|---|---|---|---|
+| P6-R1 | A1 | A policy-violating egress attempt is later disputed and the decision, destination, and injected-or-not are not durably recorded | Emit OCSF on F10 for every allow and deny; denials carry the structured `x-deny-reason`; SNI pre-filter drops and L7 inspections both record | NFR-SEC-03 |
+| P6-I1 | A1 | Content-blind exfil: the guest tunnels data to an allow-listed destination over the transparent pass-through rung (non-inspecting) | Allow-list narrows destinations; the payload-independent byte/cardinality tripwire arms at every rung; deep DLP requires the egress-wide-bump rung | NFR-SEC-57, NFR-SEC-73 |
+| P6-I2 | A1 | The injected credential leaks back to the guest via an error, redirect, or reflected header at the egress-wide-bump rung | Strip injected authorization from every response surface before it crosses to the guest leg; injection only on the edge-originated leg; the credential is received from SDS at injection and never persisted at the edge | NFR-SEC-23, NFR-SEC-29 |
+| P6-I3 | A3 | The bump-rung decrypt/re-encrypt segment exposes plaintext at the edge in memory or swap | The bump rung is per-destination, a single named inspection segment, TLS 1.3 on both legs; transparent-pass-through and broker legs never terminate | NFR-SEC-05, NFR-SEC-33 |
+| P6-E1 | A1 | Allow-list bypass via SNI≠Host domain-fronting, CONNECT abuse, DNS rebinding, or raw-IP / non-HTTP | Deny-by-default; SNI pre-filter drop before TLS; L7 SNI/Host consistency check on the inspected leg; proxy-owned resolver | NFR-SEC-27, NFR-SEC-05, NFR-SEC-16 |
+| P6-E2 | A1 | The guest forces injection toward an unintended destination via a cross-scope allow-list entry or open redirect on an allowed upstream | Gate injection on the scoped credential the request presents, never on its network origin alone ([ADR-0007](../adr/0007-egress-auth-mechanism.md)); attach only the SDS-delivered credential matching the validated destination; credential scope is set at the SDS source, so a mis-routed credential stays bounded to the scope the source supplied | NFR-SEC-29, NFR-SEC-23, NFR-SEC-73 |
+| P6-E3 | A1 | The upstream needs client-mTLS / cert-pin / DPoP, which header-token injection cannot satisfy | The customer configures the SDS source to supply the client cert / PoP key, re-originated at the bump rung; a source that cannot supply it makes the destination incompatible at config time with a structured deny; a guest-resident-key workaround is refused | NFR-SEC-50 |
+| P6-D1 | A1 | The edge is made unreachable by a crash, connection flood, or upstream-timeout storm, losing the sole outbound path | Fail-closed: outbound traffic drops, never bypasses; unallowed destinations dropped cheaply at the SNI pre-filter before TLS to bound handshake-exhaustion cost | NFR-SEC-46, NFR-SEC-53 |
+| P6-D3 | A3 | Clock rollback at the edge defeats denylist-propagation timing | Denylist propagation reads a monotonic clock; the denylist is also checked directly on every injection, giving a non-clock revoke path | NFR-SEC-48, NFR-SEC-63 |
+| P6-T1 | A3 | At the egress-wide-bump rung the edge holds plaintext between decrypt and re-encrypt; a compromised edge alters bodies undetected | The bump rung is per-destination, customer-CA-rooted, TLS 1.3 on both legs; the carve-out is a single auditable inspection point | NFR-SEC-05, NFR-SEC-33 |
+| P5-D2 | A1 | The guest floods the edge with connection/request volume to deny outbound to co-tenant sessions or amplify against an upstream | Single forward proxy bounds reachable destinations; fail-closed drops rather than bypasses; per-session egress rate / connection quota | NFR-SEC-05, NFR-SEC-27 |
+
+Residual, by [`06-threat-model.md`](../06-threat-model.md) §5 register: the transparent (non-inspected) leg stays content-blind, so P6-I1 records only metadata and P6-R1 can dispute only metadata — content-blind transparent egress, accepted-with-tier ([#182](https://github.com/Wide-Moat/open-computer-use/issues/182)). The no-credential-in-response stripping behind P6-I2, the edge-binary/config attestation behind P6-T1, and the plaintext-zeroization behind P6-I3 lack an explicit NFR ([#197](https://github.com/Wide-Moat/open-computer-use/issues/197)). SNI/Host consistency on the transparent leg behind P6-E1 is unenforced ([#198](https://github.com/Wide-Moat/open-computer-use/issues/198)). The destination-to-lease binding and per-action authz behind P6-E2 are tracked at [#187](https://github.com/Wide-Moat/open-computer-use/issues/187); the guest-resident-key schemes behind P6-E3 are declared unsupported ([#176](https://github.com/Wide-Moat/open-computer-use/issues/176)). The per-sandbox egress conn-rate / fd containment behind P6-D1 / P5-D2 is the resource-exhaustion theme — NFR-SEC-46 is the edge control and NFR-SEC-53 the sibling MCP-gateway-listener ceiling ([#188](https://github.com/Wide-Moat/open-computer-use/issues/188)). Clock-rollback behind P6-D3 is the trusted-time theme ([#185](https://github.com/Wide-Moat/open-computer-use/issues/185)). The MITIGATED P6 rows (the listener spoof, the bump-rung upstream spoof, the broker-leg tamper) live in [`06-threat-model.md`](../06-threat-model.md) §4.
+
+## Operational concerns
+
+**Config surface.** The allow-list (resolved-IP + SNI rules per destination), the per-destination egress rung ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §7), the proxy-owned resolver and its deny-set (the canonical list is in [NFR-SEC-12](../manifesto/02-nfrs.md), enforced by the resolver invariant above), and the per-session egress rate / connection ceilings. DLP-ICAP is a configuration of the egress-wide-bump rung, not a separate rung ([NFR-FLEX-15](../manifesto/02-nfrs.md), [NFR-COMP-28](../manifesto/02-nfrs.md)).
+
+**Observability.** The edge emits an OCSF event for every allow and deny on fan-in flow F10, denials carrying the `x-deny-reason`, against the audit contract ([`08-contracts.md`](../08-contracts.md) §1) and [NFR-SEC-03](../manifesto/02-nfrs.md). The payload-independent exfil tripwire ([NFR-SEC-57](../manifesto/02-nfrs.md)) raises a structured OCSF anomaly event in both postures.
+
+**Scaling axis.** A per-host shared edge serves many co-located sessions, which makes it a shared DoS surface (P5-D2 / P6-D1); the per-session rate / fd ceiling under [NFR-SEC-46](../manifesto/02-nfrs.md) is the containment, with [NFR-SEC-53](../manifesto/02-nfrs.md) bounding the sibling MCP-gateway listener, not the edge. Whether the edge is one-per-host or one-per-deployment tracks the same instantiation question as the broker ([#175](https://github.com/Wide-Moat/open-computer-use/issues/175)).
+
+**Rotation / lifecycle.** The edge receives the credential from SDS per-connection and drops it after use; rotation belongs to the SDS source, not the edge ([NFR-SEC-04](../manifesto/02-nfrs.md)). On sandbox teardown the host-driven finalizer drops the network-bound egress route host-side even if the guest is unresponsive ([NFR-SEC-65](../manifesto/02-nfrs.md)).
+
+**Shelf delta** ([`05-c4-container.md`](../05-c4-container.md) §5): egress posture is a ladder by need ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §7, [ADR-0007](../adr/0007-egress-auth-mechanism.md)). A deployment with no outbound need runs deny-all; one needing only unauthenticated internet runs transparent pass-through (no CA) and cannot inject; one with an upstream credential configured runs egress-wide bump — a per-deployment CA auto-generated and its public cert auto-injected into the sandbox trust store at start, attaching the credential on the edge-originated leg. The enterprise shelf points the credential at a customer-provided SDS source. The boundary properties in the Invariants section hold at every rung; the CA and the TLS-termination capability appear at the bump rung. Envoy is the forward-proxy substrate ([ADR-0006](../adr/0006-egress-forward-proxy-substrate.md)); the bump rung terminates with a leaf minted per SNI from that CA — pre-minted over a file SDS source for a config-time-enumerable allow-list, or a self-hosted SDS minting service for a non-enumerable one ([ADR-0007](../adr/0007-egress-auth-mechanism.md)).
+
+## Open questions
+
+1. Envoy's `credential_injector` filter and its OAuth2 extension carry an upstream maturity caveat — not substantial production burn-in, an unknown security posture, intended for trusted-on-both-ends paths — while a third-party LLM API is an untrusted upstream. The regulated-tier posture for this filter is deferred pending a security review ([#240](https://github.com/Wide-Moat/open-computer-use/issues/240)).
+2. ~~MITM-termination technology undecided.~~ Resolved by [ADR-0007](../adr/0007-egress-auth-mechanism.md): the bump rung terminates with a leaf minted per SNI from a per-deployment CA, served by the Envoy data plane plus a self-hosted SDS minting service; a config-time-enumerable allow-list uses pre-minted leaves over a file SDS source instead. Selection between edge-inject and a protocol broker is per upstream; v1 ships edge-inject only.
+3. SNI/Host consistency on the transparent (non-inspected) leg, where the SNI pre-filter alone misses domain-fronting — [#198](https://github.com/Wide-Moat/open-computer-use/issues/198).
+4. No-credential-in-response stripping, edge-binary/config attestation, and plaintext-zeroization for the bump rung lack an explicit NFR — [#197](https://github.com/Wide-Moat/open-computer-use/issues/197).
+5. mTLS / cert-pin / DPoP upstreams the edge cannot serve by injection, and the guest-resident-key schemes declared unsupported — [#176](https://github.com/Wide-Moat/open-computer-use/issues/176).