.planning/phases/04-auth-passthrough/04-01-SUMMARY.md

@@ -0,0 +1,120 @@
+---
+phase: 04
+plan: 1
+subsystem: sandbox-script
+tags: [credentials, auth, audit, bwrap]
+dependency_graph:
+  requires: []
+  provides: [credential-mount, unified-audit]
+  affects: [claudebox.sh]
+tech_stack:
+  added: []
+  patterns: [conditional-bwrap-args-array, unified-audit-prefixes]
+key_files:
+  created: []
+  modified:
+    - claudebox.sh
+decisions:
+  - "Used BWRAP_ARGS array instead of inline exec bwrap to support conditional credential mount"
+  - "Used [~]/[>]/[+] text prefixes (not color-only) for accessibility"
+  - "print_audit depends on CREDS_MOUNT set earlier in script — no API change needed"
+metrics:
+  duration: "2m 30s"
+  completed: "2026-04-10"
+  tasks_completed: 2
+  tasks_total: 2
+  files_changed: 1
+---
+
+# Phase 4 Plan 1: Credential Mount + Audit Redesign Summary
+
+**One-liner:** Read-write `~/.claude/.credentials.json` bind mount for OAuth passthrough plus unified `[~]/[>]/[+]` env audit with Mounts and Network sections.
+
+## What Was Built
+
+### Task 4.1.1 — Add credential file mount
+
+Added conditional detection and mounting of `~/.claude/.credentials.json` into the sandbox:
+
+- `CREDS_FILE` / `CREDS_MOUNT` variables set after `mkdir -p "$HOME/.claudebox"`
+- When `CREDS_MOUNT=true`: `--bind "$CREDS_FILE" "$HOME/.claude/.credentials.json"` added to bwrap args
+- Silent skip when file absent — no error or warning output
+- Uses `--bind` (not `--ro-bind`) so OAuth token refresh can write back to the file
+- `exec bwrap` refactored to use `BWRAP_ARGS` array to support the conditional mount cleanly
+- Credential bind mirrored in `--dry-run` display block
+
+### Task 4.1.2 — Rewrite print_audit
+
+Rewrote `print_audit` from three separate sections to a unified list:
+
+- Single loop ordering: sandbox keys `[~]` (green) → host allowlisted `[>]` (yellow) → extra `[+]` (cyan)
+- Text prefixes readable without color (accessibility — D-07)
+- PATH retains multiline indented display
+- New `Mounts:` section shows CWD, `~/.claude`, and conditional credentials line
+- New `Network:` section shows `full (host network)` as Phase 6 placeholder
+- All print_audit output goes to stderr
+- `mask_value` called for every env var value in all three loops
+
+## Decisions Made
+
+1. **BWRAP_ARGS array:** The `exec bwrap ... \` inline form cannot have a conditional in the middle. Refactored to build a `BWRAP_ARGS` array and `exec bwrap "${BWRAP_ARGS[@]}"`. This is cleaner and extensible for future conditional mounts (network tiers, profile mounts).
+
+2. **Text prefixes for accessibility:** `[~]`, `[>]`, `[+]` are printed as literal text (not just color differences). Color is additive — the prefix meaning is clear in monochrome terminals and when piped.
+
+3. **CREDS_MOUNT scoping:** `CREDS_MOUNT` is set at script top-level (before `print_audit`), so the Mounts section in `print_audit` can read it without needing to re-check the filesystem.
+
+## Commits
+
+| Task  | Hash    | Message |
+|-------|---------|---------|
+| 4.1.1 | 6465da8 | feat(04-01): add credential file mount for OAuth passthrough |
+| 4.1.2 | def8e67 | feat(04-01): rewrite print_audit to unified env list with Mounts and Network sections |
+
+## Verification
+
+```
+bash -n claudebox.sh                         # SYNTAX OK
+grep 'CREDS_FILE' claudebox.sh               # line 105: CREDS_FILE="$HOME/.claude/.credentials.json"
+grep 'CREDS_MOUNT' claudebox.sh              # detection + dry-run + bwrap + Mounts section
+grep 'credentials.json' claudebox.sh         # lines 105, 267, 331, 364 (dry-run + bwrap)
+grep 'ro-bind.*credentials' claudebox.sh     # (no output — correct, uses --bind)
+grep '[~]' claudebox.sh                      # lines 239, 242, 248
+grep '[>]' claudebox.sh                      # lines 239, 253
+grep '[+]' claudebox.sh                      # lines 239, 257
+grep 'Mounts:' claudebox.sh                  # line 263
+grep 'Network:' claudebox.sh                 # line 273
+grep 'full (host network)' claudebox.sh      # line 274
+```
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Refactor] Refactored exec bwrap to BWRAP_ARGS array**
+
+- **Found during:** Task 4.1.1
+- **Issue:** The `exec bwrap ... \` inline multi-line form cannot include a conditional mount (`if [[ "$CREDS_MOUNT" == true ]]; then ... fi`) in the middle of the argument list.
+- **Fix:** Replaced the inline `exec bwrap` form with a `BWRAP_ARGS` array built up with conditional appends, then `exec bwrap "${BWRAP_ARGS[@]}"`. This preserves identical runtime behavior while enabling conditional mounts.
+- **Files modified:** claudebox.sh
+- **Commit:** 6465da8
+
+## Known Stubs
+
+- **Network section:** `full (host network)` in `print_audit` is an intentional Phase 4 placeholder. Network isolation tiers will replace this in Phase 6.
+
+## Threat Flags
+
+| Flag | File | Description |
+|------|------|-------------|
+| threat_flag: credential-exfil | claudebox.sh | Read-write bind of `~/.claude/.credentials.json` gives sandbox read access to OAuth tokens; sandbox has full host network, so exfiltration is possible. Accepted risk per plan threat model — Phase 6 network tiers reduce surface. |
+
+## Self-Check: PASSED
+
+- claudebox.sh exists and was modified: FOUND
+- Commit 6465da8 exists: FOUND
+- Commit def8e67 exists: FOUND
+- bash -n claudebox.sh: PASSES
+- credentials.json appears in both exec bwrap block and dry-run block: CONFIRMED (lines 364, 331)
+- [~]/[>]/[+] prefixes present in print_audit: CONFIRMED
+- Mounts: / Network: sections present: CONFIRMED
+- full (host network) present: CONFIRMED