hack-house/docs/spec-collaborative-sandbox.md

# cmd-chat → Collaborative Sandbox Sessions — Spec

> **Status:** Draft v1 · **Date:** 2026-05-30
> **Scope:** Evolves `cmd-chat` from an E2E-encrypted terminal chat into a
> multi-user collaborative session with a shared, sandboxed Linux environment.
> **Baseline reviewed:** `cmd_chat/` @ `main` (commit `dc1b5e5`).

---

## 0. Decisions locked (from product owner)

| # | Decision | Choice |
|---|----------|--------|
| A | Client language / TUI | **Rust + ratatui client**, **Python Sanic server unchanged**. Stable JSON-over-WebSocket wire protocol between them. |
| B | Sandbox backend | **Pluggable backend interface. Multipass default, Docker secondary.** |
| C | Shared-terminal model | **Single shared PTY** (collaborative, tmux-share style). Permissions = who may type. |
| D | Permission model | **Two layers:** app-level RBAC (owner/admin/member) **+** real VM unix users & `sudo` delegation. |

---

## 1. Vision & goals

Turn a cmd-chat "room" into a **shared workspace**: up to 4 people (infra for more)
join one encrypted session, chat, drop files/dirs into a shared space, and
collaboratively drive **one sandboxed Linux box** they can type commands into and
run scripts in — with real Linux permissions and a clear owner who can delegate
superuser rights.

### Goals
- Preserve the existing security guarantees: **zero-knowledge server**, **E2E
  Fernet encryption**, **SRP auth**, **RAM-only server**, **no IP leaks**.
- 4 concurrent users per session today; capacity is a single config constant, not
  an architectural limit.
- A genuinely nice **ratatui** TUI: panes, themes, custom colour/layout config.
- One-command launch of a **disposable sandbox** (Multipass VM or Docker
  container) that the whole room shares.
- File **and directory** upload into the shared session.
- Linux-grade permissions inside the sandbox + app-level roles governing the
  session itself.

