@smartledger/keys 3.0.0 → 3.1.1

package/dist/esm/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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"}

package/dist/esm/sdk.js

@@ -4,7 +4,27 @@
  * Integrates KeyRegistry and SignatureSuiteRegistry to provide
  * a clean, high-level API for key operations.
  */
-import { KeyRegistry, SignatureSuiteRegistry, hashBytes, BIP32Derivation, InMemoryKeyStorage, BsvEcdsaSuite, MlDsa87Suite, } from '@smartledger/crypto';
+import { KeyRegistry, SignatureSuiteRegistry, hashBytes, assertKeyUsable, isKeyUsable, cloneKeyMeta, agentIdOfKey, KeyAlreadyExistsError, BIP32Derivation, InMemoryKeyStorage, BsvEcdsaSuite, MlDsa44Suite, MlDsa65Suite, MlDsa87Suite, } from '@smartledger/crypto';
+export { agentIdOfKey };
+const COUNTER_SUFFIX = /^pk-[^:-]+-(\d+)$/;
+const MAX_KEY_ID_ATTEMPTS = 8;
+function assertAgentId(agentId) {
+    if (typeof agentId !== 'string' || agentId.length === 0) {
+        throw new Error('agentId must be a non-empty string');
+    }
+}
+function toRecord(meta, publicKey) {
+    // Copies, so a caller cannot reach registry state through a KeyRecord even
+    // when a custom storage backend hands out its own objects.
+    return { meta: cloneKeyMeta(meta), publicKey: Uint8Array.from(publicKey) };
+}
+function statusAllows(meta, policy) {
+    if (policy === 'any')
+        return true;
+    if (policy === 'not-revoked')
+        return meta.status !== 'revoked';
+    return isKeyUsable(meta);
+}
 /**
  * Default KeySDK implementation.
  *
@@ -15,6 +35,7 @@ export class DefaultKeySDK {
         this.keyCounter = new Map(); // agentId -> counter
         this.counterInitialized = new Set();
         this.counterInitPromises = new Map();
+        this.getOrCreateInFlight = new Map();
         this.keyRegistry = config.keyRegistry;
         this.suiteRegistry = config.suiteRegistry;
     }
@@ -22,6 +43,7 @@ export class DefaultKeySDK {
      * Create a new key for an agent.
      */
     async createKey(agentId, profile, options = {}) {
+        assertAgentId(agentId);
         // Get suite
         const suite = this.suiteRegistry.getSuite(profile.primarySignatureSuite);
         // Generate keypair (with optional derivation)
@@ -43,20 +65,16 @@ export class DefaultKeySDK {
             // Standard random key generation
             keypair = await suite.generateKeypair();
         }
-        // Generate unique keyId
-        const counter = await this.getNextCounter(agentId);
-        const suiteName = profile.primarySignatureSuite.split('-')[0]; // 'ml-dsa' or 'bsv'
-        const keyId = `${agentId}:pk-${suiteName}-${counter}`;
-        // Register key
-        const meta = await this.keyRegistry.registerKey(keyId, keypair, profile.primarySignatureSuite, {
+        const meta = await this.registerUnderFreshId(agentId, profile.primarySignatureSuite, keyId => this.keyRegistry.registerKey(keyId, keypair, profile.primarySignatureSuite, {
             expiresAt: options.expiresAt,
             usage: options.usage || ['signing'],
             cryptoProfileVersion: options.cryptoProfileVersion || '1.0.0',
-        });
-        return {
-            meta,
-            publicKey: keypair.publicKey,
-        };
+            // Record that (and where) the key was derived. Never the seed.
+            derivation: options.derivationContext
+                ? { path: options.derivationContext.path ?? '' }
+                : undefined,
+        }));
+        return toRecord(meta, keypair.publicKey);
     }
     /**
      * Get an existing key.
@@ -66,13 +84,13 @@ export class DefaultKeySDK {
         if (!result) {
             return null;
         }
-        return {
-            meta: result.meta,
-            publicKey: result.publicKey,
-        };
+        return toRecord(result.meta, result.publicKey);
     }
     /**
      * Sign with a key (private key never exposed).
+     *
+     * @throws if the key is unknown, not active, past its `expiresAt`, or not
+     *   registered for signing
      */
     async signWithKey(keyId, message) {
         // Get full keypair (private access)
@@ -80,9 +98,15 @@ export class DefaultKeySDK {
         if (!result) {
             throw new Error(`Key not found: ${keyId}`);
         }
-        if (result.meta.status !== 'active') {
+        if (result.meta.status && result.meta.status !== 'active') {
             throw new Error(`Key is not active: ${keyId} (status: ${result.meta.status})`);
         }
+        // Status alone is not enough: an expired key keeps status 'active' until
+        // markExpiredKeys() runs, and used to go on signing in the meantime.
+        assertKeyUsable(result.meta);
+        if (!result.meta.usage.some(u => u === 'signing' || u === 'both')) {
+            throw new Error(`Key is not registered for signing: ${keyId} (usage: ${result.meta.usage.join(', ')})`);
+        }
         // Get suite and sign
         const suite = this.suiteRegistry.getSuite(result.meta.suiteId);
         // Hash the message (consistent with signAgentResponse)
@@ -92,18 +116,29 @@ export class DefaultKeySDK {
     }
     /**
      * 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.
      */
-    async verifySignature(keyId, message, signature) {
+    async verifySignature(keyId, message, signature, options = {}) {
         const result = await this.keyRegistry.getPublicKey(keyId);
         if (!result) {
             return false;
         }
-        const suite = this.suiteRegistry.getSuite(result.meta.suiteId);
-        // Hash the message
-        const hashAlg = this.getHashAlgorithm(result.meta.suiteId);
-        const messageHash = await hashBytes(message, hashAlg);
+        if (!statusAllows(result.meta, options.keyStatus ?? 'any')) {
+            return false;
+        }
+        return this.verifyAgainst(result.meta, result.publicKey, message, signature);
+    }
+    /** The cryptographic check alone. Anything but a strict `true` is a failure. */
+    async verifyAgainst(meta, publicKey, message, signature) {
         try {
-            return await suite.verify(result.publicKey, messageHash, signature);
+            const suite = this.suiteRegistry.getSuite(meta.suiteId);
+            const hashAlg = this.getHashAlgorithm(meta.suiteId);
+            const messageHash = await hashBytes(message, hashAlg);
+            return (await suite.verify(publicKey, messageHash, signature)) === true;
         }
         catch {
             return false;
@@ -113,20 +148,18 @@ export class DefaultKeySDK {
      * List keys for an agent.
      */
     async listKeysForAgent(agentId, activeOnly = true) {
+        assertAgentId(agentId);
         const keys = activeOnly
             ? await this.keyRegistry.listActiveKeys()
             : await this.keyRegistry.listKeys();
-        // Filter by agentId prefix
-        const agentKeys = keys.filter(meta => meta.keyId.startsWith(`${agentId}:`));
+        // Exact ownership, not a prefix match (see agentIdOfKey)
+        const agentKeys = keys.filter(meta => agentIdOfKey(meta.keyId) === agentId);
         // Convert to KeyRecords
         const records = [];
         for (const meta of agentKeys) {
             const result = await this.keyRegistry.getPublicKey(meta.keyId);
             if (result) {
-                records.push({
-                    meta: result.meta,
-                    publicKey: result.publicKey,
-                });
+                records.push(toRecord(result.meta, result.publicKey));
             }
         }
         return records;
@@ -151,39 +184,87 @@ export class DefaultKeySDK {
     }
     /**
      * 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}.
      */
-    async rotateAgentKeys(agentId) {
+    async rotateAgentKeys(agentId, options = {}) {
+        const derivedPolicy = options.derivedKeys ?? 'error';
         const activeKeys = await this.listKeysForAgent(agentId, true);
-        const newKeys = [];
+        // Decide everything before changing anything.
+        const toRotate = [];
         for (const keyRecord of activeKeys) {
-            // Generate new keypair
+            // Resolves the suite now, so an unknown suite fails before any rotation.
+            this.suiteRegistry.getSuite(keyRecord.meta.suiteId);
+            if (keyRecord.meta.derivation) {
+                if (derivedPolicy === 'error') {
+                    throw new Error(`Key ${keyRecord.meta.keyId} was derived from a seed ` +
+                        `(path ${keyRecord.meta.derivation.path || 'unknown'}). Rotating it here would ` +
+                        `replace it with a random key that the mnemonic cannot recover. Derive the ` +
+                        `successor yourself with createKeyFromMnemonic at a new path, or pass ` +
+                        `{ derivedKeys: 'skip' } or { derivedKeys: 'randomize' }. No keys were rotated.`);
+                }
+                if (derivedPolicy === 'skip')
+                    continue;
+            }
+            toRotate.push(keyRecord);
+        }
+        // Generate every replacement before committing any, so a failing suite
+        // cannot leave the agent half rotated. The commits below are then one
+        // registry rotation per key; they are not a single transaction, so a
+        // storage failure part-way through leaves the earlier keys rotated.
+        const replacements = [];
+        for (const keyRecord of toRotate) {
             const suite = this.suiteRegistry.getSuite(keyRecord.meta.suiteId);
-            const newKeypair = await suite.generateKeypair();
-            // Generate new keyId (increment counter)
-            const counter = await this.getNextCounter(agentId);
-            const suiteName = keyRecord.meta.suiteId.split('-')[0];
-            const newKeyId = `${agentId}:pk-${suiteName}-${counter}`;
-            // Rotate
-            const newMeta = await this.keyRegistry.rotateKey(keyRecord.meta.keyId, newKeyId, newKeypair);
-            newKeys.push({
-                meta: newMeta,
-                publicKey: newKeypair.publicKey,
-            });
+            replacements.push(await suite.generateKeypair());
+        }
+        const newKeys = [];
+        for (const [i, keyRecord] of toRotate.entries()) {
+            const newKeypair = replacements[i];
+            const newMeta = await this.registerUnderFreshId(agentId, keyRecord.meta.suiteId, newKeyId => this.keyRegistry.rotateKey(keyRecord.meta.keyId, newKeyId, newKeypair, {
+                expiresAt: options.expiresAt,
+            }));
+            newKeys.push(toRecord(newMeta, newKeypair.publicKey));
         }
         return newKeys;
     }
     /**
      * 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.
      */
     async getOrCreateKey(agentId, profile, options = {}) {
-        // Check if key exists
-        const existingKeys = await this.listKeysForAgent(agentId, true);
-        const primaryKey = existingKeys.find(k => k.meta.suiteId === profile.primarySignatureSuite);
-        if (primaryKey) {
-            return primaryKey;
-        }
-        // Create new key
-        return await this.createKey(agentId, profile, options);
+        assertAgentId(agentId);
+        const slot = JSON.stringify([agentId, profile.primarySignatureSuite]);
+        const pending = this.getOrCreateInFlight.get(slot);
+        if (pending) {
+            const record = await pending;
+            return toRecord(record.meta, record.publicKey);
+        }
+        const work = (async () => {
+            // Check if key exists
+            const existingKeys = await this.listKeysForAgent(agentId, true);
+            const primaryKey = existingKeys.find(k => k.meta.suiteId === profile.primarySignatureSuite);
+            if (primaryKey) {
+                return primaryKey;
+            }
+            // Create new key
+            return await this.createKey(agentId, profile, options);
+        })();
+        this.getOrCreateInFlight.set(slot, work);
+        try {
+            return await work;
+        }
+        finally {
+            this.getOrCreateInFlight.delete(slot);
+        }
     }
     /**
      * Create both primary and secondary keys for an agent.
@@ -192,6 +273,7 @@ export class DefaultKeySDK {
         if (!profile.secondarySignatureSuite) {
             throw new Error('secondarySignatureSuite is required to create dual signature keys');
         }
+        this.assertDualProfile(profile);
         const primaryKey = await this.createKey(agentId, {
             primarySignatureSuite: profile.primarySignatureSuite,
         }, options);
@@ -207,6 +289,7 @@ export class DefaultKeySDK {
         if (!profile.secondarySignatureSuite) {
             throw new Error('secondarySignatureSuite is required to create dual signature keys');
         }
+        this.assertDualProfile(profile);
         const primaryKey = await this.getOrCreateKey(agentId, {
             primarySignatureSuite: profile.primarySignatureSuite,
         }, options);
@@ -215,6 +298,18 @@ export class DefaultKeySDK {
         }, options);
         return { primaryKey, secondaryKey };
     }
+    /**
+     * 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).
+     */
+    assertDualProfile(profile) {
+        this.suiteRegistry.getSuite(profile.primarySignatureSuite);
+        this.suiteRegistry.getSuite(profile.secondarySignatureSuite);
+        if (profile.primarySignatureSuite === profile.secondarySignatureSuite) {
+            throw new Error(`Dual signature keys need two different suites; both are ${profile.primarySignatureSuite}`);
+        }
+    }
     /**
      * Sign with one or more suites for an agent.
      */
@@ -223,7 +318,7 @@ export class DefaultKeySDK {
         if (activeKeys.length === 0) {
             throw new Error(`No active keys found for agent: ${agentId}`);
         }
-        const suitesToUse = suites?.length ? suites : Array.from(new Set(activeKeys.map(k => k.meta.suiteId)));
+        const suitesToUse = Array.from(new Set(suites?.length ? suites : activeKeys.map(k => k.meta.suiteId)));
         const signatures = [];
         for (const suiteId of suitesToUse) {
             const key = activeKeys.find(k => k.meta.suiteId === suiteId);
@@ -236,27 +331,92 @@ export class DefaultKeySDK {
         return { signatures };
     }
     /**
-     * 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.
      */
-    async verifyWithSuites(agentId, message, signatures) {
+    async verifyWithSuites(agentId, message, signatures, options = {}) {
+        assertAgentId(agentId);
+        const keyStatus = options.keyStatus ?? 'not-revoked';
+        const requiredSuites = Array.from(new Set(options.requiredSuites ??
+            (await this.listKeysForAgent(agentId, true)).map(k => k.meta.suiteId)));
+        const refuse = (error, results = []) => ({
+            results,
+            allValid: false,
+            requiredSuites,
+            missingSuites: requiredSuites.filter(s => !results.some(r => r.valid && r.suiteId === s)),
+            error,
+        });
+        if (!Array.isArray(signatures)) {
+            return refuse('signatures must be an array');
+        }
         const results = [];
         for (const entry of signatures) {
+            const suiteId = String(entry?.suiteId);
+            const keyId = String(entry?.keyId);
+            const fail = (error) => results.push({ suiteId, keyId, valid: false, error });
             try {
-                const valid = await this.verifySignature(entry.keyId, message, entry.signature);
-                results.push({ suiteId: entry.suiteId, keyId: entry.keyId, valid });
+                if (agentIdOfKey(keyId) !== agentId) {
+                    fail(`Key does not belong to agent '${agentId}'`);
+                    continue;
+                }
+                const key = await this.keyRegistry.getPublicKey(keyId);
+                if (!key) {
+                    fail('Key not found');
+                    continue;
+                }
+                if (key.meta.suiteId !== suiteId) {
+                    fail(`Suite mismatch: key is ${key.meta.suiteId}, signature claims ${suiteId}`);
+                    continue;
+                }
+                if (!statusAllows(key.meta, keyStatus)) {
+                    fail(`Key status not accepted (status: ${key.meta.status ?? 'active'}, policy: ${keyStatus})`);
+                    continue;
+                }
+                if (!(entry.signature instanceof Uint8Array)) {
+                    fail('Signature must be a Uint8Array');
+                    continue;
+                }
+                const valid = await this.verifyAgainst(key.meta, key.publicKey, message, entry.signature);
+                if (valid) {
+                    results.push({ suiteId, keyId, valid: true });
+                }
+                else {
+                    fail('Signature verification failed');
+                }
             }
             catch (error) {
-                results.push({
-                    suiteId: entry.suiteId,
-                    keyId: entry.keyId,
-                    valid: false,
-                    error: error.message,
-                });
+                fail(error instanceof Error ? error.message : String(error));
             }
         }
+        if (requiredSuites.length === 0) {
+            return refuse(`No required suites: agent '${agentId}' has no usable keys and options.requiredSuites was not given`, results);
+        }
+        if (results.length === 0) {
+            return refuse('No signatures supplied', results);
+        }
+        // Walk the REQUIRED suites and look each up among the valid signatures.
+        const missingSuites = requiredSuites.filter(required => !results.some(r => r.valid && r.suiteId === required));
+        const everySuppliedValid = results.every(r => r.valid === true);
         return {
             results,
-            allValid: results.every(r => r.valid),
+            allValid: everySuppliedValid && missingSuites.length === 0,
+            requiredSuites,
+            missingSuites,
+            ...(missingSuites.length > 0
+                ? { error: `No valid signature for required suite(s): ${missingSuites.join(', ')}` }
+                : {}),
         };
     }
     /**
@@ -276,22 +436,29 @@ export class DefaultKeySDK {
      *
      * @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
      */
     async createKeyFromMnemonic(agentId, profile, mnemonic, path = BIP32Derivation.bitcoinPath(0, 0, 0), passphrase, options = {}) {
         const bip32 = new BIP32Derivation();
         const seed = bip32.mnemonicToSeed(mnemonic, passphrase);
-        return await this.createKey(agentId, profile, {
-            ...options,
-            derivationContext: {
-                seed,
-                path,
-            },
-        });
+        try {
+            return await this.createKey(agentId, profile, {
+                ...options,
+                derivationContext: {
+                    seed,
+                    path,
+                },
+            });
+        }
+        finally {
+            // The seed is the root of every key in the wallet; do not leave it behind.
+            seed.fill(0);
+        }
     }
     /**
      * Get available capabilities for a specific suite.
@@ -323,10 +490,36 @@ export class DefaultKeySDK {
             .map(suite => suite.suiteId);
     }
     /**
-     * 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`.
+     *
+     * 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
+     */
+    async createWalletKey(agentId, mnemonic, path, options = {}) {
+        if (!path || typeof path.coinType !== 'number') {
+            throw new Error('createWalletKey requires path.coinType (SLIP-44: Bitcoin is 0, Bitcoin SV is 236)');
+        }
+        const derivationPath = BIP32Derivation.bip44Path(path.coinType, path.account ?? 0, path.change ? 1 : 0, path.index ?? 0);
+        return this.createKeyFromMnemonic(agentId, { primarySignatureSuite: 'bsv-ecdsa-secp256k1' }, mnemonic, derivationPath, path.passphrase, options);
+    }
+    /**
+     * Create a wallet key from mnemonic at the Bitcoin (BTC) BIP44 path:
+     * m/44'/0'/account'/change/addressIndex
      *
-     * Uses standard BIP44 Bitcoin 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)
@@ -348,6 +541,34 @@ export class DefaultKeySDK {
         }
         return 'sha256';
     }
+    /**
+     * 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.
+     */
+    async registerUnderFreshId(agentId, suiteId, register) {
+        // 'ml' for every ml-dsa suite, 'bsv' for bsv-ecdsa-secp256k1
+        const suiteName = suiteId.split('-')[0].replace(/[^A-Za-z0-9]/g, '') || 'key';
+        for (let attempt = 0; attempt < MAX_KEY_ID_ATTEMPTS; attempt++) {
+            const counter = await this.getNextCounter(agentId);
+            const keyId = `${agentId}:pk-${suiteName}-${counter}`;
+            try {
+                return await register(keyId);
+            }
+            catch (error) {
+                if (!(error instanceof KeyAlreadyExistsError))
+                    throw error;
+                // Someone else holds that ID: forget the cached counter and re-read.
+                this.counterInitialized.delete(agentId);
+                this.keyCounter.delete(agentId);
+            }
+        }
+        throw new Error(`Could not allocate a key ID for agent '${agentId}' after ${MAX_KEY_ID_ATTEMPTS} attempts`);
+    }
     /**
      * Helper: Get next counter for an agent.
      */
@@ -355,19 +576,25 @@ export class DefaultKeySDK {
         if (!this.counterInitialized.has(agentId)) {
             if (!this.counterInitPromises.has(agentId)) {
                 const initPromise = (async () => {
-                    const existing = await this.keyRegistry.listKeys();
-                    const max = existing.reduce((acc, meta) => {
-                        if (!meta.keyId.startsWith(`${agentId}:pk-`))
-                            return acc;
-                        const match = meta.keyId.match(/:pk-[^-]+-(\d+)$/);
-                        if (!match)
-                            return acc;
-                        const num = parseInt(match[1], 10);
-                        return Number.isFinite(num) ? Math.max(acc, num) : acc;
-                    }, 0);
-                    this.keyCounter.set(agentId, max);
-                    this.counterInitialized.add(agentId);
-                    this.counterInitPromises.delete(agentId);
+                    try {
+                        const existing = await this.keyRegistry.listKeys();
+                        const max = existing.reduce((acc, meta) => {
+                            if (agentIdOfKey(meta.keyId) !== agentId)
+                                return acc;
+                            const local = meta.keyId.slice(agentId.length + 1);
+                            const match = COUNTER_SUFFIX.exec(local);
+                            if (!match)
+                                return acc;
+                            const num = parseInt(match[1], 10);
+                            return Number.isSafeInteger(num) ? Math.max(acc, num) : acc;
+                        }, 0);
+                        // A counter handed out while this scan ran must not be reused.
+                        this.keyCounter.set(agentId, Math.max(max, this.keyCounter.get(agentId) || 0));
+                        this.counterInitialized.add(agentId);
+                    }
+                    finally {
+                        this.counterInitPromises.delete(agentId);
+                    }
                 })();
                 this.counterInitPromises.set(agentId, initPromise);
             }
@@ -421,9 +648,17 @@ export class DefaultKeySDK {
 export function createKeySDK(config) {
     const keyRegistry = config?.keyRegistry || new KeyRegistry(new InMemoryKeyStorage());
     const suiteRegistry = config?.suiteRegistry || new SignatureSuiteRegistry();
-    // Register default suites if not provided
+    // Register default suites if not provided.
+    //
+    // All three ML-DSA levels are registered, not just 87. The README documents
+    // ml-dsa-65 as the recommended default and ml-dsa-44 for constrained
+    // devices; registering only 87 made every one of those examples throw
+    // `Unknown signature suite` at runtime, with no way for a caller to fix it
+    // -- SignatureSuiteRegistry is not re-exported from this package.
     if (!config?.suiteRegistry) {
         suiteRegistry.register(new BsvEcdsaSuite());
+        suiteRegistry.register(new MlDsa44Suite());
+        suiteRegistry.register(new MlDsa65Suite());
         suiteRegistry.register(new MlDsa87Suite());
     }
     return new DefaultKeySDK({