flynn/docs/plans/2026-02-15-credential-system-v2-api-and-oauth-checklist.md

Credential System v2 (API + OAuth/token) — Implementation Checklist

Date: 2026-02-15

Parent roadmap: docs/plans/2026-02-15-openclaw-gap-roadmap.md

Goal: Close the gap item "OAuth subscription auth" by supporting both API-key credentials and OAuth/token-based credentials (provider-specific) with consistent UX, per-tier control, and deterministic resolution.

Scope Summary

• Add auth_mode per tier (default/fast/complex/local and any local_providers entries).
• Keep backward compatibility with existing use_oauth behavior.
• Add stored credential support where it currently doesn't exist:
  • OpenAI: stored API key (OAuth already exists)
  • Anthropic: stored auth token (API key already exists)
• Improve doctor output to surface which auth sources are present (without revealing secrets).

Non-goals (explicitly out of scope for this checklist):

• Inventing an Anthropic OAuth device flow.
• Building new provider integrations (Vercel/MiniMax/etc.).

Current Baseline (important constraints)

• OpenAI OAuth uses the ChatGPT/Codex backend endpoint (SSE) and currently does not support tools on that path.
  • Source: src/models/openai.ts
• Anthropic supports apiKey and authToken in AnthropicClientConfig.
  • Source: src/models/anthropic.ts
• Stored credentials live at ~/.config/flynn/auth.json.
  • Source: src/auth/openai.ts, src/auth/anthropic.ts

Design Decisions

1) New config field: auth_mode

Add auth_mode to the per-tier model config:

• auto (default)
• api_key
• oauth

oauth is interpreted as "OAuth/token mode" (provider-specific). For Anthropic, that means auth_token.

2) Backward compatibility: use_oauth

Preserve use_oauth as a compatibility alias.

Recommended rule:

• If auth_mode is set: it wins.
• Else if use_oauth: true: treat as auth_mode: oauth.

3) Credential resolution order

For each provider, resolve the required credential type by trying:

1. config (api_key / auth_token)
2. env var
3. auth store (~/.config/flynn/auth.json)

auth_mode controls which credential type is required.

PR Breakdown (atomic, test-backed)

PR 1 — Schema + docs: per-tier auth_mode

Checklist:

• Add auth_mode to modelConfigBaseSchema in src/config/schema.ts.
• Update src/config/schema.test.ts to cover defaults + validation.
• Update README.md config examples (brief mention).
• Update config/default.yaml comment/help text (brief mention).

Acceptance:

• Config parses with no changes (defaults preserved).
• Setting auth_mode: oauth or auth_mode: api_key validates.

Tests:

• pnpm test:run src/config/schema.test.ts

---

PR 2 — OpenAI auth store: add API-key storage

Goal: allow OpenAI to run without api_key in YAML.

Checklist:

• Extend src/auth/openai.ts AuthStore shape to allow openai.api_key alongside existing OAuth info.
• Add functions:
  • loadStoredOpenAIApiKey()
  • storeOpenAIApiKey(key)
  • clearOpenAIApiKey()
  • getOpenAIApiKey() (env override + store)
• Keep existing OAuth store code working unchanged.
• Add/extend tests for new store functions.

Files:

• src/auth/openai.ts
• src/auth/openai.test.ts (or add if missing)

Acceptance:

• Stored OpenAI API key is written to ~/.config/flynn/auth.json with 0600 permissions.
• OAuth entry remains backward compatible.

Tests:

• pnpm test:run src/auth/openai.test.ts

---

PR 3 — Anthropic auth store: add auth-token storage

Goal: allow auth_token to be stored and selected with auth_mode: oauth.

Checklist:

• Extend src/auth/anthropic.ts auth store shape to include auth_token.
• Add functions:
  • loadStoredAnthropicAuthToken()
  • storeAnthropicAuthToken(token)
  • clearAnthropicAuthToken()
  • getAnthropicAuthToken()
• Extend src/auth/anthropic.test.ts.

Files:

• src/auth/anthropic.ts
• src/auth/anthropic.test.ts

Acceptance:

• auth_token can be stored and resolved without being present in YAML.

Tests:

• pnpm test:run src/auth/anthropic.test.ts

---

PR 4 — CLI commands for managing new stored credentials

Checklist:

• Add flynn openai-key command (store API key in auth.json).
• Extend flynn anthropic-auth to support storing either API key or auth token:
  • recommended: flynn anthropic-auth --token OR flynn anthropic-token
• Update src/cli/index.ts registration.

Files:

• src/cli/openai-key.ts (new)
• src/cli/anthropic-auth.ts (modify)
• src/cli/index.ts

Acceptance:

• CLI can store credentials without printing them.
• Re-running commands detects existing stored credentials and exits cleanly.

Tests:

• Add targeted unit tests if the CLI layer has existing patterns; otherwise validate via integration tests where feasible.

---

PR 5 — TUI /login UX: OpenAI choice (OAuth vs API key) + Anthropic token

Checklist:

• Update /login openai in src/frontends/tui/minimal.ts:
  • Present a simple prompt: "1) OAuth device flow 2) Paste API key"
  • Store selected credential via auth store
• Add /login anthropic in src/frontends/tui/minimal.ts:
  • "1) Paste API key 2) Paste auth token"
• Keep existing /login github and /login zai behavior intact.

Files:

• src/frontends/tui/minimal.ts
• src/frontends/tui/commands.ts (if command parsing needs to accept new provider)

Acceptance:

• TUI can store OpenAI API key or OAuth token.
• TUI can store Anthropic API key or auth token.

Tests:

• Add or extend minimal TUI tests as needed (existing suite patterns exist for model switching).

---

PR 6 — Model factory: enforce auth_mode per tier

This is the core runtime change.

Checklist:

• Update src/daemon/models.ts:
  • Read cfg.auth_mode (or inferred from use_oauth) per tier.
  • For OpenAI:
    • auth_mode=oauth: configure OpenAIClient({ useOAuth: true }) and verify OAuth tokens exist.
    • auth_mode=api_key: configure OpenAIClient({ apiKey: resolvedKey }).
  • For Anthropic:
    • auth_mode=oauth: require auth token (config/env/store).
    • auth_mode=api_key: require API key (config/env/store).
  • For other providers:
    • define behavior explicitly (likely api_key only unless provider already supports token-style auth).
  • Ensure error messages name the expected auth type and remediation.

Files:

• src/daemon/models.ts
• potentially src/models/openai.ts (if you decide to unify API key vs OAuth selection naming)

Tests:

• src/daemon/clientFactory.test.ts
  • auth_mode precedence over use_oauth
  • auto -> api key path
  • oauth -> token path
  • correct failures when missing

Acceptance:

• Selecting auth_mode changes runtime behavior deterministically.

---

PR 7 — Doctor: report auth source availability

Checklist:

• Extend checkModelConnectivity in src/cli/doctor.ts to reflect auth_mode:
  • If auth_mode=api_key, warn/fail when API key is absent from config/env/store.
  • If auth_mode=oauth, warn/fail when OAuth/token is absent.
  • If auth_mode=auto, keep current behavior but improve messaging.
• Add tests in src/cli/doctor.test.ts.

Acceptance:

• Doctor output tells user what to do next (command name + env var) without exposing secrets.

Final Integration Checks

• pnpm typecheck
• pnpm test:run
• Update docs/plans/state.json entry for this checklist once implemented (status, summary, test status).