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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined in Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is derived from (or based upon) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Huawei Cloud AI Shell
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @huaweidevtools/aishell-dsh-credentials-store
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Credential storage abstraction for aishell DSH plugins. Upper layers call `createCredentialsStore()` and receive a `CredentialsStore` — they never learn which backend is serving. The factory probes backends in priority order and returns the first that answers.
+
+This is a **tool library**, not a DSH plugin — no `dsh.client`, no `cordis.patch.yml`, no `apply`.
+
+## Backends
+
+| Priority | Backend | Durable? | Requirement |
+|---|---|---|---|
+| 1 | `KeyringBackend` | Yes (cross-process, survives reboot) | OS keyring reachable (macOS Keychain / Linux libsecret / Windows Credential Manager) |
+| 2 | `FingerprintBackend` | Yes (same-machine, survives reboot) | `node-machine-id` can resolve a machine UUID |
+| 3 | `MemoryBackend` | No (process-scoped) | None — always available, last resort |
+
+When the OS keyring is unavailable (headless Linux without D-Bus, keychain locked, container), the factory falls back to the fingerprint backend — a machine-fingerprint-bound AES-256-GCM encrypted file at `~/.<service>/credentials.enc`. The encryption key is derived from the machine UUID via scrypt; the ciphertext is useless on a different machine. If the machine UUID is also unavailable, the factory falls back to the in-memory backend so a single DSH session still works.
+
+## Write failover
+
+The construction probe can only detect a keyring that cannot be *read*. A GNOME login keyring whose collection is locked passes the probe — reads answer `null` rather than throwing — and then rejects every write (`Secret Service: no result found`, or a system unlock prompt that blocks until dismissed). So a keyring that passes the probe is wrapped in a `FailoverStore`, which covers the write side:
+
+- The first failed `set`/`delete` fails over, **stickily**, to the fingerprint backend for the life of that store instance. Sticky because a locked collection fails every write; retrying per call would surface the same error — or the same unlock prompt — once per account a save writes. `delete` trips it too, because the save route deletes the old set before writing the new one.
+- **Which copy wins.** A locked collection reports `null` for entries that really exist, so its copy can be arbitrarily stale; once it unlocks, that copy would otherwise outrank the value saved in the meantime — resurrecting a credential the user had rotated or cleared. The two backends cannot be compared by recency, so the fallback is authoritative for any account it has an opinion about: a value there wins (it got there by a failover write, which is newer by definition), a tombstone there means deleted, and otherwise the keyring answers. A failed-over clear writes a tombstone because it has no value to shadow the keyring's copy with.
+- A successful keyring write or delete clears the fallback value *and* the tombstone, handing authority back to the keyring — a leftover tombstone would make a good keyring credential read as absent.
+- Reads before any failure fall through to the fallback after a keyring miss, so a credential stored by a previous session's failover stays visible.
+
+The record lives in the fallback backend — the encrypted file in practice — so it survives the restart the failure mode requires: the keyring is locked *now*, and the read that would resurrect the credential happens in a later session, after it has unlocked. On a machine whose keyring has never failed the fallback has written nothing, and each read pays a sub-millisecond check against an absent file.
+
+## Usage
+
+```typescript
+import { createCredentialsStore } from '@huaweidevtools/aishell-dsh-credentials-store'
+
+const store = createCredentialsStore()          // probes keyring → fingerprint → memory
+store.set('HW_ACCESS_KEY', 'LTAIxxxx')          // durable if keyring or fingerprint is up
+const ak = store.get('HW_ACCESS_KEY')           // 'LTAIxxxx'
+store.has('HW_ACCESS_KEY')                       // true
+store.delete('HW_ACCESS_KEY')
+```
+
+A custom service name isolates entries from other applications sharing the same keyring:
+
+```typescript
+const store = createCredentialsStore({ service: 'my-app' })
+```
+
+## Security properties
+
+- **No plaintext files**: nothing on disk is readable with `cat`.
+- **OS-encrypted at rest**: Keychain (AES), libsecret (DPAPI/GNOME keyring), Credential Manager (DPAPI).
+- **Machine-bound encryption (FingerprintBackend)**: AES-256-GCM with a scrypt-derived key from the machine UUID. The ciphertext is useless on a different machine; the key never touches disk.
+- **Per-operation read**: no cache; a credential removed from the keyring is immediately absent on the next `get`.
+- **Graceful degradation**: a missing keyring reads as empty, not as an error — the caller's auth flow fails the same way whether the credential is absent or the store is unreachable.
+
+## Platform support (KeyringBackend)
+
+| Platform | Backend | Requirement |
+|---|---|---|
+| macOS | Keychain | None (built in) |
+| Linux | libsecret | `gnome-keyring` or `kwallet` running, plus `libsecret-1-dev` at build time |
+| Windows | Credential Manager | None (built in) |
+
+## License
+
+Apache License 2.0. See [LICENSE](../../LICENSE).

package/lib/index.d.ts

