@bopen-io/wallet-toolbox 2.15.0-bopen.1 → 2.15.0

package/out/src/WalletPermissionsManager.js

@@ -1,13 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WalletPermissionsManager = void 0;
+exports.withBrc205Capabilities = withBrc205Capabilities;
+exports.encryptMetadata = encryptMetadata;
+exports.maybeDecryptMetadata = maybeDecryptMetadata;
 const validationHelpers_1 = require("@bsv/sdk/wallet/validationHelpers");
 const sdk_1 = require("@bsv/sdk");
 const utils_1 = require("@bsv/sdk/primitives/utils");
 const brc114ActionTimeLabels_1 = require("./utility/brc114ActionTimeLabels");
 const brc177NoSendExpiry_1 = require("./utility/brc177NoSendExpiry");
 const exactActionSpend_1 = require("./utility/exactActionSpend");
+const actionOutputAuthorizations_1 = require("./utility/actionOutputAuthorizations");
 const WERR_errors_1 = require("./sdk/WERR_errors");
+const types_1 = require("./sdk/types");
 // Imported from the leaf module directly (not generateChange.ts, which
 // transitively imports StorageProvider.ts and the full signer/create-action
 // module graph) to avoid an unrelated circular-import edge from this file.
@@ -115,6 +120,70 @@ function deepEqual(object1, object2) {
 function isObject(object) {
     return object != null && typeof object === 'object';
 }
+/**
+ * A permissions module handles request/response transformation for a specific P-protocol or P-basket scheme under BRC-98/99.
+ * Modules are registered in the config mapped by their scheme ID.
+ *
+ * Modules that handled a `createAction` returning a signable transaction also receive that action's
+ * `signAction` through `onRequest` and `onResponse`, with method `signAction` and the `action` being
+ * signed. A module may add `spends`
+ * for inputs it supplied.
+ */
+// BRC-205 attribute grammar: key = lower *( lower / DIGIT / "-" ); value = 1*( unreserved / pct-encoded ).
+const BRC205_KEY = /^[a-z][a-z0-9-]*$/;
+const BRC205_VALUE = /^(?:[A-Za-z0-9._~-]|%[0-9A-F]{2})+$/;
+const BRC205_MAX_KEY_BYTES = 64;
+const BRC205_MAX_VALUE_BYTES = 256;
+const BRC205_MAX_ATTRIBUTES = 24;
+const BRC205_MAX_BYTES = 2048;
+/** UTF-16 code-unit order: locale-independent, so the advertised attribute order is stable everywhere. */
+const compareCodeUnits = (a, b) => Number(a > b) - Number(a < b);
+/**
+ * Appends the BRC-205 capability attributes of `modules` to a wallet version string:
+ * `base; key=value; key2=value2;`, one space after every nonterminal semicolon, no spaces around
+ * `=`, a trailing semicolon when attributes are present. Modules are visited by scheme id and
+ * their keys in order, so the result is deterministic. Attributes the underlying string already
+ * carries are kept and their keys are not repeated; an invalid key or value, or one that would
+ * exceed BRC-205's limits, is left out. With nothing to add the string is returned unchanged.
+ */
+function withBrc205Capabilities(version, modules) {
+    const separator = version.indexOf(';');
+    const base = separator === -1 ? version : version.slice(0, separator);
+    const attributes = separator === -1
+        ? []
+        : version
+            .slice(separator + 1)
+            .split(';')
+            .map(attribute => attribute.trim())
+            .filter(attribute => attribute !== '');
+    const keys = new Set(attributes.map(attribute => attribute.split('=')[0]));
+    let added = 0;
+    for (const scheme of Object.keys(modules).sort(compareCodeUnits)) {
+        const capabilities = modules[scheme]?.capabilities ?? {};
+        for (const key of Object.keys(capabilities).sort(compareCodeUnits)) {
+            const value = capabilities[key];
+            if (!BRC205_KEY.test(key) ||
+                key.length > BRC205_MAX_KEY_BYTES ||
+                typeof value !== 'string' ||
+                !BRC205_VALUE.test(value) ||
+                value.length > BRC205_MAX_VALUE_BYTES ||
+                keys.has(key) ||
+                attributes.length >= BRC205_MAX_ATTRIBUTES) {
+                continue;
+            }
+            const attribute = `${key}=${value}`;
+            const candidate = `${base}; ${[...attributes, attribute].join('; ')};`;
+            if (candidate.length > BRC205_MAX_BYTES)
+                continue;
+            keys.add(key);
+            attributes.push(attribute);
+            added++;
+        }
+    }
+    if (added === 0)
+        return version;
+    return `${base}; ${attributes.join('; ')};`;
+}
 /**
  * A map from each permission type to a special "admin basket" name used for storing
  * the tokens. The tokens themselves are unspent transaction outputs (UTXOs) with a
@@ -126,6 +195,42 @@ const BASKET_MAP = {
     certificate: 'admin certificate-access',
     spending: 'admin spending-authorization'
 };
+/**
+ * Preserves the confidentiality of transaction descriptions, input/output descriptions and
+ * custom instructions from lower storage layers. Always used with `keyID="1"` and `counterparty="self"`.
+ */
+const METADATA_ENCRYPTION_PROTOCOL = [2, 'admin metadata encryption'];
+/**
+ * Encrypts metadata through `wallet` as a permissions manager with `encryptWalletMetadata` does.
+ * Permission modules use this for metadata they store through the underlying wallet directly.
+ */
+async function encryptMetadata(wallet, plaintext, originator) {
+    const { ciphertext } = await wallet.encrypt({
+        plaintext: (0, utils_1.toArray)(plaintext, 'utf8'),
+        protocolID: METADATA_ENCRYPTION_PROTOCOL,
+        keyID: '1'
+    }, originator);
+    return (0, utils_1.toBase64)(ciphertext);
+}
+/**
+ * Decrypts metadata that a permissions manager with `encryptWalletMetadata` stored through `wallet`.
+ * A value that does not decrypt, such as metadata stored without encryption, is returned unchanged.
+ * Permission modules use this to read metadata from their own baskets through the underlying wallet.
+ */
+async function maybeDecryptMetadata(wallet, ciphertext, originator) {
+    try {
+        const { plaintext } = await wallet.decrypt({
+            ciphertext: (0, utils_1.toArray)(ciphertext, 'base64'),
+            protocolID: METADATA_ENCRYPTION_PROTOCOL,
+            keyID: '1'
+        }, originator);
+        return (0, utils_1.toUTF8)(plaintext);
+    }
+    catch {
+        // Decryption failed (e.g. wrong key, unencrypted legacy value) — return original string unchanged
+        return ciphertext;
+    }
+}
 /**
  * @class WalletPermissionsManager
  *
@@ -196,6 +301,10 @@ class WalletPermissionsManager {
     blockedActionReferences = new Set();
     /** Pending references whose action was created with `noSend`. */
     pendingNoSendReferences = new Set();
+    /** P-modules that handled each pending action's createAction, in request order. */
+    pendingActionModules = new Map();
+    /** The createAction arguments those P-modules returned, for their signAction hooks. */
+    pendingActionCreateArgs = new Map();
     /**
      * Originator binding for signed no-send actions, keyed by lowercase txid.
      * Signing drops the pending reference, so without this a non-admin caller
@@ -284,7 +393,12 @@ class WalletPermissionsManager {
                 ...config.permissionModules,
                 // BRC-177 is a built-in reserved BRC-111 module in every Toolbox wallet.
                 nosend: {
+                    // BRC-177 L365: this revision, including batches and `never`.
+                    capabilities: { 'brc177-nosend': '2' },
                     onRequest: async (req) => {
+                        // Signing an action this module already authorized at createAction needs nothing further.
+                        if (req.method === 'signAction')
+                            return { args: req.args };
                         const labels = req.args.labels;
                         (0, brc177NoSendExpiry_1.parseBrc177NoSendExpiryLabels)(labels);
                         if (req.method !== 'createAction' && req.method !== 'listActions') {
@@ -1867,14 +1981,6 @@ class WalletPermissionsManager {
         2,
         'admin permission token encryption'
     ];
-    /**
-     * Similarly, we will use a "metadata encryption" protocol to preserve the confidentiality
-     * of transaction descriptions and input/output descriptions from lower storage layers.
-     */
-    static METADATA_ENCRYPTION_PROTOCOL = [
-        2,
-        'admin metadata encryption'
-    ];
     /** We always use `keyID="1"` and `counterparty="self"` for these encryption ops. */
     async encryptPermissionTokenField(plaintext) {
         const data = typeof plaintext === 'string' ? (0, utils_1.toArray)(plaintext, 'utf8') : plaintext;
@@ -2003,12 +2109,7 @@ class WalletPermissionsManager {
         if (!this.config.encryptWalletMetadata) {
             return plaintext;
         }
-        const { ciphertext } = await this.underlying.encrypt({
-            plaintext: (0, utils_1.toArray)(plaintext, 'utf8'),
-            protocolID: WalletPermissionsManager.METADATA_ENCRYPTION_PROTOCOL,
-            keyID: '1'
-        }, this.adminOriginator);
-        return (0, utils_1.toBase64)(ciphertext);
+        return await encryptMetadata(this.underlying, plaintext, this.adminOriginator);
     }
     /**
      * Attempts to decrypt metadata. if decryption fails, assumes the value is already plaintext and returns it.
@@ -2016,18 +2117,7 @@ class WalletPermissionsManager {
      * @returns The decrypted metadata. If decryption fails, returns the original value instead.
      */
     async maybeDecryptMetadata(ciphertext) {
-        try {
-            const { plaintext } = await this.underlying.decrypt({
-                ciphertext: (0, utils_1.toArray)(ciphertext, 'base64'),
-                protocolID: WalletPermissionsManager.METADATA_ENCRYPTION_PROTOCOL,
-                keyID: '1'
-            }, this.adminOriginator);
-            return (0, utils_1.toUTF8)(plaintext);
-        }
-        catch {
-            // Decryption failed (e.g. wrong key, unencrypted legacy value) — return original string unchanged
-            return ciphertext;
-        }
+        return await maybeDecryptMetadata(this.underlying, ciphertext, this.adminOriginator);
     }
     /** Helper to see if a token's expiry is in the past. */
     isTokenExpired(expiry) {
@@ -3106,8 +3196,10 @@ class WalletPermissionsManager {
             labels: [...(args.labels || []), `admin originator ${originator}`, `admin month ${this.getCurrentMonthYearUTC()}`]
         };
         let createResult;
+        let moduleArgs;
         try {
-            createResult = await this.callCreateActionWithPModules(finalArgs, pModulesByScheme, originator);
+            ;
+            ({ createResult, moduleArgs } = await this.callCreateActionWithPModules(finalArgs, pModulesByScheme, originator));
         }
         catch (error) {
             this.forgetSentNoSendActionsInError(error);
@@ -3120,7 +3212,8 @@ class WalletPermissionsManager {
         // data. This ensures malformed BEEF is still aborted and cannot leave an
         // untracked action that may later be signed under another originator.
         const reference = createResult.signableTransaction.reference;
-        this.bindPendingAction(reference, originator, vargs.isNoSend);
+        const pModules = Array.from(pModulesByScheme.values());
+        this.bindPendingAction(reference, originator, vargs.isNoSend, pModules, moduleArgs);
         // 7a) Parse the signable tx to determine net spend, then gate on spending
         // authorization. SECURITY (GHSA-36f9-7rg5-cpf8) defense-in-depth: confirm every
         // caller-requested output actually appears in the transaction we are about to
@@ -3167,30 +3260,34 @@ class WalletPermissionsManager {
         // 9) Finalize or return the signable transaction based on whether more signatures are needed.
         if (vargs.isSignAction)
             return createResult;
+        let signResult;
+        const action = this.signingAction(reference, vargs.isNoSend);
         try {
-            const signResult = await this.underlying.signAction({
+            const signArgs = await this.signActionArgsThroughPModules(pModules, {
                 reference,
                 spends: {},
                 options: { ...args.options, returnTXIDOnly: false }
-            }, originator);
-            this.assertAuthorizedSignResult(reference, {}, signResult);
+            }, action, originator);
+            signResult = await this.underlying.signAction(signArgs, originator);
+            this.assertAuthorizedSignResult(reference, signArgs.spends, signResult);
             this.clearPendingAction(reference);
             if (vargs.isNoSend && signResult.txid != null) {
                 this.recordNoSendAction(signResult.txid, originator);
             }
             this.forgetSentNoSendActions(signResult.sendWithResults);
-            return {
-                ...createResult,
-                ...signResult,
-                noSendChange: noSendChangeOnSignedTransaction(createResult.noSendChange, signResult.txid),
-                signableTransaction: undefined
-            };
         }
         catch (error) {
             this.forgetSentNoSendActionsInError(error);
             await this.blockAndAbortAction(reference);
             throw error;
         }
+        signResult = await this.signActionResultThroughPModules(pModules, signResult, action, originator);
+        return {
+            ...createResult,
+            ...signResult,
+            noSendChange: noSendChangeOnSignedTransaction(createResult.noSendChange, signResult.txid),
+            signableTransaction: undefined
+        };
     }
     /** Scans outputs to split P-scheme baskets from regular baskets; registers P-modules as a side effect. */
     collectNonPBaskets(outputs, pModulesByScheme) {
@@ -3235,7 +3332,8 @@ class WalletPermissionsManager {
                 originalOutputDescriptions[i] = output.outputDescription;
                 output.outputDescription = await this.maybeEncryptMetadata(output.outputDescription);
             }
-            if (output.customInstructions) {
+            // P-basket custom instructions are encrypted after the permission modules run.
+            if (output.customInstructions && output.basket?.startsWith('p ') !== true) {
                 output.customInstructions = await this.maybeEncryptMetadata(output.customInstructions);
             }
         });
@@ -3248,6 +3346,15 @@ class WalletPermissionsManager {
         ]);
         return { originalInputDescriptions, originalOutputDescriptions };
     }
+    /** Encrypts P-basket output custom instructions as the permission modules left them. */
+    async encryptCreateActionModuleMetadata(args) {
+        if (args.outputs === undefined)
+            return args;
+        const outputs = await Promise.all(args.outputs.map(async (output) => !output.customInstructions || output.basket?.startsWith('p ') !== true
+            ? output
+            : { ...output, customInstructions: await this.maybeEncryptMetadata(output.customInstructions) }));
+        return { ...args, outputs };
+    }
     /** Calls underlying createAction, chaining P-module request/response transforms when needed. */
     async callCreateActionWithPModules(finalArgs, pModulesByScheme, originator) {
         const pModules = Array.from(pModulesByScheme.values());
@@ -3260,7 +3367,9 @@ class WalletPermissionsManager {
             });
             transformedArgs = transformed.args;
         }
-        let createResult = await this.underlying.createAction(transformedArgs, originator);
+        const moduleArgs = transformedArgs;
+        let createResult = await this.underlying.createAction(await this.encryptCreateActionModuleMetadata(moduleArgs), originator);
+        const locallyAuthorizedResult = createResult;
         const exactWalletSpend = (0, exactActionSpend_1.getExactActionSpend)(createResult);
         for (let i = pModules.length - 1; i >= 0; i--) {
             createResult = await pModules[i].onResponse(createResult, { method: 'createAction', originator: originator });
@@ -3271,7 +3380,8 @@ class WalletPermissionsManager {
         if (exactWalletSpend !== undefined) {
             (0, exactActionSpend_1.setExactActionSpend)(publicResult, exactWalletSpend);
         }
-        return publicResult;
+        (0, actionOutputAuthorizations_1.copyActionOutputAuthorizations)(locallyAuthorizedResult, publicResult);
+        return { createResult: publicResult, moduleArgs };
     }
     /**
      * Computes the net satoshis the originator is spending in a createAction call,
@@ -3505,19 +3615,25 @@ class WalletPermissionsManager {
             throw new WERR_errors_1.WERR_UNAUTHORIZED('The action reference belongs to a different originator.');
         }
     }
-    bindPendingAction(reference, originator, noSend) {
+    bindPendingAction(reference, originator, noSend, pModules, createArgs) {
         if (this.pendingActionOriginators.has(reference)) {
             throw new WERR_errors_1.WERR_UNAUTHORIZED('The action reference is already pending.');
         }
         this.pendingActionOriginators.set(reference, originator ?? '');
         if (noSend)
             this.pendingNoSendReferences.add(reference);
+        if (pModules.length > 0) {
+            this.pendingActionModules.set(reference, pModules);
+            this.pendingActionCreateArgs.set(reference, createArgs);
+        }
     }
     clearPendingAction(reference) {
         this.pendingActionOriginators.delete(reference);
         this.pendingActionTemplates.delete(reference);
         this.blockedActionReferences.delete(reference);
         this.pendingNoSendReferences.delete(reference);
+        this.pendingActionModules.delete(reference);
+        this.pendingActionCreateArgs.delete(reference);
     }
     /** Lets the originator that created a signed no-send action, and only it, abort it. */
     recordNoSendAction(txid, originator, reference) {
@@ -3554,29 +3670,51 @@ class WalletPermissionsManager {
             this.forgetSentNoSendActions(error.sendWithResults);
         }
     }
+    /** The action a signAction hook call signs, from the template bound at createAction. */
+    signingAction(reference, noSend) {
+        const transaction = this.pendingActionTemplates.get(reference);
+        if (transaction === undefined)
+            return undefined;
+        const createArgs = this.pendingActionCreateArgs.get(reference);
+        return createArgs === undefined
+            ? { reference, transaction, noSend }
+            : { reference, transaction, noSend, createArgs };
+    }
+    /** Passes signAction args through the P-modules that handled the action's createAction, in request order. */
+    async signActionArgsThroughPModules(pModules, args, action, originator) {
+        return (await pModules.reduce(async (previous, module) => (await module.onRequest({ method: 'signAction', args: await previous, originator: originator, action })).args, Promise.resolve(args)));
+    }
+    /** Passes a signAction result back through the same P-modules in reverse order. */
+    async signActionResultThroughPModules(pModules, result, action, originator) {
+        return await pModules.reduceRight(async (previous, module) => await module.onResponse(await previous, { method: 'signAction', originator: originator, action }), Promise.resolve(result));
+    }
     async signAction(...args) {
         const [requestArgs, originator] = args;
         this.assertPendingActionOriginator(requestArgs.reference, originator, false);
         // The wallet takes noSend from signAction's options, else from createAction's.
         const noSend = (requestArgs.options?.noSend ?? this.pendingNoSendReferences.has(requestArgs.reference)) === true;
+        const pModules = this.pendingActionModules.get(requestArgs.reference) ?? [];
+        const action = this.signingAction(requestArgs.reference, noSend);
+        let result;
         try {
-            const result = await this.underlying.signAction({
+            const signArgs = await this.signActionArgsThroughPModules(pModules, {
                 ...requestArgs,
                 options: { ...requestArgs.options, returnTXIDOnly: false }
-            }, originator);
-            this.assertAuthorizedSignResult(requestArgs.reference, requestArgs.spends, result);
+            }, action, originator);
+            result = await this.underlying.signAction(signArgs, originator);
+            this.assertAuthorizedSignResult(requestArgs.reference, signArgs.spends, result);
             this.clearPendingAction(requestArgs.reference);
             if (noSend && result.txid != null) {
                 this.recordNoSendAction(result.txid, originator, requestArgs.reference);
             }
             this.forgetSentNoSendActions(result.sendWithResults);
-            return result;
         }
         catch (error) {
             this.forgetSentNoSendActionsInError(error);
             await this.blockAndAbortAction(requestArgs.reference);
             throw error;
         }
+        return await this.signActionResultThroughPModules(pModules, result, action, originator);
     }
     async abortAction(...args) {
         const [requestArgs, originator] = args;
@@ -3689,14 +3827,29 @@ class WalletPermissionsManager {
             });
         }
     }
+    /**
+     * Encrypts custom instructions that permission modules can still introduce.
+     * Normal-basket instructions are already encrypted once by
+     * authorizeInternalizeActionBaskets, before modules run. Encrypting them
+     * again here wrapped ciphertext inside ciphertext whenever a registered
+     * p-label or p-basket caused modules to run, and listOutputs decrypts only
+     * one layer. Permission-module baskets are not covered by that earlier pass.
+     */
     async encryptInternalizeActionModuleMetadata(requestArgs) {
+        const encryptionTasks = [];
         for (const outIndex in requestArgs.outputs) {
             const output = requestArgs.outputs[outIndex];
-            const customInstructions = output.insertionRemittance?.customInstructions;
-            if (output.protocol !== 'basket insertion' || !customInstructions)
+            const remittance = output.insertionRemittance;
+            const customInstructions = remittance?.customInstructions;
+            if (output.protocol !== 'basket insertion' || remittance == null || !customInstructions)
                 continue;
-            output.insertionRemittance.customInstructions = await this.maybeEncryptMetadata(customInstructions);
+            if (!remittance.basket.startsWith('p '))
+                continue;
+            encryptionTasks.push(this.maybeEncryptMetadata(customInstructions).then(encrypted => {
+                remittance.customInstructions = encrypted;
+            }));
         }
+        await Promise.all(encryptionTasks);
     }
     async runInternalizeActionModules(requestArgs, originator, modules) {
         let transformedArgs = requestArgs;
@@ -4090,8 +4243,16 @@ class WalletPermissionsManager {
     async getNetwork(...args) {
         return await this.underlying.getNetwork(...args);
     }
+    /**
+     * The underlying wallet's version string with the BRC-205 capability attributes of every
+     * configured permission module appended (see `withBrc205Capabilities`).
+     */
     async getVersion(...args) {
-        return await this.underlying.getVersion(...args);
+        const result = await this.underlying.getVersion(...args);
+        return {
+            ...result,
+            version: withBrc205Capabilities(result.version, this.config.permissionModules ?? {})
+        };
     }
     /* ---------------------------------------------------------------------
      *  8) INTERNAL HELPER UTILITIES
@@ -4144,6 +4305,9 @@ class WalletPermissionsManager {
             return true;
         if (basket.startsWith('admin'))
             return true;
+        // Lists P-basket outputs past their permission modules.
+        if (basket === types_1.specOpBasketPrefixOutputs)
+            return true;
         return false;
     }
     /**