Forward Claude Code OAuth credentials from host into the guest

[hbrodin]

Summary

Today coop forwards ANTHROPIC_API_KEY (via claude.api_key config or process env) into the guest, but users who authenticate Claude Code via the OAuth flow (claude /login) have no way to bring that session into the VM. They have to re-authenticate inside every guest, or switch to API-key billing they may not want.

Add a claude.oauth_token config field that resolves to CLAUDE_CODE_OAUTH_TOKEN in the guest, mirroring how claude.api_key resolves to ANTHROPIC_API_KEY.

Motivation

• Subscription users (Pro/Max) authenticate via OAuth, not API keys. Today they get no help from coop.
• The OAuth credential lives somewhere different on every host: macOS Keychain (Claude Code-credentials service), Linux ~/.claude/.credentials.json, or the long-lived output of claude setup-token. The cmd: prefix already supported by claude.api_key is the right shape for resolving any of these.
• ~/.claude/.credentials.json is intentionally excluded from the staged config copy in src/backend.rs:1258 and should stay excluded — env-var forwarding keeps the secret off the guest disk.

Proposed approach

Config

Add oauth_token: Option<String> to ClaudeConfig in src/config.rs:447. Like api_key, it accepts either a literal value or a cmd: shell-out resolved at VM start.

[claude]
# Long-lived headless token from `claude setup-token`, stashed in Keychain
oauth_token = "cmd:security find-generic-password -s coop-claude-token -w"

Forwarding

Extend prepare_env_forwarding in src/backend.rs:856 with a parallel branch that calls resolve_cmd_value and sets CLAUDE_CODE_OAUTH_TOKEN in the EnvForward. SSH SendEnv carries it into the guest unchanged.

Precedence

If both ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN reach the guest, the Claude CLI prefers the API key. Document this. Do not auto-suppress one when the other is set — let users decide which billing path they want.

Token sources and tradeoffs

Three credentials look interchangeable but aren't:

Source	Lifetime	Refresh in guest	Suitable
claude setup-token output	Long, headless-purposed	N/A — long-lived	Recommended
macOS Keychain accessToken	~hours	Fails — guest has no writable credential store	Short sessions only
Linux ~/.claude/.credentials.json accessToken	~hours	Same as Keychain	Short sessions only

The recommended setup is to run claude setup-token once, stash the result wherever the user keeps secrets (Keychain, password manager, plain env), and reference it via cmd:. Pipe directly into the store so the literal token never lands in shell history, e.g. claude setup-token | security add-generic-password -s coop-claude-token -w.

Out of scope

• Copying ~/.claude/.credentials.json into the guest. Putting a refresh token on disk in a second location is a different security tradeoff and should be debated separately if proposed.
• Auto-detecting and extracting tokens from Keychain / credentials.json without user config. Implicit credential reads on every VM start are exactly the kind of magic that turns into a supply-chain attack vector — explicit cmd: is the right friction.
• Changing claude.api_key semantics or precedence.

Security considerations

The design is sound — it reuses the env-forward + cmd: pattern that claude.api_key already establishes. The risks are all in implementation details, not the shape:

Patterns to keep (and treat as canonical for future secret-forwarding work):

• Env-var forwarding over disk staging — guest images get snapshotted, copied, and backed up; secrets must not ride along.
• cmd: indirection over literal TOML values — TOML gets dotfile-synced, Debug-printed, and grepped.
• Lazy resolution at VM-start, not config-parse — secret-manager prompts only fire when needed, and the resolved string lives in memory only for the duration of prepare_env_forwarding. Do not memoize across instances.
• Recommending claude setup-token over access tokens — refresh-token-derived access tokens cannot refresh inside the guest (no writable credential store), so they silently expire mid-session and push users toward worse workarounds (paste-into-config, store-on-disk).
• Keeping ~/.claude/.credentials.json excluded — putting the refresh token on guest disk in a second location is strictly worse than env-var forwarding.
• No precedence flip — let the Claude CLI's documented precedence apply, instead of coop suppressing one credential. Avoids surprise billing routes and surprise auth identities.

