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

phase	plan	subsystem	tags	dependency_graph	tech_stack	key_files	decisions	metrics
04	1	sandbox-script	credentials auth audit bwrap	requires provides affects credential-mount unified-audit claudebox.sh	added patterns conditional-bwrap-args-array unified-audit-prefixes	created modified claudebox.sh	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	duration completed tasks_completed tasks_total files_changed 2m 30s 2026-04-10 2 2 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