@bsv/wallet-toolbox-client 1.7.22 → 1.8.1

package/out/src/WalletPermissionsManager.js

@@ -163,6 +163,68 @@ class WalletPermissionsManager {
             originator
         });
     }
+    /**
+     * Adds a permission module for the given schemeID if needed, throwing if unsupported.
+     */
+    addPModuleByScheme(schemeID, kind, pModulesByScheme) {
+        var _a;
+        if (pModulesByScheme.has(schemeID))
+            return;
+        const module = (_a = this.config.permissionModules) === null || _a === void 0 ? void 0 : _a[schemeID];
+        if (!module) {
+            throw new Error(`Unsupported P-${kind} scheme: p ${schemeID}`);
+        }
+        pModulesByScheme.set(schemeID, module);
+    }
+    /**
+     * Splits labels into P and non-P lists, registering any P-modules encountered.
+     *
+     * P-labels follow BRC-111 format: `p <moduleId> <payload>`
+     * - Must start with "p " (lowercase p + space)
+     * - Module ID must be at least 1 character with no spaces
+     * - Single space separates module ID from payload
+     * - Payload must be at least 1 character
+     *
+     * @example Valid: "p btms token123", "p invoicing invoice 2026-02-02"
+     * @example Invalid: "p btms" (no payload), "p btms " (empty payload), "p  data" (empty moduleId)
+     *
+     * @param labels - Array of label strings to process
+     * @param pModulesByScheme - Map to populate with discovered p-modules
+     * @returns Array of non-P labels for normal permission checks
+     * @throws Error if p-label format is invalid or module is unsupported
+     */
+    splitLabelsByPermissionModule(labels, pModulesByScheme) {
+        const nonPLabels = [];
+        if (!labels)
+            return nonPLabels;
+        for (const label of labels) {
+            if (label.startsWith('p ')) {
+                // Remove "p " prefix to get "moduleId payload"
+                const remainder = label.slice(2);
+                // Find the space that separates moduleId from payload
+                const separatorIndex = remainder.indexOf(' ');
+                // Validate: must have a space (separatorIndex > 0) and payload after it
+                // separatorIndex <= 0 means no space found or moduleId is empty
+                // separatorIndex === remainder.length - 1 means space is last char (no payload)
+                if (separatorIndex <= 0 || separatorIndex === remainder.length - 1) {
+                    throw new Error(`Invalid P-label format: ${label}`);
+                }
+                // Reject double spaces after moduleId (payload can't start with space)
+                if (remainder[separatorIndex + 1] === ' ') {
+                    throw new Error(`Invalid P-label format: ${label}`);
+                }
+                // Extract moduleId (substring before first space)
+                const schemeID = remainder.slice(0, separatorIndex);
+                // Register the module (throws if unsupported)
+                this.addPModuleByScheme(schemeID, 'label', pModulesByScheme);
+            }
+            else {
+                // Regular label - add to list for normal permission checks
+                nonPLabels.push(label);
+            }
+        }
+        return nonPLabels;
+    }
     /**
      * Decrypts custom instructions in listOutputs results if encryption is configured.
      */
@@ -176,6 +238,36 @@ class WalletPermissionsManager {
         }
         return results;
     }
+    /**
+     * Decrypts metadata in listActions results if encryption is configured.
+     */
+    async decryptListActionsMetadata(results) {
+        if (results.actions) {
+            for (let i = 0; i < results.actions.length; i++) {
+                if (results.actions[i].description) {
+                    results.actions[i].description = await this.maybeDecryptMetadata(results.actions[i].description);
+                }
+                if (results.actions[i].inputs) {
+                    for (let j = 0; j < results.actions[i].inputs.length; j++) {
+                        if (results.actions[i].inputs[j].inputDescription) {
+                            results.actions[i].inputs[j].inputDescription = await this.maybeDecryptMetadata(results.actions[i].inputs[j].inputDescription);
+                        }
+                    }
+                }
+                if (results.actions[i].outputs) {
+                    for (let j = 0; j < results.actions[i].outputs.length; j++) {
+                        if (results.actions[i].outputs[j].outputDescription) {
+                            results.actions[i].outputs[j].outputDescription = await this.maybeDecryptMetadata(results.actions[i].outputs[j].outputDescription);
+                        }
+                        if (results.actions[i].outputs[j].customInstructions) {
+                            results.actions[i].outputs[j].customInstructions = await this.maybeDecryptMetadata(results.actions[i].outputs[j].customInstructions);
+                        }
+                    }
+                }
+            }
+        }
+        return results;
+    }
     /* ---------------------------------------------------------------------
      *  1) PUBLIC API FOR REGISTERING CALLBACKS (UI PROMPTS, LOGGING, ETC.)
      * --------------------------------------------------------------------- */
