@smartledger/keys 3.0.0 → 3.1.0

package/dist/cjs/browser.d.ts

@@ -1,18 +1,28 @@
 /**
- * Browser entry point for @lumen/keys SDK
- * Includes WASM initialization and browser-compatible exports
+ * Entry point of the browser <script> bundle (dist/lumen-keys(.min).js),
+ * which exposes `window.LumenKeys`.
+ *
+ * Bundlers and Node should import '@smartledger/keys' itself: the ESM build
+ * runs unchanged in browsers. This file exists for the script-tag build only.
  */
+import { KeyRegistry } from '@smartledger/crypto';
 import type { KeySDK } from './types.js';
 export * from './types.js';
-export { InMemoryKeyStorage } from '@smartledger/crypto';
+export { InMemoryKeyStorage, KeyRegistry } from '@smartledger/crypto';
 /**
- * Creates a new KeySDK instance for browser usage
- * Handles WASM initialization automatically
+ * Creates a new KeySDK instance for browser usage.
+ *
+ * Async for backward compatibility with earlier bundles; nothing is awaited
+ * (the cryptography is pure JavaScript, there is no WASM to initialise).
  *
  * All signature suites (ECDSA, ML-DSA-44, ML-DSA-65, ML-DSA-87) are
  * auto-registered in globalRegistry when @smartledger/crypto loads.
+ *
+ * Keys live in memory only and are gone when the page unloads.
  */
-export declare function createKeySDK(): Promise<KeySDK>;
+export declare function createKeySDK(config?: {
+    keyRegistry?: KeyRegistry;
+}): Promise<KeySDK>;
 /**
  * Browser-ready default export
  */

package/dist/cjs/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAepD;AAED;;GAEG;;;;AACH,wBAEE"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAEL,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,MAAM,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAY1F;AAED;;GAEG;;;;AACH,wBAEE"}

package/dist/cjs/browser.js

@@ -1,7 +1,10 @@
 "use strict";
 /**
- * Browser entry point for @lumen/keys SDK
- * Includes WASM initialization and browser-compatible exports
+ * Entry point of the browser <script> bundle (dist/lumen-keys(.min).js),
+ * which exposes `window.LumenKeys`.
+ *
+ * Bundlers and Node should import '@smartledger/keys' itself: the ESM build
+ * runs unchanged in browsers. This file exists for the script-tag build only.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -18,7 +21,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryKeyStorage = void 0;
+exports.KeyRegistry = exports.InMemoryKeyStorage = void 0;
 exports.createKeySDK = createKeySDK;
 const sdk_js_1 = require("./sdk.js");
 const crypto_1 = require("@smartledger/crypto");
@@ -26,24 +29,26 @@ const crypto_1 = require("@smartledger/crypto");
 __exportStar(require("./types.js"), exports);
 var crypto_2 = require("@smartledger/crypto");
 Object.defineProperty(exports, "InMemoryKeyStorage", { enumerable: true, get: function () { return crypto_2.InMemoryKeyStorage; } });
+Object.defineProperty(exports, "KeyRegistry", { enumerable: true, get: function () { return crypto_2.KeyRegistry; } });
 /**
- * Creates a new KeySDK instance for browser usage
- * Handles WASM initialization automatically
+ * Creates a new KeySDK instance for browser usage.
+ *
+ * Async for backward compatibility with earlier bundles; nothing is awaited
+ * (the cryptography is pure JavaScript, there is no WASM to initialise).
  *
  * All signature suites (ECDSA, ML-DSA-44, ML-DSA-65, ML-DSA-87) are
  * auto-registered in globalRegistry when @smartledger/crypto loads.
+ *
+ * Keys live in memory only and are gone when the page unloads.
  */
