@huaweidevtools/aishell-dsh-credentials-store 0.0.1-beta.1 → 0.0.1-beta.3

package/lib/types/accounts.js

@@ -0,0 +1,384 @@
+/**
+ * The Huawei Cloud credential vocabulary every plugin in this set shares.
+ *
+ * ## Why this module exists
+ *
+ * This repo once read the same keyring entries from four places, each declaring
+ * the account names itself and re-implementing "read AK and SK as a pair". The
+ * account names are a *persistence* contract, so a divergence would not fail a
+ * build — it would surface as one plugin working and another reporting "not
+ * authenticated" on a machine where the person had stored exactly one pair, and
+ * the cause would be invisible in the diff that introduced it.
+ *
+ * Everything now goes through this file.
+ *
+ * ## One entry, not three
+ *
+ * The store holds **one** record, `aishell-credential`, whose value is a single
+ * JSON bundle encoded as base64:
+ *
+ * ```json
+ * {
+ *   "huaweicloud": { "access_key": "…", "secret_key": "…", "security_token": "…" },
+ *   "aishell_e2b": { "api_key": "…", "expired_at": "…", "ak_fingerprint": "…" }
+ * }
+ * ```
+ *
+ * The earlier layout was three separate entries (`HW_ACCESS_KEY`,
+ * `HW_SECRET_KEY`, `HW_SECURITY_TOKEN`). That had two problems this fixes:
+ *
+ *   - **A save was four operations.** Clear, then write AK, then SK, then
+ *     token. Every backend is per-entry, so a failure between them left a
+ *     half-set behind, and nothing rolled it back.
+ *   - **A read was three reads.** A concurrent write landing between them could
+ *     hand back a new AK with an old SK — a pair that passes "both present" and
+ *     then fails at the gateway with 401, pointing nowhere near the cause.
+ *
+ * One entry makes a write one atomic operation and a read one consistent
+ * snapshot.
+ *
+ * ## base64 is an encoding, not encryption
+ *
+ * It keeps the secret from sitting in a plaintext field a person or a log
+ * prints while poking at the store. It is **not** a security boundary: anyone
+ * who can read the entry can decode it. The actual protection is the backend —
+ * the OS keyring, or AES-256-GCM in the file backend.
+ *
+ * ## Read-modify-write is not atomic across processes
+ *
+ * {@link updateCredentials} reads the bundle, applies a change and writes it
+ * back. Two processes doing that concurrently can lose one of the changes. That
+ * is accepted rather than solved: the only writer is a person via the
+ * credential form, and both the e2b key and the AK/SK are refreshed by that
+ * same person. A lost update would be corrected by the next save. Solving it
+ * properly needs compare-and-swap, which the keyring API does not offer.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store/accounts
+ */
+import { createHash } from 'node:crypto';
+/**
+ * The one store entry holding every credential this repo manages.
+ *
+ * Part of the persistence contract: renaming it orphans every stored entry
+ * while looking like a harmless constant change.
+ */
+export const CREDENTIAL_ACCOUNT = 'aishell-credential';
+/**
+ * Entries written by the earlier three-key layout, in the order they are read
+ * during migration.
+ *
+ * Kept only so an existing install keeps working: see {@link readCredentials}.
+ * New writes never touch these.
+ */
+export const LEGACY_ACCOUNTS = ['HW_ACCESS_KEY', 'HW_SECRET_KEY', 'HW_SECURITY_TOKEN'];
+/**
+ * The legacy entry holding an e2b API key on its own.
+ *
+ * Folded into the bundle by {@link readCredentials}. Kept as a constant because
+ * the migration has to name it.
+ */
+export const LEGACY_E2B_ACCOUNT = 'AISHELL_E2B_API_KEY';
+/**
+ * Encode a bundle for storage.
+ *
+ * @param bundle - the bundle to store.
+ * @returns base64 of its JSON form.
+ */
+export function encodeBundle(bundle) {
+    return Buffer.from(JSON.stringify(bundle), 'utf8').toString('base64');
+}
+/**
+ * Decode a stored value.
+ *
+ * Anything unreadable reads as an empty bundle rather than throwing: a corrupt
+ * entry should behave like "nothing stored" so the person is asked to
+ * authenticate again, not so every tool call fails on a parse error.
+ *
+ * A value that is not base64 is tried as raw JSON first — that is what the
+ * legacy e2b entry held, and migration reads it through here.
+ *
+ * @param raw - the stored string, if any.
+ * @returns the decoded bundle; empty when nothing usable is there.
+ */
+export function decodeBundle(raw) {
+    if (raw === undefined || raw === '')
+        return {};
+    const text = decodeText(raw);
+    if (text === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return {};
+    const candidate = parsed;
+    return {
+        ...(isHuaweiCloudSection(candidate.huaweicloud)
+            ? { huaweicloud: candidate.huaweicloud }
+            : {}),
+        ...(isE2BSection(candidate.aishell_e2b)
+            ? { aishell_e2b: candidate.aishell_e2b }
+            : {}),
+    };
+}
+/** Decode base64, falling back to the raw string when it is already text. */
+function decodeText(raw) {
+    try {
+        const decoded = Buffer.from(raw, 'base64');
+        // `Buffer.from` never throws on bad base64 — it drops the unusable tail. So
+        // the round-trip check is what distinguishes real base64 from legacy JSON.
+        if (decoded.toString('base64') === raw.replace(/\s/g, '')) {
+            const text = decoded.toString('utf8');
+            if (text.trimStart().startsWith('{'))
+                return text;
+        }
+    }
+    catch {
+        // Fall through to raw.
+    }
+    return raw.trimStart().startsWith('{') ? raw : undefined;
+}
+/** Whether a decoded field is a usable Huawei Cloud section. */
+function isHuaweiCloudSection(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const section = value;
+    return typeof section.access_key === 'string' && section.access_key !== ''
+        && typeof section.secret_key === 'string' && section.secret_key !== ''
+        && (section.security_token === undefined || typeof section.security_token === 'string');
+}
+/** Whether a decoded field is a usable e2b section. */
+function isE2BSection(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const section = value;
+    return typeof section.api_key === 'string' && section.api_key !== ''
+        && typeof section.expired_at === 'string' && section.expired_at !== ''
+        && (section.ak_fingerprint === undefined || typeof section.ak_fingerprint === 'string');
+}
+/**
+ * Read the whole bundle, migrating a legacy layout on the way.
+ *
+ * Migration is lazy and idempotent: the first read that finds no bundle but
+ * finds legacy entries merges them into one record, writes it, and removes the
+ * old entries. A failed write leaves the legacy entries alone, so the next read
+ * tries again — the person is never left with neither layout.
+ *
+ * @param store - the caller's credential store.
+ * @returns the bundle; empty when nothing is stored.
+ */
+export function readCredentials(store) {
+    const stored = store.get(CREDENTIAL_ACCOUNT);
+    if (stored !== undefined)
+        return decodeBundle(stored);
+    const migrated = migrateLegacy(store);
+    if (migrated === undefined)
+        return {};
+    return migrated;
+}
+/**
+ * Merge the legacy entries into one record and remove the old ones.
+ *
+ * @param store - the caller's credential store.
+ * @returns the migrated bundle, or `undefined` when there was nothing to move.
+ */
+function migrateLegacy(store) {
+    const ak = store.get(LEGACY_ACCOUNTS[0]);
+    const sk = store.get(LEGACY_ACCOUNTS[1]);
+    const token = store.get(LEGACY_ACCOUNTS[2]);
+    const legacyKey = store.get(LEGACY_E2B_ACCOUNT);
+    const huaweicloud = ak !== undefined && ak !== '' && sk !== undefined && sk !== ''
+        ? {
+            access_key: ak,
+            secret_key: sk,
+            ...(token === undefined || token === '' ? {} : { security_token: token }),
+        }
+        : undefined;
+    // The legacy e2b entry held `{ key, expiresAt, akFingerprint }`. Re-keyed to
+    // the bundle's snake-case spelling; an older bare key still reads as one that
+    // never expires, which is how the reader treated it.
+    const aisleE2B = legacyE2BSection(legacyKey);
+    if (huaweicloud === undefined && aisleE2B === undefined)
+        return undefined;
+    const bundle = {
+        ...(huaweicloud === undefined ? {} : { huaweicloud }),
+        ...(aisleE2B === undefined ? {} : { aishell_e2b: aisleE2B }),
+    };
+    try {
+        store.set(CREDENTIAL_ACCOUNT, encodeBundle(bundle));
+    }
+    catch {
+        // Could not write the merged record — leave the legacy entries in place so
+        // the next read retries rather than losing the credentials.
+        return bundle;
+    }
+    for (const account of LEGACY_ACCOUNTS)
+        store.delete(account);
+    store.delete(LEGACY_E2B_ACCOUNT);
+    return bundle;
+}
+/** Read one legacy e2b entry into its bundle section. */
+function legacyE2BSection(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Not JSON at all: a bare key. Its expiry is unknown, which reads the same
+        // as "does not expire"; the gateway's 401 path covers the difference.
+        return { api_key: raw, expired_at: FOREVER_EXPIRY };
+    }
+    const candidate = parsed;
+    if (candidate === null || typeof candidate !== 'object')
+        return undefined;
+    if (typeof candidate.key !== 'string' || candidate.key === '')
+        return undefined;
+    return {
+        api_key: candidate.key,
+        expired_at: typeof candidate.expiresAt === 'string' ? candidate.expiresAt : FOREVER_EXPIRY,
+        ...(typeof candidate.akFingerprint === 'string' && candidate.akFingerprint !== ''
+            ? { ak_fingerprint: candidate.akFingerprint }
+            : {}),
+    };
+}
+/** The expiry recorded for a key that does not expire. */
+export const FOREVER_EXPIRY = '9999-12-31T23:59:59.000Z';
+/**
+ * Read the Huawei Cloud pair.
+ *
+ * AK and SK are read together and treated as one unit: half a pair reads as no
+ * credentials rather than an error, so a partially-configured machine gets
+ * "authenticate first" instead of a signing failure with no remedy. The
+ * SecurityToken is optional and is omitted entirely when absent — an empty
+ * string would sign as a third header the gateway then rejects.
+ *
+ * @param store - the caller's credential store.
+ * @returns the pair, or `undefined` when the AK/SK pair is incomplete.
+ */
+export function readStoredPair(store) {
+    const section = readCredentials(store).huaweicloud;
+    if (section === undefined)
+        return undefined;
+    return {
+        ak: section.access_key,
+        sk: section.secret_key,
+        ...(section.security_token === undefined ? {} : { securityToken: section.security_token }),
+    };
+}
+/**
+ * Whether a complete Huawei Cloud pair is stored.
+ *
+ * @param store - the caller's credential store.
+ */
+export function hasStoredPair(store) {
+    return readStoredPair(store) !== undefined;
+}
+/**
+ * Read the stored e2b key.
+ *
+ * @param store - the caller's credential store.
+ * @returns the section, or `undefined` when no key is stored.
+ */
+export function readE2BKey(store) {
+    return readCredentials(store).aishell_e2b;
+}
+/**
+ * Apply one change to the bundle and write it back.
+ *
+ * The updater receives the current bundle and returns the next one. Returning
+ * `undefined` aborts the write, which is how a caller says "nothing changed" —
+ * that matters because every write is a full re-encode, and needlessly
+ * rewriting a record while another process reads it is how a spurious
+ * "credentials changed" is produced.
+ *
+ * @param store - the caller's credential store.
+ * @param update - computes the next bundle.
+ * @returns the bundle now stored.
+ */
+export function updateCredentials(store, update) {
+    const current = readCredentials(store);
+    const next = update(current);
+    if (next === undefined)
+        return current;
+    store.set(CREDENTIAL_ACCOUNT, encodeBundle(next));
+    return next;
+}
+/**
+ * Store the Huawei Cloud pair, replacing any previous one.
+ *
+ * One write, so the pair can never be left half-replaced. A save without a
+ * token removes a previously stored one: a token belongs to the credential set
+ * that carried it, and inheriting a stale one would sign the next request with
+ * someone else's session.
+ *
+ * @param store - the caller's credential store.
+ * @param credentials - the verified pair.
+ */
+export function writeHuaweiCloud(store, credentials) {
+    updateCredentials(store, current => ({
+        ...current,
+        huaweicloud: {
+            access_key: credentials.ak,
+            secret_key: credentials.sk,
+            ...(credentials.securityToken === undefined ? {} : { security_token: credentials.securityToken }),
+        },
+    }));
+}
+/**
+ * Store an e2b key.
+ *
+ * @param store - the caller's credential store.
+ * @param key - the section to store.
+ */
+export function writeE2BKey(store, key) {
+    updateCredentials(store, current => ({ ...current, aishell_e2b: key }));
+}
+/**
+ * Remove the stored e2b key, leaving the Huawei Cloud pair alone.
+ *
+ * @param store - the caller's credential store.
+ */
+export function clearE2BKey(store) {
+    updateCredentials(store, current => {
+        if (current.aishell_e2b === undefined)
+            return undefined;
+        const { aishell_e2b: _removed, ...rest } = current;
+        return rest;
+    });
+}
+/**
+ * Remove every credential this repo writes.
+ *
+ * The whole record goes, so a clear cannot leave a token or a key behind for
+ * the next pair to inherit. Deleting an absent entry is a no-op in every
+ * backend, and the legacy entries are removed too so a half-migrated store does
+ * not come back.
+ *
+ * @param store - the caller's credential store.
+ */
+export function clearCredentials(store) {
+    store.delete(CREDENTIAL_ACCOUNT);
+    for (const account of LEGACY_ACCOUNTS)
+        store.delete(account);
+    store.delete(LEGACY_E2B_ACCOUNT);
+}
+/**
+ * A short, stable digest of an AK, for recording which identity minted a key.
+ *
+ * The AK rather than the pair: the SK can be rotated independently while the
+ * account stays the same, and the tenant the gateway derives is the account. A
+ * digest rather than the AK itself keeps the bundle from carrying a second
+ * readable copy of a credential identifier.
+ *
+ * @param ak - the access key.
+ */
+export function fingerprint(ak) {
+    return createHash('sha256').update(ak, 'utf8').digest('hex');
+}
+//# sourceMappingURL=accounts.js.map