### Non-goals (v1)
- Persistence / chat history survival across server restart (server stays RAM-only).
- Federation / multiple rooms per server process (one room per `serve`, as today).
- Running the sandbox *on the server* (see §4 — it runs on the initiator's client).
- Mobile / GUI clients. Terminal only.
- Multi-VM topologies. One shared sandbox per session.

---

## 2. Baseline architecture (what exists today)

```
CLIENT (python+rich)              SERVER (sanic, RAM-only)            CLIENT
  SRP handshake  ───────────────► /srp/init, /srp/verify ──────────►  (relay only)
  HKDF(pw,salt) → room_key                                            server NEVER
  Fernet(room_key) encrypt        WSS /ws/chat  (broadcast)           sees plaintext
  ──── ciphertext ──────────────► ConnectionManager.broadcast ─────►  decrypt(room_key)
  file xfer = _ft JSON over the same encrypted message channel (64KB chunks, SHA-256)
```

- **Server modules:** `factory.py` (DI/wiring), `server.py` (TLS + run),
  `routes.py`, `views.py` (SRP + ws + admin), `managers.py`
  (`ConnectionManager`), `stores.py` (`MessageStore`, `UserSessionStore`),
  `srp_auth.py`, `models.py`, `helpers.py` (`RateLimiter`, `get_client_ip`).
- **Client:** single `client.py` — `Client` class, asyncio `receive_loop` +
  `input_loop`, rich console clear-and-reprint, `_ft` file-transfer protocol.
- **Wire types today:** `init`, `message`, `user_left`. File transfer rides inside
  `message.text` as JSON beginning `{"_ft": …}` (offer/accept/reject/chunk/done).

### What we keep vs. change
| Component | v1 plan |
|---|---|
| Sanic server, SRP, TLS, RateLimiter | **Keep**, extend with new relay message types + capacity check. |
| `ConnectionManager` broadcast | **Keep**; add `broadcast(exclude_user)` usage and roster events. |
| RAM-only / zero-knowledge | **Keep** — non-negotiable; everything new also rides as ciphertext. |
| Python rich client | **Replace** with Rust ratatui client (protocol-compatible). |
| File transfer `_ft` protocol | **Keep & extend** for directories (tar stream). |

---

## 3. Target architecture (high level)

```
┌─────────────────────────── SESSION (one room) ───────────────────────────┐
│                                                                           │
│  OWNER CLIENT (Rust/ratatui)            SERVER (Sanic, dumb relay)         │
│  ┌───────────────────────────┐          ┌─────────────────────────┐       │
│  │ ratatui UI                │          │ SRP / TLS / rate-limit  │       │
│  │ chat | roster | sandbox   │◄──WSS───►│ ConnectionManager       │◄──┐   │
│  │ E2E Fernet(room_key)      │  cipher  │ broadcast(opaque bytes) │   │   │
│  │ ┌───────────────────────┐ │  text    │ Stores (RAM only)       │   │   │
│  │ │ SANDBOX BROKER (local)│ │          └─────────────────────────┘   │   │
│  │ │  Multipass | Docker   │ │                                        │   │
│  │ │  PTY ⇄ encrypted frames│ │     MEMBER CLIENTS (Rust/ratatui) ─────┘   │
│  │ │  RBAC + unix-user map  │ │     decrypt → render shared PTY pane       │
│  │ └───────────────────────┘ │     send keystrokes (if permitted)         │
│  └───────────────────────────┘                                            │
└───────────────────────────────────────────────────────────────────────────┘
```

**Key principle — the server stays zero-knowledge.** The sandbox does **not** run
on the server (the server has no room key and must never see plaintext). Instead:

- The **client that launches the sandbox** (normally the owner) hosts a local
  **Sandbox Broker** that spawns the Multipass VM / Docker container and owns its
  PTY.
- PTY output is Fernet-encrypted with the room key and relayed through the server
  as opaque ciphertext — identical trust model to file transfer.
- Keystrokes from other clients travel encrypted to the broker, which is the
  **single policy-enforcement point** (it decides who may type / `sudo` / upload).

This is the only design that satisfies *both* "shared sandbox" *and* "server can't
read anything." It is documented as a constraint, not an accident.

---

## 4. Wire protocol (v2)

### 4.1 Versioning & envelope
- Add a top-level relay type **`hello`** exchanged right after `init` carrying
  `protocol_version` (`2`). Server relays it untouched. Clients negotiate down /
  warn on mismatch.
- All new collaborative payloads ride **inside the encrypted channel** the same way
  `_ft` does: the cleartext-to-server is a `message` frame whose decrypted `text`
  is JSON with a discriminator key. We generalise `_ft` to a namespaced envelope:

```jsonc
// decrypted application payload (server only ever sees the ciphertext of this)
{
  "v": 2,
  "kind": "chat" | "file" | "dir" | "sbx" | "perm" | "presence",
  "id":  "uuid",            // correlation id
  "from":"username",        // asserted by sender, validated by broker for sbx/perm
  "ts":  "iso8601",
  "body": { /* kind-specific */ }
}
```

> Rationale: keeps the server's relay role unchanged (still just `message`
> broadcast of opaque bytes) while giving the app a clean, extensible schema.
> Existing `_ft` messages map onto `kind:"file"`.

### 4.2 New server-visible relay types (cleartext metadata only)
The server learns nothing it shouldn't; these carry no plaintext content.
- `roster` — authoritative presence list + capacity (server-generated; see §5).
- `capacity_full` — sent on connect rejection (HTTP 409 / ws close code).
- Everything else stays `message` (opaque ciphertext).

