spoon/docs/superpowers/plans/2026-07-13-box-user.md

# Box User Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Terminal sessions and agent turns inside `spoon-box-<username>` run as a named non-root user (uid 1000) with wheel/sudo and a user-settable password stored encrypted in Convex.

**Architecture:** The worker creates the Linux user at box init via an idempotent root exec script; dev podman maps the host user onto uid 1000 with `--userns=keep-id`, prod docker repairs host-written file ownership with targeted in-container chowns. Password lives in a new `boxSettings` Convex table (AES-256-GCM via existing `secretCrypto`), applied at init and live via a new `/box/set-password` worker route; a "Box user" card on `/machine` drives it.

**Tech Stack:** bun + TypeScript worker (execa/dockerode), Convex backend, Next 15 App Router, vitest.

**Spec:** `docs/superpowers/specs/2026-07-12-box-user-design.md`

## Global Constraints

- Box user uid/gid: `1000:1000`, fixed.
- sudo: NOPASSWD drop-in `/etc/sudoers.d/spoon-box` present only while no password is stored; wheel membership always.
- Password bounds: min 8, max 128 chars; `null`/empty clears.
- Password plaintext never in argv (stdin only), never returned to a browser.
- Home path stays `/home/<spoon-username>`; only the passwd entry name is sanitized.
- podman-only run flag: `--userns=keep-id:uid=1000,gid=1000`, override env `SPOON_AGENT_BOX_USERNS` (empty disables, other values pass through).
- All commits run the repo pre-commit hooks; finish with full `bun run ci:check`.

---

### Task 1: `box-user.ts` — sanitizer + script builders (worker, pure)

**Files:**

- Create: `apps/agent-worker/src/runtime/box-user.ts`
- Test: `apps/agent-worker/tests/unit/box-user.test.ts`

**Interfaces (Produces):**

- `linuxUsername(spoonUsername: string): string`
- `BOX_UID = 1000`
- `buildBoxInitScript(args: { username: string; home: string }): string` — idempotent root script: useradd (uid 1000, `-d <home>`, bash), wheel, marker-guarded `chown -R` of home. Does NOT touch sudoers/password (those depend on stored state and are applied by `applySudoPolicy`).
- `buildSudoPolicyScript(args: { username: string; passwordSet: boolean }): string` — writes or removes `/etc/sudoers.d/spoon-box` (mode 0440, validated with `visudo -c` before install).
- `CHPASSWD_COMMAND: string[]` (`['chpasswd']`) and `buildClearPasswordCommand(username: string): string[]` (`['passwd', '-d', username]`).

- [ ] **Step 1: Write failing tests** covering: sanitizer (lowercase, invalid → `-`, digit-start prefixed `u`, >32 truncated, empty → `spoon`); init script contains `useradd` guarded by `id -u`, `-u 1000`, `-d /home/Gabriel` untouched-case home, wheel usermod, marker path `/home/Gabriel/.spoon/chown-v1` guard around `chown -R 1000:1000`; sudo script with `passwordSet:false` installs NOPASSWD via visudo-validated temp file, with `passwordSet:true` removes the drop-in.

