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

package/lib/types/index.js

@@ -0,0 +1,73 @@
+/**
+ * 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
+ */
+import { KeyringBackend } from "./backends/keyring.js";
+import { FingerprintBackend } from "./backends/fingerprint.js";
+import { MemoryBackend } from "./backends/memory.js";
+import { FailoverStore } from "./failover.js";
+/**
+ * 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.
+ *
+ * @returns the highest-priority backend that could initialize.
+ */
+export function createCredentialsStore(config = {}) {
+    const keyring = (() => {
+        try {
+            return new KeyringBackend(config);
+        }
+        catch {
+            // OS keyring unavailable — try the fingerprint file backend.
+            return undefined;
+        }
+    })();
+    if (keyring !== undefined) {
+        // FingerprintBackend construction probes machine-id (deriveKey); if that
+        // fails, MemoryBackend closes the chain — createFallback never throws.
+        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 {
+        // Machine fingerprint unavailable (no machine ID) — fall back to memory.
+    }
+    return new MemoryBackend(config);
+}
+export { CREDENTIAL_SCOPE, CREDENTIALS_FILE_NAME, DEFAULT_SCOPE, KEYRING_SERVICE } from "./scope.js";
+export { KeyringBackend, __setKeyringModule } from "./backends/keyring.js";
+export { FingerprintBackend } from "./backends/fingerprint.js";
+export { MemoryBackend } from "./backends/memory.js";
+export { FailoverStore } from "./failover.js";
+//# sourceMappingURL=index.js.map

package/lib/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AA+B7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAiC,EAAE;IACxE,MAAM,OAAO,GAAiC,CAAC,GAAG,EAAE;QAClD,IAAI,CAAC;YACH,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAA;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;YAC7D,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC,CAAC,EAAE,CAAA;IACJ,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,yEAAyE;QACzE,uEAAuE;QACvE,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IAC1F,CAAC;IACD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAA;AACpC,CAAC;AAED,qEAAqE;AACrE,SAAS,mBAAmB,CAAC,MAA8B;IACzD,IAAI,CAAC;QACH,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;IACD,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;AAClC,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACpG,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}

package/lib/types/paths.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Where per-host state lives. One definition, shared.
+ *
+ * ## Why this lives in the store package
+ *
+ * `DSH_HOME` is the host's data directory, and two things in this repo derive
+ * from it: the encrypted credentials file here, and the terraform cache in
+ * `aishell-deploy`. Defining it twice would let the two drift — the same
+ * failure shape the credential-scope constant was created to end.
+ *
+ * The direction is forced by the dependency graph: `aishell-deploy` already
+ * depends on this package, so a definition here is reachable from there, while
+ * the reverse would be a cycle. This module is the lower of the two, so it is
+ * where the definition belongs.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store/paths
+ */
+/**
+ * The fallback data directory when the host sets no `DSH_HOME`.
+ *
+ * `~/.aishell` — the same directory the desktop app uses, so a library or
+ * headless run shares one location with a real install rather than inventing a
+ * second home directory.
+ */
+export declare const FALLBACK_HOME_NAME = ".aishell";
+/**
+ * The host's data directory.
+ *
+ * `DSH_HOME` when the host set it — the desktop app and the CLI both do, so
+ * this lands where the rest of that host's data lives — otherwise
+ * `~/.aishell`.
+ *
+ * Read per call, never captured: a host that sets `DSH_HOME` after this module
+ * is first imported must still be honoured.
+ *
+ * @returns the base directory; not created here.
+ */
+export declare function dshHome(): string;
+/**
+ * The directory holding the encrypted credentials file.
+ *
+ * `<DSH_HOME>/credentials`. Builds are separated by the *file name* (the
+ * credential scope — `plugins.credentials.enc` by default), not by a second
+ * directory, so two builds sit side by side here without reading each other's
+ * secrets.
+ *
+ * @returns the directory; not created here.
+ */
+export declare function credentialsDir(): string;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAIhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/lib/types/paths.js