@@ -0,0 +1,208 @@
+//#region src/backends/keyring.d.ts
+
+type KeyringEntry = {
+  getPassword: () => string | null;
+  setPassword: (value: string) => void;
+  deletePassword: () => void;
+};
+type KeyringModule = {
+  Entry: new (service: string, account: string) => KeyringEntry;
+};
+/** @internal Test hook: inject a mock keyring module (vi.mock cannot intercept createRequire). */
+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)`.
+ *
+ * Construction probes the keyring once — if the native module cannot be loaded
+ * (no prebuilt binding for this platform) or cannot reach a secret service it
+ * throws, and {@link createCredentialsStore} falls back to the next backend.
+ */
+declare class KeyringBackend implements CredentialsStore {
+  private readonly serviceName;
+  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;
+} //#endregion
+//#region src/backends/fingerprint.d.ts
+
+/**
+ * Encrypted-file {@link CredentialsStore}. Each account is one entry in a
+ * single JSON map, encrypted as one file under the resolved credentials
+ * directory (`$DSH_HOME/credentials/credentials.enc` by default).
+ *
+ * Construction probes the machine ID + crypto — if `node-machine-id` cannot
+ * resolve a UUID, construction throws and the factory falls back to
+ * {@link MemoryBackend}.
+ */
+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;
+} //#endregion
+//#region src/backends/memory.d.ts
+
+//# sourceMappingURL=fingerprint.d.ts.map
+/** Process-scoped {@link CredentialsStore}; entries vanish on exit. */
+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;
+}
+
+//#endregion
+//#region src/failover.d.ts
+//# sourceMappingURL=memory.d.ts.map
+
+/** Options for {@link FailoverStore}. */
+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.
+ */
+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;
+} //#endregion
+//#region src/index.d.ts
+
+//# sourceMappingURL=failover.d.ts.map
+/**
+ * Credential storage abstraction for aishell DSH plugins.
+ *
+ * Upper layers (aishell-llm's adapter, aishell-credentials' host half)
+ * call {@link createCredentialsStore} and get a {@link CredentialsStore} —
+ * they never learn which backend is serving. The factory probes backends in
+ * priority order (OS keyring first, process memory last) and returns the
+ * first that answers. New backends (fingerprint + encrypted file, etc.) slot
+ * into the chain without touching callers. A keyring that answers the probe
+ * but later rejects writes fails over to the next backend on first failure.
+ *
+ * This is a tool library, not a DSH plugin — no `dsh.client`, no
+ * `cordis.patch.yml`, no `apply`. DSH's own `ctx.credentials` is untouched;
+ * user-configured models and `.credentials.yaml` keep working.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store
+ */
+/** Options shared by every backend / the factory. */
+interface CredentialsStoreConfig {
+  /**
+   * Backend-scoped identity. For the OS-keyring backend this is the keyring
+   * service name; every entry is stored under `new Entry(service, account)`.
+   * Defaults to `'aishell-dsh'`.
+   */
+  readonly service?: string;
+  /**
+   * Explicit directory for the fingerprint encrypted-file backend. When set,
+   * overrides the default `$DSH_HOME/credentials` resolution. Callers rarely
+   * need this — the host's `DSH_HOME` already places credentials alongside
+   * its other data.
+   */
+  readonly credentialsDir?: string;
+}
+/**
+ * Read/write a named credential. Backends are synchronous and per-call — no
+ * cache, so a credential changed from outside is visible on the next `get`.
+ * Absent credentials read as `undefined` / `has === false`; a backend that
+ * cannot serve (e.g. no D-Bus secret service) degrades the same way rather
+ * than throwing on read.
+ */
+interface CredentialsStore {
+  /** Read one credential; `undefined` when absent or backend unavailable. */
+  get(account: string): string | undefined;
+  /** Store one credential. Rejects an empty value; throws on backend errors. */
+  set(account: string, value: string): void;
+  /** Remove one credential; absent is a no-op. Throws on backend errors. */
+  delete(account: string): void;
+  /** Whether a credential is currently stored; `false` when absent or backend unavailable. */
+  has(account: string): boolean;
+}
+/**
+ * Probe backends in priority order and return the first that answers.
+ *
+ * Priority: OS keyring (durable, cross-process) → machine-fingerprint
+ * encrypted file (durable, same-machine) → process memory (volatile,
+ * last resort). A backend that cannot initialize — no D-Bus secret service
+ * on a headless Linux box, keychain locked, etc. — is skipped, not fatal.
+ *
+ * A keyring that passes the construction probe but is later found unwritable
+ * (GNOME login keyring locked: reads come back null, writes fail — the probe
+ * cannot see this) is wrapped in a {@link FailoverStore}: its first failed
+ * write fails the whole process over to the fingerprint backend, so saving
+ * credentials works instead of erroring. The wrapper also records which
+ * accounts the keyring must not answer for, so a credential saved while the
+ * collection was locked is not shadowed by the keyring's stale copy once it
+ * unlocks.
+ *
+ * @param config - optional service name override.
+ * @returns the highest-priority backend that could initialize.
+ */
+declare function createCredentialsStore(config?: CredentialsStoreConfig): CredentialsStore;
+
+//#endregion
+export { CredentialsStore, CredentialsStoreConfig, FailoverStore, FingerprintBackend, KeyringBackend, MemoryBackend, __setKeyringModule, createCredentialsStore };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/backends/keyring.ts","../../src/backends/fingerprint.ts","../../src/backends/memory.ts","../../src/failover.ts","../../src/index.ts"],"sourcesContent":null,"mappings":";;AA+CA,KA1BK,YAAA,GA0BQ;EAAe,WAAA,EAAA,GAAA,GAAA,MAAA,GAAA,IAAA;EAAA,WAIN,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,GAAA,IAAA;EAA2B,cAJV,EAAA,GAAA,GAAA,IAAA;AAAgB,CAAA;KArBlD,aAAA;mDAAmE;;;iBAIxD,kBAAA,OAAyB;;;;;;;;AC2DzC;AAAgC,cD1CnB,cAAA,YAA0B,gBC0CP,CAAA;EAAA,iBAIV,WAAA;EAA2B,iBAJN,KAAA;EAAgB,WAAA,CAAA,MAAA,CAAA,EDtCrC,sBCsCqC;;;;;AC1E3D,CAAA;;;;;AFgCuD;;;;;;;cC0C1C,kBAAA,YAA8B;;;uBAIrB;;;AAJtB;;;;EAA2D,QAAA,IAAA;;;;;EC1E9C,MAAA,CAAA,OAAA,EAAc,MAAA,CAAA,EAAA,IAAA;EAAA,GAAA,CAAA,OAAA,EAAA,MAAA,CAAA,EAAA,OAAA;CAAA;;;;;AFgCd,cEhCA,aAAA,YAAyB,gBFgCV,CAAA;EAAA,iBAAA,OAAA;EAAA,WAIN,CAAA,OAAA,CAAA,EEjCC,sBFiCD;EAA2B,GAJV,CAAA,OAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAgB,GAAA,CAAA,OAAA,EAAA,MAAA,EAAA,KAAA,EAAA,MAAA,CAAA,EAAA,IAAA;;;;;;;;;;UGqDtC,oBAAA;;;;;;;iCAOgB;;;ACnFjC;;;;;;;;AAuBA;;;;;;cD8Ea,aAAA,YAAyB;;;;;;uBAOf,2BAA2B;;;;;;;;;ACtDlD;EAAsC,QAAA,cAAA;EAAA,GAAS,CAAA,OAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAA2B,GAAG,CAAA,OAAA,EAAA,MAAA,CAAA,EAAA,OAAA;EAAgB,GAAA,CAAA,OAAA,EAAA,MAAA,EAAA,KAAA,EAAA,MAAA,CAAA,EAAA,IAAA;;;;;;;;;;;;;;;AJhElB;AAO1D;;AASjB;;;;;;;;;AAiBA;;;;AAAuD;UIvBtC,sBAAA;;;;;;;;;;;;AHiEjB;EAAgC,SAAA,cAAA,CAAA,EAAA,MAAA;;;AAA2B;;;;;AC1E3D;AAA2B,UEgCV,gBAAA,CFhCU;EAAA;EAGuB,GAHZ,CAAA,OAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAgB;;;;;ECqFrC,GAAA,CAAA,OAAA,EAAA,MAAA,CAAA,EAAA,OAAoB;;;;;;;;;;;;;;;;AAyBrC;;;;;AAAsD;iBC/CtC,sBAAA,UAA+B,yBAA8B"}

package/lib/index.js

@@ -0,0 +1,357 @@
+import { createRequire } from "node:module";
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import machineIdModule from "node-machine-id";
+
+//#region src/backends/keyring.ts
+const require = createRequire(import.meta.url);
+let keyringModule;
+/** @internal Test hook: inject a mock keyring module (vi.mock cannot intercept createRequire). */
+function __setKeyringModule(mock) {
+	keyringModule = mock;
+}
+function loadKeyring() {
+	if (keyringModule === void 0) 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)`.
+*
+* Construction probes the keyring once — if the native module cannot be loaded
+* (no prebuilt binding for this platform) or cannot reach a secret service it
+* throws, and {@link createCredentialsStore} falls back to the next backend.
+*/
+var KeyringBackend = class {
+	constructor(config = {}) {
+		this.serviceName = config.service ?? "aishell-dsh";
+		this.Entry = loadKeyring().Entry;
+		new this.Entry(this.serviceName, "__probe__").getPassword();
+	}
+	get(account) {
+		try {
+			const value = new this.Entry(this.serviceName, account).getPassword();
+			return value ?? void 0;
+		} catch {
+			return void 0;
+		}
+	}
+	set(account, value) {
+		if (value.length === 0) throw new Error("credential value must be non-empty");
+		new this.Entry(this.serviceName, account).setPassword(value);
+	}
+	delete(account) {
+		try {
+			new this.Entry(this.serviceName, account).deletePassword();
+		} catch (error) {
+			if (!String(error).includes("not found") && !String(error).includes("no entry")) throw error;
+		}
+	}
+	has(account) {
+		try {
+			return new this.Entry(this.serviceName, account).getPassword() !== null;
+		} catch {
+			return false;
+		}
+	}
+};
+
+//#endregion
+//#region src/backends/fingerprint.ts
+const machineIdSync = machineIdModule.machineIdSync;
+const SALT = "aishell-dsh/credentials/v1";
+const KEY_LEN = 32;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+/** 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.
+*
+* Priority: an explicit `config.credentialsDir` override → the host's
+* `DSH_HOME` (so credentials live alongside the rest of that host's data —
+* `~/.aishell/credentials` for the desktop app, `~/.dsh/credentials` for the
+* dsh CLI) → a standalone `~/.aishell-dsh` fallback for headless / library
+* use where no DSH host is involved.
+*
+* The `service` config still names the keyring service (and the fallback
+* directory name when neither `credentialsDir` nor `DSH_HOME` is set).
+*/
+function resolveCredentialsDir(config) {
+	if (config.credentialsDir !== void 0) return config.credentialsDir;
+	const dshHome = process.env.DSH_HOME;
+	if (dshHome !== void 0 && dshHome.trim() !== "") return join(dshHome, "credentials");
+	const dirName = config.service ?? "aishell-dsh";
+	return join(homedir(), `.${dirName}`);
+}
+/**
+* Encrypted-file {@link CredentialsStore}. Each account is one entry in a
+* single JSON map, encrypted as one file under the resolved credentials
+* directory (`$DSH_HOME/credentials/credentials.enc` by default).
+*
+* Construction probes the machine ID + crypto — if `node-machine-id` cannot
+* resolve a UUID, construction throws and the factory falls back to
+* {@link MemoryBackend}.
+*/
+var FingerprintBackend = class {
+	constructor(config = {}) {
+		this.fileDir = resolveCredentialsDir(config);
+		this.filePath = join(this.fileDir, "credentials.enc");
+		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 {
+			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: 448
+		});
+		writeFileSync(this.filePath, fingerprintEncrypt(plaintext), { mode: 384 });
+	}
+	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);
+	}
+};
+
+//#endregion
+//#region src/backends/memory.ts
+/** Process-scoped {@link CredentialsStore}; entries vanish on exit. */
+var MemoryBackend = class {
+	constructor(_config = {}) {
+		this.entries = new Map();
+	}
+	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);
+	}
+};
+
+//#endregion
+//#region src/failover.ts
+/**
+* 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 = "\0aishell: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.
+*/
+var FailoverStore = class {
+	constructor(primary, options) {
+		this.failedOver = false;
+		this.primary = primary;
+		this.createFallback = options.createFallback;
+	}
+	/** The lazily built fallback; constructed at most once per store. */
+	get fallbackStore() {
+		if (this.fallback === void 0) 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 {}
+	}
+	get(account) {
+		const failedOverValue = this.fallbackStore.get(account);
+		if (failedOverValue !== void 0) return failedOverValue;
+		if (this.fallbackStore.has(tombstoneKey(account))) return void 0;
+		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) {
+			this.fallbackStore.set(account, value);
+			this.clearTombstone(account);
+			return;
+		}
+		try {
+			this.primary.set(account, value);
+		} catch (error) {
+			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;
+		}
+		try {
+			this.fallbackStore.delete(account);
+		} catch {}
+		this.clearTombstone(account);
+	}
+	delete(account) {
+		try {
+			this.fallbackStore.delete(account);
+		} catch {}
+		if (this.failedOver) {
+			this.writeTombstone(account);
+			return;
+		}
+		try {
+			this.primary.delete(account);
+			this.clearTombstone(account);
+		} catch {
+			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);
+	}
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* Probe backends in priority order and return the first that answers.
+*
+* Priority: OS keyring (durable, cross-process) → machine-fingerprint
+* encrypted file (durable, same-machine) → process memory (volatile,
+* last resort). A backend that cannot initialize — no D-Bus secret service
+* on a headless Linux box, keychain locked, etc. — is skipped, not fatal.
+*
+* A keyring that passes the construction probe but is later found unwritable
+* (GNOME login keyring locked: reads come back null, writes fail — the probe
+* cannot see this) is wrapped in a {@link FailoverStore}: its first failed
+* write fails the whole process over to the fingerprint backend, so saving
+* credentials works instead of erroring. The wrapper also records which
+* accounts the keyring must not answer for, so a credential saved while the
+* collection was locked is not shadowed by the keyring's stale copy once it
+* unlocks.
+*
+* @param config - optional service name override.
+* @returns the highest-priority backend that could initialize.
+*/
+function createCredentialsStore(config = {}) {
+	const keyring = (() => {
+		try {
+			return new KeyringBackend(config);
+		} catch {
+			return void 0;
+		}
+	})();
+	if (keyring !== void 0) return new FailoverStore(keyring, { createFallback: () => createFallbackStore(config) });
+	return createFallbackStore(config);
+}
+/** Probe the durable-file and memory backends behind the keyring. */
+function createFallbackStore(config) {
+	try {
+		return new FingerprintBackend(config);
+	} catch {}
+	return new MemoryBackend(config);
+}
+
+//#endregion
+export { FailoverStore, FingerprintBackend, KeyringBackend, MemoryBackend, __setKeyringModule, createCredentialsStore };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["keyringModule: KeyringModule | undefined","mock: KeyringModule | undefined","config: CredentialsStoreConfig","account: string","value: string","error: unknown","machineIdSync: () => string","plaintext: string","data: Buffer","config: CredentialsStoreConfig","entries: Map<string, string>","account: string","value: string","_config: CredentialsStoreConfig","account: string","value: string","account: string","primary: CredentialsStore","options: FailoverStoreOptions","value: string","error: unknown","fallbackError: unknown","config: CredentialsStoreConfig","keyring: CredentialsStore | undefined"],"sources":["../src/backends/keyring.ts","../src/backends/fingerprint.ts","../src/backends/memory.ts","../src/failover.ts","../src/index.ts"],"sourcesContent":["/**\n * OS-keyring backend — the durable, cross-process credential store.\n *\n * Wraps `@napi-rs/keyring` (macOS Keychain / Linux libsecret / Windows\n * Credential Manager). Values persist across process restarts and reboots\n * because the OS owns the store.\n *\n * Native keyring errors (e.g. no D-Bus secret service running on Linux) are\n * caught: `get`/`has` return `undefined`/`false` so callers degrade\n * gracefully; `set`/`delete` throw a descriptive error so the caller knows\n * the store is unavailable.\n */\n\nimport { createRequire } from 'node:module'\nimport type { CredentialsStore, CredentialsStoreConfig } from '../index.ts'\n\n// Lazily resolved so a missing native binding (the known @napi-rs optional-deps\n// bug, or a platform with no prebuilt binary) throws inside the constructor\n// probe — where createCredentialsStore's try/catch catches it and falls back\n// to FingerprintBackend — instead of crashing at module-load time.\nconst require = createRequire(import.meta.url)\ntype KeyringEntry = {\n  getPassword: () => string | null\n  setPassword: (value: string) => void\n  deletePassword: () => void\n}\ntype KeyringModule = { Entry: new (service: string, account: string) => KeyringEntry }\nlet keyringModule: KeyringModule | undefined\n\n/** @internal Test hook: inject a mock keyring module (vi.mock cannot intercept createRequire). */\nexport function __setKeyringModule(mock: KeyringModule | undefined): void {\n  keyringModule = mock\n}\n\nfunction loadKeyring(): KeyringModule {\n  if (keyringModule === undefined) keyringModule = require('@napi-rs/keyring') as KeyringModule\n  return keyringModule\n}\n\n/**\n * OS-keyring {@link CredentialsStore}. Constructed with a shared service name;\n * every entry is stored under `new Entry(service, account)`.\n *\n * Construction probes the keyring once — if the native module cannot be loaded\n * (no prebuilt binding for this platform) or cannot reach a secret service it\n * throws, and {@link createCredentialsStore} falls back to the next backend.\n */\nexport class KeyringBackend implements CredentialsStore {\n  private readonly serviceName: string\n  private readonly Entry: new (service: string, account: string) => KeyringEntry\n\n  constructor(config: CredentialsStoreConfig = {}) {\n    this.serviceName = config.service ?? 'aishell-dsh'\n    this.Entry = loadKeyring().Entry\n    // Probe: a getPassword on a throwaway account exercises the native path.\n    // If the secret service is absent this throws (D-Bus error, etc.), which\n    // the factory catches to fall back to the fingerprint backend.\n    new this.Entry(this.serviceName, '__probe__').getPassword()\n  }\n\n  get(account: string): string | undefined {\n    try {\n      const value = new this.Entry(this.serviceName, account).getPassword()\n      return value ?? undefined\n    } catch {\n      return undefined\n    }\n  }\n\n  set(account: string, value: string): void {\n    if (value.length === 0) throw new Error('credential value must be non-empty')\n    new this.Entry(this.serviceName, account).setPassword(value)\n  }\n\n  delete(account: string): void {\n    try {\n      new this.Entry(this.serviceName, account).deletePassword()\n    } catch (error: unknown) {\n      // deletePassword on an absent entry may throw on some backends;\n      // treat that as a no-op rather than an error.\n      if (!String(error).includes('not found') && !String(error).includes('no entry')) {\n        throw error\n      }\n    }\n  }\n\n  has(account: string): boolean {\n    try {\n      return new this.Entry(this.serviceName, account).getPassword() !== null\n    } catch {\n      return false\n    }\n  }\n}\n","/**\n * Machine-fingerprint-bound encrypted file backend.\n *\n * When the OS keyring is unavailable (headless Linux, Docker, no keyring\n * daemon), credentials are encrypted with a key derived from the machine UUID\n * (node-machine-id) via scrypt, then AES-256-GCM. File format:\n * [12B nonce][16B tag][ciphertext...].\n *\n * The key never touches disk; the ciphertext is useless on a different machine.\n * Same-user-same-machine is trusted. VM cloning copies the machine UUID — a\n * known limitation, not a security hole.\n *\n * Ported from mcp-huaweicloud-ops-deploy/src/auth/fingerprint.ts.\n */\n\nimport { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto'\nimport { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'\nimport { homedir } from 'node:os'\nimport { join } from 'node:path'\nimport machineIdModule from 'node-machine-id'\nimport type { CredentialsStore, CredentialsStoreConfig } from '../index.ts'\n\nconst machineIdSync: () => string = machineIdModule.machineIdSync\n\nconst SALT = 'aishell-dsh/credentials/v1'\nconst KEY_LEN = 32 // AES-256\nconst NONCE_LEN = 12 // GCM standard (96-bit nonce)\nconst TAG_LEN = 16 // 128-bit auth tag\n\n/** Derive a 32-byte key from the machine UUID via scrypt. */\nfunction deriveKey(): Buffer {\n  const machineId = machineIdSync()\n  return scryptSync(machineId, SALT, KEY_LEN)\n}\n\n/** Encrypt plaintext → [nonce][tag][ciphertext] as a Buffer. */\nfunction fingerprintEncrypt(plaintext: string): Buffer {\n  const key = deriveKey()\n  const nonce = randomBytes(NONCE_LEN)\n  const cipher = createCipheriv('aes-256-gcm', key, nonce)\n  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])\n  const tag = cipher.getAuthTag()\n  return Buffer.concat([nonce, tag, ciphertext])\n}\n\n/** Decrypt [nonce][tag][ciphertext] → plaintext. Throws on tamper/wrong machine. */\nfunction fingerprintDecrypt(data: Buffer): string {\n  if (data.length < NONCE_LEN + TAG_LEN) {\n    throw new Error('credentials file corrupted (too short)')\n  }\n  const key = deriveKey()\n  const nonce = data.subarray(0, NONCE_LEN)\n  const tag = data.subarray(NONCE_LEN, NONCE_LEN + TAG_LEN)\n  const ciphertext = data.subarray(NONCE_LEN + TAG_LEN)\n  const decipher = createDecipheriv('aes-256-gcm', key, nonce)\n  decipher.setAuthTag(tag)\n  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()])\n  return plaintext.toString('utf8')\n}\n\n/**\n * Resolve the directory holding the encrypted credentials file.\n *\n * Priority: an explicit `config.credentialsDir` override → the host's\n * `DSH_HOME` (so credentials live alongside the rest of that host's data —\n * `~/.aishell/credentials` for the desktop app, `~/.dsh/credentials` for the\n * dsh CLI) → a standalone `~/.aishell-dsh` fallback for headless / library\n * use where no DSH host is involved.\n *\n * The `service` config still names the keyring service (and the fallback\n * directory name when neither `credentialsDir` nor `DSH_HOME` is set).\n */\nfunction resolveCredentialsDir(config: CredentialsStoreConfig): string {\n  if (config.credentialsDir !== undefined) return config.credentialsDir\n  const dshHome = process.env.DSH_HOME\n  if (dshHome !== undefined && dshHome.trim() !== '') return join(dshHome, 'credentials')\n  const dirName = config.service ?? 'aishell-dsh'\n  return join(homedir(), `.${dirName}`)\n}\n\n/**\n * Encrypted-file {@link CredentialsStore}. Each account is one entry in a\n * single JSON map, encrypted as one file under the resolved credentials\n * directory (`$DSH_HOME/credentials/credentials.enc` by default).\n *\n * Construction probes the machine ID + crypto — if `node-machine-id` cannot\n * resolve a UUID, construction throws and the factory falls back to\n * {@link MemoryBackend}.\n */\nexport class FingerprintBackend implements CredentialsStore {\n  private readonly filePath: string\n  private readonly fileDir: string\n\n  constructor(config: CredentialsStoreConfig = {}) {\n    this.fileDir = resolveCredentialsDir(config)\n    this.filePath = join(this.fileDir, 'credentials.enc')\n    // Probe: deriveKey exercises node-machine-id. If it throws, the factory\n    // falls back to MemoryBackend.\n    deriveKey()\n  }\n\n  /**\n   * Load + decrypt the file into a fresh map. Not cached — credentials are\n   * read, used, and dropped so plaintext does not linger in memory between\n   * operations. The file I/O + scrypt decrypt per call is acceptable: this is\n   * not a hot path (once per chat request, not per token).\n   */\n  private load(): Map<string, string> {\n    if (!existsSync(this.filePath)) return new Map()\n    try {\n      const encrypted = readFileSync(this.filePath)\n      const plaintext = fingerprintDecrypt(encrypted)\n      return new Map(Object.entries(JSON.parse(plaintext) as Record<string, string>))\n    } catch {\n      // Corrupted or wrong machine — treat as empty.\n      return new Map()\n    }\n  }\n\n  /** Encrypt + write the map to disk with owner-only permissions. */\n  private persist(entries: Map<string, string>): void {\n    const plaintext = JSON.stringify(Object.fromEntries(entries))\n    mkdirSync(this.fileDir, { recursive: true, mode: 0o700 })\n    // Write owner-only (0600); on platforms that ignore the mode (Windows)\n    // the file is still encrypted, and ACLs inherit from the profile dir.\n    writeFileSync(this.filePath, fingerprintEncrypt(plaintext), { mode: 0o600 })\n  }\n\n  get(account: string): string | undefined {\n    return this.load().get(account)\n  }\n\n  set(account: string, value: string): void {\n    if (value.length === 0) throw new Error('credential value must be non-empty')\n    const entries = this.load()\n    entries.set(account, value)\n    this.persist(entries)\n  }\n\n  delete(account: string): void {\n    const entries = this.load()\n    if (entries.delete(account)) {\n      this.persist(entries)\n    }\n  }\n\n  has(account: string): boolean {\n    return this.load().has(account)\n  }\n}\n","/**\n * In-memory backend — the volatile last-resort credential store.\n *\n * Used when the OS keyring is unavailable (no secret service, keychain\n * locked, headless box without D-Bus). Entries live in a process-scoped\n * `Map` and are lost when the process exits — durable enough for a single\n * DSH session, not for persistence.\n *\n * Callers never select this directly; {@link createCredentialsStore} falls\n * back to it when {@link KeyringBackend} cannot initialize.\n */\n\nimport type { CredentialsStore, CredentialsStoreConfig } from '../index.ts'\n\n/** Process-scoped {@link CredentialsStore}; entries vanish on exit. */\nexport class MemoryBackend implements CredentialsStore {\n  private readonly entries = new Map<string, string>()\n\n  constructor(_config: CredentialsStoreConfig = {}) {\n    // Service name is accepted for API symmetry with KeyringBackend but not\n    // used: the in-process Map is keyed by account alone, and the factory\n    // guarantees only one MemoryBackend is live per credential concern.\n  }\n\n  get(account: string): string | undefined {\n    return this.entries.get(account)\n  }\n\n  set(account: string, value: string): void {\n    if (value.length === 0) throw new Error('credential value must be non-empty')\n    this.entries.set(account, value)\n  }\n\n  delete(account: string): void {\n    this.entries.delete(account)\n  }\n\n  has(account: string): boolean {\n    return this.entries.has(account)\n  }\n}\n","/**\n * Write-failover wrapper — covers the failure class the construction-time\n * probe chain cannot see.\n *\n * {@link createCredentialsStore} picks a backend by probing at construction\n * time, but the highest-priority backend (the OS keyring) can pass that probe\n * and still reject every real write: a locked GNOME keyring collection reads\n * as `null` (the probe's getPassword does not throw) while setPassword fails.\n * Measured on an isolated D-Bus session:\n *\n * - locked collection, no default alias — read 5 ms → null; write 5 ms →\n *   \"Couldn't access platform storage: Secret Service: no result found\"\n * - locked collection, default alias set (the real-desktop shape) — read\n *   still null; write blocks on the system unlock prompter and rejects with\n *   \"Secret Service: unlock prompt was dismissed\" when canceled\n *\n * So the write path needs its own fallback chain, and it must be sticky: a\n * locked keyring fails every write, so retrying it per call would surface the\n * same error (or the same prompt) once per account a save writes. Deletes trip\n * the same failover: a locked collection rejects them with the same error, and\n * the save route (delete old set → write new set) deletes first — without\n * this, a locked keyring would fail the save before the write failover ever\n * engages.\n *\n * ## Which copy wins\n *\n * A locked collection answers `null` for entries that are really there, so the\n * primary's copy of an account can be arbitrarily out of date while still\n * reading as authoritative. Once it unlocks, that copy would outrank the value\n * the user saved in the meantime — resurrecting a credential the user rotated\n * or cleared, with every later signature using the superseded key.\n *\n * The two backends cannot be compared by recency (neither records one), so the\n * fallback is treated as authoritative for any account it has an opinion\n * about, and the primary answers only when the fallback has none:\n *\n *   - **A value in the fallback wins.** It is there because a failover write\n *     put it there, and that write is by definition newer than whatever the\n *     primary holds. No bookkeeping is needed — the value shadows the primary\n *     simply by existing.\n *   - **A tombstone means deleted.** A clear whose primary delete failed has\n *     nothing to shadow with, so it writes an explicit marker; without one, the\n *     stale primary copy would read back as present.\n *   - **Otherwise the primary answers**, which is the ordinary healthy path.\n *\n * A successful primary write or delete clears both the fallback value and the\n * tombstone, handing authority back to the keyring.\n *\n * Recording deletion this way — rather than marking accounts \"stale\" on every\n * failover write — keeps the value and its shadow in one place. A mark set by a\n * write would have to be cleared in lockstep with the value, and a mark left\n * behind after its value was gone would make a perfect keyring credential read\n * as *absent* rather than merely stale.\n *\n * ## Why the record is persisted, not held in memory\n *\n * The state it describes outlives the store: the failure is \"the keyring is\n * locked now\", and the read that would resurrect the credential happens in a\n * later session, after it has unlocked. It is therefore stored in the fallback\n * backend itself — the encrypted file in practice, and merely the process in\n * the memory-backed last resort, where the failover is no more durable either.\n * Keys carry a NUL prefix, which no real credential account can collide with.\n *\n * ## Cost on the healthy path\n *\n * The fallback is consulted on every read (once for a value, once for a\n * tombstone). On a machine whose keyring has never failed the fallback has\n * written nothing, so its file does not exist and both lookups are\n * sub-millisecond `existsSync` misses (measured 0.02-0.4 ms). Where a fallback\n * file does exist, each lookup decrypts it — the read-through this replaced\n * already paid one decrypt per miss.\n *\n * The fallback is built on the first read rather than the first failed write,\n * which a machine with a working keyring pays once per store: ~97 ms, almost\n * all of it the fingerprint backend's scrypt probe (measured). It is lazy and\n * cached, so later reads are unaffected.\n *\n * @module\n */\n\nimport type { CredentialsStore } from './index.ts'\n\n/**\n * Account-name prefix marking an account as deleted while the primary was\n * unreachable.\n *\n * The NUL byte cannot appear in a real account name (`HW_ACCESS_KEY`,\n * `HW_SECRET_KEY`, `HW_SECURITY_TOKEN`), so a tombstone can never be confused\n * with a credential. Tombstones are only ever written to the fallback, never\n * to the keyring.\n */\nconst TOMBSTONE_PREFIX = '\\u0000aishell:tombstone:'\n\n/** The fallback key recording that `account` was deleted. */\nconst tombstoneKey = (account: string): string => TOMBSTONE_PREFIX + account\n\n/** Tombstone value; never read, only tested for presence. */\nconst TOMBSTONE_VALUE = '1'\n\n/** Options for {@link FailoverStore}. */\nexport interface FailoverStoreOptions {\n  /**\n   * Builds the store that takes over when the primary fails a write. Called\n   * at most once, lazily, on first need — a read miss or the first failed\n   * write — so a healthy keyring never pays for constructing it. Must not\n   * throw: the factory's closure ends in MemoryBackend.\n   */\n  readonly createFallback: () => CredentialsStore\n}\n\n/**\n * A {@link CredentialsStore} that delegates to a primary until the primary\n * fails a write, then fails over — for the life of this store — to a\n * fallback supplied by {@link FailoverStoreOptions.createFallback}.\n *\n * Stickiness is per instance, not per process: each plugin that consumes\n * credentials builds its own store, so one instance failing over does not stop\n * another from trying the primary. That is intended — the flag only exists to\n * avoid re-hitting a primary already known to be unwritable from *this* store,\n * and a second instance's attempt is one probe rather than a policy decision.\n * Correctness across instances comes from the persisted record, not the flag.\n *\n * Constructed by {@link createCredentialsStore} around a KeyringBackend whose\n * construction probe passed; not meant for direct use by upper layers.\n */\nexport class FailoverStore implements CredentialsStore {\n  private readonly primary: CredentialsStore\n  private readonly createFallback: () => CredentialsStore\n  private fallback: CredentialsStore | undefined\n  /** Set by the first failed primary write; routes writes thereafter. */\n  private failedOver = false\n\n  constructor(primary: CredentialsStore, options: FailoverStoreOptions) {\n    this.primary = primary\n    this.createFallback = options.createFallback\n  }\n\n  /** The lazily built fallback; constructed at most once per store. */\n  private get fallbackStore(): CredentialsStore {\n    if (this.fallback === undefined) this.fallback = this.createFallback()\n    return this.fallback\n  }\n\n  /**\n   * Drop the tombstone for `account`, if any.\n   *\n   * Paired with the value purge on every path that hands authority back to the\n   * primary. Best-effort: a tombstone that outlives its purpose costs one extra\n   * fallback lookup, which must never fail a write the keyring has accepted.\n   */\n  private clearTombstone(account: string): void {\n    try {\n      this.fallbackStore.delete(tombstoneKey(account))\n    } catch {\n      // Best-effort only.\n    }\n  }\n\n  get(account: string): string | undefined {\n    // Fallback value first: it is authoritative for any account a failover\n    // write touched, and reading the primary first would let the keyring's\n    // out-of-date copy win the moment it unlocked.\n    const failedOverValue = this.fallbackStore.get(account)\n    if (failedOverValue !== undefined) return failedOverValue\n    if (this.fallbackStore.has(tombstoneKey(account))) return undefined\n    return this.primary.get(account)\n  }\n\n  has(account: string): boolean {\n    if (this.fallbackStore.has(account)) return true\n    if (this.fallbackStore.has(tombstoneKey(account))) return false\n    return this.primary.has(account)\n  }\n\n  set(account: string, value: string): void {\n    if (value.length === 0) throw new Error('credential value must be non-empty')\n    if (this.failedOver) {\n      // The primary has already proved it cannot be written, so the fallback\n      // is the only destination left.\n      this.fallbackStore.set(account, value)\n      this.clearTombstone(account)\n      return\n    }\n    try {\n      this.primary.set(account, value)\n    } catch (error: unknown) {\n      // The primary answered its construction probe but cannot take writes\n      // (locked collection, vanished secret service). Fail over — sticky, so\n      // the remaining accounts of this save do not each hit the same error (or\n      // the same unlock prompt) again — and put the value somewhere durable.\n      this.failedOver = true\n      try {\n        this.fallbackStore.set(account, value)\n        this.clearTombstone(account)\n      } catch (fallbackError: unknown) {\n        throw new Error(\n          'credential write failed over, but the fallback store rejected it too: '\n          + `${String(fallbackError)} (primary error: ${String(error)})`,\n        )\n      }\n      return\n    }\n    // The keyring took the write, so it is authoritative for this account\n    // again: drop whatever an earlier failed-over session left in the fallback\n    // — a value, which would otherwise be read in preference to this write, or\n    // a tombstone, which would hide it. Best-effort: failing this cleanup must\n    // not fail a save that already succeeded.\n    try {\n      this.fallbackStore.delete(account)\n    } catch {\n      // Best-effort purge only.\n    }\n    this.clearTombstone(account)\n  }\n\n  delete(account: string): void {\n    // The value goes first: it is what a read would serve, and clearing it is\n    // required regardless of what the primary does.\n    try {\n      this.fallbackStore.delete(account)\n    } catch {\n      // Best-effort; the tombstone below still masks the primary's copy.\n    }\n    if (this.failedOver) {\n      // The primary cannot be written, so its copy cannot be removed now. Leave\n      // a tombstone: with no value left in the fallback to shadow it, this\n      // marker is the only record that the account is gone, and a later read\n      // would otherwise serve the very credential being cleared.\n      this.writeTombstone(account)\n      return\n    }\n    try {\n      this.primary.delete(account)\n      this.clearTombstone(account)\n    } catch {\n      // A locked collection fails deletes as well as writes (\"no result found\"\n      // — wording KeyringBackend's absent-entry no-op filter does not match),\n      // and the save route deletes before it writes, so this must trip the\n      // same sticky failover a failed write would. The copy we could not remove\n      // is masked rather than left readable.\n      this.failedOver = true\n      this.writeTombstone(account)\n    }\n  }\n\n  /**\n   * Record the deletion, or report its failure.\n   *\n   * Unlike the best-effort cleanups above, a tombstone that cannot be written\n   * means the delete silently did not happen and the credential will read back\n   * later. That is a failed clear, so it throws rather than being swallowed.\n   */\n  private writeTombstone(account: string): void {\n    this.fallbackStore.set(tombstoneKey(account), TOMBSTONE_VALUE)\n  }\n}\n","/**\n * Credential storage abstraction for aishell DSH plugins.\n *\n * Upper layers (aishell-llm's adapter, aishell-credentials' host half)\n * call {@link createCredentialsStore} and get a {@link CredentialsStore} —\n * they never learn which backend is serving. The factory probes backends in\n * priority order (OS keyring first, process memory last) and returns the\n * first that answers. New backends (fingerprint + encrypted file, etc.) slot\n * into the chain without touching callers. A keyring that answers the probe\n * but later rejects writes fails over to the next backend on first failure.\n *\n * This is a tool library, not a DSH plugin — no `dsh.client`, no\n * `cordis.patch.yml`, no `apply`. DSH's own `ctx.credentials` is untouched;\n * user-configured models and `.credentials.yaml` keep working.\n *\n * @module @huaweidevtools/aishell-dsh-credentials-store\n */\n\nimport { KeyringBackend } from './backends/keyring.ts'\nimport { FingerprintBackend } from './backends/fingerprint.ts'\nimport { MemoryBackend } from './backends/memory.ts'\nimport { FailoverStore } from './failover.ts'\n\n/** Options shared by every backend / the factory. */\nexport interface CredentialsStoreConfig {\n  /**\n   * Backend-scoped identity. For the OS-keyring backend this is the keyring\n   * service name; every entry is stored under `new Entry(service, account)`.\n   * Defaults to `'aishell-dsh'`.\n   */\n  readonly service?: string\n  /**\n   * Explicit directory for the fingerprint encrypted-file backend. When set,\n   * overrides the default `$DSH_HOME/credentials` resolution. Callers rarely\n   * need this — the host's `DSH_HOME` already places credentials alongside\n   * its other data.\n   */\n  readonly credentialsDir?: string\n}\n\n/**\n * Read/write a named credential. Backends are synchronous and per-call — no\n * cache, so a credential changed from outside is visible on the next `get`.\n * Absent credentials read as `undefined` / `has === false`; a backend that\n * cannot serve (e.g. no D-Bus secret service) degrades the same way rather\n * than throwing on read.\n */\nexport interface CredentialsStore {\n  /** Read one credential; `undefined` when absent or backend unavailable. */\n  get(account: string): string | undefined\n  /** Store one credential. Rejects an empty value; throws on backend errors. */\n  set(account: string, value: string): void\n  /** Remove one credential; absent is a no-op. Throws on backend errors. */\n  delete(account: string): void\n  /** Whether a credential is currently stored; `false` when absent or backend unavailable. */\n  has(account: string): boolean\n}\n\n/**\n * Probe backends in priority order and return the first that answers.\n *\n * Priority: OS keyring (durable, cross-process) → machine-fingerprint\n * encrypted file (durable, same-machine) → process memory (volatile,\n * last resort). A backend that cannot initialize — no D-Bus secret service\n * on a headless Linux box, keychain locked, etc. — is skipped, not fatal.\n *\n * A keyring that passes the construction probe but is later found unwritable\n * (GNOME login keyring locked: reads come back null, writes fail — the probe\n * cannot see this) is wrapped in a {@link FailoverStore}: its first failed\n * write fails the whole process over to the fingerprint backend, so saving\n * credentials works instead of erroring. The wrapper also records which\n * accounts the keyring must not answer for, so a credential saved while the\n * collection was locked is not shadowed by the keyring's stale copy once it\n * unlocks.\n *\n * @param config - optional service name override.\n * @returns the highest-priority backend that could initialize.\n */\nexport function createCredentialsStore(config: CredentialsStoreConfig = {}): CredentialsStore {\n  const keyring: CredentialsStore | undefined = (() => {\n    try {\n      return new KeyringBackend(config)\n    } catch {\n      // OS keyring unavailable — try the fingerprint file backend.\n      return undefined\n    }\n  })()\n  if (keyring !== undefined) {\n    // FingerprintBackend construction probes machine-id (deriveKey); if that\n    // fails, MemoryBackend closes the chain — createFallback never throws.\n    return new FailoverStore(keyring, { createFallback: () => createFallbackStore(config) })\n  }\n  return createFallbackStore(config)\n}\n\n/** Probe the durable-file and memory backends behind the keyring. */\nfunction createFallbackStore(config: CredentialsStoreConfig): CredentialsStore {\n  try {\n    return new FingerprintBackend(config)\n  } catch {\n    // Machine fingerprint unavailable (no machine ID) — fall back to memory.\n  }\n  return new MemoryBackend(config)\n}\n\nexport { KeyringBackend, __setKeyringModule } from './backends/keyring.ts'\nexport { FingerprintBackend } from './backends/fingerprint.ts'\nexport { MemoryBackend } from './backends/memory.ts'\nexport { FailoverStore } from './failover.ts'\n"],"mappings":"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"}

