@mseep/open-computer-use 1.0.0

package/docs/architecture/02-trust-boundaries.md

@@ -0,0 +1,224 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-06
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+## 1. Purpose and scope
+
+Our scope: `MCP interface / control-plane RPC → guest agent → sandbox runtime → Egress trust-edge + Storage broker`. Everything else is either an external actor (§3) or an outbound endpoint subject to the egress policy enforced by the Egress trust-edge.
+
+Ownership per row is named in [`02-nfrs.md`](manifesto/02-nfrs.md) §"Scope ownership": DELIVER (we ship + are accountable), ENABLE (we publish the contract/telemetry, customer owns the policy), REVISIT (claims more than our scope; flagged for re-cut). §02 marks each REVISIT row inline as `[REVISIT — non-gating]` so CI and verifier passes do not enforce it; the substantive re-cut of those rows lands in a follow-up PR.
+
+Product invariant from [NFR-SEC-16](manifesto/02-nfrs.md): the distributed configuration ships no outbound paths to vendor-controlled endpoints. On-prem deployments use only outbound paths the customer enabled.
+
+Measurable targets are in [`02-nfrs.md`](manifesto/02-nfrs.md); component internals are in [`components/`](./components/); threat content is out of scope here and lands when the threat-model artifact opens.
+
+## 2. Drawn zones
+
+| # | Zone | One-line role | §02 anchor |
+|---|---|---|---|
+| 1 | **Control plane** | Orchestrator + session lifecycle, exposing two interfaces of one zone: an agent-facing MCP interface (tool calls) and an operator/lifecycle interface (session lifecycle, quota, kill-switch). The kill-switch is reachable only on the operator interface, never over MCP. Single instance per deployment. Holds no outbound path to upstream; all upstream traffic originates in the Compute plane and traverses the Egress trust-edge. The Control plane is not a model proxy. The agent-facing / operator split becomes two containers at Layer 6; here it is one zone. | [NFR-IC-04](manifesto/02-nfrs.md) |
+| 2 | **Storage broker** | Host-side broker for the guest's mutable user-data mount. The guest speaks a file-operation interface (open / read / write / list) to the broker, not the object-store protocol; the broker is the object-store client and signs its own backend requests, so no middlebox ever rewrites a request signature. Holds the backend credential; the guest holds only a session-scoped resource handle (a `filesystem_id`), never the backend key ([NFR-SEC-25](manifesto/02-nfrs.md)). The broker's read authorization carries a third axis beyond scope and operation intent (`read` / `write` / `preview`) — a per-object `downloadable` tag resolved at read; a non-downloadable object is readable in-session but yields no egress-eligible artifact, and the tag reaches the Egress trust-edge as a deny signal, separating "may read" from "may remove from the sandbox" ([NFR-SEC-73](manifesto/02-nfrs.md)). The broker's backend traffic traverses a storage-dedicated lane on the Egress trust-edge — out-of-process from the broker, distinct from the guest egress lane ([NFR-SEC-85](manifesto/02-nfrs.md)) — in allow-list-only mode (no TLS termination) so the signature stays intact; content inspection, when required, happens at the broker on plaintext, before signing. The broker has two faces on one object-store client: the **south face** is the guest mount above; the **north face** is a data-plane client ingress — OCU's own file-artifact API and embeddable SPA — served on a dedicated file/UI ingress, not the MCP listener ([NFR-SEC-78](manifesto/02-nfrs.md)). The north face is a boundary crossing in its own right: an external Data-plane client (§3) reaches the host-side broker, the broker verifies a peer-minted embed token and sets a first-party session ([NFR-SEC-82](manifesto/02-nfrs.md)), and an uploaded body is archive-validated and content-classified before it becomes mount-visible ([NFR-SEC-80](manifesto/02-nfrs.md), [NFR-SEC-81](manifesto/02-nfrs.md)). Both faces emit OCSF file-activity, fail-closed ([NFR-SEC-79](manifesto/02-nfrs.md)). For multi-tenant deployments the broker is instantiated per tenant — one broker principal per tenant filesystem scope, not a single multiplexed broker ([NFR-SEC-76](manifesto/02-nfrs.md)). It governs inbound data paths (the guest mount and the north-face client ingest) where the Egress trust-edge governs only outbound. Mount substrate (FUSE / virtio-fs / 9p) is a component-spec choice. | [NFR-SEC-25](manifesto/02-nfrs.md) |
+| 3 | **Compute plane** | Session sandbox, one per session, lifecycle bound to session. Runtime tier per [§02 "Sandbox tier — workload-driven selection"](manifesto/02-nfrs.md): `runc` for solo / dev; `gVisor` for v1 hardened; microVM (hardware-virt) for post-v1. Guest agent is PID 1. Cross-session network reachability disabled per [NFR-SEC-22](manifesto/02-nfrs.md); per-tenant network isolation is a deployment property of this zone. | [NFR-SEC-02](manifesto/02-nfrs.md) |
+| 4 | **Egress trust-edge** | Single outbound path. Posture follows the §7 ladder (deny-all / transparent pass-through / egress-wide bump / external SDS source); injection happens at the egress-wide-bump rung, where the edge attaches the upstream authorization received over Envoy SDS from a static file (solo) or a customer-provided SDS-compatible store (enterprise). Injection is keyed on a presented scoped credential carried by the request, never on network origin — a request presenting none receives none ([ADR-0007](adr/0007-egress-auth-mechanism.md)); the guest carries no long-lived upstream secret on the egress leg. DLP-ICAP is a configuration of the bump rung, not a separate rung. Egress allow-list enforcement sits here (deny-by-default; an MCP server, LLM API, or object store is one allow-listed destination, not a separate control). AI-guardrail / prompt-content policy is customer's own AI gateway, not ours ([NFR-COMP-26](manifesto/02-nfrs.md) revisit). | [NFR-SEC-05](manifesto/02-nfrs.md) |
+| 5 | **Audit pipeline** | Durable bus + hash-chained store + bridges to customer sinks. Retention floor, RPO, and tamper-evidence differ from Control plane, so it is its own zone. Compute-time metering emits as audit events on this pipeline. | [NFR-SEC-03](manifesto/02-nfrs.md) |
+
+Secondary NFR anchors per zone:
+
+- Control plane — [NFR-FLEX-14](manifesto/02-nfrs.md), [NFR-REL-01](manifesto/02-nfrs.md).
+- Storage broker — [NFR-SEC-25](manifesto/02-nfrs.md), [NFR-SEC-15](manifesto/02-nfrs.md), [NFR-SEC-79](manifesto/02-nfrs.md); north face — [NFR-SEC-78](manifesto/02-nfrs.md), [NFR-SEC-80](manifesto/02-nfrs.md), [NFR-SEC-81](manifesto/02-nfrs.md), [NFR-SEC-82](manifesto/02-nfrs.md), [NFR-SEC-83](manifesto/02-nfrs.md), [NFR-SEC-84](manifesto/02-nfrs.md), [NFR-SEC-76](manifesto/02-nfrs.md).
+- Compute plane — [NFR-SEC-14](manifesto/02-nfrs.md), [NFR-SEC-22](manifesto/02-nfrs.md), [NFR-FLEX-02](manifesto/02-nfrs.md). Performance targets for this zone live in component specs.
+- Egress trust-edge — [NFR-SEC-08](manifesto/02-nfrs.md), [NFR-SEC-17](manifesto/02-nfrs.md), [NFR-SEC-23](manifesto/02-nfrs.md), [NFR-SEC-27](manifesto/02-nfrs.md), [NFR-SEC-29](manifesto/02-nfrs.md), [NFR-SEC-30](manifesto/02-nfrs.md), [NFR-FLEX-15](manifesto/02-nfrs.md), [NFR-COMP-28](manifesto/02-nfrs.md).
+- Audit pipeline — [NFR-REL-12](manifesto/02-nfrs.md), [NFR-REL-03](manifesto/02-nfrs.md), [NFR-COMP-01](manifesto/02-nfrs.md), [NFR-COST-05](manifesto/02-nfrs.md), [NFR-MAINT-AUDIT-SCHEMA](manifesto/02-nfrs.md).
+
+**Skill registry boundary** is reserved as a TBD-stub per CLAUDE.md §v1-non-goals.
+
+Cross-component encryption-in-transit invariant per [NFR-SEC-37](manifesto/02-nfrs.md): inter-zone traffic between Wide-Moat components is encrypted in transit. Two carve-outs apply, both decrypted by design and re-encrypted on the upstream leg: (a) the Egress trust-edge inspection point at the egress-wide bump rung (see §7); (b) the DLP-ICAP hook at that rung.
+
+## 3. External actors
+
+Outbound endpoints behind the egress policy — LLM upstream, customer MCP servers, object stores, internal APIs — are drawn in the diagram for visual orientation only. They are not actors against our contracts: the Egress trust-edge gates them and attaches the upstream authorization, received over Envoy SDS from a static file (solo) or a customer-provided SDS-compatible store (enterprise).
+
+| Actor | Boundary it crosses | Contract | Optional? |
+|---|---|---|---|
+| MCP client (the thing that calls our MCP server) | client → Control plane | MCP authorization spec, audience-validated tokens | required |
+| Customer IdP (OIDC) | IdP → Control plane | relying-party (we are RP) | required on the full shelf; minimal shelf uses a host-rooted local operator credential; a SAML-only IdP federates in through Dex or Keycloak |
+| Customer SIEM | Audit pipeline → SIEM | OCSF schema + bridge transport (transports per [NFR-MAINT-AUDIT-SCHEMA](manifesto/02-nfrs.md)) | optional bridge — file-system sink on the minimal shelf |
+| Customer KMS / HSM | Storage broker / Audit pipeline → KMS | PKCS#11 + KMIP | optional — full shelf only; minimal shelf uses host-local keys |
+| Customer outbound proxy | Egress trust-edge → customer proxy | chained-proxy contract | optional |
+| Customer DLP-ICAP service | Egress trust-edge → ICAP | ICAP req-mod + resp-mod | optional — engaged only at the egress-wide bump rung |
+| SOAR (incident automation) | Control plane ↔ SOAR | signed webhook + admin API | optional |
+| Admin / Operator (PAM-JIT human) | Operator → Control plane | host-rooted local credential on the minimal shelf; short-lived OIDC-asserted claim on the full shelf; no shared service accounts on either ([NFR-COMP-29](manifesto/02-nfrs.md)) | required |
+| Data-plane client (OCU SPA or headless caller) | client → Storage broker north face | file-artifact data plane (upload / list / download / preview-render); embed token verified → first-party session ([NFR-SEC-78](manifesto/02-nfrs.md), [NFR-SEC-82](manifesto/02-nfrs.md)) | optional — absent in headless deployments |
+| Transparency log | Audit pipeline → transparency log | submission envelope; log operator signs the Merkle head (§12 Open question 4) | optional — choose public or customer-private |
+
+## 4. Per-tenant isolation menu
+
+| Tier | Mechanism | Cross-tenant boundary | Where it sits |
+|---|---|---|---|
+| T0 logical | row-level filter; tenant_id column + app-side check | shared kernel, shared substrate | solo / dev / single-operator |
+| T1 namespace | namespace + network policy + role-based access control + resource quota | shared kernel, shared control plane | single-tenant agent execution, OR multi-tenant for non-agent-execution workloads only |
+| T2 VPC / VNet | per-tenant VPC, no peering | shared substrate, separate network | NPI baseline |
+| T3 dedicated cluster | dedicated control plane per tenant | separate control plane, shared substrate | common deployment shape for DORA-CIF workloads |
+
+**Multi-tenant agent-execution invariant.** Where the Compute plane runs LLM-issued tool calls / code from more than one tenant on the same node, the substrate MUST be hardware-virt OR user-space-kernel — not bare `runc`. Bare `runc` multi-tenant agent execution is forbidden; adversarial agent-issued code is not bounded by data classification. The microVM tier is tracked at [#161](https://github.com/Wide-Moat/open-computer-use/issues/161). T1 namespace remains valid for single-tenant agent execution or for multi-tenant workloads that do not execute LLM-issued code (admin UIs, read-only dashboards, batch-data jobs).
+
+**Host-attested caller-identity invariant.** The control / exec channel stays off any network the guest can reach: the host opens it and the guest listens, over vsock (microVM) or a host-side unix socket (`gVisor`, `runc`), and a TCP listener — if used — rejects loopback and own-interface sources so guest-originated code cannot dial the supervisor through its own stack. Every host-facing call the guest makes — to the Control plane or the Storage broker — carries a caller identity the host derives itself: a hypervisor-assigned context id (microVM), the kernel peer credentials of the per-session sandbox principal (`gVisor` sentry, `runc` per-session host uid), or a per-session socket path the guest cannot enumerate. A session, tenant, or principal id the guest supplies in a request body or header is at most a hint cross-checked against that host-attested identity, never the identity itself. A guest with in-sandbox root MUST NOT present another session's identity, nor reach the control channel through its own network. A guest-out reverse dial to a host-side bridge is a fallback only where the runtime makes a host-reachable guest listener unavailable; the bridge then holds no credential, runs unprivileged and syscall-confined, and authenticates the session before any privileged action. See [NFR-SEC-43](manifesto/02-nfrs.md).
+
+Higher-isolation tiers (dedicated bare-metal node pool per tenant; customer-owned hardware in customer datacenter) are tracked in open question §12 item 1 ([#148](https://github.com/Wide-Moat/open-computer-use/issues/148)) as candidates for later promotion. Promote when a named workload requires them.
+
+Boundary properties in §5–§11 hold for every tier; the tier picks the substrate, not the invariants. Measurable cross-tenant grading is in the same open question.
+
+## 5. Trust-zone diagram
+
+```mermaid
+flowchart LR
+    EXT[external actors]
+    CP[Control plane<br/>MCP + operator interfaces]
+    SB[Storage broker]
+    VM[Compute plane]
+    EDGE[Egress trust-edge]
+    SDS[SDS source<br/>static file or customer store]
+    AUDIT[Audit pipeline]
+    EXT -- "MCP (agent) · operator API" --> CP
+    CP -- "Session JWT (≤60min)" --> VM
+    CP -- "resource handle (scopes mount)" --> SB
+    SB -- "mount · resource handle only" --> VM
+    VM -- "single egress (no long-lived upstream secret)" --> EDGE
+    SDS -- "credential over SDS" --> EDGE
+    SB -- "backend traffic · storage lane (NFR-SEC-85)" --> EDGE
+    EDGE -- "auth injected" --> EXT
+    CP & SB & VM & EDGE -- "OCSF" --> AUDIT
+    AUDIT --> EXT
+```
+
+Canonical source: [`docs/architecture/diagrams/02-trust-boundaries.mmd`](./diagrams/02-trust-boundaries.mmd) — the canonical file encodes the convention "solid border = always present; dashed border = optional configuration" (CPROXY, SOAR, ICAP, SIEM, KMS, TLOG drawn dashed). The inline block above is a simplified overview that does not encode dashed-vs-solid; for the optional-vs-required reading, use the canonical file or §3 actor table.
+
+## 6. Data classification taxonomy
+
+Eight content-keyed classes. Per-tenant data residency ([NFR-COMP-13](manifesto/02-nfrs.md)) constrains where any class above PUBLIC may sit on the substrate.
+
+| Class | NYDFS NPI | GLBA NPI | SEC MNPI | GDPR Art. 4 / 9 | EU AI Act | PCI DSS v4.0 | Regulatory retention floor (customer's store) |
+|---|---|---|---|---|---|---|---|
+| **PUBLIC** | n/a | excluded | n/a | not personal data | n/a | n/a | none |
+| **INTERNAL** | n/a | n/a | n/a | not personal data | n/a | n/a | 1 yr ops |
+| **CONFIDENTIAL (PII)** | NPI on consumers | NPI | n/a | personal data Art. 4(1) | Art. 10 training data | track 2 / track 1 (non-PAN) | NYDFS §500.13 |
+| **RESTRICTED (NPI-financial)** | NPI tied to financial product | NPI | n/a if not material | personal data; Art. 6 lawful basis | high-risk-AI input | PAN, expiry, service code | 5 yr (CFR-cited financial-institution rules) |
+| **RESTRICTED (MNPI)** | n/a | n/a | Reg FD / 10b-5 | n/a directly | n/a | n/a | until public + 2 yr legal hold |
+| **SENSITIVE (special category)** | NPI plus health / biometric | NPI | n/a | Art. 9 special category | Annex III categories | n/a | per Art. 5(1)(e) |
+| **REGULATED-AUDIT** | NYDFS §500.6 audit trail | n/a | SOX-trail | Art. 30 records of processing | Art. 12 logs of high-risk AI | PCI Req 10 | 7 y default / 10 y configurable (see §10) |
+| **CRYPTO-KEYS / SECRETS** | implicit under §500.15(a) | implicit under Safeguards Rule | n/a | implicit | implicit | PCI Req 3.6 | rotation policy is the floor |
+
+OCU is an ephemeral workspace and retains no customer file bytes for any class — bytes leave with the session (scrubbed at teardown, [NFR-SEC-65](manifesto/02-nfrs.md)) or go to the customer's store, so the retention-floor column is a floor for the customer's store. The only row that is an OCU duty is REGULATED-AUDIT: the 7 y / 10 y floor binds the audit record OCU keeps ([NFR-COMP-01](manifesto/02-nfrs.md), §10), not customer content.
+
+The default solo / dev deployment runs on `runc` under the `trusted_operator` workload profile, so its default content scope is PUBLIC + INTERNAL. CONFIDENTIAL+ content triggers data-class obligations — opt-in BYOK ([NFR-SEC-04](manifesto/02-nfrs.md)), customer-managed audit sink ([NFR-MAINT-AUDIT-SCHEMA](manifesto/02-nfrs.md)), residency pinning ([NFR-COMP-13](manifesto/02-nfrs.md)) — but does not pick the runtime tier (AP-13). The tier is picked by the deployment's `workload_trust_profile` per [§02 "Sandbox tier — workload-driven selection"](manifesto/02-nfrs.md).
+
+Prompt content filtering, redaction, and AI-guardrail policy (PII masking, prompt-injection detection, jailbreak detection) are not our scope — that responsibility lives with the customer's AI gateway (commercial AI-gateway product or in-perimeter model with its own guardrails). Layer 3 routes the traffic and audits the egress event; what the gateway does with the prompt is its contract, not ours. [NFR-COMP-26](manifesto/02-nfrs.md) to be revisited in §02.
+
+## 7. Egress posture — a ladder by need
+
+Egress posture follows what the deployment needs, not a fixed default ([NFR-FLEX-15](manifesto/02-nfrs.md), [ADR-0007](adr/0007-egress-auth-mechanism.md)). Each rung adds only what the rung above requires; the one-click solo path sits wherever the deployment's need sits, so a deployment that needs no authenticated egress carries no certificate authority.
+
+| Rung | When | TLS termination | CA in sandbox trust store | Plaintext carve-out ([NFR-SEC-37](manifesto/02-nfrs.md)) |
+|---|---|---|---|---|
+| **deny-all** | no outbound need (no upstream, no model) | n/a — egress off | no | none |
+| **transparent pass-through** | unauthenticated internet only; no upstream credential | none — proxy in path, does not terminate | no | none |
+| **egress-wide bump** | an upstream credential is configured (default at this rung) | every outbound leg terminated and re-originated | yes — per-deployment CA, public cert auto-injected at start; private key only on the minter | proxy decrypt / re-encrypt segment |
+| **external SDS source** | enterprise: credential lifecycle owned off-box | as bump | yes | as bump |
+
+Bump is the default *only when an upstream credential is configured*; it is not imposed on a deployment that needs no outbound credential. "One-click" is preserved at the bump rung by automating the CA — generate per deployment, auto-inject the public certificate into the sandbox trust store at start — not by omitting it. DLP-ICAP ([NFR-COMP-28](manifesto/02-nfrs.md)) is a configuration of the bump rung, not a separate rung: an ICAP req-mod / resp-mod hook between the decrypt and re-encrypt steps, with a plaintext segment at the ICAP wire.
+
+Upstream-authorization injection (NFR-SEC-23/27) requires the edge to originate the upstream connection — the L7 property the bump rung provides. Transparent pass-through does not terminate TLS and so cannot attach an upstream credential; it reaches only endpoints needing no upstream authorization. The mechanism that attaches the credential — edge injection at the bump rung, or a protocol broker for a high-value scoped credential — is selected per upstream by [ADR-0007](adr/0007-egress-auth-mechanism.md); v1 ships edge injection only. Upstreams that pin a certificate or require client-mTLS / proof-of-possession cannot be satisfied by edge injection and are tracked at [#176](https://github.com/Wide-Moat/open-computer-use/issues/176).
+
+Fail-closed: if the egress proxy is unreachable, the Compute plane drops outbound traffic, never bypasses the proxy. Same property on the IdP → Control plane path: IdP unreachable → new sessions denied; in-flight sessions continue under their existing token until either TTL expiry or an explicit revoke event.
+
+Egress denials carry a structured reason header (`x-deny-reason`) so audit and SOAR can classify outcomes without parsing free-text logs. Unallowed destinations are dropped at SNI pre-filter before TLS handshake (cheaper, lower forensic value); allowed destinations are inspected at L7 (richer, more expensive).
+
+Revoke is independent of IdP reachability. The Control plane holds a session denylist (kill-switch state). On the Compute-plane path the denylist is checked directly on every RPC. On the Egress trust-edge path the denylist stops injection: the edge attaches no upstream authorization for a revoked session, independent of the credential's own validity window. The denylist propagates platform-wide within ≤5 min ([NFR-SEC-04](manifesto/02-nfrs.md)), so an explicit revoke cuts upstream access within ≤5 min. Upstream credential lifecycle — mint, rotation, revocation, and the credential's own TTL — belongs to the SDS source (a customer store on the enterprise shelf, a static file on the solo shelf), not to OCU ([NFR-SEC-29](manifesto/02-nfrs.md)). Kill switch ([NFR-SEC-01](manifesto/02-nfrs.md)) shares the same denylist; its ≤30 s p99 SLA covers Compute-plane stop. The IdP participates in token issue, not in revoke — that is why ≤5 min revoke holds even during an IdP outage, which is the incident the target exists for.
+
+Component-spec wiring lands under [`components/`](./components/) per [PROCESS.md](./PROCESS.md) when the egress-proxy spec opens.
+
+### 7.1 Two guest-data paths
+
+The guest reaches data over two paths with different trust roots:
+
+| Path | Direction | Zone | What the guest holds | Where the real credential lives |
+|---|---|---|---|---|
+| **Storage mount** | inbound + outbound to user-data | Storage broker (§2 zone 2) | session resource handle (`filesystem_id`) | host-side Storage broker |
+| **Egress** | outbound to upstreams | Egress trust-edge (§2 zone 4) | no long-lived upstream secret on this leg | SDS source (static file or customer store), injected at the edge on a presented scoped credential |
+
+The guest speaks a file-operation interface to the broker, not the object-store protocol. The broker is the object-store client: it holds the credential and signs its own backend requests, so the request signature is produced once, at the broker, and nothing downstream rewrites it. The broker's backend leg leaves through a storage-dedicated lane on the Egress trust-edge ([NFR-SEC-85](manifesto/02-nfrs.md)) — out-of-process from the broker and distinct from the guest egress lane, in allow-list-only mode (no TLS termination), so the signature survives the hop, and the guest never sees that leg. Where file-content inspection is required, it runs at the broker on plaintext, before signing — not at the Egress trust-edge, which sees only ciphertext on this leg. Both paths share one invariant the table makes concrete: the guest holds a session-scoped handle at most ([NFR-SEC-25](manifesto/02-nfrs.md), [NFR-SEC-23](manifesto/02-nfrs.md)).
+
+The broker does not open an uncontrolled outbound path of its own: the broker-originated backend leg traverses a storage-dedicated lane on the Egress trust-edge — out-of-process from the broker, distinct from the guest egress lane ([NFR-SEC-85](manifesto/02-nfrs.md)) — and a direct broker-to-object-store dial that bypasses that lane is forbidden ([NFR-SEC-16](manifesto/02-nfrs.md)), because it would be an outbound path the control cannot see; the storage lane is that control, which a compromised broker cannot silence.
+
+These are the two **guest** data paths. The broker also fronts a third, non-guest path — its north face (§2 zone 2): an external Data-plane client (§3) reaches the host-side broker over the file-artifact ingress. That path is caller↔broker, host-side, not a guest channel, so the host-dials-guest invariant ([NFR-SEC-43](manifesto/02-nfrs.md)) is unaffected; its authorization (embed token, three-axis claim) and inbound-body controls (archive validation, content classification) are the north-face NFRs anchored in §2 zone 2.
+
+The skill-mount path (read-only shared content vs per-session mutable data) is governed by the `SkillProvider` abstraction, which is post-v1 ([NFR-SEC-24](manifesto/02-nfrs.md), [NFR-SEC-42](manifesto/02-nfrs.md)); its boundary is specified with that ADR, not here.
+
+## 8. Workload-identity floor
+
+Token taxonomy is canonical here; the three classes, their scopes, and their TTLs match [`manifesto/02-nfrs.md`](manifesto/02-nfrs.md) §"Token TTL taxonomy". Each is named with its own scope, TTL, signer, and consumer. The guest holds only session-scoped tokens — the session JWT and a storage-mount handle; the host-side generic internal token never reaches it. The upstream credential the Egress trust-edge attaches is not an OCU-issued token class: it is delivered over Envoy SDS from a static file (solo) or a customer-provided SDS-compatible store (enterprise), and its scope and TTL are the source's.
+
+| Token class | Scope | TTL | Consumer | §02 anchor |
+|---|---|---|---|---|
+| **Session JWT** | per session (Control plane → Compute plane; bound to `container_name`) | ≤ 60 min, rotated | Compute plane (guest agent), proving session identity to the Control plane | NFR-SEC-10 |
+| **Storage-mount handle** | per session, scoped to one filesystem (a `filesystem_id`) | session-scoped (expires with the session) | Compute plane (guest), presented to the Storage broker; selects the mount, carries no backend credential | NFR-SEC-25 |
+| **Generic internal token** | inter-component RPC (Control plane ↔ audit, host-side) | ≤ 60 min | host-side service-to-service | NFR-SEC-23 |
+
+| Property | Minimal shelf | Full shelf | §02 anchor |
+|---|---|---|---|
+| Inter-component identity | Host-local signing key bound to `container_name` | Workload identity from customer PKI per tenant | NFR-SEC-26 / NFR-SEC-09 |
+| Identity trust root | host-local signing key | HSM-rooted, FIPS 140-3 L3 | NFR-FLEX-04 |
+| Tenant DEK rotation | ≤90 d | ≤90 d | NFR-SEC-04 |
+| Tenant KEK rotation | ≤365 d | ≤365 d | NFR-SEC-04 |
+| Revoke latency | ≤5 min | ≤5 min | NFR-SEC-04 |
+| Per-tenant trust domain | n/a (single-tenant) | per-tenant trust domain | open question §12 item 1 |
+| Internal mTLS substrate | TLS 1.3 enforced at the deployment overlay (substrate choice is a component-spec decision) | same, customer-CA-rooted | NFR-SEC-37 |
+
+NFR anchors for §8 (consolidated): see [NFR-SEC-04](manifesto/02-nfrs.md), [NFR-SEC-09](manifesto/02-nfrs.md), [NFR-SEC-10](manifesto/02-nfrs.md), [NFR-SEC-23](manifesto/02-nfrs.md), [NFR-SEC-26](manifesto/02-nfrs.md), [NFR-SEC-29](manifesto/02-nfrs.md), [NFR-SEC-37](manifesto/02-nfrs.md), [NFR-FLEX-04](manifesto/02-nfrs.md).
+
+Minimal shelf: identity-binding ([NFR-SEC-09](manifesto/02-nfrs.md)) via host-local signing key on JWT ([NFR-SEC-26](manifesto/02-nfrs.md)); egress trust-store ([NFR-SEC-05](manifesto/02-nfrs.md)) via auto-generated self-signed CA. Full shelf: workload identities from customer PKI + customer-rooted CA.
+
+### 8.1 Signer identity per boundary
+
+Each token class has its own signer; signer identity ties to the workload that issues the token. Minimal-shelf signers are host-local keys; full-shelf signers are workload identities from the customer PKI. The full per-boundary table (six artifacts × four columns) lands with the PKI decision — tracked at §12 item 5 ([#152](https://github.com/Wide-Moat/open-computer-use/issues/152)).
+
+## 9. Encryption matrix
+
+Single invariant: inter-component traffic between Wide-Moat components is encrypted in transit ([NFR-SEC-37](manifesto/02-nfrs.md)). Tenant data at rest uses authenticated AES ([NFR-SEC-33](manifesto/02-nfrs.md)). Key custody on the minimal shelf is host-local; on the full shelf, HSM-rooted via PKCS#11 / KMIP per [NFR-FLEX-04](manifesto/02-nfrs.md). Per-tenant data residency ([NFR-COMP-13](manifesto/02-nfrs.md)) is enforced at Control-plane scheduling and Audit-pipeline routing — not an encryption boundary. The full per-boundary matrix (TLS version, at-rest cipher, key custody, rotation cadence) is component-spec material; it lands with each component spec.
+
+## 10. Audit zone — mandatory in code, pluggable in sinks
+
+Audit pipeline is mandatory in code ([NFR-SEC-03](manifesto/02-nfrs.md) hash-chained; [NFR-REL-12](manifesto/02-nfrs.md) durable bus on critical path; [NFR-COMP-01](manifesto/02-nfrs.md) retention floor — 7 y default, 10 y configurable, machine-enforced by the Audit pipeline retention policy). Sinks are pluggable: file-system on the minimal shelf; OCSF v1.x JSON bridges to customer SIEM as opt-in per [NFR-MAINT-AUDIT-SCHEMA](manifesto/02-nfrs.md). [ADR-0009](adr/0009-audit-pipeline-pluggable-by-contract.md) sets where the mandatory-in-code / pluggable line falls: the chain of custody and a local durable commit are OCU's, while the bus product, WORM store, SIEM sink, and transparency-log endpoint are pluggable seams with solo-reference defaults.
+
+The pipeline is drawn as our zone; sinks are external actors. The contract is the OCSF v1.x JSON schema plus bridge transport (see §12 Open question 3).
+
+Tamper-evidence: hash-chained store always; the daily batch is submitted to a transparency log of the customer's choice. The transparency log operator signs the Merkle head; we sign only the submission envelope ([NFR-SEC-03](manifesto/02-nfrs.md)).
+
+## 11. Regulator citation map
+
+Mapping is **indicative, not verbatim**. Verify every cell against the source text before reuse. Layer 3 does not represent these citations as audit evidence by itself; full source-verification is tracked at [#153](https://github.com/Wide-Moat/open-computer-use/issues/153).
+
+| Our zone / boundary | NIST SP 800-207 | NYDFS Part 500 | DORA | EU AI Act | CCM v4 |
+|---|---|---|---|---|---|
+| Control plane | implicit-trust zone (§2.1) | § 500.7 access privileges (PAM) | Art. 6 ICT risk-management framework | Art. 14 human oversight | IAM-06 |
+| Storage broker | implicit-trust zone (custody of storage-backend credential) | § 500.15(a) encryption + key custody | Art. 28 ICT third-party general | Art. 10 data governance | CEK-08, DSP-01 |
+| Compute plane (sandbox) | implicit-trust zone, scoped small | § 500.7 + § 500.15 | Art. 28(4) ITS register of information | Art. 15(4) accuracy, robustness, cybersecurity | IVS-06, IVS-09 |
+| Egress trust-edge | PEP (§3.4.1) | § 500.5 vulnerability scanning (segmentation surfaces here, not § 500.7) | Art. 30 key contractual provisions (location of processing) | Art. 14 oversight | IVS-09 segmentation, DSP-05 DLP |
+| Audit pipeline | (cross-cutting — no direct ZT mapping) | § 500.6 audit trail; § 500.13 retention policy | Art. 10 detection (logs) | Art. 12 logs of high-risk AI; Art. 19(1) 10-year retention floor | LOG-01, LOG-02 |
+| MCP client → Control plane | untrusted → implicit-trust crossing | § 500.7 + § 500.12 MFA | Art. 30 contract clauses | Art. 13 transparency to deployer | IAM-08 |
+| Egress trust-edge → upstream | implicit-trust → untrusted crossing | § 500.15 encryption in transit | Art. 28 ICT third-party general | Art. 15 cybersecurity | IVS-09 |
+| Audit pipeline → SIEM | implicit-trust → external sink | § 500.6 audit trail readable by covered entity | Art. 10 detection (retention floor cited from SEC 17a-4 / FCA SYSC 9, see §10) | Art. 12 logs accessible | LOG-04 |
+
+## 12. Open questions
+
+1. Cross-tenant isolation grading — [#148](https://github.com/Wide-Moat/open-computer-use/issues/148) — measurable target ("tenant A cannot observe tenant B side-channel") not yet in §02. Also tracks higher-isolation tiers (dedicated hardware, customer-owned cage) as candidates for promotion when a named workload requires them.
+2. Control-plane metadata-only gate — [#149](https://github.com/Wide-Moat/open-computer-use/issues/149) — DORA Art. 28(2)(c) requires a measurable gate that no customer payload crosses the Control plane.
+3. SIEM-bridge transport and backpressure — [#150](https://github.com/Wide-Moat/open-computer-use/issues/150) — pluggable-sink contract needs measurable transport and end-to-end backpressure target.
+4. Transparency-log publishing path — [#151](https://github.com/Wide-Moat/open-computer-use/issues/151) — submission path between Audit pipeline and the external transparency log (auth, retry, RPO if the log is unreachable), plus the prior question of "do we publish at all on the minimal shelf".
+5. PKI tool pick — [#152](https://github.com/Wide-Moat/open-computer-use/issues/152) — §8.1 names signer identity per boundary; the per-boundary signer table lands with the PKI ADR.

package/docs/architecture/03-c4-context.md

@@ -0,0 +1,61 @@
+<!-- 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
+---
+
+## 1. Purpose
+
+Names every external boundary OCU speaks across, for architects and security engineers integrating it with the customer's IdP, KMS, SIEM, and outbound proxy. OCU is the in-perimeter tool-execution boundary — a uniform sandbox with a skill library, exposed over MCP; the calling client runs the agent loop and owns the model choice, and OCU executes the tool-calls it receives.
+
+OCU is one component of the Wide-Moat opinionated bundle (other peers in the bundle include n8n and Open WebUI). OCU is also usable standalone — any MCP-speaking peer is a first-class integration. See [`manifesto/01-audience-and-buyer.md`](manifesto/01-audience-and-buyer.md) for the buyer story; this document scopes only what is inside OCU and what it talks to.
+
+## 2. Inside the box
+
+OCU is the tool-execution component: MCP server / Control plane → guest agent → sandbox runtime → Egress trust-edge + Storage broker + Audit pipeline ([`02-trust-boundaries.md`](02-trust-boundaries.md) §1). The guest agent is OCU's in-sandbox executor. Internal decomposition is out of scope at this layer.
+
+## 3. C4 Context diagram
+
+Canonical source: [`diagrams/c4-context.mmd`](diagrams/c4-context.mmd). Convention: solid border = present on the minimal-capability shelf; dashed border = not on the minimal shelf by default. Palette borrows the project red-untrusted / green-trusted convention; semi-trusted (amber) and isolated (blue) zones from the trust-boundary diagram do not apply at the Context level. The solid / dashed split makes the one-click solo-install path visible at a glance — solid-border actors are what a solo install talks to out of the box; dashed-border actors are wired on the full-capability shelf, some optional (SIEM, proxy, ICAP, SOAR, transparency log) and some required there (IdP). Per-actor optionality is stated exactly in the §4 table. Internal containers are not shown here.
+
+## 4. External actors
+
+The boundary-crossing actors are defined canonically in [`02-trust-boundaries.md`](02-trust-boundaries.md) §3. This view groups them by role and marks per-actor optionality; exact required/optional status is in the §4 table below.
+
+| Actor | Role | Required-or-optional | NFR anchor |
+|---|---|---|---|
+| **MCP-speaking peer** (n8n, Open WebUI, custom MCP client) | Inbound calls into OCU's MCP server | required | — |
+| **Admin / Operator** (PAM-JIT human) | Operates OCU; host-rooted local credential on the minimal shelf, short-lived OIDC-asserted claim on the full shelf — no shared service accounts on either | required | [NFR-COMP-29](manifesto/02-nfrs.md) |
+| **Customer IdP** (OIDC) | Authenticates inbound peers and operators on the full shelf; OCU is a relying party; a SAML-only IdP federates in through Dex or Keycloak | not on the minimal shelf (operators use a host-rooted local credential) — required on the full-capability shelf | — |
+| **Customer SIEM** | OCSF v1.x event bridge consumed by the customer's SIEM | optional on minimal shelf (file-system sink); required where SIEM is the system of record | [NFR-MAINT-AUDIT-SCHEMA](manifesto/02-nfrs.md) |
+| **Customer KMS / HSM** | Key custody for the broker and audit signing chain on the full-capability shelf | optional — full shelf only; minimal shelf uses host-local keys | [NFR-FLEX-04](manifesto/02-nfrs.md) |
+| **Customer outbound proxy** | Chained-proxy hop for egress; OCU's trust-edge proxy speaks the chained contract | optional | — |
+| **Customer DLP-ICAP service** | ICAP req-mod / resp-mod hook at the egress-wide bump rung | optional — engaged only at the bump rung | [NFR-COMP-28](manifesto/02-nfrs.md) |
+| **SOAR** (incident automation) | Bidirectional: signed webhook from OCU on alert, admin API back for revoke | optional | — |
+| **Transparency log** | Daily Merkle-head submission for tamper-evident audit | optional — choose public or customer-private | [NFR-SEC-03](manifesto/02-nfrs.md) |
+| **Data-plane client** (OCU SPA or headless caller) | Reaches OCU's own authenticated SPA — file preview and artifact render — and the headless upload/list/download API; bytes flow client↔OCU directly, never through a peer and never to the object store. May be driven by a human; the operator control plane is separate and CLI-only | optional — absent in headless / automated deployments; OIDC-embed token required on the full shelf | [NFR-SEC-09](manifesto/02-nfrs.md), [NFR-SEC-49](manifesto/02-nfrs.md), [NFR-SEC-73](manifesto/02-nfrs.md), [NFR-SEC-82](manifesto/02-nfrs.md), [NFR-SEC-83](manifesto/02-nfrs.md) |
+
+Regulator citations and measurable targets for each row land in [`manifesto/02-nfrs.md`](manifesto/02-nfrs.md), not here.
+
+Outbound endpoints behind the egress policy (LLM upstream, customer MCP servers, object stores, internal APIs) are not actors against OCU's contracts — the Egress trust-edge gates them and attaches the upstream authorization received over Envoy SDS from a static file (solo) or a customer store (enterprise) ([`02-trust-boundaries.md`](02-trust-boundaries.md) §3 preamble).
+
+A human drives OCU's control plane only through an MCP-speaking peer (e.g. Open WebUI, n8n, or a custom client); the operator control plane stays CLI-only. The data plane is separate: OCU serves its own authenticated SPA for file preview and artifact render, plus the headless upload/list/download API. The SPA is embeddable cross-origin in a calling peer ([NFR-SEC-82](manifesto/02-nfrs.md), [NFR-SEC-83](manifesto/02-nfrs.md)). Rendering this data-plane surface is OCU's; the calling client's chat/workflow surface is separate.
+
+## 5. Scope out
+
+- **Workflow orchestration** — peers like n8n call OCU as an MCP client; they live in their own repos.
+- **Chat surface** — peers like Open WebUI call OCU as an MCP client; they live in their own repos.
+- **Hosted LLM serving, model selection, and the agent loop** — the calling client owns all three. If a sandbox tool needs an LLM, it reaches it as one allow-listed egress endpoint, not through OCU.
+- **Skill registry and skill-pack catalog** — v1 non-goal; `SkillProvider` abstraction reserved.
+- **Operator / control-plane console** — v1 non-goal; CLI (`occ`) + GitOps + Grafana cover operator operations. OCU's data-plane preview / artifact-render SPA is in scope (§4).
+- **AI-guardrail / prompt-content policy** — customer's AI gateway, not OCU ([`02-trust-boundaries.md`](02-trust-boundaries.md) §2 zone 5).
+
+## 6. Open questions
+
+1. Bundling status of n8n and Open WebUI on `next/v1` — [#154](https://github.com/Wide-Moat/open-computer-use/issues/154) — Wide-Moat bundle composition is open; Layer 4 names the integration shape but does not lock the packaging.
+2. Browser/terminal live-view surfaced to a human (CDP screencast / PTY) — [#210](https://github.com/Wide-Moat/open-computer-use/issues/210) — v2, deferred. The data-plane SPA (file preview + artifact render) is v1 and in scope per §4; the machine-facing PTY+CDP WebSocket ([NFR-IC-03](manifesto/02-nfrs.md)) is v1 and machine-to-machine only. A human live-view, when taken up, follows the host-proxied ([NFR-SEC-43](manifesto/02-nfrs.md)) shape — host-side termination, never an inbound listener on the guest.
+3. Sharing a file by link (a capability URL a recipient redeems without an OCU session) is out of v1 — the data-plane API covers upload / list / download for an identity-bound client only. Share semantics (capability mint, TTL, revocation, audit) land when taken up — [#211](https://github.com/Wide-Moat/open-computer-use/issues/211).

package/docs/architecture/04-bounded-contexts.md

@@ -0,0 +1,119 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-05-31
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+Cuts the domain into bounded contexts and classifies each as core, supporting, or generic — the buy-vs-build call. Audience: anyone deciding what we build and what we integrate.
+
+## 1. Context layer vs trust zones
+
+[`02-trust-boundaries.md`](02-trust-boundaries.md) §2 draws five zones — Control plane, Storage broker, Compute plane, Egress trust-edge, Audit pipeline. Those answer "where does it run and under what protection." This layer answers a different question: "which slices of the domain carry the competitive value, and which are solved problems we integrate." A trust zone is a deploy/protection slice; a bounded context is a domain slice. They do not map one-to-one, and the mismatches are the point.
+
+The classification drives the next layer: a context marked `generic` becomes an integration in [`03-c4-context.md`](03-c4-context.md)'s external-actor set, not a container we build; a `core` context becomes containers we own in the C4 Container layer.
+
+## 2. Subdomain classification
+
+```mermaid
+flowchart TB
+    subgraph CORE["Core — built in-house"]
+        AEX["Agent Execution &amp; Sandbox Lifecycle"]
+        CEV["Compliance Evidence &amp; Audit Lineage"]
+    end
+    subgraph SUP["Supporting — built, not differentiating"]
+        TEN["Tenancy &amp; Isolation"]
+        OPA["Operator Access"]
+    end
+    subgraph GEN["Generic — integrated, not built"]
+        IDF["Identity federation"]
+        SEC["Secrets custody"]
+        POL["Policy evaluation"]
+    end
+    AEX -->|"OCSF event"| CEV
+    style CORE fill:#e8f5e9,stroke:#1e7e34,stroke-width:3px
+    style SUP fill:#fff8e1,stroke:#b8860b
+    style GEN fill:#f5f5f5,stroke:#9e9e9e,stroke-dasharray:5 5
+```
+
+The diagram shows only the core-to-core domain edge; the full set of context relationships (inbound, generic integrations) is the context map in §4.
+
+| Subdomain | Class | Value axis | Build-vs-buy |
+|---|---|---|---|
+| **Agent Execution & Sandbox Lifecycle** | core | domain complexity — safely executing adversarial agent-issued tool-calls and code in-perimeter | build |
+| **Compliance Evidence & Audit Lineage** | core | domain complexity — binding every agent action into a replayable, hash-linked lineage that survives an adversarial workload (the lineage, not the OCSF schema or the SIEM sink, is the defensible part) | build |
+| **Tenancy & Isolation** | supporting | owns the T0–T3 isolation-tier selection logic | build |
+| **Operator Access** | supporting | owns the PAM-JIT human-to-platform contract ([NFR-COMP-29](manifesto/02-nfrs.md)); bespoke to us, sits outside the value axis | build |
+| **Identity federation** | generic | relying-party to customer IdP | integrate |
+| **Secrets custody** | generic | key custody behind PKCS#11 / KMIP | integrate |
+| **Policy evaluation** | generic | externalised authorization decisions | integrate |
+
+Source availability is a go-to-market property, not a classification axis. The security primitives ship in the open artifact ([`01-audience-and-buyer.md`](manifesto/01-audience-and-buyer.md) §"Audience"); that does not demote Agent Execution to generic. Applying an open runtime correctly to adversarial in-perimeter agent-issued code is where the domain complexity sits, so it stays core.
+
+Compliance Evidence is core for the same reason — domain depth, not deal-decisiveness. It clears the TPRM veto (the buyer chain in `01-audience-and-buyer.md`), but that proves it is commercially important, not that it is core. What makes it core is the *lineage*: the OCSF schema, the pluggable SIEM sinks, and the customer-chosen transparency log are generic substrate we integrate; reconstructing a tamper-evident, replayable chain of agent actions across an adversarial workload is the part no competitor hands over and the part we build.
+
+## 3. Trust zones to contexts
+
+The five zones group into two core contexts. The mismatch is deliberate: four zones collapse into one context, one zone is a context of its own.
+
+| Trust zone (Layer 3 §2) | Bounded context | Why this grouping |
+|---|---|---|
+| Control plane | Agent Execution | session lifecycle is execution machinery |
+| Compute plane (sandbox) | Agent Execution | the sandbox is where the tool-calls execute |
+| Storage broker | Agent Execution | host-side broker serves the session's user-data mount |
+| Egress trust-edge | Agent Execution | the single outbound path is part of running safely |
+| Audit pipeline | Compliance Evidence | different reason to exist: prove, not run |
+
+The Audit pipeline is its own zone in Layer 3 for retention/RPO/tamper-evidence reasons; it is its own context here for a domain reason — its value is regulatory proof, a separate axis from execution.
+
+Merging five zones into one context passes the linguistic test only because they share one ubiquitous language: "execute the tool-calls a client sends, safely, in-perimeter." The Control plane and Compute plane unambiguously speak that one execution language. The Storage broker (mount terms: `filesystem_id`, `resource-handle`, `backend-credential`; north-face delivery terms: `artifact`, `preview`, `downloadable`, `SPA-render`) and the Egress trust-edge (enforcement and injection terms: `SNI pre-filter`, `egress-wide bump`, `x-deny-reason`, `auth-injection`, the SDS-delivered upstream credential) speak narrower sub-languages; they sit *inside* Agent Execution, not as separate contexts, because their invariants exist only to serve the running session and they share its aggregate root (the session).
+
+The supporting and generic contexts are not Layer 3 zones we own. Of the three generic contexts, two are Layer 3 §3 external actors — Identity federation (Customer IdP) and Secrets custody (Customer KMS / HSM). Policy evaluation is not yet drawn in Layer 3; it is consumed at the Egress trust-edge (egress allow-list and credential injection) within Agent Execution. The remaining Layer 3 §3 actors are not new contexts: Customer SIEM, SOAR, and the transparency log are downstream consumers of the Compliance Evidence context (§4); the customer outbound proxy and DLP-ICAP are configurations of the Egress trust-edge already inside Agent Execution. An LLM, if a sandbox tool reaches one, is just another allow-listed egress endpoint behind that edge — not a context we model.
+
+## 4. Context map
+
+```mermaid
+flowchart LR
+    IDF["Identity federation<br/>(generic)"]
+    SEC["Secrets custody<br/>(generic)"]
+    POL["Policy evaluation<br/>(generic)"]
+    MCP["MCP caller<br/>(upstream; runs the loop)"]
+    OPER["Operator<br/>(PAM-JIT human)"]
+    AEX["Agent Execution<br/>(core)"]
+    CEV["Compliance Evidence<br/>(core)"]
+    SINK["SIEM · SOAR · transparency log<br/>(downstream consumers)"]
+    MCP -->|"Conformist:<br/>MCP authz spec"| AEX
+    OPER -->|"Customer/Supplier:<br/>PAM-JIT (NFR-COMP-29)"| AEX
+    IDF -->|"Anti-corruption layer"| AEX
+    SEC -->|"Anti-corruption layer"| AEX
+    POL -->|"Anti-corruption layer"| AEX
+    AEX -->|"Open Host Service +<br/>Published Language: OCSF"| CEV
+    CEV -->|"OCSF bridges"| SINK
+    style AEX fill:#e8f5e9,stroke:#1e7e34,stroke-width:2px
+    style CEV fill:#e8f5e9,stroke:#1e7e34,stroke-width:2px
+    style IDF fill:#f5f5f5,stroke:#9e9e9e,stroke-dasharray:5 5
+    style SEC fill:#f5f5f5,stroke:#9e9e9e,stroke-dasharray:5 5
+    style POL fill:#f5f5f5,stroke:#9e9e9e,stroke-dasharray:5 5
+    style SINK fill:#f5f5f5,stroke:#9e9e9e,stroke-dasharray:5 5
+    style MCP fill:#fdecea,stroke:#c0392b
+    style OPER fill:#fdecea,stroke:#c0392b
+```
+
+| Relationship | From → To | Pattern | What it commits to |
+|---|---|---|---|
+| Execution emits evidence | Agent Execution → Compliance Evidence | Open Host Service + Published Language | OCSF v1.x is the published schema; Compliance Evidence is the host with fan-in from five Layer 3 zones and fan-out to multiple SIEMs. The emitter conforms to the schema, not to the consumer's internals ([glossary: OCSF](glossary.md#ocsf)) |
+| Inbound tool calls | MCP caller → Agent Execution | Conformist | we conform to the MCP authorization spec; we do not define it |
+| Operator access | Operator → Agent Execution | Customer/Supplier | PAM-JIT human-to-platform contract ([NFR-COMP-29](manifesto/02-nfrs.md)); host-rooted credential on the minimal shelf, OIDC-asserted claim on the full shelf |
+| Generic integrations | {Identity, Secrets, Policy} → Agent Execution | Anti-corruption layer | each vendor's interface is translated at the boundary so a vendor swap does not reach the core |
+| Evidence to sinks | Compliance Evidence → SIEM / SOAR / transparency log | Open Host Service | OCSF bridges and the submission envelope; the consumer adapts, not us |
+
+The anti-corruption layer is what lets Identity, Secrets, and Policy stay `integrate`: the vendor (Keycloak, OpenBao, OPA) can change without the core's domain changing. An LLM is not among them — it is reached, if at all, as one allow-listed egress endpoint, and the agent loop that would call it runs in the MCP caller. The two core contexts share the OCSF event and nothing else — no shared identifier type, no shared library — so the Published Language does not degrade into a shared kernel that would bind their release cadences.
+
+## 5. Open questions
+
+1. Does Tenancy & Isolation stay supporting, or split a `core` sub-slice once multi-tenant agent-execution grading lands? — [#165](https://github.com/Wide-Moat/open-computer-use/issues/165).
+2. Does the PAM-JIT contract keep Operator Access as its own supporting context, or fold it into Agent Execution? — [#166](https://github.com/Wide-Moat/open-computer-use/issues/166).
+3. Is workload-trust sandbox-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).

package/docs/architecture/05-c4-container.md

@@ -0,0 +1,88 @@
+<!-- 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
+---
+
+Names the runnable units inside the OCU box that Layer 4 drew as one block, and what crosses between them. Audience: architects and security engineers reading this before a component spec.
+
+## 1. Container vs zone vs context
+
+A C4 container is a separately runnable unit — a process or data store that must be running for OCU to work ([c4model.com](https://c4model.com/abstractions/container)). That is a different axis from the two already cut:
+
+- A **trust zone** ([`02-trust-boundaries.md`](02-trust-boundaries.md) §2) is a deploy/protection slice — where it runs and under what protection.
+- A **bounded context** ([`04-bounded-contexts.md`](04-bounded-contexts.md) §1) is a domain slice — which part carries the competitive value.
+
+The five trust zones map to six containers. Four of the five zones are one container each. The Control plane is the exception: it splits into two containers along its interface seam — an agent-facing MCP gateway and an operator/lifecycle API — because the kill-switch must be unreachable from the agent path by network policy, not by an in-process route guard (§3). Layer 5 grouped four of the zones into one bounded context (Agent Execution); that grouping is about domain ownership, not deployment, so it does not merge the boxes — Agent Execution is realized as five cooperating containers, and the sixth (Audit pipeline) is the Compliance Evidence context.
+
+## 2. Container diagram
+
+The diagram is [`diagrams/c4-container.mmd`](diagrams/c4-container.mmd) (six containers in the OCU box; five external actors for orientation). Edge labels name the protocol or token class that crosses; `1..N` marks the per-session container; all five source containers fan into the Audit pipeline over one Published Language (OCSF). External-actor contracts are in [`03-c4-context.md`](03-c4-context.md) §4, not restated here.
+
+## 3. The six containers
+
+Each sits in a Layer 3 zone and a Layer 5 context. Responsibility is one line; technology is a component-spec decision (under [`components/`](./components/), opened per [PROCESS.md](PROCESS.md)) and is named here only by role. NFR anchors are the measurable targets each container must meet.
+
+| Container | Zone | Context | Responsibility | NFR anchor |
+|---|---|---|---|---|
+| **MCP gateway** (agent-facing) | Control plane | Agent Execution | Terminates inbound MCP tool-calls and authenticates the caller; metadata-only, runs no agent loop and proxies no model. Holds no upstream credential, no lifecycle mutation, and no kill-switch. | [NFR-IC-04](manifesto/02-nfrs.md), [NFR-FLEX-14](manifesto/02-nfrs.md) |
+| **Control / operator API** | Control plane | Agent Execution | Session lifecycle, quota, the session denylist, and the kill-switch. Operator-only ingress; no path reachable from the MCP surface. | [NFR-SEC-01](manifesto/02-nfrs.md), [NFR-COMP-29](manifesto/02-nfrs.md) |
+| **Storage broker** | Storage broker | Agent Execution | Host-side object-store client holding the backend credential; signs its own backend requests. Two faces of one client: the guest mount (south — `filesystem_id`-scoped file-operation interface) and the data-plane client face (north — the file/artifact API plus OCU's authenticated SPA and preview-render, served as components inside this container, not a separate one). Both faces share the one backend credential and the one storage-lane backend leg ([NFR-SEC-85](manifesto/02-nfrs.md)); no other component speaks the object-store protocol ([NFR-SEC-25](manifesto/02-nfrs.md)), so one consistency view covers both faces. Resolves the `downloadable` axis at read for both faces ([NFR-SEC-73](manifesto/02-nfrs.md)); neither guest nor data-plane client holds a backend credential. The north face verifies the embed token and sets a first-party session ([NFR-SEC-82](manifesto/02-nfrs.md), [NFR-SEC-83](manifesto/02-nfrs.md)). Replica count is a deployment concern (§5). | [NFR-SEC-25](manifesto/02-nfrs.md), [NFR-SEC-15](manifesto/02-nfrs.md), [NFR-SEC-73](manifesto/02-nfrs.md), [NFR-SEC-79](manifesto/02-nfrs.md), [NFR-SEC-82](manifesto/02-nfrs.md), [NFR-SEC-83](manifesto/02-nfrs.md) |
+| **Session sandbox** `[1..N]` | Compute plane | Agent Execution | Executes one session's tool-calls in an isolated runtime that holds no standing secret and reaches the network only through the egress edge. Guest agent is PID 1; runtime tier by `workload_trust_profile`. | [NFR-SEC-02](manifesto/02-nfrs.md), [NFR-SEC-43](manifesto/02-nfrs.md) |
+| **Egress trust-edge proxy** | Egress trust-edge | Agent Execution | The single outbound path. Deny-by-default allow-list; emits a structured deny reason. On legs that require it, injects the upstream authorization received over Envoy SDS at the egress-wide-bump rung (the default once an upstream credential is configured); the transparent pass-through and deny-all rungs do not inject (see [`02-trust-boundaries.md`](02-trust-boundaries.md) §7, [ADR-0007](adr/0007-egress-auth-mechanism.md)). The broker's pre-signed backend leg traverses a storage-dedicated lane allow-list-only (no TLS termination), distinct from the guest egress lane ([NFR-SEC-85](manifesto/02-nfrs.md)); the rung is per-destination, not global. | [NFR-SEC-05](manifesto/02-nfrs.md), [NFR-SEC-23](manifesto/02-nfrs.md), [NFR-SEC-27](manifesto/02-nfrs.md), [NFR-SEC-29](manifesto/02-nfrs.md) |
+| **Audit pipeline** | Audit pipeline | Compliance Evidence | Captures session, tool, storage, and egress events into a hash-linked durable store and forwards to a customer-owned sink. | [NFR-SEC-03](manifesto/02-nfrs.md), [NFR-COMP-01](manifesto/02-nfrs.md) |
+
+The MCP gateway and the Control / operator API are the same trust zone (Control plane, §2) split into two runnable units so the §1 reachability property holds at deploy time — separate process, operator-only ingress, distinct privilege set. The guest agent is the process that constitutes the sandbox container, not an eighth container: it has no lifecycle independent of the sandbox and dies with it.
+
+## 4. Internal boundaries
+
+Token classes and their TTLs are canonical in [`02-trust-boundaries.md`](02-trust-boundaries.md) §8; this layer names which boundary each crosses. The `F#` column is the canonical flow label every component spec and [`06-threat-model.md`](06-threat-model.md) §3 reference; this table is its sole definition.
+
+| F# | Boundary | What crosses | Direction |
+|---|---|---|---|
+| F1 | Caller → MCP gateway | MCP authorization spec, audience-validated | inbound |
+| F2 | Operator → Control / operator API | PAM-JIT credential, operator-only ingress | inbound |
+| F3 | Customer IdP → Control / operator API | relying-party assertion (full shelf); contract in [`03-c4-context.md`](03-c4-context.md) §4 | inbound |
+| F4 | SOAR → Control / operator API | signed admin API for revoke (the inbound half of the SOAR contract); contract in [`03-c4-context.md`](03-c4-context.md) §4 | inbound |
+| F5 | MCP gateway → Control / operator API | session create / status, service identity | internal request |
+| F6 | Control / operator API → Session sandbox | Session JWT bound to `container_name` | host dials guest |
+| F7 | Storage broker → Session sandbox | file-operation mount, session resource handle | host dials guest |
+| F8 | Session sandbox → Egress trust-edge | the only outbound network path | one-way |
+| F9 | Storage broker → Egress trust-edge → backend | broker-signed request, allow-list-only | outbound |
+| F10 | {all five source containers} → Audit pipeline | OCSF event (Published Language) | fan-in |
+| F11 | Data-plane client → Storage broker (north face) | SPA + file/artifact API (upload/list/download), embed token verified → first-party session; scope + intent checked at accept, `downloadable` resolved at read ([NFR-SEC-73](manifesto/02-nfrs.md)) | inbound |
+
+Two properties are load-bearing at this layer. First, no guest path reaches a long-lived upstream secret — the Storage broker holds its backend credential host-side, and the upstream credential reaches the Egress trust-edge over SDS on the edge-originated leg, never the guest; the guest may hold a short-lived session-scoped handle to a host-side mediator, which is not the upstream secret. The mechanism that attaches the credential is selected per upstream ([ADR-0007](adr/0007-egress-auth-mechanism.md)): edge-inject in v1; the protocol-broker mechanism is the Storage-broker zone, deferred for other upstreams. Second, the control / exec channel is opened by the host into the guest (host dials, guest listens) with the caller identity host-derived, so a compromised guest cannot reach the kill-switch or impersonate another session ([NFR-SEC-43](manifesto/02-nfrs.md)).
+
+User-data and guest-internet traffic take different routes with different authorization. User-data is exchanged with the Storage broker over its two faces (south mount, north file/artifact API), where file authorization lives — scope, intent, `downloadable`. Guest-internet traffic takes the Egress trust-edge, where network authorization lives — allow-list, bump-rung inspection, upstream-auth injection — and the guest names no storage backend. The guest has no single path that does both. The two routes converge at one boundary already in the table above — `Storage broker → Egress trust-edge → backend` — where the broker's own backend leg leaves on the storage-dedicated lane allow-list-only ([NFR-SEC-85](manifesto/02-nfrs.md)) (the edge forwards a broker-signed request, it does not authorize the content). That north-face traffic is host-side caller↔broker, not a host↔guest channel, so NFR-SEC-43 is unaffected.
+
+## 5. Deployment shelves
+
+All six containers exist on both shelves; only the substrate differs. The diagram is shelf-agnostic. Scaling topology — node placement, sandbox scheduling, replica counts — is a deployment-view concern, not drawn here. The egress-substrate and identity-floor substitutions below are summarized from [`02-trust-boundaries.md`](02-trust-boundaries.md) §7–§8, which owns them. Egress posture is chosen by need (the §7 ladder, [ADR-0007](adr/0007-egress-auth-mechanism.md)), not by shelf; the row below shows only the substrate each shelf supplies under that ladder.
+
+| Container | Minimal shelf (one-click solo) | Full shelf |
+|---|---|---|
+| MCP gateway | single process, co-located | scheduled, single instance per deployment |
+| Control / operator API | co-located, host-rooted local operator credential | scheduled; customer-IdP-asserted operator identity |
+| Storage broker | host-local backend credential | customer-PKI workload identity; STS-scoped per session |
+| Session sandbox | local runtime, `runc` default | hardened or hardware-virt tier per workload |
+| Egress trust-edge proxy | auto-generated per-deployment CA + file SDS source (pre-minted leaves for an enumerable allow-list) | external/customer SDS source; dynamic per-SNI minter for a non-enumerable allow-list |
+| Audit pipeline | file-system sink | OCSF bridge to customer SIEM |
+
+## 6. Industry comparison
+
+The agent-facing / operator split (containers 1 and 2) is the dominant shape across orchestrated sandbox platforms: caller-facing surfaces and lifecycle surfaces are separate deployables. OCU adopts that split and additionally motivates it with the kill-switch reachability invariant rather than protocol convenience alone.
+
+Two seams diverge from the field by design, for an in-perimeter regulated buyer whose threat model is an adversarial workload rather than inbound multi-tenant routing:
+
+- **Storage broker as its own container.** Storage is the least-separated concern elsewhere — usually backed by external object storage or host-local volumes managed inside the control plane. OCU keeps the backend credential and the plaintext content-inspection point out of the agent-reachable surface, which the blast-radius requirement demands ([NFR-SEC-25](manifesto/02-nfrs.md)).
+- **Egress as a credential-injecting enforcement chokepoint.** Dedicated proxies are near-universal but almost all are ingress/routing proxies. OCU's egress edge is the sole outbound path, deny-by-default, and the upstream-authorization injection point — the credential reaches it over Envoy SDS, is attached on the re-originated leg ([ADR-0007](adr/0007-egress-auth-mechanism.md)), and the guest never holds the long-lived upstream secret.
+
+## 7. Open questions
+
+1. Does the Session sandbox warrant a sub-container split once the workload-trust tier and guest-agent protocol are specified, or stay one container with internal components? — [#174](https://github.com/Wide-Moat/open-computer-use/issues/174).
+2. Is the Storage broker one container per deployment or one per sandbox host, and does the answer change the diagram? — [#175](https://github.com/Wide-Moat/open-computer-use/issues/175).