package/lib/types/accounts.js.map

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

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

@@ -0,0 +1,41 @@
+/**
+ * Machine-fingerprint-bound encrypted file backend.
+ *
+ * When the OS keyring is unavailable (headless Linux, Docker, no keyring
+ * daemon), credentials are encrypted with a key derived from the machine UUID
+ * (node-machine-id) via scrypt, then AES-256-GCM. File format:
+ * [12B nonce][16B tag][ciphertext...].
+ *
+ * The key never touches disk; the ciphertext is useless on a different machine.
+ * Same-user-same-machine is trusted. VM cloning copies the machine UUID — a
+ * known limitation, not a security hole.
+ */
+import type { CredentialsStore, CredentialsStoreConfig } from '../index.ts';
+/**
+ * Encrypted-file {@link CredentialsStore}. Each account is one entry in a
+ * single JSON map, encrypted as one file under the resolved credentials
+ * directory, named by the build's credential scope (see `../scope.ts`).
+ *
+ * Construction probes the machine ID + crypto — if `node-machine-id` cannot
+ * resolve a UUID, construction throws and the factory falls back to
+ * {@link MemoryBackend}.
+ */
+export declare class FingerprintBackend implements CredentialsStore {
+    private readonly filePath;
+    private readonly fileDir;
+    constructor(config?: CredentialsStoreConfig);
+    /**
+     * Load + decrypt the file into a fresh map. Not cached — credentials are
+     * read, used, and dropped so plaintext does not linger in memory between
+     * operations. The file I/O + scrypt decrypt per call is acceptable: this is
+     * not a hot path (once per chat request, not per token).
+     */
+    private load;
+    /** Encrypt + write the map to disk with owner-only permissions. */
+    private persist;
+    get(account: string): string | undefined;
+    set(account: string, value: string): void;
+    delete(account: string): void;
+    has(account: string): boolean;
+}
+//# sourceMappingURL=fingerprint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../../src/backends/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AA0D3E;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,YAAW,gBAAgB;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;gBAEpB,MAAM,GAAE,sBAA2B;IAQ/C;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAYZ,mEAAmE;IACnE,OAAO,CAAC,OAAO;IAQf,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAOzC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAO7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAG9B"}

