agentvault 1.0.2 → 1.0.5

package/dist/src/wallet/wallet-crypto.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Wallet Crypto Module
+ *
+ * Provides cryptographic primitives for wallet key generation and at-rest
+ * encryption using industry-standard algorithms:
+ *
+ *   - secp256k1 ECDSA (Ethereum / Polkadot) via @noble/curves
+ *   - Ed25519 EdDSA (Solana / ICP / Arweave)  via @noble/curves
+ *   - AES-256-GCM authenticated encryption for private keys / mnemonics
+ *   - PBKDF2-SHA256 (210 000 iterations) for storage-key derivation
+ *
+ * Private keys and mnemonics are NEVER stored in plaintext.  When a
+ * caller supplies an encryptionKey (the wallet's BIP39 mnemonic) the
+ * sensitive fields are encrypted into an EncryptedKeyBundle before the
+ * wallet is written to disk.
+ */
+import type { EncryptedCiphertext, WalletData } from './types.js';
+/**
+ * Derive a secp256k1 keypair from a 32-byte seed.
+ *
+ * Uses @noble/curves/secp256k1 – the same underlying library used by ethers
+ * and most modern JS wallets.  The uncompressed public key (65 bytes,
+ * 0x04 prefix) is returned so callers can choose their own encoding.
+ *
+ * @param seed - 32 bytes of key material (e.g. from BIP32 derivation)
+ */
+export declare function secp256k1KeypairFromSeed(seed: Uint8Array): {
+    privateKey: Uint8Array;
+    publicKeyUncompressed: Uint8Array;
+    publicKeyCompressed: Uint8Array;
+};
+/**
+ * Derive an Ed25519 keypair from a 32-byte seed.
+ *
+ * Uses @noble/curves/ed25519.  The private key is the raw 32-byte seed;
+ * the public key is the 32-byte Ed25519 point.
+ *
+ * @param seed - 32 bytes of key material
+ */
+export declare function ed25519KeypairFromSeed(seed: Uint8Array): {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+};
+/**
+ * Derive a 32-byte AES-256-GCM key from a BIP39 mnemonic and a random salt
+ * using PBKDF2-SHA256.
+ *
+ * The per-wallet salt ensures that two wallets encrypted with the same
+ * mnemonic produce independent keys, preventing cross-wallet key reuse.
+ *
+ * @param mnemonic - BIP39 mnemonic (the wallet owner's seed phrase)
+ * @param salt     - 32-byte random per-wallet salt (stored alongside ciphertext)
+ */
+export declare function deriveStorageKey(mnemonic: string, salt: Buffer): Buffer;
+/**
+ * Encrypt a UTF-8 plaintext string with AES-256-GCM.
+ *
+ * A fresh 12-byte IV is generated for every call.  The authentication tag
+ * is stored alongside the ciphertext so that any tampering is detected on
+ * decryption.
+ *
+ * @param plaintext - The string to encrypt (private key hex or mnemonic)
+ * @param key       - 32-byte AES key (output of deriveStorageKey)
+ */
+export declare function encryptSecret(plaintext: string, key: Buffer): EncryptedCiphertext;
+/**
+ * Decrypt an AES-256-GCM ciphertext produced by encryptSecret.
+ *
+ * Throws if the authentication tag does not match (tamper detection).
+ *
+ * @param encrypted - EncryptedCiphertext produced by encryptSecret
+ * @param key       - 32-byte AES key (must match the key used for encryption)
+ */
+export declare function decryptSecret(encrypted: EncryptedCiphertext, key: Buffer): string;
+/**
+ * Encrypt a wallet's sensitive fields (privateKey and/or mnemonic) using
+ * AES-256-GCM with a key derived from the supplied mnemonic + a fresh
+ * random salt.
+ *
+ * The returned wallet has:
+ *   - privateKey  set to undefined
+ *   - mnemonic    set to undefined
+ *   - encryptedSecrets populated with the ciphertext bundle
+ *
+ * The in-memory wallet object passed in is not mutated.
+ *
+ * @param wallet   - Wallet whose secrets should be encrypted
+ * @param mnemonic - BIP39 mnemonic used as key-derivation material
+ */
+export declare function encryptWalletSecrets(wallet: WalletData, mnemonic: string): WalletData;
+/**
+ * Decrypt a wallet's EncryptedKeyBundle back into plaintext fields.
+ *
+ * If the wallet has no encryptedSecrets the wallet is returned unchanged.
+ * Throws if the mnemonic is wrong (AES-GCM authentication will fail).
+ *
+ * @param wallet   - Wallet with encryptedSecrets populated
+ * @param mnemonic - BIP39 mnemonic used as key-derivation material
+ */
+export declare function decryptWalletSecrets(wallet: WalletData, mnemonic: string): WalletData;
+//# sourceMappingURL=wallet-crypto.d.ts.map

package/dist/src/wallet/wallet-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-crypto.d.ts","sourceRoot":"","sources":["../../../src/wallet/wallet-crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAsB,UAAU,EAAE,MAAM,YAAY,CAAC;AAsBtF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG;IAC1D,UAAU,EAAE,UAAU,CAAC;IACvB,qBAAqB,EAAE,UAAU,CAAC;IAClC,mBAAmB,EAAE,UAAU,CAAC;CACjC,CAKA;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,GAAG;IACxD,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,UAAU,CAAC;CACvB,CAIA;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAcjF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAcjF;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAsBrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAmBrF"}

package/dist/src/wallet/wallet-crypto.js

@@ -0,0 +1,185 @@
+/**
+ * Wallet Crypto Module
+ *
+ * Provides cryptographic primitives for wallet key generation and at-rest
+ * encryption using industry-standard algorithms:
+ *
+ *   - secp256k1 ECDSA (Ethereum / Polkadot) via @noble/curves
+ *   - Ed25519 EdDSA (Solana / ICP / Arweave)  via @noble/curves
+ *   - AES-256-GCM authenticated encryption for private keys / mnemonics
+ *   - PBKDF2-SHA256 (210 000 iterations) for storage-key derivation
+ *
+ * Private keys and mnemonics are NEVER stored in plaintext.  When a
+ * caller supplies an encryptionKey (the wallet's BIP39 mnemonic) the
+ * sensitive fields are encrypted into an EncryptedKeyBundle before the
+ * wallet is written to disk.
+ */
+import * as crypto from 'node:crypto';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { ed25519 } from '@noble/curves/ed25519';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** PBKDF2 iteration count – OWASP 2023 recommendation for SHA-256 */
+const PBKDF2_ITERATIONS = 210_000;
+/** AES-256-GCM key length in bytes */
+const AES_KEY_BYTES = 32;
+/** AES-256-GCM IV length in bytes */
+const GCM_IV_BYTES = 12;
+/** PBKDF2 salt length in bytes */
+const SALT_BYTES = 32;
+// ---------------------------------------------------------------------------
+// Key-generation helpers (exported for use in key-derivation.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Derive a secp256k1 keypair from a 32-byte seed.
+ *
+ * Uses @noble/curves/secp256k1 – the same underlying library used by ethers
+ * and most modern JS wallets.  The uncompressed public key (65 bytes,
+ * 0x04 prefix) is returned so callers can choose their own encoding.
+ *
+ * @param seed - 32 bytes of key material (e.g. from BIP32 derivation)
+ */
+export function secp256k1KeypairFromSeed(seed) {
+    const privateKey = seed.slice(0, 32);
+    const publicKeyUncompressed = secp256k1.getPublicKey(privateKey, false);
+    const publicKeyCompressed = secp256k1.getPublicKey(privateKey, true);
+    return { privateKey, publicKeyUncompressed, publicKeyCompressed };
+}
+/**
+ * Derive an Ed25519 keypair from a 32-byte seed.
+ *
+ * Uses @noble/curves/ed25519.  The private key is the raw 32-byte seed;
+ * the public key is the 32-byte Ed25519 point.
+ *
+ * @param seed - 32 bytes of key material
+ */
+export function ed25519KeypairFromSeed(seed) {
+    const privateKey = seed.slice(0, 32);
+    const publicKey = ed25519.getPublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+// ---------------------------------------------------------------------------
+// Storage-key derivation
+// ---------------------------------------------------------------------------
+/**
+ * Derive a 32-byte AES-256-GCM key from a BIP39 mnemonic and a random salt
+ * using PBKDF2-SHA256.
+ *
+ * The per-wallet salt ensures that two wallets encrypted with the same
+ * mnemonic produce independent keys, preventing cross-wallet key reuse.
+ *
+ * @param mnemonic - BIP39 mnemonic (the wallet owner's seed phrase)
+ * @param salt     - 32-byte random per-wallet salt (stored alongside ciphertext)
+ */
+export function deriveStorageKey(mnemonic, salt) {
+    return crypto.pbkdf2Sync(mnemonic, salt, PBKDF2_ITERATIONS, AES_KEY_BYTES, 'sha256');
+}
+// ---------------------------------------------------------------------------
+// AES-256-GCM encrypt / decrypt
+// ---------------------------------------------------------------------------
+/**
+ * Encrypt a UTF-8 plaintext string with AES-256-GCM.
+ *
+ * A fresh 12-byte IV is generated for every call.  The authentication tag
+ * is stored alongside the ciphertext so that any tampering is detected on
+ * decryption.
+ *
+ * @param plaintext - The string to encrypt (private key hex or mnemonic)
+ * @param key       - 32-byte AES key (output of deriveStorageKey)
+ */
+export function encryptSecret(plaintext, key) {
+    const iv = crypto.randomBytes(GCM_IV_BYTES);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    return {
+        iv: iv.toString('hex'),
+        ciphertext: ciphertext.toString('hex'),
+        tag: tag.toString('hex'),
+    };
+}
+/**
+ * Decrypt an AES-256-GCM ciphertext produced by encryptSecret.
+ *
+ * Throws if the authentication tag does not match (tamper detection).
+ *
+ * @param encrypted - EncryptedCiphertext produced by encryptSecret
+ * @param key       - 32-byte AES key (must match the key used for encryption)
+ */
+export function decryptSecret(encrypted, key) {
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(encrypted.iv, 'hex'));
+    decipher.setAuthTag(Buffer.from(encrypted.tag, 'hex'));
+    const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(encrypted.ciphertext, 'hex')),
+        decipher.final(),
+    ]);
+    return plaintext.toString('utf8');
+}
+// ---------------------------------------------------------------------------
+// Wallet-level encrypt / decrypt
+// ---------------------------------------------------------------------------
+/**
+ * Encrypt a wallet's sensitive fields (privateKey and/or mnemonic) using
+ * AES-256-GCM with a key derived from the supplied mnemonic + a fresh
+ * random salt.
+ *
+ * The returned wallet has:
+ *   - privateKey  set to undefined
+ *   - mnemonic    set to undefined
+ *   - encryptedSecrets populated with the ciphertext bundle
+ *
+ * The in-memory wallet object passed in is not mutated.
+ *
+ * @param wallet   - Wallet whose secrets should be encrypted
+ * @param mnemonic - BIP39 mnemonic used as key-derivation material
+ */
+export function encryptWalletSecrets(wallet, mnemonic) {
+    const salt = crypto.randomBytes(SALT_BYTES);
+    const key = deriveStorageKey(mnemonic, salt);
+    const bundle = {
+        version: 1,
+        salt: salt.toString('hex'),
+    };
+    if (wallet.privateKey) {
+        bundle.privateKey = encryptSecret(wallet.privateKey, key);
+    }
+    if (wallet.mnemonic) {
+        bundle.mnemonic = encryptSecret(wallet.mnemonic, key);
+    }
+    return {
+        ...wallet,
+        privateKey: undefined,
+        mnemonic: undefined,
+        encryptedSecrets: bundle,
+    };
+}
+/**
+ * Decrypt a wallet's EncryptedKeyBundle back into plaintext fields.
+ *
+ * If the wallet has no encryptedSecrets the wallet is returned unchanged.
+ * Throws if the mnemonic is wrong (AES-GCM authentication will fail).
+ *
+ * @param wallet   - Wallet with encryptedSecrets populated
+ * @param mnemonic - BIP39 mnemonic used as key-derivation material
+ */
+export function decryptWalletSecrets(wallet, mnemonic) {
+    if (!wallet.encryptedSecrets) {
+        return wallet;
+    }
+    const { encryptedSecrets } = wallet;
+    const salt = Buffer.from(encryptedSecrets.salt, 'hex');
+    const key = deriveStorageKey(mnemonic, salt);
+    const decrypted = {};
+    if (encryptedSecrets.privateKey) {
+        decrypted.privateKey = decryptSecret(encryptedSecrets.privateKey, key);
+    }
+    if (encryptedSecrets.mnemonic) {
+        decrypted.mnemonic = decryptSecret(encryptedSecrets.mnemonic, key);
+    }
+    return { ...wallet, ...decrypted };
+}
+//# sourceMappingURL=wallet-crypto.js.map

