---
plan: 1
phase: 04
wave: 1
depends_on: []
files_modified:
  - claudebox.sh
requirements: [AUTH-01, AUTH-02]
autonomous: true
must_haves:
  truths:
    - "claudebox launches successfully when ~/.claude/.credentials.json exists on the host"
    - "OAuth token refresh can write back to the credentials file (read-write mount)"
    - "claudebox launches without error when ~/.claude/.credentials.json does not exist"
    - "ANTHROPIC_API_KEY is passed into the sandbox when set on the host"
    - "The audit screen shows all env vars in a single unified list with [~]/[>]/[+] prefixes"
    - "The audit screen shows a Mounts section and a Network section after the env list"
    - "The --dry-run output mirrors the credential bind when the file exists"
  artifacts:
    - path: "claudebox.sh"
      provides: "Credential mount logic, updated print_audit, updated --dry-run block"
      contains: "credentials.json"
  key_links:
    - from: "claudebox.sh credential bind block"
      to: "exec bwrap call (line ~327)"
      via: "--bind $HOME/.claude/.credentials.json $HOME/.claude/.credentials.json"
    - from: "claudebox.sh credential bind block"
      to: "--dry-run display block (line ~292)"
      via: "mirrored echo of credential bind"
    - from: "print_audit"
      to: "AUDIT_SANDBOX_KEYS / AUDIT_HOST_KEYS / AUDIT_EXTRA_KEYS arrays"
      via: "[~]/[>]/[+] prefix loop"
---

# Plan 1: Credential Mount + Audit Redesign

## Goal

Mount `~/.claude/.credentials.json` read-write into the sandbox and rewrite the pre-launch audit to a unified env/mounts/network display.

## Context

Claude Code stores OAuth tokens in `~/.claude/.credentials.json`. Without mounting this file, users must re-authenticate every time. The mount must be read-write because OAuth refresh writes new tokens back to the file. When `ANTHROPIC_API_KEY` is set on the host, it is already passed through (line 204 of claudebox.sh) — no changes needed for that path.

The current audit shows three separate sections (Sandbox-generated / Host allowlisted / Extra). The redesign collapses these into one list with `[~]`/`[>]`/`[+]` prefixes (accessible without color), adds a Mounts section showing active filesystem binds, and adds a Network section (placeholder showing "full (host network)" until Phase 6).

<threat_model>
## Threat Model

**Assets:**
- `~/.claude/.credentials.json` — OAuth tokens granting access to the user's Claude subscription
- `ANTHROPIC_API_KEY` — API key granting billable Claude API access

**Threat actors:**
- Malicious code running inside the sandbox that could exfiltrate credentials via network or file writes
- A compromised Claude Code session writing a crafted `.credentials.json` back to the host

**Attack vectors:**
- Sandbox code reads `.credentials.json` and exfiltrates tokens over the network (full host network in Phase 4)
- Sandbox code overwrites `.credentials.json` with attacker-controlled content, poisoning the host credential store
- Path traversal: if the bind target were `$HOME/.claude/` (directory), sandbox code could write new files into `~/.claude` on the host

**Mitigations:**
- Bind is file-scoped (`--bind .credentials.json .credentials.json`), NOT directory-scoped — sandbox cannot create new files in the host `~/.claude` directory via this mount
- Read-write is required for legitimate OAuth refresh; this is an accepted trade-off documented in D-02
- `ANTHROPIC_API_KEY` is masked in audit output by `mask_value` (already implemented)
- Phase 6 network isolation will allow users to restrict exfiltration surface; Phase 4 accepts full-network risk consistent with existing behavior

**Residual risk:**
- A malicious prompt could cause Claude to read and exfiltrate the OAuth token over the network. Accepted: this is equivalent risk to the API key already in the sandbox. Phase 6 network tiers reduce this surface.
- OAuth token can be overwritten by sandbox code. Accepted: the file must be writable for refresh to work (D-02). The host file is the user's own credential file.
</threat_model>

## Tasks

<task id="4.1.1" name="Add credential file mount">

