@sidhujag/sysweb3-keyring 1.0.612 → 1.0.613

package/README.md

@@ -14,6 +14,40 @@ The sysweb3-keyring provides a unified interface for managing accounts, transact
 - **Secure Session Management**: Encrypted private key handling with session transfer
 - **Transaction Management**: Full transaction lifecycle support for both network types
 
+## Vault encryption compatibility
+
+New vaults require WebCrypto and use PBKDF2-HMAC-SHA-512 (900,000 production
+iterations) with AES-256-GCM. Missing WebCrypto rejects the operation without
+writing a weaker fallback vault. Restore WebCrypto availability before retrying
+an unmarked legacy vault.
+
+Historical fallback vaults used a 20,000-iteration key that also encrypted their
+persisted account keys. After authenticating such a CBC vault, the keyring records
+the explicit `pbkdf2-sha512-20000` compatibility profile and rewraps the vault with
+AES-GCM. This preserves existing account access across restart; it is **not** a
+full rekey of those account records to 900,000 iterations. The profile is written
+before rewrapping, so interruption of either write remains recoverable. Arbitrary
+KDF profiles or parameters are rejected.
+
+Storage clients must return their asynchronous write/delete promises. The core
+adapter preserves them so rejected writes do not silently advance vault migration.
+Fresh wallet creation additionally requires conditional batch creation. Native
+`chrome.storage.local` and `browser.storage.local` use a prefix-scoped Web Lock
+around the absence check and awaited write, coordinating contexts in the same
+extension origin and storage partition. Custom clients must provide an atomic
+`createItemsIfAbsent(items)` backend operation over prefixed, JSON-serialized
+values; the built-in memory client provides this operation synchronously.
+There is no sequential or unlocked fallback. A backend shared across storage
+partitions needs its own atomic implementation or a single owner.
+
+### Release order for 1.0.613
+
+Publish `@sidhujag/sysweb3-core@1.0.29` before `@sidhujag/sysweb3-keyring@1.0.613`.
+The updated lock entry describes that intended dependency; its integrity is
+intentionally absent until publication. Regenerate and verify the lockfile from
+the published registry artifacts before a clean registry installation. Local
+validation uses the built package tarballs and does not establish publication.
+
 ## Installation
 
 ```bash
@@ -191,7 +225,11 @@ Main class for keyring operations:
 
 ## Security
 
-- Private keys are encrypted and stored in memory only
+- `initializeSession`, `initializeWalletSecurely`, and the initialization factories create a new wallet only when both vault records are absent. Use `unlock()` to restore an existing wallet. Repeating initialization on a matching live session verifies the stored wallet without rewriting it.
+- Fresh vault salt and ciphertext are created together only if both are absent, through the core conditional-creation operation. Native extension contexts sharing an origin/storage partition are coordinated by Web Locks; custom backends must provide atomic `createItemsIfAbsent`. Unsupported adapters are rejected before writing. Existing or incomplete records are preserved.
+- UTXO signing authenticates the selected account's paths, public keys and spent scripts. A joint PSBT may include unfinished inputs for another signer: their HD/path hints are removed before the selected private signer runs, then their public metadata is restored to the returned partial PSBT. Another account in the same wallet remains unsigned. At least one unfinished input must authenticate to the selected account; a wholly finalized PSBT retains its existing handling. Standard P2WSH, wrapped P2WSH and P2SH multisig preserve external cosigner signatures and continuation. Hardware paths and single-address imports can reject unsupported joint inputs rather than widening signing authority.
+- Hardware signing preserves already-finalized external inputs without requesting their private derivations. Trezor receives them as `EXTERNAL` inputs; Ledger retains their final scripts in PSBTv2 and skips signing/finalizing them again. Unfinished foreign hardware inputs remain unsupported.
+- Persisted wallet and account secrets are encrypted; plaintext signing material is used in memory
 - Session data is cleared when the keyring is locked
 - Hardware wallet integration follows device security models
 - Secure memory management with explicit cleanup

package/cjs/keyring-manager.js

@@ -51,6 +51,7 @@ const BIP84 = __importStar(require("syscoinjs-lib/bip84-replacement"));
 // Reference embedded bitcoinjs from syscoinjs-lib
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const bjs = syscoinjs.utils.bitcoinjs;
+const LEGACY_ENCRYPTION_KDF = 'pbkdf2-sha512-20000';
 const SLH_DSA_DERIVATION_VERSION = 1;
 // Preserve Pali v1 SLH derivation: first 32 bytes of the account-scoped HMAC.
 // Pali expands this setup secret into the 48-byte SLH skSeed/skPrf/pkSeed tuple.
@@ -68,6 +69,7 @@ const trezor_1 = require("./trezor");
 const types_1 = require("./types");
 const blockbook_cache_1 = require("./utils/blockbook-cache");
 const derivation_paths_1 = require("./utils/derivation-paths");
+const psbt_account_scope_1 = require("./utils/psbt-account-scope");
 // Dynamic ETH HD path generation - will be computed as needed
 /**
  * Secure Buffer implementation for sensitive data
@@ -374,7 +376,7 @@ class KeyringManager {
                 if (!vaultKeys || !vaultKeys.salt) {
                     throw new Error('Vault keys not found');
                 }
-                const genPwd = await this.encryptSHA512Async(pwd, vaultKeys.salt);
+                const genPwd = await this.deriveStoredSessionKey(pwd, vaultKeys);
                 if (this.getSessionPasswordString() !== genPwd) {
                     throw new Error('Invalid password');
                 }
@@ -426,7 +428,7 @@ class KeyringManager {
             if (!vaultKeys || !vaultKeys.salt) {
                 throw new Error('Vault keys not found');
             }
-            const genPwd = await this.encryptSHA512Async(pwd, vaultKeys.salt);
+            const genPwd = await this.deriveStoredSessionKey(pwd, vaultKeys);
             if (this.getSessionPasswordString() !== genPwd) {
                 throw new Error('Invalid password');
             }
@@ -558,7 +560,7 @@ class KeyringManager {
             if (!vaultKeys || !vaultKeys.salt) {
                 throw new Error('Vault keys not found');
             }
-            const genPwd = await this.encryptSHA512Async(pwd, vaultKeys.salt);
+            const genPwd = await this.deriveStoredSessionKey(pwd, vaultKeys);
             if (!this.sessionPassword) {
                 throw new Error('Unlock wallet first');
             }
@@ -755,6 +757,33 @@ class KeyringManager {
                 throw error;
             }
         };
+        this.capturePsbtSigningContext = () => {
+            const session = this.sessionPassword;
+            const vault = this.getVault();
+            const selected = { ...vault.activeAccount };
+            const account = vault.accounts[selected.type]?.[selected.id];
+            const identity = { address: account?.address, xpub: account?.xpub };
+            const network = { ...vault.activeNetwork };
+            const assertCurrent = () => {
+                const current = this.getVault();
+                const currentAccount = current.accounts[selected.type]?.[selected.id];
+                if (!session ||
+                    session.isCleared() ||
+                    this.sessionPassword !== session ||
+                    current.activeAccount.id !== selected.id ||
+                    current.activeAccount.type !== selected.type ||
+                    currentAccount?.address !== identity.address ||
+                    currentAccount?.xpub !== identity.xpub ||
+                    current.activeNetwork.kind !== network.kind ||
+                    current.activeNetwork.chainId !== network.chainId ||
+                    current.activeNetwork.slip44 !== network.slip44 ||
+                    current.activeNetwork.url !== network.url) {
+                    throw new Error('Wallet signing context changed');
+                }
+            };
+            assertCurrent();
+            return assertCurrent;
+        };
         this.getSigner = () => {
             if (!this.sessionPassword) {
                 throw new Error('Wallet is locked cant proceed with transaction');
@@ -766,6 +795,7 @@ class KeyringManager {
             const { activeAccount } = vault;
             const accountId = activeAccount.id;
             const accountType = activeAccount.type;
+            const assertCurrent = this.capturePsbtSigningContext();
             // Determine signer type: HD or WIF single-address
             let signerForUse;
             if (accountType === types_1.KeyringAccountType.HDAccount) {
@@ -801,6 +831,33 @@ class KeyringManager {
             else {
                 throw new Error(`Unsupported account type for UTXO signing: ${accountType}`);
             }
+            const scope = {
+                account: vault.accounts[accountType][accountId],
+                accountId,
+                accountType,
+                network: vault.activeNetwork,
+            };
+            if (typeof signerForUse.getRootNode === 'function') {
+                const getRootNode = signerForUse.getRootNode.bind(signerForUse);
+                const guardPath = (0, psbt_account_scope_1.createPsbtDerivationGuard)(scope);
+                signerForUse.getRootNode = () => {
+                    const root = getRootNode();
+                    const scopedRoot = Object.create(root);
+                    scopedRoot.derivePath = (path) => {
+                        guardPath(path);
+                        return root.derivePath(path);
+                    };
+                    return scopedRoot;
+                };
+            }
+            const sign = signerForUse.sign.bind(signerForUse);
+            signerForUse.sign = async (psbt) => {
+                assertCurrent();
+                (0, psbt_account_scope_1.assertPsbtAccountScope)(psbt, scope);
+                const result = await sign(psbt);
+                assertCurrent();
+                return result;
+            };
             // Create syscoinjs instance with current network (no need to attach signer for signing flow)
             const network = vault.activeNetwork;
             const networkConfig = (0, sysweb3_network_1.getNetworkConfig)(network.slip44, network.currency);
@@ -1022,51 +1079,65 @@ class KeyringManager {
             if (!BIP84.validateMnemonic(seedPhrase)) {
                 throw new Error('Invalid Seed');
             }
-            let foundVaultKeys = true;
-            let salt = '';
-            const vaultKeys = await this.storage.get('vault-keys');
-            if (!vaultKeys || !vaultKeys.salt) {
-                foundVaultKeys = false;
-                salt = crypto_1.default.randomBytes(16).toString('hex');
-            }
-            else {
-                salt = vaultKeys.salt;
-            }
-            // v4 stores only the salt on disk (vault-keys.salt).
-            // The derived session encryption key must remain in memory only.
-            const sessionPasswordSaltedHash = await this.encryptSHA512Async(password, salt);
-            if (!foundVaultKeys) {
-                // Store vault-keys using the storage abstraction
-                await this.storage.set('vault-keys', {
-                    salt,
-                });
-            }
-            // Check if already initialized with the same password (idempotent behavior)
-            if (this.sessionPassword) {
-                if (sessionPasswordSaltedHash === this.getSessionPasswordString()) {
+            const [vault, vaultKeys] = await Promise.all([
+                this.storage.get('vault'),
+                this.storage.get('vault-keys'),
+            ]);
+            const hasVault = vault !== undefined && vault !== null;
+            const hasVaultKeys = vaultKeys !== undefined && vaultKeys !== null;
+            const livePassword = this.sessionPassword;
+            const liveMnemonic = this.sessionMnemonic;
+            // Only an already-unlocked, matching session may repeat initialization.
+            // Restoring any existing wallet must use unlock(), never rewrite its vault.
+            if (livePassword &&
+                liveMnemonic &&
+                !livePassword.isCleared() &&
+                !liveMnemonic.isCleared()) {
+                if (!hasVault || !hasVaultKeys || !vaultKeys.salt) {
+                    throw new Error('Cannot initialize a new vault over existing wallet storage');
+                }
+                const sessionPasswordSaltedHash = await this.deriveStoredSessionKey(password, vaultKeys);
+                if (livePassword === this.sessionPassword &&
+                    liveMnemonic === this.sessionMnemonic &&
+                    sessionPasswordSaltedHash === this.getSessionPasswordString()) {
                     // Same password - check if it's the same mnemonic to ensure full idempotency
+                    let currentMnemonic;
                     try {
-                        const currentMnemonic = this.withSecureData((sessionPwd, sessionMnemonic) => {
+                        currentMnemonic = this.withSecureData((sessionPwd, sessionMnemonic) => {
                             return crypto_js_1.default.AES.decrypt(sessionMnemonic, sessionPwd).toString(crypto_js_1.default.enc.Utf8);
                         });
-                        if (currentMnemonic === seedPhrase) {
-                            // Same mnemonic and password - already initialized
-                            return;
-                        }
                     }
                     catch (error) {
                         // If we can't decrypt, fall through to error
                     }
+                    if (currentMnemonic === seedPhrase) {
+                        const storedVault = await (0, storage_1.getDecryptedVault)(sessionPasswordSaltedHash);
+                        if (livePassword === this.sessionPassword &&
+                            liveMnemonic === this.sessionMnemonic &&
+                            !livePassword.isCleared() &&
+                            !liveMnemonic.isCleared() &&
+                            storedVault?.mnemonic === seedPhrase) {
+                            // This is a read-only identity check, not a second vault write.
+                            return;
+                        }
+                    }
                 }
                 // Different password or mnemonic - this is not a simple re-initialization
-                throw new Error('Wallet already initialized with different parameters. Create a new keyring instance for different parameters.');
+                throw new Error('Wallet already initialized with different parameters. Unlock the existing wallet or explicitly remove it before starting setup.');
+            }
+            if (hasVault || hasVaultKeys) {
+                throw new Error('Cannot initialize a new vault over existing wallet storage');
             }
+            const salt = crypto_1.default.randomBytes(16).toString('hex');
+            // v4 stores only the salt on disk. A genuinely fresh initialization always
+            // commits its own salt and ciphertext together under the vault mutex.
+            const sessionPasswordSaltedHash = await this.deriveStoredSessionKey(password, { salt });
             // Encrypt and store vault (mnemonic storage) - now uses single vault for all networks
             await (0, storage_1.setEncryptedVault)({
                 mnemonic: seedPhrase, // Store plain mnemonic - setEncryptedVault will encrypt the entire vault
             }, 
             // v4 vault is encrypted with the derived session password key (PBKDF2 output)
-            sessionPasswordSaltedHash);
+            sessionPasswordSaltedHash, { salt });
             await this.recreateSessionFromVault(sessionPasswordSaltedHash);
         };
         // NEW: Create first account without signer setup
@@ -1108,9 +1179,7 @@ class KeyringManager {
         };
         this.storage = sysweb3.sysweb3Di.getStateStorageDb();
         // Don't initialize secure buffers in constructor - they're created on unlock
-        this.storage.set('utf8Error', {
-            hasUtf8Error: false,
-        });
+        this.writeUtf8Diagnostic(false);
         // NOTE: activeChain is now derived from vault state, not stored locally
         // NOTE: No more persistent signers - use getSigner() for fresh on-demand signers
         this.utf8Error = false;
@@ -1123,7 +1192,7 @@ class KeyringManager {
         this.trezorSigner = new trezor_1.TrezorKeyring();
         this.ledgerSigner = new ledger_1.LedgerKeyring(hardwareManager);
         // this.syscoinTransaction = SyscoinTransactions();
-        this.syscoinTransaction = new transactions_1.SyscoinTransactions(this.getSigner, this.getReadOnlySigner, this.getAccountsState, this.getAddress, this.ledgerSigner, this.trezorSigner);
+        this.syscoinTransaction = new transactions_1.SyscoinTransactions(this.getSigner, this.getReadOnlySigner, this.getAccountsState, this.getAddress, this.ledgerSigner, this.trezorSigner, this.capturePsbtSigningContext);
         this.ethereumTransaction = new transactions_1.EthereumTransactions(this.getNetwork, this.getDecryptedPrivateKey, this.getAccountsState, this.ledgerSigner, this.trezorSigner);
     }
     // Static factory method for creating a fully initialized KeyringManager with slip44 support
@@ -1166,7 +1235,7 @@ class KeyringManager {
             const { salt } = vaultKeys;
             // Derive session encryption key (in-memory only) used to encrypt/decrypt xprv fields
             // IMPORTANT: This MUST NOT be the same value as the stored verifier above.
-            const sessionPasswordKey = await this.encryptSHA512Async(password, salt);
+            let sessionPasswordKey = await this.deriveStoredSessionKey(password, vaultKeys);
             // Handle migration from old vault format with currentSessionSalt
             if (vaultKeys.currentSessionSalt) {
                 console.log('[KeyringManager] Detected old vault format, handling session migration...');
@@ -1227,8 +1296,44 @@ class KeyringManager {
             }
             // v4 vault is encrypted with the derived session password key (PBKDF2 output).
             // If the password is wrong, this will throw and we return canLogin:false below.
-            await (0, storage_1.getDecryptedVault)(sessionPasswordKey);
+            let decryptedVault;
+            let legacyProfile = vaultKeys.keyDerivation === LEGACY_ENCRYPTION_KDF;
+            try {
+                decryptedVault = await (0, storage_1.getDecryptedVault)(sessionPasswordKey);
+            }
+            catch (error) {
+                // Only the historical CBC fallback used the 20k key without metadata.
+                // Never try it for GCM, malformed records, or platform/storage failures.
+                const rawVault = error instanceof storage_1.VaultAuthenticationError &&
+                    !vaultKeys.keyDerivation &&
+                    !vaultKeys.currentSessionSalt
+                    ? await this.storage.get('vault')
+                    : undefined;
+                if (typeof rawVault !== 'string' || rawVault.trim().startsWith('{')) {
+                    throw error;
+                }
+                const legacyKey = await this.deriveLegacySessionKey(password, salt);
+                decryptedVault = await (0, storage_1.getDecryptedVault)(legacyKey);
+                authenticated = true;
+                sessionPasswordKey = legacyKey;
+                // Keep the historical account wrapping key. Persist its profile before
+                // GCM rewrapping so either interrupted write remains recoverable.
+                await this.storage.set('vault-keys', {
+                    ...vaultKeys,
+                    keyDerivation: LEGACY_ENCRYPTION_KDF,
+                });
+                legacyProfile = true;
+            }
             authenticated = true;
+            if (legacyProfile && this.hasWebCrypto()) {
+                const storedVault = await this.storage.get('vault');
+                if (typeof storedVault === 'string' &&
+                    !storedVault.trim().startsWith('{')) {
+                    // A failed earlier rewrap can leave the authenticated profile plus
+                    // CBC. Retry that write without changing the account wrapping key.
+                    await (0, storage_1.setEncryptedVault)(decryptedVault, sessionPasswordKey);
+                }
+            }
             // If session data missing or corrupted, recreate from vault
             if (!this.sessionMnemonic) {
                 await this.recreateSessionFromVault(sessionPasswordKey);
@@ -1238,7 +1343,7 @@ class KeyringManager {
             // so we must restore the real class instance on unlock.
             if (!this.syscoinTransaction ||
                 typeof this.syscoinTransaction.getRecommendedFee !== 'function') {
-                this.syscoinTransaction = new transactions_1.SyscoinTransactions(this.getSigner, this.getReadOnlySigner, this.getAccountsState, this.getAddress, this.ledgerSigner, this.trezorSigner);
+                this.syscoinTransaction = new transactions_1.SyscoinTransactions(this.getSigner, this.getReadOnlySigner, this.getAccountsState, this.getAddress, this.ledgerSigner, this.trezorSigner, this.capturePsbtSigningContext);
             }
             // NOTE: Active account management is now handled by vault state/Redux
             // No need to explicitly set active account after unlock - it's managed externally
@@ -1576,11 +1681,20 @@ class KeyringManager {
             return { isValid: false, message: error.message };
         }
     }
+    writeUtf8Diagnostic(hasUtf8Error) {
+        try {
+            void Promise.resolve(this.storage.set('utf8Error', { hasUtf8Error })).catch(() => undefined);
+        }
+        catch {
+            // This diagnostic must not interrupt authentication or become an
+            // unhandled rejection when an asynchronous storage client is offline.
+        }
+    }
     validateAndHandleErrorByMessage(message) {
         const utf8ErrorMessage = 'Malformed UTF-8 data';
         if (message.includes(utf8ErrorMessage) ||
             message.toLowerCase().includes(utf8ErrorMessage.toLowerCase())) {
-            this.storage.set('utf8Error', { hasUtf8Error: true });
+            this.writeUtf8Diagnostic(true);
         }
     }
     async pbkdf2WebCryptoHex(params) {
@@ -1608,7 +1722,33 @@ class KeyringManager {
                 hash: 'SHA-512',
             });
         }
-        return this.encryptSHA512(password, salt);
+        throw new Error('WebCrypto is required for vault key derivation');
+    }
+    async deriveLegacySessionKey(password, salt) {
+        if (this.hasWebCrypto()) {
+            return this.pbkdf2WebCryptoHex({
+                password,
+                saltHex: salt,
+                iterations: 20000,
+                lengthBytes: 32,
+                hash: 'SHA-512',
+            });
+        }
+        // Read compatibility only; new vault writes still require WebCrypto.
+        return crypto_js_1.default.PBKDF2(password, crypto_js_1.default.enc.Hex.parse(salt), {
+            keySize: 256 / 32,
+            iterations: 20000,
+            hasher: crypto_js_1.default.algo.SHA512,
+        }).toString();
+    }
+    async deriveStoredSessionKey(password, vaultKeys) {
+        if (vaultKeys.keyDerivation === LEGACY_ENCRYPTION_KDF) {
+            return this.deriveLegacySessionKey(password, vaultKeys.salt);
+        }
+        if (vaultKeys.keyDerivation !== undefined) {
+            throw new Error('Unsupported vault key derivation profile');
+        }
+        return this.encryptSHA512Async(password, vaultKeys.salt);
     }
     async _createTrezorAccount(coin, slip44, index, label) {
         const vault = this.getVault();