872b0adb48
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and dev/ (ADRs, architecture, extension guides, proposals). Updated docs/README.md index to reflect new paths.
180 lines
9.1 KiB
Markdown
180 lines
9.1 KiB
Markdown
# Claude Code Auth Compliance Research
|
|
|
|
Date: 2026-04-10
|
|
|
|
## Executive Summary
|
|
|
|
Anthropic's current public guidance draws a hard line:
|
|
|
|
- Native Anthropic apps, including Claude Code, may use Claude subscription authentication.
|
|
- Third-party tools should prefer API key authentication through Claude Console or a supported cloud provider.
|
|
- Apps that misrepresent their identity, route third-party traffic against subscription limits, or otherwise violate Anthropic terms are explicitly prohibited.
|
|
|
|
For GSD2, the safe path is:
|
|
|
|
1. Treat local Claude Code as an external authenticated runtime.
|
|
2. Never ask GSD users to sign into Claude subscriptions through GSD-managed Anthropic OAuth.
|
|
3. Never exchange Claude.ai subscription OAuth into a bearer token and call Anthropic APIs as if GSD were Claude Code.
|
|
4. If GSD needs direct Anthropic API access, require a Claude Console API key, Bedrock, Vertex, or another explicitly supported provider path.
|
|
|
|
## What Anthropic Explicitly Allows
|
|
|
|
### 1. Claude Code itself can use Claude subscription auth
|
|
|
|
Anthropic's help center says Claude Pro/Max users should install Claude Code, run `claude`, and "log in with the same credentials you use for Claude." It also says this connects the subscription directly to Claude Code, and that `/login` is the way to switch account types. The Team/Enterprise article gives the same flow for org accounts.
|
|
|
|
Implication for GSD2:
|
|
|
|
- Letting users authenticate inside the real `claude` CLI is aligned with Anthropic's documented flow.
|
|
- Detecting `claude auth status` and routing work through the local CLI or official Claude Code SDK is the lowest-risk pattern.
|
|
|
|
### 2. Claude Code supports both subscription OAuth and API credentials
|
|
|
|
Anthropic's Claude Code docs say supported auth types include Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth. The docs also define auth precedence:
|
|
|
|
1. cloud provider credentials
|
|
2. `ANTHROPIC_AUTH_TOKEN`
|
|
3. `ANTHROPIC_API_KEY`
|
|
4. `apiKeyHelper`
|
|
5. subscription OAuth from `/login`
|
|
|
|
Implication for GSD2:
|
|
|
|
- If GSD2 shells out to or embeds Claude Code, it should respect Claude Code's own credential selection instead of inventing a parallel Anthropic OAuth flow.
|
|
- `apiKeyHelper` is the clean enterprise escape hatch when an org wants dynamic short-lived keys without handing raw API keys to the tool.
|
|
|
|
### 3. Anthropic commercial usage is available through API keys and supported cloud providers
|
|
|
|
Anthropic's commercial terms govern API keys and related Anthropic services for customer-built products, including products made available to end users. The authentication docs for teams recommend Claude for Teams/Enterprise, Claude Console, Bedrock, Vertex, or Microsoft Foundry.
|
|
|
|
Implication for GSD2:
|
|
|
|
- If GSD2 is acting as a product for users, direct Anthropic access should be through commercial auth paths, not subscription-token reuse.
|
|
|
|
## What Anthropic Explicitly Warns Against
|
|
|
|
Anthropic's current "Logging in to your Claude account" article is the clearest statement:
|
|
|
|
- Subscription plans are for ordinary use of native Anthropic apps, including Claude web, desktop, mobile, and Claude Code.
|
|
- "The preferred way" for third-party tools, including open-source projects, is API key auth through Claude Console or a supported cloud provider.
|
|
- If you're building a product, application, or tool for others, use API key auth through Claude Console or a supported cloud provider.
|
|
- Tools that misrepresent identity, route third-party traffic against subscription limits, or otherwise violate terms are prohibited.
|
|
|
|
Anthropic's consumer terms add two more constraints:
|
|
|
|
- Users may not share account login info, API keys, or account credentials with anyone else.
|
|
- Except when accessing services via an Anthropic API key or where Anthropic explicitly permits it, users may not access the services through automated or non-human means.
|
|
|
|
Implication for GSD2:
|
|
|
|
- A GSD-managed Anthropic OAuth flow for subscription accounts is high risk.
|
|
- Reusing user Claude subscription credentials inside GSD's own API client is high risk.
|
|
- Any flow that makes Anthropic believe requests come from Claude Code when they actually come from GSD infrastructure is out of bounds.
|
|
|
|
## Current GSD2 Findings
|
|
|
|
### Low-risk / aligned pieces
|
|
|
|
- `src/resources/extensions/claude-code-cli/index.ts`
|
|
Registers `claude-code` as an `externalCli` provider and routes through Anthropic's official `@anthropic-ai/claude-agent-sdk`.
|
|
- `src/resources/extensions/claude-code-cli/readiness.ts`
|
|
Only checks local CLI presence and auth state via `claude --version` and `claude auth status`.
|
|
- `src/onboarding.ts`
|
|
TUI onboarding already removed Anthropic browser OAuth and labels local Claude Code routing as the TOS-compliant path.
|
|
- `src/cli.ts`
|
|
Migrates users from `anthropic` to `claude-code` when the local CLI is available.
|
|
|
|
These are directionally correct because GSD is using the user's own local Claude Code installation as the authenticated Anthropic surface.
|
|
|
|
### Medium/high-risk pieces
|
|
|
|
- `packages/pi-ai/src/utils/oauth/anthropic.ts`
|
|
Still implements a first-party-looking Anthropic OAuth flow for GSD itself using `claude.ai/oauth/authorize` and `platform.claude.com/v1/oauth/token`.
|
|
- `packages/pi-ai/src/utils/oauth/index.ts`
|
|
Still registers `anthropicOAuthProvider` as a built-in OAuth provider.
|
|
- `src/web/onboarding-service.ts`
|
|
Still advertises Anthropic as `supportsOAuth: true`, which keeps the web onboarding surface inconsistent with the TUI stance.
|
|
- `packages/daemon/src/orchestrator.ts`
|
|
Reads Anthropic OAuth credentials from `~/.gsd/agent/auth.json`, refreshes them, and then uses the access token for Anthropic API calls.
|
|
|
|
The key risk is not just stale UI. The repo still contains code paths where GSD can behave as a third-party Anthropic OAuth client and then convert that credential into direct API access.
|
|
|
|
## Recommended Policy For GSD2
|
|
|
|
Adopt this as the repo rule:
|
|
|
|
- Claude subscription auth is allowed only inside Anthropic-owned surfaces:
|
|
- the `claude` CLI
|
|
- Claude Code SDK when it is backed by the local authenticated Claude Code install
|
|
- other Anthropic-documented native flows
|
|
- GSD2 must not implement its own Anthropic subscription OAuth flow for end users.
|
|
- GSD2 must not persist Anthropic subscription OAuth tokens for later API use.
|
|
- GSD2 must not send Anthropic API traffic using subscription OAuth tokens obtained by GSD.
|
|
- GSD2 may support Anthropic direct access only via:
|
|
- `ANTHROPIC_API_KEY`
|
|
- Claude Console API keys stored in auth storage
|
|
- `apiKeyHelper`
|
|
- Bedrock / Vertex / Foundry
|
|
- the local Claude Code provider
|
|
|
|
## Recommended Implementation Plan
|
|
|
|
### Option A: Safe minimal compliance cleanup
|
|
|
|
1. Remove Anthropic from the built-in OAuth provider registry.
|
|
2. Change web onboarding so Anthropic is API-key only.
|
|
3. Keep `claude-code` as the recommended path when `claude auth status` succeeds.
|
|
4. Add explicit UI copy:
|
|
- "Claude subscription users: sign into the local Claude Code app/CLI, not GSD."
|
|
5. Block migrations or code paths that convert Anthropic OAuth credentials into API auth for GSD-managed requests.
|
|
|
|
This is the fastest path to align the repo with Anthropic's published guidance.
|
|
|
|
### Option B: Enterprise-safe Anthropic support
|
|
|
|
Support three distinct Anthropic modes:
|
|
|
|
- `claude-code`
|
|
Uses the local authenticated `claude` runtime only.
|
|
- `anthropic-api`
|
|
Uses Console API keys or `apiKeyHelper`.
|
|
- `anthropic-cloud`
|
|
Uses Bedrock, Vertex, or Foundry.
|
|
|
|
Then remove any ambiguous `anthropic` browser-login path entirely.
|
|
|
|
This is the best long-term UX because it separates:
|
|
|
|
- subscription-native usage
|
|
- API-billed usage
|
|
- cloud-routed usage
|
|
|
|
## Concrete Repo Follow-ups
|
|
|
|
1. Delete or disable `packages/pi-ai/src/utils/oauth/anthropic.ts`.
|
|
2. Remove `anthropicOAuthProvider` from `packages/pi-ai/src/utils/oauth/index.ts`.
|
|
3. Change `src/web/onboarding-service.ts` so Anthropic does not claim OAuth support.
|
|
4. Audit `packages/daemon/src/orchestrator.ts` and any other callers that treat Anthropic OAuth access tokens as API credentials.
|
|
5. Update docs/UI labels to prefer `anthropic-api` for direct API usage and `claude-code` for subscription usage.
|
|
6. Add tests that fail if Anthropic subscription OAuth is reintroduced through the onboarding/provider registry.
|
|
|
|
## Decision Rule
|
|
|
|
If a proposed GSD2 feature needs Anthropic access, ask one question:
|
|
|
|
"Is GSD calling Anthropic as GSD, or is GSD delegating to the user's already-authenticated local Claude Code runtime?"
|
|
|
|
- If GSD is calling Anthropic as GSD: require API key or supported cloud auth.
|
|
- If GSD is delegating to local Claude Code: acceptable, as long as GSD does not intercept, mint, or replay subscription credentials itself.
|
|
|
|
## Sources Reviewed
|
|
|
|
- Anthropic Help Center: "Logging in to your Claude account"
|
|
- Anthropic Help Center: "Using Claude Code with your Pro or Max plan"
|
|
- Anthropic Help Center: "Use Claude Code with your Team or Enterprise plan"
|
|
- Anthropic Help Center: "Managing API key environment variables in Claude Code"
|
|
- Anthropic Help Center: "API Key Best Practices: Keeping Your Keys Safe and Secure"
|
|
- Claude Code Docs: getting started / authentication / team / settings / IAM
|
|
- Anthropic Commercial Terms of Service
|
|
- Anthropic Consumer Terms of Service
|
|
- Anthropic Usage Policy
|