<read_first>
- claudebox.sh lines 284–350 — the --dry-run display block and exec bwrap call; credential bind goes in both places
- claudebox.sh lines 98–103 — CWD and ~/.claudebox setup pattern to follow
</read_first>

After the `mkdir -p "$HOME/.claudebox"` call and before the `print_audit` invocation, add a block that:

1. Sets `CREDS_FILE="$HOME/.claude/.credentials.json"`
2. Checks `if [[ -f "$CREDS_FILE" ]]; then` sets `CREDS_MOUNT=true`; else `CREDS_MOUNT=false`
3. Adds `--bind "$CREDS_FILE" "$HOME/.claude/.credentials.json"` to the exec bwrap call (after the `--symlink "$HOME/.claudebox" "$HOME/.claude"` line) when `CREDS_MOUNT=true`
4. Mirrors the same conditional bind in the `--dry-run` display block (after the symlink echo)

**Bwrap mount ordering note:** The credential file bind must come AFTER the `--symlink "$HOME/.claudebox" "$HOME/.claude"` line. bwrap processes mounts in order; the symlink creates `~/.claude → ~/.claudebox`, and the subsequent file bind layers `.credentials.json` on top of it inside the sandbox. This matches the established pattern from the code context.

Do NOT use `--ro-bind` — the mount must be read-write for OAuth token refresh (D-02).

Do NOT add any warning or error output when the file is absent — skip silently (D-03).

Always add the bind when the file exists, even if `ANTHROPIC_API_KEY` is also set (D-04).

<acceptance_criteria>
- [ ] `grep -n 'CREDS_FILE' claudebox.sh` shows the variable declared as `CREDS_FILE="$HOME/.claude/.credentials.json"`
- [ ] `grep -n 'CREDS_MOUNT' claudebox.sh` shows both the conditional set and usage in bwrap exec
- [ ] `grep -n 'credentials.json' claudebox.sh` shows the bind appears in BOTH the exec bwrap block AND the --dry-run block
- [ ] The bind uses `--bind` (not `--ro-bind`) — `grep 'ro-bind.*credentials' claudebox.sh` returns nothing
- [ ] `grep -A2 'CREDS_MOUNT' claudebox.sh` shows the condition is `[[ -f "$CREDS_FILE" ]]` — file existence check, not variable existence
- [ ] No `echo` or `>&2` output is produced when the credentials file is absent — the skip is completely silent
</acceptance_criteria>

</task>

<task id="4.1.2" name="Rewrite print_audit to unified list with Mounts and Network sections">

<read_first>
- claudebox.sh lines 171–263 — the audit data structures (AUDIT_SANDBOX_KEYS, AUDIT_HOST_KEYS, AUDIT_EXTRA_KEYS arrays and associated maps) and the current print_audit function; the rewrite must consume the same data structures
- claudebox.sh lines 65–76 — ANSI color variable definitions (BOLD, RESET, DIM, CYAN, YELLOW, GREEN, RED already defined)
- claudebox.sh lines 78–91 — mask_value function signature and behavior; must be called for all env var values in the new display
</read_first>

Rewrite the `print_audit` function (lines 227–263) to produce the new unified format per D-06, D-07, D-08, D-09, D-10.

**New print_audit structure:**

```
=== Sandbox Environment ===

  [~] HOME=/home/user           ← green [~] prefix, sandbox-generated
  [~] USER=user
  [~] PATH=                     ← PATH gets special multiline treatment (same as before)
        /nix/store/.../bin
  [>] TERM=xterm-256color       ← yellow [>] prefix, host allowlisted (only if set)
  [>] ANTHROPIC_API_KEY=abc123...xyz  ← masked by mask_value
  [+] MY_VAR=value              ← cyan [+] prefix, extra via CLAUDEBOX_EXTRA_ENV

Mounts:
  CWD         /path/to/project   (read-write)
  ~/.claude   ~/.claudebox        (read-write)
  credentials ~/.claude/.credentials.json (read-write)   ← only if CREDS_MOUNT=true

Network:
  full (host network)
```

**Implementation rules:**

