docs: box user design spec (non-root box + user-set password)
This commit is contained in:
Gabriel Brown
@@ -0,0 +1,166 @@
|
||||
# Box user: non-root terminal & agent execution with a user-set password
|
||||
|
||||
**Date:** 2026-07-12
|
||||
**Status:** Approved design, pending implementation
|
||||
|
||||
## Problem
|
||||
|
||||
Everything inside a user's box container (`spoon-box-<username>`) runs as root:
|
||||
the interactive terminal, agent turns (Claude Code / Codex / OpenCode), and
|
||||
dotfiles setup. This is wrong for three reasons:
|
||||
|
||||
1. Claude Code refuses to run certain operations as root, so agent turns hit
|
||||
artificial failures.
|
||||
2. Root-owned homes make every file mutation a foot-gun (a stray `rm` has no
|
||||
guardrails, tools written for normal users misbehave).
|
||||
3. The box is pitched as "your dev machine in Spoon" — a real machine has a
|
||||
named user, a home they own, sudo, and a password.
|
||||
|
||||
## Decisions (made with the user)
|
||||
|
||||
- **sudo policy:** passwordless until the user sets a password; once a
|
||||
password is stored, sudo requires it.
|
||||
- **Password UX:** a "Box user" card on the `/machine` page. Saving stores the
|
||||
password encrypted in Convex and, when the box is running, applies it live
|
||||
via `chpasswd` — no restart needed.
|
||||
- **Agent turns run as the user too**, not just the terminal (this was the
|
||||
original motivation).
|
||||
- The Linux username mirrors the Spoon username (sanitized, see below); the
|
||||
prompt reads `gabriel@gabriel-box`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### The ownership problem (the one hard part)
|
||||
|
||||
The worker writes into box homes **from the host side**: dotfiles overlay
|
||||
files, `.bash_profile`, the box file editor (`writeBoxFile`), and job repo
|
||||
clones. Dev and prod differ in who that host writer is:
|
||||
|
||||
| | Dev (rootless podman) | Prod (rootful docker) |
|
||||
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Host writer | `gib` (host uid) | worker container, uid 0 |
|
||||
| Appears in box as | uid 0 (default mapping) | uid 0 |
|
||||
| Fix | `--userns=keep-id:uid=1000,gid=1000` on the box: the host user _is_ box uid 1000, so host writes are already user-owned | worker chowns to `1000:1000` after each host-side write |
|
||||
|
||||
The uniform mechanism: after every host-side write into a home, the worker
|
||||
runs `chown -R 1000:1000 <paths>` **inside the container as root**. Under
|
||||
dev's keep-id mapping this is a no-op (files are already uid 1000); under prod
|
||||
it repairs uid 0 ownership. One code path, no runtime branching at call sites.
|
||||
|
||||
The keep-id flag is added to the box `run` args only when the container
|
||||
runtime is podman, overridable via `SPOON_AGENT_BOX_USERNS` (empty string
|
||||
disables; any other value is passed through as `--userns=<value>`).
|
||||
|
||||
### Box init (worker, `ensureUserContainer`)
|
||||
|
||||
After the `run`, the worker execs an idempotent root init script:
|
||||
|
||||
1. `useradd` the sanitized username with uid/gid 1000, shell `/bin/bash`,
|
||||
home `-d /home/<spoon-username>` (no `-M` skeleton copy — the mounted home
|
||||
persists; `ensureBashProfile` already seeds login-shell wiring).
|
||||
2. `usermod -aG wheel <user>` (normal Fedora admin group; wheel requires a
|
||||
password for sudo, which is exactly the post-password behavior we want).
|
||||
3. Sudoers drop-in `/etc/sudoers.d/spoon-box`: present with
|
||||
`<user> ALL=(ALL) NOPASSWD:ALL` **only when no password is stored**;
|
||||
absent otherwise (wheel membership then enforces password-required sudo).
|
||||
Written via `visudo -c` validation; `chmod 0440`.
|
||||
4. If a password is stored: apply via `chpasswd` **through stdin** (never
|
||||
argv — argv is visible in `ps`).
|
||||
5. One-time home ownership migration: if `~/.spoon/chown-v1` marker is
|
||||
absent, `chown -R 1000:1000 /home/<username>` and write the marker. Guards
|
||||
against re-walking a large home on every box recreation; later host-side
|
||||
writes are covered by the per-write chown above.
|
||||
6. `--hostname <linux-username>-box` on the `run` for a normal-machine prompt.
|
||||
|
||||
Username sanitization (`linuxUsername()` helper, unit-tested): lowercase,
|
||||
invalid chars → `-`, must start `[a-z_]` (prefix `u` otherwise), truncated to
|
||||
32 chars, fallback `spoon`. The **home path stays keyed by the Spoon
|
||||
username** (everything already depends on it); only the passwd entry uses the
|
||||
sanitized name, with `-d` pointing at the existing home.
|
||||
|
||||
Init failure fails the acquire; the terminal bridge already logs it and closes
|
||||
the WebSocket with a readable reason, and agent turns already surface acquire
|
||||
errors.
|
||||
|
||||
### Execution as the user
|
||||
|
||||
- Terminal bridge (`terminal.ts`): both job and box execs get
|
||||
`User: <linux-username>`.
|
||||
- Agent turns: `streamExecInContainer` / `runExecInContainer` /
|
||||
`buildMarkedCommand` call sites pass `-u <linux-username>`.
|
||||
- Root remains only where needed: box init, post-write chowns, and
|
||||
`killBoxProcessesByMarker` (root can signal user processes).
|
||||
- Job secrets files (0600, host-written) are included in post-write chown so
|
||||
agents can still read them.
|
||||
|
||||
### Password storage (backend, Convex)
|
||||
|
||||
- New user-keyed `boxSettings` table (one row per user; do NOT piggyback on
|
||||
the dotfiles/user-environment record — the password must exist independently
|
||||
of whether dotfiles are configured) with
|
||||
`boxPasswordEncrypted?: string`, encrypted with the existing
|
||||
`secretCrypto.ts` AES-256-GCM helpers.
|
||||
- Owner-authed mutation `setBoxPassword` (min 8 / max 128 chars; empty clears
|
||||
the password and reverts sudo to NOPASSWD on next apply).
|
||||
- Worker-token-authed Node action returns the decrypted password for box
|
||||
init, mirroring `getEnvironmentForJob`.
|
||||
- A `hasBoxPassword` owner query for the UI. The password itself is
|
||||
write-only: no query ever returns the plaintext to a browser.
|
||||
|
||||
### Live apply (worker route + Next proxy)
|
||||
|
||||
- New worker route `POST /box/set-password` (same HMAC internal-token auth as
|
||||
the other `/box/*` routes), body `{ password: string | null }`. If the box
|
||||
is running: `chpasswd` via stdin (or `passwd -d` + NOPASSWD drop-in
|
||||
restore when clearing), and toggle the sudoers drop-in to match. If not
|
||||
running: no-op success (init applies it at next creation).
|
||||
- Next API route (mirrors the existing `/box/*` proxy pattern): verifies the
|
||||
session, writes Convex first, then calls the worker route so a running box
|
||||
updates live.
|
||||
|
||||
### UI (`/machine` page)
|
||||
|
||||
A "Box user" card: shows `user@host` identity, whether a password is set, and
|
||||
a set/change/clear password form (two fields: new password + confirm;
|
||||
write-only, never displays the current value). Save → Next API → Convex +
|
||||
live apply → toast. Copy explains the sudo behavior ("no password: sudo works
|
||||
without one; with a password: sudo prompts for it").
|
||||
|
||||
## Error handling
|
||||
|
||||
- Init script errors → acquire failure → visible terminal close reason /
|
||||
agent turn error (infrastructure added earlier today).
|
||||
- `chpasswd`/sudoers failure on live apply → worker route 500 with stderr
|
||||
text → surfaced in the card.
|
||||
- Convex write succeeds but live apply fails → card shows a warning that the
|
||||
password takes effect on next box restart (state is still consistent:
|
||||
init re-applies from Convex).
|
||||
|
||||
## Testing
|
||||
|
||||
- **Unit (worker):** `linuxUsername()` sanitizer; init-script builder
|
||||
(user/wheel/sudoers/chpasswd-presence permutations); sudoers content for
|
||||
password vs no-password; exec call sites pass `-u`/`User`.
|
||||
- **Unit (backend):** setBoxPassword validation, encryption round-trip,
|
||||
worker-token gate on the decrypt action.
|
||||
- **Component (next):** Box user card renders states (no password / password
|
||||
set / apply-failed warning).
|
||||
- **End-to-end (manual, WS harness from today):** `whoami` → username;
|
||||
`id -u` → 1000; `sudo -n true` succeeds before password; after setting a
|
||||
password `sudo -n true` fails and `sudo true` prompts; agent turn creates a
|
||||
file owned by the user; dotfiles + box file editor writes remain
|
||||
user-editable in both dev and prod runtimes.
|
||||
|
||||
## Migration
|
||||
|
||||
Existing boxes pick everything up on their next recreation (idle reap or
|
||||
`/machine` Restart) — no data migration. The one-time home chown handles
|
||||
files root already created. Docs (`docs/agent-terminal.md`, box docs) get a
|
||||
section on the box user + password.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- SSH access to the box.
|
||||
- Multiple users / teams per box.
|
||||
- Password complexity policies beyond length bounds.
|
||||
- Changing the home path layout.
|
||||
Reference in New Issue
Block a user