Pitfalls to avoid in implementation:

1. SendEnv vs SetEnv. SendEnv=FOO forwards from the SSH client's process env. If achieved by mutating coop's own process env, the secret leaks into anything else coop spawns. Use SetEnv=NAME=value on the ssh CLI, or scope the env to the child ssh process only — never std::env::set_var. Add a test that asserts the host process env is unchanged after prepare_env_forwarding.
2. Guest AcceptEnv allowlist. Add CLAUDE_CODE_OAUTH_TOKEN explicitly. Do not take the shortcut of AcceptEnv * — that turns the guest into a sink for arbitrary host env.
3. Debug/log leakage. ClaudeConfig derives Debug (src/config.rs:447); literal oauth_token values would be printed verbatim. Either custom Debug that redacts, or explicitly document the risk and push hard toward cmd:. Also: resolve_cmd_value includes command stderr in error messages (src/config.rs:63-71) — a misbehaving cmd: script that echoes the token to stderr would land it in error output. Document that resolver scripts must not emit the secret on stderr.
4. No tracing of values. Mirror the existing tracing::debug!("Resolving secret via command") — no field name, no length, no truncated value.
5. cmd: = sh -c, i.e. arbitrary code execution. Each new cmd:-resolved field grows the blast radius of a malicious or compromised config file. Acceptable today (the config is user-owned), but the moment coop ever auto-loads project-local coop.toml, cmd: resolution must be gated on an explicit user-level trust decision. Worth a tripwire comment near the resolver for future contributors.
6. Claude CLI may persist the token guest-side. Verify empirically — if claude writes ~/.claude/.credentials.json inside the guest after first auth, the host's no-disk policy is moot in practice. Either accept it (guest disk = trust boundary) and document it, or provide a stop-time scrub. Do not claim "never written to disk" without checking.
7. Test fixtures must not look like real tokens. Use obvious fakes (cmd:echo fake-oauth) so secret scanners and pre-commit detectors do not flag the repo and so regex scrapes cannot false-positive.

Acceptance criteria

• claude.oauth_token config field, supports literal values and cmd: resolution
• CLAUDE_CODE_OAUTH_TOKEN forwarded into the guest without mutating coop's host process env (test asserts this)
• Guest sshd AcceptEnv allowlist explicitly includes CLAUDE_CODE_OAUTH_TOKEN (no AcceptEnv *)
• Resolved token never appears in tracing/log output at any level, and is not printed by Debug on ClaudeConfig
• Documented in README / config reference, including the access-token-vs-setup-token caveat and the pipe-into-secret-store recommendation
• Documented behavior of the Claude CLI inside the guest re: on-disk persistence of the OAuth token (verified empirically)
• Unit tests mirroring the api_key coverage (resolution, empty/failure paths), using obvious-fake token strings

[hbrodin]

Update: design discussion 2026-05-13

Reopening this with context from a design discussion. The original env-forward proposal has a gap that surfaced while reasoning about it.

Findings that change the design

1. ~/.claude/.credentials.json exists on guest disk after a normal claude login flow, confirmed by observation. The issue's central security claim — "env-var forwarding keeps the secret off the guest disk" — only holds if the CLI behaves differently when started with CLAUDE_CODE_OAUTH_TOKEN set (skipping the file write). That's unverified, and very plausibly false. If the CLI writes a credentials file regardless, the env-forward design ships a security story that doesn't match runtime reality.

2. Long-lived tokens via env are also undesirable, not just on-disk ones. The issue's recommended path (claude setup-token → stash → forward) creates a months-long credential whose blast radius on any leak is much larger than a session-bounded one. Avoiding long-lived tokens narrows the env-forward design to forwarding short-lived access tokens — which expire mid-session and push the UX backward.

Together these two facts retire the original design as proposed. Both of its security claims (no on-disk, short-lived only) become hard to sustain.

Alternative designs considered

