`config-keychain` now exists. It is the module spec **0043** sketched, and it answers that spec's Q1 and Q2 — but it diverges from the design sketch in two places that matter to keryx, so this is a "pick it up and decide", not a drop-in. Everything below was checked against keryx `main` at `1b374e7` and the adapter's `main` on 2026-07-28. --- ## What keryx does today `pkg/oauth/store.go` walks a private ladder — env var, then keychain, then config file — and mirrors it in `Save`, which writes to the keychain if one is available and **falls back to writing the token into the config file in plaintext** if not. Five `oauth.Store` values declare that triple: | Package | Account | Config key | |---|---|---| | `internal/publish/instagram` | `instagram-access-token` | `platforms.instagram.access_token` | | `internal/publish/tiktok` | `tiktok-refresh-token` | `platforms.tiktok.refresh_token` | | `internal/publish/youtube` | `youtube-refresh-token` | `platforms.youtube.refresh_token` | | `internal/publish/linkedin` | `linkedin-access-token` | `platforms.linkedin.access_token` | | `internal/publish/linkedin` | `linkedin-refresh-token` | `platforms.linkedin.refresh_token` | `pkg/credscan`'s own package doc records what that fallback costs: *"three live OAuth tokens sat in the file it had just read"*. ## What the adapter is [`gitlab.com/phpboyscout/go/config-keychain`](https://gitlab.com/phpboyscout/go/config-keychain) makes the OS keychain a `config` layer, documented at [config.go.phpboyscout.uk/how-to/keychain/](https://config.go.phpboyscout.uk/how-to/keychain/). ```go config.WithEnv("KERYX"), // was EnvVar config.WithFiles(configafero.Wrap(fs), path), // was ConfigKey config.WithBackend(configkeychain.New( // was KeychainService/Account configkeychain.Registered(), "keryx", map[string]string{ "platforms.instagram.access_token": "instagram-access-token", "platforms.tiktok.refresh_token": "tiktok-refresh-token", "platforms.youtube.refresh_token": "youtube-refresh-token", "platforms.linkedin.access_token": "linkedin-access-token", "platforms.linkedin.refresh_token": "linkedin-refresh-token", })), ``` Resolution becomes ordinary layer precedence, so `keryx config` can finally say *which layer* answered — 0043 §1's first complaint. ## Two divergences from the 0043 sketch **1. The key mapping is declared on both sides, not derived from the path.** 0043 §2 sketched `configkeychain.Keys("platforms.instagram.access_token", …)`, computing the account name from the config path. The module refuses to do that, and keryx is exactly why: a convention would compute *something* from `platforms.instagram.access_token`, and whatever it computed would not be `instagram-access-token`. Every credential already in a user's keychain would be orphaned on upgrade. So the map above is explicit, and existing entries keep working untouched. **2. An unavailable keychain fails the load. It does not quietly contribute nothing.** This is the opposite of 0043 §3.2, and it is the one decision the adopting MR has to make consciously. `Load` returns `ErrKeychainUnavailable` rather than degrading, because contributing nothing is indistinguishable from "no tokens stored yet" — and silent degradation is what put tokens in plaintext files to begin with. For keryx the sketch's behaviour is still the right one, and getting it is one line: check `Available()` and omit `WithBackend` when it is false. That keeps 0043 §5's promise — on a keychain-less machine the layers beneath work exactly as they do now — but as a decision written in keryx's code rather than one nobody made. **The headless dev server is precisely this case**, so it is not hypothetical. The hang 0043 §3.2 describes on that server was real, was found and fixed: `credentials` v0.2.2 honours its context, and the adapter additionally imposes its own bound (`DefaultTimeout`, 10s; `WithTimeout` to change it), because a context bounds a call only if the callee consults it. ## 0043's open questions, as they now stand - **Q1 (where does it live) → sibling module**, as the spec leaned. - **Q2 (which implementation) → neither of the two options.** The adapter takes the `credentials.Backend` *interface* and never imports `credentials/keychain`. A test asserts `go-keyring` and `godbus` are absent from its dependency graph. `configkeychain.Registered()` bridges to whatever the consumer blank-imported. - **Q3 (does `Sensitive` belong in the core) → yes, and it shipped there.** The core refuses a write whose target is not sensitive, returning `config.ErrSensitiveLeak`. So once a token is in the keychain, **the plaintext fallback in `oauth.Store.Save` is refused by the core** rather than relying on keryx to remember not to take it. 0043 §3.3's "a keychain layer is not serialisable" is enforced rather than documented. - **Q4 (delete the ladder or keep it) → still keryx's call**, and still the riskiest slice. Note that the routing is already in keryx's favour: a *first* token lands in the keychain even when it holds nothing yet, because a new key routes to the highest-precedence writable target. No pinning, no branching. - **Q5 (priority) → unchanged.** Quality of implementation, not capability — except that the plaintext fallback stops being possible, which is a user-visible security improvement. ## Prerequisites - **`config` v0.9.2 → v0.10.0.** v0.10.0 added `Suite.BoundedKeySpace`, which a declared key space needs; the adapter's floor is v0.10.0. - **`credentials` v0.2.1 → v0.2.2.** Not optional and worth doing regardless of this ticket: **v0.2.1 is the version whose keychain backend discards its context**, so `Available()` returning true against a locked keyring blocks indefinitely with nothing able to recover it. keryx is on v0.2.1 today and calls `Available()` in `oauth.Store.Resolve` on every lookup. - The adapter is built and its conformance suite passes, but **is not yet tagged**; the first release follows shortly. Worth waiting for the tag rather than pinning a pseudo-version. ## Side-effect worth having `cmd/keryx/keychain.go` documents "delete this file to ship a regulated build whose linked binary carries no session-bus / keychain IPC code". That is not currently true: `pkg/oauth/store.go` imports `gitlab.com/phpboyscout/go/credentials/keychain` non-blank and constructs `keychain.Backend{}`, so the package is linked in whether or not the generated blank import is present. Adopting the adapter removes that import — `pkg/oauth` would talk to the interface — and the generated file becomes the only reference again, which is what makes deleting it mean anything. ## Suggested shape of the work 1. Bump `config` and `credentials`. (Independently valuable; see the hang above.) 2. Wire `configkeychain` into the store construction, `Available()`-gated, with the five-key map. Ladder untouched — both paths live, nothing changes yet. 3. Assert precedence and provenance through `Explain`, and assert that a token in the keychain cannot be written to the file beneath (`ErrSensitiveLeak`). 4. Delete `oauth.Store.Resolve`/`Save` and the five `oauth.Store` values, moving call sites to plain config reads and `store.Apply`. 0043 Q4 — its own slice. 5. Revisit `pkg/credscan` and the 0042 `accounts.yaml` layer in light of step 4. Update spec 0043 as this lands: Q1, Q2 and Q3 are answered, and §3.2's degradation model is now a keryx decision rather than an adapter guarantee.