[scottlovegrove]

Summary

Refs Doist/todoist-cli#577. Stacked on #157.

On Linux with no Secret Service on the session bus (WSL2, headless boxes), @napi-rs/keyring silently falls back to the kernel keyutils keyring. That keyring is in-memory and scoped to the login session, so td auth token reports "Token stored securely" while a second terminal, a cron job, or anything after a WSL restart fails with AUTH_STORE_READ_FAILED. The bug is in cli-core's createSecureStore, so every CLI on cli-core has it.

Changes

• createSecureStore builds the entry with { linux: { store: 'secret-service' } } (supported by @napi-rs/keyring 2.1.2, ignored on macOS and Windows). With no Secret Service the constructor throws, and the existing wrapping turns that into SecureStoreUnavailableError. Each credential-store policy then does what it already does:
  • 'system' (todoist-cli's default): AUTH_STORE_WRITE_FAILED with the existing plaintext hint, the same guidance #424 added.
  • 'fallback' (comms-cli's default): plaintext with a warning.
• AUTH_STORE_READ_FAILED for an unavailable credential manager now has hints (make it available, or log in again with plaintext storage). This covers users who upgrade with a credential already stuck in a session keyring: their reads now report the store as unavailable, where before they only worked in the session that wrote them.
• README notes the Linux pinning.

Why this is stacked on #157

The remedy here is to point users at plaintext storage. For CLIs that refresh tokens, that choice only lasts past the next rotation once #157 is merged.

Follow-up

Bump cli-core in todoist-cli, then close Doist/todoist-cli#577.

End-to-end testing

Tested end to end on Linux (node:24 arm64 container, no D-Bus, DBUS_SESSION_BUS_ADDRESS unset, seccomp unconfined so keyctl works as it does on WSL) with the real @napi-rs/keyring 2.1.2 native binary. A small harness drove createKeyringTokenStore with a JSON-file UserRecordStore. A "new session" read ran in a fresh process that first joined a new kernel session keyring (KEYCTL_JOIN_SESSION_KEYRING), as in the issue's repro.

Published cli-core 1.7.1 reproduced the bug:

• 'system': the write reported secure-store and a same-session read worked, but a new-session read failed with AUTH_STORE_READ_FAILED: system credential manager returned no credential for the stored account.
• 'fallback': same result. The write looked successful, so it never fell back to plaintext.

With this branch:

• 'system': the write failed with AUTH_STORE_WRITE_FAILED and the plaintext hint, and no record was written.
• 'fallback': the write went to plaintext with the warning, and a new-session read returned the token.
• Upgrade path: a credential written by 1.7.1 into the session keyring, read after upgrading to this branch, now fails as system credential manager unavailable with the new hints, instead of reading as missing.

The test ran below td auth token, because that command needs a real API token for getUser().

Test plan

• npm test, npm run type-check, npm run check
• secure-store tests check the Secret Service pin and that a throwing pinned constructor surfaces as SecureStoreUnavailableError on get, set and delete
• token-store test checks the hints on an unavailable read

[doistbot]

This PR pins Linux keyring storage to Secret Service in createSecureStore, so the silent session-scoped keyutils fallback (WSL2, headless boxes) now surfaces as SecureStoreUnavailableError and lets each CLI's credential-store policy handle it — system policies get the existing plaintext hint, fallback policies degrade to plaintext with a warning, and unavailable reads on AUTH_STORE_READ_FAILED now carry recovery hints. Tests cover the pinned constructor call, constructor-throw normalization, and the read-path hints, and the change reuses the existing error-wrapping and policy conventions cleanly. No inline issues were flagged during review; a minor optional follow-up would be extracting the shared plaintext-storage hint literal so the read and write paths stay wording-synced, but it's not blocking.

I also left one optional follow-up note in the details below.

Optional follow-up note (1)

• src/auth/keyring/token-store.ts:100: 'Make the system credential manager available and retry.' already exists verbatim in record-write.ts's credentialStoreUnavailableError, and this file already imports SECURE_STORE_DESCRIPTION (whose value is exactly system credential manager). Extract a shared hint constant/helper and compose it from SECURE_STORE_DESCRIPTION so the read and write paths can't drift.

_{Share Feedback • Review Logs}

[doist-release-bot]

🎉 This PR is included in version 1.7.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