@@ -0,0 +1,59 @@
+/**
+ * Where per-host state lives. One definition, shared.
+ *
+ * ## Why this lives in the store package
+ *
+ * `DSH_HOME` is the host's data directory, and two things in this repo derive
+ * from it: the encrypted credentials file here, and the terraform cache in
+ * `aishell-deploy`. Defining it twice would let the two drift — the same
+ * failure shape the credential-scope constant was created to end.
+ *
+ * The direction is forced by the dependency graph: `aishell-deploy` already
+ * depends on this package, so a definition here is reachable from there, while
+ * the reverse would be a cycle. This module is the lower of the two, so it is
+ * where the definition belongs.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store/paths
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * The fallback data directory when the host sets no `DSH_HOME`.
+ *
+ * `~/.aishell` — the same directory the desktop app uses, so a library or
+ * headless run shares one location with a real install rather than inventing a
+ * second home directory.
+ */
+export const FALLBACK_HOME_NAME = '.aishell';
+/**
+ * The host's data directory.
+ *
+ * `DSH_HOME` when the host set it — the desktop app and the CLI both do, so
+ * this lands where the rest of that host's data lives — otherwise
+ * `~/.aishell`.
+ *
+ * Read per call, never captured: a host that sets `DSH_HOME` after this module
+ * is first imported must still be honoured.
+ *
+ * @returns the base directory; not created here.
+ */
+export function dshHome() {
+    const configured = process.env.DSH_HOME;
+    if (configured !== undefined && configured.trim() !== '')
+        return configured;
+    return join(homedir(), FALLBACK_HOME_NAME);
+}
+/**
+ * The directory holding the encrypted credentials file.
+ *
+ * `<DSH_HOME>/credentials`. Builds are separated by the *file name* (the
+ * credential scope — `plugins.credentials.enc` by default), not by a second
+ * directory, so two builds sit side by side here without reading each other's
+ * secrets.
+ *
+ * @returns the directory; not created here.
+ */
+export function credentialsDir() {
+    return join(dshHome(), 'credentials');
+}
+//# sourceMappingURL=paths.js.map

package/lib/types/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAA;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAA;IACvC,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,UAAU,CAAA;IAC3E,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,kBAAkB,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,CAAC,CAAA;AACvC,CAAC"}

package/lib/types/scope.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Which credential namespace this build uses.
+ *
+ * ## The knob
+ *
+ * A build-time constant, not a runtime setting:
+ *
+ * ```sh
+ * AISHELL_CREDENTIAL_SCOPE=staging pnpm run build
+ * ```
+ *
+ * Default `plugins`. It decides two things, and it decides both at once —
+ * which is the point:
+ *
+ * | Used as | Default |
+ * |---|---|
+ * | keyring service name | `aishell-dsh-plugins` |
+ * | encrypted file name | `plugins.credentials.enc` |
+ *
+ * ## Why it is not a plugin config option
+ *
+ * It was one, briefly: `keyringService` sat on four plugins' `Config`. Only one
+ * of the four writes and all four read, so a deployment that set it on a reader
+ * but not the writer stored credentials in one namespace and looked for them in
+ * another — the form said "saved" while every tool said "not authenticated".
+ * A knob whose only observable effect is that failure is not worth having.
+ *
+ * A constant cannot be set on one side only. Two deployments that must not see
+ * each other's credentials (a staging profile beside a production one) differ
+ * by *building* differently, which is the honest place for a persistence
+ * boundary.
+ *
+ * ## Why there is no migration
+ *
+ * The default changed from `aishell-dsh` to `aishell-dsh-plugins` before the
+ * first release, so no install ever wrote the old namespace. Nothing reads it,
+ * and adding a migration path would mean keeping the old name alive forever for
+ * a state that never existed.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store/scope
+ */
+/**
+ * The default scope.
+ *
+ * Named for the repository, not for a feature: the credential store is shared
+ * by every plugin in this set, so it is not `llm`'s or `e2b`'s.
+ */
+export declare const DEFAULT_SCOPE = "plugins";
+/** The scope this build uses. */
+export declare const CREDENTIAL_SCOPE: string;
+/**
+ * The keyring service every entry of this build lives under.
+ *
+ * Part of the persistence contract: renaming it orphans every stored entry
+ * while looking like a harmless constant change.
+ */
+export declare const KEYRING_SERVICE: string;
+/**
+ * The encrypted file name for this build.
+ *
+ * Scoped the same way as the keyring service, so two builds on one machine
+ * cannot collide in either backend.
+ */
+export declare const CREDENTIALS_FILE_NAME: string;
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,YAAY,CAAA;AAkDtC,iCAAiC;AACjC,eAAO,MAAM,gBAAgB,QAAiB,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAoC,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAwC,CAAA"}

package/lib/types/scope.js

