@mseep/open-computer-use 1.0.0

package/docs/architecture/06-threat-model.md

@@ -0,0 +1,172 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-05-30
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+STRIDE-per-element threat model over the Layer 6 container DFD, with each threat resolved to a controlling NFR. Audience: security engineers and auditors reviewing the trust-boundary controls.
+
+## 1. Scope and DFD reference
+
+This model runs STRIDE-per-element over the six containers, one data store, five external actors, and eleven boundary-crossing flows fixed in [`05-c4-container.md`](05-c4-container.md) §3–§4. [`diagrams/c4-container.mmd`](diagrams/c4-container.mmd) draws the container/edge subset; the data-store and IdP/SOAR elements and the `F1`–`F11` flow labels are STRIDE elements named here, not nodes on that diagram — the DFD is not redrawn here. STRIDE letters apply per the Microsoft element-type mapping (§2); severity is qualitative Likelihood × Impact, and each row anchors to an NFR-SEC target with the per-zone framework cell from [`02-trust-boundaries.md`](02-trust-boundaries.md) §11.
+
+Each threat names the actor it is reachable by. The model inverts the usual ingress focus: the primary adversary is A1, so the high-value rows weight the sandbox's outbound and host-facing edges, not the inbound caller edge.
+
+| Actor | Who | Standing in this model |
+|---|---|---|
+| **A1** in-sandbox guest | the agent/code under execution, holding in-sandbox root | primary adversary — the model is built against it |
+| **A2** external caller | an MCP-speaking caller or network actor outside the perimeter | untrusted; authenticates at the gateway |
+| **A3** host-foothold | a guest that already escaped the sandbox, or a compromised host / insider operator | a distinct trust level — an A3 threat is conditional on a prior escape (then it derives from the escape control, [NFR-SEC-02](manifesto/02-nfrs.md)) or sits behind the trusted-host assumption, not a failure of guest isolation |
+
+## 2. Element inventory and STRIDE applicability
+
+| Element | Type | Applicable STRIDE |
+|---|---|---|
+| P1 MCP gateway | process | S T R I D E |
+| P2 Control / operator API | process | S T R I D E |
+| P4 Storage broker (south-face mount + north-face SPA/file-artifact API) | process | S T R I D E |
+| P5 Session sandbox [1..N] | process | S T R I D E |
+| P6 Egress trust-edge proxy | process | S T R I D E |
+| P7 Audit pipeline | process | S T R I D E |
+| D2 Audit pipeline store | data store (log) | T I D R |
+| F1–F11 boundary flows | data flow | T I D (+ S/E per boundary) |
+| E1 caller · E2 operator · E3 IdP · E4 SOAR · E5 data-plane client | external | S R |
+
+Element IDs P3 and D1 are intentionally absent: they named the former Credential custody process and its store, removed by [ADR-0005](adr/0005-egress-credential-delivery-envoy-sds.md). The upstream credential now reaches P6 over Envoy SDS from an external source (a static file or a customer store); the threats that survive that change are carried on the P6 rows, and the SDS source's own at-rest exposure is the source operator's, outside this boundary. The attachment mechanism is edge-inject at the egress-wide-bump rung ([ADR-0007](adr/0007-egress-auth-mechanism.md)); the dynamic per-SNI minter implementing that rung is self-hosted OCU code while the file SDS source is off-the-shelf.
+
+E1, E2, and E4 carry their S/R threats inline (P1, P2 rows). E5 (the data-plane client) carries its S/R threats inline on the broker north face (the P4 §3.2 rows on F11). E3 (the customer IdP) is a relying-party trust anchor whose own spoofing/repudiation is owned by the customer's identity estate, outside the OCU boundary; its failure surfaces here only as the F3 availability dependency (P2-D2).
+
+## 3. Live threats
+
+Every element and its applicable STRIDE letters are enumerated in §2; this section details the threats whose control is incomplete (PARTIAL — a controlling NFR is specified, implementation tracked). Fully-mitigated threats are listed in §4. Rows are split by the actor that reaches them (§2 actor table): §3.1 the threats an in-sandbox guest (A1) can reach — the primary adversary — and §3.2 those reachable only by an external caller (A2) or a host-foothold (A3).
+
+### 3.1 Reachable by the in-sandbox guest (A1)
+
+| ID | Element/edge | STRIDE | Actor | Threat | Rating | Mitigation (arch) | Anchor (NFR + framework) | Residual | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| P2-T2 | F6 (denylist/kill-switch on RPC path) | T | A1 | P5 drops/stalls the host-dialed control RPC so a revoked or killed session keeps executing past SLA. | Med | Denylist checked host-side on every RPC (guest cannot read or mutate it); kill-switch is a host-initiated container stop ≤30s p99, not a cooperative guest action; fail-closed — channel unreachable yields no new authority. | NFR-SEC-01; NYDFS §500.7, DORA Art.6, EU AI Act Art.14, CCM IAM-06 | Stop SLA assumes a trustworthy host clock for TTL/SLA accounting (#185). | PARTIAL |
+| P2-D1 | F1→F5 inbound + F2/F3/F4 operator ingress | D | A2+A1 | Flood of session-create (via F5) or operator/SOAR calls exhausts the single control-plane instance, blocking the kill-switch/revoke path during an incident. | High | Per-caller quota at P2; operator ingress is a distinct path from the agent/service-identity path so agent-side flooding cannot starve the kill-switch route; fail-closed denies new sessions rather than degrading revoke. | NFR-SEC-55 + REL-01; NYDFS §500.7, DORA Art.6, EU AI Act Art.14, CCM IAM-06 | Kill-switch ≤30s p99 under concurrent control-plane DoS is specified by NFR-SEC-55 (REL-01 the post-failure backstop). | PARTIAL |
+| P2-E1 | P2 agent path → operator capability | E | A2+A1 | Agent-path principal (F1→F5, compromised P1, or a P5 that reached P1) escalates from metadata-only ops to operator capabilities by finding a route into the operator surface. | High | Kill-switch unreachable from the MCP path by deploy-time network policy across two separate containers, not an in-process guard; distinct privilege set and operator-only ingress; the P1 service-identity audience carries no operator scopes; no MCP-surface code path maps to a lifecycle/kill-switch route. | NFR-SEC-52 + SEC-01; NIST 800-207 §2.1, NYDFS §500.7, EU AI Act Art.14, CCM IAM-06 | The CI IaC-policy assertion of gateway↛operator separation is specified by NFR-SEC-52. | PARTIAL |
+| P4-T1 | F7 broker→sandbox (mount) | T | A1 | Guest crafts malformed/oversized file-ops (path traversal, symlink/`..` escape, oversized write) to write outside the session prefix or corrupt another mount. | High | Broker exposes only file-op verbs, not the object-store protocol; resolves every path inside the host-attested prefix and rejects traversal; STS credential is prefix-scoped, so even a resolver bug cannot sign a write outside the prefix at the backend. | NFR-SEC-25 + SEC-46; EU AI Act Art.10, CCM DSP-01, DORA Art.28 | Path-confinement is an impl property (traversal-bug residual, caught by property-tests); the oversized-write tail is bounded by the NFR-SEC-46 max-object/max-message/mandatory-chunk ceiling (pre-buffer reject). | PARTIAL |
+| P4-I2 | F7 broker→sandbox (mount content) | I | A1 | Guest reads another tenant's user-data via cached/leftover content on a reused mount substrate (remanence), or a list enumerates beyond the prefix. | Med | Mount and handle session-scoped and bound to host-attested identity; user-data on a per-session volume, image carries no PII, cryptographic erasure on teardown; list/read confined to the session prefix. | NFR-SEC-15 + SEC-33 + SEC-25 + SEC-73; EU AI Act Art.10, CCM DSP-01, NYDFS §500.15(a) | Cross-session remanence depends on broker teardown discipline; deterministic per-session erasure ordering not yet pinned to an NFR scenario. | PARTIAL |
+| P4-D1 | F7 broker→sandbox (mount) | D | A1 | Hostile guest issues unbounded file-ops / huge writes / fd exhaustion against the mount, degrading the broker for co-located sessions (noisy-neighbour via shared broker). | Med | NFR-SEC-46 covers broker-side per-session rate limits (file-ops/s, in-flight bytes, fd). The broker may be one-per-host serving many sessions, making it a shared DoS surface. | NFR-SEC-46; DORA Art.28, CCM IVS-06, NYDFS §500.7 | Broker per-session file-op rate/quota and the max-object/message/chunk ceiling specified by NFR-SEC-46. | PARTIAL |
+| P4-D2 | F9 broker→edge→backend | D | A1 | Guest drives backend-bound traffic (large/repeated reads/writes) to exhaust per-session STS quota or trigger backend throttling/cost-blowout. | Low | F9 traverses the storage-dedicated lane (NFR-SEC-85) as one destination, so the path is observable and policy-gated; a direct broker→backend dial bypassing the lane is forbidden so all backend traffic is visible to one out-of-broker control; a local-volume engine (ADR-0010) opens no network leg. | NFR-SEC-85 + SEC-16; DORA Art.28, CCM IVS-09, NYDFS §500.5 | Per-session backend rate/quota ceiling not pinned (overlaps #188); the lane sees the leg but no canon limit caps backend cost per session. | PARTIAL |
+| P4-E1 | P4 broker — confused-deputy via mount | E | A1 | Guest induces the higher-privileged broker to perform a backend op it could not authorize itself, e.g. smuggling a backend key/prefix through a file-op argument the broker forwards into a signed request. | High | Privilege separation: guest names only file-op verbs against its session-scoped handle; broker maps that to a request signed with its own credential, and the handle is a hint cross-checked against host-attested identity; the guest cannot name a backend object directly. | NFR-SEC-25 + SEC-43 + SEC-76; NIST 800-207 §2.1, DORA Art.28, CCM CEK-08/DSP-01 | The deputy boundary is only as tight as the verb-to-backend mapping; accept-time non-host-peer reject + broker-per-tenant specified by NFR-SEC-76; per-action authz tracked at #187. | PARTIAL |
+| P4-E2 | F9 broker→egress (uncontrolled outbound path) | E | A1 | Broker opens a direct broker-to-object-store dial bypassing the storage lane, creating an outbound path the control cannot see — an uncontrolled exfil channel. | Med | A direct broker-to-backend dial bypassing the storage lane is forbidden; the backend leg traverses the storage-dedicated lane (NFR-SEC-85) — out-of-process from the broker — under a deny-by-default allow-list, the exfil tripwire, and an edge-authored OCSF event a compromised broker cannot suppress, so no path the control cannot see exists by policy. | NFR-SEC-85 + SEC-16; CCM IVS-09/DSP-05, DORA Art.30 | Storage user-data content is inspected at the broker on plaintext before signing (NFR-SEC-81); the lane is pass-through, so deep content DLP on legitimately-written objects stays broker-side — content-blind theme #182. | PARTIAL |
+| P5-T1 | F10 P5→audit (guest as its own source) | T | A1 | With in-sandbox root the guest suppresses, fabricates, reorders, or backfills the OCSF events it emits for its own in-sandbox actions; the chain protects events once in the pipeline, not their truthfulness at origin. | High | Out-of-band evidence for in-sandbox actions is specified by NFR-SEC-47 (host-/hypervisor-side capture — egress event correlation, sentry/VMM syscall telemetry, broker file-op log — the guest cannot author). The chain secures transport+store integrity, not source veracity. | NFR-SEC-47; EU AI Act Art.12, NYDFS §500.6, DORA Art.10 | Out-of-band capture specified by NFR-SEC-47 (host-side mediation + runtime-monitor); #181. | PARTIAL |
+| P5-I1 | P5 cross-tenant on shared substrate | I | A1 | Guest mounts a microarchitectural side-channel (Spectre/MDS, cache timing, port contention) against a co-resident tenant or the host, independent of any logical escape. | High | NFR-SEC-58 covers the per-tier posture (SMT-off + microcode + single-tenant pinning on the reduced tier; declared-not-eliminated on shared-kernel). Higher tiers reduce co-residency but do not bound the channel. | NFR-SEC-58; EU AI Act Art.15(4), CCM IVS-06, NYDFS §500.15 | Side-channel posture specified per tier by NFR-SEC-58 (declared-not-eliminated on shared-kernel); measurable target tracked at #183/#148. | PARTIAL |
+| P5-D1 | P5 resource consumption on shared substrate | D | A1 | Guest exhausts node resources (fork-bomb/PID explosion, disk fill, memory pressure → non-deterministic OOM) to degrade or kill co-resident sessions or the host. | High | The per-container PID ceiling and CPU/memory cgroup limits are mandated as a hardening invariant; disk quota on mount/scratch and deterministic OOM-kill scoping are specified by NFR-SEC-46. | NFR-SEC-14 + SEC-46 + SEC-74; EU AI Act Art.15(4), CCM IVS-09, DORA Art.6 | Disk quota on mount/scratch + deterministic OOM-kill scoping specified by NFR-SEC-46 (PID/CPU/mem ceiling already NFR-SEC-14); #188. Stdio-flood memory-pressure over the exec channel bounded by NFR-SEC-74. | PARTIAL |
+| P5-D2 | F8 P5→egress edge (sole outbound) | D | A1 | Guest floods the edge with connection/request volume to deny outbound access to itself and co-tenant sessions sharing the edge, or to amplify against an allow-listed upstream. | Med | Single forward proxy, deny-by-default allow-list, bounds reachable destinations; fail-closed drops traffic if the proxy is unreachable rather than bypassing; per-session egress rate/connection quota is a component-spec target, not a canon NFR. | NFR-SEC-05 + SEC-27; EU AI Act Art.15(4), CCM IVS-09, NYDFS §500.5 | Destination set bounded; per-session egress rate-limit not stated (folds into #188). | PARTIAL |
+| P5-I3 | F8 P5→edge→upstream (transparent mode) | I | A1 | Agentic exfiltration: guest tunnels tenant data to an allow-listed destination over default transparent (content-blind) egress (DNS/HTTP smuggling, encoded payloads), undetectable because inspection runs only at the egress-wide-bump rung. | High | Allow-list + structured deny bounds destinations but not payload content; DLP-ICAP inspection runs at the egress-wide-bump rung; the transparent pass-through rung is content-blind by design; AI-content/exfil policy is the customer AI-gateway's contract on this path. | NFR-SEC-57; CCM DSP-05, EU AI Act Art.15, NYDFS §500.15 | Payload-independent exfil tripwire specified by NFR-SEC-57; deep content DLP stays bump-rung-only (#182). | PARTIAL |
+| P5-R1 | P5 in-sandbox action accountability | R | A1 | An in-sandbox action cannot be non-repudiably attributed because its only authoritative record originates inside the guest; with P5-T1 the session can deny/misattribute, and a trusted-time dependency lets ordering be questioned. | High | Host-attested session identity binds host-observed events; hash-chained audit orders accepted events. Gaps: in-sandbox evidence is guest-authored (P5-T1/#181) and ordering assumes a trustworthy clock (no trusted-time control). | NFR-SEC-47 + SEC-48; NYDFS §500.6, EU AI Act Art.12, DORA Art.10 | Out-of-band evidence (NFR-SEC-47) + monotonic-clock ordering (NFR-SEC-48) specified; the in-sandbox-evidence + clock-trust residual stays (M-4/#181, #185). | PARTIAL |
+| P6-R1 | P6→audit (F10) and F8 deny path | R | A1 | An exfiltration or policy-violating egress attempt is later disputed because the decision (allow/deny, destination, injected-or-not, session) was not durably recorded, or the deny reason was free-text. | Med | Edge emits OCSF for every allow and deny; denials carry a structured `x-deny-reason` header so audit and SOAR classify without parsing free text; SNI pre-filter drops and L7 inspections both record. | NFR-SEC-03; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01 | In transparent pass-through the edge logs destination (SNI/connection metadata) but not request content, so a content-level dispute is non-repudiable only by metadata — same root cause as #182. | PARTIAL |
+| P6-I1 | F8 sandbox→edge (content-blind transparent) | I | A1 | Hostile guest tunnels sensitive data to an allow-listed-but-attacker-usable destination; transparent pass-through is content-blind, so agentic exfil to an allowed endpoint is undetectable. | High | Architecture caps blast radius (deny-by-default allow-list narrows destinations; guest holds no long-lived upstream secret so it can exfil only what it reads in-session); content inspection/DLP runs at the egress-wide-bump rung; the transparent pass-through rung does not inspect. | NFR-SEC-57 + SEC-73; NIST PEP §3.4.1, NYDFS §500.5, DORA Art.30, EU AI Act Art.14, CCM DSP-05 | Payload-independent exfil tripwire specified by NFR-SEC-57; broker-side downloadable-axis deny (NFR-SEC-73) blocks non-downloadable content independent of inspection mode; an allow-listed endpoint stays content-blind for downloadable content in transparent mode (#182). | PARTIAL |
+| P6-I2 | SDS-delivered credential injected in flight | I | A1 | The injected upstream credential leaks toward the guest — an error/redirect or reflected header carries the injected Authorization back into a guest-visible response at the egress-wide-bump rung. | High | Credential injected only on the edge-originated upstream leg, never on the guest→edge leg; the guest carries no long-lived upstream secret on the guest→edge leg; edge must strip injected auth from any response surface; the credential is received from the SDS source at injection and never persisted at the edge. | NFR-SEC-23 + SEC-29; NYDFS §500.15(a), DORA Art.28, EU AI Act Art.15, CCM CEK-08 | No listed NFR mandates response-side stripping of reflected injected auth at the edge — needs an explicit no-credential-in-response invariant ([#197](https://github.com/Wide-Moat/open-computer-use/issues/197)). | PARTIAL |
+| P6-D1 | F8 sandbox→edge (sole outbound); edge availability | D | A1 | Edge becomes unreachable (crash, flood, upstream timeout storm); as the sole outbound path its loss blocks all session egress; the variant is fail-open vs fail-closed. | High | Fail-closed by design: if the proxy is unreachable the Compute plane drops outbound traffic and never bypasses; unallowed destinations dropped cheaply at SNI pre-filter before TLS, limiting handshake-exhaustion cost from a flooding guest. | NFR-SEC-46 + SEC-53; NIST PEP §3.4.1, NYDFS §500.5, DORA Art.30, EU AI Act Art.14, CCM IVS-09 | Per-sandbox egress connection-rate / FD ceiling specified by NFR-SEC-46/53 (#188). | PARTIAL |
+| P6-E1 | F8 sandbox→edge (allow-list bypass) | E | A1 | Hostile guest reaches a destination outside the allow-list via domain-fronting (SNI≠Host), CONNECT abuse, DNS rebinding, raw-IP/non-HTTP, or a second route bypassing the edge. | High | Deny-by-default allow-list on the edge, which is the outbound path; sandbox has no route out except the edge (no second NIC/route); unallowed destinations dropped at SNI pre-filter before TLS; allowed destinations inspected at L7 so SNI/Host mismatch is caught on the inspected leg; broker direct-dial bypass forbidden. | NFR-SEC-27 + SEC-05 + SEC-16; NIST PEP §3.4.1, NYDFS §500.5, DORA Art.30, EU AI Act Art.14, CCM IVS-09 | SNI pre-filter alone misses SNI/Host domain-fronting on the transparent (non-inspected) leg; L7 SNI/Host consistency is enforced only where inspection runs — needs SNI/Host consistency enforcement in transparent mode ([#198](https://github.com/Wide-Moat/open-computer-use/issues/198)). | PARTIAL |
+| P6-E2 | F8/upstream (forcing injection onto unintended destination) | E | A1 | Guest induces the edge to inject a high-value credential toward a destination it was not scoped for (cross-scope allow-list entry, open-redirect on an allowed upstream), elevating from session scope to the credential's full upstream authority. | High | Injection is gated on a presented scoped credential carried by the request, never on the request's network origin — the "inject because traffic came from sandbox X" network-origin gate is the forbidden anti-pattern ([ADR-0007](adr/0007-egress-auth-mechanism.md), which tightens this row). The credential's scope is set at the SDS source (one bucket prefix / API-key class); the edge attaches only the SDS-delivered credential matching the validated destination, so an injected credential is bounded to its source-set scope even if mis-routed. | NFR-SEC-29 + SEC-23 + SEC-73; NYDFS §500.15(a), DORA Art.28, EU AI Act Art.15, CCM CEK-08 | NFR-SEC-29 caps blast radius; the downloadable-axis half specified by NFR-SEC-73; the destination-to-credential binding rule and minimum-scope/action-level authz tracked at #187. | PARTIAL |
+| P6-E3 | F8 destinations requiring client-mTLS / cert-pinning / DPoP | E | A1 | An upstream that cannot accept edge-injected authorization forces a choice — place the credential in the guest (defeating no-standing-secret) or do not serve it; a guest-held workaround is itself an escalation. | High | Architecture does not permit a guest-held credential workaround; the customer configures the SDS source to supply the client cert / PoP key, or such upstreams stay out of the edge-injection contract rather than served by placing keys in the guest. | NFR-SEC-50; NYDFS §500.15, DORA Art.28, EU AI Act Art.15, CCM IVS-09 | Edge re-origination for mTLS/cert-pin/DPoP specified by NFR-SEC-50 (egress-wide-bump rung); edge-inject cannot satisfy cert-pin/client-mTLS/PoP upstreams ([ADR-0007](adr/0007-egress-auth-mechanism.md)); guest-resident-key schemes declared unsupported (#176). | PARTIAL |
+| P7-S1 | P7 audit (OCSF source identity; via F10 fan-in) | S | A1 | Compromised P5 forges OCSF events impersonating another source container (source=control-plane/egress) so its actions are attributed to a trusted host-side component, or fabricates clean events to mask malicious tool-calls. | High | Source identity at fan-in should be the host-attested workload identity of the connecting principal, never a guest-settable source field; the guest channel is pinned to source=sandbox/<its-session>, and an event claiming any other source from that principal is rejected — specified by NFR-SEC-47 (out-of-band capture, host-attested source). | NFR-SEC-47; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 | Host-attested binding of the OCSF source at ingestion specified by NFR-SEC-47; #181. | PARTIAL |
+| P7-R2 | P5 sandbox (self-reported events; via F10) | R | A1 | The guest is its own audit source for purely in-sandbox actions (file edits, sub-process spawns, reasoning steps); with in-sandbox root it suppresses/omits/falsifies these before fan-in, so the chain faithfully records a lie. | High | Out-of-band evidence: host-observed signals the guest cannot edit — egress request log (P6), storage file-op log (P4), control-plane RPC log, runtime syscall/exec capture at the supervisor (gVisor sentry / microVM); the self-report is corroborated against these rather than trusted alone. NFR-SEC-47 covers the out-of-band corroboration set. | NFR-SEC-47; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 | Out-of-band evidence set specified by NFR-SEC-47; purely in-sandbox actions with no host-side side-effect stay the hardest case (#181). | PARTIAL |
+| P7-D1 | F10 audit→customer sink (backpressure) | D | A1 | The downstream SIEM sink slows or becomes unreachable; backpressure fills the durable bus, forcing either event drops (audit gap) or source-container blocking (cascading session stall), amplifiable by a high-volume guest. | High | Durable bus on the critical path (events committed locally before acknowledgement) plus a local file-system sink as the always-present floor; the SIEM bridge is decoupled and replays from the durable store on recovery. NFR-REL-12 mandates the bus but no measurable end-to-end backpressure target. | NFR-REL-12; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 | Sustained sink failure plus adversarial amplification has no defined saturation/spill behaviour or measurable target (#150; resource-exhaustion #188). | PARTIAL |
+| P7-D2 | F10 sandbox→audit (event-volume flood) | D | A1 | A compromised guest emits a high-rate flood of well-formed OCSF events to exhaust collector ingest, fill the durable store / retention budget, or dilute true events with noise (distinct from P7-D1). | Med | Audit-pipeline backpressure headroom ≥10× peak with no silent drop and zero chain breaks bounds collector-ingest exhaustion and the no-drop dimension; per-source ingest fairness keyed to host-attested source identity would bound a single session's share but is not yet mandated. | NFR-PERF-10; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 | No per-source/per-session fairness or retention-budget cap keyed to host-attested identity; forensic-value dilution within the no-drop budget uncovered (#188, extended to audit-ingest quota). | PARTIAL |
+| P5-I4 | P5 guest-spawned process (env/argv at spawn) | I | A1 | A guest-spawned process inherits a host-environment secret, or a secret passed on argv leaks via `/proc/<pid>/cmdline` to a same-namespace process. | Med | Allowlist-only env injection — the host strips the deny-pattern set (`*_TOKEN`/`*_SECRET`/`*_PASSWORD`/`API_KEY`) and injects only declared vars; secrets pass via env or fd, never argv. | NFR-SEC-75 + SEC-43; NYDFS §500.7, DORA Art.6, CCM IAM-08/IVS-06 | Spawn-time inheritance / argv leak specified by NFR-SEC-75; distinct from the at-rest token-snapshot vector (P5-I2/#184). | PARTIAL |
+
+### 3.2 Reachable only off a host foothold or external position (A2 / A3)
+
+A3 rows are conditional on a prior sandbox escape (then they derive from [NFR-SEC-02](manifesto/02-nfrs.md)) or sit behind the trusted-host assumption — not a failure of guest isolation.
+
+| ID | Element/edge | STRIDE | Actor | Threat | Rating | Mitigation (arch) | Anchor (NFR + framework) | Residual | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| P1-S1 | F1 caller→gateway | S | A2 | Rogue client replays/forges a bearer token, or presents a wrong-audience token, to open/address sessions it does not own. | High | Gateway is a relying party validating issuer/audience/expiry against the customer IdP; identity never self-asserted in the body. Full shelf uses the customer IdP, minimal shelf a host-rooted local credential. | NFR-SEC-09 + FLEX-03 + SEC-10; NYDFS §500.7/§500.12, DORA Art.30, EU AI Act Art.13, CCM IAM-08 | Audience binds token to the deployment, not to one session; per-tool/per-action authz unstated. | PARTIAL |
+| P1-S2 | F5 gateway→Control API | S | A2 | Gateway forges/escalates a service identity on F5 so the Control API treats a session request as a more privileged principal. | Med | Control API authenticates the gateway service principal, not an operator; kill-switch and lifecycle live only on operator-only ingress, split enforced by network policy and distinct privilege set, not an in-process guard. | NFR-SEC-26 + §3 split; NYDFS §500.7, DORA Art.6, EU AI Act Art.14, CCM IAM-06 | Minimum scope of the gateway's internal token on F5 is unstated. | PARTIAL |
+| P1-T1 | F1 caller→gateway | T | A2 | On-path attacker rewrites tool-call parameters (container_name, args, selector) in flight. | Med | F1 is TLS 1.3; gateway validates audience/integrity before acting; metadata-only and credential-free, so a tampered request cannot escalate beyond the validated caller, and host-derived F6 identity is the downstream authority. | NFR-SEC-33; NYDFS §500.15, DORA Art.30, EU AI Act Art.13, CCM IAM-08 | Parameter-schema validation depth is component-spec, not pinned. | PARTIAL |
+| P1-T2 | F5 gateway→Control API | T | A2 | Gateway crafts an F5 body claiming another tenant's session_id/container_name to bind or read a session it does not own. | High | Host-attested identity invariant: a body-supplied id is a hint cross-checked against host-derived identity; Control API derives the binding and the host dials the guest on F6; cross-session reachability disabled. | NFR-SEC-43; NYDFS §500.7, DORA Art.6, EU AI Act Art.14, CCM IAM-06 | Cross-check binds the gateway service identity, not the end-caller's tenant; per-tool/action authz unstated. | PARTIAL |
+| P1-R1 | E1 caller (action attribution; via F1) | R | A2 | Caller denies issuing a tool-call/session-create; no independent record attributes the action. | Med | Gateway emits an OCSF event on F10 per terminated request with validated caller identity; hash-chained store, daily Merkle head to a transparency log. | NFR-SEC-03; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01 | Ordering depends on a trustworthy clock (#185); metadata-only gate not yet measurable (#149). | PARTIAL |
+| P1-I1 | F1 caller→gateway | I | A2 | Verbose MCP errors / tool-discovery leak session ids, container_names, tenant ids, or the operator interface to a low-privilege caller. | Med | Gateway is metadata-only and holds no credential or kill-switch state, bounding the leak; structured (not free-text) responses per the egress deny-reason discipline; F1 TLS 1.3. | NFR-SEC-33 + SEC-51; NYDFS §500.7, DORA Art.30, EU AI Act Art.13, CCM IAM-08 | Outbound error/discovery size-bound + identifier-minimization specified by NFR-SEC-51 (#149). | PARTIAL |
+| P1-D1 | F1 caller→gateway | D | A2 | Caller floods the agent-facing MCP surface, exhausting gateway connections/CPU and indirectly pressuring the lifecycle plane via F5. | High | Gateway is a separate runnable unit from the Control API; MCP saturation cannot reach operator ingress or the kill-switch (distinct network policy); per-tenant MCP-calls/min + concurrent-session quota bounds the flood and the F5 spillover. | NFR-COST-06 + SEC-01 + SEC-53; NYDFS §500.7, DORA Art.6, EU AI Act Art.14, CCM IAM-06 | Per-caller connection / fd ceiling at the gateway socket is specified by NFR-SEC-53. | PARTIAL |
+| P1-E2 | F1 caller→gateway | E | A2 | Caller invokes a tool/session operation beyond its authorization because the gateway authenticates but does not enforce per-tool/per-action authz. | High | Audience-validated authN bounds who reaches the surface; gateway holds no credential and host-attested identity blocks cross-session addressing downstream — fine-grained per-tool/action authz is specified by NFR-SEC-49. | NFR-SEC-49; NYDFS §500.7, DORA Art.6, EU AI Act Art.13/14, CCM IAM-08 | Per-tool/per-action authorization specified by NFR-SEC-49 (#187/G1/G8). | PARTIAL |
+| P2-R1 | P2 privileged operator actions | R | A3+A2 | Operator (or a spoofed one) force-kills, edits the denylist, or overrides quota beyond tier-downgrade and denies it; only tier-downgrade is mandatorily audited (M-2). | High | Every operator action must emit a mandatory OCSF event into the hash-chained pipeline, independent of the operator's assertion; operator identity bound; the mandatorily-audited action set must be enumerated, not limited to tier-downgrade. | NFR-SEC-45; NYDFS §500.6, EU AI Act Art.12/Art.14, DORA Art.10, CCM LOG-01 | Mandatory audit of privileged operator actions specified by NFR-SEC-45 (#186/M-2). | PARTIAL |
+| P2-R2 | E4 SOAR (action attribution; via F4) | R | A2 | A SOAR revoke/kill is disputed (SOAR or a forged caller?), or replayed/forged to deny service. | Med | SOAR uses a signed admin API; the control plane verifies the signature against E4's key before acting, binding the action to SOAR; the action emits an OCSF event with the SOAR principal. | NFR-SEC-01; NYDFS §500.6, DORA Art.28, CCM IAM-08/LOG-01 | Mandatory-audit gap (#186/M-2) means a SOAR revoke of a non-tier action may not be guaranteed-audited; inherits P2-R1. | PARTIAL |
+| P2-I1 | P2 control-plane metadata / session registry | I | A2+A3 | Caller (via F5) or operator enumerates session registry, container_names, quota, or tenant ids of other tenants; metadata is itself sensitive. | Med | Service-identity audience scoped to the caller's own sessions; operator authority scoped per access-privilege model; control plane carries no customer payload; host-attested identity blocks cross-session F6 status queries. | NFR-IC-04; NIST 800-207 §2.1, NYDFS §500.7, DORA Art.28(2)(c), CCM IAM-06 | No-customer-payload gate not yet a measurable target (#149). | PARTIAL |
+| P4-S2 | P4 broker→backend | S | A3 | Compromised/impersonated broker authenticates to the backend as the tenant principal and reaches objects outside any live session scope. | Med | Full shelf gives the broker a customer-PKI workload identity with STS-scoped-per-session backend creds, so it can assume only the narrow per-session role; minimal shelf falls back to a host-local backend credential. | NFR-SEC-25; NYDFS §500.15(a), DORA Art.28, CCM CEK-08 | Minimal shelf host-local credential is broader than per-session STS; blast radius is the whole bucket on broker-host compromise — accepted for one-click solo, called out by the shelf split. | PARTIAL |
+| P4-I1 | P4 broker — backend cred in process | I | A3 | Disclosure of the backend credential the broker holds (process compromise, memory scrape, leak onto the mount surface) gives direct backend access bypassing session scoping. | Med | Credential host-side only; guest holds a filesystem_id, never the backend key; broker exposes no object-store protocol toward the guest; full shelf narrows the held secret to an STS-scoped-per-session credential. | NFR-SEC-25 + SEC-33; NYDFS §500.15(a), CCM CEK-08, DORA Art.28 | Minimal shelf holds a long-lived host-local credential (full-backend on broker-host compromise); STS floor and per-action minimum unstated (#187). | PARTIAL |
+| P4-S3 | F11 data-plane client→broker (north face, embed-token) | S | A2 | Replays a captured short-TTL embed token within its `exp` window from another origin/browser, presents a wrong-audience or unsigned (`alg:none`) token, or frames the UI (no `frame-ancestors`) to fix an attacker-chosen session onto the victim. | High | Peer backend mints the signed embed token; the UI verifies signature + `exp ≤120 s` + OIDC-asserted audience and only then sets a first-party session; no OCU upstream secret enters the browser. `frame-ancestors` per-deployment allowlist denies the cross-origin framing that drives session-fixation. | NFR-SEC-82 + SEC-83; NYDFS §500.7, NIST 800-207 §2.1, DORA Art.28, EU AI Act Art.13, CCM IAM-08 | `exp ≤120 s` caps the window but NFR-SEC-82 specifies no replay-binding (no `jti`/nonce single-use, no token↔channel binding), so a token replayed inside its TTL from another origin still verifies ([#217](https://github.com/Wide-Moat/open-computer-use/issues/217)). | PARTIAL |
+| P4-T3 | F11 data-plane client→broker (north face, cookie-bound file API) | T | A2 | Cross-site forgery of an upload/delete/state-mutating call against the first-party cookie — the `SameSite=None` cookie (mandatory for cross-site iframe embedding) disables the SameSite backstop — or the embed token rides in the iframe `src` query and leaks via `Referer` to page sub-resources. | High | First-party `SameSite=None; Secure; HttpOnly` cookie with a server-validated CSRF token on every state-mutating request and no anonymous fallback (401 on missing/invalid cookie); `HttpOnly` blocks script theft of the session; the OCU upstream secret never enters the browser (NFR-SEC-82). | NFR-SEC-84 + SEC-82; NYDFS §500.15(a), DORA Art.28, EU AI Act Art.15, CCM IVS-09 | CSRF defence specified by NFR-SEC-84; the token-pattern choice (synchronizer vs double-submit) and Referer/`exp`-in-URL avoidance are API-surface-hardening impl tracked at #187. | PARTIAL |
+| P4-I3 | F11 data-plane client→broker (north face, list/download/preview) | I | A2 | Calls `list`/`download`/`preview` with a forged or swapped `filesystem_id`/artifact id to read another tenant's objects over HTTP (the API analogue of the south-face mount remanence); or a preview-render response posts data to `*` / accepts cross-origin messages without an origin allowlist, leaking rendered content to the embedding page; or it ships a `downloadable=false` object's bytes to the browser. | High | Three-axis authz (scope `filesystem_id` + intent `read`/`write`/`preview` + downloadable) re-derived broker-side from the host-attested session, never a client-supplied claim; `intent=preview` is read-only and non-downloadable, minting no egress artifact; `frame-ancestors` per-deployment allowlist closes the unauthorized-framing leg. | NFR-SEC-49 + SEC-73 + SEC-83; EU AI Act Art.10, DORA Art.28, NYDFS §500.15(a), CCM DSP-01/DSP-05 | Cross-`filesystem_id` read bounded by NFR-SEC-49 deny-by-default keyed on the authenticated caller, but per-action/per-object authz granularity is #187; postMessage target-origin pinning is an SPA impl property not yet pinned to a scenario. | PARTIAL |
+| P4-D3 | F11 data-plane client→broker (north face, inbound byte path) | D | A2 | Floods the UI/API face — cheap-to-trigger embed-token verify and pre-auth SPA routes before the session cookie exists, or oversized/streaming upload bodies and zip-bomb preview-render on ingest — consuming broker host memory shared with co-resident sessions (north-face analogue of the south-face P4-D1). | Med | North-side inbound body capped and rejected pre-buffer, on a file/UI ingress distinct from the MCP listener, with per-validated-caller file-ops/s + bytes/min limits; archive bodies validated before extraction (uncompressed-total/ratio/entry-count/traversal/symlink); content classified on ingest. | NFR-SEC-78 + SEC-80; EU AI Act Art.15(4), DORA Art.6/28, CCM IVS-06/09, NYDFS §500.7 | North-face byte/rate ceilings specified by NFR-SEC-78/80; the pre-auth verify-cost flood (work before the cookie is set, where per-validated-caller limits do not yet apply) and the per-caller connection ceiling fold into resource-exhaustion #188. | PARTIAL |
+| P4-R2 | P4 broker north face (file-activity attribution; via F10) | R | A2 | A north-face upload/download/delete/preview is later disputed because the actor identity behind the embed token, object handle, byte count, intent, and outcome were not durably recorded — or were recorded as the broker workload rather than the embed-asserted principal. | Med | Every file-activity event on either face emits an OCSF File System Activity event into the hash-chained pipeline, fail-closed (operation denied if the audit write fails), under host-attested identity; mandatory fields include actor identity, `filesystem_id`, operation, object handle, byte count, intent, downloadable disposition, and outcome. | NFR-SEC-79 + SEC-09; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 | North-face file-activity attribution specified by NFR-SEC-79 (fail-closed, enumerated fields); binding the OCSF `actor` to the embed-asserted principal rather than the broker workload identity is the open piece (#181). | PARTIAL |
+| P4-E3 | P4 broker north face (HTTP file/artifact API) | E | A2 | A client authorized for `preview` escalates to `download`/`write` or flips a `downloadable=false` object to egress-eligible by manipulating the intent verb or object tag in the API call (the API confused-deputy analogue of south-face P4-E1); or a crafted artifact id / filename (`../`, absolute path, URL-shaped id) drives the broker to resolve outside the session prefix or to dial an attacker-named backend. | High | Per-action authz — a `preview`-authorized caller cannot invoke `download`/`write`, the lease scopes to the action verb and exact prefix and fails at the backend not only at policy; `intent=preview` stays read-only and non-downloadable regardless of stored tag, minting no egress artifact; the broker rejects path-traversal/symlink pre-extraction and classifies content to defeat disguised-extension polyglots. | NFR-SEC-49 + SEC-73 + SEC-80; NIST 800-207 §2.1, DORA Art.28, NYDFS §500.15, CCM CEK-08/DSP-01 | Intent/downloadable enforcement specified by NFR-SEC-49 + SEC-73; per-action authz granularity is #187; SSRF-via-artifact-id path-confinement is a resolver impl property (resolver-bug tail, the same character as the P4-T1 residual), traversal-class caught by NFR-SEC-80 pre-extraction checks. | PARTIAL |
+| P5-I2 | P5 state at rest (snapshot/hibernation) | I | A3 | Snapshot/hibernation persists guest memory/disk holding a live Session JWT and mount handle at rest; an image read recovers a usable token before TTL expiry. | High | At-rest encryption (AES-256-GCM, cryptographic erasure) covers the volume but not a live token captured in a snapshot taken while the session holds it; no control invalidates the token on snapshot or excludes it from the image; short JWT TTL (≤60min) caps but does not eliminate the window. | NFR-SEC-44 + SEC-66; NYDFS §500.15(a), CCM CEK-08, EU AI Act Art.15 | Clean-before-stop + pre-freeze buffer zeroize specified by NFR-SEC-44/66 (M-3/#184). | PARTIAL |
+| P6-T1 | Edge→upstream (egress-wide-bump rung) | T | A3 | At the egress-wide-bump rung the edge holds plaintext between decrypt and re-encrypt; a compromised/misconfigured edge alters request/response bodies undetected, as the edge is the trusted re-signer. | Med | The bump rung is per-destination, customer-CA-rooted, TLS 1.3 both legs; the plaintext carve-out is a single auditable inspection point; edge-process integrity is a Compute/host-hardening property, not guest-reachable. | NFR-SEC-05 + SEC-33; NIST PEP §3.4.1, NYDFS §500.15, DORA Art.30, EU AI Act Art.14, CCM DSP-05 | Edge-process integrity (signed binary, attested config) is not asserted by a listed NFR; a compromised bump-rung edge has no in-band detection — needs edge-binary/config attestation ([#197](https://github.com/Wide-Moat/open-computer-use/issues/197)). | PARTIAL |
+| P6-I3 | Edge inspection point (bump-rung plaintext carve-out) | I | A3 | The decrypt/re-encrypt segment exposes plaintext of upstream traffic at the edge; a compromised edge or its memory/logs leak that plaintext. | Med | The bump rung is per-destination; the plaintext carve-out is a single named segment, customer-CA-rooted, TLS 1.3 both legs; the transparent pass-through rung never terminates TLS; the broker leg does not terminate, so the edge sees only ciphertext there. | NFR-SEC-05 + SEC-33; NYDFS §500.15, DORA Art.30, EU AI Act Art.14, CCM DSP-05 | Plaintext-at-rest in edge memory/swap has no zeroization NFR ([#197](https://github.com/Wide-Moat/open-computer-use/issues/197)). | PARTIAL |
+| P6-D3 | Trusted-time dependency of denylist propagation at edge | D | A3 | Clock rollback at the edge defeats denylist-propagation timing, so a revoked session keeps an injected credential alive past the revoke window. | Med | Denylist-propagation timing assumes a trustworthy clock; the denylist is checked directly on every injection (not purely time-driven), giving a non-clock revoke path. | NFR-SEC-48 + SEC-63; NIST PEP §3.4.1, NYDFS §500.5, DORA Art.30, EU AI Act Art.14, CCM IVS-09 | Monotonic-clock + resume-clock-correction specified by NFR-SEC-48/63 (#185). | PARTIAL |
+| P7-T2 | Audit pipeline (hash-chain / Merkle cadence) | T | A3 | Clock rollback / untrusted time backdates events, manipulates TTL-derived ordering, or stalls/forges the daily Merkle-head cadence so a tampered batch falls within a legitimate signing window. | High | Trusted-time source independent of any guest- or component-settable clock (monotonic chain-position sequence numbers alongside wall-clock; external trusted-time anchoring of the Merkle head via the transparency log's own timestamp). NFR-SEC-48 covers the trusted-time / anti-rollback control (with NFR-SEC-63 for resume). | NFR-SEC-48 + SEC-63; NYDFS §500.6/§500.13, DORA Art.10, EU AI Act Art.12/Art.19(1), CCM LOG-01/02 | Trusted-time anchor for the Merkle cadence specified by NFR-SEC-48/63 (#185). | PARTIAL |
+| P7-R3 | E2 operator · E4 SOAR (privileged-action attribution; via F2/F4) | R | A3+A2 | A privileged operator acts beyond tier-downgrade (credential-store access, retention-policy change, denylist edit) without a mandatory audit event, so the action is repudiable and the trail has a privileged-action gap. | High | Every privileged operator/SOAR action should emit a mandatory audit event into the hash-chained store under host-attested operator identity (PAM-JIT, no shared service accounts). Present canon mandates audit only for tier-downgrade. | NFR-SEC-45; NYDFS §500.6/§500.7, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 | Mandatory audit of privileged operator actions specified by NFR-SEC-45 (#186/M-2). | PARTIAL |
+| P7-T3 | D2 snapshot/hibernation of audit/session state at rest | T | A3 | A snapshot/hibernation image captured for the audit/forensic trail holds a live session token at rest; an adversary with image access replays the token to resume/impersonate a session and tampers with state outside the chain's view. | Med | At-rest encryption (AES-256-GCM) + cryptographic erasure on the image volume; session tokens excluded from snapshot scope. NFR-SEC-44 (clean-before-stop) + NFR-SEC-61 (artifact confidentiality) specify the exclusion of a live token from the image. | NFR-SEC-44 + SEC-61; NYDFS §500.6/§500.15, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 | Clean-before-stop + at-rest artifact encryption specified by NFR-SEC-44/61 (M-3/#184). | PARTIAL |
+
+## 4. Covered threats
+
+Threats whose control is complete (MITIGATED). The anchor NFR is the covering control; full detail lives in that NFR and in §3 for the live variants of the same element.
+
+| ID | Element/edge | STRIDE | Actor | Controlling NFR |
+|---|---|---|---|---|
+| P1-D2 | F5 gateway→Control API | D | A2 | NFR-COST-06 + PERF-01 + REL-01 + SEC-01; NYDFS §500.7, DORA Art.6, EU AI Act Art.14, CCM IAM-06 |
+| P1-E1 | P1→F5 toward Control API | E | A3+A2 | NFR-SEC-26 + §3 split; NYDFS §500.7, DORA Art.6, EU AI Act Art.14, CCM IAM-06 |
+| P2-S1 | P2 operator identity (F2/F3 terminate) | S | A3+A2 | NFR-COMP-29; NYDFS §500.7/§500.12, DORA Art.6/Art.28, EU AI Act Art.14, CCM IAM-06/08 |
+| P2-S2 | F5 gateway→Control API (terminates) | S | A2+A1 | NFR-SEC-09 + SEC-26 + §3 split; NYDFS §500.7, NIST 800-207 §2.1, CCM IAM-06 |
+| P2-T1 | F6 Control API→sandbox (P2 source) | T | A1 | NFR-SEC-43; NYDFS §500.7, DORA Art.6, NIST 800-207 §2.1, CCM IAM-06 |
+| P2-D2 | F3 IdP→Control API (terminates) | D | A2 | NFR-SEC-01 + REL-01; NYDFS §500.12, DORA Art.6, EU AI Act Art.14, CCM IAM-08 |
+| P2-E2 | F6 Control API→sandbox (host-attested) | E | A1 | NFR-SEC-43; NIST 800-207 §2.1, NYDFS §500.7, DORA Art.6, CCM IAM-06 |
+| P4-S1 | F7 broker→sandbox (mount, filesystem_id) | S | A1 | NFR-SEC-43 + SEC-25; NYDFS §500.15(a), DORA Art.28, EU AI Act Art.10, CCM CEK-08/DSP-01 |
+| P4-T2 | F9 broker→edge→backend | T | A2 | NFR-SEC-25 + SEC-85 + SEC-33; NYDFS §500.15(a), DORA Art.28, CCM CEK-08 |
+| P4-R1 | P4 broker (action attribution; via F10) | R | A1 | NFR-SEC-43 + SEC-03 + SEC-25; NYDFS §500.6, EU AI Act Art.12, CCM LOG-01/02 |
+| P5-E1 | P5 runtime → host kernel | E | A1+A3 | NFR-SEC-02 + SEC-14; EU AI Act Art.15(4), CCM IVS-06/09, NYDFS §500.7/§500.15 |
+| P5-S1 | F6 Control API→P5 (P5 adversarial view) | S | A1 | NFR-SEC-43; NYDFS §500.7, CCM IAM-06, EU AI Act Art.14 |
+| P5-S2 | F7 broker→P5 (P5 adversarial view) | S | A1 | NFR-SEC-43 + SEC-25; NYDFS §500.15(a), CCM CEK-08/DSP-01, EU AI Act Art.10 |
+| P5-T2 | P5 standing-secret harvest | T | A1 | NFR-SEC-23 + SEC-29 + SEC-25; NYDFS §500.15(a), CCM CEK-08, DORA Art.28 |
+| P6-S1 | P6 guest-facing listener on F8 | S | A1 | NFR-SEC-27 + SEC-43; NIST PEP §3.4.1, NYDFS §500.5, DORA Art.30, EU AI Act Art.14, CCM IVS-09 |
+| P6-S2 | Edge→upstream (egress-wide-bump rung) | S | A2 | NFR-SEC-05 + SEC-33; NIST implicit→untrusted, NYDFS §500.15, DORA Art.28, EU AI Act Art.15, CCM IVS-09 |
+| P6-T2 | F9 broker-signed leg through the storage lane | T | A3 | NFR-SEC-25 + SEC-85 + SEC-16; NIST custody-of-backend-cred, NYDFS §500.15, DORA Art.28, EU AI Act Art.10, CCM CEK-08/DSP-01 |
+| P7-R1 | D2 audit store (log) | R | A3 | NFR-SEC-03; NYDFS §500.6/§500.13, DORA Art.10, EU AI Act Art.12/Art.19(1), CCM LOG-01/02 |
+| P7-T1 | F10 {5 sources}→audit (fan-in transport) | T | A2 | NFR-SEC-33; NYDFS §500.6/§500.15, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 |
+| P7-I1 | F10 audit→customer sink (OCSF bridge, outbound) | I | A3 | NFR-SEC-33; NYDFS §500.15, DORA Art.10, EU AI Act Art.12, CCM LOG-04 |
+| P7-E2 | Audit pipeline (process) — elevation via collector | E | A1 | NFR-SEC-14; NYDFS §500.6, DORA Art.10, EU AI Act Art.12, CCM LOG-01/02 |
+
+## 5. Residual risks and accepted exposures
+
+No threat carries an uncovered control: every §3 row names a controlling NFR. This register groups the PARTIAL rows by theme so each residual reads "control specified, implementation tracked" rather than "uncovered". See [`diagrams/06-threat-model.mmd`](diagrams/06-threat-model.mmd).
+
+| Theme | Controlling NFR | §3 rows | Tracking |
+|---|---|---|---|
+| Snapshot/hibernation live secret at rest (M-3) | NFR-SEC-44 + 61/66 | P5-I2, P7-T3 | [#184](https://github.com/Wide-Moat/open-computer-use/issues/184) |
+| Guest-self-audit / out-of-band capture (M-4) | NFR-SEC-47 | P5-T1, P5-R1, P7-S1, P7-R2 | [#181](https://github.com/Wide-Moat/open-computer-use/issues/181) |
+| Trusted-time / clock-rollback | NFR-SEC-48 + 63 | P2-T2, P5-R1, P6-D3, P7-T2 | [#185](https://github.com/Wide-Moat/open-computer-use/issues/185) |
+| Privileged operator-action audit (M-2) | NFR-SEC-45 | P2-R1, P2-R2, P7-R3 | [#186](https://github.com/Wide-Moat/open-computer-use/issues/186) |
+| Resource-exhaustion containment | NFR-SEC-46 + 53 + 74 + 78 + 80 | P4-D1, P4-D2, P4-D3, P5-D1, P5-D2, P6-D1, P7-D1, P7-D2 | [#188](https://github.com/Wide-Moat/open-computer-use/issues/188), [#150](https://github.com/Wide-Moat/open-computer-use/issues/150) |
+| Content-blind transparent egress | NFR-SEC-57 | P5-I3, P6-I1 | [#182](https://github.com/Wide-Moat/open-computer-use/issues/182) |
+| Per-action authorization | NFR-SEC-49 | P1-E2, P4-T3, P4-I3, P4-E3 | [#187](https://github.com/Wide-Moat/open-computer-use/issues/187) |
+| mTLS / cert-pin / DPoP upstreams | NFR-SEC-50 | P6-E3 | [#176](https://github.com/Wide-Moat/open-computer-use/issues/176) |
+| Egress content-leak surface | NFR-SEC-51 | P1-I1 | [#149](https://github.com/Wide-Moat/open-computer-use/issues/149) |
+| Downloadable axis (read vs remove) | NFR-SEC-73 | P4-I2, P4-I3, P4-E3, P6-E2 | — |
+| North-face file-activity attribution | NFR-SEC-79 + 09 | P4-R2 | [#181](https://github.com/Wide-Moat/open-computer-use/issues/181) |
+| Embeddable-UI authentication (north face) | NFR-SEC-82 + 83 + 84 | P4-S3, P4-T3 | [#217](https://github.com/Wide-Moat/open-computer-use/issues/217) |
+| Preview-render parser isolation (north face) | NFR-SEC-81 + 83 | P4-I3, P4-E3 | [#218](https://github.com/Wide-Moat/open-computer-use/issues/218) |
+| Spawn-time secret leak | NFR-SEC-75 | P5-I4 | — |
+| Cross-tenant side-channel (accept-with-tier) | NFR-SEC-58 | P5-I1 | [#183](https://github.com/Wide-Moat/open-computer-use/issues/183) |
+
+## 6. Machine-checkable layer (tbd)
+
+Threagile threat-model-as-code (DFD-as-YAML, automated STRIDE re-run on DFD-bearing PRs) is deferred until its CI gate lands — [#194](https://github.com/Wide-Moat/open-computer-use/issues/194).
+
+## 7. Open questions
+
+1. Per-tool / per-action authorization and minimum credential scope (G1/G8) — [#187](https://github.com/Wide-Moat/open-computer-use/issues/187).
+2. Cross-tenant hardware side-channel: needs a measurable "tenant A cannot observe tenant B" target — [#183](https://github.com/Wide-Moat/open-computer-use/issues/183), [#148](https://github.com/Wide-Moat/open-computer-use/issues/148).
+3. Trusted-time / clock-rollback control for TTLs, denylist timing, and the hash-chain / Merkle cadence — [#185](https://github.com/Wide-Moat/open-computer-use/issues/185).
+4. Out-of-band evidence for in-sandbox actions and host-attested binding of the OCSF source field at ingestion (M-4) — [#181](https://github.com/Wide-Moat/open-computer-use/issues/181).
+5. LINDDUN privacy pass over the same DFD deferred to a follow-on model — [#195](https://github.com/Wide-Moat/open-computer-use/issues/195).

package/docs/architecture/08-contracts.md

@@ -0,0 +1,105 @@
+<!-- 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 every boundary that carries a wire contract, the format each uses, and whether OCU defines or conforms to it. Audience: engineers about to author a schema file or a component spec.
+
+## 1. Contract surfaces
+
+A contract at this layer is the typed, versioned shape that crosses a boundary — the methods, payloads, errors, and auth a caller may rely on. This overview owns the inventory, the format choice, and the policy; the per-surface schema files (§5) own the field-level types. Surfaces are the [internal boundaries](05-c4-container.md) (Layer 6 §4) plus the [external actors](03-c4-context.md) (Layer 4 §4); their token classes and zones live in those layers and are not restated here. [`diagrams/08-contracts.mmd`](diagrams/08-contracts.mmd) overlays the format on each crossing of the container diagram; the table below is the full surface list.
+
+OCU does not define every contract it speaks. Five external surfaces are integration contracts the platform consumes — naming a bespoke OCU format for them would contradict the [context map](04-bounded-contexts.md) (Layer 5 §4): MCP authorization (Conformist), OIDC (relying-party), PKCS#11/KMIP (relying-party), chained-proxy, and ICAP. The overview presents these as conform/relying-party, citing the public spec, not an OCU schema.
+
+| Surface | Boundary (canonical name) | Format | Role | NFR anchor |
+|---|---|---|---|---|
+| Agent tool-call ingress | Caller → MCP gateway | MCP JSON-Schema | conform | NFR-FLEX-14, NFR-IC-04 |
+| Operator REST | Operator → Control / operator API | OpenAPI 3.1 | define | — |
+| IdP assertion | Customer IdP → Control / operator API | OIDC | relying-party | NFR-COMP-29 |
+| SOAR revoke (inbound) | SOAR → Control / operator API | OpenAPI 3.1 | define | NFR-SEC-01 |
+| Session set-up RPC | MCP gateway → Control / operator API | Protobuf/gRPC | define | NFR-IC-04 |
+| Exec / PTY+CDP | Control / operator API → Session sandbox | WebSocket, single per session (tagged-JSON control + binary stream frames) | define | NFR-IC-03, NFR-SEC-43 |
+| File-operation mount | Storage broker → Session sandbox | file-operation interface — HTTP+JSON mount config (`filesystem_id`, broker-signed lease) over a FUSE/virtio-fs/9p substrate | define | NFR-SEC-25 |
+| File / artifact data plane (north face) | Data-plane client → Storage broker (north face) | OpenAPI 3.1 (HTTP+JSON: upload/list/download/getManifest/preview-render + embeddable SPA) | define | NFR-SEC-78, NFR-SEC-82, NFR-SEC-49, NFR-SEC-73 |
+| Secret delivery | SDS source → Egress trust-edge | Envoy SDS (gRPC xDS) | wire off-the-shelf; the dynamic per-SNI minter implementing the SDS server is OCU code ([ADR-0007](adr/0007-egress-auth-mechanism.md)), the file SDS source is off-the-shelf | NFR-SEC-29 |
+| Outbound | Session sandbox → Egress trust-edge | network policy (no wire schema) | network property | NFR-SEC-27 |
+| Broker backend leg | Storage broker → backend engine (network leg via the storage lane on the Egress trust-edge, ADR-0011) | external backend protocol (pluggable adapter, ADR-0010) | conform | NFR-SEC-16, NFR-SEC-25, NFR-SEC-85 |
+| Audit fan-in / SIEM | five containers → Audit pipeline → SIEM | AsyncAPI 3.0 / OCSF | publish | NFR-SEC-03 |
+| SOAR webhook (outbound) | Audit pipeline → SOAR | AsyncAPI 3.0 | define | NFR-COMP-27 |
+| Transparency-log submission | Audit pipeline → log | submission envelope | define (envelope only) | NFR-SEC-03 |
+| KMS / proxy / DLP | Egress trust-edge ↔ customer substrate | PKCS#11 · chained-proxy · ICAP | relying-party / conform | NFR-FLEX-04, NFR-COMP-28, NFR-FLEX-15 |
+
+Protobuf/gRPC is the unary session set-up leg only (create, route, destroy a session). The mount config is HTTP+JSON and the exec stream is a WebSocket. The file-op message-set substrate (Connect-RPC over HTTP/2) is a component-spec choice, not part of the contract. Egress secret delivery rides Envoy's native Secret Discovery Service (gRPC xDS); it is off-the-shelf and not an OCU-defined contract.
+
+The broker backend leg and the transparency log are mixed-ownership: OCU defines its half and conforms to the backend's API or the log operator's Merkle-head signing.
+
+The Storage broker has two faces on one client: the south mount (above) and the north file/artifact data plane, served on a dedicated file/UI ingress, not the MCP-tool-call listener (NFR-SEC-78). The transport substrate under each into-sandbox leg (TCP / UDS / vsock for the exec channel; FUSE / virtio-fs / 9p for the mount) is a deployment-overlay and component-spec choice, not a contract (NFR-SEC-26, NFR-SEC-25). What the contract fixes is channel direction, per channel: the control/exec channel is host-dialled — the host opens it and a non-host peer is rejected at accept (NFR-SEC-43); the outbound leg runs the opposite way, guest-out and intercepted at the edge under egress policy (NFR-SEC-27).
+
+## 2. Format choice
+
+Five formats cover every surface OCU defines; the choice follows the boundary shape, not preference.
+
+- **MCP JSON-Schema (over JSON-RPC 2.0)** — the agent tool surface. The protocol fixes the format; OCU does not choose it. Tool definitions carry JSON Schema; an embedded schema defaults to JSON Schema 2020-12 and may declare another dialect with `$schema`, so the validator honours the declared dialect and falls back to 2020-12 ([MCP spec 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)).
+- **OpenAPI 3.1** — inbound human/operator and third-party REST (operator API, SOAR revoke) and the north-face file/artifact data plane (upload/list/download/getManifest/preview-render), an HTTP+JSON surface served on a dedicated ingress. SDK-generatable; its schemas are JSON Schema 2020-12 ([3.1 alignment](https://learn.openapis.org/upgrading/v3.0-to-v3.1.html)), the same dialect MCP defaults to, so inbound validation reads one dialect across both surfaces.
+- **Protobuf/gRPC** — unary internal RPC between OCU containers, where both ends version together: session set-up. Field-number rules plus `buf breaking` give machine-checked compatibility with no public-SDK obligation. Internal-only by policy. Egress secret delivery is Envoy SDS (gRPC xDS) between Envoy and the SDS source: the wire is off-the-shelf and not an OCU RPC surface, but the dynamic per-SNI minter that implements the SDS server for a non-enumerable allow-list is self-hosted OCU code ([ADR-0007](adr/0007-egress-auth-mechanism.md)); the file SDS source needs none.
+- **WebSocket** — the bidirectional exec/PTY+CDP surface, one socket per session. A PTY carries interleaved stdin/stdout/stderr bytes plus in-band resize and signal control, so the frame is tagged-JSON control alongside raw binary stream frames, not a unary call (NFR-IC-03). gRPC fits request/response, not a live byte stream, which is why this surface is WebSocket and the set-up RPC is not.
+- **AsyncAPI 3.0** — one-directional decoupled event fan-in to the Audit pipeline and fan-out to SIEM. Payload is the OCSF Published Language; AsyncAPI names the channel, OCSF types the event ([AsyncAPI 3.0](https://www.asyncapi.com/docs/concepts/asyncapi-document/define-payload)).
+
+## 3. Contract-enforced mitigations
+
+Every OCU-defined contract carries the Layer 7 mitigations as machine-checked constraints. The overview states the property and where it is enforced; the schema states the constraint values. Threats are anchored in [the threat model](06-threat-model.md) (Layer 7) and not restated.
+
+| Mitigation | Property the contract must carry | NFR |
+|---|---|---|
+| Audience-validated authz | reject any token not naming this surface in its audience ([trust-boundaries §3](02-trust-boundaries.md)); no token passthrough to upstream — the edge injects the SDS-delivered credential (NFR-SEC-23, NFR-SEC-27) | NFR-SEC-09 |
+| Bounded error verbosity | caller gets a stable reason code; `error.message`/`error.data` leak no internal topology or stack | NFR-SEC-51 |
+| Structured deny | deny is a machine-parseable object using the `x-deny-reason` vocabulary | NFR-SEC-17 |
+| Schema validation | every payload validates against the published schema; reject on violation | NFR-SEC-51 |
+| Bounded payload | gateway/REST/gRPC bound body size, array length, and object depth at the closed schema; the broker and exec transport cap max-message/max-object | NFR-SEC-51, NFR-SEC-46 |
+| Bounded north-face inbound body | reject a body above the configured ceiling (default ≤50 MiB) pre-buffer, never partially staged; per-validated-caller op/byte rate limits on a dedicated file/UI ingress | NFR-SEC-78 |
+| Archive validation | reject pre-extraction on uncompressed-total / entry-count / traversal / symlink ceilings | NFR-SEC-80 |
+| Content classification | resolve content type on ingest (magic-byte + declared media type), record before mount-visibility; pre-stage deny on a policy-denied type | NFR-SEC-81 |
+| Embed-token verify | reject any embed token not signature-valid, not naming this surface in audience, or past `exp` (`exp ≤ 120 s`); no OCU upstream secret crosses to the browser | NFR-SEC-82 |
+| Frame-ancestors allowlist | every UI/artifact response carries `CSP: frame-ancestors` from the per-deployment allowlist (header-only, default `'none'`) | NFR-SEC-83 |
+| First-party session + CSRF | a state-mutating request requires a server-validated CSRF token; a missing/invalid session is 401 with no anonymous fallback | NFR-SEC-84 |
+| File-activity audit (north) | every upload/list/download/delete emits an OCSF File System Activity event into the hash-chained pipeline, gateway-authored, fail-closed | NFR-SEC-79 |
+| Three-axis authz | resolve scope (`filesystem_id`) + intent (`read`/`write`/`preview`) + `downloadable` broker-side from the host-attested session, never a client-supplied claim; `intent=preview` is read-only and non-downloadable | NFR-SEC-49 |
+| Downloadable axis at read | the broker resolves `downloadable` at read on both faces; a non-downloadable object yields no egress-eligible artifact (preview ≠ remove-from-sandbox) | NFR-SEC-73 |
+
+The MCP edge carries the same five through a two-tier error model: a protocol error (`JSON-RPC error{code,message}`) never reaches the model and carries a reason code only; a tool-execution error (`result.isError: true` + content) reaches the model with sanitized output. Both are bounded by NFR-SEC-51.
+
+## 4. Versioning & compatibility
+
+Contracts evolve additively. Adding an endpoint, an optional field, a new event type, or a proto field with a fresh field number is non-breaking and ships without a version bump; consumers ignore unknown fields. Removing or renaming a field, tightening a type, changing an error envelope, or repurposing a proto field number is breaking and requires a new **major** version that does not depend on the prior one; the two coexist for the published transition window. Deprecation precedes removal — ship the replacement, migrate clients, then remove. REST deprecation uses the `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html)) and `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)) response headers. Breaking-change detection is CI-enforced — `oasdiff` for OpenAPI, `buf breaking` for Protobuf.
+
+The control-plane RPC rule (breaking = major version + deprecation header) is canonical in NFR-IC-04 and governs OCU's own Control/operator API and internal gRPC. The MCP gateway is a Conformist to the MCP wire contract and does not carry semver: its revision is a date string (`protocolVersion: "2025-06-18"`) negotiated on `initialize` and echoed on every HTTP request via `MCP-Protocol-Version`. A revision the peer cannot negotiate is the breaking signal — the server returns an alternate version it supports and a client that cannot accept it disconnects ([MCP lifecycle](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle)); the spec's example initialization error is `-32602` "Unsupported protocol version". This negotiation path, not an HTTP `Deprecation` header, is the deprecation mechanism NFR-IC-04 describes for that edge. Concurrency is sequential-default per session with opt-in parallelism (NFR-IC-05); PTY and CDP multiplex one WebSocket per session (NFR-IC-03).
+
+## 5. Schema artifacts
+
+This overview is the map; the schema files under `contracts/` own the field-level types. Six schema files are drafted (the storage surface carries three — mount config, south-face file-op RPC, north-face file/artifact API); the rest are not yet built. [`contracts/README.md`](../../contracts/README.md) is the navigator: how to read a schema file and what the `x-ocu-*` annotations mean.
+
+Drafted (not merged):
+
+- `contracts/mcp/2025-06-18/ocu-constraints.schema.json` — the MCP conform profile.
+- `contracts/exec/exec-channel.schema.json` — the exec/PTY WebSocket envelope.
+- `contracts/storage/mount-config.schema.json` and `contracts/storage/file-ops.schema.json` — the south-face mount config and file-op RPC (the file-op message bodies are tbd).
+- `contracts/storage/file-artifact-api.schema.json` — the north-face file/artifact data plane (upload/list/download/getManifest/preview-render + the embed-token/CSP/CSRF envelope). Per-operation bodies are tbd, like the south face; the embed-token binding claim ([#217](https://github.com/Wide-Moat/open-computer-use/issues/217)) and preview-render parser isolation ([#218](https://github.com/Wide-Moat/open-computer-use/issues/218)) are tracked open items.
+- `contracts/audit/audit-fanin.asyncapi.yaml` — the OCSF fan-in (the compute-metering and saturation payloads are tbd, [#150](https://github.com/Wide-Moat/open-computer-use/issues/150)).
+
+Not built:
+
+- `contracts/openapi/` (operator REST + SOAR revoke) and `contracts/proto/` (session set-up) — [#205](https://github.com/Wide-Moat/open-computer-use/issues/205). Egress secret delivery is off-the-shelf Envoy SDS, not an OCU contract file.
+- The transparency-log submission envelope — [#151](https://github.com/Wide-Moat/open-computer-use/issues/151).
+- Mock / conformance servers per surface for consumer CI — [#206](https://github.com/Wide-Moat/open-computer-use/issues/206).
+- The `SkillProvider` contract is a v1 non-goal; skills load from a customer-provided registry, so no skill-format schema ships in v1.
+
+## 6. Open questions
+
+1. Does NFR-IC-04 bind only the Control/operator API and internal gRPC, leaving the MCP gateway 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. Is the inbound gateway contract MCP-only per NFR-FLEX-14, and is `REST fallback` (used in Layer 4 prose, undefined in glossary) dropped or promoted to a defined surface? — [#158](https://github.com/Wide-Moat/open-computer-use/issues/158).
+3. The §4 additive-vs-breaking rules, transition window, RFC 9745/8594 headers, and the `oasdiff`/`buf breaking` CI gates extend NFR-IC-04 across two surfaces — should this versioning policy move to a dedicated ADR, leaving §4 a pointer? — [#209](https://github.com/Wide-Moat/open-computer-use/issues/209).

package/docs/architecture/MANIFESTO.md

@@ -0,0 +1,38 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-02
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+The Architecture Manifesto for open-computer-use `next/v1`. This file is the read-first artifact for every architectural decision in this repository.
+
+## Status
+
+Draft. Sections appear one at a time via PRs on `next/v1`. Each section is reviewed before the next is opened. No bulk-generation.
+
+## Sections
+
+The expanded sections live under [`manifesto/`](./manifesto/); this file stays the ≤ 400-line read-first map.
+
+| # | Section | File | Status |
+|---|---|---|---|
+| 1–2 | Purpose, audience & buyer's checklist | [`01-audience-and-buyer.md`](./manifesto/01-audience-and-buyer.md) | draft |
+| — | NFRs / quality goals | [`02-nfrs.md`](./manifesto/02-nfrs.md) | draft |
+| 3 | Non-negotiables (with anti-examples) | [`03-non-negotiables.md`](./manifesto/03-non-negotiables.md) | draft |
+| 4 | Non-goals (v1) | [`04-non-goals.md`](./manifesto/04-non-goals.md) | draft |
+| 5 | Licensing posture (FSL-1.1-Apache-2.0 + dependency policy) | [`05-licensing-posture.md`](./manifesto/05-licensing-posture.md) | draft |
+| 6 | Starter-mode policy | [`06-starter-mode-policy.md`](./manifesto/06-starter-mode-policy.md) | draft |
+| 7 | Governance & decision-recording protocol | [`07-governance.md`](./manifesto/07-governance.md) | draft |
+
+The NFR catalogue carries no MANIFESTO section number — it is the measurable-quality layer the numbered sections reference, kept in `02-nfrs.md`.
+
+## Hard rules already locked
+
+- License is **FSL-1.1-Apache-2.0** with 2-year automatic Apache-2.0 conversion. See `LICENSE` and `NOTICE`.
+- Documentation discipline, decision tree, diagram rules, dependency policy, and testing/QA discipline are codified in the project's `CLAUDE.md` (loaded by the AI assistant on every session). They apply to this directory.
+
+See [`README.md`](./README.md) for the directory layout and [`PROCESS.md`](./PROCESS.md) for how to add a section.

package/docs/architecture/PROCESS.md

@@ -0,0 +1,64 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-05-30
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+How to add new architectural content. Pacing rule: discuss → stub → draft → revise → commit. One artifact per PR. No bulk-generation.
+
+## Adding a component (4 steps)
+
+1. Open an issue titled `Component proposal: <name>`. State the component's purpose, its boundaries (inputs/outputs/owned state), and why it exists now (not later).
+2. On a feature branch, create `components/<NN>-<name>.md` from the component-spec template (front-matter + `## Purpose` line, nothing more).
+3. Open a PR against `next/v1`. Discuss. Don't add content beyond the stub until the boundaries are agreed.
+4. **Inherit Layer 0 gates.** Remove this component's path from `.semgrepignore` (and any other gate-exclusion file) in the same PR that introduces source code for the component. CI must pass without the legacy exclusion. New code is never excluded — the exclusion list shrinks monotonically. Policy: [ADR-0001](adr/0001-layer-0-gate-legacy-exclusion.md).
+
+## Adding an ADR (3 steps)
+
+1. Open an issue titled `Decision: <title>`. State the question, constraints, and at least two candidate options.
+2. On a feature branch, create `adr/<NNNN>-<slug>.md` from `adr/0000-template.md` with `status: proposed`.
+3. Open a PR against `next/v1`. The ADR moves to `status: accepted` only after the PR merges.
+
+ADRs are reserved for decisions that are load-bearing, hard to reverse, or cross at least two components. If a decision doesn't meet that bar, write it inline in the component spec.
+
+## Adding an NFR / non-negotiable
+
+1. Open an issue titled `Principle proposal: <title>`.
+2. Add a single line to `MANIFESTO.md` §03 (non-negotiables) or a sub-section in `manifesto/02-nfrs.md` with a measurable target.
+3. State the anti-example explicitly. If you can't name the anti-example, the rule is not yet ready.
+
+## Adding a dependency (Bill of Materials)
+
+1. Open an issue titled `Dependency proposal: <component> = <pick>`.
+2. Add a row to the BoM table in `manifesto/05-licensing-posture.md`: name, license, bundled/not-bundled, version pin policy, supply-chain attestation (SBOM / signed / reproducible).
+3. Reject if any of the following holds: AGPL (any flavour, except as a separate process with stable API and explicit note), BSL, BUSL (other than past versions of our own code), SSPL, CC-NC, commercial-only-source, sole-maintainer npm/PyPI package with no provenance.
+
+Heavier and vendor-backed beats lighter and unknown. The platform targets regulated enterprises; "lightweight but undocumented" loses every InfoSec review.
+
+## Marking content as TBD
+
+- If the answer isn't known yet, write `status: tbd` in the front-matter, a one-line context, and a link to the tracking issue. Don't invent.
+- TBD is a first-class state. Reviewers must not push to remove TBDs prematurely.
+- Skill registry is the canonical example: v1 ships zero default skills bundled; the `SkillProvider` abstraction stays TBD until the contract proves itself.
+
+## Capturing primitives discovered during research
+
+When a research, advisor, or verifier cycle surfaces an architectural primitive that OCU will need (e.g. evidence-as-code bundle, egress allow-list, DORA RoI field-level traceability, kill-switch SLA, replay-bundle schema), append it to `primitives-backlog.md` immediately. Do not stash primitives in research-buffer files only — they get lost on the next research cycle.
+
+Each entry is one line: `- **<primitive name>** — <one-line purpose> — surfaced in <research-file>; lands in <target-section-or-component>`. Target may be `§02` (NFRs), `§03` (non-negotiables), a component spec, or `TBD` if not yet placed.
+
+The backlog drains in two directions: each entry either resolves into a concrete NFR / principle / spec section (delete from backlog when it lands), or becomes a tracked GitHub issue when scope grows beyond a single line.
+
+## Adding a new file kind to the tree
+
+Every file under `docs/architecture/` must match an entry in the whitelist at `scripts/docs-lint/architecture-tree-whitelist.sh`. The whitelist exists so that scratch notes, verifier snapshots, screenshots, and AI artifacts cannot drift into the architecture set. CI blocks merge if an unexpected file lands.
+
+When a PR legitimately needs a new file kind (e.g. introducing the `contracts/` directory or a new compliance template), update `ALLOWED` in `architecture-tree-whitelist.sh` in the same PR. Reviewers check that the added pattern is as tight as possible: `compliance/*-mapping.md`, not `compliance/*`.
+
+## Scope boundary
+
+This file is the how-to for adding artifacts. Adjacent concerns live elsewhere: roadmaps are out of scope; the inventory of which artifacts exist is `README.md`; the rules for writing the content are in `CLAUDE.md` under `## Documentation discipline` and `## Architecture content routing`.

package/docs/architecture/README.md

@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: stub
+last-reviewed: 2026-05-28
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+This directory will hold the canonical enterprise solution architecture for `next/v1`. Read [`MANIFESTO.md`](./MANIFESTO.md) before anything else.
+
+## Files in this directory
+
+| File | Status | Purpose |
+|---|---|---|
+| [`MANIFESTO.md`](./MANIFESTO.md) | stub | Non-negotiables, NFRs by reference, governance. Read first. |
+| [`glossary.md`](./glossary.md) | stub | Canonical terms (tenant, sandbox, session, agent, runtime, …). |
+| [`PROCESS.md`](./PROCESS.md) | draft | 3-step playbooks for adding a component, ADR, NFR, dependency, or TBD. |
+| `manifesto/` | partial | Expanded Manifesto sections — appear one at a time via PRs. Currently `01-audience-and-buyer.md`, `02-nfrs.md`. |
+| `components/` | partial | Per-component design contracts — appear one at a time. Currently `0000-template.md` only. |
+| `adr/` | partial | Contains `README.md` (index) and `0000-template.md`. ADRs appear on demand. |
+| `diagrams/` | empty | Mermaid / D2 source files. |
+| `compliance/` | empty | Per-framework mappings (SOC 2, ISO 27001, DORA, EU AI Act, GDPR, SR 11-7, HIPAA, PCI-DSS). |
+
+## Not yet present
+
+The tree grows one artifact per PR, after discussion. See [`PROCESS.md`](./PROCESS.md).
+
+The in-progress materials at [`docs/future-architecture/`](../future-architecture/) remain a working buffer until coverage here reaches 100%; at that point a `SUPERSEDED.md` marker points back here and that directory becomes legacy.
+
+## Reading order
+
+1. [`MANIFESTO.md`](./MANIFESTO.md) — what the project is and what's non-negotiable.
+2. [`glossary.md`](./glossary.md) — vocabulary.
+3. [`PROCESS.md`](./PROCESS.md) — how to add new content.
+4. Specific ADRs and component specs as needed (none yet — `adr/` and `components/` will populate per `PROCESS.md`).

package/docs/architecture/adr/0000-template.md

@@ -0,0 +1,65 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: YYYY-MM-DD
+owner: "@github-handle"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: []
+license-impact: none
+threat-mitigation-link: null
+---
+
+Template for an Architecture Decision Record, used by `next/v1` engineers to capture decisions that are load-bearing, hard to reverse, or cross at least two components.
+
+# ADR-NNNN: <title>
+
+## Status
+
+`proposed` | `accepted` | `superseded` | `deprecated`
+
+Mirror the value in front-matter. On lifecycle change, update both this section and the front-matter `status` / `superseded-by` fields.
+
+## Context
+
+What forces drive this decision? What constraints are in play (NFRs, threat-model entries, prior ADRs, regulatory requirements)? One short paragraph. State the *problem*, not the solution.
+
+## Decision
+
+We will <verb> <object>, because <one-line rationale>.
+
+Present tense. One sentence ideal, one paragraph max.
+
+## Consequences
+
+What changes as a result? Positive and negative. Cite the components affected by name.
+
+- Positive: …
+- Negative: …
+- Neutral: …
+
+## Alternatives considered
+
+At least two. For each: what it is, why we rejected it. Single-sentence per alternative is fine; this is not an essay.
+
+- **<alternative A>** — rejected because …
+- **<alternative B>** — rejected because …
+
+## Compliance impact
+
+Which framework controls does this decision satisfy or affect? Reference by control ID (e.g. `SOC2-CC6.1`, `ISO27001-A.8.2`, `EU-AI-Act-Art.12`). Empty if none.
+
+## License impact
+
+Does this introduce a dependency or pattern that affects our FSL-1.1-Apache-2.0 distribution? Empty if none.
+
+## Threat mitigation
+
+Link to the threat-model entry this decision mitigates, if any. Empty if not threat-driven.
+
+---
+
+Hard cap: 200 lines. If the decision doesn't fit, split it.