### 4.3 Sandbox sub-protocol (`kind:"sbx"`, encrypted, broker-authoritative)
| `body.op` | Direction | Meaning |
|---|---|---|
| `launch` | client→broker | request to start sandbox (owner/admin only) |
| `status` | broker→all | `starting`/`ready`/`stopped`/`error`, backend, image, specs |
| `pty_data` | broker→all | base64 PTY output chunk (the shared terminal stream) |
| `pty_input` | client→broker | keystrokes; broker enforces "may type" ACL |
| `resize` | client→broker | cols/rows; broker applies if sender is the active driver |
| `run_script` | client→broker | upload+exec a script in the VM (perm-gated) |
| `stop` | owner→broker | tear down sandbox |

### 4.4 Permission sub-protocol (`kind:"perm"`, broker-authoritative)
| `body.op` | Meaning |
|---|---|
| `grant` / `revoke` | change app role (admin/member) — owner/admin only |
| `sudo_grant` / `sudo_revoke` | add/remove a user from VM sudoers — superuser only |
| `acl` | broker broadcasts the current authoritative ACL snapshot |

---

## 5. Feature 1 — Multi-user sessions (4 now, N later)

**Current state:** `ConnectionManager` already supports arbitrarily many websocket
connections; `username_exists` blocks dup names. No capacity cap, no real roster
broadcast (only `init` snapshot + `user_left`).

**Changes**
1. **Capacity constant** `SESSION_MAX_USERS = 4` in `factory.py` (env override
   `CMD_CHAT_MAX_USERS`). Enforced in `srp_verify` *and* on ws connect:
   reject with `409 Username/Room full` / ws close code `4004` when
   `session_store.count() >= max`.
2. **Authoritative roster.** Server emits a `roster` event (join, leave,
   role-change) so all clients converge on one presence list with roles. Replaces
   the ad-hoc `user_left` patching (kept for back-comp, superseded by `roster`).
3. **`user_joined` event** added (today only `user_left` exists) for live roster.
4. **Infra-for-more:** capacity is data, not code. Document that >4 needs (a) UI
   roster scroll, (b) broadcast fan-out is O(N) per message — fine to low double
   digits; note ceiling in README. No protocol change required to raise the cap.

**Acceptance**
- 5th join attempt to a 4-cap room is cleanly refused with a user-visible reason.
- Roster in every client matches server truth within one broadcast round-trip.
- Raising `CMD_CHAT_MAX_USERS=8` works with zero code changes.

---

## 6. Feature 2 — Rust ratatui client (enhanced + themeable)

**New crate:** `cmd-chat-tui/` (Rust 2021). Talks the v2 protocol to the existing
Sanic server. The Python client remains in-tree as a reference/fallback until the
Rust client reaches parity, then is deprecated.

### 6.1 Crate layout
```
cmd-chat-tui/
  Cargo.toml
  src/
    main.rs            # CLI (clap): connect/serve-shim, flags mirror python
    app.rs             # App state, event loop (tokio + crossterm)
    net/
      srp.rs           # SRP-6a client (crate: srp + sha2) — matches python params
      ws.rs            # tokio-tungstenite WS client
      crypto.rs        # HKDF-SHA256 → Fernet (crate: fernet) room key
      proto.rs         # v2 envelope (serde) types
    ui/
      layout.rs        # ratatui layout regions
      chat.rs          # chat pane (scrollback, msg styling)
      roster.rs        # users + roles + sandbox status
      sandbox.rs       # shared PTY pane (vt100 parse: crate `vt100`)
      input.rs         # input box, command palette (/send /run /grant …)
      theme.rs         # theme model + loader
    sandbox/
      broker.rs        # local PTY broker (owner side) — see §8
      backend.rs       # trait SandboxBackend
      multipass.rs     # default backend
      docker.rs        # secondary backend
    files.rs           # upload (file + dir/tar), SHA-256, chunking
    perms.rs           # client-side ACL view + enforcement hints
  themes/
    default.toml  nord.toml  gruvbox.toml  mono.toml
```

### 6.2 Crypto parity (must match Python exactly)
- SRP-6a, group **RFC5054 / SHA-256**, identity `b"chat"` (matches
  `srp_auth.py`). Verify interop against the live Sanic server early — this is the
  #1 integration risk.
