@bsv/wallet-toolbox-mobile 2.1.9 → 2.1.11

package/out/src/CWIStyleWalletManager.js

@@ -1,15 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CWIStyleWalletManager = exports.OverlayUMPTokenInteractor = exports.DEFAULT_PROFILE_ID = exports.PBKDF2_NUM_ROUNDS = void 0;
+exports.CWIStyleWalletManager = exports.OverlayUMPTokenInteractor = exports.DEFAULT_PROFILE_ID = exports.ARGON2ID_DEFAULT_HASH_LENGTH = exports.ARGON2ID_DEFAULT_PARALLELISM = exports.ARGON2ID_DEFAULT_MEMORY_KIB = exports.ARGON2ID_DEFAULT_ITERATIONS = exports.PBKDF2_NUM_ROUNDS = void 0;
 const sdk_1 = require("@bsv/sdk");
+const hash_wasm_1 = require("hash-wasm");
 const PrivilegedKeyManager_1 = require("./sdk/PrivilegedKeyManager");
 /**
  * Number of rounds used in PBKDF2 for deriving password keys.
  */
 exports.PBKDF2_NUM_ROUNDS = 7777;
 /**
- * PBKDF-2 that prefers the browser / Node 20+ WebCrypto implementation and
- * silently falls back to the existing JS code.
+ * Default Argon2id parameters for password-key derivation (UMP v3).
+ */
+exports.ARGON2ID_DEFAULT_ITERATIONS = 7;
+exports.ARGON2ID_DEFAULT_MEMORY_KIB = 131072;
+exports.ARGON2ID_DEFAULT_PARALLELISM = 1;
+exports.ARGON2ID_DEFAULT_HASH_LENGTH = 32;
+function isLikelyDerSignatureField(field) {
+    if (!field || field.length < 8 || field.length > 80) {
+        return false;
+    }
+    if (field[0] !== 0x30) {
+        return false;
+    }
+    const declaredLen = field[1];
+    return declaredLen === field.length - 2;
+}
+function stripVerifiedPushDropSignature(fields, lockingPublicKey) {
+    if (fields.length <= 11) {
+        return fields;
+    }
+    const protocolFieldCount = fields.length - 1;
+    const trailingField = fields[protocolFieldCount];
+    if (!trailingField || !isLikelyDerSignatureField(trailingField)) {
+        return fields;
+    }
+    try {
+        let dataLength = 0;
+        for (let i = 0; i < protocolFieldCount; i++) {
+            dataLength += fields[i].length;
+        }
+        const dataToVerify = new Array(dataLength);
+        let writeOffset = 0;
+        for (let i = 0; i < protocolFieldCount; i++) {
+            const field = fields[i];
+            for (let j = 0; j < field.length; j++) {
+                dataToVerify[writeOffset++] = field[j];
+            }
+        }
+        const signature = sdk_1.Signature.fromDER(trailingField);
+        if (signature.verify(dataToVerify, lockingPublicKey)) {
+            return fields.slice(0, protocolFieldCount);
+        }
+    }
+    catch (_a) {
+        return fields;
+    }
+    return fields;
+}
+/**
+ * PBKDF-2 that prefers WebCrypto and falls back to hash-wasm.
  *
  * @param passwordBytes   Raw password bytes.
  * @param salt            Salt bytes.
@@ -18,7 +67,7 @@ exports.PBKDF2_NUM_ROUNDS = 7777;
  * @param hash            Digest algorithm (default "sha512").
  * @returns               Derived key bytes.
  */
