feat(secrets): the OS keychain as a place a credential can live, with .env still winning

[eaitbrahim]

Refs #437 (D4). Milestone: Desktop distribution (#18).

The next thing blocking a first run: after setup creates a config, a database and a rule library, keel fetch needs a CDP key — and a desktop user has no terminal, no editor open on a dotfile, and no way to create a .env.

Three sources, and the order is the whole design

	source	who sets it
1	the real environment	whoever launched the process
2	the .env file	the operator, in a folder they chose
3	the OS keychain	the first-run wizard

.env sits above the keychain deliberately. Every pre-existing deployment therefore behaves byte-identically — the keychain only answers where the file was silent — and a value the operator can see beats one they cannot when the two disagree. A stale keychain entry silently overriding an edited .env is a debugging session nobody should have to have.

Nothing migrates. No credential is moved out of a file, and delete_secret never edits one: a .env is the operator's own artifact, and deleting a line out of a file someone hand-wrote, on their behalf, is not something a credential command should do.

The source is carried, and that is not decoration

"keel cannot see your key" and "keel is using a different key than the one you just typed" are the two support questions this exists to make answerable, and only the source tells them apart.

So credentials set reads the value back through the same resolver a real caller uses and says when something shadows what was just stored:

$ keel credentials set CDP_API_KEY --stdin
stored CDP_API_KEY in the OS keychain.
note: keel will still read CDP_API_KEY from your .env file, which takes precedence.
      Remove it there if you meant the keychain value to be used.

Otherwise the operator finds out at the first request that used the wrong key.

Nothing here prints a value

• __repr__ is overridden. A dataclass that prints its own secret in a traceback has published it to every log that traceback reaches — and tracebacks travel further than anything else in a program.
• credentials show reports set/unset and the source. Nothing else.
• credentials set refuses to take the value as an argument. A secret on a command line is in shell history, in ps output for every other process on the machine while it runs, and in any terminal recording. It prompts with echo off, or reads stdin. Pinned off the function signature, so a --value option added later as a convenience fails a test rather than shipping.

A machine with no usable backend is detected, not discovered: keyring always imports and selects fail.Keyring, whose every operation raises. store_secret refuses up front and names the .env alternative, because a form that appears to save a credential and does not is worse than one that says no.

Verified in a frozen bundle, not assumed

keyring selects its backend dynamically — exactly the kind of thing freezing breaks. So it was built and run:

$ ./keel credentials show
keychain: available (service 'keel-trader')
precedence: environment, then .env, then the keychain.

$ echo "frozen-secret-abc" | ./keel credentials set KEEL_FROZEN_PROBE --stdin
stored KEEL_FROZEN_PROBE in the OS keychain.       # round-tripped through the real macOS Keychain
                                                    # 0 occurrences of the value in any output

Tests do not touch the real keychain

CI has no backend, and a suite that wrote to a developer's login keychain would be leaving state on their machine to make an assertion.

One of them started out patching over the very code it claimed to test — _from_keychain replaced by a stub that never raised. It now patches keyring.get_password instead, with a second test proving that path is actually reached.

Verification

4064 passed, 3 skipped (26 new). ruff check clean repo-wide, mypy clean over keel + packages.

uv.lock moves with the new dependency — the inverse of the omission that shipped 0.10.0 DIRTY.

Next

The browser form over this, so the first-run wizard can capture a key without a terminal — and then market data, which is the last mechanical step before a paper deployment actually does something.

🤖 Generated with Claude Code