@@ -316,91 +408,103 @@ class WalletPermissionsManager {
         if (!matching) {
             throw new Error('Request ID not found.');
         }
-        const originalRequest = matching.request;
-        const { originator, permissions: requestedPermissions, displayOriginator } = originalRequest;
-        const originLookupValues = this.buildOriginatorLookupValues(displayOriginator, originator);
-        // --- Validation: Ensure granted permissions are a subset of what was requested ---
-        if (params.granted.spendingAuthorization && !requestedPermissions.spendingAuthorization) {
-            throw new Error('Granted spending authorization was not part of the original request.');
-        }
-        if ((_a = params.granted.protocolPermissions) === null || _a === void 0 ? void 0 : _a.some(g => { var _a; return !((_a = requestedPermissions.protocolPermissions) === null || _a === void 0 ? void 0 : _a.find(r => deepEqual(r, g))); })) {
-            throw new Error('Granted protocol permissions are not a subset of the original request.');
-        }
-        if ((_b = params.granted.basketAccess) === null || _b === void 0 ? void 0 : _b.some(g => { var _a; return !((_a = requestedPermissions.basketAccess) === null || _a === void 0 ? void 0 : _a.find(r => deepEqual(r, g))); })) {
-            throw new Error('Granted basket access permissions are not a subset of the original request.');
-        }
-        if ((_c = params.granted.certificateAccess) === null || _c === void 0 ? void 0 : _c.some(g => { var _a; return !((_a = requestedPermissions.certificateAccess) === null || _a === void 0 ? void 0 : _a.find(r => deepEqual(r, g))); })) {
-            throw new Error('Granted certificate access permissions are not a subset of the original request.');
-        }
-        // --- End Validation ---
-        const expiry = params.expiry || 0; // default: never expires
-        const toCreate = [];
-        const toRenew = [];
-        if (params.granted.spendingAuthorization) {
-            toCreate.push({
-                request: {
-                    type: 'spending',
-                    originator,
-                    spending: { satoshis: params.granted.spendingAuthorization.amount },
-                    reason: params.granted.spendingAuthorization.description
-                },
-                expiry: 0,
-                amount: params.granted.spendingAuthorization.amount
-            });
-        }
-        const grantedProtocols = params.granted.protocolPermissions || [];
-        const protocolTokens = await this.mapWithConcurrency(grantedProtocols, 8, async (p) => {
-            const token = await this.findProtocolToken(originator, false, p.protocolID, p.counterparty || 'self', true, originLookupValues);
-            return { p, token };
-        });
-        for (const { p, token } of protocolTokens) {
-            const request = {
-                type: 'protocol',
-                originator,
-                privileged: false,
-                protocolID: p.protocolID,
-                counterparty: p.counterparty || 'self',
-                reason: p.description
-            };
-            if (token) {
-                toRenew.push({ oldToken: token, request, expiry });
+        try {
+            const originalRequest = matching.request;
+            const { originator, permissions: requestedPermissions, displayOriginator } = originalRequest;
+            const originLookupValues = this.buildOriginatorLookupValues(displayOriginator, originator);
+            // --- Validation: Ensure granted permissions are a subset of what was requested ---
+            if (params.granted.spendingAuthorization && !requestedPermissions.spendingAuthorization) {
+                throw new Error('Granted spending authorization was not part of the original request.');
             }
-            else {
-                toCreate.push({ request, expiry });
+            if ((_a = params.granted.protocolPermissions) === null || _a === void 0 ? void 0 : _a.some(g => { var _a; return !((_a = requestedPermissions.protocolPermissions) === null || _a === void 0 ? void 0 : _a.find(r => deepEqual(r, g))); })) {
+                throw new Error('Granted protocol permissions are not a subset of the original request.');
             }
-        }
-        for (const b of params.granted.basketAccess || []) {
-            toCreate.push({
-                request: { type: 'basket', originator, basket: b.basket, reason: b.description },
-                expiry
+            if ((_b = params.granted.basketAccess) === null || _b === void 0 ? void 0 : _b.some(g => { var _a; return !((_a = requestedPermissions.basketAccess) === null || _a === void 0 ? void 0 : _a.find(r => deepEqual(r, g))); })) {
+                throw new Error('Granted basket access permissions are not a subset of the original request.');
+            }
+            if ((_c = params.granted.certificateAccess) === null || _c === void 0 ? void 0 : _c.some(g => { var _a; return !((_a = requestedPermissions.certificateAccess) === null || _a === void 0 ? void 0 : _a.find(r => deepEqual(r, g))); })) {
+                throw new Error('Granted certificate access permissions are not a subset of the original request.');
+            }
+            // --- End Validation ---
+            const expiry = params.expiry || 0; // default: never expires
+            const toCreate = [];
+            const toRenew = [];
+            if (params.granted.spendingAuthorization) {
+                toCreate.push({
+                    request: {
+                        type: 'spending',
+                        originator,
+                        spending: { satoshis: params.granted.spendingAuthorization.amount },
+                        reason: params.granted.spendingAuthorization.description
+                    },
+                    expiry: 0,
+                    amount: params.granted.spendingAuthorization.amount
+                });
+            }
+            const grantedProtocols = params.granted.protocolPermissions || [];
+            const protocolTokens = await this.mapWithConcurrency(grantedProtocols, 8, async (p) => {
+                const token = await this.findProtocolToken(originator, false, p.protocolID, p.counterparty || 'self', true, originLookupValues);
+                return { p, token };
             });
-        }
-        for (const c of params.granted.certificateAccess || []) {
-            toCreate.push({
-                request: {
-                    type: 'certificate',
+            for (const { p, token } of protocolTokens) {
+                const request = {
+                    type: 'protocol',
                     originator,
                     privileged: false,
-                    certificate: {
-                        verifier: c.verifierPublicKey,
-                        certType: c.type,
-                        fields: c.fields
+                    protocolID: p.protocolID,
+                    counterparty: p.counterparty || 'self',
+                    reason: p.description
+                };
+                if (token) {
+                    toRenew.push({ oldToken: token, request, expiry });
+                }
+                else {
+                    toCreate.push({ request, expiry });
+                }
+            }
+            for (const b of params.granted.basketAccess || []) {
+                toCreate.push({
+                    request: { type: 'basket', originator, basket: b.basket, reason: b.description },
+                    expiry
+                });
+            }
+            for (const c of params.granted.certificateAccess || []) {
+                toCreate.push({
+                    request: {
+                        type: 'certificate',
+                        originator,
+                        privileged: false,
+                        certificate: {
+                            verifier: c.verifierPublicKey,
+                            certType: c.type,
+                            fields: c.fields
+                        },
+                        reason: c.description
                     },
-                    reason: c.description
-                },
-                expiry
-            });
+                    expiry
+                });
+            }
+            const created = await this.createPermissionTokensBestEffort(toCreate);
+            const renewed = await this.renewPermissionTokensBestEffort(toRenew);
+            for (const req of [...created, ...renewed]) {
+                this.markRecentGrant(req);
+            }
+            // Success - resolve all pending promises for this request
+            for (const p of matching.pending) {
+                p.resolve(true);
+            }
         }
-        const created = await this.createPermissionTokensBestEffort(toCreate);
-        const renewed = await this.renewPermissionTokensBestEffort(toRenew);
-        for (const req of [...created, ...renewed]) {
-            this.markRecentGrant(req);
+        catch (error) {
+            // Failure - reject all pending promises so callers don't hang forever
+            for (const p of matching.pending) {
+                p.reject(error);
+            }
+            throw error;
         }
-        // Resolve all pending promises for this request
-        for (const p of matching.pending) {
-            p.resolve(true);
+        finally {
+            // Always clean up the request entry
+            this.activeRequests.delete(params.requestID);
         }
-        this.activeRequests.delete(params.requestID);
     }
     /**
      * Denies a previously requested grouped permission.
@@ -2482,22 +2586,16 @@ class WalletPermissionsManager {
      *  7) BRC-100 WALLET INTERFACE FORWARDING WITH PERMISSION CHECKS
      * --------------------------------------------------------------------- */
     async createAction(args, originator) {
-        var _a;
-        // 1) Identify unique P-modules involved (one per schemeID)
+        // 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
         if (args.outputs) {
             for (const out of args.outputs) {
                 if (out.basket) {
                     if (out.basket.startsWith('p ')) {
                         const schemeID = out.basket.split(' ')[1];
-                        if (!pModulesByScheme.has(schemeID)) {
-                            const module = (_a = this.config.permissionModules) === null || _a === void 0 ? void 0 : _a[schemeID];
-                            if (!module) {
-                                throw new Error(`Unsupported P-basket scheme: p ${schemeID}`);
-                            }
-                            pModulesByScheme.set(schemeID, module);
-                        }
+                        this.addPModuleByScheme(schemeID, 'basket', pModulesByScheme);
                     }
                     else {
                         // Track non-P baskets for normal permission checks
@@ -2506,6 +2604,8 @@ class WalletPermissionsManager {
                 }
             }
         }
+        // Check labels for p modules
+        const nonPLabels = this.splitLabelsByPermissionModule(args.labels, pModulesByScheme);
         // 2) Check permissions for non-P baskets
         for (const basket of nonPBaskets) {
             await this.ensureBasketAccess({
@@ -2515,15 +2615,14 @@ class WalletPermissionsManager {
                 usageType: 'insertion'
             });
         }
-        if (args.labels) {
-            for (const lbl of args.labels) {
-                await this.ensureLabelAccess({
-                    originator: originator,
-                    label: lbl,
-                    reason: args.description,
-                    usageType: 'apply'
-                });
-            }
+        // 3) Check permissions for non-P labels
+        for (const lbl of nonPLabels) {
+            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.
@@ -2701,74 +2800,132 @@ class WalletPermissionsManager {
     }
     async listActions(...args) {
         const [requestArgs, originator] = args;
-        // for each label, ensure label access
-        if (requestArgs.labels) {
-            for (const lbl of requestArgs.labels) {
-                await this.ensureLabelAccess({
-                    originator: originator,
-                    label: lbl,
-                    reason: 'listActions',
-                    usageType: 'list'
+        // 1) Identify unique P-modules involved (one per schemeID, preserving label order)
+        const pModulesByScheme = new Map();
+        const nonPLabels = this.splitLabelsByPermissionModule(requestArgs.labels, pModulesByScheme);
+        // 2) Check permissions for non-P labels
+        for (const lbl of nonPLabels) {
+            await this.ensureLabelAccess({
+                originator: originator,
+                label: lbl,
+                reason: 'listActions',
+                usageType: 'list'
+            });
+        }
+        // 3) Call underlying wallet, with P-module transformations if needed
+        let results;
+        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: 'listActions',
+                    args: transformedArgs,
+                    originator: originator
                 });
+                transformedArgs = transformed.args;
             }
-        }
-        const results = await this.underlying.listActions(...args);
-        // Transparently decrypt transaction metadata, if configured to do so.
-        if (results.actions) {
-            for (let i = 0; i < results.actions.length; i++) {
-                if (results.actions[i].description) {
-                    results.actions[i].description = await this.maybeDecryptMetadata(results.actions[i].description);
-                }
-                if (results.actions[i].inputs) {
-                    for (let j = 0; j < results.actions[i].inputs.length; j++) {
-                        if (results.actions[i].inputs[j].inputDescription) {
-                            results.actions[i].inputs[j].inputDescription = await this.maybeDecryptMetadata(results.actions[i].inputs[j].inputDescription);
-                        }
-                    }
-                }
-                if (results.actions[i].outputs) {
-                    for (let j = 0; j < results.actions[i].outputs.length; j++) {
-                        if (results.actions[i].outputs[j].outputDescription) {
-                            results.actions[i].outputs[j].outputDescription = await this.maybeDecryptMetadata(results.actions[i].outputs[j].outputDescription);
-                        }
-                        if (results.actions[i].outputs[j].customInstructions) {
-                            results.actions[i].outputs[j].customInstructions = await this.maybeDecryptMetadata(results.actions[i].outputs[j].customInstructions);
-                        }
-                    }
-                }
+            // Call underlying wallet with transformed args
+            results = await this.underlying.listActions(transformedArgs, originator);
+            // Chain onResponse calls in reverse order
+            for (let i = pModules.length - 1; i >= 0; i--) {
+                results = await pModules[i].onResponse(results, {
+                    method: 'listActions',
+                    originator: originator
+                });
             }
         }
-        return results;
+        else {
+            // No P-modules - call underlying wallet directly
+            results = await this.underlying.listActions(...args);
+        }
+        // 4) Transparently decrypt transaction metadata, if configured to do so.
+        return await this.decryptListActionsMetadata(results);
     }
     async internalizeAction(...args) {
+        var _a;
         const [requestArgs, originator] = args;
-        // If the transaction is inserting outputs into baskets, we also ensure basket permission
+        // 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
         for (const outIndex in requestArgs.outputs) {
             const out = requestArgs.outputs[outIndex];
             if (out.protocol === 'basket insertion') {
-                // Delegate to permission module if needed
-                const pModuleResult = await this.delegateToPModuleIfNeeded(out.insertionRemittance.basket, 'internalizeAction', requestArgs, originator, async (transformedArgs) => {
-                    if (out.insertionRemittance.customInstructions) {
-                        ;
-                        transformedArgs.outputs[outIndex].insertionRemittance.customInstructions =
-                            await this.maybeEncryptMetadata(out.insertionRemittance.customInstructions);
-                    }
-                    return await this.underlying.internalizeAction(transformedArgs, originator);
-                });
-                if (pModuleResult !== null) {
-                    return pModuleResult;
+                const basket = out.insertionRemittance.basket;
+                if (basket.startsWith('p ')) {
+                    const schemeID = basket.split(' ')[1];
+                    this.addPModuleByScheme(schemeID, 'basket', pModulesByScheme);
                 }
-                await this.ensureBasketAccess({
-                    originator: originator,
-                    basket: out.insertionRemittance.basket,
-                    reason: requestArgs.description,
-                    usageType: 'insertion'
+                else {
+                    // Track non-P baskets for normal permission checks
+                    nonPBaskets.push({
+                        outIndex,
+                        basket,
+                        customInstructions: out.insertionRemittance.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) {
+            await this.ensureBasketAccess({
+                originator: originator,
+                basket,
+                reason: requestArgs.description,
+                usageType: 'insertion'
+            });
+            if (customInstructions) {
+                requestArgs.outputs[outIndex].insertionRemittance.customInstructions =
+                    await this.maybeEncryptMetadata(customInstructions);
+            }
+        }
+        // 3) Check permissions for non-P labels
+        for (const lbl of nonPLabels) {
+            await this.ensureLabelAccess({
+                originator: originator,
+                label: lbl,
+                reason: requestArgs.description,
+                usageType: 'apply'
+            });
+        }
+        // 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
                 });
-                if (out.insertionRemittance.customInstructions) {
-                    requestArgs.outputs[outIndex].insertionRemittance.customInstructions = await this.maybeEncryptMetadata(out.insertionRemittance.customInstructions);
+                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' && ((_a = out.insertionRemittance) === null || _a === void 0 ? void 0 : _a.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;
         }
+        // No P-modules - call underlying wallet directly
         return this.underlying.internalizeAction(...args);
     }
     async listOutputs(...args) {
@@ -3153,6 +3310,7 @@ class WalletPermissionsManager {
      * Checks if the given label is admin-reserved per BRC-100 rules:
      *
      *  - Must not start with `admin` (admin-reserved)
+     *  - Must not start with `p ` (permissioned labels requiring a permission module)
      *
      * If it violates these rules and the caller is not admin, we consider it "admin-only."
      */
@@ -3160,6 +3318,9 @@ class WalletPermissionsManager {
         if (label.startsWith('admin')) {
             return true;
         }
+        if (label.startsWith('p ')) {
+            return true;
+        }
         return false;
     }
     /**