@bsv/wallet-toolbox 2.4.3 → 2.4.20

package/out/src/CWIStyleWalletManager.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.CWIStyleWalletManager = exports.OverlayUMPTokenInteractor = exports.UMPTokenLookupError = exports.DEFAULT_PROFILE_ID = exports.MAX_STATE_SNAPSHOT_BYTES = exports.PBKDF2_MAX_ITERATIONS = exports.KDF_MAX_HASH_LENGTH = exports.ARGON2ID_MAX_PARALLELISM = exports.ARGON2ID_MAX_MEMORY_KIB = exports.ARGON2ID_MAX_ITERATIONS = 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");
+const hashWasm_1 = require("./utility/hashWasm");
 /**
  * Number of rounds used in PBKDF2 for deriving password keys.
  */
@@ -15,6 +15,72 @@ exports.ARGON2ID_DEFAULT_ITERATIONS = 7;
 exports.ARGON2ID_DEFAULT_MEMORY_KIB = 131072;
 exports.ARGON2ID_DEFAULT_PARALLELISM = 1;
 exports.ARGON2ID_DEFAULT_HASH_LENGTH = 32;
+exports.ARGON2ID_MAX_ITERATIONS = 20;
+exports.ARGON2ID_MAX_MEMORY_KIB = 262144;
+exports.ARGON2ID_MAX_PARALLELISM = 16;
+exports.KDF_MAX_HASH_LENGTH = 64;
+exports.PBKDF2_MAX_ITERATIONS = 10_000_000;
+exports.MAX_STATE_SNAPSHOT_BYTES = 16 * 1024 * 1024;
+function isPositiveIntegerInRange(value, maximum) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= maximum;
+}
+function isValidKdfConfig(kdf) {
+    if (kdf == null)
+        return false;
+    if (!isPositiveIntegerInRange(kdf.iterations, kdf.algorithm === 'argon2id' ? exports.ARGON2ID_MAX_ITERATIONS : exports.PBKDF2_MAX_ITERATIONS)) {
+        return false;
+    }
+    if (kdf.algorithm === 'pbkdf2-sha512') {
+        return kdf.hashLength === undefined || isPositiveIntegerInRange(kdf.hashLength, exports.KDF_MAX_HASH_LENGTH);
+    }
+    if (kdf.algorithm !== 'argon2id')
+        return false;
+    return (isPositiveIntegerInRange(kdf.memoryKiB, exports.ARGON2ID_MAX_MEMORY_KIB) &&
+        isPositiveIntegerInRange(kdf.parallelism, exports.ARGON2ID_MAX_PARALLELISM) &&
+        isPositiveIntegerInRange(kdf.hashLength, exports.KDF_MAX_HASH_LENGTH));
+}
+function findKdfVersionFieldIndex(protocolFields) {
+    const hasMetadataWithProfiles = protocolFields.length >= 15 &&
+        protocolFields[12]?.length === 1 &&
+        protocolFields[12][0] === 3;
+    if (hasMetadataWithProfiles)
+        return 12;
+    const hasMetadataWithoutProfiles = protocolFields.length >= 14 &&
+        protocolFields[11]?.length === 1 &&
+        protocolFields[11][0] === 3;
+    return hasMetadataWithoutProfiles ? 11 : -1;
+}
+function addProfilesField(token, protocolFields, kdfVersionFieldIndex) {
+    const hasProfilesField = kdfVersionFieldIndex === 12 || (kdfVersionFieldIndex !== 11 && protocolFields[11] != null);
+    if (!hasProfilesField || protocolFields[11].length === 0)
+        return true;
+    if (protocolFields[11].length > exports.MAX_STATE_SNAPSHOT_BYTES)
+        return false;
+    token.profilesEncrypted = protocolFields[11];
+    return true;
+}
+function addPasswordKdf(token, protocolFields, kdfVersionFieldIndex) {
+    if (kdfVersionFieldIndex === -1)
+        return true;
+    const kdfAlgorithmField = protocolFields[kdfVersionFieldIndex + 1];
+    const kdfParamsField = protocolFields[kdfVersionFieldIndex + 2];
+    if (kdfAlgorithmField == null || kdfParamsField == null || kdfParamsField.length > 1024) {
+        return false;
+    }
+    const kdfParams = JSON.parse(sdk_1.Utils.toUTF8(kdfParamsField));
+    const passwordKdf = {
+        algorithm: sdk_1.Utils.toUTF8(kdfAlgorithmField),
+        iterations: kdfParams.iterations,
+        memoryKiB: kdfParams.memoryKiB,
+        parallelism: kdfParams.parallelism,
+        hashLength: kdfParams.hashLength
+    };
+    if (!isValidKdfConfig(passwordKdf))
+        return false;
+    token.umpVersion = 3;
+    token.passwordKdf = passwordKdf;
+    return true;
+}
 function isLikelyDerSignatureField(field) {
     if (!field || field.length < 8 || field.length > 80) {
         return false;
@@ -39,7 +105,7 @@ function stripVerifiedPushDropSignature(fields, lockingPublicKey) {
         for (let i = 0; i < protocolFieldCount; i++) {
             dataLength += fields[i].length;
         }
-        const dataToVerify = new Array(dataLength);
+        const dataToVerify = Array.from({ length: dataLength }, () => 0);
         let writeOffset = 0;
         for (let i = 0; i < protocolFieldCount; i++) {
             const field = fields[i];
@@ -82,14 +148,13 @@ async function pbkdf2NativeOrWasm(passwordBytes, salt, iterations, keyLen, hash
             }, baseKey, keyLen * 8);
             return Array.from(new Uint8Array(bits));
         }
-        catch (webCryptoErr) {
+        catch {
             // WebCrypto is unavailable or refused the algorithm (e.g. non-secure context, old
             // Safari).  Fall through to the pure-JS hash-wasm implementation below.
-            console.debug('[pbkdf2] WebCrypto path failed, falling back to JS implementation', webCryptoErr);
         }
     }
-    const hashFunction = hash === 'sha256' ? (0, hash_wasm_1.createSHA256)() : (0, hash_wasm_1.createSHA512)();
-    const derived = await (0, hash_wasm_1.pbkdf2)({
+    const hashFunction = hash === 'sha256' ? (0, hashWasm_1.createSHA256)() : (0, hashWasm_1.createSHA512)();
+    const derived = await (0, hashWasm_1.pbkdf2)({
         password: new Uint8Array(passwordBytes),
         salt: new Uint8Array(salt),
         iterations,
@@ -111,8 +176,11 @@ async function pbkdf2NativeOrWasm(passwordBytes, salt, iterations, keyLen, hash
  */
 async function derivePasswordKey(token, passwordBytes, overrideKdf) {
     const kdf = overrideKdf || token.passwordKdf;
+    if (kdf != null && !isValidKdfConfig(kdf)) {
+        throw new Error('UMP token contains unsupported or unsafe KDF parameters.');
+    }
     // Legacy token or explicit PBKDF2 request
-    if ((kdf == null) || kdf.algorithm === 'pbkdf2-sha512') {
+    if (kdf == null || kdf.algorithm === 'pbkdf2-sha512') {
         return await pbkdf2NativeOrWasm(passwordBytes, token.passwordSalt, kdf?.iterations ?? exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
     }
     // Argon2id path (UMP v3)
@@ -121,7 +189,7 @@ async function derivePasswordKey(token, passwordBytes, overrideKdf) {
         const memorySize = kdf.memoryKiB ?? exports.ARGON2ID_DEFAULT_MEMORY_KIB;
         const parallelism = kdf.parallelism ?? exports.ARGON2ID_DEFAULT_PARALLELISM;
         const hashLength = kdf.hashLength ?? exports.ARGON2ID_DEFAULT_HASH_LENGTH;
-        const hash = await (0, hash_wasm_1.argon2id)({
+        const hash = await (0, hashWasm_1.argon2id)({
             password: new Uint8Array(passwordBytes),
             salt: new Uint8Array(token.passwordSalt),
             iterations,
@@ -138,6 +206,43 @@ async function derivePasswordKey(token, passwordBytes, overrideKdf) {
  * Unique Identifier for the default profile (16 zero bytes).
  */
 exports.DEFAULT_PROFILE_ID = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+function isByteArrayOfLength(value, length) {
+    return (Array.isArray(value) &&
+        value.length === length &&
+        value.every(byte => Number.isInteger(byte) && byte >= 0 && byte <= 255));
+}
+function isValidProfile(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const profile = value;
+    return (typeof profile.name === 'string' &&
+        profile.name.length > 0 &&
+        profile.name.length <= 250 &&
+        isByteArrayOfLength(profile.id, 16) &&
+        isByteArrayOfLength(profile.primaryPad, 32) &&
+        isByteArrayOfLength(profile.privilegedPad, 32) &&
+        typeof profile.createdAt === 'number' &&
+        Number.isFinite(profile.createdAt) &&
+        profile.createdAt >= 0);
+}
+/**
+ * Raised when UMP absence cannot be established authoritatively.
+ *
+ * Callers must offer retry/recovery rather than treating this error as a new
+ * account. Diagnostics contain counts only and never hashes, keys, or tokens.
+ */
+class UMPTokenLookupError extends Error {
+    reason;
+    diagnostics;
+    code = 'WERR_UMP_LOOKUP_INDETERMINATE';
+    constructor(reason, diagnostics, options) {
+        super('Unable to determine whether the wallet account already exists. Retry or use account recovery.', options);
+        this.reason = reason;
+        this.diagnostics = diagnostics;
+        this.name = 'UMPTokenLookupError';
+    }
+}
+exports.UMPTokenLookupError = UMPTokenLookupError;
 /**
  * @class OverlayUMPTokenInteractor
  *
@@ -160,15 +265,17 @@ class OverlayUMPTokenInteractor {
      * under the `tm_users` topic to overlay service peers.
      */
     broadcaster;
+    telemetry;
     /**
      * Construct a new OverlayUMPTokenInteractor.
      *
      * @param resolver     A LookupResolver instance for performing overlay queries (ls_users).
      * @param broadcaster  A SHIPBroadcaster instance for sharing new or updated tokens across the `tm_users` overlay.
      */
-    constructor(resolver = new sdk_1.LookupResolver(), broadcaster = new sdk_1.SHIPBroadcaster(['tm_users'])) {
+    constructor(resolver = new sdk_1.LookupResolver(), broadcaster = new sdk_1.SHIPBroadcaster(['tm_users']), telemetry) {
         this.resolver = resolver;
         this.broadcaster = broadcaster;
+        this.telemetry = new sdk_1.Telemetry(telemetry);
     }
     /**
      * Finds a UMP token on-chain by the given presentation key hash, if it exists.
@@ -178,13 +285,10 @@ class OverlayUMPTokenInteractor {
      * @returns A UMPToken object (including currentOutpoint) if found, otherwise undefined.
      */
     async findByPresentationKeyHash(hash) {
-        // Query ls_users for the given presentationHash
-        const question = {
+        return await this.findToken({
             service: 'ls_users',
             query: { presentationHash: sdk_1.Utils.toHex(hash) }
-        };
-        const answer = await this.resolver.query(question);
-        return this.parseLookupAnswer(answer);
+        }, 'presentation');
     }
     /**
      * Finds a UMP token on-chain by the given recovery key hash, if it exists.
@@ -194,12 +298,142 @@ class OverlayUMPTokenInteractor {
      * @returns A UMPToken object (including currentOutpoint) if found, otherwise undefined.
      */
     async findByRecoveryKeyHash(hash) {
-        const question = {
+        return await this.findToken({
             service: 'ls_users',
             query: { recoveryHash: sdk_1.Utils.toHex(hash) }
+        }, 'recovery');
+    }
+    async findToken(question, lookupKind) {
+        const correlationId = this.telemetry.enabled === true ? this.telemetry.createCorrelationId() : undefined;
+        const startedAt = Date.now();
+        this.telemetry.capture({
+            name: 'wallet-toolbox.ump.lookup.started',
+            component: 'wallet-toolbox.ump',
+            severity: 'debug',
+            correlationId,
+            attributes: { lookupKind }
+        });
+        let resolution;
+        try {
+            resolution = await this.resolver.queryDetailed(question, undefined, {
+                waitForAllHosts: true,
+                correlationId
+            });
+        }
+        catch (error) {
+            const diagnostics = this.emptyLookupDiagnostics(correlationId);
+            this.captureLookupFailure(lookupKind, 'lookup-unavailable', diagnostics, startedAt, error);
+            throw new UMPTokenLookupError('lookup-unavailable', diagnostics, { cause: error });
+        }
+        const diagnostics = this.toLookupDiagnostics(resolution);
+        if (resolution.answer.outputs.length === 0) {
+            const authoritative = resolution.progress.isFinal &&
+                resolution.progress.hostCount > 0 &&
+                resolution.progress.completedHosts === resolution.progress.hostCount &&
+                resolution.progress.successfulHosts === resolution.progress.hostCount &&
+                resolution.progress.emptyHosts === resolution.progress.hostCount &&
+                resolution.progress.failedHosts === 0 &&
+                resolution.progress.rejectedHosts === 0 &&
+                resolution.progress.freeformHosts === 0;
+            if (!authoritative) {
+                this.captureLookupFailure(lookupKind, 'lookup-incomplete', diagnostics, startedAt);
+                throw new UMPTokenLookupError('lookup-incomplete', diagnostics);
+            }
+            this.telemetry.capture({
+                name: 'wallet-toolbox.ump.lookup.completed',
+                component: 'wallet-toolbox.ump',
+                severity: 'info',
+                correlationId: diagnostics.correlationId,
+                attributes: {
+                    lookupKind,
+                    result: 'not-found',
+                    durationMs: Date.now() - startedAt,
+                    ...this.lookupDiagnosticAttributes(diagnostics)
+                }
+            });
+            return undefined;
+        }
+        const tokens = this.parseLookupAnswers(resolution.answer);
+        const expectedHash = question.query[lookupKind === 'presentation' ? 'presentationHash' : 'recoveryHash'].toLowerCase();
+        const everyOutputValidAndMatching = tokens.length === resolution.answer.outputs.length &&
+            tokens.every(token => sdk_1.Utils.toHex(lookupKind === 'presentation' ? token.presentationHash : token.recoveryHash).toLowerCase() ===
+                expectedHash);
+        if (!everyOutputValidAndMatching || tokens.length === 0) {
+            this.captureLookupFailure(lookupKind, 'token-malformed', diagnostics, startedAt);
+            throw new UMPTokenLookupError('token-malformed', diagnostics);
+        }
+        if (tokens.length !== 1) {
+            const reason = 'token-ambiguous';
+            this.captureLookupFailure(lookupKind, reason, diagnostics, startedAt);
+            throw new UMPTokenLookupError(reason, diagnostics);
+        }
+        this.telemetry.capture({
+            name: 'wallet-toolbox.ump.lookup.completed',
+            component: 'wallet-toolbox.ump',
+            severity: 'info',
+            correlationId: diagnostics.correlationId,
+            attributes: {
+                lookupKind,
+                result: 'found',
+                durationMs: Date.now() - startedAt,
+                ...this.lookupDiagnosticAttributes(diagnostics)
+            }
+        });
+        return tokens[0];
+    }
+    emptyLookupDiagnostics(correlationId) {
+        return {
+            hostCount: 0,
+            completedHosts: 0,
+            successfulHosts: 0,
+            emptyHosts: 0,
+            failedHosts: 0,
+            rejectedHosts: 0,
+            freeformHosts: 0,
+            outputCount: 0,
+            ...(correlationId !== undefined ? { correlationId } : {})
         };
-        const answer = await this.resolver.query(question);
-        return this.parseLookupAnswer(answer);
+    }
+    toLookupDiagnostics(resolution) {
+        const progress = resolution.progress;
+        return {
+            hostCount: progress.hostCount,
+            completedHosts: progress.completedHosts,
+            successfulHosts: progress.successfulHosts,
+            emptyHosts: progress.emptyHosts,
+            failedHosts: progress.failedHosts,
+            rejectedHosts: progress.rejectedHosts,
+            freeformHosts: progress.freeformHosts,
+            outputCount: resolution.answer.outputs.length,
+            ...(progress.correlationId !== undefined ? { correlationId: progress.correlationId } : {})
+        };
+    }
+    lookupDiagnosticAttributes(diagnostics) {
+        return {
+            hostCount: diagnostics.hostCount,
+            completedHosts: diagnostics.completedHosts,
+            successfulHosts: diagnostics.successfulHosts,
+            emptyHosts: diagnostics.emptyHosts,
+            failedHosts: diagnostics.failedHosts,
+            rejectedHosts: diagnostics.rejectedHosts,
+            freeformHosts: diagnostics.freeformHosts,
+            outputCount: diagnostics.outputCount
+        };
+    }
+    captureLookupFailure(lookupKind, reason, diagnostics, startedAt, error) {
+        this.telemetry.capture({
+            name: 'wallet-toolbox.ump.lookup.indeterminate',
+            component: 'wallet-toolbox.ump',
+            severity: 'warn',
+            correlationId: diagnostics.correlationId,
+            attributes: {
+                lookupKind,
+                reason,
+                durationMs: Date.now() - startedAt,
+                ...this.lookupDiagnosticAttributes(diagnostics)
+            },
+            error
+        });
     }
     /**
      * Creates or updates (replaces) a UMP token on-chain. If `oldTokenToConsume` is provided,
@@ -224,7 +458,13 @@ class OverlayUMPTokenInteractor {
         // 2) Resolve the old-token input (if provided) and create the action.
         const { resolvedOldToken, inputToken } = await this.resolveOldTokenInput(oldTokenToConsume);
         const inputs = resolvedOldToken?.currentOutpoint
-            ? [{ outpoint: resolvedOldToken.currentOutpoint, unlockingScriptLength: 73, inputDescription: 'Consume old UMP token' }]
+            ? [
+                {
+                    outpoint: resolvedOldToken.currentOutpoint,
+                    unlockingScriptLength: 73,
+                    inputDescription: 'Consume old UMP token'
+                }
+            ]
             : [];
         const createResult = await this.createUMPAction(wallet, adminOriginator, inputs, tokenOutput, inputToken, resolvedOldToken);
         // 3) If the wallet fully processed it (no signable tx), broadcast and return.
@@ -256,7 +496,7 @@ class OverlayUMPTokenInteractor {
         if (token.profilesEncrypted != null)
             fields[11] = token.profilesEncrypted;
         if (token.umpVersion === 3 && token.passwordKdf != null) {
-            const vi = (token.profilesEncrypted == null) ? 11 : 12;
+            const vi = token.profilesEncrypted == null ? 11 : 12;
             fields[vi] = [token.umpVersion];
             fields[vi + 1] = sdk_1.Utils.toArray(token.passwordKdf.algorithm, 'utf8');
             const kdfParams = { iterations: token.passwordKdf.iterations };
@@ -275,28 +515,34 @@ class OverlayUMPTokenInteractor {
         if (!oldTokenToConsume?.currentOutpoint)
             return { resolvedOldToken: undefined, inputToken: undefined };
         const inputToken = await this.findByOutpoint(oldTokenToConsume.currentOutpoint);
-        if (inputToken == null)
-            return { resolvedOldToken: undefined, inputToken: undefined };
+        if (inputToken == null) {
+            throw new Error('The previous UMP token could not be resolved; refusing to publish a duplicate token.');
+        }
         return { resolvedOldToken: oldTokenToConsume, inputToken };
     }
-    /** Creates the UMP action; falls back to a bare recovery action on failure. */
+    /** Creates the UMP action without dropping a required old-token input on failure. */
     async createUMPAction(wallet, adminOriginator, inputs, outputs, inputToken, resolvedOldToken) {
         try {
             return await wallet.createAction({
-                description: (resolvedOldToken == null) ? 'Create new UMP token' : 'Renew UMP token (consume old, create new)',
+                description: resolvedOldToken == null ? 'Create new UMP token' : 'Renew UMP token (consume old, create new)',
                 inputs,
                 outputs,
                 inputBEEF: inputToken?.beef,
                 options: { randomizeOutputs: false, acceptDelayedBroadcast: false }
             }, adminOriginator);
         }
-        catch (e) {
-            console.error('Error with UMP token update. Attempting a last-ditch effort to get a new one', e);
-            return await wallet.createAction({
-                description: 'Recover UMP token',
-                outputs,
-                options: { randomizeOutputs: false, acceptDelayedBroadcast: false }
-            }, adminOriginator);
+        catch (error) {
+            this.telemetry.capture({
+                name: 'wallet-toolbox.ump.action.failed',
+                component: 'wallet-toolbox.ump',
+                severity: 'error',
+                attributes: {
+                    operation: resolvedOldToken == null ? 'create' : 'renew',
+                    oldTokenInputRequired: resolvedOldToken != null
+                },
+                error
+            });
+            throw error;
         }
     }
     /** Handles a fully-finalized (no signable tx) createAction result — broadcasts and returns outpoint. */
@@ -308,7 +554,7 @@ class OverlayUMPTokenInteractor {
             throw new Error('No final TX data to broadcast.');
         const broadcastTx = sdk_1.Transaction.fromAtomicBEEF(createResult.tx);
         const result = await this.broadcaster.broadcast(broadcastTx);
-        console.log('BROADCAST RESULT', result);
+        this.assertSuccessfulBroadcast(result, 'create-finalized');
         return `${finalTxid}.0`;
     }
     /** Signs the old-token input and broadcasts — used during UMP token renewal. */
@@ -316,27 +562,43 @@ class OverlayUMPTokenInteractor {
         const unlocker = new sdk_1.PushDrop(wallet, adminOriginator).unlock([2, 'admin user management token'], '1', 'self');
         const unlockingScript = await unlocker.sign(partialTx, 0);
         const signResult = await wallet.signAction({ reference, spends: { 0: { unlockingScript: unlockingScript.toHex() } } }, adminOriginator);
-        const finalTxid = signResult.txid || ((signResult.tx == null) ? '' : sdk_1.Transaction.fromAtomicBEEF(signResult.tx).id('hex'));
+        const finalTxid = signResult.txid || (signResult.tx == null ? '' : sdk_1.Transaction.fromAtomicBEEF(signResult.tx).id('hex'));
         if (!finalTxid)
             throw new Error('Could not finalize transaction for renewed UMP token.');
         if (signResult.tx == null)
             throw new Error('Final transaction data missing after signing renewed UMP token.');
         const result = await this.broadcaster.broadcast(sdk_1.Transaction.fromAtomicBEEF(signResult.tx));
-        console.log('BROADCAST RESULT', result);
+        this.assertSuccessfulBroadcast(result, 'renew');
         return `${finalTxid}.0`;
     }
     /** Signs without input spending and broadcasts — used when creating a brand-new UMP token. */
     async signAndBroadcastNewToken(wallet, adminOriginator, reference) {
         const signResult = await wallet.signAction({ reference, spends: {} }, adminOriginator);
-        const finalTxid = signResult.txid || ((signResult.tx == null) ? '' : sdk_1.Transaction.fromAtomicBEEF(signResult.tx).id('hex'));
+        const finalTxid = signResult.txid || (signResult.tx == null ? '' : sdk_1.Transaction.fromAtomicBEEF(signResult.tx).id('hex'));
         if (!finalTxid)
             throw new Error('Failed to finalize new UMP token transaction.');
         if (signResult.tx == null)
             throw new Error('Final transaction data missing after signing new UMP token.');
         const result = await this.broadcaster.broadcast(sdk_1.Transaction.fromAtomicBEEF(signResult.tx));
-        console.log('BROADCAST RESULT', result);
+        this.assertSuccessfulBroadcast(result, 'create');
         return `${finalTxid}.0`;
     }
+    assertSuccessfulBroadcast(result, operation) {
+        const succeeded = result.status === 'success';
+        this.telemetry.capture({
+            name: succeeded ? 'wallet-toolbox.ump.broadcast.completed' : 'wallet-toolbox.ump.broadcast.failed',
+            component: 'wallet-toolbox.ump',
+            severity: succeeded ? 'info' : 'error',
+            attributes: {
+                operation,
+                outcome: result.status,
+                ...(result.status === 'error' ? { code: result.code } : {})
+            }
+        });
+        if (!succeeded) {
+            throw new Error(`UMP token broadcast failed (${result.code}).`);
+        }
+    }
     /**
      * Attempts to parse a LookupAnswer from the UMP lookup service. If successful,
      * extracts the token fields from the resulting transaction and constructs
@@ -346,40 +608,36 @@ class OverlayUMPTokenInteractor {
      * @returns The parsed UMPToken or `undefined` if none found/decodable.
      */
     parseLookupAnswer(answer) {
-        if (answer.type !== 'output-list') {
-            return undefined;
-        }
-        if (!answer.outputs || answer.outputs.length === 0) {
-            return undefined;
+        return this.parseLookupAnswers(answer)[0];
+    }
+    parseLookupAnswers(answer) {
+        if (answer.type !== 'output-list' || answer.outputs.length === 0)
+            return [];
+        const tokens = [];
+        for (const output of answer.outputs) {
+            const token = this.parseLookupOutput(output);
+            if (token != null)
+                tokens.push(token);
         }
-        const { beef, outputIndex } = answer.outputs[0];
+        return tokens;
+    }
+    parseLookupOutput(output) {
         try {
-            const tx = sdk_1.Transaction.fromBEEF(beef);
-            const outpoint = `${tx.id('hex')}.${outputIndex}`;
-            const decoded = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
-            // Expecting 11 or more fields for UMP
-            if (!decoded.fields || decoded.fields.length < 11) {
-                console.warn(`Unexpected number of fields in UMP token: ${decoded.fields?.length}`);
+            const tx = sdk_1.Transaction.fromBEEF(output.beef);
+            const txOutput = tx.outputs[output.outputIndex];
+            if (txOutput == null)
+                return undefined;
+            const decoded = sdk_1.PushDrop.decode(txOutput.lockingScript);
+            if (decoded.fields == null || decoded.fields.length < 11 || decoded.fields.length > 16) {
                 return undefined;
             }
-            // Parse protocol fields, excluding the trailing PushDrop signature only when
-            // it is cryptographically valid for the preceding field payload.
             const 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 && protocolFields[12]?.length === 1 && protocolFields[12][0] === 3;
-            const hasV3MetadataWithoutProfiles = protocolFields.length >= 14 && protocolFields[11]?.length === 1 && protocolFields[11][0] === 3;
-            let kdfVersionFieldIndex;
-            if (hasV3MetadataWithProfiles)
-                kdfVersionFieldIndex = 12;
-            else if (hasV3MetadataWithoutProfiles)
-                kdfVersionFieldIndex = 11;
-            else
-                kdfVersionFieldIndex = -1;
-            // Build the UMP token from these fields, preserving outpoint
-            const t = {
-                // Core fields (unchanged for all versions)
+            if (protocolFields.length < 11 ||
+                protocolFields.slice(0, 11).some(field => field.length === 0 || field.length > exports.MAX_STATE_SNAPSHOT_BYTES)) {
+                return undefined;
+            }
+            const kdfVersionFieldIndex = findKdfVersionFieldIndex(protocolFields);
+            const token = {
                 passwordSalt: protocolFields[0],
                 passwordPresentationPrimary: protocolFields[1],
                 passwordRecoveryPrimary: protocolFields[2],
@@ -391,41 +649,17 @@ class OverlayUMPTokenInteractor {
                 presentationKeyEncrypted: protocolFields[8],
                 passwordKeyEncrypted: protocolFields[9],
                 recoveryKeyEncrypted: protocolFields[10],
-                currentOutpoint: outpoint
+                currentOutpoint: `${tx.id('hex')}.${output.outputIndex}`
             };
-            // 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;
+            if (token.presentationHash.length !== 32 || token.recoveryHash.length !== 32)
+                return undefined;
+            if (!addProfilesField(token, protocolFields, kdfVersionFieldIndex))
+                return undefined;
+            if (!addPasswordKdf(token, protocolFields, kdfVersionFieldIndex))
+                return undefined;
+            return token;
         }
-        catch (e) {
-            console.error('Failed to parse or decode UMP token:', e);
+        catch {
             return undefined;
         }
     }
@@ -435,19 +669,43 @@ class OverlayUMPTokenInteractor {
      * @returns The result so that we can use it to unlock the transaction
      */
     async findByOutpoint(outpoint) {
-        const results = await this.resolver.query({
-            service: 'ls_users',
-            query: {
-                outpoint
-            }
-        });
-        if (results.type !== 'output-list') {
-            return undefined;
+        const correlationId = this.telemetry.enabled === true ? this.telemetry.createCorrelationId() : undefined;
+        const startedAt = Date.now();
+        let resolution;
+        try {
+            resolution = await this.resolver.queryDetailed({
+                service: 'ls_users',
+                query: {
+                    outpoint
+                }
+            }, undefined, {
+                waitForAllHosts: true,
+                correlationId
+            });
         }
-        if (!results.outputs || (results.outputs.length === 0)) {
+        catch (error) {
+            const diagnostics = this.emptyLookupDiagnostics(correlationId);
+            this.captureLookupFailure('outpoint', 'lookup-unavailable', diagnostics, startedAt, error);
+            throw new UMPTokenLookupError('lookup-unavailable', diagnostics, { cause: error });
+        }
+        if (resolution.answer.outputs.length === 0) {
+            const p = resolution.progress;
+            const authoritative = p.isFinal &&
+                p.hostCount > 0 &&
+                p.completedHosts === p.hostCount &&
+                p.successfulHosts === p.hostCount &&
+                p.emptyHosts === p.hostCount &&
+                p.failedHosts === 0 &&
+                p.rejectedHosts === 0 &&
+                p.freeformHosts === 0;
+            if (!authoritative) {
+                const diagnostics = this.toLookupDiagnostics(resolution);
+                this.captureLookupFailure('outpoint', 'lookup-incomplete', diagnostics, startedAt);
+                throw new UMPTokenLookupError('lookup-incomplete', diagnostics);
+            }
             return undefined;
         }
-        return results.outputs[0];
+        return resolution.answer.outputs[0];
     }
 }
 exports.OverlayUMPTokenInteractor = OverlayUMPTokenInteractor;
@@ -468,9 +726,7 @@ class CWIStyleWalletManager {
      * Await `ready` before calling wallet methods after constructing with a snapshot.
      */
     get ready() {
-        if (this._readyInit === undefined) {
-            this._readyInit = this._init();
-        }
+        this._readyInit ??= this._init();
         return this._readyInit;
     }
     _readyInit;
@@ -483,6 +739,10 @@ class CWIStyleWalletManager {
      * The system that locates and publishes UMP tokens on-chain.
      */
     UMPTokenInteractor;
+    /**
+     * Privacy-bounded diagnostic channel for wallet state transitions.
+     */
+    telemetry;
     /**
      * A function called to persist the newly generated recovery key.
      * It should generally trigger a UI prompt where the user is asked to write it down.
@@ -510,7 +770,7 @@ class CWIStyleWalletManager {
     /**
      * Indicates new user or existing user flow.
      */
-    authenticationFlow = 'new-user';
+    authenticationFlow = 'unknown';
     /**
      * The current UMP token in use.
      */
@@ -559,32 +819,54 @@ class CWIStyleWalletManager {
      * @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, kdfConfig) {
+    constructor(...[adminOriginator, walletBuilder, interactor, recoveryKeySaver, passwordRetriever, newWalletFunder, stateSnapshot, kdfConfig, telemetry]) {
         this.adminOriginator = adminOriginator;
         this.walletBuilder = walletBuilder;
-        this.UMPTokenInteractor = interactor;
+        this.telemetry = new sdk_1.Telemetry(telemetry);
+        this.UMPTokenInteractor = interactor ?? new OverlayUMPTokenInteractor(undefined, undefined, telemetry);
         this.recoveryKeySaver = recoveryKeySaver;
         this.passwordRetriever = passwordRetriever;
         this.authenticated = false;
         this.newWalletFunder = newWalletFunder;
         // Initialize KDF config with Argon2id defaults for v3 tokens
+        const kdfAlgorithm = kdfConfig?.algorithm ?? 'argon2id';
         this.kdfConfig = {
-            algorithm: kdfConfig?.algorithm ?? 'argon2id',
-            iterations: kdfConfig?.iterations ?? exports.ARGON2ID_DEFAULT_ITERATIONS,
+            algorithm: kdfAlgorithm,
+            iterations: kdfConfig?.iterations ?? (kdfAlgorithm === 'argon2id' ? exports.ARGON2ID_DEFAULT_ITERATIONS : exports.PBKDF2_NUM_ROUNDS),
             memoryKiB: kdfConfig?.memoryKiB ?? exports.ARGON2ID_DEFAULT_MEMORY_KIB,
             parallelism: kdfConfig?.parallelism ?? exports.ARGON2ID_DEFAULT_PARALLELISM,
             hashLength: kdfConfig?.hashLength ?? exports.ARGON2ID_DEFAULT_HASH_LENGTH
         };
+        if (!isValidKdfConfig(this.kdfConfig)) {
+            throw new Error('Unsupported or unsafe KDF configuration.');
+        }
         // Store snapshot for lazy init; callers await ready before calling wallet methods.
         this._initSnapshot = stateSnapshot;
     }
     async _init() {
         if (this._initSnapshot !== undefined) {
-            await this.loadSnapshot(this._initSnapshot).catch((err) => {
-                console.error('Failed to load snapshot during construction:', err);
-                // Clear potentially partially loaded state. destroy() is synchronous.
-                this.destroy();
+            this.telemetry.capture({
+                name: 'wallet-toolbox.snapshot.initialization.started',
+                component: 'wallet-toolbox.cwi-manager',
+                severity: 'debug'
             });
+            try {
+                await this.loadSnapshot(this._initSnapshot);
+                this.telemetry.capture({
+                    name: 'wallet-toolbox.snapshot.initialization.completed',
+                    component: 'wallet-toolbox.cwi-manager',
+                    severity: 'info'
+                });
+            }
+            catch (error) {
+                this.telemetry.capture({
+                    name: 'wallet-toolbox.snapshot.initialization.failed',
+                    component: 'wallet-toolbox.cwi-manager',
+                    severity: 'error',
+                    error
+                });
+                throw error;
+            }
         }
     }
     // --- Authentication Methods ---
@@ -598,8 +880,35 @@ class CWIStyleWalletManager {
         if (this.authenticationMode === 'recovery-key-and-password') {
             throw new Error('Presentation key is not needed in this mode');
         }
+        if (key.length !== 32 || key.some(byte => !Number.isInteger(byte) || byte < 0 || byte > 255)) {
+            throw new TypeError('Presentation key must contain exactly 32 bytes.');
+        }
+        this.authenticationFlow = 'unknown';
         const hash = sdk_1.Hash.sha256(key);
-        const token = await this.UMPTokenInteractor.findByPresentationKeyHash(hash);
+        const startedAt = Date.now();
+        this.telemetry.capture({
+            name: 'wallet-toolbox.authentication.account-lookup.started',
+            component: 'wallet-toolbox.cwi-manager',
+            severity: 'debug',
+            attributes: { lookupKind: 'presentation' }
+        });
+        let token;
+        try {
+            token = await this.UMPTokenInteractor.findByPresentationKeyHash(hash);
+        }
+        catch (error) {
+            this.telemetry.capture({
+                name: 'wallet-toolbox.authentication.account-lookup.failed',
+                component: 'wallet-toolbox.cwi-manager',
+                severity: 'warn',
+                attributes: {
+                    lookupKind: 'presentation',
+                    durationMs: Date.now() - startedAt
+                },
+                error
+            });
+            throw error;
+        }
         if (token == null) {
             // No token found -> New user
             this.authenticationFlow = 'new-user';
@@ -611,6 +920,16 @@ class CWIStyleWalletManager {
             this.presentationKey = key;
             this.currentUMPToken = token;
         }
+        this.telemetry.capture({
+            name: 'wallet-toolbox.authentication.account-lookup.completed',
+            component: 'wallet-toolbox.cwi-manager',
+            severity: 'info',
+            attributes: {
+                lookupKind: 'presentation',
+                accountStatus: this.authenticationFlow,
+                durationMs: Date.now() - startedAt
+            }
+        });
     }
     /**
      * Provides the password.
@@ -621,6 +940,9 @@ class CWIStyleWalletManager {
         if (this.authenticationMode === 'presentation-key-and-recovery-key') {
             throw new Error('Password is not needed in this mode');
         }
+        if (this.authenticationFlow === 'unknown') {
+            throw new Error('Determine account status with a presentation or recovery key before providing a password.');
+        }
         if (this.authenticationFlow === 'existing-user') {
             await this.handleExistingUserPassword(password);
         }
@@ -638,8 +960,7 @@ class CWIStyleWalletManager {
         if (this.authenticationMode === 'presentation-key-and-password') {
             if (this.presentationKey == null)
                 throw new Error('No presentation key found!');
-            rootPrimaryKey = new sdk_1.SymmetricKey(this.XOR(this.presentationKey, derivedPasswordKey))
-                .decrypt(this.currentUMPToken.passwordPresentationPrimary);
+            rootPrimaryKey = new sdk_1.SymmetricKey(this.XOR(this.presentationKey, derivedPasswordKey)).decrypt(this.currentUMPToken.passwordPresentationPrimary);
         }
         else {
             // 'recovery-key-and-password'
@@ -647,8 +968,7 @@ class CWIStyleWalletManager {
                 throw new Error('No recovery key found!');
             const primaryDecryptionKey = this.XOR(this.recoveryKey, derivedPasswordKey);
             rootPrimaryKey = new sdk_1.SymmetricKey(primaryDecryptionKey).decrypt(this.currentUMPToken.passwordRecoveryPrimary);
-            rootPrivilegedKey = new sdk_1.SymmetricKey(this.XOR(rootPrimaryKey, derivedPasswordKey))
-                .decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
+            rootPrivilegedKey = new sdk_1.SymmetricKey(this.XOR(rootPrimaryKey, derivedPasswordKey)).decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
         }
         await this.setupRootInfrastructure(rootPrimaryKey, rootPrivilegedKey);
         await this.switchProfile(this.activeProfileId);
@@ -673,7 +993,8 @@ class CWIStyleWalletManager {
         const recoveryPassword = new sdk_1.SymmetricKey(this.XOR(recoveryKey, passwordKey));
         const primaryPassword = new sdk_1.SymmetricKey(this.XOR(rootPrimaryKey, passwordKey));
         const tempPrivilegedKeyManager = new PrivilegedKeyManager_1.PrivilegedKeyManager(async () => new sdk_1.PrivateKey(rootPrivilegedKey));
-        const wrapKey = async (plaintext) => (await tempPrivilegedKeyManager.encrypt({ plaintext, protocolID: [2, 'admin key wrapping'], keyID: '1' })).ciphertext;
+        const wrapKey = async (plaintext) => (await tempPrivilegedKeyManager.encrypt({ plaintext, protocolID: [2, 'admin key wrapping'], keyID: '1' }))
+            .ciphertext;
         // Build new UMP token (v3 with KDF metadata, no profiles initially)
         const newToken = {
             passwordSalt,
@@ -695,14 +1016,19 @@ class CWIStyleWalletManager {
         await this.setupRootInfrastructure(rootPrimaryKey);
         await this.switchProfile(exports.DEFAULT_PROFILE_ID);
         // Fund the *default* wallet if funder provided
-        if ((this.newWalletFunder != null) && (this.underlying != null)) {
+        if (this.newWalletFunder != null && this.underlying != null) {
             try {
                 await this.newWalletFunder(this.presentationKey, this.underlying, this.adminOriginator);
             }
-            catch (e) {
-                console.error('Error funding new wallet:', e);
-                const message = e instanceof Error ? e.message : String(e);
-                throw new Error(`Failed to fund new wallet before publishing UMP token: ${message}`);
+            catch (error) {
+                this.telemetry.capture({
+                    name: 'wallet-toolbox.authentication.new-wallet-funding.failed',
+                    component: 'wallet-toolbox.cwi-manager',
+                    severity: 'error',
+                    error: new Error('New wallet funding failed.')
+                });
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to fund new wallet before publishing UMP token: ${message}`, { cause: error });
             }
         }
         if (this.underlying == null)
@@ -722,6 +1048,9 @@ class CWIStyleWalletManager {
         if (this.authenticationMode === 'presentation-key-and-password') {
             throw new Error('No recovery key required in this mode');
         }
+        if (recoveryKey.length !== 32 || recoveryKey.some(byte => !Number.isInteger(byte) || byte < 0 || byte > 255)) {
+            throw new TypeError('Recovery key must contain exactly 32 bytes.');
+        }
         if (this.authenticationMode === 'recovery-key-and-password') {
             // Wait for password
             const hash = sdk_1.Hash.sha256(recoveryKey);
@@ -755,7 +1084,7 @@ class CWIStyleWalletManager {
      * @returns Encrypted snapshot bytes.
      */
     saveSnapshot() {
-        if ((this.rootPrimaryKey == null) || (this.currentUMPToken == null)) {
+        if (this.rootPrimaryKey == null || this.currentUMPToken == null) {
             throw new Error('No root primary key or current UMP token set');
         }
         const snapshotKey = (0, sdk_1.Random)(32);
@@ -778,7 +1107,20 @@ class CWIStyleWalletManager {
         snapshotWriter.write(snapshotKey);
         snapshotWriter.write(this.activeProfileId); // Active profile ID
         snapshotWriter.write(snapshotPayload); // Encrypted data
-        return snapshotWriter.toArray();
+        const snapshot = snapshotWriter.toArray();
+        if (snapshot.length > exports.MAX_STATE_SNAPSHOT_BYTES) {
+            throw new Error('Snapshot exceeds the maximum supported size.');
+        }
+        this.telemetry.capture({
+            name: 'wallet-toolbox.snapshot.saved',
+            component: 'wallet-toolbox.cwi-manager',
+            severity: 'info',
+            attributes: {
+                formatVersion: 2,
+                profileCount: this.profiles.length
+            }
+        });
+        return snapshot;
     }
     /**
      * Loads a previously saved state snapshot. Restores root key, UMP token, profiles, and active profile.
@@ -788,6 +1130,11 @@ class CWIStyleWalletManager {
      */
     async loadSnapshot(snapshot) {
         try {
+            if (snapshot.length === 0 ||
+                snapshot.length > exports.MAX_STATE_SNAPSHOT_BYTES ||
+                snapshot.some(byte => !Number.isInteger(byte) || byte < 0 || byte > 255)) {
+                throw new Error('Snapshot is empty, oversized, or contains invalid bytes.');
+            }
             const reader = new sdk_1.Utils.Reader(snapshot);
             const version = reader.readUInt8();
             let snapshotKey;
@@ -820,22 +1167,38 @@ class CWIStyleWalletManager {
             await this.setupRootInfrastructure(rootPrimaryKey); // Will automatically load profiles
             await this.switchProfile(activeProfileId); // Switch to the profile saved in the snapshot
             this.authenticationFlow = 'existing-user'; // Loading implies existing user
+            this.telemetry.capture({
+                name: 'wallet-toolbox.snapshot.loaded',
+                component: 'wallet-toolbox.cwi-manager',
+                severity: 'info',
+                attributes: {
+                    formatVersion: version,
+                    profileCount: this.profiles.length
+                }
+            });
         }
         catch (error) {
             this.destroy(); // Clear state on error
-            throw new Error(`Failed to load snapshot: ${error.message}`);
+            this.telemetry.capture({
+                name: 'wallet-toolbox.snapshot.load-failed',
+                component: 'wallet-toolbox.cwi-manager',
+                severity: 'error',
+                error
+            });
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to load snapshot: ${message}`, { cause: error });
         }
     }
     async syncUMPToken() {
-        if (!this.authenticated || (this.currentUMPToken == null) || (this.rootPrimaryKey == null)) {
+        if (!this.authenticated || this.currentUMPToken == null || this.rootPrimaryKey == null) {
             throw new Error('Wallet not authenticated or missing UMP token.');
         }
         const currentToken = this.currentUMPToken;
         let refreshed;
-        if (currentToken.presentationHash && (currentToken.presentationHash.length > 0)) {
+        if (currentToken.presentationHash && currentToken.presentationHash.length > 0) {
             refreshed = await this.UMPTokenInteractor.findByPresentationKeyHash(currentToken.presentationHash);
         }
-        if ((refreshed == null) && currentToken.recoveryHash && (currentToken.recoveryHash.length > 0)) {
+        if (refreshed == null && currentToken.recoveryHash && currentToken.recoveryHash.length > 0) {
             refreshed = await this.UMPTokenInteractor.findByRecoveryKeyHash(currentToken.recoveryHash);
         }
         if (refreshed == null) {
@@ -865,7 +1228,7 @@ class CWIStyleWalletManager {
         this.profiles = [];
         this.activeProfileId = exports.DEFAULT_PROFILE_ID;
         this.authenticationMode = 'presentation-key-and-password';
-        this.authenticationFlow = 'new-user';
+        this.authenticationFlow = 'unknown';
     }
     // --- Profile Management Methods ---
     /**
@@ -905,7 +1268,10 @@ class CWIStyleWalletManager {
      * @returns The ID of the newly created profile.
      */
     async addProfile(name) {
-        if (!this.authenticated || (this.rootPrimaryKey == null) || (this.currentUMPToken == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated ||
+            this.rootPrimaryKey == null ||
+            this.currentUMPToken == null ||
+            this.rootPrivilegedKeyManager == null) {
             throw new Error('Wallet not fully initialized or authenticated.');
         }
         // Ensure name is unique (including 'default')
@@ -936,7 +1302,10 @@ class CWIStyleWalletManager {
      * @param profileId The 16-byte ID of the profile to delete.
      */
     async deleteProfile(profileId) {
-        if (!this.authenticated || (this.rootPrimaryKey == null) || (this.currentUMPToken == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated ||
+            this.rootPrimaryKey == null ||
+            this.currentUMPToken == null ||
+            this.rootPrivilegedKeyManager == null) {
             throw new Error('Wallet not fully initialized or authenticated.');
         }
         if (profileId.every(x => x === 0)) {
@@ -963,7 +1332,7 @@ class CWIStyleWalletManager {
      * @param profileId The 16-byte ID of the profile to switch to (use DEFAULT_PROFILE_ID for default).
      */
     async switchProfile(profileId) {
-        if (!this.authenticated || (this.rootPrimaryKey == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated || this.rootPrimaryKey == null || this.rootPrivilegedKeyManager == null) {
             throw new Error('Cannot switch profile: Wallet not authenticated or root keys missing.');
         }
         let profilePrimaryKey;
@@ -991,9 +1360,7 @@ class CWIStyleWalletManager {
             const rootPrivileged = await this.rootPrivilegedKeyManager.getPrivilegedKey(reason);
             const rootPrivilegedBytes = rootPrivileged.toArray();
             // Apply the profile's pad if applicable
-            const profilePrivilegedBytes = (profilePrivilegedPad == null)
-                ? rootPrivilegedBytes
-                : this.XOR(rootPrivilegedBytes, profilePrivilegedPad);
+            const profilePrivilegedBytes = profilePrivilegedPad == null ? rootPrivilegedBytes : this.XOR(rootPrivilegedBytes, profilePrivilegedPad);
             return new sdk_1.PrivateKey(profilePrivilegedBytes);
         });
         // Build the underlying wallet for the specific profile
@@ -1006,7 +1373,10 @@ class CWIStyleWalletManager {
      * Changes the user's password. Re-wraps keys and updates the UMP token.
      */
     async changePassword(newPassword) {
-        if (!this.authenticated || (this.currentUMPToken == null) || (this.rootPrimaryKey == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated ||
+            this.currentUMPToken == null ||
+            this.rootPrimaryKey == null ||
+            this.rootPrivilegedKeyManager == null) {
             throw new Error('Not authenticated or missing required data.');
         }
         const passwordSalt = (0, sdk_1.Random)(32);
@@ -1029,7 +1399,7 @@ class CWIStyleWalletManager {
      * Retrieves the current recovery key. Requires privileged access.
      */
     async getRecoveryKey() {
-        if (!this.authenticated || (this.currentUMPToken == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated || this.currentUMPToken == null || this.rootPrivilegedKeyManager == null) {
             throw new Error('Not authenticated or missing required data.');
         }
         return await this.getFactor('recoveryKey');
@@ -1038,7 +1408,10 @@ class CWIStyleWalletManager {
      * Changes the user's recovery key. Prompts user to save the new key.
      */
     async changeRecoveryKey() {
-        if (!this.authenticated || (this.currentUMPToken == null) || (this.rootPrimaryKey == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated ||
+            this.currentUMPToken == null ||
+            this.rootPrimaryKey == null ||
+            this.rootPrivilegedKeyManager == null) {
             throw new Error('Not authenticated or missing required data.');
         }
         // Decrypt existing factors needed
@@ -1056,7 +1429,10 @@ class CWIStyleWalletManager {
      * Changes the user's presentation key.
      */
     async changePresentationKey(newPresentationKey) {
-        if (!this.authenticated || (this.currentUMPToken == null) || (this.rootPrimaryKey == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated ||
+            this.currentUMPToken == null ||
+            this.rootPrimaryKey == null ||
+            this.rootPrivilegedKeyManager == null) {
             throw new Error('Not authenticated or missing required data.');
         }
         if (newPresentationKey.length !== 32) {
@@ -1083,7 +1459,7 @@ class CWIStyleWalletManager {
             // Provide more context in error
             throw new Error(`XOR length mismatch: ${n1.length} vs ${n2.length}`);
         }
-        const r = new Array(n1.length);
+        const r = Array.from({ length: n1.length }, () => 0);
         for (let i = 0; i < n1.length; i++) {
             r[i] = n1[i] ^ n2[i];
         }
@@ -1097,7 +1473,7 @@ class CWIStyleWalletManager {
      * @returns The decrypted key bytes.
      */
     async getFactor(factorName) {
-        if (!this.authenticated || (this.currentUMPToken == null) || (this.rootPrivilegedKeyManager == null)) {
+        if (!this.authenticated || this.currentUMPToken == null || this.rootPrivilegedKeyManager == null) {
             throw new Error(`Cannot get factor "${factorName}": Wallet not ready.`);
         }
         const protocolID = [2, 'admin key wrapping']; // Protocol used for encrypting factors
@@ -1134,8 +1510,15 @@ class CWIStyleWalletManager {
             }
         }
         catch (error) {
-            console.error(`Error decrypting factor ${factorName}:`, error);
-            throw new Error(`Failed to decrypt factor "${factorName}": ${error.message}`);
+            this.telemetry.capture({
+                name: 'wallet-toolbox.authentication.factor-decryption.failed',
+                component: 'wallet-toolbox.cwi-manager',
+                severity: 'error',
+                attributes: { factor: factorName },
+                error
+            });
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to decrypt factor "${factorName}": ${message}`, { cause: error });
         }
     }
     /**
@@ -1145,7 +1528,7 @@ class CWIStyleWalletManager {
     async updateAuthFactors(passwordSalt, passwordKey, presentationKey, recoveryKey, rootPrimaryKey, rootPrivilegedKey, // Explicitly pass the root key bytes
     profiles // Pass current/new profiles list
     ) {
-        if (!this.authenticated || (this.rootPrimaryKey == null) || (this.currentUMPToken == null)) {
+        if (!this.authenticated || this.rootPrimaryKey == null || this.currentUMPToken == null) {
             throw new Error('Wallet is not properly authenticated or missing data for update.');
         }
         // Ensure we have the OLD token to consume
@@ -1162,7 +1545,7 @@ class CWIStyleWalletManager {
         const tempRootPrivilegedKeyManager = new PrivilegedKeyManager_1.PrivilegedKeyManager(async () => new sdk_1.PrivateKey(rootPrivilegedKey));
         // Encrypt profiles if provided
         let profilesEncrypted;
-        if ((profiles != null) && profiles.length > 0) {
+        if (profiles != null && profiles.length > 0) {
             const profilesJson = JSON.stringify(profiles);
             const profilesBytes = sdk_1.Utils.toArray(profilesJson, 'utf8');
             profilesEncrypted = new sdk_1.SymmetricKey(rootPrimaryKey).encrypt(profilesBytes);
@@ -1210,7 +1593,12 @@ class CWIStyleWalletManager {
         const currentActiveId = this.activeProfileId;
         let walletToUse = this.underlying;
         if (!currentActiveId.every(x => x === 0)) {
-            console.log('Temporarily switching to default profile to update UMP token...');
+            this.telemetry.capture({
+                name: 'wallet-toolbox.ump.profile-switch.started',
+                component: 'wallet-toolbox.cwi-manager',
+                severity: 'debug',
+                attributes: { reason: 'token-update' }
+            });
             await this.switchProfile(exports.DEFAULT_PROFILE_ID); // This rebuilds this.underlying
             walletToUse = this.underlying;
         }
@@ -1228,8 +1616,13 @@ class CWIStyleWalletManager {
         finally {
             // Switch back if we temporarily switched
             if (!currentActiveId.every(x => x === 0)) {
-                console.log('Switching back to original profile...');
                 await this.switchProfile(currentActiveId);
+                this.telemetry.capture({
+                    name: 'wallet-toolbox.ump.profile-switch.completed',
+                    component: 'wallet-toolbox.cwi-manager',
+                    severity: 'debug',
+                    attributes: { reason: 'token-update' }
+                });
             }
         }
     }
@@ -1261,7 +1654,7 @@ class CWIStyleWalletManager {
         writeArray(token.passwordKeyEncrypted); // 9
         writeArray(token.recoveryKeyEncrypted); // 10
         // Write optional profiles field
-        if ((token.profilesEncrypted != null) && token.profilesEncrypted.length > 0) {
+        if (token.profilesEncrypted != null && token.profilesEncrypted.length > 0) {
             writer.writeUInt8(1); // Flag indicating profiles present
             writeArray(token.profilesEncrypted);
         }
@@ -1311,6 +1704,9 @@ class CWIStyleWalletManager {
         }
         const readArray = () => {
             const length = reader.readVarIntNum();
+            if (length <= 0 || length > exports.MAX_STATE_SNAPSHOT_BYTES) {
+                throw new Error('UMP token field exceeds allowed bounds.');
+            }
             return reader.read(length);
         };
         // Read standard fields (order matches serialization)
@@ -1344,18 +1740,16 @@ class CWIStyleWalletManager {
                 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);
+                const kdfParams = JSON.parse(kdfParamsJson);
+                passwordKdf = {
+                    algorithm,
+                    iterations: kdfParams.iterations,
+                    memoryKiB: kdfParams.memoryKiB,
+                    parallelism: kdfParams.parallelism,
+                    hashLength: kdfParams.hashLength
+                };
+                if (!isValidKdfConfig(passwordKdf)) {
+                    throw new Error('Serialized UMP token contains unsupported or unsafe KDF parameters.');
                 }
             }
         }
@@ -1363,6 +1757,9 @@ class CWIStyleWalletManager {
         const outpointLen = reader.readVarIntNum();
         const outpointBytes = reader.read(outpointLen);
         const currentOutpoint = sdk_1.Utils.toUTF8(outpointBytes);
+        if (currentOutpoint.length > 128 || !/^[^\s.:]+[.:]\d+$/.test(currentOutpoint)) {
+            throw new Error('Serialized UMP token contains an invalid outpoint.');
+        }
         const token = {
             passwordSalt,
             passwordPresentationPrimary,
@@ -1396,9 +1793,7 @@ class CWIStyleWalletManager {
         }
         this.rootPrimaryKey = rootPrimaryKey;
         // Store ephemeral key if provided, for one-time use by the manager
-        let oneTimePrivilegedKey = (ephemeralRootPrivilegedKey == null)
-            ? undefined
-            : new sdk_1.PrivateKey(ephemeralRootPrivilegedKey);
+        let oneTimePrivilegedKey = ephemeralRootPrivilegedKey == null ? undefined : new sdk_1.PrivateKey(ephemeralRootPrivilegedKey);
         // Create the ROOT PrivilegedKeyManager
         this.rootPrivilegedKeyManager = new PrivilegedKeyManager_1.PrivilegedKeyManager(async (reason) => {
             // 1. Use one-time key if available (for recovery)
@@ -1415,7 +1810,7 @@ class CWIStyleWalletManager {
                     const decryptedPrivileged = new sdk_1.SymmetricKey(privilegedDecryptor).decrypt(this.currentUMPToken.passwordPrimaryPrivileged);
                     return !!decryptedPrivileged; // Test passes if decryption works
                 }
-                catch (_intentionallyIgnored) {
+                catch {
                     // Decryption failure means the password candidate is wrong — this is the
                     // expected rejection path for an incorrect password.  Returning false causes
                     // the password-retriever loop to prompt the user again rather than crashing.
@@ -1430,18 +1825,26 @@ class CWIStyleWalletManager {
         });
         // Decrypt and load profiles if present in the token
         this.profiles = []; // Clear existing profiles before loading
-        if ((this.currentUMPToken.profilesEncrypted != null) && this.currentUMPToken.profilesEncrypted.length > 0) {
+        if (this.currentUMPToken.profilesEncrypted != null && this.currentUMPToken.profilesEncrypted.length > 0) {
             try {
                 const decryptedProfileBytes = new sdk_1.SymmetricKey(rootPrimaryKey).decrypt(this.currentUMPToken.profilesEncrypted);
                 const profilesJson = sdk_1.Utils.toUTF8(decryptedProfileBytes);
-                this.profiles = JSON.parse(profilesJson);
+                const profiles = JSON.parse(profilesJson);
+                if (!Array.isArray(profiles) || profiles.length > 1000 || !profiles.every(isValidProfile)) {
+                    throw new Error('Decrypted profile data is invalid or exceeds supported bounds.');
+                }
+                this.profiles = profiles;
             }
             catch (error) {
-                console.error('Failed to decrypt or parse profiles:', error);
-                // Decide if this should be fatal or just log and continue without profiles
-                this.profiles = []; // Ensure profiles are empty on error
-                // Optionally re-throw or handle more gracefully
-                throw new Error(`Failed to load profiles: ${error.message}`);
+                this.profiles = [];
+                this.telemetry.capture({
+                    name: 'wallet-toolbox.profile.load-failed',
+                    component: 'wallet-toolbox.cwi-manager',
+                    severity: 'error',
+                    error
+                });
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                throw new Error(`Failed to load profiles: ${message}`, { cause: error });
             }
         }
         this.authenticated = true;
@@ -1568,7 +1971,7 @@ class CWIStyleWalletManager {
         if (originator === this.adminOriginator) {
             throw new Error('External applications are not allowed to use the admin originator.');
         }
-        while (!this.authenticated || (this.underlying == null)) {
+        while (!this.authenticated || this.underlying == null) {
             await new Promise(resolve => setTimeout(resolve, 100));
         }
         return await this.underlying.waitForAuthentication({}, originator);