package/lib/types/backends/fingerprint.js

@@ -0,0 +1,135 @@
+/**
+ * Machine-fingerprint-bound encrypted file backend.
+ *
+ * When the OS keyring is unavailable (headless Linux, Docker, no keyring
+ * daemon), credentials are encrypted with a key derived from the machine UUID
+ * (node-machine-id) via scrypt, then AES-256-GCM. File format:
+ * [12B nonce][16B tag][ciphertext...].
+ *
+ * The key never touches disk; the ciphertext is useless on a different machine.
+ * Same-user-same-machine is trusted. VM cloning copies the machine UUID — a
+ * known limitation, not a security hole.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import machineIdModule from 'node-machine-id';
+import { CREDENTIALS_FILE_NAME } from "../scope.js";
+import { credentialsDir } from "../paths.js";
+const machineIdSync = machineIdModule.machineIdSync;
+// Deliberately NOT the keyring service name: this is the scrypt salt for
+// the encrypted file, and changing it would make every existing
+// `credentials.enc` undecryptable — the file would read as empty and the
+// credentials would look cleared. It is frozen.
+const SALT = 'aishell-dsh/credentials/v1';
+const KEY_LEN = 32; // AES-256
+const NONCE_LEN = 12; // GCM standard (96-bit nonce)
+const TAG_LEN = 16; // 128-bit auth tag
+/** Derive a 32-byte key from the machine UUID via scrypt. */
+function deriveKey() {
+    const machineId = machineIdSync();
+    return scryptSync(machineId, SALT, KEY_LEN);
+}
+/** Encrypt plaintext → [nonce][tag][ciphertext] as a Buffer. */
+function fingerprintEncrypt(plaintext) {
+    const key = deriveKey();
+    const nonce = randomBytes(NONCE_LEN);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([nonce, tag, ciphertext]);
+}
+/** Decrypt [nonce][tag][ciphertext] → plaintext. Throws on tamper/wrong machine. */
+function fingerprintDecrypt(data) {
+    if (data.length < NONCE_LEN + TAG_LEN) {
+        throw new Error('credentials file corrupted (too short)');
+    }
+    const key = deriveKey();
+    const nonce = data.subarray(0, NONCE_LEN);
+    const tag = data.subarray(NONCE_LEN, NONCE_LEN + TAG_LEN);
+    const ciphertext = data.subarray(NONCE_LEN + TAG_LEN);
+    const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAuthTag(tag);
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return plaintext.toString('utf8');
+}
+/**
+ * Resolve the directory holding the encrypted credentials file.
+ *
+ * An explicit `config.credentialsDir` wins; otherwise `<DSH_HOME>/credentials`,
+ * resolved by the shared `paths` module so the terraform cache in
+ * `aishell-deploy` cannot drift to a different home.
+ *
+ * Builds are separated by the *file name* — see `../scope.ts` — not by the
+ * directory.
+ */
+function resolveCredentialsDir(config) {
+    return config.credentialsDir ?? credentialsDir();
+}
+/**
+ * Encrypted-file {@link CredentialsStore}. Each account is one entry in a
+ * single JSON map, encrypted as one file under the resolved credentials
+ * directory, named by the build's credential scope (see `../scope.ts`).
+ *
+ * Construction probes the machine ID + crypto — if `node-machine-id` cannot
+ * resolve a UUID, construction throws and the factory falls back to
+ * {@link MemoryBackend}.
+ */
+export class FingerprintBackend {
+    filePath;
+    fileDir;
+    constructor(config = {}) {
+        this.fileDir = resolveCredentialsDir(config);
+        this.filePath = join(this.fileDir, CREDENTIALS_FILE_NAME);
+        // Probe: deriveKey exercises node-machine-id. If it throws, the factory
+        // falls back to MemoryBackend.
+        deriveKey();
+    }
+    /**
+     * Load + decrypt the file into a fresh map. Not cached — credentials are
+     * read, used, and dropped so plaintext does not linger in memory between
+     * operations. The file I/O + scrypt decrypt per call is acceptable: this is
+     * not a hot path (once per chat request, not per token).
+     */
+    load() {
+        if (!existsSync(this.filePath))
+            return new Map();
+        try {
+            const encrypted = readFileSync(this.filePath);
+            const plaintext = fingerprintDecrypt(encrypted);
+            return new Map(Object.entries(JSON.parse(plaintext)));
+        }
+        catch {
+            // Corrupted or wrong machine — treat as empty.
+            return new Map();
+        }
+    }
+    /** Encrypt + write the map to disk with owner-only permissions. */
+    persist(entries) {
+        const plaintext = JSON.stringify(Object.fromEntries(entries));
+        mkdirSync(this.fileDir, { recursive: true, mode: 0o700 });
+        // Write owner-only (0600); on platforms that ignore the mode (Windows)
+        // the file is still encrypted, and ACLs inherit from the profile dir.
+        writeFileSync(this.filePath, fingerprintEncrypt(plaintext), { mode: 0o600 });
+    }
+    get(account) {
+        return this.load().get(account);
+    }
+    set(account, value) {
+        if (value.length === 0)
+            throw new Error('credential value must be non-empty');
+        const entries = this.load();
+        entries.set(account, value);
+        this.persist(entries);
+    }
+    delete(account) {
+        const entries = this.load();
+        if (entries.delete(account)) {
+            this.persist(entries);
+        }
+    }
+    has(account) {
+        return this.load().has(account);
+    }
+}
+//# sourceMappingURL=fingerprint.js.map

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

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

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