```ts
// apps/agent-worker/tests/unit/box-user.test.ts
import { describe, expect, it } from 'vitest';

import {
  buildBoxInitScript,
  buildClearPasswordCommand,
  buildSudoPolicyScript,
  linuxUsername,
} from '../../src/runtime/box-user';

describe('linuxUsername', () => {
  it('lowercases and passes through simple names', () => {
    expect(linuxUsername('gabriel')).toBe('gabriel');
    expect(linuxUsername('Gabriel')).toBe('gabriel');
  });
  it('replaces invalid characters with dashes', () => {
    expect(linuxUsername('g@b r!el')).toBe('g-b-r-el');
  });
  it('prefixes names that do not start with [a-z_]', () => {
    expect(linuxUsername('1337')).toBe('u1337');
    expect(linuxUsername('-dash')).toBe('u-dash');
  });
  it('truncates to 32 chars and falls back to spoon', () => {
    expect(linuxUsername('a'.repeat(40))).toHaveLength(32);
    expect(linuxUsername('')).toBe('spoon');
    expect(linuxUsername('@@@')).toBe('u---');
  });
});

describe('buildBoxInitScript', () => {
  const script = buildBoxInitScript({
    username: 'gabriel',
    home: '/home/Gabriel',
  });
  it('creates the user idempotently with uid 1000 at the given home', () => {
    expect(script).toContain("id -u 'gabriel'");
    expect(script).toContain('useradd');
    expect(script).toContain('-u 1000');
    expect(script).toContain("-d '/home/Gabriel'");
    expect(script).toContain('-s /bin/bash');
  });
  it('adds wheel membership', () => {
    expect(script).toContain("usermod -aG wheel 'gabriel'");
  });
  it('chowns the home once, guarded by the marker', () => {
    expect(script).toContain('/home/Gabriel/.spoon/chown-v1');
    expect(script).toContain("chown -R 1000:1000 '/home/Gabriel'");
  });
});

describe('buildSudoPolicyScript', () => {
  it('installs a visudo-validated NOPASSWD drop-in when no password is set', () => {
    const script = buildSudoPolicyScript({
      username: 'gabriel',
      passwordSet: false,
    });
    expect(script).toContain('gabriel ALL=(ALL) NOPASSWD:ALL');
    expect(script).toContain('visudo -c');
    expect(script).toContain('/etc/sudoers.d/spoon-box');
    expect(script).toContain('chmod 0440');
  });
  it('removes the drop-in when a password is set', () => {
    const script = buildSudoPolicyScript({
      username: 'gabriel',
      passwordSet: true,
    });
    expect(script).toContain('rm -f /etc/sudoers.d/spoon-box');
    expect(script).not.toContain('NOPASSWD');
  });
});

describe('password commands', () => {
  it('clears via passwd -d', () => {
    expect(buildClearPasswordCommand('gabriel')).toEqual([
      'passwd',
      '-d',
      'gabriel',
    ]);
  });
});
```

- [ ] **Step 2: Run to verify failure** — `cd apps/agent-worker && bun run test:unit -- box-user` → module not found.
- [ ] **Step 3: Implement**

```ts
// apps/agent-worker/src/runtime/box-user.ts
// The per-box Linux user (Phase: box-user). Terminal sessions and agent turns
// exec as this user instead of root; sudo is passwordless until the user
// stores a password (then wheel membership enforces password-required sudo).

export const BOX_UID = 1000;

const shellQuote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;

// Linux-safe username derived from the Spoon username. The home path keeps
// the Spoon username; only the passwd entry uses this.
export const linuxUsername = (spoonUsername: string): string => {
  const cleaned = spoonUsername
    .toLowerCase()
    .replaceAll(/[^a-z0-9_-]/g, '-')
    .slice(0, 32);
  if (!cleaned) return 'spoon';
  return /^[a-z_]/.test(cleaned) ? cleaned : `u${cleaned}`.slice(0, 32);
};

// Idempotent root init: create the user at the (already mounted) home, grant
// wheel, and chown the home ONCE (marker-guarded — later host-side writes are
// repaired by targeted chowns, so a big home is never re-walked).
export const buildBoxInitScript = (args: {
  username: string;
  home: string;
}): string => {
  const user = shellQuote(args.username);
  const home = shellQuote(args.home);
  const marker = shellQuote(`${args.home}/.spoon/chown-v1`);
  return [
    'set -e',
    `if ! id -u ${user} >/dev/null 2>&1; then`,
    `  useradd -u 1000 -o -M -d ${home} -s /bin/bash ${user}`,
    'fi',
    `usermod -aG wheel ${user}`,
    `if [ ! -f ${marker} ]; then`,
    `  chown -R 1000:1000 ${home}`,
    `  mkdir -p "$(dirname ${marker})" && touch ${marker} && chown 1000:1000 ${marker}`,
    'fi',
  ].join('\n');
};

// Sudo policy: NOPASSWD drop-in only while no password is stored; with a
// password, wheel membership makes sudo prompt for it. The drop-in is staged
// to a temp file and checked with `visudo -c` before install so a bad write
// can never brick sudo.
export const buildSudoPolicyScript = (args: {
  username: string;
  passwordSet: boolean;
}): string => {
  if (args.passwordSet) {
    return 'rm -f /etc/sudoers.d/spoon-box';
  }
  const line = `${args.username} ALL=(ALL) NOPASSWD:ALL`;
  return [
    'set -e',
    `printf '%s\\n' ${shellQuote(line)} > /etc/sudoers.d/spoon-box.tmp`,
    'visudo -c -f /etc/sudoers.d/spoon-box.tmp',
    'chmod 0440 /etc/sudoers.d/spoon-box.tmp',
    'mv /etc/sudoers.d/spoon-box.tmp /etc/sudoers.d/spoon-box',
  ].join('\n');
};

// `chpasswd` reads `user:password` from stdin, so the password never appears
// in argv (visible in `ps`) or in a shell script body.
export const CHPASSWD_COMMAND = ['chpasswd'];

export const buildClearPasswordCommand = (username: string): string[] => [
  'passwd',
  '-d',
  username,
];
```

