@mseep/open-computer-use 1.0.0

package/docs/architecture/adr/0001-layer-0-gate-legacy-exclusion.md

@@ -0,0 +1,75 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: accepted
+last-reviewed: 2026-05-24
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: []
+license-impact: none
+threat-mitigation-link: null
+---
+
+The Layer 0 CI gates run against every PR on `next/v1`, but `main`-line legacy code on this branch fails them. This ADR records how we keep the gates on without rewriting code that v1 GA does not ship.
+
+# ADR-0001: Layer 0 gate legacy exclusion policy
+
+## Status
+
+`accepted`
+
+## Context
+
+`next/v1` was branched from `main` to carry the existing PoC (sandbox `Dockerfile`, `computer-use-server/` FastAPI, `openwebui/`, `settings-wrapper/`, `cron/`, bundled skills) so the branch stays runnable while the enterprise architecture is designed. The Layer 0 SAST gate (`p/security-audit`, `p/owasp-top-ten`, `p/python`, `p/javascript`, `p/dockerfile`, `p/github-actions`) found 37 blocking issues in that legacy code on its first run: root containers, wildcard CORS, md5 hash use, stdlib XML parsing, dynamic urllib, etc.
+
+None of that code ships in v1 GA. Every legacy area is replaced from scratch by a new component under `docs/architecture/components/` in Layer 6+ (Sandbox Runtime, Control Plane, Audit Pipeline, Egress Proxy, …). Rewriting the legacy now means polishing code we are about to delete.
+
+The gate itself is correct and must remain blocking. The question is which paths it covers.
+
+## Decision
+
+The Layer 0 SAST gate runs against every path in the repository except those listed in `.semgrepignore`. That file enumerates the `main`-line legacy paths slated for replacement, with a header that names the responsible new-architecture component for each entry. Every new-architecture PR that introduces a component covering one of those areas removes the corresponding `.semgrepignore` line in the same commit. CI must pass without the exclusion before the PR can merge.
+
+## Consequences
+
+- Positive: Layer 0 gates stay green on `next/v1` HEAD; the verifier's "CI green" criterion is satisfied without dead-code refactoring.
+- Positive: every new component inherits the full SAST gate by default. The exclusion list shrinks monotonically — additions require this ADR's amendment.
+- Positive: the legacy debt is auditable in one file rather than scattered across `# nosemgrep` comments.
+- Negative: a legacy finding could mask a related issue in new code that imports the legacy path. Mitigated by the rule that new components never import legacy modules (enforced by component-boundary review).
+- Negative: `.semgrepignore` is a coarse tool — excluding `computer-use-server/` excludes every rule, not just the failing ones. Acceptable because the directory dies in Layer 6+.
+
+## Alternatives considered
+
+- **Baseline cleanup PR.** Fix the 37 findings in legacy code before continuing. Rejected: the code is scheduled for full rewrite in Layer 6+ per the architecture plan; fixing it now spends review time on artifacts we throw away.
+- **Per-rule exception file** (`.semgrep-exceptions.yaml` with finding hashes). Rejected: gives the illusion of per-finding scrutiny while in practice rubber-stamping every legacy hit. The directory-level exclusion is more honest about what we are doing.
+- **Lower the gate to `WARN`.** Rejected: removes the gate for new code too. The whole point of Layer 0 is that new components must pass on creation.
+- **Delete the legacy code from `next/v1` now.** Rejected: the branch must stay runnable for early-stage demos and contract-shape experiments until Layer 6+ components land.
+
+## Compliance impact
+
+None for now. When the first compliance-mapping ADR lands (Layer 12), this exclusion list is referenced as the scope-boundary statement: SOC 2 / ISO 27001 controls apply to non-excluded paths.
+
+## License impact
+
+None.
+
+## Threat mitigation
+
+None directly. The legacy code's threats (root containers, XXE, SSRF via `urllib`) are addressed by replacement, not by SAST suppression. The new-component-must-remove-its-path rule keeps that promise auditable.
+
+## Amendments
+
+Each amendment names the discovery commit and the affected exclusion entries.
+
+### 2026-05-24 — initial exclusion-list completion
+
+The first version of `.semgrepignore` shipped in commit `709db53` missed three legacy areas that the SAST gate scans:
+
+- `.github/workflows/release-chart.yml` — `main`-line Helm release workflow with a pre-existing `run-shell-injection` finding on the `gh release create` step. Replaced when the supply-chain.yml pattern is extended to chart artifacts in Layer 6+.
+- `skills/examples/` — bundled skill examples carrying the same `defusedxml` gaps as `skills/public/`. v1 GA ships zero skills per `manifesto/04-non-goals.md`; both directories die together.
+- `tests/` — top-level PoC test tree using stdlib `xml.etree`. New components ship their own tests under each component's directory; this tree dies with the code it tests.
+
+Discovered by the third verifier pass on commit `709db53`. The amendment adds them under the same policy with no change to the decision or alternatives.

package/docs/architecture/adr/0002-session-view-descriptor.md