- Room key: `HKDF(SHA256, len=32, salt=room_salt, info=b"cmd-chat-room-key")`
  over the password, then `Fernet(urlsafe_b64(key))` — byte-for-byte as
  `client.py::srp_authenticate`.
- WS auth: `ws_token` echoed from `/srp/verify`; HMAC token already server-side.

### 6.3 UI / layout
Default layout (resizable, ratatui `Layout` constraints):
```
┌ cmd-chat ── room: <name> ── 🔒 E2E ── users 3/4 ──────────────┐
│ ┌─ chat ───────────────────────────┐ ┌─ roster ─────────────┐ │
│ │ 12:01 alice: hey                 │ │ ● alice  (owner,root)│ │
│ │ 12:01 bob:   yo                  │ │ ● bob    (admin,sudo)│ │
│ │ …scrollback…                     │ │ ○ carol  (member)    │ │
│ └──────────────────────────────────┘ │ sandbox: ● ready     │ │
│ ┌─ sandbox  (shared PTY · driver: alice) ─────────────────────┐│
│ │ ubuntu@sbx:~$ ./build.sh                                    ││
│ │ …live vt100 output for everyone…                           ││
│ └────────────────────────────────────────────────────────────┘│
│ > type message  ·  /send /run /sbx /grant  (F2 toggle PTY focus)│
└────────────────────────────────────────────────────────────────┘
```
- **Panes:** chat, roster (with roles + sandbox status), shared PTY, input.
- **Focus model:** Tab cycles panes; `F2` toggles "drive the PTY" (keystrokes go to
  sandbox) vs "chat input". Visible indicator of who currently holds the PTY driver
  token (see §8.3).
- **Command palette** (`/`): `/send`, `/sendd <dir>`, `/run <script>`, `/sbx
  launch|stop`, `/grant <user> <role>`, `/sudo <user>`, `/theme <name>`, `/quit`.
- **vt100 rendering** via the `vt100` crate so real terminal apps (vim, htop) render.

### 6.4 Themes & custom design
- TOML themes in `themes/`, loaded from `$XDG_CONFIG_HOME/cmd-chat/themes/` first.
- Schema: named colours (16 + hex), per-element styles (chat.self, chat.other,
  timestamp, roster.owner, sandbox.border, …), border style, layout ratios
  (chat:roster split, PTY height), and key-bindings overrides.
- `--theme <name>` flag + `/theme` live switch. Ships: default, nord, gruvbox, mono.

**Acceptance**
- Authenticates against the unchanged Sanic server and exchanges chat with a
  Python client (proves crypto + protocol parity).
- vim/htop usable inside the shared PTY pane.
- Switching theme at runtime restyles without reconnect.

---

## 7. Feature 3 — Launchable sandboxed environment (pluggable backend)

### 7.1 Backend abstraction
```rust
trait SandboxBackend {
    async fn launch(&self, spec: &SandboxSpec) -> Result<Handle>;   // create + boot
    async fn attach_pty(&self, h: &Handle) -> Result<PtyPair>;      // master pty
    async fn exec(&self, h: &Handle, argv: &[String], as_user: &str) -> Result<Output>;
    async fn put_file(&self, h: &Handle, dst: &str, bytes: &[u8], mode: u32) -> Result<()>;
    async fn add_user(&self, h: &Handle, name: &str, sudo: bool) -> Result<()>;
    async fn set_sudo(&self, h: &Handle, name: &str, enabled: bool) -> Result<()>;
    async fn stop(&self, h: &Handle) -> Result<()>;                 // destroy
}
```
- **Multipass (default):** `multipass launch`, `multipass exec`, `multipass
  transfer`, `multipass shell` (PTY via `multipass exec -- bash -i` over a pty),
  `multipass delete --purge`. Real VM ⇒ strong isolation, genuine users/sudo.