-async function createKeySDK() {
-    const storage = new crypto_1.InMemoryKeyStorage();
-    const keyRegistry = new crypto_1.KeyRegistry(storage);
+async function createKeySDK(config) {
+    const keyRegistry = config?.keyRegistry ?? new crypto_1.KeyRegistry(new crypto_1.InMemoryKeyStorage());
     // Use the global registry with auto-registered suites
     // (BsvEcdsaSuite, MlDsa44Suite, MlDsa65Suite, MlDsa87Suite)
     const sdk = new sdk_js_1.DefaultKeySDK({
         keyRegistry,
         suiteRegistry: crypto_1.globalRegistry,
     });
-    // Pre-initialize WASM for ML-DSA if needed
-    // The dilithium-crystals library will lazy-load WASM on first use
     return sdk;
 }
 /**

package/dist/cjs/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;;AAqBH,oCAeC;AAlCD,qCAAyC;AACzC,gDAI6B;AAG7B,wCAAwC;AACxC,6CAA2B;AAC3B,8CAAyD;AAAhD,4GAAA,kBAAkB,OAAA;AAE3B;;;;;;GAMG;AACI,KAAK,UAAU,YAAY;IAChC,MAAM,OAAO,GAAG,IAAI,2BAAkB,EAAE,CAAC;IACzC,MAAM,WAAW,GAAG,IAAI,oBAAW,CAAC,OAAO,CAAC,CAAC;IAE7C,sDAAsD;IACtD,4DAA4D;IAC5D,MAAM,GAAG,GAAG,IAAI,sBAAa,CAAC;QAC5B,WAAW;QACX,aAAa,EAAE,uBAAc;KAC9B,CAAC,CAAC;IAEH,2CAA2C;IAC3C,kEAAkE;IAElE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,kBAAe;IACb,YAAY;CACb,CAAC;AAEF,8BAA8B;AAC9B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;IACjC,MAAc,CAAC,SAAS,GAAG;QAC1B,YAAY;KACb,CAAC;AACJ,CAAC"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;AAyBH,oCAYC;AAnCD,qCAAyC;AACzC,gDAI6B;AAG7B,wCAAwC;AACxC,6CAA2B;AAC3B,8CAAsE;AAA7D,4GAAA,kBAAkB,OAAA;AAAE,qGAAA,WAAW,OAAA;AAExC;;;;;;;;;;GAUG;AACI,KAAK,UAAU,YAAY,CAAC,MAAsC;IACvE,MAAM,WAAW,GAAG,MAAM,EAAE,WAAW,IAAI,IAAI,oBAAW,CAAC,IAAI,2BAAkB,EAAE,CAAC,CAAC;IAErF,sDAAsD;IACtD,4DAA4D;IAC5D,MAAM,GAAG,GAAG,IAAI,sBAAa,CAAC;QAC5B,WAAW;QACX,aAAa,EAAE,uBAAc;KAC9B,CAAC,CAAC;IAGH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,kBAAe;IACb,YAAY;CACb,CAAC;AAEF,8BAA8B;AAC9B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;IACjC,MAAc,CAAC,SAAS,GAAG;QAC1B,YAAY;KACb,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Entry point of the browser <script> bundle (dist/lumen-keys(.min).js),\n * which exposes `window.LumenKeys`.\n *\n * Bundlers and Node should import '@smartledger/keys' itself: the ESM build\n * runs unchanged in browsers. This file exists for the script-tag build only.\n */\n\nimport { DefaultKeySDK } from './sdk.js';\nimport { \n  InMemoryKeyStorage, \n  KeyRegistry,\n  globalRegistry,\n} from '@smartledger/crypto';\nimport type { KeySDK } from './types.js';\n\n// Re-export all types for browser usage\nexport * from './types.js';\nexport { InMemoryKeyStorage, KeyRegistry } from '@smartledger/crypto';\n\n/**\n * Creates a new KeySDK instance for browser usage.\n *\n * Async for backward compatibility with earlier bundles; nothing is awaited\n * (the cryptography is pure JavaScript, there is no WASM to initialise).\n * \n * All signature suites (ECDSA, ML-DSA-44, ML-DSA-65, ML-DSA-87) are\n * auto-registered in globalRegistry when @smartledger/crypto loads.\n *\n * Keys live in memory only and are gone when the page unloads.\n */\nexport async function createKeySDK(config?: { keyRegistry?: KeyRegistry }): Promise<KeySDK> {\n  const keyRegistry = config?.keyRegistry ?? new KeyRegistry(new InMemoryKeyStorage());\n  \n  // Use the global registry with auto-registered suites\n  // (BsvEcdsaSuite, MlDsa44Suite, MlDsa65Suite, MlDsa87Suite)\n  const sdk = new DefaultKeySDK({\n    keyRegistry,\n    suiteRegistry: globalRegistry,\n  });\n  \n  \n  return sdk;\n}\n\n/**\n * Browser-ready default export\n */\nexport default {\n  createKeySDK,\n};\n\n// Global export for CDN usage\nif (typeof window !== 'undefined') {\n  (window as any).LumenKeys = {\n    createKeySDK,\n  };\n}\n"]}

package/dist/cjs/index.d.ts

@@ -7,4 +7,7 @@ export * from './types.js';
 export * from './sdk.js';
 export type { KeyMeta, CryptoProfile } from '@smartledger/crypto';
 export { BIP32Derivation } from '@smartledger/crypto';
+export { SignatureSuiteRegistry, BsvEcdsaSuite, MlDsa44Suite, MlDsa65Suite, MlDsa87Suite, } from '@smartledger/crypto';
+export { KeyRegistry, InMemoryKeyStorage, isKeyUsable, assertKeyUsable, KeyAlreadyExistsError, KeyExpiredError, KeyInvalidStateError, } from '@smartledger/crypto';
+export type { KeyStorage } from '@smartledger/crypto';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AAGzB,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AAGzB,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAKtD,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/cjs/index.js

@@ -19,9 +19,27 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BIP32Derivation = void 0;
+exports.KeyInvalidStateError = exports.KeyExpiredError = exports.KeyAlreadyExistsError = exports.assertKeyUsable = exports.isKeyUsable = exports.InMemoryKeyStorage = exports.KeyRegistry = exports.MlDsa87Suite = exports.MlDsa65Suite = exports.MlDsa44Suite = exports.BsvEcdsaSuite = exports.SignatureSuiteRegistry = exports.BIP32Derivation = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./sdk.js"), exports);
 var crypto_1 = require("@smartledger/crypto");
 Object.defineProperty(exports, "BIP32Derivation", { enumerable: true, get: function () { return crypto_1.BIP32Derivation; } });
+// Re-exported so callers can build or extend a suite registry without taking
+// a direct dependency on @smartledger/crypto -- doing so pulls in a second
+// copy of the library and splits the registry.
+var crypto_2 = require("@smartledger/crypto");
+Object.defineProperty(exports, "SignatureSuiteRegistry", { enumerable: true, get: function () { return crypto_2.SignatureSuiteRegistry; } });
+Object.defineProperty(exports, "BsvEcdsaSuite", { enumerable: true, get: function () { return crypto_2.BsvEcdsaSuite; } });
+Object.defineProperty(exports, "MlDsa44Suite", { enumerable: true, get: function () { return crypto_2.MlDsa44Suite; } });
+Object.defineProperty(exports, "MlDsa65Suite", { enumerable: true, get: function () { return crypto_2.MlDsa65Suite; } });
+Object.defineProperty(exports, "MlDsa87Suite", { enumerable: true, get: function () { return crypto_2.MlDsa87Suite; } });
+// Key-state helpers and the errors callers are expected to catch.
+var crypto_3 = require("@smartledger/crypto");
+Object.defineProperty(exports, "KeyRegistry", { enumerable: true, get: function () { return crypto_3.KeyRegistry; } });
+Object.defineProperty(exports, "InMemoryKeyStorage", { enumerable: true, get: function () { return crypto_3.InMemoryKeyStorage; } });
+Object.defineProperty(exports, "isKeyUsable", { enumerable: true, get: function () { return crypto_3.isKeyUsable; } });
+Object.defineProperty(exports, "assertKeyUsable", { enumerable: true, get: function () { return crypto_3.assertKeyUsable; } });
+Object.defineProperty(exports, "KeyAlreadyExistsError", { enumerable: true, get: function () { return crypto_3.KeyAlreadyExistsError; } });
+Object.defineProperty(exports, "KeyExpiredError", { enumerable: true, get: function () { return crypto_3.KeyExpiredError; } });
+Object.defineProperty(exports, "KeyInvalidStateError", { enumerable: true, get: function () { return crypto_3.KeyInvalidStateError; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,2CAAyB;AAIzB,8CAAsD;AAA7C,yGAAA,eAAe,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,2CAAyB;AAIzB,8CAAsD;AAA7C,yGAAA,eAAe,OAAA;AAExB,6EAA6E;AAC7E,2EAA2E;AAC3E,+CAA+C;AAC/C,8CAM6B;AAL3B,gHAAA,sBAAsB,OAAA;AACtB,uGAAA,aAAa,OAAA;AACb,sGAAA,YAAY,OAAA;AACZ,sGAAA,YAAY,OAAA;AACZ,sGAAA,YAAY,OAAA;AAGd,kEAAkE;AAClE,8CAQ6B;AAP3B,qGAAA,WAAW,OAAA;AACX,4GAAA,kBAAkB,OAAA;AAClB,qGAAA,WAAW,OAAA;AACX,yGAAA,eAAe,OAAA;AACf,+GAAA,qBAAqB,OAAA;AACrB,yGAAA,eAAe,OAAA;AACf,8GAAA,oBAAoB,OAAA","sourcesContent":["/**\n * @smartledger/keys - Key Management SDK\n * \n * Single source of truth for cryptographic key operations.\n */\n\nexport * from './types.js';\nexport * from './sdk.js';\n\n// Re-export commonly used types and utilities from @smartledger/crypto\nexport type { KeyMeta, CryptoProfile } from '@smartledger/crypto';\nexport { BIP32Derivation } from '@smartledger/crypto';\n\n// Re-exported so callers can build or extend a suite registry without taking\n// a direct dependency on @smartledger/crypto -- doing so pulls in a second\n// copy of the library and splits the registry.\nexport {\n  SignatureSuiteRegistry,\n  BsvEcdsaSuite,\n  MlDsa44Suite,\n  MlDsa65Suite,\n  MlDsa87Suite,\n} from '@smartledger/crypto';\n\n// Key-state helpers and the errors callers are expected to catch.\nexport {\n  KeyRegistry,\n  InMemoryKeyStorage,\n  isKeyUsable,\n  assertKeyUsable,\n  KeyAlreadyExistsError,\n  KeyExpiredError,\n  KeyInvalidStateError,\n} from '@smartledger/crypto';\nexport type { KeyStorage } from '@smartledger/crypto';\n"]}

package/dist/cjs/sdk.d.ts

@@ -4,8 +4,8 @@
  * Integrates KeyRegistry and SignatureSuiteRegistry to provide
  * a clean, high-level API for key operations.
  */
-import { KeyRegistry, SignatureSuiteRegistry, CryptoProfile } from '@smartledger/crypto';
-import { KeySDK, KeyRecord, CreateKeyOptions, MultiSignatureResult, MultiVerificationResult, SuiteSignature } from './types.js';
+import { KeyRegistry, SignatureSuiteRegistry, CryptoProfile, agentIdOfKey } from '@smartledger/crypto';
+import { KeySDK, KeyRecord, CreateKeyOptions, MultiSignatureResult, MultiVerificationResult, SuiteSignature, VerifySignatureOptions, VerifyWithSuitesOptions, RotateAgentKeysOptions, WalletKeyPath } from './types.js';
 /**
  * Configuration for DefaultKeySDK.
  */
@@ -15,6 +15,7 @@ export interface KeySDKConfig {
     /** Signature suite registry instance */
     suiteRegistry: SignatureSuiteRegistry;
 }
+export { agentIdOfKey };
 /**
  * Default KeySDK implementation.
  *
@@ -26,6 +27,7 @@ export declare class DefaultKeySDK implements KeySDK {
     private keyCounter;
     private counterInitialized;
     private counterInitPromises;
+    private getOrCreateInFlight;
     constructor(config: KeySDKConfig);
     /**
      * Create a new key for an agent.
@@ -37,12 +39,22 @@ export declare class DefaultKeySDK implements KeySDK {
     getKey(keyId: string): Promise<KeyRecord | null>;
     /**
      * Sign with a key (private key never exposed).
+     *
+     * @throws if the key is unknown, not active, past its `expiresAt`, or not
+     *   registered for signing
      */
     signWithKey(keyId: string, message: Uint8Array): Promise<Uint8Array>;
     /**
      * Verify a signature.
+     *
+     * By default this is the cryptographic check only: a signature made by a
+     * key that has since been rotated, expired or revoked still verifies, which
+     * is what verifying a historical signature needs. Pass `keyStatus` to also
+     * require something of the key's state now.
      */
-    verifySignature(keyId: string, message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+    verifySignature(keyId: string, message: Uint8Array, signature: Uint8Array, options?: VerifySignatureOptions): Promise<boolean>;
+    /** The cryptographic check alone. Anything but a strict `true` is a failure. */
+    private verifyAgainst;
     /**
      * List keys for an agent.
      */
@@ -53,10 +65,22 @@ export declare class DefaultKeySDK implements KeySDK {
     getActiveCryptoProfile(agentId: string): Promise<CryptoProfile | null>;
     /**
      * Rotate all keys for an agent.
+     *
+     * Each replacement gets its predecessor's lifetime again, counted from now
+     * (or `options.expiresAt`); it does not inherit the old expiry instant.
+     *
+     * A key derived from a seed cannot be re-derived here, because the SDK does
+     * not keep seeds. By default the call refuses, before changing anything,
+     * rather than silently swapping a recoverable key for a random one. See
+     * {@link RotateAgentKeysOptions.derivedKeys}.
      */
-    rotateAgentKeys(agentId: string): Promise<KeyRecord[]>;
+    rotateAgentKeys(agentId: string, options?: RotateAgentKeysOptions): Promise<KeyRecord[]>;
     /**
      * Get or create key (idempotent).
+     *
+     * Concurrent calls on this SDK instance for the same agent and suite share
+     * one creation. Two SDK instances (or processes) on one storage backend can
+     * still each create a key; that needs a lock in the backend.
      */
     getOrCreateKey(agentId: string, profile: CryptoProfile, options?: CreateKeyOptions): Promise<KeyRecord>;
     /**
@@ -73,14 +97,33 @@ export declare class DefaultKeySDK implements KeySDK {
         primaryKey: KeyRecord;
         secondaryKey: KeyRecord;
     }>;
+    /**
+     * Fail before creating either key if the pair could not be a hybrid pair:
+     * an unknown suite, or the same suite twice (two ECDSA keys are not a
+     * classical + post-quantum pair, whatever the profile calls them).
+     */
+    private assertDualProfile;
     /**
      * Sign with one or more suites for an agent.
      */
     signWithSuites(agentId: string, message: Uint8Array, suites?: string[]): Promise<MultiSignatureResult>;
     /**
-     * Verify multiple signatures for an agent.
+     * Verify a set of signatures as a hybrid (multi-suite) signature by `agentId`.
+     *
+     * `allValid` is true only when ALL of these hold:
+     * - at least one signature was supplied;
+     * - every supplied signature is by a key that belongs to `agentId`, names
+     *   that key's real suite, passes the key-status policy, and verifies;
+     * - every REQUIRED suite has such a signature.
+     *
+     * The required suites come from the verifier: `options.requiredSuites`, or
+     * by default the suites of the agent's currently usable keys in this SDK's
+     * registry. They are never read from `signatures`. The check walks the
+     * required suites and looks each one up among the valid signatures, so an
+     * empty list, or one that merely omits the post-quantum signature, is
+     * refused instead of passing because everything in it happens to be valid.
      */
-    verifyWithSuites(agentId: string, message: Uint8Array, signatures: SuiteSignature[]): Promise<MultiVerificationResult>;
+    verifyWithSuites(agentId: string, message: Uint8Array, signatures: SuiteSignature[], options?: VerifyWithSuitesOptions): Promise<MultiVerificationResult>;
     /**
      * Generate a new BIP39 mnemonic phrase.
      *
@@ -95,11 +138,12 @@ export declare class DefaultKeySDK implements KeySDK {
      *
      * @param agentId Agent identifier
      * @param profile Crypto profile (must use derivation-capable suite)
-     * @param mnemonic BIP39 mnemonic phrase
+     * @param mnemonic BIP39 mnemonic phrase (words and checksum are validated)
      * @param path BIP32 derivation path (default: "m/44'/0'/0'/0/0")
      * @param passphrase Optional BIP39 passphrase
      * @param options Additional key creation options
      * @returns KeyRecord with derived key
+     * @throws if the mnemonic has an unknown word, a wrong word count or a bad checksum
      */
     createKeyFromMnemonic(agentId: string, profile: CryptoProfile, mnemonic: string, path?: string, passphrase?: string, options?: CreateKeyOptions): Promise<KeyRecord>;
     /**
@@ -117,11 +161,31 @@ export declare class DefaultKeySDK implements KeySDK {
      */
     getSuitesWithCapability(capability: 'derivation' | 'encryption' | 'threshold'): string[];
     /**
-     * Create a Bitcoin wallet key from mnemonic (convenience method).
+     * Create a wallet key from a mnemonic at an explicit BIP44 coin type:
+     * `m/44'/coinType'/account'/change/index`.
      *
-     * Uses standard BIP44 Bitcoin path: m/44'/0'/account'/change/addressIndex
+     * The coin type is required and has no default. It decides which wallets
+     * will find the key again: Bitcoin (BTC) is 0, Bitcoin SV is 236.
      *
      * @param agentId Agent identifier
+     * @param mnemonic BIP39 mnemonic phrase (words and checksum are validated)
+     * @param path Coin type and position in the BIP44 tree
+     * @param options Additional key creation options
+     * @returns KeyRecord with the derived secp256k1 key
+     */
+    createWalletKey(agentId: string, mnemonic: string, path: WalletKeyPath, options?: CreateKeyOptions): Promise<KeyRecord>;
+    /**
+     * Create a wallet key from mnemonic at the Bitcoin (BTC) BIP44 path:
+     * m/44'/0'/account'/change/addressIndex
+     *
+     * NOTE: coin type 0 is BTC. A Bitcoin SV wallet restoring the same mnemonic
+     * looks under coin type 236 and will not find this key. The path is left
+     * as it is because changing it would move every key already created with
+     * this method. For new code use {@link createWalletKey}, which makes the
+     * coin type explicit.
+     *
+     * @deprecated Use createWalletKey(agentId, mnemonic, { coinType, ... }).
+     * @param agentId Agent identifier
      * @param mnemonic BIP39 mnemonic phrase
      * @param accountIndex Account index (default: 0)
      * @param addressIndex Address index (default: 0)
@@ -134,6 +198,16 @@ export declare class DefaultKeySDK implements KeySDK {
      * Helper: Get hash algorithm for a suite.
      */
     private getHashAlgorithm;
+    /**
+     * Helper: register a key under the agent's next free key ID.
+     *
+     * The counter is cached per SDK instance, so another instance (or process)
+     * on the same storage can have taken the ID already. The registry refuses
+     * to overwrite; on that refusal the counter is re-read from storage and the
+     * next ID is tried. Before, the second writer silently replaced the first
+     * writer's private key.
+     */
+    private registerUnderFreshId;
     /**
      * Helper: Get next counter for an agent.
      */

package/dist/cjs/sdk.d.ts.map

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