package/dist/src/wallet/wallet-crypto.js.map

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

package/dist/src/wallet/wallet-manager.d.ts

@@ -5,7 +5,7 @@
  * Handles wallet creation, storage, and retrieval with per-agent isolation.
  * Phase 5A: Added canister sync functionality.
  */
-import type { WalletData, WalletCreationOptions, WalletStorageOptions } from './types.js';
+import type { WalletData, WalletCreationOptions, WalletStorageOptions, HsmWalletCreationOptions } from './types.js';
 /**
  * Create a new wallet
  *
@@ -23,7 +23,7 @@ export declare function createWallet(options: WalletCreationOptions, storageOpti
  * @param storageOptions - Storage options
  * @returns Imported wallet data
  */
-export declare function importWalletFromPrivateKey(agentId: string, chain: string, privateKey: string, storageOptions?: WalletStorageOptions): WalletData;
+export declare function importWalletFromPrivateKey(agentId: string, chain: string, privateKey: string, storageOptions?: WalletStorageOptions, chainMetadata?: Record<string, unknown>): WalletData;
 /**
  * Import wallet from seed phrase
  *
@@ -34,7 +34,7 @@ export declare function importWalletFromPrivateKey(agentId: string, chain: strin
  * @param storageOptions - Storage options
  * @returns Imported wallet data
  */