- [ ] **Step 4: Run to verify pass** — `bun run test:unit -- box-user` → all pass.
- [ ] **Step 5: Commit** — `feat(worker): box-user script builders + username sanitizer`

### Task 2: docker.ts plumbing — exec-as-user, stdin input, chown helper, box run flags

**Files:**

- Modify: `apps/agent-worker/src/runtime/docker.ts`
- Test: `apps/agent-worker/tests/unit/docker-runtime.test.ts` (extend)

**Interfaces:**

- Consumes: `linuxUsername`, `BOX_UID`, `buildBoxInitScript`, `buildSudoPolicyScript`, `CHPASSWD_COMMAND`, `buildClearPasswordCommand` from Task 1.
- Produces:
  - `streamExecInContainer` / `runExecInContainer` gain optional `user?: string` (adds `-u <user>` to the exec argv) and `runExecInContainer` gains optional `input?: string` (execa `input`, replacing `stdin: 'ignore'` when present).
  - `chownInBox(args: { containerName: string; paths: string[]; redact?: (v: string) => string }): Promise<void>` — best-effort `chown -R 1000:1000 <paths>` exec'd as root; logs (does not throw) on failure. No-op for empty `paths`.
  - `boxUsernsArgs(): string[]` — `['--userns=keep-id:uid=1000,gid=1000']` when runtime ends with `podman`; `SPOON_AGENT_BOX_USERNS` overrides (empty string → `[]`, other value → `['--userns=<value>']`). Exported for tests.
  - `ensureUserContainer` gains optional `onCreated?: (containerName: string) => Promise<void>` — invoked only when a fresh container was created (not when already running), AFTER `run` succeeds. Also adds `--hostname <linuxUsername(username)>-box` and `...boxUsernsArgs()` to the `run` argv.
- New env in `apps/agent-worker/src/env.ts`: `boxUserns: process.env.SPOON_AGENT_BOX_USERNS` (raw, may be empty string — distinguish unset).

- [ ] **Step 1: Write failing tests** in `docker-runtime.test.ts` for `boxUsernsArgs` (podman default, docker default `[]`, override set, override empty) and for the exec arg builders if extracted pure (extract `execArgv(args)` helper returning the argv array so `-u` placement is unit-testable: `['exec', ...envFlags, '-w', cwd, ...(user ? ['-u', user] : []), name, ...command]`).
- [ ] **Step 2: Run to verify failure.**
- [ ] **Step 3: Implement** (extract `execArgv` used by both exec fns; add `input`/`user` params; `chownInBox` via `runExecInContainer` with `command: ['chown','-R','1000:1000',...paths]`, catches and `console.error`s; `boxUsernsArgs` reading `env.boxUserns`; wire `--hostname`/userns/`onCreated` into `ensureUserContainer`).
- [ ] **Step 4: Run tests** — extended docker-runtime tests + whole unit suite pass.
- [ ] **Step 5: Commit** — `feat(worker): exec-as-user, stdin input, chown + userns plumbing`

### Task 3: Convex — `boxSettings` table + node actions

**Files:**

- Modify: `packages/backend/convex/schema.ts`
- Create: `packages/backend/convex/boxSettings.ts` (query + internal query/mutation)
- Create: `packages/backend/convex/boxSettingsNode.ts` ('use node' actions)
- Test: follow the existing backend test layout (`packages/backend/tests/…`, convex-test) mirroring the closest existing coverage of `aiSettingsNode`/`userDotfiles`.

