claudebox/.planning/phases/04-auth-passthrough/04-CONTEXT.md

Phase 4: Auth Passthrough - Context

Gathered: 2026-04-10 Status: Ready for planning

## Phase Boundary

Mount host Claude credentials read-write into the sandbox so subscription and API key access work inside. Includes a redesign of the pre-launch env audit to show env vars, mounts, and network as three unified sections with color + prefix-based categorization.

This phase does NOT scope per-project instance isolation (Phase 5) or any other ~/.claude state (history, todos, settings).

## Implementation Decisions

Credential mount

• D-01: Mount only ~/.claude/.credentials.json from the host — no other auth files. Other ~/.claude contents (history, todos, settings) belong to Phase 5.
• D-02: Mount read-write (already decided in v2.0 planning): OAuth token refresh writes back to .credentials.json; ro-bind causes silent EACCES.
• D-03: If ~/.claude/.credentials.json does not exist on the host, skip the mount silently. No warning, no error — Claude will prompt the user to log in inside the sandbox if needed.
• D-04: Always mount credentials if the file exists, even when ANTHROPIC_API_KEY is also set. Claude Code handles precedence internally.

ANTHROPIC_API_KEY

• D-05: ANTHROPIC_API_KEY is already in the host allowlist (line 204 of claudebox.sh). No additional changes needed — AUTH-02 is satisfied by existing code.

Audit screen redesign

• D-06: Replace the current three-section audit (Sandbox-generated / Host allowlisted / Extra) with a single unified list of all env vars, each prefixed to indicate category. Add two new sections after the env list: Mounts and Network.
• D-07: Prefix scheme (accessible without color — works for colorblind/screen-reader users):
  • [~] — Sandbox-generated (auto-set, never from host)
  • [>] — Host allowlisted (passed from host if set)
  • [+] — User-configured extras (via CLAUDEBOX_EXTRA_ENV or future profile)
• D-08: Color scheme mapped to prefixes:
  • [~] green
  • [>] yellow
  • [+] cyan
• D-09: Mounts section lists the active filesystem binds visible to the user — at minimum: CWD (read-write), ~/.claudebox → ~/.claude, and credential file if mounted. Format TBD by planner.
• D-10: Network section: for now (Phase 4, before Phase 6 adds tiers), show the current default — "full (host network)". This section is a placeholder that Phase 6 will fill in.

Claude's Discretion

• Exact formatting of the Mounts and Network sections (spacing, alignment, separators).
• Whether to show a header row for each section or just a bold label.
• Whether unset allowlisted vars are shown as [>] VAR (not set) or silently omitted (recommend omitting — less noise).

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Requirements

• .planning/REQUIREMENTS.md §Authentication (AUTH-01, AUTH-02) — credential mount spec and API key precedence rule

Existing implementation

• claudebox.sh lines 180–263 — current ENV_ARGS construction and audit display (print_audit function); this is the primary code that changes
• claudebox.sh lines 326–350 — bwrap exec with current mount list; credential bind goes here

No external specs — requirements fully captured in decisions above and in REQUIREMENTS.md.

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• ENV_ARGS array (claudebox.sh:181) — bwrap --setenv args built up before exec; credential mount args follow the same pattern as a new MOUNT_ARGS array or inline additions to the exec call.
• print_audit function (claudebox.sh:227–263) — current audit display; will be rewritten per D-06.
• mask_value function (claudebox.sh:86–95) — masks sensitive var values; remains unchanged.
• ANSI color vars (claudebox.sh:66–79) — GREEN, YELLOW, CYAN, BOLD, RESET already defined; CYAN is not yet used in the audit but is available.

Established Patterns

• bwrap mount ordering matters: ~/.claudebox bind first, then credential file bind on top of it — bwrap layers binds in order.
• Conditional passthrough pattern: if [[ -v "$var" ]]; then ... fi (line 205) — same guard pattern applies for the credential file existence check: if [[ -f "$HOME/.claude/.credentials.json" ]]; then.
• All user-visible output goes to stderr (>&2), never stdout.

Integration Points

• Credential bind must be added to both the live exec bwrap call (line 327) AND the --dry-run display block (line 292) to keep them in sync.
• print_audit is called before the bwrap exec and is the only place the audit display is generated.
• ANTHROPIC_API_KEY already wired (line 204) — no changes needed there.

</code_context>

## Specific Ideas

• Audit format: single unified env var list with [~]/[>]/[+] prefixes, followed by a Mounts section and a Network section. The prefix alone (no color) must be sufficient to distinguish categories — for accessibility.
• Network section in Phase 4 is a placeholder showing "full (host network)" — Phase 6 will make it dynamic.
• The credential bind must be mirrored in --dry-run output.

## Deferred Ideas

• Per-project instance isolation (~/.claude state scoped per project) — Phase 5
• Dynamic network tier display in audit — Phase 6 (placeholder added in Phase 4)
• Profile-driven extra mounts shown in audit — Phase 7

---

Phase: 04-auth-passthrough Context gathered: 2026-04-10