navio-sdk 0.1.0 → 0.1.3

package/dist/index.d.mts

@@ -167,6 +167,10 @@ declare class KeyManager {
     private timeFirstKey;
     private fViewKeyDefined;
     private fSpendKeyDefined;
+    private encrypted;
+    private encryptionSalt;
+    private passwordVerificationHash;
+    private encryptionKey;
     /**
      * Check if HD is enabled (has a seed)
      * @returns True if HD is enabled
@@ -177,6 +181,92 @@ declare class KeyManager {
      * @returns True if HD is enabled
      */
     canGenerateKeys(): boolean;
+    /**
+     * Check if the wallet is encrypted
+     * @returns True if the wallet has been encrypted with a password
+     */
+    isEncrypted(): boolean;
+    /**
+     * Check if the wallet is unlocked (decryption key is cached)
+     * @returns True if the wallet is unlocked and can access private keys
+     */
+    isUnlocked(): boolean;
+    /**
+     * Set a password to encrypt the wallet
+     * This encrypts all private keys and stores them in encrypted form
+     *
+     * @param password - The password to encrypt the wallet with
+     * @throws Error if wallet is already encrypted
+     */
+    setPassword(password: string): Promise<void>;
+    /**
+     * Unlock an encrypted wallet with the password
+     * This derives the encryption key and caches it for decrypting private keys
+     *
+     * @param password - The wallet password
+     * @returns True if the password is correct and wallet is unlocked
+     */
+    unlock(password: string): Promise<boolean>;
+    /**
+     * Lock the wallet, clearing the cached encryption key and unencrypted keys
+     * After locking, private keys cannot be accessed without unlocking again
+     */
+    lock(): void;
+    /**
+     * Change the wallet password
+     *
+     * @param oldPassword - The current password
+     * @param newPassword - The new password
+     * @returns True if password was changed successfully
+     * @throws Error if wallet is not encrypted or old password is incorrect
+     */
+    changePassword(oldPassword: string, newPassword: string): Promise<boolean>;
+    /**
+     * Get encryption parameters for storage
+     * @returns Encryption salt and verification hash, or null if not encrypted
+     */
+    getEncryptionParams(): {
+        salt: string;
+        verificationHash: string;
+    } | null;
+    /**
+     * Set encryption parameters from storage (for loading encrypted wallet)
+     * @param salt - Hex-encoded salt
+     * @param verificationHash - Hex-encoded verification hash
+     */
+    setEncryptionParams(salt: string, verificationHash: string): void;
+    /**
+     * Get key storage statistics (for testing/debugging)
+     * @returns Object with counts of plain and encrypted keys
+     */
+    getKeyStats(): {
+        plainKeys: number;
+        plainOutKeys: number;
+        encryptedKeys: number;
+        encryptedOutKeys: number;
+    };
+    /**
+     * Encrypt all private keys in the wallet
+     * Internal method called when setting password
+     */
+    private encryptAllKeys;
+    /**
+     * Decrypt essential keys needed for wallet operations
+     * Called after successful unlock
+     */
+    private decryptEssentialKeys;
+    /**
+     * Re-encrypt all keys with a new key (for password change)
+     */
+    private reEncryptAllKeys;
+    /**
+     * Serialize EncryptedData to bytes for storage
+     */
+    private serializeEncryptedToBytes;
+    /**
+     * Deserialize EncryptedData from bytes
+     */
+    private deserializeEncryptedFromBytes;
     /**
      * Generate a new random seed
      * @returns A new random Scalar (seed)
@@ -203,6 +293,65 @@ declare class KeyManager {
      * @returns The master seed Scalar
      */
     getMasterSeedKey(): ScalarType;
+    /**
+     * Generate a new random mnemonic phrase (24 words)
+     * @param strength - Entropy strength in bits (128=12 words, 160=15 words, 192=18 words, 224=21 words, 256=24 words)
+     * @returns A BIP39 mnemonic phrase
+     */
+    static generateMnemonic(strength?: 128 | 160 | 192 | 224 | 256): string;
+    /**
+     * Validate a mnemonic phrase
+     * @param mnemonic - The mnemonic phrase to validate
+     * @returns True if the mnemonic is valid
+     */
+    static validateMnemonic(mnemonic: string): boolean;
+    /**
+     * Convert a mnemonic phrase to seed bytes
+     * Uses BIP39 standard derivation with optional passphrase
+     * @param mnemonic - The mnemonic phrase
+     * @param passphrase - Optional passphrase for additional security
+     * @returns 64-byte seed derived from mnemonic
+     */
+    static mnemonicToSeedBytes(mnemonic: string, passphrase?: string): Uint8Array;
+    /**
+     * Convert a seed (Scalar) to a mnemonic phrase
+     * Note: This converts the 32-byte scalar to mnemonic using it as entropy
+     * @param seed - The seed Scalar
+     * @returns A 24-word mnemonic phrase
+     */
+    static seedToMnemonic(seed: ScalarType): string;
+    /**
+     * Convert a mnemonic phrase to a Scalar seed
+     * For direct entropy-based conversion (mnemonic as entropy, not BIP39 derivation)
+     * @param mnemonic - The mnemonic phrase
+     * @returns A Scalar seed
+     */
+    static mnemonicToScalar(mnemonic: string): ScalarType;
+    /**
+     * Generate a new mnemonic and set it as the HD seed
+     * @param strength - Entropy strength in bits (default: 256 for 24 words)
+     * @returns The mnemonic phrase that can be used to recover this wallet
+     * @note The returned mnemonic is derived from the stored seed, which ensures
+     *       it will produce the same wallet when used for restoration. Due to BLS
+     *       Scalar normalization, this may differ from the initially generated entropy.
+     */
+    generateNewMnemonic(strength?: 128 | 160 | 192 | 224 | 256): string;
+    /**
+     * Set the HD seed from a mnemonic phrase
+     * Uses direct entropy conversion (mnemonic words encode the seed directly)
+     * @param mnemonic - The mnemonic phrase
+     */
+    setHDSeedFromMnemonic(mnemonic: string): void;
+    /**
+     * Get the mnemonic phrase for the current seed
+     * @returns The mnemonic phrase for the current master seed
+     */
+    getMnemonic(): string;
+    /**
+     * Get the master seed as a hex string
+     * @returns The master seed as a 64-character hex string (32 bytes)
+     */
+    getMasterSeedHex(): string;
     /**
      * Get the private view key
      * @returns The view key
@@ -220,6 +369,24 @@ declare class KeyManager {
      * @returns The sub-address (SubAddr)
      */
     getSubAddress(id?: SubAddressIdentifier): SubAddrType;
+    /**
+     * Get a bech32m encoded address string for the given sub-address identifier
+     * @param id - The sub-address identifier (defaults to account 0, address 0)
+     * @param network - The network type ('mainnet' or 'testnet', defaults to 'mainnet')
+     * @returns The bech32m encoded address string
+     * @example
+     * ```typescript
+     * const keyManager = new KeyManager();
+     * keyManager.setHDSeed(seed);
+     *
+     * // Get mainnet address
+     * const mainnetAddress = keyManager.getSubAddressBech32m({ account: 0, address: 0 }, 'mainnet');
+     *
+     * // Get testnet address
+     * const testnetAddress = keyManager.getSubAddressBech32m({ account: 0, address: 0 }, 'testnet');
+     * ```
+     */
+    getSubAddressBech32m(id?: SubAddressIdentifier, network?: 'mainnet' | 'testnet'): string;
     /**
      * Generate a new sub-address for the given account
      * @param account - The account number (0 for main, -1 for change, -2 for staking)
@@ -462,6 +629,7 @@ declare class KeyManager {
      */
     private hash160;
     private bytesToHex;
+    private hexToBytes;
     /**
      * Get the private spending key
      * Replicates GetSpendingKey from keyman.cpp
@@ -837,6 +1005,13 @@ declare class WalletDB {
      * @returns The restored KeyManager instance
      */
     restoreWallet(seedHex: string, creationHeight?: number): Promise<KeyManager>;
+    /**
+     * Restore wallet from mnemonic phrase
+     * @param mnemonic - The BIP39 mnemonic phrase (12-24 words)
+     * @param creationHeight - Optional block height to start scanning from (for faster restore)
+     * @returns The restored KeyManager instance
+     */
+    restoreWalletFromMnemonic(mnemonic: string, creationHeight?: number): Promise<KeyManager>;
     /**
      * Save wallet metadata to database
      */
@@ -917,6 +1092,110 @@ declare class WalletDB {
      * @returns Array of all wallet outputs
      */
     getAllOutputs(): Promise<WalletOutput[]>;
+    /**
+     * Check if the database has encryption enabled
+     * @returns True if encryption is enabled
+     */
+    isEncrypted(): boolean;
+    /**
+     * Save encryption metadata to the database
+     * @param salt - Hex-encoded salt
+     * @param verificationHash - Hex-encoded password verification hash
+     */
+    saveEncryptionMetadata(salt: string, verificationHash: string): void;
+    /**
+     * Load encryption metadata from the database
+     * @returns Encryption metadata or null if not encrypted
+     */
+    getEncryptionMetadata(): {
+        salt: string;
+        verificationHash: string;
+    } | null;
+    /**
+     * Save an encrypted key to the database
+     * @param keyId - Key identifier (hex)
+     * @param publicKey - Public key (hex)
+     * @param encryptedSecret - Encrypted secret (JSON string)
+     */
+    saveEncryptedKey(keyId: string, publicKey: string, encryptedSecret: string): void;
+    /**
+     * Load an encrypted key from the database
+     * @param keyId - Key identifier (hex)
+     * @returns Encrypted key data or null if not found
+     */
+    getEncryptedKey(keyId: string): {
+        publicKey: string;
+        encryptedSecret: string;
+    } | null;
+    /**
+     * Get all encrypted keys from the database
+     * @returns Array of encrypted key data
+     */
+    getAllEncryptedKeys(): Array<{
+        keyId: string;
+        publicKey: string;
+        encryptedSecret: string;
+    }>;
+    /**
+     * Save an encrypted output key to the database
+     * @param outId - Output identifier (hex)
+     * @param publicKey - Public key (hex)
+     * @param encryptedSecret - Encrypted secret (JSON string)
+     */
+    saveEncryptedOutKey(outId: string, publicKey: string, encryptedSecret: string): void;
+    /**
+     * Load an encrypted output key from the database
+     * @param outId - Output identifier (hex)
+     * @returns Encrypted output key data or null if not found
+     */
+    getEncryptedOutKey(outId: string): {
+        publicKey: string;
+        encryptedSecret: string;
+    } | null;
+    /**
+     * Get all encrypted output keys from the database
+     * @returns Array of encrypted output key data
+     */
+    getAllEncryptedOutKeys(): Array<{
+        outId: string;
+        publicKey: string;
+        encryptedSecret: string;
+    }>;
+    /**
+     * Delete plaintext keys (after encryption)
+     * This removes the unencrypted keys from the database
+     */
+    deletePlaintextKeys(): void;
+    /**
+     * Export the database as an encrypted binary blob
+     * Uses the encryption module to encrypt the entire SQLite database
+     *
+     * @param password - Password to encrypt the export
+     * @returns Encrypted database bytes
+     */
+    exportEncrypted(password: string): Promise<Uint8Array>;
+    /**
+     * Load a database from an encrypted binary blob
+     *
+     * @param encryptedData - Encrypted database bytes
+     * @param password - Password to decrypt
+     * @param dbPath - Path for the new database instance
+     * @returns New WalletDB instance with decrypted data
+     */
+    static loadEncrypted(encryptedData: Uint8Array, password: string, dbPath?: string): Promise<WalletDB>;
+    /**
+     * Get the raw database bytes (unencrypted)
+     * @returns Database bytes
+     */
+    export(): Uint8Array;
+    /**
+     * Load a database from raw bytes
+     *
+     * @param data - Raw database bytes
+     * @param dbPath - Path for the new database instance
+     * @returns New WalletDB instance
+     */
+    static loadFromBytes(data: Uint8Array, dbPath?: string): Promise<WalletDB>;
 }
 
 /**
@@ -1947,8 +2226,10 @@ interface NavioClientConfig {
     createWalletIfNotExists?: boolean;
     /** Restore wallet from seed (hex string) */
     restoreFromSeed?: string;
+    /** Restore wallet from mnemonic phrase (24 words) */
+    restoreFromMnemonic?: string;
     /**
-     * Block height to start scanning from when restoring a wallet from seed.
+     * Block height to start scanning from when restoring a wallet from seed or mnemonic.
      * This is the height when the wallet was originally created.
      * Setting this avoids scanning blocks before the wallet existed.
      *
@@ -2221,6 +2502,168 @@ type BlockHash = HexString;
  */
 type OutputHash = HexString;
 
+/**
+ * Wallet encryption module using Argon2id for key derivation and AES-256-GCM for encryption.
+ *
+ * This module provides secure password-based encryption for wallet data.
+ *
+ * @module crypto/encryption
+ */
+type WebCryptoKey = Awaited<ReturnType<SubtleCrypto['importKey']>>;
+/**
+ * Encrypted data structure containing ciphertext and encryption parameters
+ */
+interface EncryptedData {
+    /** The encrypted ciphertext (includes auth tag for GCM) */
+    ciphertext: Uint8Array;
+    /** Initialization vector (12 bytes for AES-GCM) */
+    iv: Uint8Array;
+    /** Salt used for Argon2 key derivation (16 bytes) */
+    salt: Uint8Array;
+}
+/**
+ * Serialized format for encrypted data (for storage)
+ */
+interface SerializedEncryptedData {
+    /** Base64-encoded ciphertext */
+    ciphertext: string;
+    /** Base64-encoded IV */
+    iv: string;
+    /** Base64-encoded salt */
+    salt: string;
+    /** Encryption version for future compatibility */
+    version: number;
+}
+/**
+ * Current encryption version for forward compatibility
+ */
+declare const ENCRYPTION_VERSION = 1;
+/**
+ * IV length for AES-GCM (96 bits / 12 bytes is recommended)
+ */
+declare const IV_LENGTH = 12;
+/**
+ * Salt length for Argon2 (16 bytes is recommended minimum)
+ */
+declare const SALT_LENGTH = 16;
+/**
+ * Generate cryptographically secure random bytes
+ * @param length - Number of bytes to generate
+ * @returns Random bytes
+ */
+declare function randomBytes(length: number): Uint8Array;
+/**
+ * Derive an AES-256 encryption key from a password using Argon2id
+ *
+ * @param password - The user's password
+ * @param salt - Random salt (16 bytes recommended)
+ * @returns CryptoKey suitable for AES-256-GCM encryption
+ */
+declare function deriveKey(password: string, salt: Uint8Array): Promise<WebCryptoKey>;
+/**
+ * Derive raw key bytes from a password using Argon2id
+ * Useful for creating a password verification hash
+ *
+ * @param password - The user's password
+ * @param salt - Random salt (16 bytes recommended)
+ * @returns 32 bytes of derived key material
+ */
+declare function deriveKeyBytes(password: string, salt: Uint8Array): Promise<Uint8Array>;
+/**
+ * Encrypt data using AES-256-GCM with a password
+ *
+ * @param data - The plaintext data to encrypt
+ * @param password - The user's password
+ * @returns Encrypted data with IV and salt
+ */
+declare function encrypt(data: Uint8Array, password: string): Promise<EncryptedData>;
+/**
+ * Encrypt data using AES-256-GCM with a pre-derived CryptoKey
+ * More efficient when encrypting multiple items with the same password
+ *
+ * @param data - The plaintext data to encrypt
+ * @param key - Pre-derived CryptoKey
+ * @param salt - Salt used to derive the key (for storage)
+ * @returns Encrypted data with IV and salt
+ */
+declare function encryptWithKey(data: Uint8Array, key: WebCryptoKey, salt: Uint8Array): Promise<EncryptedData>;
+/**
+ * Decrypt data using AES-256-GCM with a password
+ *
+ * @param encrypted - The encrypted data with IV and salt
+ * @param password - The user's password
+ * @returns Decrypted plaintext data
+ * @throws Error if decryption fails (wrong password or corrupted data)
+ */
+declare function decrypt(encrypted: EncryptedData, password: string): Promise<Uint8Array>;
+/**
+ * Decrypt data using AES-256-GCM with a pre-derived CryptoKey
+ * More efficient when decrypting multiple items with the same password
+ *
+ * @param encrypted - The encrypted data with IV and salt
+ * @param key - Pre-derived CryptoKey
+ * @returns Decrypted plaintext data
+ * @throws Error if decryption fails (wrong key or corrupted data)
+ */
+declare function decryptWithKey(encrypted: EncryptedData, key: WebCryptoKey): Promise<Uint8Array>;
+/**
+ * Serialize encrypted data for storage (converts to base64 strings)
+ *
+ * @param encrypted - Encrypted data to serialize
+ * @returns Serialized format suitable for JSON storage
+ */
+declare function serializeEncryptedData(encrypted: EncryptedData): SerializedEncryptedData;
+/**
+ * Deserialize encrypted data from storage
+ *
+ * @param serialized - Serialized encrypted data
+ * @returns Encrypted data ready for decryption
+ * @throws Error if version is unsupported
+ */
+declare function deserializeEncryptedData(serialized: SerializedEncryptedData): EncryptedData;
+/**
+ * Encrypt an entire database buffer
+ *
+ * @param dbBuffer - Raw database file bytes
+ * @param password - The user's password
+ * @returns Encrypted database buffer with header
+ */
+declare function encryptDatabase(dbBuffer: Uint8Array, password: string): Promise<Uint8Array>;
+/**
+ * Decrypt an entire database buffer
+ *
+ * @param encryptedBuffer - Encrypted database buffer with header
+ * @param password - The user's password
+ * @returns Decrypted database file bytes
+ * @throws Error if decryption fails
+ */
+declare function decryptDatabase(encryptedBuffer: Uint8Array, password: string): Promise<Uint8Array>;
+/**
+ * Check if a buffer appears to be an encrypted database
+ *
+ * @param buffer - Buffer to check
+ * @returns True if buffer starts with valid encryption header
+ */
+declare function isEncryptedDatabase(buffer: Uint8Array): boolean;
+/**
+ * Create a password verification hash
+ * This is stored to verify the password is correct before attempting decryption
+ *
+ * @param password - The user's password
+ * @param salt - Salt to use (same as encryption salt)
+ * @returns Verification hash (32 bytes)
+ */
+declare function createPasswordVerification(password: string, salt: Uint8Array): Promise<Uint8Array>;
+/**
+ * Verify a password against a stored verification hash
+ *
+ * @param password - Password to verify
+ * @param salt - Salt used for key derivation
+ * @param storedHash - Previously stored verification hash
+ * @returns True if password is correct
+ */
+declare function verifyPassword(password: string, salt: Uint8Array, storedHash: Uint8Array): Promise<boolean>;
+
 /**
  * Electrum Sync Provider
  *
@@ -2497,4 +2940,4 @@ declare class P2PSyncProvider extends BaseSyncProvider {
     private decodeVarInt;
 }
 
-export { type AmountRecoveryResult, type BackendType, type BackgroundSyncOptions, BaseSyncProvider, type BlockHash, type BlockHeader, type BlockHeadersResult, type BlockLocator, type BlockTransactionKeys, type BlockTransactionKeysRange, type CTxDestination, type CTxOut, type CTxOutBLSCTData, type ChainTip, DefaultPorts, ElectrumClient, ElectrumError, type ElectrumOptions, type ElectrumSyncOptions, ElectrumSyncProvider, type HDChain, type HexString, InvType, type InvVector, KeyManager, type KeyStorage, type MessageHeader, MessageType, NavioClient, type NavioClientConfig, type NavioNetwork, NetworkMagic, type NetworkType, type OutputHash, P2PClient, type P2PConnectionOptions, type P2PMessage, type P2POptions, type P2PSyncOptions, P2PSyncProvider, PROTOCOL_VERSION, type PublicKey$1 as PublicKey, type ReorganizationInfo, type SecretKey, type SeedType, ServiceFlags, type SubAddress, type SubAddressIdentifier, type SyncBlockHeader, type SyncOptions, type SyncProgressCallback, type SyncProvider, type SyncProviderOptions, type SyncState, type TransactionKeys, TransactionKeysSync, type TxHash, type VersionPayload, WalletDB, type WalletOutput };
+export { type AmountRecoveryResult, type BackendType, type BackgroundSyncOptions, BaseSyncProvider, type BlockHash, type BlockHeader, type BlockHeadersResult, type BlockLocator, type BlockTransactionKeys, type BlockTransactionKeysRange, type CTxDestination, type CTxOut, type CTxOutBLSCTData, type ChainTip, DefaultPorts, ENCRYPTION_VERSION, ElectrumClient, ElectrumError, type ElectrumOptions, type ElectrumSyncOptions, ElectrumSyncProvider, type EncryptedData, type HDChain, type HexString, IV_LENGTH, InvType, type InvVector, KeyManager, type KeyStorage, type MessageHeader, MessageType, NavioClient, type NavioClientConfig, type NavioNetwork, NetworkMagic, type NetworkType, type OutputHash, P2PClient, type P2PConnectionOptions, type P2PMessage, type P2POptions, type P2PSyncOptions, P2PSyncProvider, PROTOCOL_VERSION, type PublicKey$1 as PublicKey, type ReorganizationInfo, SALT_LENGTH, type SecretKey, type SeedType, type SerializedEncryptedData, ServiceFlags, type SubAddress, type SubAddressIdentifier, type SyncBlockHeader, type SyncOptions, type SyncProgressCallback, type SyncProvider, type SyncProviderOptions, type SyncState, type TransactionKeys, TransactionKeysSync, type TxHash, type VersionPayload, WalletDB, type WalletOutput, createPasswordVerification, decrypt, decryptDatabase, decryptWithKey, deriveKey, deriveKeyBytes, deserializeEncryptedData, encrypt, encryptDatabase, encryptWithKey, isEncryptedDatabase, randomBytes, serializeEncryptedData, verifyPassword };