@@ -0,0 +1,102 @@
+/**
+ * Which credential namespace this build uses.
+ *
+ * ## The knob
+ *
+ * A build-time constant, not a runtime setting:
+ *
+ * ```sh
+ * AISHELL_CREDENTIAL_SCOPE=staging pnpm run build
+ * ```
+ *
+ * Default `plugins`. It decides two things, and it decides both at once —
+ * which is the point:
+ *
+ * | Used as | Default |
+ * |---|---|
+ * | keyring service name | `aishell-dsh-plugins` |
+ * | encrypted file name | `plugins.credentials.enc` |
+ *
+ * ## Why it is not a plugin config option
+ *
+ * It was one, briefly: `keyringService` sat on four plugins' `Config`. Only one
+ * of the four writes and all four read, so a deployment that set it on a reader
+ * but not the writer stored credentials in one namespace and looked for them in
+ * another — the form said "saved" while every tool said "not authenticated".
+ * A knob whose only observable effect is that failure is not worth having.
+ *
+ * A constant cannot be set on one side only. Two deployments that must not see
+ * each other's credentials (a staging profile beside a production one) differ
+ * by *building* differently, which is the honest place for a persistence
+ * boundary.
+ *
+ * ## Why there is no migration
+ *
+ * The default changed from `aishell-dsh` to `aishell-dsh-plugins` before the
+ * first release, so no install ever wrote the old namespace. Nothing reads it,
+ * and adding a migration path would mean keeping the old name alive forever for
+ * a state that never existed.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store/scope
+ */
+/**
+ * The default scope.
+ *
+ * Named for the repository, not for a feature: the credential store is shared
+ * by every plugin in this set, so it is not `llm`'s or `e2b`'s.
+ */
+export const DEFAULT_SCOPE = 'plugins';
+/**
+ * Accepted scope shape: a lowercase identifier.
+ *
+ * The value reaches a keyring service name and a file name, so it is validated
+ * as a strict identifier rather than merely "not obviously a path": no
+ * separators, no dots, no leading dash. Assuming a value is benign because the
+ * caller is trusted is how path traversal gets in.
+ */
+const SCOPE_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+ * Resolve the scope for this build.
+ *
+ * Fails loudly on a malformed value rather than falling back to the default:
+ * a typo would otherwise silently share the namespace with every unset build,
+ * which is exactly the confusion scoping exists to avoid.
+ *
+ * @returns the validated scope.
+ * @throws when the injected value is not a valid scope.
+ */
+function resolveScope() {
+    // `typeof` rather than a direct read: an undeclared identifier throws, and a
+    // source run legitimately has no injected value.
+    const injected = typeof __AISHELL_CREDENTIAL_SCOPE__ === 'string'
+        ? __AISHELL_CREDENTIAL_SCOPE__
+        : undefined;
+    if (injected === undefined || injected === '')
+        return DEFAULT_SCOPE;
+    const normalized = injected.trim().toLowerCase();
+    if (normalized.length === 0)
+        return DEFAULT_SCOPE;
+    if (!SCOPE_PATTERN.test(normalized)) {
+        throw new Error(`AISHELL_CREDENTIAL_SCOPE=${JSON.stringify(injected)} is not a valid credential scope: `
+            + `expected 1-64 characters of [a-z0-9_-], starting with a letter or digit `
+            + '(for example "plugins" or "staging").');
+    }
+    return normalized;
+}
+/** The scope this build uses. */
+export const CREDENTIAL_SCOPE = resolveScope();
+/**
+ * The keyring service every entry of this build lives under.
+ *
+ * Part of the persistence contract: renaming it orphans every stored entry
+ * while looking like a harmless constant change.
+ */
+export const KEYRING_SERVICE = `aishell-dsh-${CREDENTIAL_SCOPE}`;
+/**
+ * The encrypted file name for this build.
+ *
+ * Scoped the same way as the keyring service, so two builds on one machine
+ * cannot collide in either backend.
+ */
+export const CREDENTIALS_FILE_NAME = `${CREDENTIAL_SCOPE}.credentials.enc`;
+//# sourceMappingURL=scope.js.map

package/lib/types/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAA;AAWtC;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,4BAA4B,CAAA;AAElD;;;;;;;;;GASG;AACH,SAAS,YAAY;IACnB,6EAA6E;IAC7E,iDAAiD;IACjD,MAAM,QAAQ,GAAG,OAAO,4BAA4B,KAAK,QAAQ;QAC/D,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,SAAS,CAAA;IACb,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,aAAa,CAAA;IACnE,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAChD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,aAAa,CAAA;IACjD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,4BAA4B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,oCAAoC;cACtF,0EAA0E;cAC1E,uCAAuC,CAC1C,CAAA;IACH,CAAC;IACD,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,iCAAiC;AACjC,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,EAAE,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,gBAAgB,EAAE,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,gBAAgB,kBAAkB,CAAA"}

