@smartledger/keys 2.0.0 → 3.1.0

package/README.md

@@ -1,548 +1,201 @@
-# @smartledger/keys SDK Documentation
-
-**Single source of truth for cryptographic key operations.**
-
-Version: 1.5.1  
-Status: ✅ Production Ready  
-Tests: 52/52 passing
-
-**New in 1.5.1:** All three ML-DSA security levels now available (44/65/87)
-
----
-
-## Why This SDK?
-
-Keys are the **root of everything** in your crypto architecture:
-- Identity
-- Signatures  
-- PQ migration
-- Regulatory/audit story
-
-Without a clean SDK layer, key handling becomes **ad hoc** and **brittle**:
-- ❌ Random `generateKeypair()` implementations scattered across repos
-- ❌ Slightly different formats (hex here, base64 there)
-- ❌ Surprise refactors when adding PQ suites
-- ❌ Private keys exposed to calling code
-
-**With `@smartledger/keys`**, all your agents/modules/bridge code simply ask:
-```typescript
-"Give me a signing key of suite X"
-"Sign this payload with keyId Y"
-```
-
-And **don't care** how keys are stored, rotated, or implemented.
-
----
-
-## Design Principles
-
-1. **Private keys hidden** - Never exposed to most callers
-2. **Crypto agility** - Suite is config, not code  
-3. **Single entry point** - Easy to audit
-4. **Idempotent operations** - Safe for retries
-5. **Minimal API surface** - Small, focused, easy to learn
-
----
-
-## Installation
-
-```bash
-npm install @smartledger/keys
-```
-
-### Supported ML-DSA Variants
-
-Choose the right security level for your use case:
-
-| Variant | NIST Level | Equivalent | Use Case |
-|---------|------------|------------|----------|
-| **ml-dsa-44** | Level 2 | AES-128 | IoT devices, high-throughput systems |
-| **ml-dsa-65** | Level 3 | AES-192 | **General purpose (recommended)** |
-| **ml-dsa-87** | Level 5 | AES-256 | High-security, long-term confidential data |
-
----
-
-## Quick Start
-
-```typescript
-import { createKeySDK } from '@smartledger/keys';
-
-// One line to get a ready-to-use SDK with ML-DSA + ECDSA suites registered
-const sdk = createKeySDK();
-
-// Create both PQ + ECDSA keys for an agent
-// Using ml-dsa-65 (Level 3) - recommended for most use cases
-const { primaryKey, secondaryKey } = await sdk.createDualSignatureKeys(
-  'agent-resonance',
-  {
-    primarySignatureSuite: 'ml-dsa-65',  // or 'ml-dsa-44', 'ml-dsa-87'
-    secondarySignatureSuite: 'bsv-ecdsa-secp256k1',
-  }
-);
-
-// Sign with both suites (private keys stay hidden)
-const message = new TextEncoder().encode('agent output');
-const { signatures } = await sdk.signWithSuites('agent-resonance', message);
-
-// Verify both signatures
-const verify = await sdk.verifyWithSuites('agent-resonance', message, signatures);
-console.log(verify.allValid); // true
-```
-
----
-
-## API Reference
-
-### Factory Helper
-
-`createKeySDK(config?)` returns a ready-to-use SDK wired with in-memory storage and the default ML-DSA + ECDSA suites. Pass your own `keyRegistry` or `suiteRegistry` to override defaults.
-
-### KeySDK Interface
-
-#### `createKey(agentId, profile, options?)`
-
-Create a new key for an agent/module.
-
-**Parameters:**
-- `agentId` (string) - Agent identifier (e.g. `'agent-resonance'`)
-- `profile` (CryptoProfile) - Which signature suites to use
-- `options` (CreateKeyOptions) - Optional expiration, usage, etc.
-
-**Returns:** `Promise<KeyRecord>` - KeyRecord with metadata and public key
-
-**Example:**
-```typescript
-const key = await sdk.createKey(
-  'agent-schema',
-  { primarySignatureSuite: 'ml-dsa-65' },  // Recommended: Level 3
-  {
-    expiresAt: new Date(Date.now() + 365 * 86400000).toISOString(), // 1 year
-    usage: ['signing'],
-  }
-);
-```
-
----
-
-#### `getKey(keyId)`
-
-Get an existing key by ID.
-
-**Parameters:**
-- `keyId` (string) - Key identifier
-
-**Returns:** `Promise<KeyRecord | null>` - KeyRecord or null if not found
-
-**Example:**
-```typescript
-const key = await sdk.getKey('agent-resonance:pk-ml-1');
-if (key) {
-  console.log(key.meta.suiteId); // 'ml-dsa-65' or 'ml-dsa-44', 'ml-dsa-87'
-  console.log(key.publicKey); // Uint8Array
-}
-```
-
----
-
-#### `signWithKey(keyId, message)`
-
-Sign a message with a key. **Private key never leaves the SDK.**
-
-**Parameters:**
-- `keyId` (string) - Which key to sign with
-- `message` (Uint8Array) - Message to sign (will be hashed internally)
-
-**Returns:** `Promise<Uint8Array>` - Signature bytes
-
-**Throws:** Error if key not found or not active
-
-**Example:**
-```typescript
-const message = new TextEncoder().encode('agent output');
-const signature = await sdk.signWithKey('agent-resonance:pk-ml-1', message);
-```
-
----
-
-#### `verifySignature(keyId, message, signature)`
-
-Verify a signature against a public key.
-
-**Parameters:**
-- `keyId` (string) - Which key to verify with
-- `message` (Uint8Array) - Original message
-- `signature` (Uint8Array) - Signature to verify
-
-**Returns:** `Promise<boolean>` - true if valid
-
-**Example:**
-```typescript
-const valid = await sdk.verifySignature(
-  'agent-resonance:pk-ml-1',
-  message,
-  signature
-);
-```
-
----
-
-#### `listKeysForAgent(agentId, activeOnly?)`
-
-List all keys for an agent.
-
-**Parameters:**
-- `agentId` (string) - Agent identifier
-- `activeOnly` (boolean) - If true, only return active keys (default: true)
-
-**Returns:** `Promise<KeyRecord[]>` - Array of KeyRecords
-
-**Example:**
-```typescript
-const keys = await sdk.listKeysForAgent('agent-schema');
-for (const key of keys) {
-  console.log(`${key.meta.keyId} (${key.meta.suiteId})`);
-}
-```
-
----
-
-#### `getActiveCryptoProfile(agentId)`
-
-Get the active crypto profile for an agent.
-
-Looks up the most recent active keys and infers the profile.
-
-**Parameters:**
-- `agentId` (string) - Agent identifier
-
-**Returns:** `Promise<CryptoProfile | null>` - CryptoProfile or null if no keys found
-
-**Example:**
-```typescript
-const profile = await sdk.getActiveCryptoProfile('agent-schema');
-console.log(profile.primarySignatureSuite); // 'ml-dsa-65'
-console.log(profile.secondarySignatureSuite); // 'bsv-ecdsa-secp256k1'
-```
-
----
-
-#### `rotateAgentKeys(agentId)`
-
-Rotate an agent's keys.
-
-Generates new keypairs for all active keys, marks old ones as rotated.
-
-**Parameters:**
-- `agentId` (string) - Agent identifier
-
-**Returns:** `Promise<KeyRecord[]>` - Array of new KeyRecords
-
-**Example:**
-```typescript
-const newKeys = await sdk.rotateAgentKeys('agent-schema');
-for (const key of newKeys) {
-  console.log(`New: ${key.meta.keyId}`);
-  console.log(`Rotated from: ${key.meta.rotatedFrom}`);
-}
-```
-
----
-
-#### `getOrCreateKey(agentId, profile, options?)`
-
-Create key if it doesn't exist, otherwise return existing.
-
-**Idempotent** key creation for agent setup.
-
-**Parameters:**
-- `agentId` (string) - Agent identifier
-- `profile` (CryptoProfile) - Crypto configuration
-- `options` (CreateKeyOptions) - Creation options
-
-**Returns:** `Promise<KeyRecord>` - KeyRecord (new or existing)
-
-**Example:**
-```typescript
-// Safe to call multiple times
-const key1 = await sdk.getOrCreateKey('agent-validator', {
-  primarySignatureSuite: 'ml-dsa-65',
-});
-
-const key2 = await sdk.getOrCreateKey('agent-validator', {
-  primarySignatureSuite: 'ml-dsa-65',
-});
-
-console.log(key1.meta.keyId === key2.meta.keyId); // true
-```
-
----
-
-#### `createDualSignatureKeys(agentId, profile, options?)`
-
-Create both primary and secondary keys in one call. Requires `profile.secondarySignatureSuite`.
-
-**Returns:** `{ primaryKey, secondaryKey }`
-
-**Example:**
-```typescript
-const { primaryKey, secondaryKey } = await sdk.createDualSignatureKeys(
-  'agent-bridge',
-  {
-    primarySignatureSuite: 'ml-dsa-65',  // Recommended
-    secondarySignatureSuite: 'bsv-ecdsa-secp256k1',
-  }
-);
-```
-
----
-
-#### `getOrCreateDualSignatureKeys(agentId, profile, options?)`
-
-Idempotent version of the above; reuses active keys when present.
-
-**Returns:** `{ primaryKey, secondaryKey }`
-
----
-
-#### `signWithSuites(agentId, message, suites?)`
-
-Sign once per suite. When `suites` is omitted, active primary + secondary are used.
-
-**Returns:** `{ signatures: Array<{ suiteId, keyId, signature }> }`
-
-**Example:**
-```typescript
-const message = new TextEncoder().encode('hybrid payload');
-const { signatures } = await sdk.signWithSuites('agent-bridge', message);
-```
-
----
-
-#### `verifyWithSuites(agentId, message, signatures)`
-
-Verify multiple signatures and get per-suite results.
-
-**Returns:** `{ results: Array<{ suiteId, keyId, valid }>, allValid: boolean }`
-
-**Example:**
-```typescript
-const verify = await sdk.verifyWithSuites('agent-bridge', message, signatures);
-console.log(verify.allValid); // true when every suite verifies
-```
----
-
----
-
-## Types
-
-### KeyRecord
-
-Public key record (safe to expose, no private key).
-
-```typescript
-interface KeyRecord {
-  meta: KeyMeta;          // Key metadata
-  publicKey: Uint8Array;  // Public key bytes
-}
-```
-
-### CreateKeyOptions
-
-Options for key creation.
-
-```typescript
-interface CreateKeyOptions {
-  expiresAt?: string;                              // ISO 8601
-  usage?: Array<'signing' | 'encryption' | 'both'>; // Default: ['signing']
-  cryptoProfileVersion?: string;                    // Default: '1.0.0'
-}
-```
-
-### CryptoProfile
-
-Per-agent/module crypto configuration.
-
-```typescript
-interface CryptoProfile {
-  primarySignatureSuite: string;     // e.g. 'ml-dsa-65' (recommended), 'ml-dsa-44', 'ml-dsa-87'
-  secondarySignatureSuite?: string;  // e.g. 'bsv-ecdsa-secp256k1' (hybrid)
-  keyEncapsulationSuite?: string;    // e.g. 'ml-kem-768' (future)
-}
-```
-
----
-
-## Usage Patterns
-
-### Single Signature (PQ-only)
-
-```typescript
-// Agent uses only ML-DSA (recommended: ml-dsa-65)
-const key = await sdk.createKey('agent-research', {
-  primarySignatureSuite: 'ml-dsa-65',  // or 'ml-dsa-44' for IoT, 'ml-dsa-87' for max security
-});
-
-const message = new TextEncoder().encode('research results');
-const signature = await sdk.signWithKey(key.meta.keyId, message);
-```
-
-### Hybrid Signature (ECDSA + PQ)
-
-```typescript
-// One call to create both keys
-await sdk.getOrCreateDualSignatureKeys('agent-bridge', {
-  primarySignatureSuite: 'ml-dsa-65',  // Balanced security (recommended)
-  secondarySignatureSuite: 'bsv-ecdsa-secp256k1',
-});
-
-// Sign with both suites
-const message = new TextEncoder().encode('bridge output');
-const { signatures } = await sdk.signWithSuites('agent-bridge', message);
-
-// Verify both signatures
-const verified = await sdk.verifyWithSuites('agent-bridge', message, signatures);
-console.log(verified.allValid); // true
-```
-
-### Agent Setup (Idempotent)
-
-```typescript
-// Safe to call on every startup
-async function setupAgent(agentId: string) {
-  const key = await sdk.getOrCreateKey(agentId, {
-    primarySignatureSuite: 'ml-dsa-65',  // Recommended default
-  }, {
-    expiresAt: new Date(Date.now() + 365 * 86400000).toISOString(),
-  });
-  
-  return key;
-}
-```
-
-### Monthly Key Rotation
-
-```typescript
-// Automated rotation job
-async function monthlyRotation() {
-  const agents = ['agent-resonance', 'agent-schema', 'agent-validator'];
-  
-  for (const agentId of agents) {
-    const newKeys = await sdk.rotateAgentKeys(agentId);
-    console.log(`✓ Rotated ${agentId}: ${newKeys.length} keys`);
-  }
-}
-```
-
----
-
-## Benefits
-
-### 🔒 Security
-
-- **Private keys hidden** - Never exposed to calling code
-- **Single audit point** - All key operations go through SDK
-- **No key leakage** - Keys stay in KeyRegistry storage
-- **Consistent hashing** - Suite-appropriate algorithms
-
-### 🔄 Crypto Agility
-
-- **Suite is config** - Change ML-DSA → Falcon without code changes
-- **Profile-driven** - CryptoProfile defines agent's crypto setup
-- **Easy migration** - Hybrid mode for ECDSA → PQ transition
-
-### 🛠️ Developer Experience
-
-- **Clean API** - 8 methods, easy to learn
-- **Idempotent** - `getOrCreateKey` safe for retries
-- **TypeScript** - Full type safety
-- **Well-tested** - 23 tests covering all scenarios
-
-### 📊 Operations
-
-- **Centralized** - One SDK for all agents
-- **Auditable** - Easy to track key operations
-- **Scalable** - Storage backends (in-memory, file, KMS)
-- **Rotation-friendly** - Built-in rotation support
-
----
-
-## Best Practices
-
-### ✅ Do
-
-- Use SDK for **all** key operations
-- Call `getOrCreateKey` for idempotent setup
-- Set expiration dates on keys
-- Rotate keys regularly (monthly/quarterly)
-- Use `signWithKey` (not direct registry access)
-
-### ❌ Don't
-
-- Expose private keys to calling code
-- Create keys manually outside SDK
-- Hard-code suite IDs in business logic
-- Skip key rotation
-
----
-
-## Integration with Existing Code
-
-### Before (Direct Registry)
-
-```typescript
-// Scattered key operations
-const suite = globalRegistry.getSuite('ml-dsa-87');
-const keypair = await suite.generateKeypair();
-await keyRegistry.registerKey('agent-1:pk-1', keypair, 'ml-dsa-87');
-
-const key = await keyRegistry.getKey('agent-1:pk-1');
-const sig = await suite.sign(key.keypair.privateKey, message);
-```
-
-### After (SDK)
-
-```typescript
-// Clean, centralized
-const key = await sdk.createKey('agent-1', {
-  primarySignatureSuite: 'ml-dsa-65',  // Choose: 'ml-dsa-44', '65', or '87'
-});
-
-const sig = await sdk.signWithKey(key.meta.keyId, message);
-```
-
----
-
-## What's Next?
-
-- **File Storage** - Persistent key storage (not just in-memory)
-- **KMS Integration** - AWS KMS, Azure Key Vault, HSM
-- **Key Backup** - Encrypted backup/recovery procedures
-- **Multi-tenant** - Isolate keys per tenant
-- **Hardware Keys** - Support for non-exportable hardware keys
-
----
-
-## Summary
-
-**`@smartledger/keys` is the single source of truth for cryptographic keys:**
-
-✅ 23 tests passing  
-✅ Private keys hidden from callers  
-✅ Crypto-agnostic API (suite is config)  
-✅ Idempotent operations  
-✅ Easy to audit  
-✅ Production-ready  
-
-**Use it for all key operations. Make crypto agility a reality.**
-
----
-
-**See Also:**
-- [Key Management Guide](../docs/KEY_MANAGEMENT_GUIDE.md) - Lower-level KeyRegistry details
-- [Algorithm Selection Guide](../docs/ALGORITHM_SELECTION_GUIDE.md) - Which suite to use?
-- [ECDSA Implementation Strategy](../docs/ECDSA_IMPLEMENTATION_STRATEGY.md) - Why Noble
-
----
-
-**Version**: 1.0.0  
-**Last Updated**: November 28, 2025
+# @smartledger/keys
+
+A key-management SDK for hybrid classical + post-quantum signing: create keys,
+sign, verify, rotate. It sits on [`@smartledger/crypto`](../crypto), which
+supplies ML-DSA-44/65/87 (FIPS 204, via `@noble/post-quantum`) and ECDSA
+secp256k1 (via `@noble/secp256k1`).
+
+**Read [Limits](#limits) before depending on it.** The only storage backend
+shipped is in-memory, and ML-DSA signatures are made over a digest rather than
+the message.
+
+## Installation
+
+```bash
+npm install @smartledger/keys
+```
+
+Node ≥ 20.19. Works in browsers through any bundler (the ESM build uses only
+Web-standard APIs). For a `<script>` tag, `dist/lumen-keys.min.js` exposes
+`window.LumenKeys`.
+
+## Quick start
+
+```typescript
+import { createKeySDK } from '@smartledger/keys';
+
+const sdk = createKeySDK(); // in-memory storage; ECDSA + ML-DSA-44/65/87
+
+const HYBRID = {
+  primarySignatureSuite: 'ml-dsa-65',
+  secondarySignatureSuite: 'bsv-ecdsa-secp256k1',
+};
+await sdk.createDualSignatureKeys('agent-resonance', HYBRID);
+
+const message = new TextEncoder().encode('agent output');
+const { signatures } = await sdk.signWithSuites('agent-resonance', message);
+
+const result = await sdk.verifyWithSuites('agent-resonance', message, signatures, {
+  requiredSuites: ['ml-dsa-65', 'bsv-ecdsa-secp256k1'],
+});
+console.log(result.allValid); // true
+```
+
+| Suite | NIST category | Public key | Signature |
+|---|---|---|---|
+| `ml-dsa-44` | 2 | 1,312 B | 2,420 B |
+| `ml-dsa-65` | 3 | 1,952 B | 3,309 B |
+| `ml-dsa-87` | 5 | 2,592 B | 4,627 B |
+| `bsv-ecdsa-secp256k1` | not post-quantum | 33 B | 64 B (compact `r‖s`, low S) |
+
+## Verifying a hybrid signature
+
+`verifyWithSuites(agentId, message, signatures, options?)` returns
+`allValid: 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 are the verifier's policy. Pass them as
+`options.requiredSuites` from your own configuration. If you omit them they
+default to the suites of the agent's currently usable keys in this SDK's
+registry. They are never taken from `signatures`: a bundle that simply leaves
+out the post-quantum signature is refused, and `missingSuites` names what is
+absent.
+
+> **If you used 3.0.x:** `verifyWithSuites` returned `allValid: true` for an
+> empty list, for a list missing a suite, and for signatures made by another
+> agent's keys. Any stored result computed by 3.0.x over an incomplete list
+> means nothing and should be recomputed.
+
+`options.keyStatus` (also on `verifySignature`) decides what is asked of the
+key's state today:
+
+| Value | Accepts |
+|---|---|
+| `'any'` | any key; the cryptographic check only (default for `verifySignature`) |
+| `'not-revoked'` | anything but revoked keys (default for `verifyWithSuites`) |
+| `'usable'` | only keys that are active and unexpired now |
+
+There is no signing-time evidence here: the SDK cannot tell whether a
+signature by a now-rotated key was made before or after the rotation. If that
+matters, timestamp the signature independently when it is made.
+
+## API
+
+`createKeySDK(config?)` returns a `KeySDK`. Pass `keyRegistry` or
+`suiteRegistry` to override the defaults.
+
+| Method | Notes |
+|---|---|
+| `createKey(agentId, profile, options?)` | `options`: `expiresAt` (ISO 8601, validated), `usage`, `derivationContext` |
+| `getKey(keyId)` | Returns a copy; editing it changes nothing in the registry |
+| `signWithKey(keyId, message)` | Throws if the key is not active, is past `expiresAt`, or is not a signing key |
+| `verifySignature(keyId, message, signature, options?)` | Cryptographic check; `options.keyStatus` |
+| `listKeysForAgent(agentId, activeOnly = true)` | Exact ownership (see below) |
+| `getActiveCryptoProfile(agentId)` | Inferred from active keys |
+| `rotateAgentKeys(agentId, options?)` | See [Rotation](#rotation) |
+| `getOrCreateKey(agentId, profile, options?)` | Concurrent calls on one SDK instance share one creation |
+| `createDualSignatureKeys(agentId, profile, options?)` | Two different suites required |
+| `getOrCreateDualSignatureKeys(agentId, profile, options?)` | Idempotent form |
+| `signWithSuites(agentId, message, suites?)` | One signature per suite |
+| `verifyWithSuites(agentId, message, signatures, options?)` | See above |
+| `generateMnemonic(strength?)` | BIP39, 128 or 256 bits |
+| `createKeyFromMnemonic(agentId, profile, mnemonic, path?, passphrase?, options?)` | Mnemonic words and checksum are validated |
+| `getCapabilities(suiteId)`, `getSuitesWithCapability(capability)` | |
+
+`DefaultKeySDK` additionally has `createWalletKey` and the deprecated
+`createBitcoinWalletKey` (see [Wallet keys](#wallet-keys)).
+
+**Key IDs and ownership.** A key ID is `<agentId>:pk-<suite>-<n>`. A key
+belongs to the agent named by everything before its last `:`, so agent IDs may
+themselves contain colons (`did:web:example.com`) and agent `a` never sees the
+keys of agent `a:b`. `agentIdOfKey(keyId)` is exported.
+
+**Registration never overwrites.** The registry throws `KeyAlreadyExistsError`
+rather than replace the key behind an existing ID. If two SDK instances share
+a storage backend, the loser of an ID race re-reads the counter and takes the
+next ID.
+
+## Rotation
+
+```typescript
+const newKeys = await sdk.rotateAgentKeys('agent-schema');
+```
+
+- Each new key gets its predecessor's **lifetime** again, counted from the
+  rotation. Pass `{ expiresAt }` for a specific instant or `{ expiresAt: null }`
+  for none.
+- A key derived from a mnemonic cannot be re-derived, because the SDK does not
+  keep seeds. By default the call refuses, before changing anything. Pass
+  `{ derivedKeys: 'skip' }` to rotate the other keys, or
+  `{ derivedKeys: 'randomize' }` to replace derived keys with random ones that
+  the mnemonic will not recover.
+- All replacements are generated before any is committed. The commits are one
+  registry operation per key, not a transaction.
+- Revoked and already-rotated keys cannot be rotated.
+
+## Wallet keys
+
+```typescript
+const key = await sdk.createWalletKey('agent-wallet', mnemonic, {
+  coinType: 236, // SLIP-44: Bitcoin SV. Bitcoin (BTC) is 0.
+  account: 0,
+  index: 0,
+});
+// m/44'/236'/0'/0/0
+```
+
+`coinType` is required and has no default, because it decides which wallets
+will find the key again.
+
+`createBitcoinWalletKey` still derives at `m/44'/0'/…` (BTC), exactly as
+before: **upgrading does not move any existing key.** A Bitcoin SV wallet
+restoring the same mnemonic looks under coin type 236 and will not find those
+keys, which is why the method is deprecated in favour of `createWalletKey`.
+
+The ECDSA suite produces 64-byte compact signatures over a single SHA-256.
+That suits notarisation-style signing. It is **not** a transaction signature:
+Bitcoin-family transactions need DER plus a sighash byte over a double-SHA-256
+sighash preimage, which this SDK does not build.
+
+## Limits
+
+- **Storage is in-memory only.** Private keys are held unencrypted in process
+  memory and are lost on exit. There is no file, KMS or HSM backend in this
+  package; implement `KeyStorage` for one. A backend shared between processes
+  should implement `storeIfAbsent` atomically.
+- **Private keys are reachable.** `signWithKey` keeps them out of the common
+  path, but anyone holding the `KeyRegistry` can call `getKey`. This is an API
+  convenience, not an isolation boundary.
+- **ML-DSA signs a digest.** The SDK signs `SHA3-256(message)` with pure
+  ML-DSA and an empty context string (and ECDSA signs `SHA-256(message)`).
+  A standard FIPS 204 verifier must therefore be given the 32-byte digest as
+  its message. The 256-bit digest also bounds collision resistance at about
+  128 bits whatever the ML-DSA level, which matters where an attacker can
+  choose the messages that get signed. Signing the message directly (or
+  HashML-DSA with a context string) is planned for the next major version,
+  because it changes every signature.
+- **No domain separation between uses.** A key that signs for several purposes
+  can have a signature replayed from one to another. Put the purpose in the
+  message.
+- **`getOrCreateKey` across instances.** Two SDK instances or processes on one
+  backend can each create a key; this needs a lock in the backend.
+- **Dependencies.** `@noble/post-quantum` is pre-1.0 and, unlike the other
+  noble libraries used here, has not had an independent audit.
+
+## Development
+
+```bash
+npm run build:all   # CJS, ESM and the browser bundle
+npm test
+```
+
+`test/hardening.test.ts` holds the regression tests for the defects fixed in
+3.1.0; see the repository CHANGELOG.
+
+## License
+
+MIT