-export declare function importWalletFromSeed(agentId: string, chain: string, seedPhrase: string, derivationPath?: string, storageOptions?: WalletStorageOptions): WalletData;
+export declare function importWalletFromSeed(agentId: string, chain: string, seedPhrase: string, derivationPath?: string, storageOptions?: WalletStorageOptions, chainMetadata?: Record<string, unknown>): WalletData;
 /**
  * Import wallet from mnemonic
  *
@@ -45,7 +45,7 @@ export declare function importWalletFromSeed(agentId: string, chain: string, see
  * @param storageOptions - Storage options
  * @returns Imported wallet data
  */
-export declare function importWalletFromMnemonic(agentId: string, chain: string, mnemonic: string, derivationPath?: string, storageOptions?: WalletStorageOptions): WalletData;
+export declare function importWalletFromMnemonic(agentId: string, chain: string, mnemonic: string, derivationPath?: string, storageOptions?: WalletStorageOptions, chainMetadata?: Record<string, unknown>): WalletData;
 /**
  * Generate new wallet
  *
@@ -126,6 +126,26 @@ export declare function clearCachedConnection(agentId: string, walletId: string)
  * @returns True if valid
  */
 export declare function validateSeedPhraseWrapper(seedPhrase: string): boolean;
+/**
+ * Create a wallet whose private key is generated and permanently stored inside
+ * a hardware secure element (Ledger) or Trusted Execution Environment (SGX).
+ *
+ * Security guarantees:
+ *   - The private key is generated inside the secure boundary.
+ *   - The BIP39 mnemonic never exists in this process (Ledger) or is sealed
+ *     inside the enclave (SGX).
+ *   - Only the public key and chain address cross the hardware boundary.
+ *   - The returned WalletData has privateKey=undefined and mnemonic=undefined.
+ *
+ * @param options        - HSM-specific wallet creation options.
+ * @param storageOptions - Where / how to persist the wallet metadata.
+ * @returns WalletData with address/publicKey populated, secrets absent.
+ *
+ * @throws {HsmNotAvailableError}   when device / daemon is unreachable.
+ * @throws {HsmCurveUnsupportedError} when the chain's curve is unsupported.
+ * @throws {HsmOperationError}      on device-level failures.
+ */
+export declare function createWalletWithHsm(options: HsmWalletCreationOptions, storageOptions?: WalletStorageOptions): Promise<WalletData>;
 /**
  * Sync wallet to canister (register wallet metadata)
  *

package/dist/src/wallet/wallet-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-manager.d.ts","sourceRoot":"","sources":["../../../src/wallet/wallet-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAsDpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,qBAAqB,EAC9B,cAAc,GAAE,oBAAyB,GACxC,UAAU,CA+BZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,cAAc,GAAE,oBAAyB,EACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,UAAU,CAQZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,MAAM,EACvB,cAAc,GAAE,oBAAyB,EACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,UAAU,CASZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,cAAc,CAAC,EAAE,MAAM,EACvB,cAAc,GAAE,oBAAyB,EACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,UAAU,CASZ;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,oBAAyB,GACxC,UAAU,CAGZ;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,cAAc,GAAE,oBAAyB,GACxC,UAAU,GAAG,IAAI,CAEnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,oBAAyB,GACxC,MAAM,EAAE,CAEV;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,cAAc,GAAE,oBAAyB,GACxC,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,cAAc,GAAE,oBAAyB,GACxC,IAAI,CAKN;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,oBAAyB,GACxC,IAAI,CAON;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,GAAG,GACZ,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,GAAG,CAEL;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAErE;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,wBAAwB,EACjC,cAAc,GAAE,oBAAyB,GACxC,OAAO,CAAC,UAAU,CAAC,CA+CrB;AAID;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyCtE;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,CAAC,CAkB9E;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,GAAG,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC,CAoCD;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,EAAE,CAAC,CAchB;AAED;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB/C;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,EACzC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAiC/C"}

package/dist/src/wallet/wallet-manager.js

@@ -90,12 +90,13 @@ export function createWallet(options, storageOptions = {}) {
  * @param storageOptions - Storage options
  * @returns Imported wallet data
  */