package/lib/types/signer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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. */
+export interface SignCredentials {
+    readonly ak: string;
+    readonly sk: string;
+    readonly securityToken?: string;
+}
+/** The headers produced by {@link sign}. */
+export 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. `openai.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.
+ */
+export declare function sign(method: string, host: string, path: string, query: Record<string, string>, body: string, credentials: SignCredentials): SignedHeaders;
+//# sourceMappingURL=signer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC;AAiCD;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,eAAe,GAC3B,aAAa,CAoCf"}

package/lib/types/signer.js

@@ -0,0 +1,81 @@
+/**
+ * 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
+ */
+import crypto from 'node:crypto';
+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 < 0x80) {
+            out += noEscape.has(ch) ? ch : hex(c);
+        }
+        else {
+            out += encodeURIComponent(ch);
+        }
+    }
+    return out;
+}
+/** ISO 8601 timestamp in Huawei Cloud format: `20260912T064552Z`. */
+function sdkTimestamp() {
+    // toISOString() returns "2026-09-12T06:45:52.123Z"; strip separators and
+    // milliseconds but keep the trailing Z — do NOT append another one.
+    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. `openai.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.
+ */
+export function sign(method, host, path, query, body, credentials) {
+    const ts = sdkTimestamp();
+    // Canonical query string (sorted keys)
+    const cqs = Object.entries(query)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${urlEncode(k)}=${urlEncode(v)}`)
+        .join('&');
+    // Canonical URI: path segments URL-encoded, joined with /, trailing /
+    const curi = '/' + path.split('/').filter(Boolean).map(urlEncode).join('/') + '/';
+    // Signed headers
+    const hasToken = credentials.securityToken !== undefined;
+    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`;
+    // Payload hash
+    const payloadHash = sha256Hex(body);
+    // Canonical request
+    const canonicalRequest = [method, curi, cqs, canonicalHeaders, signedHeaders, payloadHash].join('\n');
+    // String to sign
+    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;
+}
+//# sourceMappingURL=signer.js.map

