@doist/cli-core 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.16.0](https://github.com/Doist/cli-core/compare/v0.15.0...v0.16.0) (2026-05-16)
+
+### Features
+
+* **auth:** add migrateLegacyAuth helper ([#28](https://github.com/Doist/cli-core/issues/28)) ([cd7baee](https://github.com/Doist/cli-core/commit/cd7baeebdb9b3dfc5909862a0af7ae5bfee17723))
+
+## [0.15.0](https://github.com/Doist/cli-core/compare/v0.14.0...v0.15.0) (2026-05-16)
+
+### Features
+
+* **auth:** add createKeyringTokenStore (multi-account) ([#27](https://github.com/Doist/cli-core/issues/27)) ([adc07d1](https://github.com/Doist/cli-core/commit/adc07d1830657471bc945a5b2a5599f81a066ee3))
+
 ## [0.14.0](https://github.com/Doist/cli-core/compare/v0.13.0...v0.14.0) (2026-05-16)
 
 ### Features

package/README.md

@@ -12,20 +12,20 @@ npm install @doist/cli-core
 
 ## What's in it
 
-| Module               | Key exports                                                                                                                                                                                                                                                            | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth` (subpath)     | `attachLoginCommand`, `attachLogoutCommand`, `attachStatusCommand`, `attachTokenViewCommand`, `runOAuthFlow`, `createPkceProvider`, `createSecureStore`, PKCE helpers, `AuthProvider` / `TokenStore` / `AccountRef` / `SecureStore` types, `AttachLogoutRevokeContext` | OAuth runtime plus the Commander attachers for `<cli> [auth] login` / `logout` / `status` / `token`. `attachLogoutCommand` accepts an optional `revokeToken` hook for best-effort server-side token revocation. Ships the standard public-client PKCE flow (`createPkceProvider`) and a thin cross-platform OS-keyring wrapper (`createSecureStore`) backed by `@napi-rs/keyring`. `AuthProvider` and `TokenStore` are the escape hatches for DCR, OS-keychain, multi-account, etc. — consumers implement `TokenStore` directly (single-user store implements `list` / `setDefault` trivially against the one account). `logout` / `status` / `token` always attach `--user <ref>` and thread the parsed ref to `store.active(ref)` (and `store.clear(ref)` on `logout`). `commander` (when using the attachers), `open` (browser launch), and `@napi-rs/keyring` (when using `createSecureStore`) are optional peer/optional deps. |
-| `commands` (subpath) | `registerChangelogCommand`, `registerUpdateCommand` (+ semver helpers)                                                                                                                                                                                                 | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`, `<cli> update`, `<cli> update switch`). **Requires** `commander` as an optional peer-dep.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`, `CoreConfig`, `UpdateChannel`                                                                                                                                                        | Read / write a per-CLI JSON config file with typed error codes; `CoreConfig` is the shape of fields cli-core itself owns (extend it for per-CLI fields).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `empty`              | `printEmpty`                                                                                                                                                                                                                                                           | Print an empty-state message gated on `--json` / `--ndjson` so machine consumers never see human strings on stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `errors`             | `CliError`                                                                                                                                                                                                                                                             | Typed CLI error class with `code` and exit-code mapping.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `global-args`        | `parseGlobalArgs`, `stripUserFlag`, `createGlobalArgsStore`, `createAccessibleGate`, `createSpinnerGate`, `getProgressJsonlPath`, `isProgressJsonlEnabled`                                                                                                             | Parse well-known global flags (`--json`, `--ndjson`, `--quiet`, `--verbose`, `--accessible`, `--no-spinner`, `--progress-jsonl`, `--user <ref>`) and derive predicates from them. `stripUserFlag` removes `--user` tokens from argv so the cleaned array can be forwarded to Commander when the flag has no root-program attachment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `json`               | `formatJson`, `formatNdjson`                                                                                                                                                                                                                                           | Stable JSON / newline-delimited JSON formatting for stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `markdown` (subpath) | `preloadMarkdown`, `renderMarkdown`, `TerminalRendererOptions`                                                                                                                                                                                                         | Lazy-init terminal markdown renderer. **Requires** `marked` and `marked-terminal-renderer` as peer-deps — install only if your CLI uses this subpath.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `options`            | `ViewOptions`                                                                                                                                                                                                                                                          | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `spinner`            | `createSpinner`                                                                                                                                                                                                                                                        | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                                                                                                                                                     | TTY / CI detection helpers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                                                                                                                                                           | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Module               | Key exports                                                                                                                                                                                                                                                                                                                                | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth` (subpath)     | `attachLoginCommand`, `attachLogoutCommand`, `attachStatusCommand`, `attachTokenViewCommand`, `runOAuthFlow`, `createPkceProvider`, `createSecureStore`, `createKeyringTokenStore`, `migrateLegacyAuth`, PKCE helpers, `AuthProvider` / `TokenStore` / `AccountRef` / `SecureStore` / `UserRecordStore` types, `AttachLogoutRevokeContext` | OAuth runtime plus the Commander attachers for `<cli> [auth] login` / `logout` / `status` / `token`. `attachLogoutCommand` accepts an optional `revokeToken` hook for best-effort server-side token revocation. Ships the standard public-client PKCE flow (`createPkceProvider`), a thin cross-platform OS-keyring wrapper (`createSecureStore`), and a multi-account keyring-backed `TokenStore` (`createKeyringTokenStore`) that stores secrets in the OS credential manager and degrades to plaintext in the consumer's config when the keyring is unavailable (WSL/headless Linux/containers). `AuthProvider` and `TokenStore` remain the escape hatches for DCR or fully bespoke backends. `logout` / `status` / `token` always attach `--user <ref>` and thread the parsed ref to `store.active(ref)` (and `store.clear(ref)` on `logout`). `commander` (when using the attachers), `open` (browser launch), and `@napi-rs/keyring` (when using `createSecureStore` or the keyring `TokenStore`) are optional peer/optional deps. |
+| `commands` (subpath) | `registerChangelogCommand`, `registerUpdateCommand` (+ semver helpers)                                                                                                                                                                                                                                                                     | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`, `<cli> update`, `<cli> update switch`). **Requires** `commander` as an optional peer-dep.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`, `CoreConfig`, `UpdateChannel`                                                                                                                                                                                                                            | Read / write a per-CLI JSON config file with typed error codes; `CoreConfig` is the shape of fields cli-core itself owns (extend it for per-CLI fields).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `empty`              | `printEmpty`                                                                                                                                                                                                                                                                                                                               | Print an empty-state message gated on `--json` / `--ndjson` so machine consumers never see human strings on stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `errors`             | `CliError`                                                                                                                                                                                                                                                                                                                                 | Typed CLI error class with `code` and exit-code mapping.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `global-args`        | `parseGlobalArgs`, `stripUserFlag`, `createGlobalArgsStore`, `createAccessibleGate`, `createSpinnerGate`, `getProgressJsonlPath`, `isProgressJsonlEnabled`                                                                                                                                                                                 | Parse well-known global flags (`--json`, `--ndjson`, `--quiet`, `--verbose`, `--accessible`, `--no-spinner`, `--progress-jsonl`, `--user <ref>`) and derive predicates from them. `stripUserFlag` removes `--user` tokens from argv so the cleaned array can be forwarded to Commander when the flag has no root-program attachment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `json`               | `formatJson`, `formatNdjson`                                                                                                                                                                                                                                                                                                               | Stable JSON / newline-delimited JSON formatting for stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `markdown` (subpath) | `preloadMarkdown`, `renderMarkdown`, `TerminalRendererOptions`                                                                                                                                                                                                                                                                             | Lazy-init terminal markdown renderer. **Requires** `marked` and `marked-terminal-renderer` as peer-deps — install only if your CLI uses this subpath.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `options`            | `ViewOptions`                                                                                                                                                                                                                                                                                                                              | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `spinner`            | `createSpinner`                                                                                                                                                                                                                                                                                                                            | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                                                                                                                                                                                                                         | TTY / CI detection helpers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                                                                                                                                                                                                                               | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 ## Usage
 
@@ -315,6 +315,89 @@ Every failure mode — `@napi-rs/keyring` failing to load on an arch without a p
 
 `@napi-rs/keyring` is declared in cli-core's own `optionalDependencies`, so npm pulls it in transitively when you install `@doist/cli-core` — your consumer CLI does not need to add it explicitly. The library ships pre-built native binaries for Windows (Credential Manager), macOS (Keychain), and Linux glibc + musl (libsecret / Secret Service).
 
+#### Multi-account keyring-backed `TokenStore`
+
+`createKeyringTokenStore` wires `createSecureStore` into the `TokenStore` contract for multi-account CLIs. Secrets live in the OS credential manager; per-user metadata stays in the consumer's config via a small `UserRecordStore` port the consumer implements. When the keyring is unreachable the store transparently falls back to a `fallbackToken` field on the user record and exposes a warning on `getLastStorageResult()` for the login command to surface.
+
+```ts
+import { createKeyringTokenStore, type UserRecordStore } from '@doist/cli-core/auth'
+
+type Account = { id: string; label?: string; email: string }
+
+// Adapter over the consumer's existing config.json shape.
+const userRecords: UserRecordStore<Account> = {
+    async list() {
+        /* read from config */
+    },
+    async upsert(record) {
+        /* replace, do not merge — see UserRecordStore docs */
+    },
+    async remove(id) {
+        /* … */
+    },
+    async getDefaultId() {
+        /* … */
+    },
+    async setDefaultId(id) {
+        /* … */
+    },
+    describeLocation() {
+        return '~/.config/todoist-cli/config.json'
+    },
+}
+
+export const tokenStore = createKeyringTokenStore<Account>({
+    serviceName: 'todoist-cli',
+    userRecords,
+})
+
+// In your login command's onSuccess:
+const storage = tokenStore.getLastStorageResult()
+if (storage?.warning) console.error('Warning:', storage.warning)
+```
+
+The returned store satisfies the full `TokenStore` contract — including `list()` / `setDefault(ref)` / `ref`-aware `active` / `clear` — so it plugs straight into the `logout` / `status` / `token` attachers. Default ref matching is `account.id === ref || account.label === ref`; override `matchAccount` to broaden it (e.g. case-insensitive email).
+
+When a matching record exists but the keyring read fails, `active(ref)` throws `CliError('AUTH_STORE_READ_FAILED', …)`. `attachLogoutCommand` catches it specifically so `logout --user <ref>` still clears the local record even with the keyring offline; status / token-view propagate it because they can't render without the token.
+
+For sync/lazy-decrypt or fully bespoke backends, implement `TokenStore` directly.
+
+For one-time migration of a v1 single-user token into the v2 multi-user shape, use `migrateLegacyAuth` from a postinstall hook. The helper requires a durable **migration marker** the consumer owns — a boolean persisted in their config — so the migration is genuinely one-way: a later `logout` (which empties `userRecords`) followed by a reinstall won't re-migrate a stale legacy token.
+
+```ts
+import { getConfigPath, readConfig, updateConfig } from '@doist/cli-core'
+import { migrateLegacyAuth } from '@doist/cli-core/auth'
+
+const configPath = getConfigPath('todoist-cli')
+
+const result = await migrateLegacyAuth<Account>({
+    serviceName: 'todoist-cli',
+    legacyAccount: 'api-token',
+    userRecords,
+    // Durable one-way gate. Persist `migrated_v2: true` in your config
+    // after a successful migration; check it on every run.
+    hasMigrated: async () =>
+        (await readConfig<{ migrated_v2?: boolean }>(configPath)).migrated_v2 === true,
+    markMigrated: async () =>
+        updateConfig<{ migrated_v2: boolean }>(configPath, { migrated_v2: true }),
+    loadLegacyPlaintextToken: async () =>
+        (await readConfig<{ api_token?: string }>(configPath)).api_token ?? null,
+    identifyAccount: async (token) => fetchUser(token),
+    cleanupLegacyConfig: async () => clearLegacyAuthFields(configPath),
+    silent: true,
+    logPrefix: 'todoist-cli',
+})
+
+if (result.status === 'skipped' && result.reason === 'legacy-keyring-unreachable') {
+    // Retryable — the next postinstall run with the keyring online will
+    // pick up where this one left off.
+}
+```
+
+`MigrateAuthResult` is a discriminated union on `status` (`'already-migrated' | 'no-legacy-state' | 'migrated' | 'skipped'`). `migrated` carries the resolved `account`; `skipped` carries a stable `reason` (`'identify-failed' | 'legacy-keyring-unreachable' | 'user-record-write-failed' | 'marker-write-failed'`) plus a free-form `detail`.
+
+The helper is best-effort throughout: any failure (offline keyring, network error fetching the user, upsert blip) leaves the v1 state untouched so the consumer's runtime fallback can keep serving the legacy token until the next attempt. `markMigrated()` is called **before** the legacy keyring delete + `cleanupLegacyConfig`, so cleanup failures can't cause re-migration on the next run — the marker is the one-way gate, not cleanup success. The legacy delete and `cleanupLegacyConfig` run concurrently via `Promise.allSettled`. stderr output uses fixed phrases keyed off `MigrateSkipReason` and the success log omits the account identifier entirely so consumer-supplied error text (and PII-shaped `account.id` values like emails) can't leak into logs.
+
 #### `--user <ref>` and multi-user wiring
 
 The three account-touching attachers (`attachLogoutCommand` / `attachStatusCommand` / `attachTokenViewCommand`) always attach `--user <ref>` on their subcommand. `attachLogoutCommand` threads the parsed ref to both `store.active(ref)` and `store.clear(ref)`; `attachStatusCommand` and `attachTokenViewCommand` only call `store.active(ref)`. When `--user` is supplied but `store.active(ref)` returns `null`, each attacher throws `CliError('ACCOUNT_NOT_FOUND', …)` so the user sees a typed miss rather than `NOT_AUTHENTICATED` or a silent `✓ Logged out`. Single-user stores returning `null` for a non-matching ref is the supported way to feed this guard.

package/dist/auth/index.d.ts

@@ -14,6 +14,6 @@ export type { GenerateVerifierOptions } from './pkce.js';
 export { createPkceProvider } from './providers/pkce.js';
 export type { PkceLazyString, PkceProviderOptions } from './providers/pkce.js';
 export type { AccountRef, AuthAccount, AuthorizeInput, AuthorizeResult, AuthProvider, ExchangeInput, ExchangeResult, PrepareInput, PrepareResult, TokenStore, ValidateInput, } from './types.js';
-export { SecureStoreUnavailableError, createSecureStore } from './keyring/index.js';
-export type { CreateSecureStoreOptions, SecureStore } from './keyring/index.js';
+export { SecureStoreUnavailableError, createKeyringTokenStore, createSecureStore, migrateLegacyAuth, } from './keyring/index.js';
+export type { CreateKeyringTokenStoreOptions, CreateSecureStoreOptions, KeyringTokenStore, MigrateAuthResult, MigrateLegacyAuthOptions, MigrateSkipReason, SecureStore, TokenStorageLocation, TokenStorageResult, UserRecord, UserRecordStore, } from './keyring/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,YAAY,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EACR,0BAA0B,EAC1B,mBAAmB,EACnB,yBAAyB,GAC5B,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACxD,YAAY,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,gBAAgB,GACnB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EACR,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACnF,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/C,YAAY,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EACR,0BAA0B,EAC1B,mBAAmB,EACnB,yBAAyB,GAC5B,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACxD,YAAY,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,gBAAgB,GACnB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EACR,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,aAAa,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EACH,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,GACpB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACR,8BAA8B,EAC9B,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,EACjB,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,eAAe,GAClB,MAAM,oBAAoB,CAAA"}

package/dist/auth/index.js

@@ -5,5 +5,5 @@ export { attachStatusCommand } from './status.js';
 export { attachTokenViewCommand } from './token-view.js';
 export { DEFAULT_VERIFIER_ALPHABET, deriveChallenge, generateState, generateVerifier, } from './pkce.js';
 export { createPkceProvider } from './providers/pkce.js';
-export { SecureStoreUnavailableError, createSecureStore } from './keyring/index.js';
+export { SecureStoreUnavailableError, createKeyringTokenStore, createSecureStore, migrateLegacyAuth, } from './keyring/index.js';
 //# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAMjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAExD,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,gBAAgB,GACnB,MAAM,WAAW,CAAA;AAElB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAexD,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAMjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAExD,OAAO,EACH,yBAAyB,EACzB,eAAe,EACf,aAAa,EACb,gBAAgB,GACnB,MAAM,WAAW,CAAA;AAElB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAexD,OAAO,EACH,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,GACpB,MAAM,oBAAoB,CAAA"}

package/dist/auth/keyring/index.d.ts

@@ -1,3 +1,8 @@
 export { SecureStoreUnavailableError, createSecureStore } from './secure-store.js';
 export type { CreateSecureStoreOptions, SecureStore } from './secure-store.js';
+export { createKeyringTokenStore } from './token-store.js';
+export type { CreateKeyringTokenStoreOptions, KeyringTokenStore } from './token-store.js';
+export { migrateLegacyAuth } from './migrate.js';
+export type { MigrateAuthResult, MigrateLegacyAuthOptions, MigrateSkipReason } from './migrate.js';
+export type { TokenStorageLocation, TokenStorageResult, UserRecord, UserRecordStore, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/auth/keyring/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAClF,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAClF,YAAY,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,YAAY,EAAE,8BAA8B,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAElG,YAAY,EACR,oBAAoB,EACpB,kBAAkB,EAClB,UAAU,EACV,eAAe,GAClB,MAAM,YAAY,CAAA"}

package/dist/auth/keyring/index.js

@@ -1,2 +1,4 @@
 export { SecureStoreUnavailableError, createSecureStore } from './secure-store.js';
+export { createKeyringTokenStore } from './token-store.js';
+export { migrateLegacyAuth } from './migrate.js';
 //# sourceMappingURL=index.js.map

package/dist/auth/keyring/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/auth/keyring/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/auth/keyring/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAGlF,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA"}

package/dist/auth/keyring/migrate.d.ts

@@ -0,0 +1,93 @@
+import type { AuthAccount } from '../types.js';
+import type { UserRecordStore } from './types.js';
+export type MigrateLegacyAuthOptions<TAccount extends AuthAccount> = {
+    serviceName: string;
+    /** Legacy single-user keyring account slug, e.g. `'api-token'`. */
+    legacyAccount: string;
+    /** v2 user-record store the migrated record is written into. */
+    userRecords: UserRecordStore<TAccount>;
+    /** Per-user keyring slug for the new entry. Defaults to `user-${id}`. */
+    accountForUser?: (id: string) => string;
+    /**
+     * Reads the durable "migration already ran" marker the consumer owns
+     * (typically a flag in their config). When this returns `true`, the
+     * helper short-circuits with `already-migrated` and never touches the
+     * legacy state. This is the **one-way gate** — without it, a later
+     * `logout` (which empties `userRecords`) followed by a reinstall would
+     * cause the helper to re-migrate a stale legacy token.
+     */
+    hasMigrated: () => Promise<boolean>;
+    /**
+     * Persists the durable migration marker. Called **after** the v2 record
+     * write succeeds and **before** legacy cleanup so the gate is set before
+     * any best-effort follow-up runs. If this throws, the helper returns a
+     * `skipped` result with reason `marker-write-failed` — the v2 record is
+     * already on disk, but the marker isn't, so the caller should retry.
+     */
+    markMigrated: () => Promise<void>;
+    /**
+     * Returns the v1 token from the consumer's *plaintext* config slot, or
+     * `null` if absent. cli-core handles the legacy keyring slot itself.
+     */
+    loadLegacyPlaintextToken: () => Promise<string | null>;
+    /**
+     * Identifies the user behind the v1 token. Implementations typically hit
+     * the product API with the token to fetch the canonical `id` / `email`
+     * for the new account record.
+     */
+    identifyAccount: (token: string) => Promise<TAccount>;
+    /**
+     * Optional best-effort cleanup of v1-only config fields after a
+     * successful migration (e.g. unset legacy `api_token` / `auth_mode`).
+     * Runs concurrently with the legacy keyring delete; failures are
+     * swallowed because the marker (above) is what gates re-migration.
+     */
+    cleanupLegacyConfig?: () => Promise<void>;
+    /** Suppress stderr output (postinstall hooks set this). */
+    silent?: boolean;
+    /** Label used in the stderr log line. Defaults to `'cli'`. */
+    logPrefix?: string;
+};
+/**
+ * Stable skip reasons. `legacy-keyring-unreachable` is retryable (a later
+ * run with the keyring online would succeed); the others are diagnostic.
+ */
+export type MigrateSkipReason = 'identify-failed' | 'legacy-keyring-unreachable' | 'user-record-write-failed' | 'marker-write-failed';
+/**
+ * Discriminated by `status`. Narrowing on `status === 'skipped'` exposes
+ * the structured `reason` + free-form `detail`; `migrated` carries the
+ * resolved account.
+ */
+export type MigrateAuthResult<TAccount extends AuthAccount = AuthAccount> = {
+    status: 'already-migrated';
+} | {
+    status: 'no-legacy-state';
+} | {
+    status: 'migrated';
+    account: TAccount;
+} | {
+    status: 'skipped';
+    reason: MigrateSkipReason;
+    detail: string;
+};
+/**
+ * One-time migration of a v1 single-user auth state into a v2 multi-user
+ * shape. Best-effort: any failure (offline keyring, network error fetching
+ * the user, …) leaves the v1 state untouched so the consumer's runtime
+ * fallback can keep serving the legacy token until the next attempt.
+ *
+ * Order of operations is deliberate so the migration is genuinely one-way:
+ *
+ *   1. `hasMigrated()` short-circuits if the durable marker is already set.
+ *   2. Read the v1 token (legacy keyring slot first, then plaintext).
+ *   3. `identifyAccount(token)` resolves the v2 `account` shape.
+ *   4. `writeRecordWithKeyringFallback` writes the v2 record.
+ *   5. Best-effort `setDefaultId(account.id)` so the new record is active.
+ *   6. `markMigrated()` persists the marker. **If this fails, we return
+ *      `skipped` even though the v2 record is on disk** — the marker is
+ *      what prevents re-migration on the next run.
+ *   7. Best-effort legacy keyring delete + `cleanupLegacyConfig()` run
+ *      concurrently. Failures here are harmless because the marker is set.
+ */
+export declare function migrateLegacyAuth<TAccount extends AuthAccount>(options: MigrateLegacyAuthOptions<TAccount>): Promise<MigrateAuthResult<TAccount>>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/auth/keyring/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/migrate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAQ9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,MAAM,MAAM,wBAAwB,CAAC,QAAQ,SAAS,WAAW,IAAI;IACjE,WAAW,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,WAAW,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;IACtC,yEAAyE;IACzE,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC;;;;;;;OAOG;IACH,WAAW,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACnC;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC;;;OAGG;IACH,wBAAwB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACtD;;;;OAIG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACrD;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACvB,iBAAiB,GACjB,4BAA4B,GAC5B,0BAA0B,GAC1B,qBAAqB,CAAA;AAS3B;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,QAAQ,SAAS,WAAW,GAAG,WAAW,IAClE;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC9B;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAC7B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAOtE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,SAAS,WAAW,EAChE,OAAO,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAC5C,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAuGtC"}

package/dist/auth/keyring/migrate.js

@@ -0,0 +1,143 @@
+import { getErrorMessage } from '../../errors.js';
+import { writeRecordWithKeyringFallback } from './record-write.js';
+import { createSecureStore, DEFAULT_ACCOUNT_FOR_USER, SecureStoreUnavailableError, } from './secure-store.js';
+const SKIP_REASON_MESSAGES = {
+    'identify-failed': 'could not identify user',
+    'legacy-keyring-unreachable': 'legacy credential is unreachable (keyring offline)',
+    'user-record-write-failed': 'failed to update user records',
+    'marker-write-failed': 'failed to persist migration marker',
+};
+/**
+ * One-time migration of a v1 single-user auth state into a v2 multi-user
+ * shape. Best-effort: any failure (offline keyring, network error fetching
+ * the user, …) leaves the v1 state untouched so the consumer's runtime
+ * fallback can keep serving the legacy token until the next attempt.
+ *
+ * Order of operations is deliberate so the migration is genuinely one-way:
+ *
+ *   1. `hasMigrated()` short-circuits if the durable marker is already set.
+ *   2. Read the v1 token (legacy keyring slot first, then plaintext).
+ *   3. `identifyAccount(token)` resolves the v2 `account` shape.
+ *   4. `writeRecordWithKeyringFallback` writes the v2 record.
+ *   5. Best-effort `setDefaultId(account.id)` so the new record is active.
+ *   6. `markMigrated()` persists the marker. **If this fails, we return
+ *      `skipped` even though the v2 record is on disk** — the marker is
+ *      what prevents re-migration on the next run.
+ *   7. Best-effort legacy keyring delete + `cleanupLegacyConfig()` run
+ *      concurrently. Failures here are harmless because the marker is set.
+ */
+export async function migrateLegacyAuth(options) {
+    const { serviceName, legacyAccount, userRecords, hasMigrated, markMigrated, loadLegacyPlaintextToken, identifyAccount, cleanupLegacyConfig, silent, } = options;
+    const accountForUser = options.accountForUser ?? DEFAULT_ACCOUNT_FOR_USER;
+    const logPrefix = options.logPrefix ?? 'cli';
+    if (await hasMigrated()) {
+        return { status: 'already-migrated' };
+    }
+    // One legacy-keyring handle covers both the initial read and the
+    // post-success cleanup delete.
+    const legacyStore = createSecureStore({ serviceName, account: legacyAccount });
+    const legacyToken = await readLegacyToken(legacyStore, loadLegacyPlaintextToken);
+    if (legacyToken.kind === 'none')
+        return { status: 'no-legacy-state' };
+    if (legacyToken.kind === 'keyring-unavailable') {
+        return skipped(silent, logPrefix, 'legacy-keyring-unreachable', 'OS keyring unreachable while reading legacy slot');
+    }
+    let account;
+    try {
+        account = await identifyAccount(legacyToken.token);
+    }
+    catch (error) {
+        return skipped(silent, logPrefix, 'identify-failed', getErrorMessage(error));
+    }
+    // `writeRecordWithKeyringFallback` swallows `SecureStoreUnavailableError`
+    // internally (writing to `fallbackToken` instead), so any error here is
+    // a non-keyring failure — typically a `userRecords.upsert` rejection.
+    try {
+        await writeRecordWithKeyringFallback({
+            secureStore: createSecureStore({
+                serviceName,
+                account: accountForUser(account.id),
+            }),
+            userRecords,
+            account,
+            token: legacyToken.token,
+        });
+    }
+    catch (error) {
+        return skipped(silent, logPrefix, 'user-record-write-failed', getErrorMessage(error));
+    }
+    // Default promotion is best-effort and **only fires when nothing is
+    // already pinned**. A retry after a previous `markMigrated()` failure
+    // can land on a store where the user has since logged in to a different
+    // account and picked it as default — blindly setting the legacy account
+    // back as default would silently switch the user.
+    try {
+        const existingDefault = await userRecords.getDefaultId();
+        if (!existingDefault) {
+            await userRecords.setDefaultId(account.id);
+        }
+    }
+    catch {
+        // best-effort
+    }
+    // Persist the one-way marker BEFORE legacy cleanup. If this fails, the
+    // v2 record is already written but the gate is unset — surface as
+    // `skipped` so the caller retries. Without this ordering, a later
+    // `logout` could let the next run re-migrate the stale v1 token.
+    try {
+        await markMigrated();
+    }
+    catch (error) {
+        return skipped(silent, logPrefix, 'marker-write-failed', getErrorMessage(error));
+    }
+    // Best-effort legacy cleanup — runs concurrently so we don't pay
+    // keyring latency followed by config-write latency on every install.
+    // The marker is already set, so a failure here can't cause
+    // re-migration on the next run. The `Promise.resolve().then(...)`
+    // wrappers convert any *synchronous* throw from a consumer-supplied
+    // `cleanupLegacyConfig` (or an oddly-implemented `SecureStore`) into
+    // a rejected promise that `Promise.allSettled` can swallow.
+    await Promise.allSettled([
+        Promise.resolve().then(() => legacyStore.deleteSecret()),
+        Promise.resolve().then(() => cleanupLegacyConfig?.()),
+    ]);
+    if (!silent) {
+        // No identifier in the log line — `account.id` is typed as `string`
+        // but consumers can legitimately use an email or other PII there.
+        // Callers that need richer telemetry can compose it from the
+        // returned `account`.
+        console.error(`${logPrefix}: migrated existing token to multi-user store.`);
+    }
+    return { status: 'migrated', account };
+}
+async function readLegacyToken(legacyStore, loadLegacyPlaintextToken) {
+    let keyringUnavailable = false;
+    try {
+        const stored = await legacyStore.getSecret();
+        if (stored?.trim())
+            return { kind: 'found', token: stored.trim() };
+    }
+    catch (error) {
+        if (!(error instanceof SecureStoreUnavailableError))
+            throw error;
+        keyringUnavailable = true;
+    }
+    const plaintext = await loadLegacyPlaintextToken();
+    if (plaintext?.trim())
+        return { kind: 'found', token: plaintext.trim() };
+    return keyringUnavailable ? { kind: 'keyring-unavailable' } : { kind: 'none' };
+}
+/**
+ * Emit the migration skip line. The stderr text is a fixed phrase keyed off
+ * `MigrateSkipReason` so consumer-supplied callbacks (`identifyAccount`,
+ * the `UserRecordStore`, …) can't leak emails, paths, or auth diagnostics
+ * into logs. The raw error message is still attached to the returned
+ * `MigrateAuthResult.detail` for in-process callers that need it.
+ */
+function skipped(silent, logPrefix, reason, detail) {
+    if (!silent) {
+        console.error(`${logPrefix}: skipped legacy auth migration — ${SKIP_REASON_MESSAGES[reason]}.`);
+    }
+    return { status: 'skipped', reason, detail };
+}
+//# sourceMappingURL=migrate.js.map

package/dist/auth/keyring/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../../src/auth/keyring/migrate.ts"],"names":[],"mappings":"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"}

package/dist/auth/keyring/record-write.d.ts

@@ -0,0 +1,34 @@
+import type { AuthAccount } from '../types.js';
+import { type SecureStore } from './secure-store.js';
+import type { UserRecordStore } from './types.js';
+type WriteRecordOptions<TAccount extends AuthAccount> = {
+    /** Per-account keyring slot, already configured by the caller (e.g. via `createSecureStore`). */
+    secureStore: SecureStore;
+    userRecords: UserRecordStore<TAccount>;
+    account: TAccount;
+    token: string;
+};
+type WriteRecordResult = {
+    /** `true` when the secret landed in the OS keyring; `false` when the keyring was unavailable and the token was written to `fallbackToken` on the user record. */
+    storedSecurely: boolean;
+};
+/**
+ * Shared keyring-then-record write used by `createKeyringTokenStore.set` and
+ * `migrateLegacyAuth`. Encapsulates the order-of-operations contract that
+ * matters for credential safety:
+ *
+ *   1. Keyring `setSecret` first. On `SecureStoreUnavailableError`, swallow
+ *      the failure and record a `fallbackToken` on the user record instead.
+ *      Any other error rethrows.
+ *   2. `userRecords.upsert(record)`. On failure, best-effort rollback the
+ *      keyring write so we don't leave an orphan credential for an account
+ *      cli-core never managed to register. Original error rethrows.
+ *
+ * Default promotion (`setDefaultId`) is intentionally **not** in here — both
+ * call sites do it best-effort outside the critical section because it is a
+ * preference, not a correctness requirement, and an error there must not
+ * dirty up a successful credential write.
+ */
+export declare function writeRecordWithKeyringFallback<TAccount extends AuthAccount>(options: WriteRecordOptions<TAccount>): Promise<WriteRecordResult>;
+export {};
+//# sourceMappingURL=record-write.d.ts.map

package/dist/auth/keyring/record-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-write.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/record-write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,KAAK,WAAW,EAA+B,MAAM,mBAAmB,CAAA;AACjF,OAAO,KAAK,EAAc,eAAe,EAAE,MAAM,YAAY,CAAA;AAE7D,KAAK,kBAAkB,CAAC,QAAQ,SAAS,WAAW,IAAI;IACpD,iGAAiG;IACjG,WAAW,EAAE,WAAW,CAAA;IACxB,WAAW,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;IACtC,OAAO,EAAE,QAAQ,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,KAAK,iBAAiB,GAAG;IACrB,iKAAiK;IACjK,cAAc,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,8BAA8B,CAAC,QAAQ,SAAS,WAAW,EAC7E,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACtC,OAAO,CAAC,iBAAiB,CAAC,CA8B5B"}

package/dist/auth/keyring/record-write.js

@@ -0,0 +1,50 @@
+import { SecureStoreUnavailableError } from './secure-store.js';
+/**
+ * Shared keyring-then-record write used by `createKeyringTokenStore.set` and
+ * `migrateLegacyAuth`. Encapsulates the order-of-operations contract that
+ * matters for credential safety:
+ *
+ *   1. Keyring `setSecret` first. On `SecureStoreUnavailableError`, swallow
+ *      the failure and record a `fallbackToken` on the user record instead.
+ *      Any other error rethrows.
+ *   2. `userRecords.upsert(record)`. On failure, best-effort rollback the
+ *      keyring write so we don't leave an orphan credential for an account
+ *      cli-core never managed to register. Original error rethrows.
+ *
+ * Default promotion (`setDefaultId`) is intentionally **not** in here — both
+ * call sites do it best-effort outside the critical section because it is a
+ * preference, not a correctness requirement, and an error there must not
+ * dirty up a successful credential write.
+ */
+export async function writeRecordWithKeyringFallback(options) {
+    const { secureStore, userRecords, account, token } = options;
+    const trimmed = token.trim();
+    let storedSecurely = false;
+    try {
+        await secureStore.setSecret(trimmed);
+        storedSecurely = true;
+    }
+    catch (error) {
+        if (!(error instanceof SecureStoreUnavailableError))
+            throw error;
+    }
+    const record = storedSecurely
+        ? { account }
+        : { account, fallbackToken: trimmed };
+    try {
+        await userRecords.upsert(record);
+    }
+    catch (error) {
+        if (storedSecurely) {
+            try {
+                await secureStore.deleteSecret();
+            }
+            catch {
+                // best-effort — the user record failure is the real cause
+            }
+        }
+        throw error;
+    }
+    return { storedSecurely };
+}
+//# sourceMappingURL=record-write.js.map

package/dist/auth/keyring/record-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-write.js","sourceRoot":"","sources":["../../../src/auth/keyring/record-write.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,2BAA2B,EAAE,MAAM,mBAAmB,CAAA;AAgBjF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAChD,OAAqC;IAErC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAC5D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAE5B,IAAI,cAAc,GAAG,KAAK,CAAA;IAC1B,IAAI,CAAC;QACD,MAAM,WAAW,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QACpC,cAAc,GAAG,IAAI,CAAA;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,KAAK,YAAY,2BAA2B,CAAC;YAAE,MAAM,KAAK,CAAA;IACpE,CAAC;IAED,MAAM,MAAM,GAAyB,cAAc;QAC/C,CAAC,CAAC,EAAE,OAAO,EAAE;QACb,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,CAAA;IAEzC,IAAI,CAAC;QACD,MAAM,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,IAAI,cAAc,EAAE,CAAC;YACjB,IAAI,CAAC;gBACD,MAAM,WAAW,CAAC,YAAY,EAAE,CAAA;YACpC,CAAC;YAAC,MAAM,CAAC;gBACL,0DAA0D;YAC9D,CAAC;QACL,CAAC;QACD,MAAM,KAAK,CAAA;IACf,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,CAAA;AAC7B,CAAC"}

package/dist/auth/keyring/secure-store.d.ts

@@ -1,3 +1,16 @@
+/**
+ * User-facing label for the OS credential manager. Used by the keyring
+ * `TokenStore`'s fallback-warning composition; internal to the keyring
+ * module until a public caller asks for it.
+ */
+export declare const SECURE_STORE_DESCRIPTION = "system credential manager";
+/**
+ * Default keyring `account` slug for a stored user. Lives here so every
+ * caller that derives a per-user slot name agrees on the wire format — a
+ * future rename can't silently park tokens in a slot the runtime no longer
+ * reads from.
+ */
+export declare const DEFAULT_ACCOUNT_FOR_USER: (id: string) => string;
 /**
  * Thrown when the OS credential manager cannot be reached — missing native
  * binary for the current architecture, libsecret/D-Bus unavailable

package/dist/auth/keyring/secure-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-store.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/secure-store.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBAE9C,OAAO,SAA6C,EACpD,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKpC;AAED,MAAM,MAAM,WAAW,GAAG;IACtB,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACnC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACnC,uHAAuH;IACvH,WAAW,EAAE,MAAM,CAAA;IACnB,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAA;CAClB,CAAA;AAID;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAoChF"}
+{"version":3,"file":"secure-store.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/secure-store.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,8BAA8B,CAAA;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,IAAI,MAAM,KAAG,MAAsB,CAAA;AAE5E;;;;;;;;;;GAUG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBAE9C,OAAO,SAA6C,EACpD,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKpC;AAED,MAAM,MAAM,WAAW,GAAG;IACtB,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACnC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACnC,uHAAuH;IACvH,WAAW,EAAE,MAAM,CAAA;IACnB,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAA;CAClB,CAAA;AAID;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAoChF"}

package/dist/auth/keyring/secure-store.js

@@ -1,4 +1,17 @@
 import { getErrorMessage } from '../../errors.js';
+/**
+ * User-facing label for the OS credential manager. Used by the keyring
+ * `TokenStore`'s fallback-warning composition; internal to the keyring
+ * module until a public caller asks for it.
+ */
+export const SECURE_STORE_DESCRIPTION = 'system credential manager';
+/**
+ * Default keyring `account` slug for a stored user. Lives here so every
+ * caller that derives a per-user slot name agrees on the wire format — a
+ * future rename can't silently park tokens in a slot the runtime no longer
+ * reads from.
+ */
+export const DEFAULT_ACCOUNT_FOR_USER = (id) => `user-${id}`;
 /**
  * Thrown when the OS credential manager cannot be reached — missing native
  * binary for the current architecture, libsecret/D-Bus unavailable

package/dist/auth/keyring/secure-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"secure-store.js","sourceRoot":"","sources":["../../../src/auth/keyring/secure-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAClD,YACI,OAAO,GAAG,0CAA0C,EACpD,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAA;IAC7C,CAAC;CACJ;AAiBD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IAC/D,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IACxC,IAAI,YAA6C,CAAA;IAEjD,KAAK,UAAU,SAAS,CAAI,EAAqC;QAC7D,IAAI,CAAC,YAAY,EAAE,CAAC;YAChB,gEAAgE;YAChE,+DAA+D;YAC/D,gEAAgE;YAChE,iCAAiC;YACjC,YAAY,GAAG,CAAC,KAAK,IAAI,EAAE;gBACvB,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;gBACvD,OAAO,IAAI,UAAU,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;YAC/C,CAAC,CAAC,EAAE,CAAA;QACR,CAAC;QACD,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAA;YAChC,OAAO,MAAM,EAAE,CAAC,KAAK,CAAC,CAAA;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,kBAAkB,CAAC,KAAK,CAAC,CAAA;QACnC,CAAC;IACL,CAAC;IAED,OAAO;QACH,KAAK,CAAC,SAAS;YACX,OAAO,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC,CAAA;QAC1E,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,MAAM;YAClB,OAAO,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBAC7B,MAAM,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;YACnC,CAAC,CAAC,CAAA;QACN,CAAC;QACD,KAAK,CAAC,YAAY;YACd,OAAO,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAA;QACzD,CAAC;KACJ,CAAA;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACtC,IAAI,KAAK,YAAY,2BAA2B,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAA;IAChB,CAAC;IACD,OAAO,IAAI,2BAA2B,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;AACpF,CAAC"}
+{"version":3,"file":"secure-store.js","sourceRoot":"","sources":["../../../src/auth/keyring/secure-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,2BAA2B,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAA;AAE5E;;;;;;;;;;GAUG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAClD,YACI,OAAO,GAAG,0CAA0C,EACpD,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAA;IAC7C,CAAC;CACJ;AAiBD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IAC/D,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IACxC,IAAI,YAA6C,CAAA;IAEjD,KAAK,UAAU,SAAS,CAAI,EAAqC;QAC7D,IAAI,CAAC,YAAY,EAAE,CAAC;YAChB,gEAAgE;YAChE,+DAA+D;YAC/D,gEAAgE;YAChE,iCAAiC;YACjC,YAAY,GAAG,CAAC,KAAK,IAAI,EAAE;gBACvB,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;gBACvD,OAAO,IAAI,UAAU,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;YAC/C,CAAC,CAAC,EAAE,CAAA;QACR,CAAC;QACD,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAA;YAChC,OAAO,MAAM,EAAE,CAAC,KAAK,CAAC,CAAA;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,kBAAkB,CAAC,KAAK,CAAC,CAAA;QACnC,CAAC;IACL,CAAC;IAED,OAAO;QACH,KAAK,CAAC,SAAS;YACX,OAAO,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC,CAAA;QAC1E,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,MAAM;YAClB,OAAO,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBAC7B,MAAM,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;YACnC,CAAC,CAAC,CAAA;QACN,CAAC;QACD,KAAK,CAAC,YAAY;YACd,OAAO,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAA;QACzD,CAAC;KACJ,CAAA;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACtC,IAAI,KAAK,YAAY,2BAA2B,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAA;IAChB,CAAC;IACD,OAAO,IAAI,2BAA2B,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;AACpF,CAAC"}

package/dist/auth/keyring/token-store.d.ts

@@ -0,0 +1,58 @@
+import type { AccountRef, AuthAccount, TokenStore } from '../types.js';
+import type { TokenStorageResult, UserRecordStore } from './types.js';
+export type CreateKeyringTokenStoreOptions<TAccount extends AuthAccount> = {
+    /** Application identifier used for every keyring entry (e.g. `'todoist-cli'`). */
+    serviceName: string;
+    /** Consumer-owned per-user record store (typically backed by their config file). */
+    userRecords: UserRecordStore<TAccount>;
+    /**
+     * Human-readable location of the record store, used in the fallback-warning
+     * text (e.g. `~/.config/todoist-cli/config.json`). Plain string; cli-core
+     * does not interpret it.
+     */
+    recordsLocation: string;
+    /**
+     * Builds the keyring `account` slug for a user id. Defaults to
+     * `user-${id}`. Override only when migrating from a legacy naming scheme.
+     */
+    accountForUser?: (id: string) => string;
+    /**
+     * Decides whether an account matches an `AccountRef` supplied via
+     * `--user <ref>`. Defaults to id-or-label equality. Override to broaden
+     * (e.g. case-insensitive email, alias map).
+     */
+    matchAccount?: (account: TAccount, ref: AccountRef) => boolean;
+};
+export type KeyringTokenStore<TAccount extends AuthAccount> = TokenStore<TAccount> & {
+    /** Storage result from the most recent `set()` call, or `undefined` before any (and reset to `undefined` when the most recent `set()` threw). */
+    getLastStorageResult(): TokenStorageResult | undefined;
+    /** Storage result from the most recent `clear()` call, or `undefined` before any (and reset to `undefined` when the most recent `clear()` threw or was a no-op). */
+    getLastClearResult(): TokenStorageResult | undefined;
+};
+/**
+ * Multi-account `TokenStore` that keeps secrets in the OS credential manager
+ * and per-user metadata in the consumer's `UserRecordStore`. Falls back to a
+ * plaintext token on the user record when the keyring is unreachable (WSL
+ * without D-Bus, missing native binary, locked Keychain, …) so the CLI keeps
+ * working at the cost of a visible warning.
+ *
+ * Read order in `active()` is `fallbackToken` first, then the keyring. That
+ * matches the write semantics in `writeRecordWithKeyringFallback`: when the
+ * keyring is online the record is written with no `fallbackToken`, so the
+ * keyring read is the only path. When the keyring is offline the token is
+ * parked on the record and must be reachable on every subsequent read.
+ *
+ * Write order is keyring first, then `userRecords.upsert`. If the upsert
+ * fails after a successful keyring write, the keyring entry is rolled back
+ * via `deleteSecret()` to avoid orphan credentials for a user that cli-core
+ * never managed to record.
+ *
+ * Clear order is the inverse: record removal first (the source of truth that
+ * the rest of the CLI reads), then keyring delete. Any keyring delete
+ * failure after a successful removal is downgraded to a warning — the orphan
+ * secret is harmless because no record references it anymore, and surfacing
+ * the error would corrupt local state (record gone, but caller sees a thrown
+ * exception and assumes the clear failed).
+ */
+export declare function createKeyringTokenStore<TAccount extends AuthAccount>(options: CreateKeyringTokenStoreOptions<TAccount>): KeyringTokenStore<TAccount>;
+//# sourceMappingURL=token-store.d.ts.map

package/dist/auth/keyring/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/token-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAUtE,OAAO,KAAK,EAAE,kBAAkB,EAAc,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjF,MAAM,MAAM,8BAA8B,CAAC,QAAQ,SAAS,WAAW,IAAI;IACvE,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAA;IACnB,oFAAoF;IACpF,WAAW,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;IACtC;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,KAAK,OAAO,CAAA;CACjE,CAAA;AAED,MAAM,MAAM,iBAAiB,CAAC,QAAQ,SAAS,WAAW,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG;IACjF,iJAAiJ;IACjJ,oBAAoB,IAAI,kBAAkB,GAAG,SAAS,CAAA;IACtD,oKAAoK;IACpK,kBAAkB,IAAI,kBAAkB,GAAG,SAAS,CAAA;CACvD,CAAA;AAOD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,SAAS,WAAW,EAChE,OAAO,EAAE,8BAA8B,CAAC,QAAQ,CAAC,GAClD,iBAAiB,CAAC,QAAQ,CAAC,CAgP7B"}

package/dist/auth/keyring/token-store.js

@@ -0,0 +1,240 @@
+import { CliError } from '../../errors.js';
+import { accountNotFoundError } from '../user-flag.js';
+import { writeRecordWithKeyringFallback } from './record-write.js';
+import { createSecureStore, DEFAULT_ACCOUNT_FOR_USER, SECURE_STORE_DESCRIPTION, SecureStoreUnavailableError, } from './secure-store.js';
+const DEFAULT_MATCH_ACCOUNT = (account, ref) => account.id === ref || account.label === ref;
+/**
+ * Multi-account `TokenStore` that keeps secrets in the OS credential manager
+ * and per-user metadata in the consumer's `UserRecordStore`. Falls back to a
+ * plaintext token on the user record when the keyring is unreachable (WSL
+ * without D-Bus, missing native binary, locked Keychain, …) so the CLI keeps
+ * working at the cost of a visible warning.
+ *
+ * Read order in `active()` is `fallbackToken` first, then the keyring. That
+ * matches the write semantics in `writeRecordWithKeyringFallback`: when the
+ * keyring is online the record is written with no `fallbackToken`, so the
+ * keyring read is the only path. When the keyring is offline the token is
+ * parked on the record and must be reachable on every subsequent read.
+ *
+ * Write order is keyring first, then `userRecords.upsert`. If the upsert
+ * fails after a successful keyring write, the keyring entry is rolled back
+ * via `deleteSecret()` to avoid orphan credentials for a user that cli-core
+ * never managed to record.
+ *
+ * Clear order is the inverse: record removal first (the source of truth that
+ * the rest of the CLI reads), then keyring delete. Any keyring delete
+ * failure after a successful removal is downgraded to a warning — the orphan
+ * secret is harmless because no record references it anymore, and surfacing
+ * the error would corrupt local state (record gone, but caller sees a thrown
+ * exception and assumes the clear failed).
+ */
+export function createKeyringTokenStore(options) {
+    const { serviceName, userRecords, recordsLocation } = options;
+    const accountForUser = options.accountForUser ?? DEFAULT_ACCOUNT_FOR_USER;
+    const matchAccount = options.matchAccount ?? DEFAULT_MATCH_ACCOUNT;
+    let lastStorageResult;
+    let lastClearResult;
+    function secureStoreFor(account) {
+        return createSecureStore({ serviceName, account: accountForUser(account.id) });
+    }
+    /**
+     * Read both `list()` and `getDefaultId()` concurrently. Used by paths
+     * that need the pinned default (no-ref `active`/`clear`, `list`, and
+     * `clear`'s default-unpin check).
+     */
+    async function readFullSnapshot() {
+        const [records, defaultId] = await Promise.all([
+            userRecords.list(),
+            userRecords.getDefaultId(),
+        ]);
+        return { records, defaultId };
+    }
+    /**
+     * Resolve the snapshot target for a given ref (or the implicit default
+     * when `ref === undefined`). Two failure modes:
+     *
+     * - Multiple records match the `ref`: ambiguous (the default matcher
+     *   includes `account.label`, and labels aren't guaranteed unique).
+     *   Throws `NO_ACCOUNT_SELECTED` so the user picks a tighter ref instead
+     *   of silently acting on whichever record `list()` returned first.
+     * - `ref === undefined`, no `defaultId` pinned, and more than one record
+     *   exists. Same code — `setDefaultId` is best-effort during `set()`,
+     *   so a typed failure here is the only non-misleading signal for "you
+     *   have multiple accounts; pick one".
+     */
+    function resolveTarget(snapshot, ref) {
+        if (ref !== undefined) {
+            const matches = snapshot.records.filter((record) => matchAccount(record.account, ref));
+            if (matches.length > 1) {
+                throw new CliError('NO_ACCOUNT_SELECTED', `Multiple stored accounts match "${ref}". Pass a more specific --user <ref> (e.g. a unique account id).`);
+            }
+            return matches[0] ?? null;
+        }
+        if (snapshot.defaultId) {
+            const pinned = snapshot.records.find((r) => r.account.id === snapshot.defaultId);
+            if (pinned)
+                return pinned;
+        }
+        if (snapshot.records.length === 1)
+            return snapshot.records[0];
+        if (snapshot.records.length === 0)
+            return null;
+        throw new CliError('NO_ACCOUNT_SELECTED', 'Multiple accounts are stored but none is set as the default. Pass --user <ref>, or set a default in your CLI.');
+    }
+    function fallbackResult(action) {
+        return {
+            storage: 'config-file',
+            warning: `${SECURE_STORE_DESCRIPTION} unavailable; ${action} ${recordsLocation}`,
+        };
+    }
+    return {
+        async active(ref) {
+            // Ref-only path skips `getDefaultId()` — `resolveTarget` never
+            // touches it when `ref` is supplied, so the extra read would be
+            // pure latency on every authenticated command.
+            const snapshot = ref === undefined
+                ? await readFullSnapshot()
+                : { records: await userRecords.list(), defaultId: null };
+            const record = resolveTarget(snapshot, ref);
+            if (!record)
+                return null;
+            const fallback = record.fallbackToken?.trim();
+            if (fallback) {
+                return { token: fallback, account: record.account };
+            }
+            let raw;
+            try {
+                raw = await secureStoreFor(record.account).getSecret();
+            }
+            catch (error) {
+                // A matching record exists but the keyring can't be read.
+                // Surface a typed failure instead of returning `null`, which
+                // would otherwise be indistinguishable from "no stored
+                // account" and trigger `ACCOUNT_NOT_FOUND` on `--user <ref>`.
+                // `attachLogoutCommand` catches this specific code so an
+                // explicit `logout --user <ref>` can still clear the matching
+                // record without needing the unreadable token.
+                if (error instanceof SecureStoreUnavailableError) {
+                    throw new CliError('AUTH_STORE_READ_FAILED', `${SECURE_STORE_DESCRIPTION} unavailable; could not read stored token (${error.message})`);
+                }
+                throw error;
+            }
+            const token = raw?.trim();
+            if (token) {
+                return { token, account: record.account };
+            }
+            // Record exists, no `fallbackToken`, and the keyring slot is
+            // empty — the credential was deleted out-of-band (user ran
+            // `security delete-generic-password`, `secret-tool clear`, …).
+            // This is corrupted state, not a miss; collapsing it to `null`
+            // would make `--user <ref>` surface as `ACCOUNT_NOT_FOUND` and
+            // hide the real problem.
+            throw new CliError('AUTH_STORE_READ_FAILED', `${SECURE_STORE_DESCRIPTION} returned no credential for the stored account; the keyring entry may have been removed externally.`);
+        },
+        async set(account, token) {
+            // Reset the cached storage result up front so a caller that
+            // catches a thrown `set()` doesn't observe the previous call's
+            // warning leaking through `getLastStorageResult`.
+            lastStorageResult = undefined;
+            const { storedSecurely } = await writeRecordWithKeyringFallback({
+                secureStore: secureStoreFor(account),
+                userRecords,
+                account,
+                token,
+            });
+            // Best-effort default promotion: the record is already persisted,
+            // so a failure here must not turn into `AUTH_STORE_WRITE_FAILED`
+            // (the user can recover by setting a default later).
+            try {
+                const existingDefault = await userRecords.getDefaultId();
+                if (!existingDefault) {
+                    await userRecords.setDefaultId(account.id);
+                }
+            }
+            catch {
+                // best-effort
+            }
+            lastStorageResult = storedSecurely
+                ? { storage: 'secure-store' }
+                : fallbackResult('token saved as plaintext in');
+        },
+        async clear(ref) {
+            // Reset up front for the same reason as `set` — and so a no-op
+            // (no matching record) clears any stale result from a previous
+            // call.
+            lastClearResult = undefined;
+            // `clear` always needs the pinned default to decide whether to
+            // un-pin after the removal, so we can't skip `getDefaultId()`
+            // even on the explicit-ref path.
+            const snapshot = await readFullSnapshot();
+            const record = resolveTarget(snapshot, ref);
+            if (!record)
+                return;
+            await userRecords.remove(record.account.id);
+            // Default un-pinning is best-effort: a failure here must not
+            // skip the keyring delete below, otherwise we leave an
+            // unreachable orphan secret behind for the just-removed record.
+            if (snapshot.defaultId === record.account.id) {
+                try {
+                    await userRecords.setDefaultId(null);
+                }
+                catch {
+                    // best-effort
+                }
+            }
+            const fallbackClear = fallbackResult('local auth state cleared in');
+            // Always attempt the keyring delete. Even when the record carried
+            // a `fallbackToken`, an older keyring entry may still be parked
+            // there from a prior keyring-online write that was later replaced
+            // by an offline-fallback write — skipping the delete would leak
+            // that orphan. Downgrade *any* failure to a warning: the record
+            // is already gone, so re-throwing would corrupt local state
+            // (caller sees an exception and assumes nothing was cleared,
+            // even though the next `account list` will show the user gone).
+            try {
+                await secureStoreFor(record.account).deleteSecret();
+                lastClearResult =
+                    record.fallbackToken !== undefined ? fallbackClear : { storage: 'secure-store' };
+            }
+            catch {
+                lastClearResult = fallbackClear;
+            }
+        },
+        async list() {
+            const snapshot = await readFullSnapshot();
+            // Use `resolveTarget` to compute the *effective* default so the
+            // `isDefault` markers match what `active()` would resolve — that
+            // includes the implicit single-record case. `resolveTarget` can
+            // throw `NO_ACCOUNT_SELECTED`, which we want to swallow here
+            // (listing accounts is a diagnostic operation that must work
+            // even when no default is pinned).
+            let implicitDefault = null;
+            try {
+                implicitDefault = resolveTarget(snapshot, undefined);
+            }
+            catch {
+                // multiple records, no default → `isDefault: false` for all
+            }
+            return snapshot.records.map((record) => ({
+                account: record.account,
+                isDefault: record.account.id === implicitDefault?.account.id,
+            }));
+        },
+        async setDefault(ref) {
+            // Ref-only path — skip `getDefaultId()` like `active(ref)`.
+            const snapshot = { records: await userRecords.list(), defaultId: null };
+            const record = resolveTarget(snapshot, ref);
+            if (!record) {
+                throw accountNotFoundError(ref);
+            }
+            await userRecords.setDefaultId(record.account.id);
+        },
+        getLastStorageResult() {
+            return lastStorageResult;
+        },
+        getLastClearResult() {
+            return lastClearResult;
+        },
+    };
+}
+//# sourceMappingURL=token-store.js.map

package/dist/auth/keyring/token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.js","sourceRoot":"","sources":["../../../src/auth/keyring/token-store.ts"],"names":[],"mappings":"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"}

package/dist/auth/keyring/types.d.ts

@@ -0,0 +1,48 @@
+import type { AuthAccount } from '../types.js';
+/** Where a token was (or wasn't) persisted on the most recent write/clear. */
+export type TokenStorageLocation = 'secure-store' | 'config-file';
+export type TokenStorageResult = {
+    storage: TokenStorageLocation;
+    /**
+     * Present when the OS keyring was unavailable and the operation fell back
+     * to (or left state in) the consumer's config file. Suitable for surfacing
+     * to the user as a `Warning:` line on stderr.
+     */
+    warning?: string;
+};
+export type UserRecord<TAccount extends AuthAccount> = {
+    account: TAccount;
+    /**
+     * Plaintext token, present only when the keyring was unavailable at write
+     * time. The runtime reads it in preference to the keyring slot, so a
+     * stale fallback would mask a fresh keyring-backed write — consumers
+     * implementing `upsert` as replace-not-merge (per the contract below)
+     * guarantees the field is cleared on every successful keyring write.
+     * Surface its presence as security-relevant: it is the same material
+     * that would otherwise live in the OS credential manager.
+     */
+    fallbackToken?: string;
+};
+/**
+ * Port the consumer implements to expose their per-user config records to
+ * cli-core's keyring-backed `TokenStore`. The shape of the record map (file
+ * format, path, schema versioning) stays in the consumer — cli-core only
+ * needs CRUD on these primitives plus a default-user pointer.
+ */
+export type UserRecordStore<TAccount extends AuthAccount> = {
+    list(): Promise<UserRecord<TAccount>[]>;
+    /**
+     * **Replace**, do not merge. The persisted record must equal `record` field
+     * for field — an absent `fallbackToken` means "no plaintext token", and a
+     * merge-style implementation would let a stale plaintext token outlive a
+     * later keyring-backed write (the runtime preferentially reads
+     * `fallbackToken` over the keyring). Records are keyed by `account.id`.
+     */
+    upsert(record: UserRecord<TAccount>): Promise<void>;
+    /** Remove the record whose `account.id` matches. */
+    remove(id: string): Promise<void>;
+    /** The pinned default's `account.id`, or `null` when nothing is pinned. */
+    getDefaultId(): Promise<string | null>;
+    setDefaultId(id: string | null): Promise<void>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/keyring/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/auth/keyring/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,aAAa,CAAA;AAEjE,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,oBAAoB,CAAA;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,UAAU,CAAC,QAAQ,SAAS,WAAW,IAAI;IACnD,OAAO,EAAE,QAAQ,CAAA;IACjB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,QAAQ,SAAS,WAAW,IAAI;IACxD,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACvC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,oDAAoD;IACpD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,2EAA2E;IAC3E,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACtC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjD,CAAA"}

package/dist/auth/keyring/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/auth/keyring/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/auth/keyring/types.ts"],"names":[],"mappings":""}

package/dist/auth/user-flag.d.ts

@@ -1,8 +1,11 @@
 import type { Command } from 'commander';
+import { CliError } from '../errors.js';
 import type { AccountRef, AuthAccount, TokenStore } from './types.js';
 export declare function attachUserFlag(command: Command): Command;
 /** `cmd.user` as an `AccountRef`, or `undefined` when absent. */
 export declare function extractUserRef(cmd: Record<string, unknown>): AccountRef | undefined;
+/** Shared constructor so multiple call sites can't drift on the `ACCOUNT_NOT_FOUND` wording. */
+export declare function accountNotFoundError(ref: AccountRef): CliError;
 /**
  * Read `store.active(ref)` and throw `ACCOUNT_NOT_FOUND` if the explicit
  * `ref` doesn't match. With `ref === undefined` returns the snapshot

package/dist/auth/user-flag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-flag.d.ts","sourceRoot":"","sources":["../../src/auth/user-flag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AASrE,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAExD;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,GAAG,SAAS,CAEnF;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,SAAS,WAAW,EACpE,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC3B,GAAG,EAAE,UAAU,GAAG,SAAS,GAC5B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GAAG,IAAI,CAAC,CAMtD"}
+{"version":3,"file":"user-flag.d.ts","sourceRoot":"","sources":["../../src/auth/user-flag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AASrE,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAExD;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,GAAG,SAAS,CAEnF;AAED,gGAAgG;AAChG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,QAAQ,CAE9D;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,SAAS,WAAW,EACpE,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC3B,GAAG,EAAE,UAAU,GAAG,SAAS,GAC5B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GAAG,IAAI,CAAC,CAMtD"}

package/dist/auth/user-flag.js

@@ -11,6 +11,10 @@ export function attachUserFlag(command) {
 export function extractUserRef(cmd) {
     return typeof cmd.user === 'string' ? cmd.user : undefined;
 }
+/** Shared constructor so multiple call sites can't drift on the `ACCOUNT_NOT_FOUND` wording. */
+export function accountNotFoundError(ref) {
+    return new CliError('ACCOUNT_NOT_FOUND', `No stored account matches "${ref}".`);
+}
 /**
  * Read `store.active(ref)` and throw `ACCOUNT_NOT_FOUND` if the explicit
  * `ref` doesn't match. With `ref === undefined` returns the snapshot
@@ -19,7 +23,7 @@ export function extractUserRef(cmd) {
 export async function requireSnapshotForRef(store, ref) {
     const snapshot = await store.active(ref);
     if (ref !== undefined && snapshot === null) {
-        throw new CliError('ACCOUNT_NOT_FOUND', `No stored account matches "${ref}".`);
+        throw accountNotFoundError(ref);
     }
     return snapshot;
 }

package/dist/auth/user-flag.js.map

@@ -1 +1 @@
-{"version":3,"file":"user-flag.js","sourceRoot":"","sources":["../../src/auth/user-flag.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAGvC,4EAA4E;AAC5E,0EAA0E;AAC1E,eAAe;AAEf,MAAM,SAAS,GAAG,cAAc,CAAA;AAChC,MAAM,qBAAqB,GAAG,kCAAkC,CAAA;AAEhE,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC3C,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAA;AAC3D,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,GAA4B;IACvD,OAAO,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACvC,KAA2B,EAC3B,GAA2B;IAE3B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACxC,IAAI,GAAG,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,QAAQ,CAAC,mBAAmB,EAAE,8BAA8B,GAAG,IAAI,CAAC,CAAA;IAClF,CAAC;IACD,OAAO,QAAQ,CAAA;AACnB,CAAC"}
+{"version":3,"file":"user-flag.js","sourceRoot":"","sources":["../../src/auth/user-flag.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAGvC,4EAA4E;AAC5E,0EAA0E;AAC1E,eAAe;AAEf,MAAM,SAAS,GAAG,cAAc,CAAA;AAChC,MAAM,qBAAqB,GAAG,kCAAkC,CAAA;AAEhE,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC3C,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAA;AAC3D,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,GAA4B;IACvD,OAAO,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9D,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,oBAAoB,CAAC,GAAe;IAChD,OAAO,IAAI,QAAQ,CAAC,mBAAmB,EAAE,8BAA8B,GAAG,IAAI,CAAC,CAAA;AACnF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACvC,KAA2B,EAC3B,GAA2B;IAE3B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACxC,IAAI,GAAG,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACzC,MAAM,oBAAoB,CAAC,GAAG,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,QAAQ,CAAA;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/cli-core",
-    "version": "0.14.0",
+    "version": "0.16.0",
     "description": "Shared core utilities for Doist CLI projects",
     "type": "module",
     "main": "dist/index.js",