- **Docker (secondary):** `docker run -d`, `docker exec -it`, `docker cp`,
  `useradd`/`gpasswd`. Faster, weaker isolation; flag the root-in-container caveat.
- Backend chosen via `--sbx-backend multipass|docker` (default multipass), with
  capability probe (which binary exists) and graceful fallback message.

### 7.2 `SandboxSpec`
- image/release (e.g. `24.04` for multipass, `ubuntu:24.04` for docker),
  cpus, mem, disk, name (`sbx-<room>-<short>`), `disposable: true` (purge on stop /
  session end). Defaults sized small (1 cpu / 1G / 5G).

### 7.3 Launch flow
1. Owner/admin runs `/sbx launch` → broker validates RBAC (§9) → `sbx.status:
   starting` broadcast.
2. Broker boots backend, opens PTY, creates VM users for each *current* member
   (owner = sudoer/root, others = standard) — see §9.4.
3. `sbx.status: ready` broadcast with backend/image/specs.
4. Broker streams `pty_data` (encrypted) to all; accepts `pty_input` from the
   permitted driver; everyone watches live.
5. `/sbx stop` (owner) → `stop()` → purge → `sbx.status: stopped`.

### 7.4 Lifecycle & safety
- Sandbox is **disposable**: destroyed on `/sbx stop`, on owner disconnect (grace
  timer), and on server/session end. Nothing persists by default (matches RAM-only
  ethos). A `--keep` flag can opt out for the owner.
- Resource caps enforced via backend spec; reject launch if host lacks resources.
- The broker runs on the **owner's machine**, so the owner is implicitly trusting
  their own host to run the VM — documented clearly.

**Acceptance**
- `/sbx launch` boots a Multipass VM in the owner's client; all members see
  `ready` and live output. Switching `--sbx-backend docker` works unchanged at the
  protocol level.
- `/sbx stop` fully purges the VM/container (verified: `multipass list` clean).

---

## 8. Feature 4 — Shared collaborative PTY

### 8.1 Model
Single shared PTY (decision C). The broker owns one master PTY connected to a
shell in the sandbox. Output fans out to everyone (`pty_data`); input is funneled
from whoever currently holds the **driver token**.

### 8.2 Output path (E2E)
PTY master output → broker reads → base64 → Fernet(room_key) → `message` relay →
all clients decrypt → feed bytes to local `vt100` parser → render sandbox pane.
Server sees only ciphertext. Output is **broadcast to all** including the driver
(so everyone has identical screen state).

### 8.3 Input path & driver token
- "Who may type" is a permission (see §9). Among permitted users, a **single driver
  token** prevents keystroke interleaving.
- Default: token follows last `request-drive` (F2) and auto-releases after N
  seconds idle, or explicit release. Owner can force-grab.
- Non-driver permitted users see a "request drive" affordance; the current driver
  / owner approves (or owner config = open-grab among permitted users).
- Broker is authoritative: it drops `pty_input` from anyone not holding the token.

### 8.4 Resize
- Driver's terminal size drives `resize`; others letterbox/scroll to fit. Broker
  applies `TIOCSWINSZ`.

**Acceptance**
- Two members alternately take the driver token and type; no interleaved garbage;
  all panes show identical output.
- A member without "may type" permission is silently prevented from driving and
  told why.

---

## 9. Features 5 & 6 — File/dir upload + permission model

### 9.1 File & directory upload (feature 5)
Extends the existing `_ft` flow (now `kind:"file"` / `kind:"dir"`):
- **File:** unchanged semantics (offer/accept/chunk/done, 64KB, SHA-256), but a
  shared-session target: accepted files land in the **sandbox shared dir**
  (`/srv/shared`, default) *and/or* local `./downloads/` (user choice on accept).
- **Directory:** `/sendd <dir>` → broker/sender streams a **tar** of the tree as
  `kind:"dir"` chunks (same chunking + a single SHA-256 over the tar). On accept,
  extracted into `/srv/shared/<name>/` in the sandbox (path-traversal-guarded:
  reject entries with `..`, absolute paths, or symlinks escaping root).