-async function pbkdf2NativeOrJs(passwordBytes, salt, iterations, keyLen, hash = 'sha512') {
+async function pbkdf2NativeOrWasm(passwordBytes, salt, iterations, keyLen, hash = 'sha512') {
     var _a;
     // ----- fast-path: WebCrypto (both browser & recent Node expose globalThis.crypto.subtle)
     const subtle = (_a = globalThis === null || globalThis === void 0 ? void 0 : globalThis.crypto) === null || _a === void 0 ? void 0 : _a.subtle;
@@ -39,8 +88,52 @@ async function pbkdf2NativeOrJs(passwordBytes, salt, iterations, keyLen, hash =
             /* fall through */
         }
     }
-    // ----- slow-path: old JavaScript implementation
-    return sdk_1.Hash.pbkdf2(passwordBytes, salt, iterations, keyLen, hash);
+    const hashFunction = hash === 'sha256' ? (0, hash_wasm_1.createSHA256)() : (0, hash_wasm_1.createSHA512)();
+    const derived = await (0, hash_wasm_1.pbkdf2)({
+        password: new Uint8Array(passwordBytes),
+        salt: new Uint8Array(salt),
+        iterations,
+        hashLength: keyLen,
+        hashFunction,
+        outputType: 'binary'
+    });
+    return Array.from(derived);
+}
+/**
+ * Derives the password key from a password using the KDF specified in the UMP token.
+ * For legacy tokens (no KDF metadata), uses PBKDF2 with fixed rounds (7777).
+ * For v3 tokens, uses the algorithm specified in passwordKdf metadata.
+ *
+ * @param token          The UMP token containing KDF metadata and salt.
+ * @param passwordBytes  Raw password bytes.
+ * @param overrideKdf    Optional KDF config to override token/default settings.
+ * @returns              Derived password key bytes.
+ */
+async function derivePasswordKey(token, passwordBytes, overrideKdf) {
+    var _a, _b, _c, _d, _e;
+    const kdf = overrideKdf || token.passwordKdf;
+    // Legacy token or explicit PBKDF2 request
+    if (!kdf || kdf.algorithm === 'pbkdf2-sha512') {
+        return pbkdf2NativeOrWasm(passwordBytes, token.passwordSalt, (_a = kdf === null || kdf === void 0 ? void 0 : kdf.iterations) !== null && _a !== void 0 ? _a : exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
+    }
+    // Argon2id path (UMP v3)
+    if (kdf.algorithm === 'argon2id') {
+        const iterations = (_b = kdf.iterations) !== null && _b !== void 0 ? _b : exports.ARGON2ID_DEFAULT_ITERATIONS;
+        const memorySize = (_c = kdf.memoryKiB) !== null && _c !== void 0 ? _c : exports.ARGON2ID_DEFAULT_MEMORY_KIB;
+        const parallelism = (_d = kdf.parallelism) !== null && _d !== void 0 ? _d : exports.ARGON2ID_DEFAULT_PARALLELISM;
+        const hashLength = (_e = kdf.hashLength) !== null && _e !== void 0 ? _e : exports.ARGON2ID_DEFAULT_HASH_LENGTH;
+        const hash = await (0, hash_wasm_1.argon2id)({
+            password: new Uint8Array(passwordBytes),
+            salt: new Uint8Array(token.passwordSalt),
+            iterations,
+            memorySize,
+            parallelism,
+            hashLength,
+            outputType: 'binary'
+        });
+        return Array.from(hash);
+    }
+    throw new Error(`Unsupported KDF algorithm: ${kdf.algorithm}`);
 }
 /**
  * Unique Identifier for the default profile (16 zero bytes).
@@ -127,11 +220,32 @@ class OverlayUMPTokenInteractor {
         fields[8] = token.presentationKeyEncrypted;
         fields[9] = token.passwordKeyEncrypted;
         fields[10] = token.recoveryKeyEncrypted;
-        // Optional field (11) for encrypted profiles
+        // Optional field for encrypted profiles
         if (token.profilesEncrypted) {
             fields[11] = token.profilesEncrypted;
         }
+        // V3 fields: umpVersion, kdfAlgorithm, kdfParams
+        if (token.umpVersion === 3 && token.passwordKdf) {
+            const versionFieldIndex = token.profilesEncrypted ? 12 : 11;
+            fields[versionFieldIndex] = [token.umpVersion]; // Single byte
+            fields[versionFieldIndex + 1] = sdk_1.Utils.toArray(token.passwordKdf.algorithm, 'utf8');
+            // Construct kdfParams JSON
+            const kdfParams = {
+                iterations: token.passwordKdf.iterations
+            };
+            if (token.passwordKdf.memoryKiB !== undefined) {
+                kdfParams.memoryKiB = token.passwordKdf.memoryKiB;
+            }
+            if (token.passwordKdf.parallelism !== undefined) {
+                kdfParams.parallelism = token.passwordKdf.parallelism;
+            }
+            if (token.passwordKdf.hashLength !== undefined) {
+                kdfParams.hashLength = token.passwordKdf.hashLength;
+            }
+            fields[versionFieldIndex + 2] = sdk_1.Utils.toArray(JSON.stringify(kdfParams), 'utf8');
+        }
         // 2) Create a PushDrop script referencing these fields, locked with the admin key.
+        // The signature will be added as trailing metadata by PushDrop (not part of protocol fields).
         const script = await new sdk_1.PushDrop(wallet, adminOriginator).lock(fields, [2, 'admin user management token'], // protocolID
         '1', // keyID
         'self', // counterparty
@@ -257,7 +371,7 @@ class OverlayUMPTokenInteractor {
      * @returns The parsed UMPToken or `undefined` if none found/decodable.
      */
     parseLookupAnswer(answer) {
-        var _a;
+        var _a, _b, _c;
         if (answer.type !== 'output-list') {
             return undefined;
         }
@@ -274,23 +388,60 @@ class OverlayUMPTokenInteractor {
                 console.warn(`Unexpected number of fields in UMP token: ${(_a = decoded.fields) === null || _a === void 0 ? void 0 : _a.length}`);
                 return undefined;
             }
+            // Parse protocol fields, excluding the trailing PushDrop signature only when
+            // it is cryptographically valid for the preceding field payload.
+            let protocolFields = stripVerifiedPushDropSignature(decoded.fields, decoded.lockingPublicKey);
+            // Detect v3 token metadata in either layout:
+            // - with profilesEncrypted present: [0..10]=core, [11]=profiles, [12]=version, [13]=algorithm, [14]=params
+            // - without profilesEncrypted:      [0..10]=core, [11]=version, [12]=algorithm, [13]=params
+            const hasV3MetadataWithProfiles = protocolFields.length >= 15 && ((_b = protocolFields[12]) === null || _b === void 0 ? void 0 : _b.length) === 1 && protocolFields[12][0] === 3;
+            const hasV3MetadataWithoutProfiles = protocolFields.length >= 14 && ((_c = protocolFields[11]) === null || _c === void 0 ? void 0 : _c.length) === 1 && protocolFields[11][0] === 3;
+            const kdfVersionFieldIndex = hasV3MetadataWithProfiles ? 12 : hasV3MetadataWithoutProfiles ? 11 : -1;
             // Build the UMP token from these fields, preserving outpoint
             const t = {
-                // Order matches buildAndSend and serialize/deserialize
-                passwordSalt: decoded.fields[0],
-                passwordPresentationPrimary: decoded.fields[1],
-                passwordRecoveryPrimary: decoded.fields[2],
-                presentationRecoveryPrimary: decoded.fields[3],
-                passwordPrimaryPrivileged: decoded.fields[4],
-                presentationRecoveryPrivileged: decoded.fields[5],
-                presentationHash: decoded.fields[6],
-                recoveryHash: decoded.fields[7],
-                presentationKeyEncrypted: decoded.fields[8],
-                passwordKeyEncrypted: decoded.fields[9],
-                recoveryKeyEncrypted: decoded.fields[10],
-                profilesEncrypted: decoded.fields[12] ? decoded.fields[11] : undefined, // If there's a signature in field 12, use field 11
+                // Core fields (unchanged for all versions)
+                passwordSalt: protocolFields[0],
+                passwordPresentationPrimary: protocolFields[1],
+                passwordRecoveryPrimary: protocolFields[2],
+                presentationRecoveryPrimary: protocolFields[3],
+                passwordPrimaryPrivileged: protocolFields[4],
+                presentationRecoveryPrivileged: protocolFields[5],
+                presentationHash: protocolFields[6],
+                recoveryHash: protocolFields[7],
+                presentationKeyEncrypted: protocolFields[8],
+                passwordKeyEncrypted: protocolFields[9],
+                recoveryKeyEncrypted: protocolFields[10],
                 currentOutpoint: outpoint
             };
+            // Encrypted profiles (optional, all versions)
+            const hasProfilesField = hasV3MetadataWithProfiles || (!hasV3MetadataWithoutProfiles && !!protocolFields[11]);
+            if (hasProfilesField && protocolFields[11] && protocolFields[11].length > 0) {
+                t.profilesEncrypted = protocolFields[11];
+            }
+            // V3 fields: umpVersion, kdfAlgorithm, kdfParams (fields 12, 13, 14)
+            if (kdfVersionFieldIndex !== -1) {
+                t.umpVersion = protocolFields[kdfVersionFieldIndex][0]; // Single byte value 3
+                const kdfAlgorithmField = protocolFields[kdfVersionFieldIndex + 1];
+                const kdfParamsField = protocolFields[kdfVersionFieldIndex + 2];
+                if (!kdfAlgorithmField || !kdfParamsField) {
+                    return t;
+                }
+                const kdfAlgorithm = sdk_1.Utils.toUTF8(kdfAlgorithmField);
+                const kdfParamsJson = sdk_1.Utils.toUTF8(kdfParamsField);
+                try {
+                    const kdfParams = JSON.parse(kdfParamsJson);
+                    t.passwordKdf = {
+                        algorithm: kdfAlgorithm,
+                        iterations: kdfParams.iterations,
+                        memoryKiB: kdfParams.memoryKiB,
+                        parallelism: kdfParams.parallelism,
+                        hashLength: kdfParams.hashLength
+                    };
+                }
+                catch (e) {
+                    console.warn('Failed to parse v3 KDF params:', e);
+                }
+            }
             return t;
         }
         catch (e) {
@@ -336,8 +487,10 @@ class CWIStyleWalletManager {
      * @param passwordRetriever A function to request the user's password.
      * @param newWalletFunder   Optional function to fund a new wallet.
      * @param stateSnapshot     Optional previously saved state snapshot.
+     * @param kdfConfig         Optional KDF configuration for new UMP tokens.
      */
-    constructor(adminOriginator, walletBuilder, interactor = new OverlayUMPTokenInteractor(), recoveryKeySaver, passwordRetriever, newWalletFunder, stateSnapshot) {
+    constructor(adminOriginator, walletBuilder, interactor = new OverlayUMPTokenInteractor(), recoveryKeySaver, passwordRetriever, newWalletFunder, stateSnapshot, kdfConfig) {
+        var _a, _b, _c, _d, _e;
         /**
          * Current mode of authentication.
          */
@@ -361,6 +514,14 @@ class CWIStyleWalletManager {
         this.passwordRetriever = passwordRetriever;
         this.authenticated = false;
         this.newWalletFunder = newWalletFunder;
+        // Initialize KDF config with Argon2id defaults for v3 tokens
+        this.kdfConfig = {
+            algorithm: (_a = kdfConfig === null || kdfConfig === void 0 ? void 0 : kdfConfig.algorithm) !== null && _a !== void 0 ? _a : 'argon2id',
+            iterations: (_b = kdfConfig === null || kdfConfig === void 0 ? void 0 : kdfConfig.iterations) !== null && _b !== void 0 ? _b : exports.ARGON2ID_DEFAULT_ITERATIONS,
+            memoryKiB: (_c = kdfConfig === null || kdfConfig === void 0 ? void 0 : kdfConfig.memoryKiB) !== null && _c !== void 0 ? _c : exports.ARGON2ID_DEFAULT_MEMORY_KIB,
+            parallelism: (_d = kdfConfig === null || kdfConfig === void 0 ? void 0 : kdfConfig.parallelism) !== null && _d !== void 0 ? _d : exports.ARGON2ID_DEFAULT_PARALLELISM,
+            hashLength: (_e = kdfConfig === null || kdfConfig === void 0 ? void 0 : kdfConfig.hashLength) !== null && _e !== void 0 ? _e : exports.ARGON2ID_DEFAULT_HASH_LENGTH
+        };
         // If a saved snapshot is provided, attempt to load it.
         // Note: loadSnapshot now returns a promise. We don't await it here,
         // as the constructor must be synchronous. The caller should check
@@ -413,7 +574,8 @@ class CWIStyleWalletManager {
             if (!this.currentUMPToken) {
                 throw new Error('Provide presentation or recovery key first.');
             }
-            const derivedPasswordKey = await pbkdf2NativeOrJs(sdk_1.Utils.toArray(password, 'utf8'), this.currentUMPToken.passwordSalt, exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
+            // Use token-driven KDF (legacy PBKDF2 or v3 Argon2id)
+            const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, sdk_1.Utils.toArray(password, 'utf8'));
             let rootPrimaryKey;
             let rootPrivilegedKey; // Only needed for recovery mode
             if (this.authenticationMode === 'presentation-key-and-password') {
@@ -447,7 +609,12 @@ class CWIStyleWalletManager {
             const recoveryKey = (0, sdk_1.Random)(32);
             await this.recoveryKeySaver(recoveryKey);
             const passwordSalt = (0, sdk_1.Random)(32);
-            const passwordKey = await pbkdf2NativeOrJs(sdk_1.Utils.toArray(password, 'utf8'), passwordSalt, exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
+            // Build temporary token with KDF config for password derivation
+            const tempTokenForKdf = {
+                passwordSalt,
+                passwordKdf: this.kdfConfig
+            };
+            const passwordKey = await derivePasswordKey(tempTokenForKdf, sdk_1.Utils.toArray(password, 'utf8'));
             const rootPrimaryKey = (0, sdk_1.Random)(32);
             const rootPrivilegedKey = (0, sdk_1.Random)(32);
             // Build XOR keys
@@ -457,7 +624,7 @@ class CWIStyleWalletManager {
             const primaryPassword = new sdk_1.SymmetricKey(this.XOR(rootPrimaryKey, passwordKey));
             // Temp manager for encryption
             const tempPrivilegedKeyManager = new PrivilegedKeyManager_1.PrivilegedKeyManager(async () => new sdk_1.PrivateKey(rootPrivilegedKey));
-            // Build new UMP token (no profiles initially)
+            // Build new UMP token (v3 with KDF metadata, no profiles initially)
             const newToken = {
                 passwordSalt,
                 passwordPresentationPrimary: presentationPassword.encrypt(rootPrimaryKey),
@@ -482,7 +649,9 @@ class CWIStyleWalletManager {
                     protocolID: [2, 'admin key wrapping'],
                     keyID: '1'
                 })).ciphertext,
-                profilesEncrypted: undefined // No profiles yet
+                profilesEncrypted: undefined, // No profiles yet
+                umpVersion: 3, // UMP protocol version 3
+                passwordKdf: this.kdfConfig // KDF metadata for v3
             };
             this.currentUMPToken = newToken;
             // Setup root infrastructure and switch to default profile
@@ -495,7 +664,8 @@ class CWIStyleWalletManager {
                 }
                 catch (e) {
                     console.error('Error funding new wallet:', e);
-                    // Decide if this should halt the process or just log
+                    const message = e instanceof Error ? e.message : String(e);
+                    throw new Error(`Failed to fund new wallet before publishing UMP token: ${message}`);
                 }
             }
             // Publish the new UMP token *after* potentially funding
@@ -803,11 +973,18 @@ class CWIStyleWalletManager {
      * Changes the user's password. Re-wraps keys and updates the UMP token.
      */
     async changePassword(newPassword) {
+        var _a;
         if (!this.authenticated || !this.currentUMPToken || !this.rootPrimaryKey || !this.rootPrivilegedKeyManager) {
             throw new Error('Not authenticated or missing required data.');
         }
         const passwordSalt = (0, sdk_1.Random)(32);
-        const newPasswordKey = await pbkdf2NativeOrJs(sdk_1.Utils.toArray(newPassword, 'utf8'), passwordSalt, exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
+        // Preserve current token's KDF metadata (or use manager's kdfConfig for legacy tokens)
+        const kdfToUse = (_a = this.currentUMPToken.passwordKdf) !== null && _a !== void 0 ? _a : this.kdfConfig;
+        const tempTokenForKdf = {
+            passwordSalt,
+            passwordKdf: kdfToUse
+        };
+        const newPasswordKey = await derivePasswordKey(tempTokenForKdf, sdk_1.Utils.toArray(newPassword, 'utf8'));
         // Decrypt existing factors needed for re-encryption, using the *root* privileged key manager
         const recoveryKey = await this.getFactor('recoveryKey');
         const presentationKey = await this.getFactor('presentationKey');
@@ -936,6 +1113,7 @@ class CWIStyleWalletManager {
     async updateAuthFactors(passwordSalt, passwordKey, presentationKey, recoveryKey, rootPrimaryKey, rootPrivilegedKey, // Explicitly pass the root key bytes
     profiles // Pass current/new profiles list
     ) {
+        var _a;
         if (!this.authenticated || !this.rootPrimaryKey || !this.currentUMPToken) {
             throw new Error('Wallet is not properly authenticated or missing data for update.');
         }
@@ -958,7 +1136,8 @@ class CWIStyleWalletManager {
             const profilesBytes = sdk_1.Utils.toArray(profilesJson, 'utf8');
             profilesEncrypted = new sdk_1.SymmetricKey(rootPrimaryKey).encrypt(profilesBytes);
         }
-        // Construct the new UMP token data
+        // Construct the new UMP token data (preserve or upgrade to v3 with KDF metadata)
+        const kdfMetadata = (_a = this.currentUMPToken.passwordKdf) !== null && _a !== void 0 ? _a : this.kdfConfig;
         const newTokenData = {
             passwordSalt,
             passwordPresentationPrimary: presentationPassword.encrypt(rootPrimaryKey),
@@ -983,7 +1162,9 @@ class CWIStyleWalletManager {
                 protocolID: [2, 'admin key wrapping'],
                 keyID: '1'
             })).ciphertext,
-            profilesEncrypted // Add encrypted profiles
+            profilesEncrypted, // Add encrypted profiles
+            umpVersion: 3, // UMP protocol version 3
+            passwordKdf: kdfMetadata // Preserve or upgrade KDF metadata
             // currentOutpoint will be set after publishing
         };
         // We need the wallet built for the DEFAULT profile to publish the UMP token.
@@ -1015,15 +1196,16 @@ class CWIStyleWalletManager {
         }
     }
     /**
-     * Serializes a UMP token to binary format (Version 2 with optional profiles).
-     * Layout: [1 byte version=2] + [11 * (varint len + bytes) for standard fields] + [1 byte profile_flag] + [IF flag=1 THEN varint len + profile bytes] + [varint len + outpoint bytes]
+     * Serializes a UMP token to binary format (Version 3 with KDF metadata, Version 2 with profiles).
+     * V3 Layout: [1 byte version=3] + [11 * (varint len + bytes) for standard fields] + [1 byte profile_flag] + [IF flag=1 THEN varint len + profile bytes] + [1 byte kdf_flag] + [IF flag=1 THEN kdf metadata] + [varint len + outpoint bytes]
      */
     serializeUMPToken(token) {
         if (!token.currentOutpoint) {
             throw new Error('Token must have outpoint for serialization');
         }
         const writer = new sdk_1.Utils.Writer();
-        writer.writeUInt8(2); // Version 2
+        const hasKdfMetadata = token.umpVersion === 3 && token.passwordKdf;
+        writer.writeUInt8(hasKdfMetadata ? 3 : 2); // Version 3 for KDF, 2 for legacy
         const writeArray = (arr) => {
             writer.writeVarIntNum(arr.length);
             writer.write(arr);
@@ -1038,7 +1220,7 @@ class CWIStyleWalletManager {
         writeArray(token.presentationHash); // 6
         writeArray(token.recoveryHash); // 7
         writeArray(token.presentationKeyEncrypted); // 8
-        writeArray(token.passwordKeyEncrypted); // 9 - Swapped order vs original doc comment
+        writeArray(token.passwordKeyEncrypted); // 9
         writeArray(token.recoveryKeyEncrypted); // 10
         // Write optional profiles field
         if (token.profilesEncrypted && token.profilesEncrypted.length > 0) {
@@ -1048,6 +1230,32 @@ class CWIStyleWalletManager {
         else {
             writer.writeUInt8(0); // Flag indicating no profiles
         }
+        // V3: Write KDF metadata
+        if (hasKdfMetadata) {
+            writer.writeUInt8(1); // Flag indicating KDF metadata present
+            writer.writeUInt8(token.umpVersion); // On-chain UMP version
+            const algorithmBytes = sdk_1.Utils.toArray(token.passwordKdf.algorithm, 'utf8');
+            writeArray(algorithmBytes);
+            // Serialize KDF params as JSON
+            const kdfParams = {
+                iterations: token.passwordKdf.iterations
+            };
+            if (token.passwordKdf.memoryKiB !== undefined) {
+                kdfParams.memoryKiB = token.passwordKdf.memoryKiB;
+            }
+            if (token.passwordKdf.parallelism !== undefined) {
+                kdfParams.parallelism = token.passwordKdf.parallelism;
+            }
+            if (token.passwordKdf.hashLength !== undefined) {
+                kdfParams.hashLength = token.passwordKdf.hashLength;
+            }
+            const kdfParamsBytes = sdk_1.Utils.toArray(JSON.stringify(kdfParams), 'utf8');
+            writeArray(kdfParamsBytes);
+        }
+        else if (writer.toArray()[0] === 3) {
+            // Version 3 without KDF metadata (shouldn't happen, but handle gracefully)
+            writer.writeUInt8(0); // Flag indicating no KDF metadata
+        }
         // Write outpoint string
         const outpointBytes = sdk_1.Utils.toArray(token.currentOutpoint, 'utf8');
         writer.writeVarIntNum(outpointBytes.length);
@@ -1055,19 +1263,19 @@ class CWIStyleWalletManager {
         return writer.toArray();
     }
     /**
-     * Deserializes a UMP token from binary format (Handles Version 1 and 2).
+     * Deserializes a UMP token from binary format (Handles Version 1, 2, and 3).
      */
     deserializeUMPToken(bin) {
         const reader = new sdk_1.Utils.Reader(bin);
         const version = reader.readUInt8();
-        if (version !== 1 && version !== 2) {
+        if (version !== 1 && version !== 2 && version !== 3) {
             throw new Error(`Unsupported UMP token serialization version: ${version}`);
         }
         const readArray = () => {
             const length = reader.readVarIntNum();
             return reader.read(length);
         };
-        // Read standard fields (order matches serialization V2)
+        // Read standard fields (order matches serialization)
         const passwordSalt = readArray(); // 0
         const passwordPresentationPrimary = readArray(); // 1
         const passwordRecoveryPrimary = readArray(); // 2
@@ -1079,14 +1287,40 @@ class CWIStyleWalletManager {
         const presentationKeyEncrypted = readArray(); // 8
         const passwordKeyEncrypted = readArray(); // 9
         const recoveryKeyEncrypted = readArray(); // 10
-        // Read optional profiles (only in V2)
+        // Read optional profiles (V2 and V3)
         let profilesEncrypted;
-        if (version === 2) {
+        if (version >= 2) {
             const profilesFlag = reader.readUInt8();
             if (profilesFlag === 1) {
                 profilesEncrypted = readArray();
             }
         }
+        // Read KDF metadata (V3 only)
+        let umpVersion;
+        let passwordKdf;
+        if (version === 3) {
+            const kdfFlag = reader.readUInt8();
+            if (kdfFlag === 1) {
+                umpVersion = reader.readUInt8(); // On-chain UMP version
+                const algorithmBytes = readArray();
+                const algorithm = sdk_1.Utils.toUTF8(algorithmBytes);
+                const kdfParamsBytes = readArray();
+                const kdfParamsJson = sdk_1.Utils.toUTF8(kdfParamsBytes);
+                try {
+                    const kdfParams = JSON.parse(kdfParamsJson);
+                    passwordKdf = {
+                        algorithm,
+                        iterations: kdfParams.iterations,
+                        memoryKiB: kdfParams.memoryKiB,
+                        parallelism: kdfParams.parallelism,
+                        hashLength: kdfParams.hashLength
+                    };
+                }
+                catch (e) {
+                    console.warn('Failed to parse KDF params during deserialization:', e);
+                }
+            }
+        }
         // Read outpoint string
         const outpointLen = reader.readVarIntNum();
         const outpointBytes = reader.read(outpointLen);
@@ -1101,10 +1335,12 @@ class CWIStyleWalletManager {
             presentationHash,
             recoveryHash,
             presentationKeyEncrypted,
-            passwordKeyEncrypted, // Corrected order
+            passwordKeyEncrypted,
             recoveryKeyEncrypted,
-            profilesEncrypted, // May be undefined
-            currentOutpoint
+            profilesEncrypted,
+            currentOutpoint,
+            umpVersion,
+            passwordKdf
         };
         return token;
     }
@@ -1134,9 +1370,9 @@ class CWIStyleWalletManager {
                 return tempKey;
             }
             // 2. Otherwise, derive from password
-            const password = await this.passwordRetriever(reason, (passwordCandidate) => {
+            const password = await this.passwordRetriever(reason, async (passwordCandidate) => {
                 try {
-                    const derivedPasswordKey = sdk_1.Hash.pbkdf2(sdk_1.Utils.toArray(passwordCandidate, 'utf8'), this.currentUMPToken.passwordSalt, exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
+                    const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, sdk_1.Utils.toArray(passwordCandidate, 'utf8'));
                     const privilegedDecryptor = this.XOR(this.rootPrimaryKey, derivedPasswordKey);
                     const decryptedPrivileged = new sdk_1.SymmetricKey(privilegedDecryptor).decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
                     return !!decryptedPrivileged; // Test passes if decryption works
@@ -1145,8 +1381,8 @@ class CWIStyleWalletManager {
                     return false;
                 }
             });
-            // Decrypt the root privileged key using the confirmed password
-            const derivedPasswordKey = await pbkdf2NativeOrJs(sdk_1.Utils.toArray(password, 'utf8'), this.currentUMPToken.passwordSalt, exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
+            // Decrypt the root privileged key using the confirmed password (with token-driven KDF)
+            const derivedPasswordKey = await derivePasswordKey(this.currentUMPToken, sdk_1.Utils.toArray(password, 'utf8'));
             const privilegedDecryptor = this.XOR(this.rootPrimaryKey, derivedPasswordKey);
             const rootPrivilegedBytes = new sdk_1.SymmetricKey(privilegedDecryptor).decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
             return new sdk_1.PrivateKey(rootPrivilegedBytes); // Return the ROOT key object