RFC: unify credential storage for desktop + headless (pure-Node CredentialStore)

[Astro-Han]

Problem

Provider API keys are stored via Electron safeStorage (apps/desktop/src/main/credential-store.ts), an Electron-only API. The rest of @maka/runtime is pure-Node and Electron-free.

This blocks first-class headless mode (see #31): a pure-Node CLI / eval harness / third-party caller running the same runtime outside Electron cannot decrypt the existing credentials. connectionStore (model/connection config) is already pure-Node in @maka/storage and reusable; only the secret is trapped behind safeStorage.

This is a global, security-sensitive change touching desktop OAuth, connection tests, and bots. It needs owner + collaborator sign-off — not to be implemented unilaterally. This RFC is to align before any code.

Threat model

Per SECURITY.md, the OS user account is the only real enforcement boundary against an adversarial LLM/tool. A tool running as the user can already read files, run commands, hit the network, and read env. Against that threat, at-rest encryption buys little. safeStorage meaningfully protects only secondary threats: offline disk theft, other OS users, backup/cloud-sync leakage, and (macOS) other-app boundary. It is also not cross-platform consistent (Electron docs: Windows DPAPI doesn't stop same-user apps; Linux falls back to basic_text without a secret store).

Prior art (verified)

Tool	On disk	Format	Perms	Keychain
Codex CLI	~/.codex/auth.json (file/keyring/auto)	plaintext JSON	0600 (on create)	optional
OpenCode	~/.local/share/opencode/auth.json	plaintext JSON	0600	no
Claude Code	macOS Keychain; Linux/Win ~/.claude/.credentials.json	keychain / plaintext	0600	macOS only
aider	env / .env / yaml	plaintext	umask	no
gh / aws / docker	keyring / plaintext / base64	mixed	—	partial

The dominant convention for CLI agents is a local 0600 JSON file; keychain-led tools (Claude Code, gh) keep a same-shape 0600 file as the headless fallback.

Proposed design

A single pure-Node CredentialStore interface in @maka/storage, used by desktop + CLI + harness + third-party. Resolution precedence:

env override (MAKA_* / provider-native)
  > credential_provider command (first-class extension: 1Password / Vault / keychain)
  > JSON file store (default)
  > safeStorage one-time importer (migration only)

• File store: user data dir, dir 0700 / file 0600, plaintext (no base64 theater), atomic write, schema version. Windows: ACL or best-effort + clear warning.
• credential_provider: returns structured JSON, supports expires_at, has a timeout, must not write secrets to stderr, cached by expiry. This is where keychain / 1Password / Vault live — first-class, not default.
• safeStorage: kept only as a one-time importer — on desktop start, decrypt legacy creds → write into the new store → mark legacy.
• Third-party: callers can inject a custom CredentialStore (not forced to read the global user file).

Rejected alternatives (with reasons)

• helper-first as default — git/docker/aws/Claude-Code prove helpers are a good extension point, not a good default; wrapping "read a file" in a process protocol adds spawn/timeout/stderr-leak/caching/quoting/diagnostic cost for the common case.
• shell out to OS keychain from Node (security/secret-tool/cmdkey) — cross-platform semantics inconsistent, can block on user input, Windows has no clean read-to-stdout. OK as an optional helper example, not the core store.
• native keychain lib (keytar archived; @napi-rs/keyring) — reintroduces native binary / libsecret/DBus / ABI / headless-packaging deps, defeating pure-Node. Optional, never the sole store.
• credential broker over socket — makes headless depend on a running desktop daemon; defeats first-class headless.

Security trade-off (stated honestly)

We trade some at-rest encryption for default composability/debuggability/headless. The main new exposure: a plaintext key getting carried off by iCloud / Time Machine / Dropbox / dotfile sync. Mitigations: keep the store outside common sync paths, document it, unified redaction across logs / crash reports / debug dumps / migration backups.

Open questions

1. Do we accept plaintext-at-rest as the default, given the threat model — or require credential_provider/keychain encryption on by default where available?
2. Token model: static API key vs refresh token vs short-lived access token — the store should not treat every secret as a never-expiring string.
3. Multi-account / multi-endpoint key shape: provider + account/profile + base_url/org/tenant.
4. Windows permission handling (no 0600 equivalent).
5. Migration/rollout: silent import vs explicit user step; what happens to the legacy safeStorage entries.

---

Driver: #31 · Prior art: Codex CLI, OpenCode, Claude Code, aider · Refs: git credential helpers, aws credential_process, Electron safeStorage

[Astro-Han]

Update — pre-PR research done; direction confirmed, scope clarified.

Did a deep best-practice pass (5 source-verified research angles + Codex consults) and grounded it in the actual code. Direction holds: file-first, pure-Node, off safeStorage. Two clarifications change the plan:

1. The real surface is 5 safeStorage-bound secret stores, not 1 — and the split is intentional:

Store	Mechanism	Secret
credentials.json	SafeStorageCredentialStore	API keys, bot tokens, proxy/gateway/tavily
4× OAuth token files	per-provider service (claude / codex / antigravity / cursor)	{access_token, refresh_token, expires_at, ...}, already 0600, refresh logic lives in each service, never crosses IPC

So "single CredentialStore" means a shared pure-Node sealing primitive + file helpers (atomic write, 0600-every-write, dir 0700, cross-process lock) reused by all stores — NOT one merged file. The API-key/OAuth partition stays.

2. This splits cleanly into two PRs, and the headless lab (#31) only needs the first:

• PR A (unblocks RFC: headless agent experiment lab (@maka/lab) #31, low risk): migrate credentials.json (API keys) off safeStorage; move the CredentialStore interface into @maka/storage; pure-Node file backend with a SecretSealer seam (plaintext-0600 default; OS-keychain via @napi-rs/keyring is a pure addition later); versioned schema (unknown version → fail closed); desktop-side one-time importer that tombstones the old secret (no dual-active); drop the dead setOAuthToken/getOAuthToken. The lab runs benchmarks on API-key connections, so this alone unblocks it.
• PR B (separate, higher risk): migrate the 4 OAuth services off safeStorage + the cross-process refresh lock (desktop + headless both holding one refresh token = the Claude Code #48786 logout race) + headless-usable refresh. Only needed when the lab must use subscription OAuth.

Verified refinements baked into both: store stays in the data dir (Maka's userData already qualifies; headless must resolve the same path — high-risk detail); 0600 on every write not just create (Codex/Gemini CVE class); Windows chmod is a no-op → ACL/DPAPI deferred but not faked; redact-by-construction for secrets in logs/crash; expose the TS CredentialStore API to third parties, never the raw file format.

Proceeding with PR A first.

[Astro-Han]

Plan: PR A now, PR B later — rationale.

Splitting #32 into two PRs.

PR A — #33 (open): migrate the API-key store (credentials.json) off safeStorage to the pure-Node FileCredentialStore.

Why PR A first:

• Smallest change that unblocks the headless lab (RFC: headless agent experiment lab (@maka/lab) #31) — benchmarks run on API-key connections.
• Carries the contentious decision (at-rest plaintext-0600); better to settle it before building more on top.
• Lowest risk: the API-key store is write-rare and has no live refresh logic.

PR B — later: migrate the 4 OAuth subscription token files (claude / codex / antigravity / cursor) off safeStorage, plus the cross-process refresh lock (desktop + headless both holding one refresh token = the Claude Code #48786 logout race).

When / why deferred:

• Not on RFC: headless agent experiment lab (@maka/lab) #31's critical path — subscription OAuth is rate-limited and not ideal for benchmarking; the lab uses API-key connections.
• It's the higher-risk half: it touches live OAuth refresh in 4 services + cross-process concurrency. It deserves a clean review on the settled PR-A foundation.
• It will be a flat PR off main after feat(credentials): pure-Node CredentialStore for headless (#32, PR A) #33 merges, reusing/extending PR A's @maka/storage primitives and adding the cross-process lock.

[Astro-Han]

#32 is no longer useful as an open tracking issue.

PR A was completed by #33: credentials.json now uses the shared pure-Node FileCredentialStore, which removes the credential blocker for the current API-key based headless / autonomous-task path.

The old headless-lab framing in #31 has been superseded by #45, which is now the main design thread for Autonomous Task Maka. The remaining OAuth subscription token work (claude / codex / antigravity / cursor token files plus cross-process refresh locking) is not on the current critical path and should not be carried as debt under this broad RFC. If #45 later needs subscription OAuth in autonomous/headless mode, we can open a narrow follow-up issue or PR for that specific need.

Closing this RFC as resolved for the current headless path.