- If no sandbox is running, dir/file upload still works peer-to-peer into
  `./downloads/` (parity with today).
- Max sizes: keep 50 MB/file; add `CMD_CHAT_MAX_UPLOAD` and a per-session
  aggregate cap. Files written into the VM get owner = uploader's VM user, mode
  `0644` (dirs `0755`).

**Acceptance**
- `/sendd ./project` puts the tree under `/srv/shared/project` in the VM with
  correct ownership; SHA-256 verified; traversal attack entries rejected.

### 9.2 Permission model — two layers (feature 6)

**Layer 1 — App-level RBAC (session control).** Enforced by the broker (the only
component that can read plaintext and owns the sandbox). Roles:

| Role | Capabilities |
|---|---|
| **owner** | Everything. The initiator. Can launch/stop sandbox, grant/revoke admin, delegate VM superuser, force driver token, kick. Exactly one. |
| **admin** | Launch sandbox, manage members (grant/revoke member-level), approve drive requests, manage uploads. Cannot remove owner. |
| **member** | Chat, request drive, upload (if allowed), use sandbox per VM perms. |

- Owner is whoever ran `serve` / first authenticated as owner (config:
  `CMD_CHAT_OWNER=<username>`; default = first user to connect). Ownership transfer
  via `perm.grant owner <user>` (owner only).
- RBAC changes broadcast as `perm.acl` snapshots so all clients show current roles.

**Layer 2 — Real VM unix users & sudo (filesystem/command control).** Inside the
sandbox, each session member maps to a real Linux account:
- On member join *while sandbox is up*, broker `add_user(name, sudo=role∈{owner})`.
- **Superuser = real root/sudoer.** The initiator's VM user is in `sudo` group.
- **Delegation:** owner runs `/sudo <user>` → `perm.sudo_grant` → broker
  `set_sudo(user, true)` (adds to `sudo` group in VM). `/sudo -r <user>` revokes.
- The shared PTY shell runs **as the current driver's VM user**, so real Linux
  permissions (file ownership, `sudo` prompts) apply naturally — a member without
  sudo who types `sudo apt install` gets denied by the *VM*, not just the app.

> The two layers are complementary: app RBAC decides *who can touch the session and
> the driver token*; unix perms decide *what a command can actually do once typed*.
> Defense in depth — an RBAC bug can't grant root, and a VM-perms bug can't bypass
> session control.

**Acceptance**
- Owner delegates sudo to bob; bob's `sudo` commands now succeed in the VM; revoke
  works (`gpasswd -d`).
- A member demoted from admin immediately loses launch/grant abilities (next
  broker-validated action rejected; `perm.acl` updated in all clients).
- Driver shell runs as the driver's own unix user (verify with `whoami`/`id`).

---

## 10. Security considerations

- **Server remains zero-knowledge.** PTY frames, uploads, perms — all ride as
  Fernet ciphertext inside `message`. The server's job is unchanged (broadcast
  opaque bytes). Re-audit `views.py::chat_ws` to confirm no new plaintext leaks.
- **Broker = trust anchor.** It holds the room key and runs the VM on the owner's
  host. It is the single enforcement point for sbx/perm ops. Document that members
  are trusting the owner's host (where the VM runs).
- **Sender spoofing:** `from` in the envelope is asserted by the sender. For
  chat that's acceptable (today's model). For `sbx`/`perm` ops the broker **must
  bind identity to the ws session** (the `user_id`/`ws_token` already authenticated
  by the server), not to the self-asserted `from`. Add a server-stamped, integrity-
  protected sender id to relayed frames, or have the broker correlate via the
  authenticated channel. **Open item — see §12.**
- **Sandbox escape:** Multipass (VM) >> Docker (container). Default to Multipass;
  warn loudly when Docker is selected. Never run the broker's host shell — only the
  VM shell is shared.