@@ -0,0 +1,57 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-01
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [EU-AI-Act-Art.12, SOC2-CC6.1]
+license-impact: none
+threat-mitigation-link: 06-threat-model.md
+---
+
+Fixes how OCU's data-plane UI discovers its views, so adding the deferred live-session views (browser, terminal) is additive, not a breaking change.
+
+# ADR-0002: Session view is descriptor-driven
+
+## Status
+
+`proposed`
+
+## Context
+
+The PoC ships a working preview panel with three tabs — files, a live browser (CDP screencast), and a live terminal (ttyd). v1 ships only the files tab; the two live-session tabs are deferred to [#210](https://github.com/Wide-Moat/open-computer-use/issues/210) pending a security pass on the human channel into the guest. The two later tabs read from a different source than files (ephemeral CDP/PTY streams off the Session sandbox host edge, not the durable object store behind the Storage broker), authenticate separately, and have their own lifecycle. The risk: if the UI hardcodes its tab set or folds all three behind one file API and one credential, adding the live-session tabs later breaks the embedding contract and collapses two trust domains into one.
+
+## Decision
+
+We will have the data-plane UI discover its available surfaces at runtime from a session-scoped descriptor list, rendering one tab per descriptor and ignoring kinds it does not recognize, because this makes the file tab and the later live-session tabs additive entries in one list rather than a hardcoded set. The discovery endpoint lands as an addition to the north-face contract inventory ([`08-contracts.md`](../08-contracts.md) §1) in the same change set that ships it.
+
+## Consequences
+
+- Positive: v1 returns one descriptor (`files`); the endpoint returns three once [#210](https://github.com/Wide-Moat/open-computer-use/issues/210) lands. Adding the browser and terminal tabs is appending two descriptors; an old shell renders the subset it recognizes and never errors on a new kind.
+- Positive: the files surface is served by the **Storage broker** north face as a component inside that container ([`05-c4-container.md`](../05-c4-container.md) §3); the shell that renders the descriptor list is a thin data-plane-UI component over per-surface sources, not owned by any one container — the deferred live-view tabs read off the **Session sandbox** host edge, a different container.
+- Positive: each surface authenticates to its own source with its own token — the files tab uses the embed-token → first-party-session path ([NFR-SEC-82](../manifesto/02-nfrs.md), [NFR-SEC-84](../manifesto/02-nfrs.md)); a future live-view tab gets a separate session-scoped token. The shell carries and forwards no credential, closing the PoC's single-`chat_id`-gates-everything weakness.
+- Positive: the descriptor's `entry.url` is host-side only — a structural invariant (schema + property test) that forbids a guest container IP/port, enforcing host-dials-guest ([NFR-SEC-43](../manifesto/02-nfrs.md)) before any live-view kind exists.
+- Negative: a capability-discovery endpoint plus a versioned descriptor schema is more than a single hardcoded tab needs today; mitigated by shipping the minimum (a length-1 list, open `kind` enum, `transport` discriminator, `contract_ref`) and deferring the host↔surface message protocol until a sandboxed surface needs it.
+- Neutral: the descriptor is one cross-surface contract; each surface keeps its own per-surface contract (the file-artifact data plane stays `file-artifact-api.schema.json`), not absorbed into a mega-API.
+
+## Alternatives considered
+
+- **Hardcoded tab set in the UI** — rejected because adding the browser/terminal tabs would change the shell and break any embedder pinned to the v1 tab set; offers no forward-compatibility seam.
+- **One mega data-plane API with capability flags** (`/dataplane` toggling files/browser/terminal under one credential) — rejected because it folds the durable file-artifact data plane and the ephemeral live-view plane behind one credential and one lifecycle, collapsing two trust domains (NFR-SEC-25) and re-creating the PoC exfil surface.
+- **Customer builds its own UI over our APIs, OCU ships no SPA** — rejected for v1 because OCU's authenticated file-preview SPA is in-scope per `03-c4-context.md` §4; kept available as a path (the descriptor + per-surface contracts are public), but not the default.
+
+## Compliance impact
+
+`EU-AI-Act-Art.12` (per-surface audit of file activity, NFR-SEC-79), `SOC2-CC6.1` (per-surface authentication, no panel-wide credential).
+
+## License impact
+
+None.
+
+## Threat mitigation
+
+Structurally bars a guest-reachable `entry.url` ([NFR-SEC-43](../manifesto/02-nfrs.md)) and keeps per-surface authentication, closing the PoC's single-`chat_id` and direct-guest-reachability weaknesses; the north-face F11 rows P4-S3/T3/I3 in [`06-threat-model.md`](../06-threat-model.md) §3.2 cover the embed-token and single-credential vectors. Live-view STRIDE rows land with [#210](https://github.com/Wide-Moat/open-computer-use/issues/210).

package/docs/architecture/adr/0003-sandbox-runtime-tier-ladder.md

@@ -0,0 +1,63 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-01
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [EU-AI-Act-Art.15, DORA-Art.28, NIST-SP-800-190]
+license-impact: none
+threat-mitigation-link: ../02-trust-boundaries.md#4-per-tenant-isolation-menu
+---
+
+Fixes the axis that selects the sandbox runtime tier, and which tiers v1 GA ships. Audience: anyone touching the Session sandbox substrate or its admission rules.
+
+# ADR-0003: Sandbox runtime tier ladder
+
+## Status
+
+`proposed`
+
+## Context
+
+The Session sandbox ([component 05](../components/05-session-sandbox.md)) runs agent-issued actions inside an isolation boundary. The strength of that boundary — bare namespaces, a user-space kernel, or hardware virtualization — sets escape resistance, host footprint, and whether a deployment runs from a single `docker-compose up`.
+
+Two axes compete to drive the choice: data classification (stronger tier for more sensitive data) versus workload trust (the tier follows who supplies the prompts the agent executes). §02 and AP-13 already record the split — data classification governs retention, custody, and residency; workload trust governs the tier. The remaining question is the product-level one this ADR closes: which tiers v1 GA ships and which it defers.
+
+The one-click solo install is an NFR-shaping invariant: the default deployment runs single-operator, no IdP, no KVM, and must not pay for a regulated enterprise's isolation or audit machinery to start.
+
+## Decision
+
+The sandbox runtime tier is selected by the deployment-wide workload-trust profile — `runc` for `trusted_operator`, gVisor/`runsc` for `internal_workforce`, with microVM as the `untrusted` tier deferred post-v1 — and never by data classification (AP-13).
+
+## Consequences
+
+- v1 GA bundles two runtimes and ships three deployable cells; the profile/tier matrix, allowed pairings, and rejected cells live in NFR-SEC-38, enforced at deploy time by the Control / operator API ([component 02](../components/02-control-operator-api.md)). This ADR does not restate them.
+- The `trusted_operator` × `runc` cell preserves the one-click solo install — no KVM, no IdP, zero-config. gVisor is the hardened default for `internal_workforce`.
+- Enterprise audit machinery stays opt-in for the solo default: the local audit-event emit is mandatory in code for every tier (NFR-SEC-45, fail-closed), but the external sinks and alarms that consume it — SIEM-bridge, SOAR webhook, the NFR-SEC-39 tier-downgrade alarm — are off when no such sink is configured. A solo operator reconfiguring their own tier raises a local event and nothing external fires.
+- Per-tier escape resistance and the per-release red-team gate stay governed by NFR-SEC-02; the tier-downgrade alarm by NFR-SEC-39, emitted as `config.trust_profile.downgraded` through the Audit pipeline ([component 07](../components/07-audit-pipeline.md)). This ADR adds no requirement to either.
+- The Session sandbox records this ADR in its `adr:` front-matter; its host-side exec-supervisor and runtime-supervisor model is unchanged, so the tier choice forces no Layer-6 container split.
+- microVM packaging (Firecracker vs Kata, [#161](https://github.com/Wide-Moat/open-computer-use/issues/161)), per-session trust profile ([#162](https://github.com/Wide-Moat/open-computer-use/issues/162)), and the sandbox sub-split ([#174](https://github.com/Wide-Moat/open-computer-use/issues/174)) are downstream seams this ADR names but does not design.
+
+## Alternatives considered
+
+- **microVM-default (E2B-style)** — hardware virtualization for every deployment. Rejected because it requires KVM on the `trusted_operator` path that needs no hardware boundary, breaking the one-click solo invariant.
+- **gVisor-only floor** — drop `runc`, run `runsc` everywhere. Rejected because it removes zero-config `runc` from the `trusted_operator` path and pays user-space-kernel overhead where the workload-trust profile does not call for it.
+- **Tier by data classification** — pick the tier from the data the agent touches. Rejected by AP-13: the container-escape surface for adversarial agent-issued code is identical regardless of data class.
+
+## Compliance impact
+
+- `EU-AI-Act-Art.15` (4)/(5): the tier ladder is the agent-execution boundary's cybersecurity measure under the Article's accuracy-and-cybersecurity requirement for high-risk systems; per-tier red-team evidence lands via NFR-SEC-02.
+- `DORA-Art.28` (4): the active runtime substrate per deployment is declared at deploy and auditable, so it is recordable in the ITS register of information.
+- `NIST-SP-800-190` §3: workload separation is realized through each tier's isolation primitives (`runc` namespaces, gVisor user-space kernel, microVM hardware boundary) — cited for the primitives, not for the selection axis.
+
+## License impact
+
+This is the adopting ADR for `runc` and gVisor, so both enter the Bill of Materials in [`manifesto/05-licensing-posture.md`](../manifesto/05-licensing-posture.md) as bundled (Apache-2.0; gVisor carries per-file MIT/BSD). Both clear the licence gate. Firecracker and Kata clear the same gate but are not bundled in v1; they enter the Bill of Materials when the microVM tier lands ([#161](https://github.com/Wide-Moat/open-computer-use/issues/161)).
+
+## Threat mitigation
+
+The multi-tenant agent-execution invariant in [`02-trust-boundaries.md`](../02-trust-boundaries.md#4-per-tenant-isolation-menu) §4 forbids bare `runc` for multi-tenant execution and requires a user-space kernel or hardware virtualization; the tier ladder is how a deployment satisfies it. Per-tier escape resistance — seccomp BPF, Landlock, cap-drop ALL, read-only rootfs, and the zero-pass red-team gate — is held by NFR-SEC-02.

package/docs/architecture/adr/0004-operator-authentication-substrate.md

@@ -0,0 +1,63 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-01
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC6.1, ISO27001-A.8.2, DORA-Art.9, NYDFS-500.7, EU-AI-Act-Art.14]
+license-impact: none
+threat-mitigation-link: ../components/02-control-operator-api.md
+---
+
+Fixes how a human operator and an automated SOAR caller authenticate to the Control / operator API, and what that costs on the solo path. Audience: anyone touching operator auth, the kill switch, or SOAR integration.
+
+# ADR-0004: Operator authentication substrate
+
+## Status
+
+`proposed`
+
+## Context
+
+The Control / operator API ([component 02](../components/02-control-operator-api.md)) is the privileged plane: it reaches the kill switch, the denylist authority, and tier admission. Two principals call it — a human operator and an automated SOAR responder — and the component marks operator-auth as `needs ADR` in its Boundaries, Operational concerns, and Open question #5 (tracked [#225](https://github.com/Wide-Moat/open-computer-use/issues/225)). This ADR closes that question.
+
+The one-click solo install is an NFR-shaping invariant: the default deployment runs single-operator, no IdP, no KVM, and must not pay for a regulated enterprise's identity machinery to start. The substrate has to scale from that floor up to a customer with a federated identity provider and a PAM tool, without forking the contract.
+
+Dual-control and break-glass stay out of scope. The kill switch is itself the single-operator emergency path, and accountability is already carried by the chain-linked audit emit before acknowledgement. The solo shelf has one operator, so two-person control cannot be a baseline.
+
+## Decision
+
+The Control / operator API authenticates a human operator and an automated SOAR caller against a two-shelf substrate — minimal shelf is a host-rooted local operator credential plus a signature-verified signed-webhook, full shelf makes OCU a relying-party to the customer IdP (OIDC + SCIM, PAM-JIT via OIDC-asserted claims) and a SPIFFE SVID workload identity for SOAR — with multi-party approval left as a post-v1 policy seam over the same audit set, and no break-glass or dual-control fixture added.
+
+## Consequences
+
+- Human identity, minimal shelf: a single host-rooted local operator credential, no IdP. Satisfies NFR-SEC-09 and NFR-COMP-29; preserves the zero-config solo path.
+- Human identity, full shelf: OCU is a relying-party to the customer IdP — Keycloak/OIDC reference RP plus SCIM provisioning — with PAM just-in-time access driven by OIDC-asserted claims that integrate the customer PAM tool (a SAML-only IdP or PAM federates in through Dex or Keycloak, never an OCU SAML surface). The IdP and PAM tool are customer-provided, never bundled (NFR-COMP-29).
+- SOAR machine identity, minimal shelf: signed-webhook plus admin API, the signature verified before any action per [component 02](../components/02-control-operator-api.md) (P2-R2), satisfying NFR-COMP-27.
+- SOAR machine identity, full shelf: a SPIFFE SVID over mTLS, reusing the NFR-SEC-09 workload-identity floor. The per-boundary signer assignment and PKI tool pick are decided upstream by the PKI ADR tracked at [#152](https://github.com/Wide-Moat/open-computer-use/issues/152) ([`02-trust-boundaries.md`](../02-trust-boundaries.md) §8.1 names signer identity per boundary; the per-boundary signer table lands with that ADR); this ADR depends on it for the full-shelf signer and does not pick the PKI tool.
+- A privileged call touches the Egress trust-edge ([component 06](../components/06-egress-trust-edge.md)) as denylist authority and emits to the Audit pipeline ([component 07](../components/07-audit-pipeline.md)); the emit-before-acknowledge ordering and fail-closed posture are governed by NFR-SEC-45, the kill-switch latency by NFR-SEC-01 and its under-saturation bound NFR-SEC-55.
+- Multi-party approval is a named post-v1 policy seam layered over the NFR-SEC-45 audit set; a customer whose NIST SP 800-53 AC-3(2) baseline requires it selects it then. Nothing is built for it now.
+- [Component 02](../components/02-control-operator-api.md) moves its `adr` reference from `[]` to `[0004]`.
+
+## Alternatives considered
+
+- Bundle Teleport as the access plane — rejected: AGPLv3 plus commercial-only binaries fail the license gate (05-licensing-posture.md reject-table).
+- Bundle HashiCorp Boundary as the access plane — rejected: BUSL fails the license gate (05-licensing-posture.md reject-table).
+- Add a break-glass credential alongside the operator credential — rejected: the kill switch is already the single-operator emergency path and the audit emit already carries accountability, so a third fixture is ceremony.
+- Assert two-person dual-control as the v1 baseline — rejected: the solo shelf has one operator, so it cannot be a baseline; it lands as the post-v1 multi-party seam instead.
+
+## Compliance impact
+
+SOC2-CC6.1 and ISO 27001 A.8.2 (privileged-access control), DORA Art. 9 (protection and prevention), NYDFS 500.7 (access privileges), EU AI Act Art. 14 (human oversight — the kill switch is the oversight control).
+
+## License impact
+
+None. OCU stays a relying-party; Keycloak/OIDC and SPIRE on the full shelf are integrated, not bundled by this ADR; the customer PAM tool is never bundled.
+
+## Threat mitigation
+
+Mitigates the P2 attack-path rows in [component 02](../components/02-control-operator-api.md): unauthenticated or spoofed access to the privileged plane, and an unverified SOAR caller acting on the denylist or kill switch.

package/docs/architecture/adr/0005-egress-credential-delivery-envoy-sds.md

@@ -0,0 +1,62 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-01
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC6.1, ISO27001-A.8.24, NYDFS-500.15, PCI-DSS-Req.3]
+license-impact: none
+threat-mitigation-link: ../02-trust-boundaries.md
+---
+
+Egress credential delivery uses off-the-shelf Envoy SDS; OCU stores, mints, and rotates no secrets.
+
+# ADR-0005: Egress credential delivery is off-the-shelf Envoy SDS
+
+## Status
+
+`proposed`
+
+## Context
+
+The Egress trust-edge (zone 4, [02-trust-boundaries.md](../02-trust-boundaries.md)) attaches upstream authorization on the outbound leg so the guest never holds the real credential (NFR-SEC-23 invariant). Behind that injection sits a source question: where the credential rests, what API the edge calls to fetch it, and who owns the unseal, rotation, lease, and key-escrow lifecycle of that source.
+
+Envoy's Secret Discovery Service (SDS, gRPC xDS) is a standard protocol for runtime secret delivery to a proxy, with hot-swap on push. Envoy's native `credential_injector` filter attaches an Authorization header on the outbound leg. Both are off-the-shelf and require no OCU code for credential delivery, minting, or rotation. A solo operator points SDS at a static file; a regulated enterprise points it at a customer-provided SDS-compatible store over the same protocol.
+
+## Decision
+
+The Egress trust-edge receives the upstream credential over Envoy SDS; the SDS source is a static file (solo deployments) or a customer-provided SDS-compatible store (enterprise deployments). Envoy's `credential_injector` filter attaches the Authorization header on the outbound leg. OCU stores, mints, and rotates nothing. Credential minting, rotation, revocation, and per-issuance audit are the SDS source's responsibility: the customer's store on the enterprise shelf, an operator-managed artifact on the solo shelf.
+
+## Consequences
+
+- Zone count is five (was six). Credential custody is no longer a separate zone or container; credential attachment is a capability of the Egress trust-edge. Threat-model rows in [`06-threat-model.md`](../06-threat-model.md) and token-taxonomy rows in [`02-trust-boundaries.md`](../02-trust-boundaries.md) §8 that named Credential custody re-anchor to the Egress trust-edge and the SDS source.
+- The solo path stays zero-config. A static file source has no stateful service, no unseal step, and no key infrastructure: the operator places the credential file on the host and points Envoy SDS at it. The minimal-shelf long-lived key is admissible only under NFR-SEC-60; the edge process memory is not a secret store against host-root.
+- The enterprise path delegates lifecycle to the customer store. The customer provides an SDS endpoint (a gRPC address) that Envoy queries; that store owns unseal, dynamic-secret issuance, rotation, revocation, and audit. OCU documents the SDS contract — the Secret resource shape, TTL and refresh behavior, error behavior — and the customer operates the store.
+- Upstream authorization is attached at the boundary, never in the guest. The guest carries no long-lived upstream secret on the egress leg (it may hold a short-lived session-scoped handle, which is not the upstream credential); Envoy's `credential_injector` attaches the credential on the edge-originated upstream leg before forwarding. The NFR-SEC-23 invariant (the real upstream secret never enters the guest) holds. The mechanism that attaches it — edge-inject here, or a protocol broker for a high-value scoped credential — is selected per upstream in [ADR-0007](0007-egress-auth-mechanism.md).
+- The bespoke `F8` lease-pull gRPC protocol (issue [#205](https://github.com/Wide-Moat/open-computer-use/issues/205)), the STS delegator, the per-session lease-issue audit event, and the OCU-enforced TTL and revoke bounds are removed: they governed an OCU minting service that does not exist when Envoy SDS is the delivery path.
+- The Egress trust-edge ([component 06](../components/06-egress-trust-edge.md)) records `0005` in its `adr:` front-matter. The SDS source binding (static file or customer endpoint) is a component-spec wiring detail.
+- Envoy (Apache-2.0) is the egress edge and a bundled dependency. See the Bill of Materials in [`manifesto/05-licensing-posture.md`](../manifesto/05-licensing-posture.md).
+
+## Alternatives considered
+
+- **Bespoke `F8` lease-pull protocol plus an OCU STS delegator.** Rejected: Envoy SDS is an open, implemented standard. A proprietary lease-pull wire protocol and minting service add code, audit surface, CVE liability, and operational cost for a property SDS already delivers, and grant no security property SDS lacks.
+- **An OCU-bundled secret store (OpenBao, or a thin SDS server OCU runs).** Rejected: the store's governance — unseal, rotation policy, audit sink, key custody — is the customer's. Bundling a store breaks the solo one-click path with stateful infrastructure and duplicates machinery the customer already operates. OCU stays a consumer of the SDS API.
+- **Inject the credential inside the guest (sandbox mount, env var, or guest-side config).** Rejected: violates NFR-SEC-23. A guest with in-sandbox root extracts the secret from memory, `/proc`, or the filesystem. The edge boundary holds the secret outside the guest, where injection keys on a presented scoped credential, never on network origin ([ADR-0007](0007-egress-auth-mechanism.md), the P6-E2 anti-pattern).
+
+## Compliance impact
+
+- `SOC2-CC6.1` / `ISO27001-A.8.24`: secret confidentiality is realized by the SDS source — a customer store (enterprise) or a static file (solo). No OCU key-management policy is present to audit.
+- `NYDFS-500.15`: encryption of nonpublic information in transit (the upstream authorization header) holds on the edge-originated TLS leg and on the customer store's TLS to its SDS endpoint.
+- `PCI-DSS-Req.3`: stored-credential protection is the customer store's on the enterprise shelf; the solo shelf rests the credential in a static file under authenticated encryption (the file primitive is a component-spec choice, not this decision).
+
+## License impact
+
+Envoy is Apache-2.0 and is bundled. No stateful secret store is bundled by this decision.
+
+## Threat mitigation
+
+Addresses Information Disclosure and credential-compromise paths at the Egress trust-edge (the credential is attached only on the edge-originated upstream leg, where the request's network identity is known) and on the guest→upstream path (the upstream secret never enters the guest, per NFR-SEC-23). The deferred maturity question on Envoy's `credential_injector` / OAuth2 filter for untrusted upstreams is tracked in [component 06](../components/06-egress-trust-edge.md) Open questions.

package/docs/architecture/adr/0006-egress-forward-proxy-substrate.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: 2026-06-01
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC6.6, SOC2-CC6.7, NYDFS-500.15, DORA-Art.9, EU-AI-Act-Art.12]
+license-impact: Envoy Apache-2.0; clears the allow-list, bundled by this ADR
+threat-mitigation-link: ../components/06-egress-trust-edge.md
+---
+
+Picks the forward-proxy substrate for the Egress trust-edge and scopes it to the v1 deny-by-default floor. Audience: anyone wiring or auditing the sandbox's outbound path.
+
+# ADR-0006: Egress forward-proxy substrate
+
+## Status
+
+`proposed`
+
+## Context
+
+The Egress trust-edge ([component 06](../components/06-egress-trust-edge.md)) is the sandbox's sole outbound network path. v1 ships one capability there: a deny-by-default destination allow-list applied at connect time on resolved-IP and SNI, with a machine-parseable reason on every block. That floor must run from a single `docker-compose up` with no certificate authority, no IdP, and no policy engine — the one-click solo install is an NFR-shaping invariant.
+
+The component spec carries no substrate decision (`adr: []`) and an open question on which proxy provides it (open-Q#2). A purpose-built forward proxy supplies connect-time allow-listing, a controllable resolver, and an external-authorization seam. The risk is over-buying: pulling in TLS termination, dynamic config distribution, or an inline content-inspection path that the v1 floor does not need and that would tax the solo default.
+
+MITM termination — per-SNI on-the-fly leaf certificates — was a separate decision deferred at the time of this ADR (component 06 open question #2, the MITM-termination half); it is now decided in [ADR-0007](0007-egress-auth-mechanism.md) on the same Envoy substrate plus a self-hosted SDS minting service. This ADR fixes only the forward-proxy substrate and the deny-by-default floor.
+
+## Decision
+
+The Egress trust-edge runs an Apache-2.0/MIT/BSD forward proxy — Envoy is the lead candidate (Apache-2.0, native connect-time SNI/resolved-IP filtering and an `ext_authz`/`ext_proc` seam), with the final binary left to the component spec — configured to the v1 floor only: a deny-by-default allow-list at connect time on resolved-IP + SNI, a proxy-owned resolver carrying the mandatory deny-set, a machine-parseable `x-deny-reason` on block, one external-authorization seam whose default backend is a static allow-list, and a per-upstream-leg credential-origination hook.
+
+## Consequences
+
+- Component 06 records this ADR in its `adr:` front-matter (`[]` → `[0006]`). The allow-list at connect time satisfies NFR-SEC-08 and NFR-SEC-17; the proxy-owned resolver enforces NFR-SEC-12's mandatory deny-set; the structured block carries the `x-deny-reason` vocabulary the spec already defines. This ADR does not restate those NFRs.
+- The `ext_authz`/`ext_proc` seam ships with a static allow-list as its default backend — the solo path configures no policy engine. OPA as a full-shelf backend behind the same seam is deferred, not v1.
+- The credential-origination hook is the seam where the edge attaches the upstream authorization received over Envoy SDS ([ADR-0005](0005-egress-credential-delivery-envoy-sds.md)); it fires only on a leg that needs it, never on the transparent default route. No CA, cert-issuer, ICAP, or credential wiring lands on the transparent path.
+- The broker backend leg ([component 04](../components/04-storage-broker.md), F9) traverses the proxy on a storage-dedicated lane, distinct from the guest egress lane ([NFR-SEC-85](../manifesto/02-nfrs.md), [ADR-0011](0011-storage-egress-lane.md)), with no TLS termination, so the broker-signed request is forwarded byte-intact per NFR-SEC-25.
+- Every allow and every deny is emitted as an OCSF event through the Audit pipeline ([component 07](../components/07-audit-pipeline.md)); the payload-independent exfil tripwire (NFR-SEC-57) runs on this path with no CA. This ADR adds no requirement to either.
+- The egress posture is the NFR-FLEX-15 ladder (deny-all / transparent pass-through / egress-wide bump / external SDS): this ADR fixes the forward-proxy substrate and the deny-by-default floor that every rung shares; egress-wide-bump origination (NFR-SEC-30, NFR-SEC-37, NFR-SEC-50) and DLP/ICAP as a bump-rung config (NFR-COMP-28) ride the same substrate and are decided in [ADR-0007](0007-egress-auth-mechanism.md) (which resolves component 06 open question #2).
+- xDS dynamic config and per-node sharding ([#175](https://github.com/Wide-Moat/open-computer-use/issues/175)) are deferred seams this ADR names but does not design.
+
+## Alternatives considered
+
+- **Squid (GPL-2.0+)** — mature forward proxy with SslBump for the later egress-wide-bump leg; clears the allow-list, but a bundled GPL binary triggers the distribution review noted in [`manifesto/05-licensing-posture.md`](../manifesto/05-licensing-posture.md), and its config model fits the deny-by-default floor less directly than Envoy's filter chain.
+- **HAProxy (GPL-2.0+ / LGPL)** — passes the allow-list and handles SNI routing, but bundling carries the same GPL distribution review and it lacks a first-class external-authorization seam equivalent to `ext_authz`.
+- **Hand-rolled CONNECT proxy** — a minimal Go/Rust proxy owned end to end. Rejected: re-implementing resolver pinning, filter chains, and an `ext_authz` seam is net-new attack surface a regulated-enterprise InfoSec review would not credit against a vendor-backed proxy.
+
+## Compliance impact
+
+- `SOC2-CC6.6` / `SOC2-CC6.7`: the deny-by-default allow-list and structured deny reason are the boundary-protection and transmission controls for outbound flows.
+- `NYDFS-500.15`: outbound destinations are gated and logged, supporting the access-and-monitoring controls.
+- `DORA-Art.9`: the edge is the network-segmentation and traffic-control measure for the sandbox's outbound leg, recordable per deployment.
+- `EU-AI-Act-Art.12`: allow/deny events emitted to the Audit pipeline contribute to the automatic record-keeping required of high-risk systems.
+
+## License impact
+
+This is the adopting ADR for the forward proxy: Envoy enters the Bill of Materials in [`manifesto/05-licensing-posture.md`](../manifesto/05-licensing-posture.md) as bundled (Apache-2.0), clearing the licence gate. The Squid and HAProxy alternatives clear the same gate, but a bundled GPL binary triggers the distribution review that file records; neither is bundled by this ADR.
+
+## Threat mitigation
+
+The deny-by-default floor is the v1 realization of the egress controls in [`06-egress-trust-edge.md`](../components/06-egress-trust-edge.md) (P6 rows): connect-time allow-listing on resolved-IP + SNI, the proxy-owned resolver's mandatory deny-set, and the payload-independent exfil tripwire (NFR-SEC-57) that runs in both postures without a CA. The credential-origination hook keeps the upstream authorization off the guest, attached over Envoy SDS ([ADR-0005](0005-egress-credential-delivery-envoy-sds.md)) only on the leg that needs it.

package/docs/architecture/adr/0007-egress-auth-mechanism.md

@@ -0,0 +1,72 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-01
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC6.1, SOC2-CC6.6, NYDFS-500.15, DORA-Art.28, EU-AI-Act-Art.15]
+license-impact: TLS-termination substrate is the same Envoy already bundled by ADR-0006; a per-SNI cert-minting sidecar is the added build surface
+threat-mitigation-link: ../components/06-egress-trust-edge.md
+---
+
+Selects how the Egress trust-edge attaches upstream authorization — by edge injection or by a protocol broker — and scopes v1 to edge injection only. Audience: anyone wiring or auditing how the sandbox reaches an authenticated upstream.
+
+# ADR-0007: Egress auth mechanism — edge-inject vs protocol-broker
+
+## Status
+
+`proposed`
+
+## Context
+
+The guest holds no long-lived upstream secret ([NFR-SEC-23](../manifesto/02-nfrs.md)); the credential is attached outside the guest. Two mechanisms can do that, and they suit different upstreams. The Egress trust-edge can originate the connection and inject an `Authorization` header (edge-inject), or a host-side broker can hold the credential, speak the upstream protocol itself, and expose only a local handle to the guest (protocol-broker). [ADR-0005](0005-egress-credential-delivery-envoy-sds.md) fixed where the credential comes from (Envoy SDS); [ADR-0006](0006-egress-forward-proxy-substrate.md) fixed the forward-proxy substrate (Envoy, deny-by-default floor). Neither decided which mechanism attaches the credential, nor how the edge terminates TLS to do it — left open as component-06 open question #2. The forcing constraint is the one-click solo install ([NFR-FLEX-15](../manifesto/02-nfrs.md)): the default path must run from one `docker-compose up` with no certificate authority an operator has to manage.
+
+## Decision
+
+We will select the egress auth mechanism by the upstream's properties — edge-inject for a fixed-client, low-granularity bearer credential; protocol-broker for a high-value credential scoped by per-operation rights — and ship only edge-inject in v1, because the v1 upstream is an LLM API and a broker is unneeded surface until a scoped-credential upstream exists.
+
+The selection axis:
+
+| Upstream property | Mechanism |
+|---|---|
+| Client is a fixed binary that hardcodes the endpoint; credential is one bearer token; protocol is HTTP + `Authorization`; no per-operation authorization needed | **edge-inject (egress-wide bump)** |
+| Credential is high-value and scoped by rights (repo / object / tenant); protocol is multi-operation (git-smart-http, S3/SigV4, REST with per-object authz); the credential holder must authorize each operation | **protocol-broker** |
+
+v1 implements edge-inject. Protocol-broker is named, abstraction-ready, and deferred: the pattern is already canonical as the Storage broker zone ([02-trust-boundaries.md](../02-trust-boundaries.md) §2), which holds the object-store backend credential and exposes a session-scoped handle. A future scoped-credential upstream reuses that zone; v1 builds no new broker.
+
+**edge-inject mechanism (v1).** The edge runs egress-wide bump: it terminates every outbound TLS connection by presenting a leaf certificate minted on demand for the requested SNI, signed by a per-deployment CA whose public certificate is in the sandbox trust store and whose private key never enters the guest. It injects the upstream credential on the re-originated leg and re-establishes TLS to the genuine upstream, validating the upstream's real certificate against the public CA set. Injection is gated on a presented, scoped credential carried by the request — never on the request's network origin (a guest process that presents no credential receives none, which is why a bare `curl` from the sandbox reaches an allowed host but is unauthenticated). The substrate is the Envoy already bundled by ADR-0006 as the data plane, plus a self-hosted SDS minting service (a gRPC `SecretDiscoveryService` that stamps a leaf for the requested SNI from the CA key); Envoy alone does not mint leaves on the fly.
+
+## Consequences
+
+- Component 06 records this ADR in its `adr:` front-matter (`[0005, 0006]` → `[0005, 0006, 0007]`); open question #2 (the MITM-termination half) is resolved here.
+- Egress posture follows need, not a fixed default ([02-trust-boundaries.md](../02-trust-boundaries.md) §7): a deployment that needs no egress runs deny-all; one that needs only unauthenticated internet runs transparent pass-through; one that needs an authenticated upstream runs egress-wide bump. Bump is the default *only when an upstream credential is configured* — it is not imposed on a deployment that needs no outbound credential, so the one-click solo path stays intact. [NFR-FLEX-15](../manifesto/02-nfrs.md) is reframed from a two-mode switch to this ladder.
+- The bump CA is generated per deployment and its public certificate is injected into the sandbox trust store automatically at start; "one-click" is preserved by automating the CA, not by omitting it. The private key sits only on the minting service.
+- Egress-wide bump holds plaintext for every inspected destination at the edge, a larger blast radius than the broker pattern. The credential-holding minter and the plaintext-inspection path are distinct trust surfaces: the rule the substrate must not blur is that the injected credential does not share a blast radius with the plaintext of all egress. A single Envoy-plus-minter process is admissible on the solo shelf only because the injected credential there is itself scoped and short-lived; a high-value long-lived credential separates the minter from the inspection plane.
+- The leaf source is static or dynamic by the allow-list's shape, not its size: a config-time-enumerable allow-list that changes slower than the deploy cadence is served by pre-minted leaves over a file SDS source (Envoy holds thousands of certificates without issue — the limit is enumerability, sub-domain depth, and churn, not a certificate count). A non-enumerable allow-list (CDN shards, per-tenant sub-domains, deep multi-label hosts a wildcard cannot compress, or third-party-controlled naming) requires the dynamic per-SNI minter. v1's single LLM apex is the trivial static case; the minter is specified so the dynamic case needs no re-decision.
+- mTLS / cert-pin / proof-of-possession upstreams cannot be served by header injection and stay tracked at [#176](https://github.com/Wide-Moat/open-computer-use/issues/176); they are a protocol-broker or out-of-scope case, not an edge-inject one.
+- This ADR adds no requirement to the Audit pipeline, the resolver, or the allow-list that ADR-0006 already fixed; it sits above them.
+
+## Alternatives considered
+
+- **Protocol-broker for v1's LLM upstream** — rejected: the LLM credential is a single low-granularity bearer to a fixed endpoint, so a broker that speaks the protocol and authorizes per operation buys nothing the edge does not, and adds a stateful service to the solo path.
+- **mitmproxy / Squid ssl-bump as the bump substrate** — both mint per-SNI leaves natively with less code than a custom SDS minter. Rejected as the default: adopting either as the bump engine drops the Envoy data plane (the allow-list, OCSF audit emit, and `ext_authz` seam ADR-0006 already placed there) or runs two proxies in series. The Envoy-plus-minter path keeps one data plane; mitmproxy (BSD, clears the licence gate) is recorded as the fallback for a deployment that does not need the Envoy data plane.
+- **GCP Secure Web Proxy (managed Envoy + minter)** — supplies exactly this shape as a managed service. Rejected: not self-hostable inside a customer perimeter, which is the deployment target; it informs the architecture but cannot be the substrate.
+- **Inject user personal access tokens through the egress edge** — proposed as a way to let the agent reach a user's third-party account by storing each user's PAT outside the guest and injecting it like the LLM key. Rejected: a PAT is a high-value credential scoped by rights, so by this ADR's own axis it is a protocol-broker case, not edge-inject. Edge injection cannot authorize per operation (it staples the token to every request to that host) and would make OCU a store of users' personal third-party access — the broad blast radius an InfoSec review rejects. The correct path is the broker pattern with short-lived, per-resource tokens (e.g. a GitHub App installation token), deferred with the rest of the broker mechanism.
+
+## Compliance impact
+
+- `SOC2-CC6.1` / `SOC2-CC6.6`: the credential is attached outside the guest on the edge-originated leg, and the bump segment is a single named inspection point — the access-control and boundary-protection story for authenticated egress.
+- `NYDFS-500.15`: the upstream authorization is encrypted in transit on both legs; the re-originated leg validates the genuine upstream certificate.
+- `DORA-Art.28` / `EU-AI-Act-Art.15`: the selection axis records, per upstream, where a credential is held and how each authenticated outbound flow is mediated — the third-party-arrangement and robustness evidence for the outbound path.
+
+## License impact
+
+The TLS-termination substrate is the Envoy already bundled by [ADR-0006](0006-egress-forward-proxy-substrate.md); no new bundled proxy. The added build surface is a self-hosted SDS minting service (OCU code). mitmproxy, if later adopted as the fallback engine, is BSD and clears the licence gate; it is recorded in [`manifesto/05-licensing-posture.md`](../manifesto/05-licensing-posture.md) as rejected-as-default for dropping the Envoy data plane.
+
+## Threat mitigation
+
+Resolves the MITM-termination half of [component 06](../components/06-egress-trust-edge.md) open question #2 and tightens P6-E2: injection keyed on a presented scoped credential, never on network origin, bounds a cross-scope or compromised-in-guest process to the credentials it can present rather than to whatever the sandbox can reach. The anti-pattern this forbids — "inject because traffic came from sandbox X" — is named so it is not re-introduced.

package/docs/architecture/adr/0008-session-egress-attribution.md

@@ -0,0 +1,59 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: proposed
+last-reviewed: 2026-06-02
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+supersedes: []
+superseded-by: null
+compliance-impact: [SOC2-CC6.1, NYDFS-500.15, DORA-Art.28]
+license-impact: none
+threat-mitigation-link: ../06-threat-model.md
+---
+
+Fixes how the Egress trust-edge attributes an outbound request to the session that owns it, and scopes that attribution to deny decisions only. Audience: anyone wiring or auditing how per-session egress policy reaches the edge.
+
+# ADR-0008: Session-to-egress attribution by presented token
+
+## Status
+
+`proposed`
+
+## Context
+
+[ADR-0007](0007-egress-auth-mechanism.md) gates credential injection on a credential the request *presents*, never on its network origin — the forbidden P6-E2 pattern is "inject because traffic came from sandbox X". Per-session deny policy still has to reach the edge: the kill-switch denylist ([component 02](../components/02-control-operator-api.md)), downloadable-deny ([NFR-SEC-73](../manifesto/02-nfrs.md)), and per-session rate limits all need the edge to know *which session* a request belongs to. Nothing decided how the edge derives that session identity. Because the edge bump-terminates TLS on the egress-wide-bump rung ([NFR-FLEX-15](../manifesto/02-nfrs.md), [02-trust-boundaries.md](../02-trust-boundaries.md) §7, [ADR-0006](0006-egress-forward-proxy-substrate.md), [ADR-0007](0007-egress-auth-mechanism.md)) — the guest trusts the per-deployment CA whose public certificate is in its trust store, so the edge can terminate and read — it holds the plaintext request and the session token the guest carries. The open question is whether attribution reads that L7 token or instead needs a network-layer fact (source IP, mTLS peer, the host↔guest connection identity).
+
+## Decision
+
+We will attribute an outbound request to its owning session by the **session-scoped token the request presents at L7**, read after bump-termination, and key every per-session deny and rate decision on the verified token's claims — not on any network-layer fact. The edge runs the off-the-shelf Envoy filter chain `jwt_authn → ext_authz → rbac → ratelimit → credential_injector → router`: `jwt_authn` reads and verifies the token and writes its session claim to dynamic metadata; `ext_authz` consults the denylist and `ratelimit` applies the per-session limit on that claim; `credential_injector` attaches the SDS-delivered upstream credential. Injection stays gated on the presented token by filter order — auth and denylist filters terminate a disallowed request before it reaches the injector, which carries no per-request predicate of its own — so a request that presents no valid session token is rejected and never injected, satisfying the [ADR-0007](0007-egress-auth-mechanism.md) gate. The session token is the presented scoped credential that ADR-0007 gates injection on: one L7 read of the same artifact serves both the deny/rate decision here and the injection gate there.
+
+Network-layer identity is **not** the egress attribution key. The host-attested network fact (per-session netns, host kernel peer-credentials, or the hypervisor vsock context id by runtime tier) attributes a connection to a *guest* on the host↔guest channel and isolates one sandbox from another — guest isolation, owned by [02-trust-boundaries.md](../02-trust-boundaries.md) §4 and [NFR-SEC-43](../manifesto/02-nfrs.md). It is a different boundary from egress session attribution and is not restated as one here.
+
+## Consequences
+
+- The session claim drives **deny** at the Egress trust-edge ([component 06](../components/06-egress-trust-edge.md)): `ext_authz` refuses a revoked session against the denylist, downloadable-deny ([NFR-SEC-73](../manifesto/02-nfrs.md)) drops an egress-eligible artifact, and `ratelimit` bounds the session. It is never the injection trigger on its own — that is the [ADR-0007](0007-egress-auth-mechanism.md) line; here it is enforced by filter order, not a flag.
+- Component 06 records this ADR in its `adr:` front-matter (`[0005, 0006, 0007]` → `[0005, 0006, 0007, 0008]`); the sandbox-listener face now has a named session key — the L7 token — and the denylist-at-edge invariant reads it through `ext_authz`.
+- Positive: attribution needs no per-session network plumbing, so it holds identically across every runtime tier ([ADR-0003](0003-sandbox-runtime-tier-ladder.md)) — `runc` shared-kernel with no context id, gVisor, and microVM all present the same L7 token. The chain is native Envoy ([ADR-0006](0006-egress-forward-proxy-substrate.md)); no custom data-plane code.
+- Negative: the token must be a verifiable JWT for `jwt_authn` to validate it standalone; an opaque token moves validation to an `ext_authz` introspection call-out to the session authority (still native Envoy, one more dependency on the call path). `credential_injector` is the youngest filter in the chain — pin its version and smoke-test the SDS-rotation path.
+- Neutral: a downstream filter trusts the token only after `jwt_authn` records a verified status, never a copied claim header alone, so a forged claim header cannot pass; claims reach `ext_authz` as metadata, not a trusted header.
+
+## Alternatives considered
+
+- **Host-attested network fact (netns / peer-credentials / vsock context id) as the egress key** — rejected: that fact attributes a connection to a guest and isolates sandboxes (the host↔guest concern, [NFR-SEC-43](../manifesto/02-nfrs.md)); it is absent or weak exactly where the edge bumps (shared-kernel `runc` has no context id), and the edge already holds the session token in plaintext after bump, so a network fact adds nothing the L7 read does not give. Carrying it onto the egress edge conflates isolation with attribution.
+- **Source IP as the session key** — rejected: a guest-settable network fact; keying any decision on it re-introduces the P6-E2 network-origin pattern.
+- **A custom Envoy filter or `ext_proc` for the read/validate/inject path** — rejected: the native `jwt_authn` / `ext_authz` / `ratelimit` / `credential_injector` chain covers it; custom data-plane code is only needed for value-varying per-session credential selection, which v1's single upstream does not require.
+
+## Compliance impact
+
+- `SOC2-CC6.1`: per-session deny reaches the boundary on a verified token claim, so a revoked or rate-limited session is enforced at the egress point — the access-control story for outbound traffic.
+- `NYDFS-500.15` / `DORA-Art.28`: the outbound leg's session identity is the verified token, audited per request, recording which session each authenticated outbound flow belongs to.
+
+## License impact
+
+None. The chain is native Envoy filters already bundled by [ADR-0006](0006-egress-forward-proxy-substrate.md); no new dependency.
+
+## Threat mitigation
+
+Tightens the deny side behind P6-E2 in [the threat model](../06-threat-model.md): a request presenting no valid session token is rejected before the injector, and a forged claim is caught by the verified-status check, so a compromised guest cannot borrow a co-tenant's egress policy by forging a header. Per-action authorization on the attributed session — what that session may do to which object — is separate and tracked at [#187](https://github.com/Wide-Moat/open-computer-use/issues/187); whether the session token is a JWT or an opaque token validated by introspection is the open sub-question at [#160](https://github.com/Wide-Moat/open-computer-use/issues/160).