package/lib/types/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAA;AAiBhC,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/D,CAAC;AAED,SAAS,UAAU,CAAC,GAAW,EAAE,IAAY;IAC3C,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACpE,CAAC;AAED,oEAAoE;AACpE,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IAC3F,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,oEAAoE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IACxG,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAE,CAAA;QAC5B,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;YACb,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QACvC,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,kBAAkB,CAAC,EAAE,CAAC,CAAA;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,qEAAqE;AACrE,SAAS,YAAY;IACnB,yEAAyE;IACzE,oEAAoE;IACpE,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;AAC3E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,IAAI,CAClB,MAAc,EACd,IAAY,EACZ,IAAY,EACZ,KAA6B,EAC7B,IAAY,EACZ,WAA4B;IAE5B,MAAM,EAAE,GAAG,YAAY,EAAE,CAAA;IAEzB,uCAAuC;IACvC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SAC9B,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;SAClD,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,sEAAsE;IACtE,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAA;IAEjF,iBAAiB;IACjB,MAAM,QAAQ,GAAG,WAAW,CAAC,aAAa,KAAK,SAAS,CAAA;IACxD,MAAM,aAAa,GAAG,QAAQ,CAAC,CAAC,CAAC,kCAAkC,CAAC,CAAC,CAAC,iBAAiB,CAAA;IACvF,MAAM,gBAAgB,GAAG,QAAQ;QAC/B,CAAC,CAAC,QAAQ,IAAI,gBAAgB,EAAE,sBAAsB,WAAW,CAAC,aAAa,IAAI;QACnF,CAAC,CAAC,QAAQ,IAAI,gBAAgB,EAAE,IAAI,CAAA;IAEtC,eAAe;IACf,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAEnC,oBAAoB;IACpB,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAErG,iBAAiB;IACjB,MAAM,YAAY,GAAG,oBAAoB,EAAE,KAAK,SAAS,CAAC,gBAAgB,CAAC,EAAE,CAAA;IAC7E,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,EAAE,EAAE,YAAY,CAAC,CAAA;IAE1D,MAAM,OAAO,GAAkB;QAC7B,IAAI;QACJ,YAAY,EAAE,EAAE;QAChB,aAAa,EAAE,0BAA0B,WAAW,CAAC,EAAE,mBAAmB,aAAa,eAAe,SAAS,EAAE;QACjH,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,WAAW,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAA;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/lib/types/verify.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Huawei Cloud IAM credential verification — one implementation, shared.
+ *
+ * ## Why it moved here
+ *
+ * Two packages verified credentials independently: `aishell-credentials`' Host
+ * route, with `GET /v3/auth/domains` (it only wanted the account name), and
+ * the copied ops tool `auth`, with `GET /v3/projects` (it also wanted the
+ * account id and the project list). Same question — "are these credentials
+ * valid?" — two endpoints, two error-message vocabularies, two chances to
+ * disagree about what a 403 means.
+ *
+ * This module is the one answer. It is storage-adjacent rather than
+ * credential-form-specific, so it lives with the store and the signer, and
+ * every caller gets the same verdict in the same shape.
+ *
+ * ## Why `/v3/projects` is the endpoint
+ *
+ * It is a superset of the domains call:
+ *
+ *   - A 200 proves the AK/SK (and STS token) work, signed exactly the way every
+ *     other call is.
+ *   - Each project carries `domain_id`, which **is** the account id (Huawei
+ *     Cloud's "domain" and "account" are the same object).
+ *   - Each project's `name` is a region name, so a caller that needs a
+ *     `project_id` for a region-scoped API has it without a second request.
+ *
+ * The account *name* is the one thing projects does not carry, so it is read
+ * from `/v3/auth/domains` **best-effort** — some AK/SK scopes do not grant it,
+ * and a missing name is diagnostic-only. A failure there never fails
+ * verification.
+ *
+ * ## Region semantics, which surprise people
+ *
+ * IAM is a global service. The region in the URL only routes to a regional
+ * replica; it does not scope the result. So a wrong region still answers 200
+ * with the same account, and the real mismatch surfaces at the first
+ * region-scoped call. Verification therefore validates the credentials and
+ * **not** the region — conflating them would report "invalid credentials" for
+ * a typo'd region, sending the person to check the wrong thing.
+ *
+ * ## Result shape
+ *
+ * A discriminated union rather than a throw: a rejected credential is an
+ * expected outcome of asking someone for credentials, not an exception. The
+ * caller decides whether to show, log or retry it.
+ *
+ * @module @huaweidevtools/aishell-dsh-credentials-store/verify
+ */
+import { type SignCredentials } from './signer.ts';
+/** One project visible to the credentials; its `name` is a region name. */
+export interface VerifiedProject {
+    /** The `project_id` a region-scoped API takes. */
+    readonly id: string;
+    /** The project name — the region name, e.g. `cn-north-4`. */
+    readonly name: string;
+    readonly description?: string;
+}
+/** The account the credentials belong to. */
+export interface VerifiedAccount {
+    /** The account id, equal to IAM's `domain_id`. */
+    readonly accountId: string;
+    /** The account (domain) name; falls back to {@link accountId} when unreadable. */
+    readonly name: string;
+    /**
+     * Every project visible to these credentials.
+     *
+     * More than one project may share a region name (enterprise projects), which
+     * is why this is not reduced to a region→project map: picking one would be a
+     * deployment decision this module has no basis for.
+     */
+    readonly projects: readonly VerifiedProject[];
+}
+/** A successful verification. */
+export interface VerifyOk {
+    readonly ok: true;
+    readonly account: VerifiedAccount;
+    /** The region the call was routed through; see the module note — not verified. */
+    readonly region: string;
+    /** Whether the credentials were temporary (STS). */
+    readonly sts: boolean;
+}
+/** A failed verification. */
+export interface VerifyFailed {
+    readonly ok: false;
+    /** HTTP status from IAM, or `0` for a network/signing failure. */
+    readonly status: number;
+    /** A sentence the person or model can act on. */
+    readonly message: string;
+}
+/** The outcome of one verification. */
+export type VerifyResult = VerifyOk | VerifyFailed;
+/** Options for {@link verifyCredentials}. */
+export interface VerifyOptions {
+    /** Region used to route the call. Does not scope the result; see the module note. */
+    readonly region: string;
+    /** Fetch implementation; defaults to the global. Injected so tests need no network. */
+    readonly fetchImpl?: typeof fetch;
+    /** Per-request timeout in milliseconds; defaults to 15 s. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Verify a credential pair against Huawei Cloud IAM.
+ *
+ * The pair is signed exactly as every other request is, so a 200 proves the
+ * same thing a successful tool call would prove — no separate verification
+ * scheme that could drift from the one that actually runs.
+ *
+ * @param credentials - the AK/SK (and optional STS token) to verify.
+ * @param options - region and transport details.
+ * @returns the account on success, or a failure naming what IAM said.
+ */
+export declare function verifyCredentials(credentials: SignCredentials, options: VerifyOptions): Promise<VerifyResult>;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAQ,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAExD,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CAC9C;AAED,iCAAiC;AACjC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAED,6BAA6B;AAC7B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,uCAAuC;AACvC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAA;AAElD,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uFAAuF;IACvF,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AA8CD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,eAAe,EAC5B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAqDvB"}