- **Path traversal / zip-slip** on dir upload: hard-reject `..`, absolute, escaping
  symlinks; extract under a fixed root with a safe tar extractor.
- **Resource exhaustion:** cap VM cpu/mem/disk, upload sizes, PTY output rate
  (coalesce + backpressure so a `yes` flood can't DoS the room).
- **Rate limiting:** keep on `/srp/*`; add light rate-limit on launch/upload ops at
  the broker.
- Keep TLS-by-default, SRP, getpass, no-IP-broadcast guarantees intact.

---

## 11. Milestones

| Phase | Deliverable | Gates |
|---|---|---|
| **P0** | Spec sign-off + crypto interop spike: Rust SRP+HKDF+Fernet talks to live Sanic server. | Rust client exchanges one chat msg with Python client. |
| **P1** | Rust ratatui client at parity (chat, roster, file xfer, themes). Deprecate rich client. | Feature-2 acceptance. |
| **P2** | Multi-user hardening: capacity cap, authoritative roster, `user_joined`. | Feature-1 acceptance. |
| **P3** | Sandbox broker + backend trait + Multipass; shared PTY (output+driver token). | Features 3 & 4 acceptance. |
| **P4** | Permissions: app RBAC + VM unix users/sudo delegation; sender-identity binding. | Feature-6 acceptance + §10 sender fix. |
| **P5** | Dir upload (tar) into shared dir; Docker backend; resource/rate caps; docs. | Feature-5 acceptance; Docker smoke test. |

---

## 12. Open questions / risks

1. **Sender-identity binding (security-critical).** `sbx`/`perm` ops must be tied to
   the server-authenticated `user_id`, not the self-asserted `from`. Options: (a)
   server stamps an authenticated sender id onto every relayed `message`
   (small server change, breaks "pure relay" purity slightly but stays
   zero-knowledge re: *content*); (b) broker-side challenge per privileged op.
   **Recommend (a).** Needs owner decision.
2. **Where does the broker live if the owner uses the Rust client on a phone/thin
   host?** v1 assumes owner host can run Multipass. Fallback: allow a designated
   "sandbox-host" member. Out of scope v1?
3. **Multipass PTY fidelity** via `multipass exec` — confirm full pty (job control,
   resize). If lacking, SSH into the VM instead (`multipass` injects a key).
4. **vt100 crate completeness** for heavy TUIs (vim/tmux-in-VM). Spike in P3.
5. **Cross-platform** broker (owner on macOS/Windows)? Multipass supports both;
   Docker paths differ. v1 target = Linux owner (matches current usage).
6. **Capacity >4 fan-out** — O(N) broadcast + N PTY decryptions per frame. Fine to
   ~12; note ceiling. Coalesce PTY output to bound it.

---

## 13. Testing strategy

- **Crypto interop** (P0): Rust↔Python chat round-trip; golden vectors for
  HKDF/Fernet/SRP.
- **Protocol:** schema tests for v2 envelope; back-compat with `_ft`.
- **Server:** extend existing pytest suite (`tests/`) for capacity cap, roster
  events, sender-id stamping.
- **Broker (Rust):** unit tests for RBAC matrix, ACL transitions, driver-token
  state machine, tar-extract traversal guard.
- **Integration:** scripted Multipass launch in CI-capable runner (or gated
  manual); verify user/sudo mapping, file ownership, purge-on-stop.
- **Manual lab:** extend `lab/setup-lab.sh` to a 3-pane Rust-client lab + a
  `/sbx launch` smoke walkthrough.

---

## Appendix A — Mapping requested features → spec sections

| Requested | Section |
|---|---|
| 1. Up to 4 users, infra for more | §5 |
| 2. ratatui TUI, enhanced + custom colours/layout | §6 |
| 3. Launch sandboxed env (Multipass), run commands/scripts | §7, §8 |
| 4. Shared collaborative terminal | §8 |
| 5. Upload files/directories to shared session | §9.1 |
| 6. Linux perms in VM, superuser by initiator + delegation | §9.2 |