-export function importWalletFromPrivateKey(agentId, chain, privateKey, storageOptions = {}) {
+export function importWalletFromPrivateKey(agentId, chain, privateKey, storageOptions = {}, chainMetadata) {
     return createWallet({
         agentId,
         chain: chain,
         method: 'private-key',
         privateKey,
+        chainMetadata,
     }, storageOptions);
 }
 /**
@@ -108,13 +109,14 @@ export function importWalletFromPrivateKey(agentId, chain, privateKey, storageOp
  * @param storageOptions - Storage options
  * @returns Imported wallet data
  */
-export function importWalletFromSeed(agentId, chain, seedPhrase, derivationPath, storageOptions = {}) {
+export function importWalletFromSeed(agentId, chain, seedPhrase, derivationPath, storageOptions = {}, chainMetadata) {
     return createWallet({
         agentId,
         chain: chain,
         method: 'seed',
         seedPhrase,
         derivationPath,
+        chainMetadata,
     }, storageOptions);
 }
 /**
@@ -127,13 +129,14 @@ export function importWalletFromSeed(agentId, chain, seedPhrase, derivationPath,
  * @param storageOptions - Storage options
  * @returns Imported wallet data
  */
-export function importWalletFromMnemonic(agentId, chain, mnemonic, derivationPath, storageOptions = {}) {
+export function importWalletFromMnemonic(agentId, chain, mnemonic, derivationPath, storageOptions = {}, chainMetadata) {
     return createWallet({
         agentId,
         chain: chain,
         method: 'mnemonic',
         seedPhrase: mnemonic,
         derivationPath,
+        chainMetadata,
     }, storageOptions);
 }
 /**
@@ -243,6 +246,70 @@ export function clearCachedConnection(agentId, walletId) {
 export function validateSeedPhraseWrapper(seedPhrase) {
     return validateSeedPhrase(seedPhrase);
 }
+// ==================== HSM / TEE Keygen ====================
+/**
+ * Create a wallet whose private key is generated and permanently stored inside
+ * a hardware secure element (Ledger) or Trusted Execution Environment (SGX).
+ *
+ * Security guarantees:
+ *   - The private key is generated inside the secure boundary.
+ *   - The BIP39 mnemonic never exists in this process (Ledger) or is sealed
+ *     inside the enclave (SGX).
+ *   - Only the public key and chain address cross the hardware boundary.
+ *   - The returned WalletData has privateKey=undefined and mnemonic=undefined.
+ *
+ * @param options        - HSM-specific wallet creation options.
+ * @param storageOptions - Where / how to persist the wallet metadata.
+ * @returns WalletData with address/publicKey populated, secrets absent.
+ *
+ * @throws {HsmNotAvailableError}   when device / daemon is unreachable.
+ * @throws {HsmCurveUnsupportedError} when the chain's curve is unsupported.
+ * @throws {HsmOperationError}      on device-level failures.
+ */
+export async function createWalletWithHsm(options, storageOptions = {}) {
+    const { createHsmProvider } = await import('./hsm/index.js');
+    const { getDefaultDerivationPath } = await import('./key-derivation.js');
+    // Determine curve from chain
+    const chain = options.chain.toLowerCase();
+    const isEd25519Chain = ['solana', 'icp', 'arweave'].includes(chain);
+    const curve = isEd25519Chain ? 'ed25519' : 'secp256k1';
+    const derivationPath = options.derivationPath ?? getDefaultDerivationPath(chain);
+    let provider = null;
+    try {
+        provider = await createHsmProvider(options.hsmBackend, options.hsmOptions ?? {});
+        const pubKeyResult = await provider.getPublicKey(derivationPath, curve);
+        const deviceId = await provider.deviceId();
+        const walletData = {
+            id: options.walletId ?? generateWalletId(),
+            agentId: options.agentId,
+            chain: options.chain,
+            address: pubKeyResult.address,
+            // No privateKey or mnemonic – they stay inside the hardware boundary.
+            privateKey: undefined,
+            mnemonic: undefined,
+            seedDerivationPath: derivationPath,
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            creationMethod: 'hsm',
+            chainMetadata: {
+                hsm: {
+                    backend: options.hsmBackend,
+                    deviceId,
+                    derivationPath,
+                    curve,
+                    createdAt: new Date().toISOString(),
+                    publicKeyHex: pubKeyResult.publicKeyHex,
+                },
+            },
+        };
+        saveWallet(walletData, storageOptions);
+        return walletData;
+    }
+    finally {
+        if (provider)
+            await provider.close();
+    }
+}
 // ==================== Phase 5A: Canister Sync Functions ====================
 /**
  * Sync wallet to canister (register wallet metadata)

package/dist/src/wallet/wallet-manager.js.map

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

package/dist/src/wallet/wallet-storage.d.ts

@@ -37,19 +37,27 @@ export declare function getWalletFilePath(agentId: string, walletId: string, opt
  */
 export declare function ensureWalletDirectories(agentId: string, options?: WalletStorageOptions): void;
 /**
- * Save wallet to encrypted storage
+ * Save wallet to storage, encrypting private keys and mnemonics with
+ * AES-256-GCM when options.encryptionKey (a BIP39 mnemonic) is supplied.
  *
- * @param wallet - Wallet data to save
- * @param options - Storage options
+ * When encryption is active the on-disk CBOR file will contain an
+ * `encryptedSecrets` bundle and the plaintext `privateKey` / `mnemonic`
+ * fields will be absent, ensuring no sensitive material is committed to
+ * the canister or filesystem in cleartext.
+ *
+ * @param wallet  - Wallet data to save
+ * @param options - Storage options; supply `encryptionKey` to enable at-rest
+ *                  encryption of private keys / mnemonics
  */
 export declare function saveWallet(wallet: WalletData, options?: WalletStorageOptions): void;
 /**
- * Load wallet from storage
+ * Load wallet from storage, decrypting secrets when options.encryptionKey
+ * is supplied and the wallet contains an encrypted bundle.
  *
- * @param agentId - Agent ID
+ * @param agentId  - Agent ID
  * @param walletId - Wallet ID
- * @param options - Storage options
- * @returns Loaded wallet data or null if not found
+ * @param options  - Storage options; supply `encryptionKey` to decrypt secrets
+ * @returns Loaded (and optionally decrypted) wallet data, or null if not found
  */
 export declare function loadWallet(agentId: string, walletId: string, options?: WalletStorageOptions): WalletData | null;
 /**

package/dist/src/wallet/wallet-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-storage.d.ts","sourceRoot":"","sources":["../../../src/wallet/wallet-storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiBH,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAG3E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAMN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAiBN;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,UAAU,GAAG,IAAI,CAoBnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAON;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,MAAM,EAAE,CAiBV;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,EAAE,CAkBvE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC;IACD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,IAAI,CAAC;IACf,OAAO,EAAE,IAAI,CAAC;CACf,GAAG,IAAI,CAcP;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAoBN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAmBN;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,IAAI,CAaN;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAmBR"}

package/dist/src/wallet/wallet-storage.js

@@ -7,7 +7,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { serializeWallet, deserializeWallet, validateCborData, } from './cbor-serializer.js';
+import { serializeWallet, deserializeWallet, } from './cbor-serializer.js';
+import { encryptWalletSecrets, decryptWalletSecrets, } from './wallet-crypto.js';
+import { sanitizePathPart, atomicWriteFileSync, } from '../utils/path-validation.js';
 /**
  * Get base directory for wallet storage
  *
@@ -27,7 +29,8 @@ export function getWalletBaseDir(options = {}) {
  */
 export function getAgentWalletDir(agentId, options = {}) {
     const baseDir = getWalletBaseDir(options);
-    return path.join(baseDir, agentId);
+    // SEC-12: reject `..`, separators, NUL, etc. before joining
+    return path.join(baseDir, sanitizePathPart(agentId));
 }
 /**
  * Get wallet file path
@@ -39,7 +42,8 @@ export function getAgentWalletDir(agentId, options = {}) {
  */
 export function getWalletFilePath(agentId, walletId, options = {}) {
     const agentDir = getAgentWalletDir(agentId, options);
-    return path.join(agentDir, `${walletId}.wallet`);
+    // SEC-12: walletId is also user-supplied
+    return path.join(agentDir, `${sanitizePathPart(walletId)}.wallet`);
 }
 /**
  * Ensure wallet directories exist
@@ -54,28 +58,40 @@ export function ensureWalletDirectories(agentId, options = {}) {
     }
 }
 /**
- * Save wallet to encrypted storage
+ * Save wallet to storage, encrypting private keys and mnemonics with
+ * AES-256-GCM when options.encryptionKey (a BIP39 mnemonic) is supplied.
  *
- * @param wallet - Wallet data to save
- * @param options - Storage options
+ * When encryption is active the on-disk CBOR file will contain an
+ * `encryptedSecrets` bundle and the plaintext `privateKey` / `mnemonic`
+ * fields will be absent, ensuring no sensitive material is committed to
+ * the canister or filesystem in cleartext.
+ *
+ * @param wallet  - Wallet data to save
+ * @param options - Storage options; supply `encryptionKey` to enable at-rest
+ *                  encryption of private keys / mnemonics
  */
 export function saveWallet(wallet, options = {}) {
     // Ensure directories exist
     ensureWalletDirectories(wallet.agentId, options);
+    // Encrypt sensitive fields when a key is available
+    const walletToStore = options.encryptionKey
+        ? encryptWalletSecrets(wallet, options.encryptionKey)
+        : wallet;
     // Serialize wallet to CBOR
-    const serialized = serializeWallet(wallet);
+    const serialized = serializeWallet(walletToStore);
     // Get wallet file path
     const walletPath = getWalletFilePath(wallet.agentId, wallet.id, options);
-    // Write wallet file
-    fs.writeFileSync(walletPath, Buffer.from(serialized));
+    // SEC-17: atomic write so a crash mid-flight doesn't corrupt the wallet
+    atomicWriteFileSync(walletPath, Buffer.from(serialized), { mode: 0o600 });
 }
 /**
- * Load wallet from storage
+ * Load wallet from storage, decrypting secrets when options.encryptionKey
+ * is supplied and the wallet contains an encrypted bundle.
  *
- * @param agentId - Agent ID
+ * @param agentId  - Agent ID
  * @param walletId - Wallet ID
- * @param options - Storage options
- * @returns Loaded wallet data or null if not found
+ * @param options  - Storage options; supply `encryptionKey` to decrypt secrets
+ * @returns Loaded (and optionally decrypted) wallet data, or null if not found
  */
 export function loadWallet(agentId, walletId, options = {}) {
     const walletPath = getWalletFilePath(agentId, walletId, options);
@@ -85,12 +101,12 @@ export function loadWallet(agentId, walletId, options = {}) {
     }
     // Read wallet file
     const data = fs.readFileSync(walletPath);
-    // Validate CBOR data
-    if (!validateCborData(new Uint8Array(data))) {
-        throw new Error(`Invalid wallet data: ${walletId}`);
-    }
-    // Deserialize wallet
+    // Deserialize wallet (validation is done inside deserializeWallet)
     const wallet = deserializeWallet(new Uint8Array(data));
+    // Decrypt secrets when a key is present
+    if (options.encryptionKey && wallet.encryptedSecrets) {
+        return decryptWalletSecrets(wallet, options.encryptionKey);
+    }
     return wallet;
 }
 /**