@@ -0,0 +1,69 @@
+/**
+ * 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 type { CredentialsStore, CredentialsStoreConfig } from '../index.ts';
+type KeyringEntry = {
+    getPassword: () => string | null;
+    setPassword: (value: string) => void;
+    deletePassword: () => void;
+};
+/** Entry options bag; only the Linux store pin is used (see the module note). */
+type KeyringEntryOptions = {
+    linux?: {
+        store?: 'secret-service' | 'keyutils';
+    };
+};
+type KeyringModule = {
+    Entry: new (service: string, account: string, options?: KeyringEntryOptions) => KeyringEntry;
+};
+/** @internal Test hook: inject a mock keyring module (vi.mock cannot intercept createRequire). */
+export declare function __setKeyringModule(mock: KeyringModule | undefined): void;
+/**
+ * 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 declare class KeyringBackend implements CredentialsStore {
+    private readonly serviceName;
+    private readonly options;
+    private readonly Entry;
+    constructor(_config?: CredentialsStoreConfig);
+    get(account: string): string | undefined;
+    set(account: string, value: string): void;
+    delete(account: string): void;
+    has(account: string): boolean;
+}
+export {};
+//# sourceMappingURL=keyring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyring.d.ts","sourceRoot":"","sources":["../../../src/backends/keyring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAO3E,KAAK,YAAY,GAAG;IAClB,WAAW,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IAChC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,cAAc,EAAE,MAAM,IAAI,CAAA;CAC3B,CAAA;AACD,iFAAiF;AACjF,KAAK,mBAAmB,GAAG;IAAE,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,CAAA;AAChF,KAAK,aAAa,GAAG;IACnB,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,YAAY,CAAA;CAC7F,CAAA;AAGD,kGAAkG;AAClG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAExE;AAOD;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,gBAAgB;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;gBAElC,OAAO,GAAE,sBAA2B;IAWhD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IASxC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAY7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAO9B"}