1. Single loop over all three key arrays in order: sandbox keys first ([~]), then host keys ([>]), then extra keys ([+])
2. Each line: `  {COLOR}{PREFIX}{RESET} {var}={masked_value}` — the prefix `[~]`, `[>]`, `[+]` is printed in color AND must be readable without color (accessibility per D-07)
3. PATH gets the same multiline indented treatment as the current implementation — show label then each path entry indented
4. After the env list, print a blank line then `${BOLD}Mounts:${RESET}` section:
   - Always show: `  CWD         $CWD   (read-write)`
   - Always show: `  ~/.claude   $HOME/.claudebox   (read-write)`
   - Conditionally show (when `CREDS_MOUNT=true`): `  credentials $HOME/.claude/.credentials.json   (read-write)`
   - Use consistent column alignment — pad the label to a fixed width (e.g., 12 chars) so values align
5. After Mounts, print a blank line then `${BOLD}Network:${RESET}` section:
   - Always show: `  full (host network)`
   - This is a Phase 4 placeholder — no dynamic logic
6. All output to stderr (`>&2`)
7. Unset allowlisted host vars are silently omitted from the display (discretion decision from CONTEXT.md)

The existing `AUDIT_SANDBOX_KEYS`, `AUDIT_SANDBOX_VALS`, `AUDIT_HOST_KEYS`, `AUDIT_HOST_VALS`, `AUDIT_EXTRA_KEYS`, `AUDIT_EXTRA_VALS` arrays must NOT be restructured — only `print_audit` changes.

<acceptance_criteria>
- [ ] `grep '\[~\]' claudebox.sh` matches inside print_audit, used for sandbox-generated vars
- [ ] `grep '\[>\]' claudebox.sh` matches inside print_audit, used for host-allowlisted vars
- [ ] `grep '\[+\]' claudebox.sh` matches inside print_audit, used for extra vars
- [ ] `grep 'Mounts:' claudebox.sh` matches inside print_audit
- [ ] `grep 'Network:' claudebox.sh` matches inside print_audit
- [ ] `grep 'full (host network)' claudebox.sh` matches inside print_audit
- [ ] `grep 'CREDS_MOUNT' claudebox.sh` shows the Mounts section conditionally includes the credentials line
- [ ] `grep 'mask_value' claudebox.sh` shows mask_value is called for every env var value in the new loops (not just some vars)
- [ ] `grep '>&2' claudebox.sh` — all print_audit echo/printf calls redirect to stderr
- [ ] `bash -n claudebox.sh` exits 0 (no syntax errors)
</acceptance_criteria>

</task>

## Verification

```bash
# Syntax check
bash -n claudebox.sh

# Verify credential bind present in both exec and dry-run blocks
grep -n 'credentials.json' claudebox.sh

# Verify read-write (not ro-bind) for credentials
grep 'ro-bind.*credentials' claudebox.sh  # must return nothing

# Verify prefix scheme present
grep -E '\[~\]|\[>\]|\[+\]' claudebox.sh

# Verify Mounts and Network sections
grep -E 'Mounts:|Network:|full .host network.' claudebox.sh

# Functional test: dry-run with credentials file present
# (Create a test file, run dry-run, confirm bind appears in output)
touch /tmp/test_credentials.json
HOME_ORIG="$HOME"
# If test harness available: claudebox --dry-run should show --bind ...credentials.json
```

## Must-Haves

- `~/.claude/.credentials.json` is mounted read-write into the sandbox when it exists on the host
- When the file does not exist, claudebox starts without any error or warning
- The exec bwrap call and the --dry-run display block are in sync (credential bind appears in both or neither)
- The audit screen shows `[~]`, `[>]`, and `[+]` prefixes that distinguish env var categories without relying on color alone
- The audit screen shows a Mounts section listing CWD, ~/.claude, and (conditionally) the credentials file
- The audit screen shows a Network section with "full (host network)" as a Phase 6 placeholder
- `bash -n claudebox.sh` passes (no syntax errors introduced)

## Output

After completion, create `.planning/phases/04-auth-passthrough/04-01-SUMMARY.md`