@mseep/open-computer-use 1.0.0

package/docs/future-architecture/architecture/04b-credential-broker.md

@@ -0,0 +1,153 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 04b — Credential Broker
+
+> The host-side process that holds **real** cloud credentials so the sandbox guest never sees them. Follows the industry-observed FUSE-filestore-over-loopback broker pattern.
+>
+> **Phase placement.** Foundations in Phase 4 (secret broker section of [07-security.md](./07-security.md)); deployment-topology decisions referenced here. Final shape locked when Phase 4 ships.
+
+## Why a broker (not credential injection)
+
+The guest must reach S3, GCS, and the Anthropic API. The naive choices both fail:
+
+- **Inject real keys into the guest env.** Any RCE in the guest exfils them. Violates the "no secrets in the sandbox" invariant.
+- **Egress proxy that re-signs the request.** Works for HTTP headers (`x-api-key`); breaks for SigV4 because the signature covers the body the proxy cannot legally rewrite. AND it conflates the **network** plane with the **authorization** plane (see [§ Two planes, two mechanisms](#two-planes-two-mechanisms)).
+
+The broker pattern: a trusted daemon outside the guest holds the real keys, accepts a **scoped JWT** from the guest over a host-controlled channel (vsock or loopback), and signs the outbound request itself.
+
+```text
+[ guest (untrusted) ]                            [ trust boundary ]
+  FUSE filestore   ── HTTP/localhost:9112 ───►  broker (host-side)
+   client                                          (real GCS/S3/API creds,
+   (scoped JWT,                                    SigV4 / x-api-key signing,
+    filesystem_id,                                 TLS origination outbound)
+    NO secrets)
+                                                       │
+                                                       ▼
+                                                GCS / S3 / model API
+```
+
+## Two planes, two mechanisms
+
+**Network identity** (egress to the public internet): grounded in the **path itself** — the guest has no route out other than via the egress proxy. The HTTPS request carries no token. The proxy and broker know it's a sandbox because nothing else can reach them.
+
+**Resource authorization** (per-session data access): grounded in a **scoped JWT** that encodes `session_id`, `filesystem_id`, scope (which bucket/prefix), and TTL. The broker validates the JWT and enforces scope.
+
+These two planes are **orthogonal**. JWT does not authenticate egress; the network path does. JWT does not authenticate the network; it authorizes a specific resource operation. Conflating them produces either "secrets in the guest" (network-bound only) or a fake security perimeter (JWT for egress that the guest could leak anyway). Phase 4 + Phase 8 design must keep them separate.
+
+## Broker contract
+
+### Authentication / authorization
+- Accept a per-session **Ed25519 JWT** from the guest. Validate signature, expiry, scope claims.
+- Claims minimum set: `session_id`, `filesystem_id`, `tenant_id`, `ops` (e.g. `read`, `write`), `exp`.
+- Reject anything outside the JWT's stated scope (no cross-session reads, no cross-tenant access).
+- Support short TTLs (≤ 15 min target) and explicit revocation (broker-side blocklist by `session_id`).
+
+### Upstream signing
+- Hold the real GCS service-account key / S3 access keys / `x-api-key`, on disk via the host secret store (Vault, AWS Secrets Manager, k8s Secret with appropriate KMS) — never inside the guest.
+- Sign each outbound call:
+  - **S3 / S3-compatible** → SigV4 with broker's keys after scope check (guest never signs).
+  - **Anthropic API** → inject `x-api-key` + `anthropic-version` after scope check.
+  - **GCS** → service-account token exchange.
+- **Terminate TLS outbound** (TLS origination): guest speaks plaintext to broker over a host-controlled channel; broker speaks valid HTTPS to upstream with strict cert validation (fail-closed).
+
+### Filestore semantics
+- CRUD: `list`, `stat`, `get`, `put`, `delete`, `move`.
+- Logical paths (`/inputs`, `/outputs`, `/tool-results`) map to the physical backend (`bucket/prefix`) keyed on `filesystem_id`.
+- Streaming for large objects — never buffer a whole file in broker memory.
+- ro vs rw enforcement per mount point, derived from JWT `ops` claim.
+
+### Operational
+- Listen on loopback / vsock only — **never** on a public host interface.
+- Audit log of every operation with `session_id`, `filesystem_id`, operation, decision, `trace_id` ([10-observability.md](./10-observability.md)).
+- Per-token rate limiting; per-tenant aggregate quotas (cross-link [gaps.md § A](../gaps.md#a-multi-tenancy-beyond-per-session)).
+- Domain allowlist (broker refuses to call upstreams outside the configured set).
+- Health endpoint, Prometheus metrics (requests, auth errors, upstream latency).
+
+## Deployment topology by runtime tier
+
+The broker's home depends on the L2 runtime. The choice is **not** a single design but a per-tier matrix.
+
+### Docker / runc / sysbox (shared kernel)
+
+The broker is a sidecar process. Three options, in increasing isolation:
+
+| Variant | Channel | Isolation | Verdict |
+|---|---|---|---|
+| Shared network namespace (`--network container:broker`) | `localhost:9112` | Weakest — shared network stack with the guest | **Anti-pattern for untrusted guests.** Use only for trusted-dev tiers. |
+| Per-network user-defined Docker net | `broker:9112` via DNS | Separate netns; routing controlled by Docker | Acceptable for sysbox-class tenants. |
+| Unix domain socket bind-mounted in | `/run/broker.sock` (ro mount in guest) | No shared netns at all | Strongest in this tier. |
+
+### Firecracker / Cloud Hypervisor (microVM, own kernel)
+
+Sidecar patterns do not apply — the guest has its own kernel, the boundary is the hypervisor (KVM). The broker **must** live host-side and the guest reaches it through an explicit host↔guest channel:
+
+| Channel | Notes |
+|---|---|
+| **virtio-vsock** | Preferred. Native Firecracker/CH primitive, no TCP/IP needed in the guest. Guest can run with no network at all, just vsock → broker. |
+| TAP + IP | Use only when the guest needs a routed network for other reasons. Broker listens on a host address; host-side firewall blocks anything else from the guest. |
+
+The microVM tiers **strengthen** the broker pattern: guest kernel escape (the most common shared-kernel failure mode) does not reach the broker — KVM is in the way.
+
+### Localhost ergonomics over a non-local channel: the vsock shim
+
+Application code (FUSE filestore client, custom backends) assumes `localhost:9112`. To preserve that ergonomics on a microVM tier without baking vsock awareness into every caller:
+
+```text
+GUEST (Firecracker):
+  FUSE filestore client  →  127.0.0.1:9112    ← caller thinks it's local
+        └── vsock-shim: listens on 127.0.0.1:9112,
+            forwards to vsock(host CID, port 9112)    ← dumb bridge, NO secrets
+
+══════════════════ KVM hypervisor ══════════════════
+
+HOST:
+  vsock-listener :9112
+        └── broker (real creds) → S3 / model API / GCS
+```
+
+The shim is a **dumb forwarder** — it holds no keys, runs no policy, knows no JWTs. Implementations: `socat VSOCK-CONNECT ... TCP-LISTEN:9112` for prototyping, or a tiny static Rust/Go binary in the L1 image for production. The illusion of "localhost broker" is independent of whether the host runs one shared broker or broker-per-VM — pick the multi-tenancy posture separately.
+
+## Multi-tenancy: shared broker vs broker-per-VM
+
+A single process serving every guest's traffic = **shared fate** (one broker bug or RCE leaks credentials across tenants). The anchor for safe multi-tenancy is the **vsock CID** assigned by the hypervisor: it is set on the host side, the guest cannot spoof it, and the broker sees it on every connection.
+
+| Posture | Mechanic | Blast radius | Recommendation |
+|---|---|---|---|
+| **Single multiplexing broker** | One process, partitions state by CID + JWT scope | All tenants share one process — compromise = total exposure | Only for trusted-tier deployments |
+| **Broker-per-VM** | One lightweight broker process per VM, started at VM boot, holds only that VM's short-lived creds | Per-tenant — broker dies with the VM | **Recommended** for untrusted tiers |
+| **Per-VM + delegated STS** | Per-VM broker, but the broker itself does not hold a master key — pulls scoped temp credentials from L4 at boot | Per-session — even broker compromise leaks only that session's scoped STS | **Target** for compliance-bearing tiers (cross-link [gaps.md § C](../gaps.md#c-compliance-and-audit-immutability)) |
+
+Localhost ergonomics (the vsock shim) and strong isolation (broker-per-VM + per-VM STS) are **not** mutually exclusive. Phase 4 ships the per-VM model; Phase 6 adds delegated STS.
+
+## Filesystem-scope as a first-class secret-scope dimension
+
+The `filesystem_id` JWT claim is what makes one session's filestore invisible to another, **architecturally** rather than via file permissions:
+
+- The broker maps `(tenant_id, filesystem_id) → bucket/prefix` server-side.
+- The JWT names the `filesystem_id` it's authorized for; the broker refuses any path outside that prefix.
+- Cross-session reads are not "guarded" — they're impossible to express because the JWT cannot name another session's `filesystem_id`.
+
+This is the design lever that lets per-session FUSE mounts (`filestore:session_<SESSION_ID>:/path` style) work without per-session credentials in the guest.
+
+## Open questions (resolve before Phase 4 ships)
+
+- **Issuer of the scoped JWT.** L4? Per-session minting? Where the signing key lives and rotates. **This is the gating decision** — the JWT is the only barrier between "the guest asked" and "the broker spent a real key." Resolve first.
+- **JWT binding to vsock CID.** Either embed CID in claims (broker verifies channel CID == claim CID — defense in depth) or rely purely on the unforgeable CID (simpler).
+- **FUSE mount vs HTTP API only.** The FUSE client path uses a mount; some workloads only need the HTTP CRUD. Phase 4 ships HTTP first; FUSE-in-guest behind a feature flag.
+- **Upstream set on day one.** S3 only? Plus Anthropic Files API? Plus GCS? Start minimal — each upstream is a new attack surface.
+- **Physical backend.** MinIO (PoC), AWS S3, OVH Object Storage. Path-style vs virtual-hosted for S3-compatible — broker normalizes.
+
+## Related
+
+- [04-layer2-runtimes.md](./04-layer2-runtimes.md) — runtime tiers and per-tier isolation mechanics.
+- [05-layer1-guest-agent.md](./05-layer1-guest-agent.md) — L1's `Configure` RPC delivers the scoped JWT into the guest.
+- [06-storage.md](./06-storage.md) — Tier 4 (user data) mounts that the broker serves.
+- [07-security.md](./07-security.md) — secret broker phase placement, image signing, audit log.
+- [08-networking.md](./08-networking.md) — egress proxy (the other half of "no secrets in the guest").
+- [10-observability.md](./10-observability.md) — audit-event schema, secret-scrubbing rules.
+
+## Source
+
+- Internal design notes — credential-broker spec, the two-planes-of-identity argument, and the no-S3-keys-in-the-guest rule.

package/docs/future-architecture/architecture/05-layer1-guest-agent.md

@@ -0,0 +1,138 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 05 — Layer 1: Guest Agent
+
+> The PID 1 process inside every sandbox. Today: Python entrypoint + in-image MCP server. Future: small **Rust** static binary (Phase 7).
+> Language decision: **Rust** ([ADR-0002](../adr/0002-guest-agent-language-go.md)). Follows the established agent-in-microVM runtime pattern.
+
+## Contract (target)
+
+The agent exposes **two ports**:
+
+1. **Data plane — WebSocket.** Bidirectional, JSON frames (serde-tagged enums), zstd compression optional via capabilities negotiation. Carries every per-session interaction: exec, streaming I/O, signal forwarding, CDP/ttyd passthrough. Transport is **auto-detected**, not build-tag-gated:
+   - `vsock` if `/dev/vsock` is present (microVM tiers `kata-ch`, `kata-fc`).
+   - `TCP` otherwise (runc, sysbox, gVisor, dev).
+   - Same `handle_ws` accept loop drives both. Transport is operational, not architectural.
+2. **Control plane — HTTP.** Stateless POSTs for actions that should not flow through the user-facing data plane. Separate listener, same binary:
+   - `GET /healthz`, `GET /readyz` — liveness / readiness probes for L3.
+   - `POST /shutdown` — graceful shutdown signal.
+   - `POST /mount_root` — snapstart restore handshake. **Phase 10 only**, feature-gated until then.
+   - `POST /fs_freeze`, `POST /fs_thaw` — `FIFREEZE` / `FITHAW` ioctl bridge for snapshot consistency. **Phase 10 only.**
+   - `POST /auth_public_key` — hot-reload of the Ed25519 verification key. Optional, Phase 7+.
+
+The L1 agent is **never** publicly reachable — only L3 (provider) talks to it. See [ADR-0008](../adr/0008-internal-grpc-external-rest-mcp.md) for transport positioning across tiers (and the Phase 7 gate on connect-rust vs. WS-frame protocol).
+
+## RPC surface (data plane)
+
+The methods below map to message variants on the WebSocket. The shape is sketched as a `.proto` for clarity, but the wire is **JSON frames + capabilities-negotiated V1/V2 variants**, not gRPC.
+
+```proto
+service Agent {
+  rpc Health    (HealthRequest)       returns (HealthResponse);
+  rpc Configure (ConfigureRequest)    returns (ConfigureResponse);  // inject session ctx, env, egress JWT
+  rpc Exec      (ExecRequest)         returns (stream ExecChunk);   // streaming stdout/stderr/exit
+  rpc Upload    (stream UploadChunk)  returns (UploadResponse);
+  rpc Download  (DownloadRequest)     returns (stream DownloadChunk);
+  rpc Signal    (SignalRequest)       returns (SignalResponse);     // SIGINT / SIGTERM / SIGKILL
+  rpc Shutdown  (ShutdownRequest)     returns (ShutdownResponse);   // drop caches → SIGTERM → wait → SIGKILL
+  rpc ToolCall  (ToolCallRequest)     returns (stream ToolChunk);   // MCP-tool semantics translated by L4
+}
+```
+
+**WebSocket passthroughs** are routed through a **sibling port by default** (one passthrough socket per stream), so the data-plane WS does not have to multiplex CDP / ttyd binary frames alongside `Agent.*` RPC frames. The same-port variant ("one socket per sandbox") stays available as an option if a future deployment needs to minimize listener count, but Phase 7 ships the sibling-port shape.
+
+- `WS /v1/cdp` — bidirectional CDP proxy to local Chromium; L4 shovels frames opaquely.
+- `WS /v1/tty` — ttyd-equivalent terminal stream.
+
+The agent **does not** speak MCP. MCP semantics live in L4's gateway. L4 receives `tools/call` from the user, decides which sandbox owns the session, and calls `Agent.ToolCall`. This keeps the user-facing wire (MCP) decoupled from internal RPC evolution.
+
+## Capabilities negotiation (V1/V2)
+
+The server's first frame on each connection advertises capabilities via a `ConnectionCapabilities` message:
+
+```json
+{
+  "type": "ConnectionCapabilities",
+  "supports_traces": true,
+  "supports_zstd":   true,
+  "protocol_version": 2
+}
+```
+
+Old clients ignore unknown fields and stay on V1 message variants. New clients opt into V2, zstd compression on server-to-client frames, and trace events. This lets the agent protocol evolve without breaking older sandboxes still in flight.
+
+## PID 1 hygiene (Phase 7 mandatory)
+
+The agent is the init process inside the sandbox. These primitives are mandatory together — none of them works alone:
+
+- **`SIGCHLD` reaping.** Wait on the signalfd or libc `signal()` and reap zombies. Without this, fork-heavy workloads (sub-agent CLIs, shell scripts) leak PIDs until cgroup limits trip.
+- **`SIGTERM` propagation.** L3's `/shutdown` POST or a connect-side `Shutdown` RPC drains via: page-cache drop → SIGTERM to the workload process group → grace-period wait → SIGKILL escalation. The two-phase shape is the standard OOM-killer pattern.
+- **`PR_SET_DUMPABLE=0` post-init.** Disables core dumps and blocks `/proc/<pid>/mem` reads from other processes — even from inside the same UID. Cheap, prevents an entire class of "ptrace the agent to steal session JWT" attacks.
+- **`agent-killed` audit flag.** A per-child boolean that distinguishes "agent killed this" (timeout, OOM, signal RPC) from "kernel killed this" (cgroup OOM, external SIGKILL). Removes ambiguity from the audit log without parsing exit codes.
+- **Env-var scrub before fork.** Strip names matching `_TOKEN`, `_SECRET`, `_PASSWORD`, `API_KEY` from the child env unless the configure-time policy explicitly passes them through. Cross-link to [antipattern A1].
+
+## What L1 does NOT do
+
+- **Authenticate users.** L4 does. L1 trusts whoever can reach its port — network policy ensures only L3 can.
+- **Authenticate L3 — for now.** Phase 7+ may add **Ed25519 JWT bound to `container_name`** read from `/container_info.json`. Pre-Phase-7+ the network boundary alone is the trust boundary. **Document this loudly; do NOT add a fake bearer token that lulls operators.**
+- **Persist state across sessions.** L3 owns the sandbox lifecycle and any volume binding.
+- **Manage its own lifecycle.** It runs until killed; L3 decides when.
+- **Hold long-lived secrets.** Secrets arrive via `Configure` (per-session, short-lived). Rotated by L4's secret broker. See [07-security.md](./07-security.md).
+
+## Today's transitional L1 (Python entrypoint + MCP server in image)
+
+The current image's entrypoint:
+- Reads env vars.
+- Dynamically generates an MCP config.
+- Starts the MCP server (FastMCP) that the orchestrator talks to via `docker exec` and Docker streams.
+
+This works for the PoC and stays through Phases 1–6. It blocks two things:
+- **microVM runtimes** — no vsock transport in the current setup.
+- **Smaller, harder-to-RCE surface** — Python + Playwright + skills is a big attack surface inside the sandbox.
+
+Phase 7 replaces this with the Rust agent.
+
+## Future Rust agent — design notes
+
+- **Static-PIE binary**, `musl` target, x86-64 + arm64. Target size ~4–6 MB (comparable microVM agents land around 4 MB).
+- **Crate footprint** ([ADR-0002](../adr/0002-guest-agent-language-go.md)): `tokio`, `hyper`, `tokio-tungstenite`, `tokio-vsock`, `ring`, `jsonwebtoken`, `clap`, `nix`, `serde_json`. Optional `zstd` if capabilities negotiation enables it. No `chromedp` equivalent — see CDP note below.
+- **PID 1 hygiene** as above (`SIGCHLD`, `SIGTERM`/`SIGKILL` chain, `PR_SET_DUMPABLE=0`, env-scrub).
+- **Process model:** spawn workloads as child process groups; stream stdout/stderr as `ExpectStdOut`/`ExpectStdErr` frames; track exit code; emit `ProcessExited` / `ProcessTimedOut` / `ProcessOutOfMemory` terminal states (mutually exclusive).
+- **Cgroup-aware OOM monitor.** Per-container OOM watchdog polls cgroup memory at 100 ms; adopts orphans before scanning; two-phase kill (signal → wait → escalate). Replaces our current reliance on Docker's default OOM policy.
+- **CDP proxy.** Two options for Phase 7 research:
+  - Use [`chromiumoxide`](https://github.com/mattsse/chromiumoxide) (Rust-native CDP client) and let L1 drive Chromium.
+  - **Raw WebSocket pass-through** to Chromium's `/devtools/browser` endpoint — L4 (and L1) never parse CDP frames. Simpler, smaller agent. Aligns with ADR-0008's "L4 shovels frames opaquely" stance.
+- **MCP tool execution.** A small dispatch layer above the data-plane WS — see "MCP tool execution inside L1" below.
+- **No HTTP bearer auth on the data plane** until Phase 7+ Ed25519 JWT lands. Network policy is the trust boundary in the meantime.
+
+## MCP tool execution inside L1
+
+Today's tools (`mcp_tools.py`):
+- `bash_tool` — exec in a shell.
+- `python_tool` — exec under python3.
+- `create_file` / `str_replace` / `view` — file ops.
+- `view_image` — return base64.
+- `sub_agent` — dispatch to claude / codex / opencode CLI.
+
+Phase 7 maps each to a Rust handler reachable via `Agent.ToolCall`. Sub-agent dispatch (`cli_runtime.dispatch()`) is the heaviest port — its current Python adapter layer per CLI must be re-implemented. Acceptable cost: this is where most "sandbox business logic" lives, and the new home is auditable.
+
+The agent itself does not need to know what's in `skills/`. Skills are mounted as a Tier-2 squashfs and discovered at runtime by the workload, not by L1 ([06-storage.md](./06-storage.md)).
+
+## Open questions (Phase 7 research must answer)
+
+- `chromiumoxide` vs raw CDP WebSocket passthrough — pick one, justify, document.
+- ttyd replacement (Rust-native) vs wrap-in-place (run ttyd as a subprocess and proxy its WS).
+- Transport auto-detect details: presence of `/dev/vsock` plus configure-time hint, or a CLI flag with a sensible default — Phase 7 picks the rule.
+- Connect-rust vs a WS-frame protocol on vsock ([ADR-0008](../adr/0008-internal-grpc-external-rest-mcp.md) Phase 7 gate). Driven by tooling maturity and binary-size measurement on real artefacts.
+- Whether Phase 7 ships JWT auth on day one, or starts network-only and adds JWT in Phase 7.1. Default leans toward the latter — small surfaces first.
+
+## Related
+
+- ADR: [ADR-0002](../adr/0002-guest-agent-language-go.md) (Rust for L1), [ADR-0008](../adr/0008-internal-grpc-external-rest-mcp.md) (transport choice + Phase 7 gate), [ADR-0010](../adr/0010-lambda-as-inspiration-not-runtime.md) (Lambda framing).
+- Research: [`research/02-e2b-infra.md`](../research/02-e2b-infra.md) (`envd` comparison).
+- Antipatterns: A1 (secret leakage in env), and the deny-paths list (`.git/hooks/*`, `.bashrc`, `.mcp.json`, `.claude/`) enforced via [`07-security.md`](./07-security.md).
+
+## Source
+
+- Internal design notes — Layer 1 architecture and the agent protocol contract.

package/docs/future-architecture/architecture/06-storage.md

@@ -0,0 +1,134 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 06 — Storage
+
+> Four-tier model (carried over from the old `docs/requirements/k8s-architecture.md` and elevated to a layer-agnostic spec).
+> Applies regardless of L2 runtime or L3 provider.
+
+## The four tiers
+
+| Tier | What | Mode | Lifetime | Backend |
+|---|---|---|---|---|
+| **1. Image layers** | OS, runtimes, guest agent | RO | per release | OCI registry (cached on host); sealed `squashfs` block disks for the binaries / skills split once Phase 9 lands |
+| **2. Skills** | AI capability bundles (`skills/`) | RO | per release, immutable | Object store (S3) as squashfs blobs; **materialized at provisioning, not runtime** (no hot-reload) |
+| **3. Workspace home** | `/home/assistant` per session | RW | per session, ephemeral | **CoW snapshot of golden rootfs** (qcow2 backing / dm-thin / ZFS clone) on Kata/CH; tmpfs / overlayfs on sysbox/runc. **Never PVC** (see [A37](../antipatterns.md#a37--pvc-for-sandbox-session-workspace)) |
+| **4. User data** | uploads, outputs, tool results | RW | per tenant | S3-compatible object storage, reached via a FUSE client speaking file-ops to a host-side storage broker; **no S3 credentials inside the guest** (session-token auth) |
+
+## Tier 1 — Image
+
+- Standard OCI image. Built once per release. Pulled to nodes via image cache.
+- Includes the guest agent binary (today: Python entrypoint; Phase 7+: Go binary).
+- **Signed with cosign** ([07-security.md](./07-security.md)); admission controller verifies signature.
+- **Immutable reference by digest, never tag** in production templates.
+
+## Tier 2 — Skills
+
+Current state: skills are baked into the image (`/usr/local/share/skills/...`).
+
+Target state (Phase 3):
+- Each skill packaged as a `.squashfs` blob at release time, pushed to S3.
+- Sandbox manifests reference skills by content-hash (`SkillRef`).
+- Mounted RO into the sandbox via squashfuse / kernel squashfs (decision deferred to Phase 3 research — needs `CAP_SYS_ADMIN` for kernel mount, doesn't for squashfuse; sandbox cap surface matters).
+- Drops the current ZIP cache; immutability contract guarantees "skill v1.2.3 is bit-identical everywhere".
+
+Benefits:
+- Skill updates without rebuilding the sandbox image
+- Multi-version coexistence (template A pins skill v1; template B pins v2)
+- Smaller image (skills move out)
+
+## Tier 3 — Workspace home
+
+- `/home/assistant` is the AI agent's working directory. **Always ephemeral.** Vanishes when the sandbox dies.
+- **Compose / k8s today (sysbox, runc):** tmpfs or overlayfs over the image layer.
+- **Phase 9 target (Kata + CH / FC):** **CoW snapshot of a golden rootfs image** at the storage layer — `qcow2` backing files, `dm-thin` snapshots, or ZFS `clone`. This is an industry-observed production-sandbox pattern. Per-session ext4 deltas live on the snapshot; the delta is discarded at session end. The golden image is shared and untouched.
+- **No PVC for the session workspace tier in any template.** RWO PVC is rejected — CoW snapshot is cheaper, faster, and gives stronger reset-on-spawn guarantees with no claim controller, no quota controller, no garbage collection. See [A37](../antipatterns.md#a37--pvc-for-sandbox-session-workspace) for the locked-decision rationale. "Continue yesterday's session" is served by Tier 4 (S3) — the workspace re-binds to the same `filesystem_id` prefix on the next VM, no PVC needed.
+- **Per-VM soft cap.** Phase 9 templates set ext4 `resuid=65534,resgid=65534` so reserved blocks are claimable by no one, yielding a cheap per-VM ENOSPC ceiling without a quota daemon. Phase 3 / 5 can ship with a plain 10 GiB volume.
+
+## Tier 4 — User data
+
+- Three logical buckets per tenant: `uploads/` (user → sandbox), `outputs/` (sandbox → user), `tool-results/` (intermediate artifacts surfaced in UI).
+- **Backend:** S3-compatible. Production: AWS S3 / GCS / R2 / Ceph RGW. Local PoC: MinIO in `docker-compose.yml`.
+- **Broker model (the object-store credential is never in the guest).** The guest mounts a FUSE filesystem that speaks a file-operation interface to a host-side storage broker; the broker is the object-store client and signs its own backend requests. The guest never speaks the object-store protocol and never holds an STS token. This is the canonical model in [`02-trust-boundaries.md`](../../architecture/02-trust-boundaries.md) §2 zone 3 / §7.1 and [NFR-SEC-25](../../architecture/manifesto/02-nfrs.md), and matches Daytona's runner-as-S3-client volume model.
+- **Guest-side FUSE client.** A FUSE backend that speaks the broker's file-RPC — either a custom thin backend or a forked FUSE client. Stock `rclone mount` straight to S3 (70+ backends, VFS cache) is the *interim PoC shortcut* only, and only where the guest is trusted; it is not the target, because it puts the object-store credential and protocol in the guest.
+  - `mountpoint-s3` — AWS-native, fastest, **sequential-write-only**; usable behind the broker, rejected as a guest-facing primary.
+  - `geesefs` — better random-write than mountpoint-s3, smaller backend set.
+- **Backend credential:** held by the broker, never the guest. Short-lived **STS scoped-session** credentials minted per session, locked by inline session policy to the bucket-prefix the `filesystem_id` names ([07-security.md](./07-security.md)). Not static keys. The broker's backend leg traverses the Egress trust-edge allow-list-only (no TLS termination), so the request signature stays intact.
+- **Lifecycle policy** at the S3 layer replaces the current `find /tmp -mtime` cleanup cron.
+
+## Mounts spec on the sandbox
+
+The (planned) `SandboxTemplate` will declare its mounts; the provider (L3) materializes them. Target shape (prospective schema — not implemented today):
+
+```yaml
+mounts:
+  - type: image                       # Tier 1 — implicit
+  - type: skill
+    ref: sha256:abcdef…               # Tier 2 — content-addressed
+    path: /usr/local/share/skills/pptx
+    mode: ro
+  - type: workspace
+    persistence: ephemeral            # only "ephemeral"; PVC rejected (A37)
+    backend: cow-snapshot             # prospective Phase 9 field, not in schema today: qcow2 | dm-thin | zfs-clone; overlayfs (sysbox/runc)
+    path: /home/assistant
+  - type: user-data
+    backend: s3
+    bucket: tenant-{tenant_id}-data
+    prefix: sessions/{session_id}/
+    path: /mnt/user-data
+    mode: rw
+```
+
+## What changes per phase
+
+| Phase | Storage change |
+|---|---|
+| 1 | None — extract provider interface only |
+| 2 | None directly; provider learns mount specs but Docker still binds local fs |
+| 3 | MinIO into Compose; `S3_*` config; FUSE sidecar pattern; squashfs skill blobs |
+| 4 | Storage broker holds the backend credential (per-session STS, not static keys); guest speaks file-RPC to the broker and holds only a `filesystem_id` handle |
+| 5 | K8s provider keeps Tier 3 ephemeral (tmpfs / overlayfs on sysbox); no PVC for sandbox session workspace ([A37](../antipatterns.md#a37--pvc-for-sandbox-session-workspace)); FUSE pattern carried to pods |
+| 8 | virtio-fs replaces FUSE on kata-ch (faster, kernel-level) |
+| 9 | Tier 3 = CoW snapshot of golden rootfs (qcow2 / dm-thin / ZFS) on Kata templates; ext4 `resuid=65534` per-VM ceiling; sealed `squashfs` disks for binaries / system skills |
+
+## Block-device tooling swap (microVM templates, Phase 10)
+
+Once the snapshot-pool pattern lands (internal design note), Tier-1 and Tier-2 content stops being "OCI layers pulled at spawn" and becomes **block devices the host swaps at resume**. The L1 agent's job is to remount them when the host signals readiness via `POST /mount_root` on its control server.
+
+Layout per session (Firecracker / Cloud Hypervisor microVM):
+
+| Device | Content | Mode | Lifetime |
+|---|---|---|---|
+| `vda` | per-tenant root overlay on a shared template base (ext4) | RW | per session |
+| `vdb` | Tier 2 skills (squashfs of `/opt/skills`) | RO | per release |
+| `vdc` | Tier 1 runtime/payload (squashfs of `/opt/<runner>`) | RO | per release |
+| Tier-4 mounts | rclone-FUSE-in-VM (interim PoC) | RW (where applicable) | per tenant |
+
+Per-resume sequence on the L1 side (the host does the device swap first, then calls `/mount_root`):
+
+1. `drop_caches` — page cache references files from the frozen rootfs that no longer exist.
+2. Remount devtmpfs.
+3. Mount `/dev/vda` as ext4, `pivot_root` into it.
+4. Mount `/dev/vdb`, `/dev/vdc` squashfs overlays.
+5. `clock_settime()` (the wall-clock was frozen).
+6. Trigger CRNG reseed (see [07-security.md](./07-security.md) snapstart-restore hardening).
+7. Drop `CAP_SYS_RESOURCE`.
+8. Start accepting WS connections.
+
+The pattern is the standard snapshot-pool block-device-swap approach. Tier-2 stays as squashfs in both the OCI-layer world and the block-device world — the format is the same, only the delivery channel changes. **Skills built before Phase 10 are forward-compatible.**
+
+Implication for the release pipeline (Phase 10): tooling produces both an OCI image *and* a paired set of `vdb` / `vdc` squashfs blobs from the same source. Both are signed; both are referenced by content hash from templates. Phase 9 templates use only OCI; Phase 10 templates may use either, gated on `snapstart_compatible` ([09-templates.md](./09-templates.md)).
+
+## Explicit non-goals
+
+- **No RWX (ReadWriteMany).** Single-writer patterns only. Avoids EFS/Filestore complexity and consistency surprises.
+- **No proprietary CSI drivers.** S3-compatible API only.
+- **No custom storage *transport*.** The mount substrate uses existing FUSE / virtio-fs / CSI building blocks — we do not write a block protocol. The storage *broker* (credential custody + object-store client + per-session scope) is a deliberate component, not a transport; it is the canonical model, not a workaround ([`02-trust-boundaries.md`](../../architecture/02-trust-boundaries.md) §2 zone 3).
+- **No PVC for the sandbox session workspace (Tier 3).** Locked decision — see [A37](../antipatterns.md#a37--pvc-for-sandbox-session-workspace). CoW snapshot at the storage layer replaces it. PVC remains the right primitive for stateful platform services (PostgreSQL, Redis, Prometheus, etcd) — none of which our sandbox runtime hosts.
+- **No S3 credentials inside the sandbox guest.** Tier 4 Phase 4 target end-state: guest carries a `filesystem_id` session token, broker / storage proxy holds S3 keys server-side.
+- **No skill hot-reload.** Skills materialize at provisioning, are immutable for the lifetime of the VM.
+
+## Source
+
+- `docs/requirements/k8s-architecture.md` (pre-rename — original 4-tier spec)
+- Internal design notes (storage section)

package/docs/future-architecture/architecture/07-security.md

@@ -0,0 +1,194 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 07 — Security
+
+> Threat model, secret-rotation strategy, egress controls, image signing, audit.
+> Derived from internal security notes, adapted to our stack.
+
+## Threat model
+
+**We protect against:**
+- Curious users probing what's reachable from the sandbox
+- "Confused agent" — LLM hallucinating dangerous commands
+- Prompt injection coercing the agent into exfil / lateral movement
+- Direct adversaries with valid credentials
+- Compromised dependencies (npm, pip) inside the sandbox
+
+**We do NOT protect against:**
+- Compromised control plane (L4) — if L4 is owned, game over by design
+- Host kernel CVEs (assume patches applied)
+- Side-channel attacks on shared cores (Spectre / Meltdown — kernel mitigations assumed)
+- Hardware attacks (datacenter-level threat)
+- Determined DoS by exhausting resources (mitigated by quotas, not prevented)
+
+## Isolation responsibility per layer
+
+| Layer | Trust posture | Primary control |
+|---|---|---|
+| L1 (agent) | Trusted by L4 (we wrote it); untrusted by host | Small surface, no auth (network-policy-enforced) |
+| L2 (runtime) | **Primary security boundary** | Hypervisor / kernel isolation |
+| L3 (provider) | Trusted infrastructure | NetworkPolicy, ResourceQuota, PSA, RBAC |
+| L4 (control plane) | Most-trusted | Std hardening: mTLS, secrets, RBAC, WAF |
+
+L2 carries the load for untrusted workloads. See the runtime matrix in [04-layer2-runtimes.md](./04-layer2-runtimes.md).
+
+## Secret management
+
+### Today (transitional)
+- Anthropic API key, GitLab token, vision API key injected as env vars at container create time.
+- Static for container lifetime; rotation requires container restart.
+- Stored in k8s `Secret` objects (when on Helm) or `.env` files (Compose).
+
+### Target (Phase 4 ships, Phase 6 expands)
+
+- **Secret broker** lives in L4. Responsibilities:
+  1. Read static long-lived secrets from the backing store (AWS Secrets Manager / GCP Secret Manager / Vault / k8s `Secret`) — operator concern.
+  2. **Mint short-lived, scoped credentials per session:**
+     - Anthropic / vision API keys: same-key issuance (Anthropic doesn't STS) — but rotated on schedule and injected via `/v1/configure` so rotation never requires restart.
+     - S3: per-session STS tokens (AWS STS / MinIO STS) scoped to `bucket/sessions/{session_id}/*` only.
+     - Egress JWT: signed per-session, encodes allowed destinations + expiry.
+  3. **Rotate** static keys on a schedule (≤ 90 days) without downtime.
+  4. **Revoke** on session end.
+
+- **In the sandbox:** secrets arrive via `POST /v1/configure`. Never baked into image. Never logged.
+- **Rotation pattern:** L4 calls `/v1/configure` again with new short-lived creds; sandbox swaps in place.
+
+### Image signing
+
+- All sandbox images signed with [cosign](https://github.com/sigstore/cosign).
+- Admission controller (k8s) verifies signature; rejects unsigned or invalid.
+- Templates reference images by **digest** (`sha256:...`), never tag.
+
+## Network egress
+
+- **Default-deny.** No direct internet from any sandbox.
+- **Egress proxy** mediates every outbound connection.
+  - Sandbox carries a per-session JWT in egress requests.
+  - Proxy validates JWT signature, checks destination against the JWT-encoded allowlist, checks expiry.
+  - Logs every request (audit).
+- **Reference implementation:** [`Michaelliv/agentbox`](https://github.com/Michaelliv/agentbox) — port to Go for production (Phase 8).
+- **Allowlist sources:** template-level baseline (e.g., `pypi.org`, `registry.npmjs.org`) + session-level additions (the agent's running task scope).
+
+## Network ingress (to sandbox)
+
+- Sandboxes are **not** publicly addressable.
+- Only L3 (provider) reaches L1's port — enforced by k8s `NetworkPolicy` or Docker network isolation.
+- The agent itself does **not** authenticate requests — defense is exclusively network-policy-level. Documented loudly to prevent "let's add an extra auth check" cargo-cult that misleads operators.
+
+## Per-runtime residual risks (one-line each)
+
+- **runc/sysbox:** shared host kernel → kernel CVE escapes the sandbox.
+- **gVisor:** Sentry bugs (~500K LoC Go); passthrough syscalls.
+- **kata-fc / kata-ch:** Firecracker / CH bugs (Rust, ~50-80K LoC); KVM bugs; side-channels on shared CPUs.
+
+See internal security notes for CVE history references.
+
+## Mandatory deny paths inside the workspace
+
+Even with full L2 isolation, the agent itself must refuse to write a small set of paths that are vectors for persistent shell takeover or self-exfiltration. The list is **always-on, regardless of template configuration** — following an industry-observed local-sandbox deny-path pattern:
+
+| Path / glob | Why blocked |
+|---|---|
+| `.bashrc`, `.bash_profile`, `.zshrc`, `.zprofile`, `.profile` | Persistent shell hijack — survives session, exfils on next user shell |
+| `.gitconfig`, `.gitmodules` | Persistent git hooks via `[core] hooksPath`; submodule URL injection |
+| `.git/hooks/*` | Hook execution on every git operation |
+| `.mcp.json` | Sub-agent MCP server hijack |
+| `.claude/`, `.claude-code/`, `.codex/`, `.opencode/` | Sub-agent CLI config / credential hijack |
+| `.vscode/`, `.idea/` | IDE-driven code execution on user re-open |
+| `.ssh/`, `.aws/`, `.gcp/`, `.kube/` | Credential exfil targets |
+| `$PATH` directories owned by the user (`~/.local/bin/*`, `bin/*`) | Shadow-binary injection |
+
+Enforcement: a Rust-side path-canonicalization check on every write in the L1 agent's file-ops handlers. Symlink targets are resolved before the check (standard symlink-attack defense). Phase 7 implements; the antipattern reference is A1 / C-series.
+
+## Graceful-shutdown protocol
+
+When L3 needs to stop a sandbox — drain for upgrade, end-of-session, idle TTL — the protocol is **four steps, in order**. Skipping steps causes data loss (atomic-rename caught mid-flight) or audit-log gaps:
+
+1. **Drop the page cache** inside the sandbox (echo 3 → drop_caches via the L1 control endpoint). Forces dirty data to disk; pending writebacks complete or fail visibly.
+2. **`SIGTERM` to the workload process group.** Give it a grace period (default 10 s, template-tunable).
+3. **Wait** for child reaper to confirm exit, or timeout.
+4. **`SIGKILL`** to anything still running. Container teardown follows.
+
+The L1 agent exposes this as `POST /shutdown` on the control plane ([05-layer1-guest-agent.md](./05-layer1-guest-agent.md)) and as a connect-side `Shutdown` RPC on the data plane. The two paths share the same state machine; whichever fires first wins.
+
+## Defense-in-depth: `memfd_create` for the agent binary (Phase 9+)
+
+Optional hardening for the microVM tiers: the L1 agent binary is loaded into a `memfd` at boot and the on-disk copy is unlinked. An attacker who lands code execution inside the sandbox cannot read the agent binary from disk to study it — `/proc/self/exe` resolves to a memory-only file descriptor.
+
+This is purely defense-in-depth (the binary's source-equivalent is public). Cheap to implement once the agent is a static Rust binary; **Phase 9 nice-to-have, not Phase 7 must.**
+
+## Snapstart-restore hardening (Phase 10)
+
+When a sandbox resumes from a frozen Firecracker snapshot, the guest is **stale by design** — the kernel knows it forked but userspace does not. Without explicit re-initialization, userspace RNGs reseed from snapshotted state (worst-case identical seeds across restores), wall-clock is wrong by minutes-to-days, and any cached page references point into a rootfs that was just swapped underneath.
+
+Mandatory on every restore (standard snapshot-restore hardening):
+
+| Action | Why |
+|---|---|
+| `drop_caches` after device hot-swap | Page cache references the frozen rootfs |
+| Devtmpfs remount | Device-node mapping changed |
+| `pivot_root` onto fresh rootfs | The frozen rootfs is stale |
+| `clock_settime()` to current host time | Wall-clock was frozen |
+| **CRNG reseed** (`getrandom`-style force) | Userspace RNGs (OpenSSL, glibc arc4random) don't notice the fork — without reseed, two sandboxes restored from the same snapshot can generate identical "random" values |
+| Drop `CAP_SYS_RESOURCE` | Held only for init |
+| Re-run env-var scrub | Template env may have changed since the template was frozen |
+
+Template-build-time hardening:
+- `init_on_free=1` kernel cmdline — zeroes freed pages before reuse so a fresh resume can't read template-VM secrets out of recycled memory.
+- Template image built with **no `CAP_SYS_RESOURCE` retention** logic — the cap is held only during init.
+
+Until Phase 10 ships, the L1 agent's `/mount_root` endpoint is **not exposed**. Adding it pre-Phase-10 is a footgun (untested resume path on a sandbox that was never frozen).
+
+## Sandbox hygiene
+
+- **No reuse between tenants.** When a session ends, sandbox is destroyed. Never returned to the pool of another tenant.
+- **Per-sandbox ServiceAccount** with empty RBAC (k8s) — sandbox can't enumerate the cluster.
+- **`securityContext`:** `runAsNonRoot` (where the runtime allows — note: sysbox/kata enable safe root-in-sandbox), `allowPrivilegeEscalation: false`, drop ALL capabilities (re-add only needed ones), `seccompProfile: RuntimeDefault`.
+- **`ResourceQuota` + `LimitRange`** per tenant namespace — blast-radius cap.
+
+## Audit log
+
+Mandatory events:
+- Session created / configured / terminated
+- Exec call (cmd hash, exit code, duration — **not** stdout/stderr verbatim)
+- Egress request (destination, decision, JWT id — **not** body)
+- Secret rotated
+- Admission decision (template assigned)
+- Runtime error / health-degraded
+
+Forbidden in logs:
+- stdout / stderr verbatim (may contain secrets)
+- Env var values
+- File contents
+- HTTP body through proxy
+
+Retention: **≥ 90 days**. Append-only sink. See [10-observability.md](./10-observability.md).
+
+## Compliance posture (informational, not committed)
+
+| Standard | Posture |
+|---|---|
+| PCI-DSS 2.4 (isolation) | `kata-ch` satisfies "logical separation" in spirit — get auditor sign-off per deployment |
+| HIPAA | Same as above for PHI; encrypt persistent storage with per-session keys; PHI must not appear in audit logs |
+| GDPR | Ephemeral by default; explicit DPA needed if persistence enabled |
+| SOC 2 | Audit logging here aligns with SOC 2 evidence requirements |
+
+## What ships, when
+
+| Phase | Security change |
+|---|---|
+| 1–3 | No security change (refactor + storage) |
+| 4 | **Secret broker** + per-session STS + key rotation |
+| 5 | NetworkPolicy default-deny + ResourceQuota + empty-RBAC SA in Helm chart |
+| 6 | mTLS L4 ↔ L3; OIDC for admin UI |
+| 7 | Rust agent shrinks attack surface; signed image enforcement |
+| 8 | Egress proxy + audit-log pipeline + 90 d retention **(prereq for any untrusted tier)** |
+| 9 | `kata-ch` / `kata-fc` raise the isolation ceiling — untrusted tier opens, gated on Phase 8 |
+| 10 | Snapshot/restore + post-restore hardening (CRNG reseed, `init_on_free=1`, `CAP_SYS_RESOURCE` drop); KMS-backed per-session encryption keys for persistent storage |
+
+## Source
+
+- Internal security notes
+- [`docs/future-architecture/references.md`](../references.md) (`agentbox`, `cosign`)
+- [ADR-0006](../adr/0006-no-agpl-no-bsl-dependencies.md) (license hygiene)