114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
# Phase 4: Auth Passthrough - Context
|
||
|
||
**Gathered:** 2026-04-10
|
||
**Status:** Ready for planning
|
||
|
||
<domain>
|
||
## 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).
|
||
|
||
</domain>
|
||
|
||
<decisions>
|
||
## 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).
|
||
|
||
</decisions>
|
||
|
||
<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>
|
||
|
||
<specifics>
|
||
## 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.
|
||
|
||
</specifics>
|
||
|
||
<deferred>
|
||
## 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
|
||
|
||
</deferred>
|
||
|
||
---
|
||
|
||
*Phase: 04-auth-passthrough*
|
||
*Context gathered: 2026-04-10*
|