package/lib/signer.d.ts

@@ -0,0 +1,40 @@
+//#region src/signer.d.ts
+/**
+ * Huawei Cloud SDK-HMAC-SHA256 request signing.
+ *
+ * Signs an HTTP request with AK/SK (and an optional temporary SecurityToken)
+ * using the same algorithm as the official Huawei Cloud SDK. Produces the
+ * `Authorization`, `x-sdk-date`, and `x-security-token` headers to attach
+ * to a `fetch` call.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store/signer
+ */
+/** Credentials for signing. */
+interface SignCredentials {
+  readonly ak: string;
+  readonly sk: string;
+  readonly securityToken?: string;
+}
+/** The headers produced by {@link sign}. */
+interface SignedHeaders {
+  readonly host: string;
+  readonly 'x-sdk-date': string;
+  readonly Authorization: string;
+  readonly 'x-security-token'?: string;
+}
+/**
+ * Sign an HTTP request with SDK-HMAC-SHA256.
+ *
+ * @param method - HTTP method (GET, POST, ...).
+ * @param host - Host component of the request URL (e.g. `api.aishell.openbuildlab.com`).
+ * @param path - Path component of the request URL (e.g. `/chat/completions`).
+ * @param query - Query parameters as a key-value map.
+ * @param body - Request body (stringified for hashing; empty string for GET).
+ * @param credentials - AK/SK and optional SecurityToken.
+ * @returns The headers to attach to the fetch call.
+ */
+declare function sign(method: string, host: string, path: string, query: Record<string, string>, body: string, credentials: SignCredentials): SignedHeaders; //#endregion
+
+//# sourceMappingURL=signer.d.ts.map
+export { SignCredentials, SignedHeaders, sign };
+//# sourceMappingURL=signer.d.ts.map

