@huaweidevtools/aishell-dsh-credentials-store 0.0.7 → 0.0.9

package/lib/types/backends/keyring.js

@@ -0,0 +1,107 @@
+/**
+ * OS-keyring backend — the durable, cross-process credential store.
+ *
+ * Wraps `@napi-rs/keyring` (macOS Keychain / Linux Secret Service / Windows
+ * Credential Manager). Values persist across process restarts and reboots
+ * because the OS owns the store.
+ *
+ * ## Why Linux pins the Secret Service store
+ *
+ * On Linux the binding picks a store itself: Secret Service (gnome-keyring,
+ * KWallet, KeePassXC) first, then — silently — the kernel keyutils keyring.
+ * That fallback is wrong for credentials, and the binding's README says so:
+ * the kernel keyring is "completely in-memory and will not persist across
+ * reboots". A machine with no Secret Service (a container, CI, a systemd unit
+ * with no session bus) would therefore accept credentials, report them stored,
+ * and lose them at the next reboot — with `credentialsStored: true` left in
+ * the profile pointing at nothing.
+ *
+ * Pinning `{ linux: { store: 'secret-service' } }` makes an unavailable
+ * service throw from the constructor probe instead, so
+ * {@link createCredentialsStore} falls through to the machine-fingerprint
+ * encrypted file: durable, and honest about where the value lives. Requiring
+ * the store is the only way to get that throw — the default selection reports
+ * success either way.
+ *
+ * Native keyring errors are caught: `get`/`has` return `undefined`/`false` so
+ * callers degrade gracefully; `set`/`delete` throw a descriptive error so the
+ * caller knows the store is unavailable.
+ */
+import { createRequire } from 'node:module';
+import { KEYRING_SERVICE } from "../scope.js";
+// Lazily resolved so a missing native binding (the known @napi-rs optional-deps
+// bug, or a platform with no prebuilt binary) throws inside the constructor
+// probe — where createCredentialsStore's try/catch catches it and falls back
+// to FingerprintBackend — instead of crashing at module-load time.
+const require = createRequire(import.meta.url);
+let keyringModule;
+/** @internal Test hook: inject a mock keyring module (vi.mock cannot intercept createRequire). */
+export function __setKeyringModule(mock) {
+    keyringModule = mock;
+}
+function loadKeyring() {
+    if (keyringModule === undefined)
+        keyringModule = require('@napi-rs/keyring');
+    return keyringModule;
+}
+/**
+ * OS-keyring {@link CredentialsStore}. Constructed with a shared service name;
+ * every entry is stored under `new Entry(service, account, { linux: { store:
+ * 'secret-service' } })`.
+ *
+ * Construction probes the keyring once — if the native module cannot be loaded
+ * (no prebuilt binding for this platform), or the Linux Secret Service is
+ * unavailable, it throws and {@link createCredentialsStore} falls back to the
+ * next backend. Without the pin the absent-service case does not throw; see
+ * the module note.
+ */
+export class KeyringBackend {
+    serviceName;
+    options;
+    Entry;
+    constructor(_config = {}) {
+        this.serviceName = KEYRING_SERVICE;
+        // Required, not preferred: an unavailable Secret Service must throw here so
+        // the factory can fall through to a durable backend, rather than silently
+        // landing in the kernel keyring's reboot-volatile store.
+        this.options = { linux: { store: 'secret-service' } };
+        this.Entry = loadKeyring().Entry;
+        // Probe: a getPassword on a throwaway account exercises the native path.
+        new this.Entry(this.serviceName, '__probe__', this.options).getPassword();
+    }
+    get(account) {
+        try {
+            const value = new this.Entry(this.serviceName, account, this.options).getPassword();
+            return value ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    set(account, value) {
+        if (value.length === 0)
+            throw new Error('credential value must be non-empty');
+        new this.Entry(this.serviceName, account, this.options).setPassword(value);
+    }
+    delete(account) {
+        try {
+            new this.Entry(this.serviceName, account, this.options).deletePassword();
+        }
+        catch (error) {
+            // deletePassword on an absent entry may throw on some backends;
+            // treat that as a no-op rather than an error.
+            if (!String(error).includes('not found') && !String(error).includes('no entry')) {
+                throw error;
+            }
+        }
+    }
+    has(account) {
+        try {
+            return new this.Entry(this.serviceName, account, this.options).getPassword() !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=keyring.js.map

package/lib/types/backends/keyring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyring.js","sourceRoot":"","sources":["../../../src/backends/keyring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAG7C,gFAAgF;AAChF,4EAA4E;AAC5E,6EAA6E;AAC7E,mEAAmE;AACnE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAW9C,IAAI,aAAwC,CAAA;AAE5C,kGAAkG;AAClG,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,aAAa,GAAG,IAAI,CAAA;AACtB,CAAC;AAED,SAAS,WAAW;IAClB,IAAI,aAAa,KAAK,SAAS;QAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAkB,CAAA;IAC7F,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,cAAc;IACR,WAAW,CAAQ;IACnB,OAAO,CAAqB;IAC5B,KAAK,CAAwB;IAE9C,YAAY,UAAkC,EAAE;QAC9C,IAAI,CAAC,WAAW,GAAG,eAAe,CAAA;QAClC,4EAA4E;QAC5E,0EAA0E;QAC1E,yDAAyD;QACzD,IAAI,CAAC,OAAO,GAAG,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,CAAA;QACrD,IAAI,CAAC,KAAK,GAAG,WAAW,EAAE,CAAC,KAAK,CAAA;QAChC,yEAAyE;QACzE,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAA;IAC3E,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAA;YACnF,OAAO,KAAK,IAAI,SAAS,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED,GAAG,CAAC,OAAe,EAAE,KAAa;QAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;QAC7E,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;IAC5E,CAAC;IAED,MAAM,CAAC,OAAe;QACpB,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,CAAA;QAC1E,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,gEAAgE;YAChE,8CAA8C;YAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChF,MAAM,KAAK,CAAA;YACb,CAAC;QACH,CAAC;IACH,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,IAAI,CAAC;YACH,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAA;QACvF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;CACF"}

package/lib/types/backends/memory.d.ts

@@ -0,0 +1,45 @@
+/**
+ * In-memory backend — the volatile last-resort credential store.
+ *
+ * Used when the OS keyring is unavailable (no secret service, keychain
+ * locked, headless box without D-Bus). Entries live in a process-scoped
+ * `Map` and are lost when the process exits — durable enough for a single
+ * DSH session, not for persistence.
+ *
+ * Callers never select this directly; {@link createCredentialsStore} falls
+ * back to it when {@link KeyringBackend} cannot initialize.
+ *
+ * ## Why the shared instance is not this class's business
+ *
+ * Each plugin that stores credentials calls `createCredentialsStore()` for
+ * itself — four of them — and every call constructs a fresh backend. That is
+ * harmless for the keyring and the encrypted file, which are process-external
+ * and therefore shared by construction, but a private `Map` is not: without
+ * the sharing below, the plugin that saved a credential and the plugin that
+ * read it would be looking at different maps, and the second would report
+ * "not authenticated" on a machine where the person had just authenticated.
+ *
+ * The sharing lives in {@link sharedMemoryBackend} rather than in this class
+ * so that `new MemoryBackend()` keeps producing an independent store. Tests
+ * rely on that — a spec constructing one expects it to start empty, and a
+ * singleton class would leak state between spec files.
+ */
+import type { CredentialsStore, CredentialsStoreConfig } from '../index.ts';
+/** Process-scoped {@link CredentialsStore}; entries vanish on exit. */
+export declare class MemoryBackend implements CredentialsStore {
+    private readonly entries;
+    constructor(_config?: CredentialsStoreConfig);
+    get(account: string): string | undefined;
+    set(account: string, value: string): void;
+    delete(account: string): void;
+    has(account: string): boolean;
+}
+export declare function sharedMemoryBackend(config?: CredentialsStoreConfig): MemoryBackend;
+/**
+ * Drop the shared instance.
+ *
+ * For tests, which need each case to start from an empty store. Not called in
+ * production: discarding the instance would discard every credential in it.
+ */
+export declare function __resetSharedMemoryBackend(): void;
+//# sourceMappingURL=memory.d.ts.map

package/lib/types/backends/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/backends/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAE3E,uEAAuE;AACvE,qBAAa,aAAc,YAAW,gBAAgB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,GAAE,sBAA2B;IAKhD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAG9B;AA8BD,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,sBAA2B,GAAG,aAAa,CAGtF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/lib/types/backends/memory.js

@@ -0,0 +1,89 @@
+/**
+ * In-memory backend — the volatile last-resort credential store.
+ *
+ * Used when the OS keyring is unavailable (no secret service, keychain
+ * locked, headless box without D-Bus). Entries live in a process-scoped
+ * `Map` and are lost when the process exits — durable enough for a single
+ * DSH session, not for persistence.
+ *
+ * Callers never select this directly; {@link createCredentialsStore} falls
+ * back to it when {@link KeyringBackend} cannot initialize.
+ *
+ * ## Why the shared instance is not this class's business
+ *
+ * Each plugin that stores credentials calls `createCredentialsStore()` for
+ * itself — four of them — and every call constructs a fresh backend. That is
+ * harmless for the keyring and the encrypted file, which are process-external
+ * and therefore shared by construction, but a private `Map` is not: without
+ * the sharing below, the plugin that saved a credential and the plugin that
+ * read it would be looking at different maps, and the second would report
+ * "not authenticated" on a machine where the person had just authenticated.
+ *
+ * The sharing lives in {@link sharedMemoryBackend} rather than in this class
+ * so that `new MemoryBackend()` keeps producing an independent store. Tests
+ * rely on that — a spec constructing one expects it to start empty, and a
+ * singleton class would leak state between spec files.
+ */
+/** Process-scoped {@link CredentialsStore}; entries vanish on exit. */
+export class MemoryBackend {
+    entries = new Map();
+    constructor(_config = {}) {
+        // Service name is accepted for API symmetry with KeyringBackend but not
+        // used: the in-process Map is keyed by account alone.
+    }
+    get(account) {
+        return this.entries.get(account);
+    }
+    set(account, value) {
+        if (value.length === 0)
+            throw new Error('credential value must be non-empty');
+        this.entries.set(account, value);
+    }
+    delete(account) {
+        this.entries.delete(account);
+    }
+    has(account) {
+        return this.entries.has(account);
+    }
+}
+/**
+ * The one memory backend the factory hands to every caller in this process.
+ *
+ * ## Why a module-level instance and not a class singleton
+ *
+ * `createCredentialsStore()` is called once per plugin — four of them — and
+ * the memory backend is the only one of the three that is not shared by
+ * construction. The keyring is a daemon and the encrypted file is a path, so
+ * two callers reaching either are reading the same bytes; two `Map`s are not.
+ * Without this, a machine with no keyring would have one plugin storing a
+ * credential and another unable to see it.
+ *
+ * Held here rather than on the class so `new MemoryBackend()` stays
+ * independent, which the specs depend on.
+ *
+ * ## Why the lazily-created shape
+ *
+ * The instance is created on first use rather than at module load, so
+ * importing this module has no effect a test has to account for — the specs
+ * that swap the keyring module in and out must not leave a populated store
+ * behind.
+ *
+ * @param config - forwarded on first construction only; later callers reuse
+ *   the instance, since the memory backend keeps nothing config decides.
+ * @returns the shared backend.
+ */
+let shared;
+export function sharedMemoryBackend(config = {}) {
+    shared ??= new MemoryBackend(config);
+    return shared;
+}
+/**
+ * Drop the shared instance.
+ *
+ * For tests, which need each case to start from an empty store. Not called in
+ * production: discarding the instance would discard every credential in it.
+ */
+export function __resetSharedMemoryBackend() {
+    shared = undefined;
+}
+//# sourceMappingURL=memory.js.map

package/lib/types/backends/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/backends/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,uEAAuE;AACvE,MAAM,OAAO,aAAa;IACP,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IAEpD,YAAY,UAAkC,EAAE;QAC9C,wEAAwE;QACxE,sDAAsD;IACxD,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED,GAAG,CAAC,OAAe,EAAE,KAAa;QAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;QAC7E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IAClC,CAAC;IAED,MAAM,CAAC,OAAe;QACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAC9B,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,IAAI,MAAiC,CAAA;AAErC,MAAM,UAAU,mBAAmB,CAAC,SAAiC,EAAE;IACrE,MAAM,KAAK,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B;IACxC,MAAM,GAAG,SAAS,CAAA;AACpB,CAAC"}

package/lib/types/failover.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Write-failover wrapper — covers the failure class the construction-time
+ * probe chain cannot see.
+ *
+ * {@link createCredentialsStore} picks a backend by probing at construction
+ * time, but the highest-priority backend (the OS keyring) can pass that probe
+ * and still reject every real write: a locked GNOME keyring collection reads
+ * as `null` (the probe's getPassword does not throw) while setPassword fails.
+ * Measured on an isolated D-Bus session:
+ *
+ * - locked collection, no default alias — read 5 ms → null; write 5 ms →
+ *   "Couldn't access platform storage: Secret Service: no result found"
+ * - locked collection, default alias set (the real-desktop shape) — read
+ *   still null; write blocks on the system unlock prompter and rejects with
+ *   "Secret Service: unlock prompt was dismissed" when canceled
+ *
+ * So the write path needs its own fallback chain, and it must be sticky: a
+ * locked keyring fails every write, so retrying it per call would surface the
+ * same error (or the same prompt) once per account a save writes. Deletes trip
+ * the same failover: a locked collection rejects them with the same error, and
+ * the save route (delete old set → write new set) deletes first — without
+ * this, a locked keyring would fail the save before the write failover ever
+ * engages.
+ *
+ * ## Which copy wins
+ *
+ * A locked collection answers `null` for entries that are really there, so the
+ * primary's copy of an account can be arbitrarily out of date while still
+ * reading as authoritative. Once it unlocks, that copy would outrank the value
+ * the user saved in the meantime — resurrecting a credential the user rotated
+ * or cleared, with every later signature using the superseded key.
+ *
+ * The two backends cannot be compared by recency (neither records one), so the
+ * fallback is treated as authoritative for any account it has an opinion
+ * about, and the primary answers only when the fallback has none:
+ *
+ *   - **A value in the fallback wins.** It is there because a failover write
+ *     put it there, and that write is by definition newer than whatever the
+ *     primary holds. No bookkeeping is needed — the value shadows the primary
+ *     simply by existing.
+ *   - **A tombstone means deleted.** A clear whose primary delete failed has
+ *     nothing to shadow with, so it writes an explicit marker; without one, the
+ *     stale primary copy would read back as present.
+ *   - **Otherwise the primary answers**, which is the ordinary healthy path.
+ *
+ * A successful primary write or delete clears both the fallback value and the
+ * tombstone, handing authority back to the keyring.
+ *
+ * Recording deletion this way — rather than marking accounts "stale" on every
+ * failover write — keeps the value and its shadow in one place. A mark set by a
+ * write would have to be cleared in lockstep with the value, and a mark left
+ * behind after its value was gone would make a perfect keyring credential read
+ * as *absent* rather than merely stale.
+ *
+ * ## Why the record is persisted, not held in memory
+ *
+ * The state it describes outlives the store: the failure is "the keyring is
+ * locked now", and the read that would resurrect the credential happens in a
+ * later session, after it has unlocked. It is therefore stored in the fallback
+ * backend itself — the encrypted file in practice, and merely the process in
+ * the memory-backed last resort, where the failover is no more durable either.
+ * Keys carry a NUL prefix, which no real credential account can collide with.
+ *
+ * ## Cost on the healthy path
+ *
+ * The fallback is consulted on every read (once for a value, once for a
+ * tombstone). On a machine whose keyring has never failed the fallback has
+ * written nothing, so its file does not exist and both lookups are
+ * sub-millisecond `existsSync` misses (measured 0.02-0.4 ms). Where a fallback
+ * file does exist, each lookup decrypts it — the read-through this replaced
+ * already paid one decrypt per miss.
+ *
+ * The fallback is built on the first read rather than the first failed write,
+ * which a machine with a working keyring pays once per store: ~97 ms, almost
+ * all of it the fingerprint backend's scrypt probe (measured). It is lazy and
+ * cached, so later reads are unaffected.
+ *
+ * @module
+ */
+import type { CredentialsStore } from './index.ts';
+/** Options for {@link FailoverStore}. */
+export interface FailoverStoreOptions {
+    /**
+     * Builds the store that takes over when the primary fails a write. Called
+     * at most once, lazily, on first need — a read miss or the first failed
+     * write — so a healthy keyring never pays for constructing it. Must not
+     * throw: the factory's closure ends in MemoryBackend.
+     */
+    readonly createFallback: () => CredentialsStore;
+}
+/**
+ * A {@link CredentialsStore} that delegates to a primary until the primary
+ * fails a write, then fails over — for the life of this store — to a
+ * fallback supplied by {@link FailoverStoreOptions.createFallback}.
+ *
+ * Stickiness is per instance, not per process: each plugin that consumes
+ * credentials builds its own store, so one instance failing over does not stop
+ * another from trying the primary. That is intended — the flag only exists to
+ * avoid re-hitting a primary already known to be unwritable from *this* store,
+ * and a second instance's attempt is one probe rather than a policy decision.
+ * Correctness across instances comes from the persisted record, not the flag.
+ *
+ * Constructed by {@link createCredentialsStore} around a KeyringBackend whose
+ * construction probe passed; not meant for direct use by upper layers.
+ */
+export declare class FailoverStore implements CredentialsStore {
+    private readonly primary;
+    private readonly createFallback;
+    private fallback;
+    /** Set by the first failed primary write; routes writes thereafter. */
+    private failedOver;
+    constructor(primary: CredentialsStore, options: FailoverStoreOptions);
+    /** The lazily built fallback; constructed at most once per store. */
+    private get fallbackStore();
+    /**
+     * Drop the tombstone for `account`, if any.
+     *
+     * Paired with the value purge on every path that hands authority back to the
+     * primary. Best-effort: a tombstone that outlives its purpose costs one extra
+     * fallback lookup, which must never fail a write the keyring has accepted.
+     */
+    private clearTombstone;
+    get(account: string): string | undefined;
+    has(account: string): boolean;
+    set(account: string, value: string): void;
+    delete(account: string): void;
+    /**
+     * Record the deletion, or report its failure.
+     *
+     * Unlike the best-effort cleanups above, a tombstone that cannot be written
+     * means the delete silently did not happen and the credential will read back
+     * later. That is a failed clear, so it throws rather than being swallowed.
+     */
+    private writeTombstone;
+}
+//# sourceMappingURL=failover.d.ts.map

package/lib/types/failover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failover.d.ts","sourceRoot":"","sources":["../../src/failover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAmBlD,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,gBAAgB,CAAA;CAChD;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,YAAW,gBAAgB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,uEAAuE;IACvE,OAAO,CAAC,UAAU,CAAQ;gBAEd,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,oBAAoB;IAKpE,qEAAqE;IACrE,OAAO,KAAK,aAAa,GAGxB;IAED;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAQtB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUxC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAM7B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAyCzC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IA8B7B;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAGvB"}

package/lib/types/failover.js

@@ -0,0 +1,242 @@
+/**
+ * Write-failover wrapper — covers the failure class the construction-time
+ * probe chain cannot see.
+ *
+ * {@link createCredentialsStore} picks a backend by probing at construction
+ * time, but the highest-priority backend (the OS keyring) can pass that probe
+ * and still reject every real write: a locked GNOME keyring collection reads
+ * as `null` (the probe's getPassword does not throw) while setPassword fails.
+ * Measured on an isolated D-Bus session:
+ *
+ * - locked collection, no default alias — read 5 ms → null; write 5 ms →
+ *   "Couldn't access platform storage: Secret Service: no result found"
+ * - locked collection, default alias set (the real-desktop shape) — read
+ *   still null; write blocks on the system unlock prompter and rejects with
+ *   "Secret Service: unlock prompt was dismissed" when canceled
+ *
+ * So the write path needs its own fallback chain, and it must be sticky: a
+ * locked keyring fails every write, so retrying it per call would surface the
+ * same error (or the same prompt) once per account a save writes. Deletes trip
+ * the same failover: a locked collection rejects them with the same error, and
+ * the save route (delete old set → write new set) deletes first — without
+ * this, a locked keyring would fail the save before the write failover ever
+ * engages.
+ *
+ * ## Which copy wins
+ *
+ * A locked collection answers `null` for entries that are really there, so the
+ * primary's copy of an account can be arbitrarily out of date while still
+ * reading as authoritative. Once it unlocks, that copy would outrank the value
+ * the user saved in the meantime — resurrecting a credential the user rotated
+ * or cleared, with every later signature using the superseded key.
+ *
+ * The two backends cannot be compared by recency (neither records one), so the
+ * fallback is treated as authoritative for any account it has an opinion
+ * about, and the primary answers only when the fallback has none:
+ *
+ *   - **A value in the fallback wins.** It is there because a failover write
+ *     put it there, and that write is by definition newer than whatever the
+ *     primary holds. No bookkeeping is needed — the value shadows the primary
+ *     simply by existing.
+ *   - **A tombstone means deleted.** A clear whose primary delete failed has
+ *     nothing to shadow with, so it writes an explicit marker; without one, the
+ *     stale primary copy would read back as present.
+ *   - **Otherwise the primary answers**, which is the ordinary healthy path.
+ *
+ * A successful primary write or delete clears both the fallback value and the
+ * tombstone, handing authority back to the keyring.
+ *
+ * Recording deletion this way — rather than marking accounts "stale" on every
+ * failover write — keeps the value and its shadow in one place. A mark set by a
+ * write would have to be cleared in lockstep with the value, and a mark left
+ * behind after its value was gone would make a perfect keyring credential read
+ * as *absent* rather than merely stale.
+ *
+ * ## Why the record is persisted, not held in memory
+ *
+ * The state it describes outlives the store: the failure is "the keyring is
+ * locked now", and the read that would resurrect the credential happens in a
+ * later session, after it has unlocked. It is therefore stored in the fallback
+ * backend itself — the encrypted file in practice, and merely the process in
+ * the memory-backed last resort, where the failover is no more durable either.
+ * Keys carry a NUL prefix, which no real credential account can collide with.
+ *
+ * ## Cost on the healthy path
+ *
+ * The fallback is consulted on every read (once for a value, once for a
+ * tombstone). On a machine whose keyring has never failed the fallback has
+ * written nothing, so its file does not exist and both lookups are
+ * sub-millisecond `existsSync` misses (measured 0.02-0.4 ms). Where a fallback
+ * file does exist, each lookup decrypts it — the read-through this replaced
+ * already paid one decrypt per miss.
+ *
+ * The fallback is built on the first read rather than the first failed write,
+ * which a machine with a working keyring pays once per store: ~97 ms, almost
+ * all of it the fingerprint backend's scrypt probe (measured). It is lazy and
+ * cached, so later reads are unaffected.
+ *
+ * @module
+ */
+/**
+ * Account-name prefix marking an account as deleted while the primary was
+ * unreachable.
+ *
+ * The NUL byte cannot appear in a real account name (`HW_ACCESS_KEY`,
+ * `HW_SECRET_KEY`, `HW_SECURITY_TOKEN`), so a tombstone can never be confused
+ * with a credential. Tombstones are only ever written to the fallback, never
+ * to the keyring.
+ */
+const TOMBSTONE_PREFIX = '\u0000aishell:tombstone:';
+/** The fallback key recording that `account` was deleted. */
+const tombstoneKey = (account) => TOMBSTONE_PREFIX + account;
+/** Tombstone value; never read, only tested for presence. */
+const TOMBSTONE_VALUE = '1';
+/**
+ * A {@link CredentialsStore} that delegates to a primary until the primary
+ * fails a write, then fails over — for the life of this store — to a
+ * fallback supplied by {@link FailoverStoreOptions.createFallback}.
+ *
+ * Stickiness is per instance, not per process: each plugin that consumes
+ * credentials builds its own store, so one instance failing over does not stop
+ * another from trying the primary. That is intended — the flag only exists to
+ * avoid re-hitting a primary already known to be unwritable from *this* store,
+ * and a second instance's attempt is one probe rather than a policy decision.
+ * Correctness across instances comes from the persisted record, not the flag.
+ *
+ * Constructed by {@link createCredentialsStore} around a KeyringBackend whose
+ * construction probe passed; not meant for direct use by upper layers.
+ */
+export class FailoverStore {
+    primary;
+    createFallback;
+    fallback;
+    /** Set by the first failed primary write; routes writes thereafter. */
+    failedOver = false;
+    constructor(primary, options) {
+        this.primary = primary;
+        this.createFallback = options.createFallback;
+    }
+    /** The lazily built fallback; constructed at most once per store. */
+    get fallbackStore() {
+        if (this.fallback === undefined)
+            this.fallback = this.createFallback();
+        return this.fallback;
+    }
+    /**
+     * Drop the tombstone for `account`, if any.
+     *
+     * Paired with the value purge on every path that hands authority back to the
+     * primary. Best-effort: a tombstone that outlives its purpose costs one extra
+     * fallback lookup, which must never fail a write the keyring has accepted.
+     */
+    clearTombstone(account) {
+        try {
+            this.fallbackStore.delete(tombstoneKey(account));
+        }
+        catch {
+            // Best-effort only.
+        }
+    }
+    get(account) {
+        // Fallback value first: it is authoritative for any account a failover
+        // write touched, and reading the primary first would let the keyring's
+        // out-of-date copy win the moment it unlocked.
+        const failedOverValue = this.fallbackStore.get(account);
+        if (failedOverValue !== undefined)
+            return failedOverValue;
+        if (this.fallbackStore.has(tombstoneKey(account)))
+            return undefined;
+        return this.primary.get(account);
+    }
+    has(account) {
+        if (this.fallbackStore.has(account))
+            return true;
+        if (this.fallbackStore.has(tombstoneKey(account)))
+            return false;
+        return this.primary.has(account);
+    }
+    set(account, value) {
+        if (value.length === 0)
+            throw new Error('credential value must be non-empty');
+        if (this.failedOver) {
+            // The primary has already proved it cannot be written, so the fallback
+            // is the only destination left.
+            this.fallbackStore.set(account, value);
+            this.clearTombstone(account);
+            return;
+        }
+        try {
+            this.primary.set(account, value);
+        }
+        catch (error) {
+            // The primary answered its construction probe but cannot take writes
+            // (locked collection, vanished secret service). Fail over — sticky, so
+            // the remaining accounts of this save do not each hit the same error (or
+            // the same unlock prompt) again — and put the value somewhere durable.
+            this.failedOver = true;
+            try {
+                this.fallbackStore.set(account, value);
+                this.clearTombstone(account);
+            }
+            catch (fallbackError) {
+                throw new Error('credential write failed over, but the fallback store rejected it too: '
+                    + `${String(fallbackError)} (primary error: ${String(error)})`);
+            }
+            return;
+        }
+        // The keyring took the write, so it is authoritative for this account
+        // again: drop whatever an earlier failed-over session left in the fallback
+        // — a value, which would otherwise be read in preference to this write, or
+        // a tombstone, which would hide it. Best-effort: failing this cleanup must
+        // not fail a save that already succeeded.
+        try {
+            this.fallbackStore.delete(account);
+        }
+        catch {
+            // Best-effort purge only.
+        }
+        this.clearTombstone(account);
+    }
+    delete(account) {
+        // The value goes first: it is what a read would serve, and clearing it is
+        // required regardless of what the primary does.
+        try {
+            this.fallbackStore.delete(account);
+        }
+        catch {
+            // Best-effort; the tombstone below still masks the primary's copy.
+        }
+        if (this.failedOver) {
+            // The primary cannot be written, so its copy cannot be removed now. Leave
+            // a tombstone: with no value left in the fallback to shadow it, this
+            // marker is the only record that the account is gone, and a later read
+            // would otherwise serve the very credential being cleared.
+            this.writeTombstone(account);
+            return;
+        }
+        try {
+            this.primary.delete(account);
+            this.clearTombstone(account);
+        }
+        catch {
+            // A locked collection fails deletes as well as writes ("no result found"
+            // — wording KeyringBackend's absent-entry no-op filter does not match),
+            // and the save route deletes before it writes, so this must trip the
+            // same sticky failover a failed write would. The copy we could not remove
+            // is masked rather than left readable.
+            this.failedOver = true;
+            this.writeTombstone(account);
+        }
+    }
+    /**
+     * Record the deletion, or report its failure.
+     *
+     * Unlike the best-effort cleanups above, a tombstone that cannot be written
+     * means the delete silently did not happen and the credential will read back
+     * later. That is a failed clear, so it throws rather than being swallowed.
+     */
+    writeTombstone(account) {
+        this.fallbackStore.set(tombstoneKey(account), TOMBSTONE_VALUE);
+    }
+}
+//# sourceMappingURL=failover.js.map

package/lib/types/failover.js.map

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