@bsv/wallet-toolbox 2.4.4 → 2.4.20

package/out/src/WalletPermissionsManager.js

@@ -3,9 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WalletPermissionsManager = void 0;
 const sdk_1 = require("@bsv/sdk");
 const brc114ActionTimeLabels_1 = require("./utility/brc114ActionTimeLabels");
-/// /// TODO: ADD SUPPORT FOR ADMIN COUNTERPARTIES BASED ON WALLET STORAGE
-/// ///       PROHIBITION OF SPECIAL OPERATIONS IS ALSO CRITICAL.
-/// /// !!!!!!!! SECURITY-CRITICAL ADDITION — DO NOT USE UNTIL IMPLEMENTED.
+// Security invariant: only the configured admin originator bypasses permission
+// prompts. Admin-reserved protocols, baskets, and labels are rejected for all
+// other originators; counterparty bypasses require an explicit configuration
+// allowlist.
 function deepEqual(object1, object2) {
     if (object1 === null || object1 === undefined || object2 === null || object2 === undefined) {
         return object1 === object2;
@@ -126,6 +127,7 @@ class WalletPermissionsManager {
      * Configuration that determines whether to skip or apply various checks and encryption.
      */
     config;
+    telemetry;
     /**
      * Constructs a new Permissions Manager instance.
      *
@@ -136,6 +138,7 @@ class WalletPermissionsManager {
     constructor(underlyingWallet, adminOriginator, config = {}) {
         this.underlying = underlyingWallet;
         this.adminOriginator = this.normalizeOriginator(adminOriginator) || adminOriginator;
+        this.telemetry = new sdk_1.Telemetry(config.telemetry);
         // Default all config options to true unless specified
         this.config = {
             seekProtocolPermissionsForSigning: true,
@@ -363,12 +366,24 @@ class WalletPermissionsManager {
      */
     async callEvent(eventName, param) {
         const arr = this.callbacks[eventName] || [];
-        for (const cb of arr) {
+        for (const [callbackIndex, cb] of arr.entries()) {
             if (typeof cb === 'function') {
                 try {
-                    await cb(param);
+                    if (this.telemetry.enabled && typeof param === 'object' && param != null) {
+                        await this.telemetry.withSpan('wallet.permission.callback', {
+                            component: 'wallet-permissions',
+                            carrier: param,
+                            attributes: {
+                                'permission.callback': eventName,
+                                'permission.callback_index': callbackIndex
+                            }
+                        }, async () => await cb(param));
+                    }
+                    else {
+                        await cb(param);
+                    }
                 }
-                catch (_callbackError) {
+                catch {
                     // Intentionally swallow errors from user-provided callbacks to prevent
                     // a misbehaving callback from disrupting the event dispatch loop.
                 }
@@ -568,16 +583,16 @@ class WalletPermissionsManager {
      * Throws an error on the first mismatch.
      */
     validateGrantedPermissionsSubset(granted, requested) {
-        if ((granted.spendingAuthorization != null) && (requested.spendingAuthorization == null)) {
+        if (granted.spendingAuthorization != null && requested.spendingAuthorization == null) {
             throw new Error('Granted spending authorization was not part of the original request.');
         }
-        if (granted.protocolPermissions?.some(g => (requested.protocolPermissions?.find(r => deepEqual(r, g))) == null)) {
+        if (granted.protocolPermissions?.some(g => requested.protocolPermissions?.find(r => deepEqual(r, g)) == null)) {
             throw new Error('Granted protocol permissions are not a subset of the original request.');
         }
-        if (granted.basketAccess?.some(g => (requested.basketAccess?.find(r => deepEqual(r, g))) == null)) {
+        if (granted.basketAccess?.some(g => requested.basketAccess?.find(r => deepEqual(r, g)) == null)) {
             throw new Error('Granted basket access permissions are not a subset of the original request.');
         }
-        if (granted.certificateAccess?.some(g => (requested.certificateAccess?.find(r => deepEqual(r, g))) == null)) {
+        if (granted.certificateAccess?.some(g => requested.certificateAccess?.find(r => deepEqual(r, g)) == null)) {
             throw new Error('Granted certificate access permissions are not a subset of the original request.');
         }
     }
@@ -707,13 +722,21 @@ class WalletPermissionsManager {
         if (await this.hasRecentOrPendingGrant(cacheKey))
             return true;
         // 4) Attempt to find a valid token in the internal basket
-        const token = await this.findProtocolToken(originator, privileged, protocolID, counterparty, /* includeExpired= */ true, lookupValues);
+        const token = await this.findProtocolToken(originator, privileged, protocolID, counterparty, 
+        /* includeExpired= */ true, lookupValues);
         if (token == null) {
             // No token found => request a new one if allowed
             if (!seekPermission)
                 throw new Error('No protocol permission token found (seekPermission=false).');
             return await this.requestPermissionFlow({
-                type: 'protocol', originator, privileged, protocolID, counterparty, usageType, reason, renewal: false
+                type: 'protocol',
+                originator,
+                privileged,
+                protocolID,
+                counterparty,
+                usageType,
+                reason,
+                renewal: false
             });
         }
         if (this.isTokenExpired(token.expiry)) {
@@ -722,8 +745,15 @@ class WalletPermissionsManager {
                 throw new Error('Protocol permission expired and no further user consent allowed (seekPermission=false).');
             }
             return await this.requestPermissionFlow({
-                type: 'protocol', originator, privileged, protocolID, counterparty, usageType, reason,
-                renewal: true, previousToken: token
+                type: 'protocol',
+                originator,
+                privileged,
+                protocolID,
+                counterparty,
+                usageType,
+                reason,
+                renewal: true,
+                previousToken: token
             });
         }
         // valid and unexpired
@@ -756,7 +786,13 @@ class WalletPermissionsManager {
             if (!seekPermission)
                 throw new Error('Basket permission expired (seekPermission=false).');
             return await this.requestPermissionFlow({
-                type: 'basket', originator, basket, usageType, reason, renewal: true, previousToken: token
+                type: 'basket',
+                originator,
+                basket,
+                usageType,
+                reason,
+                renewal: true,
+                previousToken: token
             });
         }
         this.cachePermission(cacheKey, token.expiry);
@@ -999,7 +1035,7 @@ class WalletPermissionsManager {
     }
     async fetchManifestPermissions(originator) {
         const cached = this.manifestCache.get(originator);
-        if ((cached != null) && Date.now() - cached.fetchedAt < WalletPermissionsManager.MANIFEST_CACHE_TTL_MS) {
+        if (cached != null && Date.now() - cached.fetchedAt < WalletPermissionsManager.MANIFEST_CACHE_TTL_MS) {
             return {
                 groupPermissions: cached.groupPermissions,
                 counterpartyPermissions: cached.counterpartyPermissions
@@ -1026,7 +1062,7 @@ class WalletPermissionsManager {
                     return { groupPermissions, counterpartyPermissions: counterpartyPermissionsDeclared };
                 }
             }
-            catch (_manifestFetchError) {
+            catch {
                 // Manifest fetch or parse failed — fall through to return null/null defaults below
             }
             const result = { groupPermissions: null, counterpartyPermissions: null };
@@ -1482,12 +1518,36 @@ class WalletPermissionsManager {
      *   and return a promise that resolves once permission is granted or rejects if denied.
      */
     async requestPermissionFlow(r) {
+        if (!this.telemetry.enabled)
+            return await this.requestPermissionFlowCore(r);
+        return await this.telemetry.withSpan('wallet.permission.request', {
+            component: 'wallet-permissions',
+            carrier: r,
+            attributes: {
+                'permission.type': r.type,
+                'permission.renewal': r.renewal === true
+            }
+        }, async (span) => {
+            const result = await this.requestPermissionFlowCore(r, span.context);
+            span.end({
+                attributes: {
+                    'permission.granted': result
+                }
+            });
+            return result;
+        });
+    }
+    async requestPermissionFlowCore(r, context) {
+        if (context != null)
+            this.telemetry.bindContext(r, context);
         const normalizedOriginator = this.normalizeOriginator(r.originator) || r.originator;
         const preparedRequest = {
             ...r,
             originator: normalizedOriginator,
             displayOriginator: r.displayOriginator ?? r.previousToken?.rawOriginator ?? r.originator
         };
+        if (context != null)
+            this.telemetry.bindContext(preparedRequest, context);
         if (preparedRequest.type === 'protocol' && preparedRequest.protocolID?.[0] === 1) {
             preparedRequest.counterparty = '';
         }
@@ -1513,7 +1573,7 @@ class WalletPermissionsManager {
     /** Returns true when an active-request queue already has pending waiters for this key. */
     isPiggybacking(key) {
         const q = this.activeRequests.get(key);
-        return (q != null) && q.pending.length > 0;
+        return q != null && q.pending.length > 0;
     }
     /** Appends to an existing request queue and waits for resolution. */
     async piggybackOnExistingQueue(key) {
@@ -1523,7 +1583,7 @@ class WalletPermissionsManager {
         });
     }
     /** Runs the grouped-permission flow (with or without a lock) and checks post-group satisfaction. */
-    async resolveGroupedFlow(preparedRequest, key) {
+    async resolveGroupedFlow(preparedRequest, _key) {
         const hadPendingGroupedFlowBefore = this.config.seekGroupedPermission && this.groupedPermissionFlowTail.has(preparedRequest.originator);
         let groupResult;
         if (this.config.seekGroupedPermission) {
@@ -1565,23 +1625,27 @@ class WalletPermissionsManager {
     async firePermissionRequestEvent(request, key) {
         switch (request.type) {
             case 'protocol':
-                await this.callEvent('onProtocolPermissionRequested', {
+                await this.callPermissionEvent(request, 'onProtocolPermissionRequested', {
                     ...request,
                     counterparty: request.protocolID?.[0] === 1 ? undefined : request.counterparty,
                     requestID: key
                 });
                 break;
             case 'basket':
-                await this.callEvent('onBasketAccessRequested', { ...request, requestID: key });
+                await this.callPermissionEvent(request, 'onBasketAccessRequested', { ...request, requestID: key });
                 break;
             case 'certificate':
-                await this.callEvent('onCertificateAccessRequested', { ...request, requestID: key });
+                await this.callPermissionEvent(request, 'onCertificateAccessRequested', { ...request, requestID: key });
                 break;
             case 'spending':
-                await this.callEvent('onSpendingAuthorizationRequested', { ...request, requestID: key });
+                await this.callPermissionEvent(request, 'onSpendingAuthorizationRequested', { ...request, requestID: key });
                 break;
         }
     }
+    async callPermissionEvent(request, eventName, param) {
+        this.telemetry.linkContext(request, param);
+        await this.callEvent(eventName, param);
+    }
     /* ---------------------------------------------------------------------
      *  4) SEARCH / DECODE / DECRYPT ON-CHAIN TOKENS (PushDrop Scripts)
      * --------------------------------------------------------------------- */
@@ -1660,7 +1724,7 @@ class WalletPermissionsManager {
             }, this.adminOriginator);
             return plaintext;
         }
-        catch (_decryptionError) {
+        catch {
             // Decryption failed (e.g. wrong key, unencrypted legacy value) — return the raw bytes unchanged
             return ciphertext;
         }
@@ -1695,7 +1759,7 @@ class WalletPermissionsManager {
             }, this.adminOriginator);
             return sdk_1.Utils.toUTF8(plaintext);
         }
-        catch (_decryptionError) {
+        catch {
             // Decryption failed (e.g. wrong key, unencrypted legacy value) — return original string unchanged
             return ciphertext;
         }
@@ -1715,6 +1779,108 @@ class WalletPermissionsManager {
         const cptyDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(fields[5]));
         return { domainDecoded, expiryDecoded, privDecoded, secLevelDecoded, protoNameDecoded, cptyDecoded };
     }
+    protocolTokenTags(originator, privileged, securityLevel, protocolName, counterparty) {
+        const tags = [
+            `originator ${originator}`,
+            `privileged ${!!privileged}`,
+            `protocolName ${protocolName}`,
+            `protocolSecurityLevel ${securityLevel}`
+        ];
+        if (securityLevel === 2)
+            tags.push(`counterparty ${counterparty}`);
+        return tags;
+    }
+    async parseProtocolTokenOutput(result, output, expected) {
+        const [txid, outputIndex] = this.parseOutpoint(output.outpoint);
+        const tx = this.transactionFromResultBeef(result, txid);
+        const decoded = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
+        if (decoded?.fields == null || decoded.fields.length < 6)
+            return undefined;
+        const fields = await this.decryptProtocolTokenFields(decoded.fields);
+        if (this.normalizeOriginator(fields.domainDecoded) !== expected.originator)
+            return undefined;
+        const matches = fields.privDecoded === !!expected.privileged &&
+            fields.secLevelDecoded === expected.securityLevel &&
+            fields.protoNameDecoded === expected.protocolName &&
+            (fields.secLevelDecoded !== 2 || fields.cptyDecoded === expected.counterparty);
+        if (!matches)
+            return undefined;
+        return {
+            tx: tx.toBEEF(),
+            txid,
+            outputIndex,
+            outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
+            satoshis: output.satoshis,
+            originator: expected.originator,
+            rawOriginator: fields.domainDecoded,
+            privileged: expected.privileged,
+            protocol: expected.protocolName,
+            securityLevel: expected.securityLevel,
+            expiry: fields.expiryDecoded,
+            counterparty: fields.cptyDecoded
+        };
+    }
+    async parseBasketTokenOutput(result, output, originator, basket) {
+        const [txid, outputIndex] = this.parseOutpoint(output.outpoint);
+        const tx = this.transactionFromResultBeef(result, txid);
+        const decoded = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
+        if (decoded?.fields == null || decoded.fields.length < 3)
+            return undefined;
+        const domainDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(decoded.fields[0]));
+        if (this.normalizeOriginator(domainDecoded) !== originator)
+            return undefined;
+        const expiryDecoded = Number.parseInt(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(decoded.fields[1])), 10);
+        const basketDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(decoded.fields[2]));
+        if (basketDecoded !== basket)
+            return undefined;
+        return {
+            tx: tx.toBEEF(),
+            txid,
+            outputIndex,
+            outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
+            satoshis: output.satoshis,
+            originator,
+            rawOriginator: domainDecoded,
+            basketName: basketDecoded,
+            expiry: expiryDecoded
+        };
+    }
+    async parseCertificateTokenOutput(result, output, expected) {
+        const [txid, outputIndex] = this.parseOutpoint(output.outpoint);
+        const tx = this.transactionFromResultBeef(result, txid);
+        const decoded = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
+        if (decoded?.fields == null || decoded.fields.length < 6)
+            return undefined;
+        const [domainRaw, expiryRaw, privRaw, typeRaw, fieldsRaw, verifierRaw] = decoded.fields;
+        const domainDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw));
+        if (this.normalizeOriginator(domainDecoded) !== expected.originator)
+            return undefined;
+        const expiryDecoded = Number.parseInt(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10);
+        const privileged = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(privRaw)) === 'true';
+        const certType = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(typeRaw));
+        const verifier = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(verifierRaw));
+        const allFields = JSON.parse(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(fieldsRaw)));
+        const metadataMatches = privileged === !!expected.privileged && certType === expected.certType && verifier === expected.verifier;
+        if (!metadataMatches)
+            return undefined;
+        const availableFields = new Set(allFields);
+        if (expected.fields.some(field => !availableFields.has(field)))
+            return undefined;
+        return {
+            tx: tx.toBEEF(),
+            txid,
+            outputIndex,
+            outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
+            satoshis: output.satoshis,
+            originator: expected.originator,
+            rawOriginator: domainDecoded,
+            privileged: expected.privileged,
+            verifier,
+            certType,
+            certFields: allFields,
+            expiry: expiryDecoded
+        };
+    }
     /** Parses outpoint string "txid.vout" into [txid, outputIndex]. */
     parseOutpoint(outpoint) {
         const [txid, indexStr] = outpoint.split('.');
@@ -1730,7 +1896,7 @@ class WalletPermissionsManager {
         if (!/^[0-9a-f]{64}$/.test(hex))
             return hex;
         const bytes = hex.match(/../g);
-        return (bytes != null) ? bytes.reverse().join('') : hex;
+        return bytes != null ? bytes.reverse().join('') : hex;
     }
     /**
      * Returns true when an outpoint string (e.g. "txid.vout" or "txid:vout") refers to `token`.
@@ -1778,52 +1944,25 @@ class WalletPermissionsManager {
         const [secLevel, protoName] = protocolID;
         const originsToTry = originatorLookupValues?.length ? originatorLookupValues : [originator];
         for (const originTag of originsToTry) {
-            const tags = [
-                `originator ${originTag}`,
-                `privileged ${!!privileged}`,
-                `protocolName ${protoName}`,
-                `protocolSecurityLevel ${secLevel}`
-            ];
-            if (secLevel === 2) {
-                tags.push(`counterparty ${counterparty}`);
-            }
             const result = await this.underlying.listOutputs({
                 basket: BASKET_MAP.protocol,
-                tags,
+                tags: this.protocolTokenTags(originTag, privileged, secLevel, protoName, counterparty),
                 tagQueryMode: 'all',
                 include: 'entire transactions'
             }, this.adminOriginator);
             for (const out of result.outputs) {
-                const [txid, outputIndex] = this.parseOutpoint(out.outpoint);
-                const tx = this.transactionFromResultBeef(result, txid);
-                const dec = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
-                if (dec?.fields == null || dec.fields.length < 6)
-                    continue;
-                const f = await this.decryptProtocolTokenFields(dec.fields);
-                if (this.normalizeOriginator(f.domainDecoded) !== originator)
-                    continue;
-                if (f.privDecoded !== !!privileged ||
-                    f.secLevelDecoded !== secLevel ||
-                    f.protoNameDecoded !== protoName ||
-                    (f.secLevelDecoded === 2 && f.cptyDecoded !== counterparty)) {
-                    continue;
-                }
-                if (!includeExpired && this.isTokenExpired(f.expiryDecoded))
-                    continue;
-                return {
-                    tx: tx.toBEEF(),
-                    txid,
-                    outputIndex,
-                    outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
-                    satoshis: out.satoshis,
+                const token = await this.parseProtocolTokenOutput(result, out, {
                     originator,
-                    rawOriginator: f.domainDecoded,
                     privileged,
-                    protocol: protoName,
                     securityLevel: secLevel,
-                    expiry: f.expiryDecoded,
-                    counterparty: f.cptyDecoded
-                };
+                    protocolName: protoName,
+                    counterparty
+                });
+                if (token == null)
+                    continue;
+                if (!includeExpired && this.isTokenExpired(token.expiry))
+                    continue;
+                return token;
             }
         }
         return undefined;
@@ -1835,53 +1974,26 @@ class WalletPermissionsManager {
         const matches = [];
         const seen = new Set();
         for (const originTag of originsToTry) {
-            const tags = [
-                `originator ${originTag}`,
-                `privileged ${!!privileged}`,
-                `protocolName ${protoName}`,
-                `protocolSecurityLevel ${secLevel}`
-            ];
-            if (secLevel === 2) {
-                tags.push(`counterparty ${counterparty}`);
-            }
             const result = await this.underlying.listOutputs({
                 basket: BASKET_MAP.protocol,
-                tags,
+                tags: this.protocolTokenTags(originTag, privileged, secLevel, protoName, counterparty),
                 tagQueryMode: 'all',
                 include: 'entire transactions'
             }, this.adminOriginator);
             for (const out of result.outputs) {
                 if (seen.has(out.outpoint))
                     continue;
-                const [txid, vout] = this.parseOutpoint(out.outpoint);
-                const tx = this.transactionFromResultBeef(result, txid);
-                const dec = sdk_1.PushDrop.decode(tx.outputs[vout].lockingScript);
-                if (dec?.fields == null || dec.fields.length < 6)
-                    continue;
-                const f = await this.decryptProtocolTokenFields(dec.fields);
-                if (this.normalizeOriginator(f.domainDecoded) !== originator)
-                    continue;
-                if (f.privDecoded !== !!privileged ||
-                    f.secLevelDecoded !== secLevel ||
-                    f.protoNameDecoded !== protoName ||
-                    (f.secLevelDecoded === 2 && f.cptyDecoded !== counterparty)) {
-                    continue;
-                }
-                seen.add(out.outpoint);
-                matches.push({
-                    tx: tx.toBEEF(),
-                    txid,
-                    outputIndex: vout,
-                    outputScript: tx.outputs[vout].lockingScript.toHex(),
-                    satoshis: out.satoshis,
+                const token = await this.parseProtocolTokenOutput(result, out, {
                     originator,
-                    rawOriginator: f.domainDecoded,
                     privileged,
-                    protocol: protoName,
                     securityLevel: secLevel,
-                    expiry: f.expiryDecoded,
-                    counterparty: f.cptyDecoded
+                    protocolName: protoName,
+                    counterparty
                 });
+                if (token == null)
+                    continue;
+                seen.add(out.outpoint);
+                matches.push(token);
             }
         }
         return matches;
@@ -1897,31 +2009,12 @@ class WalletPermissionsManager {
                 include: 'entire transactions'
             }, this.adminOriginator);
             for (const out of result.outputs) {
-                const [txid, outputIndex] = this.parseOutpoint(out.outpoint);
-                const tx = this.transactionFromResultBeef(result, txid);
-                const dec = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
-                if (!dec?.fields || dec.fields.length < 3)
+                const token = await this.parseBasketTokenOutput(result, out, originator, basket);
+                if (token == null)
                     continue;
-                const domainDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(dec.fields[0]));
-                if (this.normalizeOriginator(domainDecoded) !== originator)
+                if (!includeExpired && this.isTokenExpired(token.expiry))
                     continue;
-                const expiryDecoded = Number.parseInt(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(dec.fields[1])), 10);
-                const basketDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(dec.fields[2]));
-                if (basketDecoded !== basket)
-                    continue;
-                if (!includeExpired && this.isTokenExpired(expiryDecoded))
-                    continue;
-                return {
-                    tx: tx.toBEEF(),
-                    txid,
-                    outputIndex,
-                    outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
-                    satoshis: out.satoshis,
-                    originator,
-                    rawOriginator: domainDecoded,
-                    basketName: basketDecoded,
-                    expiry: expiryDecoded
-                };
+                return token;
             }
         }
         return undefined;
@@ -1937,42 +2030,18 @@ class WalletPermissionsManager {
                 include: 'entire transactions'
             }, this.adminOriginator);
             for (const out of result.outputs) {
-                const [txid, outputIndex] = this.parseOutpoint(out.outpoint);
-                const tx = this.transactionFromResultBeef(result, txid);
-                const dec = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
-                if (!dec?.fields || dec.fields.length < 6)
-                    continue;
-                const [domainRaw, expiryRaw, privRaw, typeRaw, fieldsRaw, verifierRaw] = dec.fields;
-                const domainDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw));
-                if (this.normalizeOriginator(domainDecoded) !== originator)
-                    continue;
-                const expiryDecoded = Number.parseInt(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10);
-                const privDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(privRaw)) === 'true';
-                const typeDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(typeRaw));
-                const verifierDec = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(verifierRaw));
-                const allFields = JSON.parse(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(fieldsRaw)));
-                if (privDecoded !== !!privileged || typeDecoded !== certType || verifierDec !== verifier)
-                    continue;
-                // Check if 'fields' is a subset of 'allFields'
-                const setAll = new Set(allFields);
-                if (fields.some(f => !setAll.has(f)))
-                    continue;
-                if (!includeExpired && this.isTokenExpired(expiryDecoded))
-                    continue;
-                return {
-                    tx: tx.toBEEF(),
-                    txid,
-                    outputIndex,
-                    outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
-                    satoshis: out.satoshis,
+                const token = await this.parseCertificateTokenOutput(result, out, {
                     originator,
-                    rawOriginator: domainDecoded,
                     privileged,
-                    verifier: verifierDec,
-                    certType: typeDecoded,
-                    certFields: allFields,
-                    expiry: expiryDecoded
-                };
+                    verifier,
+                    certType,
+                    fields
+                });
+                if (token == null)
+                    continue;
+                if (!includeExpired && this.isTokenExpired(token.expiry))
+                    continue;
+                return token;
             }
         }
         return undefined;
@@ -2088,7 +2157,7 @@ class WalletPermissionsManager {
     async mapWithConcurrency(items, concurrency, fn) {
         if (items.length === 0)
             return [];
-        const results = new Array(items.length);
+        const results = Array.from({ length: items.length });
         let i = 0;
         const worker = async () => {
             while (true) {
@@ -2228,7 +2297,7 @@ class WalletPermissionsManager {
                     satoshis: 1,
                     outputDescription: 'Renewed permission token',
                     ...(opts?.basket ? { basket: opts.basket } : {}),
-                    ...((opts?.tags == null) ? {} : { tags: opts.tags })
+                    ...(opts?.tags == null ? {} : { tags: opts.tags })
                 }
             ],
             options: {
@@ -2417,7 +2486,7 @@ class WalletPermissionsManager {
     async listProtocolPermissions({ originator, privileged, protocolName, protocolSecurityLevel, counterparty } = {}) {
         const baseTags = this.buildProtocolFilterTags({ privileged, protocolName, protocolSecurityLevel, counterparty });
         const originFilter = originator ? this.prepareOriginator(originator) : undefined;
-        const originVariants = (originFilter == null) ? [undefined] : originFilter.lookupValues;
+        const originVariants = originFilter == null ? [undefined] : originFilter.lookupValues;
         const seen = new Set();
         const tokens = [];
         for (const originTag of originVariants) {
@@ -2452,15 +2521,22 @@ class WalletPermissionsManager {
                 continue;
             const f = await this.decryptProtocolTokenFields(dec.fields);
             const normalizedDomain = this.normalizeOriginator(f.domainDecoded);
-            if ((originFilter != null) && normalizedDomain !== originFilter.normalized)
+            if (originFilter != null && normalizedDomain !== originFilter.normalized)
                 continue;
             seen.add(out.outpoint);
             tokens.push({
-                tx: tx.toBEEF(), txid, outputIndex,
+                tx: tx.toBEEF(),
+                txid,
+                outputIndex,
                 outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
-                satoshis: out.satoshis, originator: normalizedDomain, rawOriginator: f.domainDecoded,
-                expiry: f.expiryDecoded, privileged: f.privDecoded,
-                securityLevel: f.secLevelDecoded, protocol: f.protoNameDecoded, counterparty: f.cptyDecoded
+                satoshis: out.satoshis,
+                originator: normalizedDomain,
+                rawOriginator: f.domainDecoded,
+                expiry: f.expiryDecoded,
+                privileged: f.privDecoded,
+                securityLevel: f.secLevelDecoded,
+                protocol: f.protoNameDecoded,
+                counterparty: f.cptyDecoded
             });
         }
     }
@@ -2495,7 +2571,7 @@ class WalletPermissionsManager {
             baseTags.push(`basket ${params.basket}`);
         }
         const originFilter = params.originator ? this.prepareOriginator(params.originator) : undefined;
-        const originVariants = (originFilter == null) ? [undefined] : originFilter.lookupValues;
+        const originVariants = originFilter == null ? [undefined] : originFilter.lookupValues;
         const seen = new Set();
         const tokens = [];
         for (const originTag of originVariants) {
@@ -2510,37 +2586,41 @@ class WalletPermissionsManager {
                 include: 'entire transactions',
                 limit: 10000
             }, this.adminOriginator);
-            for (const out of result.outputs) {
-                if (seen.has(out.outpoint))
-                    continue;
-                const [txid, outputIndex] = this.parseOutpoint(out.outpoint);
-                const tx = this.transactionFromResultBeef(result, txid);
-                const dec = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
-                if (!dec?.fields || dec.fields.length < 3)
-                    continue;
-                const [domainRaw, expiryRaw, basketRaw] = dec.fields;
-                const domainDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw));
-                const normalizedDomain = this.normalizeOriginator(domainDecoded);
-                if ((originFilter != null) && normalizedDomain !== originFilter.normalized)
-                    continue;
-                const expiryDecoded = Number.parseInt(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10);
-                const basketDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(basketRaw));
-                seen.add(out.outpoint);
-                tokens.push({
-                    tx: tx.toBEEF(),
-                    txid,
-                    outputIndex,
-                    satoshis: out.satoshis,
-                    outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
-                    originator: normalizedDomain,
-                    rawOriginator: domainDecoded,
-                    basketName: basketDecoded,
-                    expiry: expiryDecoded
-                });
-            }
+            await this.collectBasketTokens(result, originFilter, seen, tokens);
         }
         return tokens;
     }
+    /** Decodes and appends basket permission tokens from a listOutputs result. */
+    async collectBasketTokens(result, originFilter, seen, tokens) {
+        for (const out of result.outputs) {
+            if (seen.has(out.outpoint))
+                continue;
+            const [txid, outputIndex] = this.parseOutpoint(out.outpoint);
+            const tx = this.transactionFromResultBeef(result, txid);
+            const dec = sdk_1.PushDrop.decode(tx.outputs[outputIndex].lockingScript);
+            if (!dec?.fields || dec.fields.length < 3)
+                continue;
+            const [domainRaw, expiryRaw, basketRaw] = dec.fields;
+            const domainDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw));
+            const normalizedDomain = this.normalizeOriginator(domainDecoded);
+            if (originFilter != null && normalizedDomain !== originFilter.normalized)
+                continue;
+            const expiryDecoded = Number.parseInt(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10);
+            const basketDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(basketRaw));
+            seen.add(out.outpoint);
+            tokens.push({
+                tx: tx.toBEEF(),
+                txid,
+                outputIndex,
+                satoshis: out.satoshis,
+                outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
+                originator: normalizedDomain,
+                rawOriginator: domainDecoded,
+                basketName: basketDecoded,
+                expiry: expiryDecoded
+            });
+        }
+    }
     /**
      * Returns `true` if the originator already holds a valid unexpired basket permission for `basket`.
      */
@@ -2632,7 +2712,7 @@ class WalletPermissionsManager {
         if (params.verifier)
             baseTags.push(`verifier ${params.verifier}`);
         const originFilter = params.originator ? this.prepareOriginator(params.originator) : undefined;
-        const originVariants = (originFilter == null) ? [undefined] : originFilter.lookupValues;
+        const originVariants = originFilter == null ? [undefined] : originFilter.lookupValues;
         const seen = new Set();
         const tokens = [];
         for (const originTag of originVariants) {
@@ -2655,7 +2735,7 @@ class WalletPermissionsManager {
             const [domainRaw, expiryRaw, privRaw, typeRaw, fieldsRaw, verifierRaw] = dec.fields;
             const domainDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(domainRaw));
             const normalizedDomain = this.normalizeOriginator(domainDecoded);
-            if ((originFilter != null) && normalizedDomain !== originFilter.normalized)
+            if (originFilter != null && normalizedDomain !== originFilter.normalized)
                 continue;
             const expiryDecoded = Number.parseInt(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(expiryRaw)), 10);
             const privDecoded = sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(privRaw)) === 'true';
@@ -2664,11 +2744,18 @@ class WalletPermissionsManager {
             const allFields = JSON.parse(sdk_1.Utils.toUTF8(await this.decryptPermissionTokenField(fieldsRaw)));
             seen.add(out.outpoint);
             tokens.push({
-                tx: tx.toBEEF(), txid, outputIndex, satoshis: out.satoshis,
+                tx: tx.toBEEF(),
+                txid,
+                outputIndex,
+                satoshis: out.satoshis,
                 outputScript: tx.outputs[outputIndex].lockingScript.toHex(),
-                originator: normalizedDomain, rawOriginator: domainDecoded,
-                privileged: privDecoded, certType: typeDecoded, certFields: allFields,
-                verifier: verifierDec, expiry: expiryDecoded
+                originator: normalizedDomain,
+                rawOriginator: domainDecoded,
+                privileged: privDecoded,
+                certType: typeDecoded,
+                certFields: allFields,
+                verifier: verifierDec,
+                expiry: expiryDecoded
             });
         }
     }
@@ -2713,7 +2800,7 @@ class WalletPermissionsManager {
                 ? this.listSpendingAuthorizations({ originator: preparedOriginator.normalized })
                 : Promise.resolve([])
         ]);
-        const spendingTokenList = (spendingTokens.length > 0) ? [spendingTokens[0]] : [];
+        const spendingTokenList = spendingTokens.length > 0 ? [spendingTokens[0]] : [];
         const allTokens = [...protocolTokens, ...basketTokens, ...certificateTokens, ...spendingTokenList];
         const seen = new Set();
         const deduped = allTokens.filter(t => {
@@ -2833,11 +2920,21 @@ class WalletPermissionsManager {
         const nonPLabels = this.splitLabelsByPermissionModule(args.labels, pModulesByScheme);
         // 2) Check permissions for non-P baskets
         for (const basket of nonPBaskets) {
-            await this.ensureBasketAccess({ originator: originator, basket, reason: args.description, usageType: 'insertion' });
+            await this.ensureBasketAccess({
+                originator: originator,
+                basket,
+                reason: args.description,
+                usageType: 'insertion'
+            });
         }
         // 3) Check permissions for non-P labels
         for (const lbl of nonPLabels) {
-            await this.ensureLabelAccess({ originator: originator, label: lbl, reason: args.description, usageType: 'apply' });
+            await this.ensureLabelAccess({
+                originator: originator,
+                label: lbl,
+                reason: args.description,
+                usageType: 'apply'
+            });
         }
         // 4) Force signAndProcess=false unless the originator is admin and explicitly sets it to true.
         const modifiedOptions = this.enforceSignAndProcess(args.options, originator);
@@ -2875,7 +2972,12 @@ class WalletPermissionsManager {
         // 8) If netSpent > 0, require spending authorization. Abort if denied.
         if (netSpent > 0) {
             try {
-                await this.ensureSpendingAuthorization({ originator: originator, satoshis: netSpent, lineItems, reason: originalDescription });
+                await this.ensureSpendingAuthorization({
+                    originator: originator,
+                    satoshis: netSpent,
+                    lineItems,
+                    reason: originalDescription
+                });
             }
             catch (err) {
                 await this.underlying.abortAction({ reference });
@@ -2937,7 +3039,9 @@ class WalletPermissionsManager {
             }
         });
         await Promise.all([
-            (async () => { args.description = await this.maybeEncryptMetadata(args.description); })(),
+            (async () => {
+                args.description = await this.maybeEncryptMetadata(args.description);
+            })(),
             ...inputEncryptionTasks,
             ...outputEncryptionTasks
         ]);
@@ -2950,7 +3054,11 @@ class WalletPermissionsManager {
         const pModules = Array.from(pModulesByScheme.values());
         let transformedArgs = finalArgs;
         for (const module of pModules) {
-            const transformed = await module.onRequest({ method: 'createAction', args: transformedArgs, originator: originator });
+            const transformed = await module.onRequest({
+                method: 'createAction',
+                args: transformedArgs,
+                originator: originator
+            });
             transformedArgs = transformed.args;
         }
         let createResult = await this.underlying.createAction(transformedArgs, originator);
@@ -3094,85 +3202,86 @@ class WalletPermissionsManager {
         // 4) Transparently decrypt transaction metadata, if configured to do so.
         return await this.decryptListActionsMetadata(results);
     }
-    async internalizeAction(...args) {
-        const [requestArgs, originator] = args;
-        // 1) Identify unique P-modules involved (one per schemeID) from both baskets and labels
-        const pModulesByScheme = new Map();
-        const nonPBaskets = [];
-        // Check baskets for p modules
+    collectInternalizeActionBaskets(requestArgs, pModulesByScheme) {
+        const nonPModuleBaskets = [];
         for (const outIndex in requestArgs.outputs) {
-            const out = requestArgs.outputs[outIndex];
-            if (out.protocol === 'basket insertion') {
-                const basket = out.insertionRemittance.basket;
-                if (basket.startsWith('p ')) {
-                    const schemeID = basket.split(' ')[1];
-                    this.addPModuleByScheme(schemeID, 'basket', pModulesByScheme);
-                }
-                else {
-                    // Track non-P baskets for normal permission checks
-                    nonPBaskets.push({
-                        outIndex,
-                        basket,
-                        customInstructions: out.insertionRemittance.customInstructions
-                    });
-                }
+            const output = requestArgs.outputs[outIndex];
+            if (output.protocol !== 'basket insertion')
+                continue;
+            const { basket, customInstructions } = output.insertionRemittance;
+            if (basket.startsWith('p ')) {
+                this.addPModuleByScheme(basket.split(' ')[1], 'basket', pModulesByScheme);
+            }
+            else {
+                nonPModuleBaskets.push({ outIndex, basket, customInstructions });
             }
         }
-        // Check labels for p modules
-        const nonPLabels = this.splitLabelsByPermissionModule(requestArgs.labels, pModulesByScheme);
-        // 2) Check permissions for non-P baskets
-        for (const { outIndex, basket, customInstructions } of nonPBaskets) {
+        return nonPModuleBaskets;
+    }
+    async authorizeInternalizeActionBaskets(requestArgs, originator, baskets) {
+        for (const { outIndex, basket, customInstructions } of baskets) {
             await this.ensureBasketAccess({
-                originator: originator,
+                originator,
                 basket,
                 reason: requestArgs.description,
                 usageType: 'insertion'
             });
-            if (customInstructions) {
-                requestArgs.outputs[outIndex].insertionRemittance.customInstructions =
-                    await this.maybeEncryptMetadata(customInstructions);
-            }
+            if (customInstructions == null || customInstructions === '')
+                continue;
+            requestArgs.outputs[outIndex].insertionRemittance.customInstructions =
+                await this.maybeEncryptMetadata(customInstructions);
         }
-        // 3) Check permissions for non-P labels
-        for (const lbl of nonPLabels) {
+    }
+    async authorizeInternalizeActionLabels(requestArgs, originator, labels) {
+        for (const label of labels) {
             await this.ensureLabelAccess({
-                originator: originator,
-                label: lbl,
+                originator,
+                label,
                 reason: requestArgs.description,
                 usageType: 'apply'
             });
         }
+    }
+    async encryptInternalizeActionModuleMetadata(requestArgs) {
+        for (const outIndex in requestArgs.outputs) {
+            const output = requestArgs.outputs[outIndex];
+            const customInstructions = output.insertionRemittance?.customInstructions;
+            if (output.protocol !== 'basket insertion' || !customInstructions)
+                continue;
+            output.insertionRemittance.customInstructions = await this.maybeEncryptMetadata(customInstructions);
+        }
+    }
+    async runInternalizeActionModules(requestArgs, originator, modules) {
+        let transformedArgs = requestArgs;
+        for (const module of modules) {
+            const transformed = await module.onRequest({
+                method: 'internalizeAction',
+                args: transformedArgs,
+                originator
+            });
+            transformedArgs = transformed.args;
+        }
+        await this.encryptInternalizeActionModuleMetadata(transformedArgs);
+        let result = await this.underlying.internalizeAction(transformedArgs, originator);
+        for (let index = modules.length - 1; index >= 0; index--) {
+            result = await modules[index].onResponse(result, {
+                method: 'internalizeAction',
+                originator
+            });
+        }
+        return result;
+    }
+    async internalizeAction(...args) {
+        const [requestArgs, originator] = args;
+        // 1) Identify unique P-modules involved (one per schemeID) from both baskets and labels
+        const pModulesByScheme = new Map();
+        const nonPBaskets = this.collectInternalizeActionBaskets(requestArgs, pModulesByScheme);
+        const nonPLabels = this.splitLabelsByPermissionModule(requestArgs.labels, pModulesByScheme);
+        await this.authorizeInternalizeActionBaskets(requestArgs, originator, nonPBaskets);
+        await this.authorizeInternalizeActionLabels(requestArgs, originator, nonPLabels);
         // 4) Call underlying wallet, with P-module transformations if needed
         if (pModulesByScheme.size > 0) {
-            // P-modules are involved - chain transformations
-            const pModules = Array.from(pModulesByScheme.values());
-            // Chain onRequest calls through all modules in order
-            let transformedArgs = requestArgs;
-            for (const module of pModules) {
-                const transformed = await module.onRequest({
-                    method: 'internalizeAction',
-                    args: transformedArgs,
-                    originator: originator
-                });
-                transformedArgs = transformed.args;
-            }
-            // Encrypt custom instructions for p basket outputs
-            for (const outIndex in transformedArgs.outputs) {
-                const out = transformedArgs.outputs[outIndex];
-                if (out.protocol === 'basket insertion' && out.insertionRemittance?.customInstructions) {
-                    out.insertionRemittance.customInstructions = await this.maybeEncryptMetadata(out.insertionRemittance.customInstructions);
-                }
-            }
-            // Call underlying wallet with transformed args
-            let results = await this.underlying.internalizeAction(transformedArgs, originator);
-            // Chain onResponse calls in reverse order
-            for (let i = pModules.length - 1; i >= 0; i--) {
-                results = await pModules[i].onResponse(results, {
-                    method: 'internalizeAction',
-                    originator: originator
-                });
-            }
-            return results;
+            return await this.runInternalizeActionModules(requestArgs, originator, Array.from(pModulesByScheme.values()));
         }
         // No P-modules - call underlying wallet directly
         return await this.underlying.internalizeAction(...args);
@@ -3593,6 +3702,22 @@ class WalletPermissionsManager {
      * user a duplicate prompt for a grant they already made moments ago.
      */
     async hasRecentOrPendingGrant(cacheKey) {
+        if (!this.telemetry.enabled)
+            return await this.hasRecentOrPendingGrantCore(cacheKey);
+        return await this.telemetry.withSpan('wallet.permission.cache_check', {
+            component: 'wallet-permissions'
+        }, async (span) => {
+            const result = await this.hasRecentOrPendingGrantCore(cacheKey);
+            span.end({
+                attributes: {
+                    'permission.cache_hit': result,
+                    'permission.mint_in_flight': this.mintsInFlight.has(cacheKey)
+                }
+            });
+            return result;
+        });
+    }
+    async hasRecentOrPendingGrantCore(cacheKey) {
         if (this.isPermissionCached(cacheKey) || this.isRecentlyGranted(cacheKey))
             return true;
         const inFlight = this.mintsInFlight.get(cacheKey);