package/lib/signer.js

@@ -0,0 +1,66 @@
+import crypto from "node:crypto";
+
+//#region src/signer.ts
+function sha256Hex(data) {
+	return crypto.createHash("sha256").update(data).digest("hex");
+}
+function hmacSha256(key, data) {
+	return crypto.createHmac("sha256", key).update(data).digest("hex");
+}
+/** RFC 3986 URL-encode a string (unreserved chars stay literal). */
+function urlEncode(str) {
+	const hex = (c) => "%" + (c < 16 ? "0" : "") + c.toString(16).toUpperCase();
+	const noEscape = new Set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.~".split(""));
+	let out = "";
+	for (const ch of str) {
+		const c = ch.codePointAt(0);
+		if (c < 128) out += noEscape.has(ch) ? ch : hex(c);
+		else out += encodeURIComponent(ch);
+	}
+	return out;
+}
+/** ISO 8601 timestamp in Huawei Cloud format: `20260912T064552Z`. */
+function sdkTimestamp() {
+	return new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+/, "");
+}
+/**
+* Sign an HTTP request with SDK-HMAC-SHA256.
+*
+* @param method - HTTP method (GET, POST, ...).
+* @param host - Host component of the request URL (e.g. `api.aishell.openbuildlab.com`).
+* @param path - Path component of the request URL (e.g. `/chat/completions`).
+* @param query - Query parameters as a key-value map.
+* @param body - Request body (stringified for hashing; empty string for GET).
+* @param credentials - AK/SK and optional SecurityToken.
+* @returns The headers to attach to the fetch call.
+*/
+function sign(method, host, path, query, body, credentials) {
+	const ts = sdkTimestamp();
+	const cqs = Object.entries(query).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${urlEncode(k)}=${urlEncode(v)}`).join("&");
+	const curi = "/" + path.split("/").filter(Boolean).map(urlEncode).join("/") + "/";
+	const hasToken = credentials.securityToken !== void 0;
+	const signedHeaders = hasToken ? "host;x-sdk-date;x-security-token" : "host;x-sdk-date";
+	const canonicalHeaders = hasToken ? `host:${host}\nx-sdk-date:${ts}\nx-security-token:${credentials.securityToken}\n` : `host:${host}\nx-sdk-date:${ts}\n`;
+	const payloadHash = sha256Hex(body);
+	const canonicalRequest = [
+		method,
+		curi,
+		cqs,
+		canonicalHeaders,
+		signedHeaders,
+		payloadHash
+	].join("\n");
+	const stringToSign = `SDK-HMAC-SHA256\n${ts}\n${sha256Hex(canonicalRequest)}`;
+	const signature = hmacSha256(credentials.sk, stringToSign);
+	const headers = {
+		host,
+		"x-sdk-date": ts,
+		Authorization: `SDK-HMAC-SHA256 Access=${credentials.ak}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+		...hasToken ? { "x-security-token": credentials.securityToken } : {}
+	};
+	return headers;
+}
+
+//#endregion
+export { sign };
+//# sourceMappingURL=signer.js.map

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@huaweidevtools/aishell-dsh-credentials-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Credential storage + SDK-HMAC-SHA256 signing for aishell DSH plugins",
+  "version": "0.0.1-beta.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yusheng-g/aishell-dsh-plugins.git",
+    "directory": "packages/credentials-store"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./signer": {
+      "types": "./lib/signer.d.ts",
+      "default": "./lib/signer.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/signer.js",
+    "lib/index.d.ts",
+    "lib/signer.d.ts",
+    "lib/index.js.map",
+    "lib/index.d.ts.map"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@napi-rs/keyring": "^2.0.0",
+    "node-machine-id": "^1.1.12"
+  },
+  "scripts": {
+    "build:bundle": "tsdown"
+  }
 }