feat: OS-keychain API key storage (ROADMAP Movement IV groundwork)

[evangress]

Why

Toril has no .env and no API key handling — a tree-wide grep for api_key, ANTHROPIC, OPENAI, dotenv, process.env, std::env::var and sops turns up only TAURI_DEV_HOST in vite.config.ts and a planned feature in ROADMAP Movement IV. Nothing in Toril talks to a network today.

So this is a greenfield decision made ahead of the AI layer that will consume it, rather than a refactor of anything existing.

Design: docs/superpowers/specs/2026-07-27-windows-install-and-secret-store-design.md (merged in #32)

The load-bearing decision: no getter

keystore::SecretStore::get() exists so Movement IV's provider calls can use a key from Rust. It is never registered with invoke_handler. The webview can learn whether a key is set; it has no call available to learn what it is.

This is why the design beats the two alternatives that were on the table:

Option	Why not
System environment variables	A setx value is plaintext-readable by any process running as that user, appears in child-process environments and crash dumps, cannot be set from inside the app, and needs a relaunch.
SOPS	Built for secrets committed to a repo for a deployment pipeline. Needs an age/GPG key already on the machine — chicken-and-egg — plus a CLI install.
OS keychain ✅	DPAPI/Keychain/Secret-Service encrypted at rest, settable in-app, zero user setup.

But the storage backend is not where the security lives. §3.3 already treats webview content as untrusted and sanitizes it. Keeping the key on the Rust side means a future sanitizer bypass degrades to a rendering bug rather than a stolen credential — the property comes from the API shape. The invariant is stated in three places that would each have to be edited to break it: the absent registration, the comment at the registration site in lib.rs, and the ipc.ts docstring telling the next reader there is nothing to call.

Structure

src/ui/secrets.ts        masked input, "Configured / Not set". Never holds a key.
      │ invoke()
commands/secrets.rs      4 commands. No getter.
      │
crates/keystore          SecretStore trait; OsKeychain + MemoryStore.
      │
keyring → Credential Manager / Keychain / Secret Service

• Provider is a closed enum (Anthropic, OpenAi), not a free-text id, so a typo cannot silently create an orphaned keychain entry. Ollama is deliberately absent: it is local and unauthenticated, and needs a host URL rather than a secret.
• Validation rejects control characters and line breaks — those would corrupt an HTTP header once Movement IV sends the key, so entry is the honest place to catch them. Length bounds (8..=1024) are deliberately loose and provider-agnostic; a hard-coded sk-ant- prefix check would age badly.
• clear() is idempotent — pressing Clear twice is not an error the user has to interpret.
• zeroize wraps the in-flight key so it is overwritten on drop rather than left in freed heap.

Dependencies (CLAUDE.md §2)

Both checked against crates.io before adoption, not assumed:

Crate	Version	Last publish	Recent downloads	License	Publisher
keyring	4.1.5	2026-07-14	7.08M	MIT OR Apache-2.0	open-source-cooperative
zeroize	1.9.0	2026-06-12	149M	Apache-2.0 OR MIT	RustCrypto

Gates

cargo test -p keystore (11) added to the CI matrix — ninth logic crate. tests/secrets.test.ts (9). Full suite: 210 frontend, 97 Rust, cargo fmt --all --check clean, clippy clean in our code (all remaining warnings are inside the vendored glib, as §8 predicts).

The frontend gate pins the security-relevant behavior rather than form mechanics: the field is type=password, it is blanked after a successful save, configured state comes from the backend rather than a cached key, and a backend rejection surfaces instead of the row claiming success.

What is deliberately NOT tested

OsKeychain itself has no automated test. It needs a logged-in desktop session, and CI's Linux runners have no Secret Service — a test there could only fail or silently skip, and a silently-skipping test reads as coverage without being coverage. The MemoryStore suite pins the contract instead. This is stated in the CI comment and CLAUDE.md §8 rather than left to be rediscovered.

Outstanding — on-device verification

• Set a key, restart Toril, confirm has_api_key still reports it (proving it survived in Credential Manager, not process memory).
• Clear a key, confirm it disappears from rundll32.exe keymgr.dll,KRShowKeyMgr, and that Clear twice does not error.

Scope

This branch stores keys. Nothing sends an HTTP request to any provider — that is Movement IV branch 20.

🤖 Generated with Claude Code