diff --git a/.planning/phases/04-auth-passthrough/04-CONTEXT.md b/.planning/phases/04-auth-passthrough/04-CONTEXT.md new file mode 100644 index 0000000..5a5fd3f --- /dev/null +++ b/.planning/phases/04-auth-passthrough/04-CONTEXT.md @@ -0,0 +1,114 @@ +# 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 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. + + + + +## 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. + + + + +## 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* diff --git a/.planning/phases/04-auth-passthrough/04-DISCUSSION-LOG.md b/.planning/phases/04-auth-passthrough/04-DISCUSSION-LOG.md new file mode 100644 index 0000000..c30f012 --- /dev/null +++ b/.planning/phases/04-auth-passthrough/04-DISCUSSION-LOG.md @@ -0,0 +1,78 @@ +# Phase 4: Auth Passthrough - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions captured in CONTEXT.md — this log preserves the Q&A. + +**Date:** 2026-04-10 +**Phase:** 04-auth-passthrough +**Mode:** discuss +**Areas discussed:** Missing credentials fallback, Audit display, API key + OAuth coexistence, Which credential files + +--- + +## Areas Discussed + +### Missing credentials fallback + +| Question | Options | Selected | +|----------|---------|----------| +| What should happen if ~/.claude/.credentials.json doesn't exist on the host? | Skip silently / Warn in audit / Hard error | Skip silently | + +**Rationale:** No credentials = no subscription access inside sandbox. Claude will prompt to log in. No need to warn or error. + +--- + +### Audit display + +| Question | Options | Selected | +|----------|---------|----------| +| Should the credential mount appear in the pre-launch env audit? | Show in audit / Silent | Show in audit | + +**User input:** Requested a broader audit redesign — three sections (env, mounts, network), unified env var list with color + prefix-based categorization. Not just a minimal mount line. + +| Question | Options | Selected | +|----------|---------|----------| +| Fold audit redesign into Phase 4 or defer? | Fold into Phase 4 / Phase 4 shows mount only | Fold into Phase 4 | + +**Rationale:** Phase 4 already touches the audit; doing the full redesign avoids a half-done audit screen. + +| Question | Options | Selected | +|----------|---------|----------| +| Color scheme for unified env var list? | Green/Yellow/Cyan / Green/Yellow/Magenta / You decide | Green/Yellow/Cyan + accessibility prefixes | + +**User input:** Requested accessibility prefixes alongside colors: `[~]` sandbox-generated, `[>]` host allowlisted, `[+]` user-configured. + +| Question | Options | Selected | +|----------|---------|----------| +| Prefix characters? | [S]/[H]/[U] / [~]/[>]/[+] / You decide | [~] / [>] / [+] | + +--- + +### API key + OAuth coexistence + +| Question | Options | Selected | +|----------|---------|----------| +| When ANTHROPIC_API_KEY is set, still mount credentials? | Always mount if credentials exist / Skip mount when API key is set | Always mount if credentials exist | + +**Rationale:** Simpler logic. Claude Code handles precedence internally. + +--- + +### Which credential files + +| Question | Options | Selected | +|----------|---------|----------| +| Which auth files to mount? | .credentials.json only / Entire ~/.claude / credentials.json + .oauth-token | .credentials.json only | + +**Rationale:** Minimal surface. Other ~/.claude contents belong to Phase 5 (instance isolation). + +--- + +## Corrections Made + +None — all selections were user-confirmed choices. + +## Scope Notes + +- Audit redesign (three sections, color + prefix) folded into Phase 4 scope at user request. +- Network section in audit is a placeholder in Phase 4 — Phase 6 makes it dynamic.