Option A — File sync host → guest.
Read host credential (Keychain on macOS, ~/.claude/.credentials.json on Linux), drop it onto guest at ~/.claude/.credentials.json during coop start. Guest CLI handles refresh natively. Opt-in via claude.share_host_session = true. End state is identical to what the guest disk holds after manual /login today — we just skip the manual step. No new env plumbing.

Tradeoff: refresh token lives on guest disk for VM lifetime. Same surface as today's manual flow, but materialized at boot instead of after first interactive auth.

Option B — Host-side auth-injecting relay.
coop runs a small HTTP proxy on the host, bound to 127.0.0.1. SSH reverse-forward makes that port reachable from inside the guest. Guest's Claude CLI is started with ANTHROPIC_BASE_URL=http://127.0.0.1:N. Each request reaches the relay without auth; the relay injects an Authorization: Bearer … header from the host credential and forwards to api.anthropic.com. Token never enters guest env, disk, or process memory.

Refresh happens on the host. Standard OAuth 2.0 — Claude Code uses Authorization Code + PKCE, so the token endpoint URL and client_id are public (PKCE public clients have no client secret). The refresh call is just grant_type=refresh_token. Not a reverse-engineering exercise — same de-facto-stable contract every other OAuth provider offers.

The refresh problem and why it's the central question

The mechanical refresh is standard. The coexistence question is what decides whether Option B works:

• If Anthropic doesn't rotate refresh tokens on each refresh, the host CLI and the relay can both hold the same refresh token and refresh independently. Clean.
• If Anthropic rotates refresh tokens (RFC 6749 §10.4 recommends this), only one entity holds "the" refresh token at any moment. Once the relay refreshes, the host CLI's stored refresh token is invalidated — host `claude` breaks until the user re-logs in. Same problem in the other direction.

If rotation happens, Option B viability requires either:

• writing the new refresh token back to host store after every refresh (Keychain writes need consent ACLs, file writes race with host CLI), or
• accepting host/guest divergence as a known limitation.

Empirical work that decides the design

Three experiments, in order of importance:

1. Refresh token rotation test. Read the refresh token from host Keychain, POST a standard OAuth refresh, then POST a second refresh with the original refresh token. If the second succeeds → no rotation, Option B is clean. If it returns `invalid_grant` → rotation, Option B has to write back or accept divergence. ~10 minutes.

2. `ANTHROPIC_BASE_URL` behavior in a guest with no credentials. Boot a guest, set `ANTHROPIC_BASE_URL` to a netcat/Python listener, run `claude` with no `ANTHROPIC_API_KEY`, no `CLAUDE_CODE_OAUTH_TOKEN`, no `.credentials.json`. Observe: does it start? does it short-circuit to "not logged in"? does it write a credentials file? ~15 minutes.

3. Streaming + tool-use round-trip through a forwarding proxy. Once we know the CLI talks to the relay, verify SSE streaming and tool-use responses pass cleanly. ~20 minutes.

Where this leaves issue scope

The original env-forward design is parked. Two viable replacements (A — file sync; B — host relay) are on the table. The choice between them hinges on the rotation experiment (1) and the base-URL experiment (2):

• If (1) shows rotation and the user values host/guest auth coexistence: Option A wins by default, since Option B introduces friction that's worse than just letting the guest CLI handle refresh.
• If (1) shows no rotation and (2) shows the CLI behaves cleanly with just `ANTHROPIC_BASE_URL`: Option B is the honest "credentials never on guest" design and should be preferred.
• If (2) shows the CLI writes a credentials file even with `ANTHROPIC_BASE_URL`: Option B's security claim collapses too, and we converge on Option A or close the issue.

Next step is running the experiments.

[hbrodin]

Cross-link with #87. Independent of which credentialing approach lands here, Claude Code's TUI gates the onboarding wizard on ~/.claude.json: hasCompletedOnboarding, not on the presence of CLAUDE_CODE_OAUTH_TOKEN. Whatever design we pick, the end-to-end UX check should include whether the TUI completes onboarding cleanly under it.