@bsv/wallet-toolbox-mobile 2.4.3 → 2.4.4

package/out/src/CWIStyleWalletManager.js

@@ -1,6 +1,6 @@
 "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");
@@ -15,6 +15,30 @@ 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 isLikelyDerSignatureField(field) {
     if (!field || field.length < 8 || field.length > 80) {
         return false;
@@ -82,10 +106,9 @@ 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)();
@@ -111,6 +134,9 @@ 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') {
         return await pbkdf2NativeOrWasm(passwordBytes, token.passwordSalt, kdf?.iterations ?? exports.PBKDF2_NUM_ROUNDS, 32, 'sha512');
@@ -138,6 +164,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 +223,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 +243,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 +256,141 @@ 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 } : {})
+        };
+    }
+    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
         };
-        const answer = await this.resolver.query(question);
-        return this.parseLookupAnswer(answer);
+    }
+    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,
@@ -275,11 +466,12 @@ 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({
@@ -290,13 +482,18 @@ class OverlayUMPTokenInteractor {
                 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 +505,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. */
@@ -322,7 +519,7 @@ class OverlayUMPTokenInteractor {
         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. */
@@ -334,9 +531,27 @@ class OverlayUMPTokenInteractor {
         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 +561,38 @@ 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
+            if (protocolFields.length < 11 ||
+                protocolFields.slice(0, 11).some(field => field.length === 0 || field.length > exports.MAX_STATE_SNAPSHOT_BYTES)) {
+                return undefined;
+            }
             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)
+            const kdfVersionFieldIndex = hasV3MetadataWithProfiles ? 12 : (hasV3MetadataWithoutProfiles ? 11 : -1);
+            const token = {
                 passwordSalt: protocolFields[0],
                 passwordPresentationPrimary: protocolFields[1],
                 passwordRecoveryPrimary: protocolFields[2],
@@ -391,41 +604,38 @@ 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];
+            if (token.presentationHash.length !== 32 || token.recoveryHash.length !== 32)
+                return undefined;
+            const hasProfilesField = hasV3MetadataWithProfiles || (!hasV3MetadataWithoutProfiles && protocolFields[11] != null);
+            if (hasProfilesField && protocolFields[11].length > 0) {
+                if (protocolFields[11].length > exports.MAX_STATE_SNAPSHOT_BYTES)
+                    return undefined;
+                token.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);
+                if (kdfAlgorithmField == null || kdfParamsField == null || kdfParamsField.length > 1024) {
+                    return undefined;
                 }
+                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 undefined;
+                token.umpVersion = 3;
+                token.passwordKdf = passwordKdf;
             }
-            return t;
+            return token;
         }
-        catch (e) {
-            console.error('Failed to parse or decode UMP token:', e);
+        catch {
             return undefined;
         }
     }
@@ -435,19 +645,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;
@@ -483,6 +717,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 +748,7 @@ class CWIStyleWalletManager {
     /**
      * Indicates new user or existing user flow.
      */
-    authenticationFlow = 'new-user';
+    authenticationFlow = 'unknown';
     /**
      * The current UMP token in use.
      */
@@ -559,32 +797,55 @@ 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 +859,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 +899,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 +919,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);
         }
@@ -699,10 +1000,15 @@ class CWIStyleWalletManager {
             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 +1028,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);
@@ -778,7 +1087,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 +1110,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,10 +1147,26 @@ 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() {
@@ -865,7 +1208,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 ---
     /**
@@ -1134,8 +1477,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 });
         }
     }
     /**
@@ -1210,7 +1560,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 +1583,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' }
+                });
             }
         }
     }
@@ -1311,6 +1671,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 +1707,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 +1724,9 @@ class CWIStyleWalletManager {
         const outpointLen = reader.readVarIntNum();
         const outpointBytes = reader.read(outpointLen);
         const currentOutpoint = sdk_1.Utils.toUTF8(outpointBytes);
+        if (currentOutpoint.length > 128 || !/^[^\s.:]+[.:][0-9]+$/.test(currentOutpoint)) {
+            throw new Error('Serialized UMP token contains an invalid outpoint.');
+        }
         const token = {
             passwordSalt,
             passwordPresentationPrimary,
@@ -1434,14 +1798,22 @@ class CWIStyleWalletManager {
             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;