**Interfaces (Produces):**

- Schema:

```ts
boxSettings: defineTable({
  ownerId: v.id('users'),
  // Resolved Spoon home username at the time the password was set — the
  // worker looks the row up by this (usernames are not indexed anywhere else).
  username: v.string(),
  boxPasswordEncrypted: v.optional(v.string()),
  updatedAt: v.number(),
})
  .index('by_owner', ['ownerId'])
  .index('by_username', ['username']),
```

- `boxSettings.hasMine` — owner query → `{ hasPassword: boolean }`.
- `boxSettings.getByUsernameInternal` / `boxSettings.upsertMineInternal` — internal plumbing for the node actions.
- `boxSettingsNode.setBoxPassword` — authed action `{ password: string | null }`; validates 8–128 (null/'' clears), resolves the caller's username exactly like `userEnvironment.getMine` (reuse `deriveHomeUsername` from `model.ts`), stores `encryptSecret(password)` or clears the field.
- `boxSettingsNode.getBoxPasswordForWorker` — action `{ workerToken: string; username: string }` → `{ password: string | null }`, gated by the same worker-token check used in `userDotfilesNode.getEnvironmentForJob`; decrypts with `decryptSecret`.

- [ ] **Step 1: Write failing backend tests** (validation bounds, clear semantics, worker-token gate rejects bad token, round-trip returns the plaintext).
- [ ] **Step 2: Run to verify failure** (`cd packages/backend && bun run test` — use the package's existing test script name).
- [ ] **Step 3: Implement schema + functions; run `bash scripts/convex-codegen`.**
- [ ] **Step 4: Run tests + typecheck.**
- [ ] **Step 5: Commit** — `feat(backend): boxSettings table + box password actions`

### Task 4: Worker — box init wiring (user creation, password at creation, exec-as-user everywhere)

**Files:**

- Create: `apps/agent-worker/src/box-settings.ts` (Convex fetch)
- Modify: `apps/agent-worker/src/user-container.ts`, `apps/agent-worker/src/box.ts`, `apps/agent-worker/src/terminal.ts`, `apps/agent-worker/src/worker.ts`, `apps/agent-worker/src/user-environment.ts`, adapters (`runtime/claude-adapter.ts`, `runtime/codex-adapter.ts`, `runtime/opencode-adapter.ts`) and `runtime/agent-runtime.ts` arg types.
- Test: extend `apps/agent-worker/tests/unit/user-container.test.ts`, adapter tests (assert `user` is forwarded to `execStream`), `terminal-resize.test.ts` untouched.

**Interfaces:**

- Consumes: everything from Tasks 1–3.
- Produces:
  - `box-settings.ts`: `fetchBoxPassword(username: string): Promise<string | null>` — ConvexHttpClient action call to `api.boxSettingsNode.getBoxPasswordForWorker` with `env.workerToken`; returns null on any error (box must still start when Convex is down; log the error).
  - `initializeBoxUser(containerName: string, spoonUsername: string, home: string): Promise<void>` (in `box.ts` or a small `box-init.ts`): runs `buildBoxInitScript` as root, fetches password, applies `chpasswd` via stdin when set, then `buildSudoPolicyScript`. This is the `onCreated` hook passed to `ensureUserContainer` from BOTH call paths (`acquireUserBox` in `user-container.ts` and `startBox` in `box.ts`).
  - Terminal bridges pass `User: linuxUsername(username)` in the dockerode exec create (both `bridge` and `bridgeBox`).
  - `worker.ts` / adapters: exec arg objects gain `user: linuxUsername(claim/workspace username)`; `runProjectCommand`, agent turn `execStream` calls, and dotfiles `runExecInContainer` in `materializeUserHome` all pass it. `killBoxProcessesByMarker` stays root.
  - Chown call sites (all best-effort `chownInBox`): after `cloneRepository` (repo dir), after secrets env-file write in `worker.ts` (the `claim.job.envFilePath` target), after overlay-file writes in `materializeUserHome`, after `writeBoxFile` in `box.ts`, after `ensureBashProfile` when invoked with a running box (bridgeBox: chown `~/.bash_profile` right after acquire).

- [ ] **Step 1: Write failing tests** — user-container test asserting `onCreated` fires once per creation (mock `ensureUserContainer` invoking its hook); adapter test asserting `user` reaches `execStream` args.
- [ ] **Step 2: Run to verify failure.**
- [ ] **Step 3: Implement the wiring.**
- [ ] **Step 4: Full worker unit suite + typecheck + lint pass.**
- [ ] **Step 5: Commit** — `feat(worker): run terminals and agent turns as the box user`

### Task 5: Worker — `/box/set-password` route

**Files:**

- Modify: `apps/agent-worker/src/server.ts` (route regex + handler), `apps/agent-worker/src/box.ts` (`setBoxUserPassword`)
- Test: extend `apps/agent-worker/tests/unit/box-route.test.ts` (regex accepts `set-password`).

**Interfaces:**

- Produces: `setBoxUserPassword(username: string, password: string | null): Promise<{ applied: boolean }>` — if box not running → `{ applied: false }`; else chpasswd/clear + sudo policy toggle → `{ applied: true }`. Route: `POST /box/set-password` body `{ password: string | null }`, 400 on invalid length, 200 `{ applied }`.

- [ ] Steps: failing route-regex test → implement → suite green → commit `feat(worker): live box password apply route`.

### Task 6: Next — proxy + API route

**Files:**

- Modify: `apps/next/src/lib/agent-worker-proxy.ts` (`proxyBox` action union + `'set-password'`)
- Create: `apps/next/src/app/api/box/set-password/route.ts`

**Interfaces:**

- Produces: `POST /api/box/set-password` `{ password: string | null }` → `withBox` → validate 8–128/null → `fetchAction(api.boxSettingsNode.setBoxPassword, { password }, { token })` (Convex is source of truth, written first) → `proxyBox(username, 'set-password', { method: 'POST', body: JSON.stringify({ password }) })` → respond `{ hasPassword, applied }`; worker failure downgrades to `{ applied: false }` with 200 (spec: card shows "takes effect on restart").

- [ ] Steps: implement (route has no unit test — component test in Task 7 covers the card; the route mirrors existing `/api/box/*` one-screen handlers) → typecheck/lint → commit `feat(next): box password API`.

### Task 7: Next — Box user card on /machine

**Files:**

- Create: `apps/next/src/components/machine/box-user-card.tsx`
- Modify: `apps/next/src/components/machine/machine-shell.tsx` (render the card)
- Test: `apps/next/tests/component/box-user-card.test.tsx`

**Interfaces:**

- Consumes: `api.boxSettings.hasMine` (convex react query), `api.userEnvironment.getMine` (username for the `user@host` line), `POST /api/box/set-password`.
- Behavior: shows `<username>@<username>-box`; "Password: set / not set"; form (password + confirm, min 8) with Save and — when set — a "Remove password" button; on save success where `applied === false`, shows the "takes effect next restart" note; explains the sudo policy in one sentence of muted copy.

- [ ] Steps: failing component test (renders not-set state; mismatch confirm blocks submit; renders applied-false warning) → implement card + wire into `machine-shell.tsx` → component suite green → commit `feat(next): box user card on /machine`.

### Task 8: Docs + end-to-end verification

**Files:**

- Modify: `docs/agent-terminal.md` (+ the box docs section touched in the docs rewrite) — box user, sudo policy, password flow, ownership model (keep-id vs chown), `SPOON_AGENT_BOX_USERNS`.

- [ ] **Step 1: Docs.**
- [ ] **Step 2: Live verification (dev)** — recreate the box, then via the WS harness: `whoami` → username; `id -u` → 1000; `sudo -n true` → ok; `touch ~/x && ls -l` → user-owned; box file editor write → file user-editable in the terminal. Set a password via the UI (or curl the API route), then: `sudo -n true` fails, `chpasswd` took effect (`su - <user>` with the password succeeds); clear password → NOPASSWD sudo returns. Run one agent turn and confirm it executes as the user (`whoami` artifact or a file it creates is uid 1000).
- [ ] **Step 3: `bun run ci:check` at repo root — all green.**
- [ ] **Step 4: Commit docs; final review of the whole diff.**