@bsv/btms-permission-module 1.0.0

package/dist/BasicTokenModule.js

@@ -0,0 +1,1018 @@
+import { Hash, LockingScript, PushDrop, Transaction, Utils } from '@bsv/sdk';
+import { ISSUE_MARKER } from '@bsv/btms';
+import { P_BASKET_PREFIX, BTMS_FIELD } from './types';
+/**
+ * BasicTokenModule - BTMS Permission Module
+ *
+ * SECURITY MODEL:
+ * This module enforces permissions when spending BTMS tokens stored in
+ * permissioned baskets (format: "p btms <assetId>"). It prevents unauthorized
+ * token transfers by requiring explicit user approval for each transaction.
+ *
+ * THREAT MODEL:
+ * - Malicious dApp attempts to spend tokens without user knowledge
+ * - Malicious dApp gets approval for one transaction, attempts to sign different transaction
+ * - Malicious dApp attempts to bypass authorization checks
+ * - Malicious dApp attempts to steal tokens via preimage manipulation
+ *
+ * SECURITY BOUNDARIES:
+ * 1. createAction: Extracts token details and prompts user for approval
+ * 2. createSignature: Verifies session authorization + preimage integrity
+ * 3. Session authorization: Time-limited (60s) to prevent replay attacks
+ * 4. Preimage verification: Ensures signed transaction matches approved transaction
+ *
+ * AUTHORIZATION FLOW:
+ * 1. createAction → extract token info → prompt user → grant session auth
+ * 2. createSignature → verify session auth → verify preimage → allow signature
+ *
+ * ISSUANCE HANDLING:
+ * Token issuance is auto-approved (no user prompt) because:
+ * - Issuance creates new tokens (doesn't spend existing ones)
+ * - Detected by ISSUE_MARKER in locking script or btms_issue tag
+ * - Short signatures (<157 bytes) are assumed to be issuance
+ */
+export class BasicTokenModule {
+    requestTokenAccess;
+    btms;
+    /**
+     * Session-based authorization tracking.
+     *
+     * SECURITY: Time-limited to prevent replay attacks. Each approval expires after 60s.
+     * Key: originator (dApp identifier)
+     * Value: timestamp of approval (milliseconds since epoch)
+     */
+    sessionAuthorizations = new Map();
+    SESSION_TIMEOUT_MS = 60000; // 60 seconds
+    /**
+     * Authorized transaction data from createAction responses.
+     *
+     * SECURITY: Stores cryptographic commitments (hashOutputs, outpoints) to verify
+     * that createSignature is signing the exact transaction the user approved.
+     * This prevents a malicious dApp from getting approval for one transaction
+     * and then signing a different transaction.
+     *
+     * Key: originator (dApp identifier)
+     * Value: authorized transaction details (reference, hashOutputs, outpoints, timestamp)
+     */
+    authorizedTransactions = new Map();
+    /**
+     * Creates a new BasicTokenModule instance.
+     *
+     * @param requestTokenAccess - Callback to prompt user for token spending approval.
+     *   Should return true if user approves, false if denied.
+     *   SECURITY: This callback MUST be implemented securely to prevent UI spoofing.
+     * @param btms - BTMS instance for fetching token metadata via getAssetInfo
+     */
+    constructor(requestTokenAccess, btms) {
+        if (!requestTokenAccess || typeof requestTokenAccess !== 'function') {
+            throw new Error('requestTokenAccess callback is required');
+        }
+        this.requestTokenAccess = requestTokenAccess;
+        this.btms = btms;
+        // Start periodic cleanup of expired sessions
+        this.startSessionCleanup();
+    }
+    /**
+     * Periodic cleanup of expired session authorizations.
+     * Runs every 30 seconds to prevent memory leaks.
+     */
+    startSessionCleanup() {
+        setInterval(() => {
+            const now = Date.now();
+            for (const [originator, timestamp] of this.sessionAuthorizations.entries()) {
+                if (now - timestamp > this.SESSION_TIMEOUT_MS) {
+                    this.sessionAuthorizations.delete(originator);
+                }
+            }
+            for (const [originator, tx] of this.authorizedTransactions.entries()) {
+                if (now - tx.timestamp > this.SESSION_TIMEOUT_MS) {
+                    this.authorizedTransactions.delete(originator);
+                }
+            }
+        }, 30000); // Every 30 seconds
+    }
+    /**
+     * Intercepts wallet method requests for P-basket/protocol operations.
+     *
+     * SECURITY: This is the main entry point for all permission checks.
+     * All token spending operations MUST go through this method.
+     *
+     * @param req - Request object containing method, args, and originator
+     * @returns Modified args (unchanged in this implementation)
+     * @throws Error if authorization is denied
+     */
+    async onRequest(req) {
+        const { method, args, originator } = req;
+        // Input validation
+        if (!method || typeof method !== 'string') {
+            throw new Error('Invalid method');
+        }
+        if (!originator || typeof originator !== 'string') {
+            throw new Error('Invalid originator');
+        }
+        if (!args || typeof args !== 'object') {
+            throw new Error('Invalid args');
+        }
+        // Handle security-critical methods
+        if (method === 'createAction') {
+            await this.handleCreateAction(args, originator);
+        }
+        else if (method === 'createSignature') {
+            await this.handleCreateSignature(args, originator);
+        }
+        else if (method === 'listActions') {
+            await this.handleListActions(args, originator);
+        }
+        else if (method === 'listOutputs') {
+            await this.handleListOutputs(args, originator);
+        }
+        return { args };
+    }
+    /**
+     * Transforms responses from the underlying wallet.
+     * For createAction: Captures signable transaction data for security verification.
+     */
+    async onResponse(res, context) {
+        const { method, originator } = context;
+        if (method === 'createAction') {
+            await this.captureAuthorizedTransaction(res, originator);
+        }
+        return res;
+    }
+    /**
+     * Captures authorized transaction data from createAction response.
+     *
+     * SECURITY: This data is used to verify that createSignature calls are signing
+     * the exact transaction the user approved. Prevents transaction substitution attacks.
+     *
+     * Captured data:
+     * 1. reference - Transaction reference for matching
+     * 2. hashOutputs - BIP-143 hash of all outputs (prevents output modification)
+     * 3. authorizedOutpoints - Whitelist of inputs that can be signed (prevents input substitution)
+     * 4. timestamp - For expiry checking
+     *
+     * @param result - createAction response
+     * @param originator - dApp identifier
+     */
+    async captureAuthorizedTransaction(result, originator) {
+        if (!result || typeof result !== 'object' || !result.signableTransaction) {
+            return;
+        }
+        try {
+            const { tx, reference } = result.signableTransaction;
+            if (!tx || !reference) {
+                return;
+            }
+            const transaction = Transaction.fromAtomicBEEF(tx);
+            // Compute hashOutputs (BIP-143 style) from the transaction outputs
+            const hashOutputs = this.computeHashOutputs(transaction);
+            // Collect all input outpoints as authorized
+            const authorizedOutpoints = new Set();
+            if (Array.isArray(transaction.inputs)) {
+                for (const input of transaction.inputs) {
+                    if (!input || typeof input !== 'object')
+                        continue;
+                    const txid = input.sourceTXID || input.sourceTransaction?.id('hex');
+                    if (txid && typeof txid === 'string') {
+                        const vout = input.sourceOutputIndex;
+                        if (typeof vout === 'number' && vout >= 0) {
+                            const outpoint = `${txid}.${vout}`;
+                            authorizedOutpoints.add(outpoint);
+                        }
+                    }
+                }
+            }
+            // Store the authorized transaction data
+            this.authorizedTransactions.set(originator, {
+                reference,
+                hashOutputs,
+                authorizedOutpoints,
+                timestamp: Date.now()
+            });
+        }
+        catch (error) {
+            // Don't throw - we'll fall back to session-based auth
+        }
+    }
+    /**
+     * Computes BIP-143 hashOutputs from a transaction.
+     *
+     * SECURITY: This hash commits to all transaction outputs. Any modification
+     * to outputs (amounts, recipients, scripts) will change this hash.
+     *
+     * @param tx - Transaction to compute hashOutputs for
+     * @returns Hex-encoded double-SHA256 hash of all outputs
+     */
+    computeHashOutputs(tx) {
+        if (!tx || typeof tx !== 'object' || !Array.isArray(tx.outputs)) {
+            throw new Error('Invalid transaction for hashOutputs computation');
+        }
+        // Serialize all outputs: satoshis (8 bytes LE) + scriptLen (varint) + script
+        const outputBytes = [];
+        for (const output of tx.outputs) {
+            // Satoshis as 8-byte little-endian
+            const satoshis = output.satoshis ?? 0;
+            for (let i = 0; i < 8; i++) {
+                outputBytes.push(Number((BigInt(satoshis) >> BigInt(i * 8)) & BigInt(0xff)));
+            }
+            // Script length as varint + script bytes
+            const scriptBytes = output.lockingScript?.toBinary() ?? [];
+            const scriptLen = scriptBytes.length;
+            if (scriptLen < 0xfd) {
+                outputBytes.push(scriptLen);
+            }
+            else if (scriptLen <= 0xffff) {
+                outputBytes.push(0xfd);
+                outputBytes.push(scriptLen & 0xff);
+                outputBytes.push((scriptLen >> 8) & 0xff);
+            }
+            else {
+                outputBytes.push(0xfe);
+                outputBytes.push(scriptLen & 0xff);
+                outputBytes.push((scriptLen >> 8) & 0xff);
+                outputBytes.push((scriptLen >> 16) & 0xff);
+                outputBytes.push((scriptLen >> 24) & 0xff);
+            }
+            outputBytes.push(...scriptBytes);
+        }
+        // Double SHA-256
+        const hash = Hash.hash256(outputBytes);
+        return Utils.toHex(hash);
+    }
+    /**
+     * Handles createAction requests that involve BTMS P-baskets.
+     *
+     * SECURITY: This is the primary authorization checkpoint. User approval here
+     * grants session authorization for subsequent createSignature calls.
+     *
+     * ISSUANCE DETECTION: Token issuance is auto-approved because it creates new
+     * tokens rather than spending existing ones. Detected by:
+     * - ISSUE_MARKER in locking script
+     * - btms_issue tag in outputs
+     * - No inputs (issuance doesn't spend existing UTXOs)
+     *
+     * @param args - createAction arguments
+     * @param originator - dApp identifier
+     * @throws Error if user denies authorization
+     */
+    async handleCreateAction(args, originator) {
+        // Input validation
+        if (!args || typeof args !== 'object') {
+            throw new Error('Invalid createAction args');
+        }
+        // Check if this is token issuance - auto-approve
+        const isIssuance = this.isTokenIssuance(args);
+        if (isIssuance) {
+            this.grantSessionAuthorization(originator);
+            return;
+        }
+        // No inputs = likely issuance (creating new tokens)
+        if (!args.inputs || args.inputs.length === 0) {
+            this.grantSessionAuthorization(originator);
+            return;
+        }
+        // Extract token spend information for user prompt
+        const spendInfo = this.extractTokenSpendInfo(args);
+        const enrichedSpendInfo = await this.enrichSpendInfoWithMetadata(spendInfo, spendInfo.assetId);
+        const actionClassification = this.classifyTokenAction(enrichedSpendInfo);
+        if (actionClassification.isInvalidBurn) {
+            throw new Error('Burn transactions must not send tokens to a recipient');
+        }
+        if (actionClassification.isBurn) {
+            await this.promptForTokenBurn(originator, {
+                ...enrichedSpendInfo,
+                sendAmount: 0,
+                totalInputAmount: actionClassification.burnAmount
+            });
+            return;
+        }
+        if (enrichedSpendInfo.sendAmount > 0 || enrichedSpendInfo.totalInputAmount > 0) {
+            await this.promptForTokenSpend(originator, enrichedSpendInfo);
+            return;
+        }
+        // Fallback to generic prompt if we can't parse token details
+        await this.promptForGenericAuthorization(originator);
+    }
+    async enrichSpendInfoWithMetadata(spendInfo, assetId) {
+        if (!assetId)
+            return spendInfo;
+        const meta = await this.getAssetMetadata(assetId);
+        return {
+            ...spendInfo,
+            assetId,
+            tokenName: meta?.name || spendInfo.tokenName,
+            iconURL: meta?.iconURL || spendInfo.iconURL
+        };
+    }
+    classifyTokenAction(spendInfo) {
+        const inputAmountReliable = spendInfo.inputAmountSource === 'beef';
+        const burnAmount = inputAmountReliable
+            ? Math.max(0, spendInfo.totalInputAmount - spendInfo.outputChangeAmount - spendInfo.outputSendAmount)
+            : 0;
+        const isInvalidBurn = burnAmount > 0 && spendInfo.outputSendAmount > 0;
+        const isBurn = inputAmountReliable && burnAmount > 0 && spendInfo.outputSendAmount === 0;
+        return {
+            burnAmount,
+            isBurn,
+            isInvalidBurn
+        };
+    }
+    /**
+     * Extracts comprehensive token spend information from createAction args.
+     *
+     * Parses ALL output locking scripts to get token data, and extracts
+     * recipient info from the action description.
+     */
+    extractTokenSpendInfo(args) {
+        let sendAmount = 0;
+        let changeAmount = 0;
+        let totalInputAmount = 0;
+        let outputSendAmount = 0;
+        let outputChangeAmount = 0;
+        let hasTokenOutputs = false;
+        let inputAmountSource = 'none';
+        let inputAssetId;
+        let outputAssetId;
+        let assetIdMismatch = false;
+        let tokenName = 'BTMS Token';
+        let assetId = '';
+        let iconURL;
+        let recipient;
+        // Input validation
+        if (!args || typeof args !== 'object') {
+            throw new Error('Invalid args for extractTokenSpendInfo');
+        }
+        // Parse inputs using inputBEEF to get total input amount (if available)
+        let beefInputAmount = 0;
+        if (args.inputBEEF && Array.isArray(args.inputs)) {
+            for (const input of args.inputs) {
+                if (!input?.outpoint || typeof input.outpoint !== 'string')
+                    continue;
+                const [txid, voutStr] = input.outpoint.split('.');
+                const outputIndex = Number(voutStr);
+                if (!txid || !Number.isFinite(outputIndex) || outputIndex < 0)
+                    continue;
+                try {
+                    const tx = Transaction.fromBEEF(args.inputBEEF, txid);
+                    const lockingScript = tx.outputs?.[outputIndex]?.lockingScript;
+                    const scriptHex = lockingScript?.toHex?.();
+                    if (!scriptHex)
+                        continue;
+                    const parsed = this.parseTokenLockingScript(scriptHex);
+                    if (!parsed || parsed.assetId === ISSUE_MARKER)
+                        continue;
+                    if (!inputAssetId) {
+                        inputAssetId = parsed.assetId;
+                    }
+                    else if (parsed.assetId !== inputAssetId) {
+                        assetIdMismatch = true;
+                        continue;
+                    }
+                    if (!assetId) {
+                        assetId = parsed.assetId;
+                    }
+                    else if (parsed.assetId !== assetId) {
+                        assetIdMismatch = true;
+                        continue;
+                    }
+                    beefInputAmount += parsed.amount;
+                    if (parsed.metadata?.name && typeof parsed.metadata.name === 'string') {
+                        tokenName = parsed.metadata.name;
+                    }
+                    if (parsed.metadata?.iconURL && typeof parsed.metadata.iconURL === 'string') {
+                        iconURL = parsed.metadata.iconURL;
+                    }
+                }
+                catch {
+                    // Ignore malformed input BEEF
+                }
+            }
+        }
+        if (beefInputAmount > 0) {
+            totalInputAmount = beefInputAmount;
+            inputAmountSource = 'beef';
+        }
+        // Parse ALL output locking scripts to extract token metadata
+        if (Array.isArray(args.outputs)) {
+            for (const output of args.outputs) {
+                if (output?.lockingScript && typeof output.lockingScript === 'string') {
+                    const parsed = this.parseTokenLockingScript(output.lockingScript);
+                    if (parsed) {
+                        if (parsed.assetId === ISSUE_MARKER) {
+                            continue;
+                        }
+                        // Get asset ID from first valid token
+                        if (!outputAssetId) {
+                            outputAssetId = parsed.assetId;
+                        }
+                        else if (parsed.assetId !== outputAssetId) {
+                            assetIdMismatch = true;
+                            continue;
+                        }
+                        if (!assetId) {
+                            assetId = parsed.assetId;
+                        }
+                        else if (parsed.assetId !== assetId) {
+                            assetIdMismatch = true;
+                            continue;
+                        }
+                        hasTokenOutputs = true;
+                        if (parsed.metadata?.name && typeof parsed.metadata.name === 'string') {
+                            tokenName = parsed.metadata.name;
+                        }
+                        if (parsed.metadata?.iconURL && typeof parsed.metadata.iconURL === 'string') {
+                            iconURL = parsed.metadata.iconURL;
+                        }
+                        // Determine if this is a change output or send output
+                        // Basket presence indicates change (returning to self)
+                        if (output.basket && typeof output.basket === 'string' && output.basket.startsWith(P_BASKET_PREFIX)) {
+                            outputChangeAmount += parsed.amount;
+                        }
+                        else {
+                            outputSendAmount += parsed.amount;
+                        }
+                    }
+                }
+            }
+        }
+        if (hasTokenOutputs) {
+            sendAmount = outputSendAmount;
+            changeAmount = outputChangeAmount;
+        }
+        if (assetIdMismatch || (inputAssetId && outputAssetId && inputAssetId !== outputAssetId)) {
+            throw new Error('Asset swap support coming soon');
+        }
+        // If we have token outputs, derive total input amount from them
+        if (sendAmount + changeAmount > 0 && totalInputAmount === 0) {
+            totalInputAmount = sendAmount + changeAmount;
+            inputAmountSource = 'derived';
+        }
+        // If we still couldn't determine send amount, try calculating from inputs
+        if (sendAmount === 0 && totalInputAmount > 0) {
+            sendAmount = totalInputAmount - changeAmount;
+        }
+        return {
+            sendAmount,
+            totalInputAmount,
+            changeAmount,
+            outputSendAmount,
+            outputChangeAmount,
+            hasTokenOutputs,
+            inputAmountSource,
+            tokenName,
+            assetId,
+            recipient,
+            iconURL,
+            actionDescription: args.description || 'Token transaction'
+        };
+    }
+    /**
+     * Prompts user for token spend authorization with detailed information.
+     *
+     * SECURITY: The prompt data is JSON-encoded to prevent injection attacks.
+     * The UI component (TokenAccessPrompt) is responsible for safely rendering this data.
+     *
+     * @param originator - dApp identifier
+     * @param spendInfo - Parsed token spend information
+     * @throws Error if user denies authorization
+     */
+    async promptForTokenSpend(originator, spendInfo) {
+        // Input validation
+        if (!originator || typeof originator !== 'string') {
+            throw new Error('Invalid originator');
+        }
+        if (!spendInfo || typeof spendInfo !== 'object') {
+            throw new Error('Invalid spendInfo');
+        }
+        // Build structured prompt data (JSON-encoded for safety)
+        const promptData = {
+            type: 'btms_spend',
+            sendAmount: spendInfo.sendAmount,
+            tokenName: spendInfo.tokenName,
+            assetId: spendInfo.assetId,
+            recipient: spendInfo.recipient,
+            iconURL: spendInfo.iconURL,
+            changeAmount: spendInfo.changeAmount,
+            totalInputAmount: spendInfo.totalInputAmount
+        };
+        const message = JSON.stringify(promptData);
+        const approved = await this.requestTokenAccess(originator, message);
+        if (!approved) {
+            throw new Error('User denied permission to spend tokens');
+        }
+        this.grantSessionAuthorization(originator);
+    }
+    /**
+     * Prompts user for token burn authorization (burns all inputs with no token outputs).
+     */
+    async promptForTokenBurn(originator, spendInfo) {
+        // Input validation
+        if (!originator || typeof originator !== 'string') {
+            throw new Error('Invalid originator');
+        }
+        if (!spendInfo || typeof spendInfo !== 'object') {
+            throw new Error('Invalid spendInfo');
+        }
+        const promptData = {
+            type: 'btms_burn',
+            burnAmount: spendInfo.totalInputAmount,
+            tokenName: spendInfo.tokenName,
+            assetId: spendInfo.assetId,
+            iconURL: spendInfo.iconURL,
+            burnAll: spendInfo.changeAmount === 0
+        };
+        const message = JSON.stringify(promptData);
+        const approved = await this.requestTokenAccess(originator, message);
+        if (!approved) {
+            throw new Error('User denied permission to burn tokens');
+        }
+        this.grantSessionAuthorization(originator);
+    }
+    /**
+     * Prompts user for generic authorization when token details cannot be parsed.
+     *
+     * SECURITY: Fallback prompt when we can't extract detailed token information.
+     * Still requires explicit user approval.
+     *
+     * @param originator - dApp identifier
+     * @throws Error if user denies authorization
+     */
+    async promptForGenericAuthorization(originator) {
+        if (!originator || typeof originator !== 'string') {
+            throw new Error('Invalid originator');
+        }
+        const message = `Spend BTMS tokens\n\nApp: ${originator}`;
+        const approved = await this.requestTokenAccess(originator, message);
+        if (!approved) {
+            throw new Error('User denied permission to spend BTMS tokens');
+        }
+        this.grantSessionAuthorization(originator);
+    }
+    /**
+     * Handles createSignature requests for BTMS token spending.
+     *
+     * SECURITY: This is the second checkpoint. It verifies that:
+     * 1. Session authorization exists (granted by createAction approval)
+     * 2. The preimage matches the authorized transaction (prevents transaction substitution)
+     *
+     * ISSUANCE HANDLING:
+     * Token issuance is auto-approved via multiple detection methods:
+     * - Session auth from createAction (if ISSUE_MARKER or btms_issue tag detected)
+     * - Preimage parsing (checks for ISSUE_MARKER in scriptCode)
+     * - Short signatures (<157 bytes, not full BIP-143 preimages)
+     *
+     * @param args - createSignature arguments
+     * @param originator - dApp identifier
+     * @throws Error if authorization is denied or verification fails
+     */
+    async handleCreateSignature(args, originator) {
+        // Input validation
+        if (!args || typeof args !== 'object') {
+            throw new Error('Invalid createSignature args');
+        }
+        if (!originator || typeof originator !== 'string') {
+            throw new Error('Invalid originator');
+        }
+        // Check if we have session authorization from createAction
+        if (this.hasSessionAuthorization(originator)) {
+            // Session auth exists - proceed to verification
+        }
+        else {
+            // No session auth - check if this is token issuance
+            // Method 1: Parse BIP-143 preimage for ISSUE_MARKER
+            if (args.data && args.data.length >= 157) {
+                if (this.isIssuanceFromPreimage(args.data)) {
+                    this.grantSessionAuthorization(originator);
+                    return;
+                }
+            }
+            // Method 2: Short signatures (not full BIP-143 preimages) are assumed to be issuance
+            // This handles PushDrop signatures that don't include full transaction context
+            if (args.data && args.data.length > 0 && args.data.length < 157) {
+                this.grantSessionAuthorization(originator);
+                return;
+            }
+            // No authorization and not issuance - require user approval
+            await this.promptForGenericAuthorization(originator);
+        }
+        // Verify the signature request matches the authorized transaction
+        const authorizedTx = this.authorizedTransactions.get(originator);
+        if (!authorizedTx) {
+            // No transaction data captured - allow based on session auth alone
+            return;
+        }
+        // Check if authorization has expired
+        const elapsed = Date.now() - authorizedTx.timestamp;
+        if (elapsed > this.SESSION_TIMEOUT_MS) {
+            this.sessionAuthorizations.delete(originator);
+            this.authorizedTransactions.delete(originator);
+            throw new Error('Transaction authorization has expired. Please try again.');
+        }
+        // Verify the preimage matches the authorized transaction
+        if (args.data && args.data.length >= 157) {
+            this.verifyPreimage(args.data, authorizedTx, originator);
+        }
+    }
+    /**
+     * Verifies that a BIP-143 preimage matches the authorized transaction.
+     *
+     * SECURITY: This prevents a malicious dApp from:
+     * 1. Getting approval for one transaction
+     * 2. Signing a different transaction with different outputs or inputs
+     *
+     * BIP-143 preimage structure:
+     * - Version: 4 bytes
+     * - hashPrevouts: 32 bytes
+     * - hashSequence: 32 bytes
+     * - Outpoint (txid + vout): 36 bytes
+     * - scriptCode: variable (varint length + script)
+     * - Value: 8 bytes
+     * - Sequence: 4 bytes
+     * - hashOutputs: 32 bytes
+     * - Locktime: 4 bytes
+     * - Sighash type: 4 bytes
+     *
+     * Verification checks:
+     * 1. Outpoint being signed is in our authorized list
+     * 2. hashOutputs matches what we computed from createAction
+     *
+     * @param data - BIP-143 preimage bytes
+     * @param authorizedTx - Authorized transaction data from createAction
+     * @param _originator - dApp identifier (unused, for future logging)
+     * @throws Error if verification fails
+     */
+    verifyPreimage(data, authorizedTx, _originator) {
+        // Input validation
+        if (!Array.isArray(data) || data.length < 157) {
+            // Too short to be a valid BIP-143 preimage - skip verification
+            return;
+        }
+        if (!authorizedTx || typeof authorizedTx !== 'object') {
+            throw new Error('Invalid authorized transaction data');
+        }
+        try {
+            // Extract outpoint (bytes 68-103: 32-byte txid reversed + 4-byte vout)
+            const outpointStart = 4 + 32 + 32; // After version, hashPrevouts, hashSequence
+            if (data.length < outpointStart + 36) {
+                throw new Error('Preimage too short to extract outpoint');
+            }
+            const txidBytes = data.slice(outpointStart, outpointStart + 32);
+            // Reverse the txid bytes (Bitcoin uses little-endian)
+            const txid = Utils.toHex(txidBytes.reverse());
+            const voutBytes = data.slice(outpointStart + 32, outpointStart + 36);
+            const vout = voutBytes[0] | (voutBytes[1] << 8) | (voutBytes[2] << 16) | (voutBytes[3] << 24);
+            const outpoint = `${txid}.${vout}`;
+            // SECURITY: Verify the outpoint is in our authorized list
+            if (!authorizedTx.authorizedOutpoints.has(outpoint)) {
+                throw new Error(`Unauthorized outpoint: ${outpoint}. This transaction was not approved.`);
+            }
+            // Parse scriptCode length to find hashOutputs position
+            const scriptCodeLenStart = outpointStart + 36;
+            if (data.length < scriptCodeLenStart + 1) {
+                throw new Error('Preimage too short to parse scriptCode length');
+            }
+            let scriptCodeLen;
+            let scriptCodeDataStart;
+            const firstByte = data[scriptCodeLenStart];
+            if (firstByte < 0xfd) {
+                scriptCodeLen = firstByte;
+                scriptCodeDataStart = scriptCodeLenStart + 1;
+            }
+            else if (firstByte === 0xfd) {
+                if (data.length < scriptCodeLenStart + 3) {
+                    throw new Error('Preimage too short for varint');
+                }
+                scriptCodeLen = data[scriptCodeLenStart + 1] | (data[scriptCodeLenStart + 2] << 8);
+                scriptCodeDataStart = scriptCodeLenStart + 3;
+            }
+            else if (firstByte === 0xfe) {
+                if (data.length < scriptCodeLenStart + 5) {
+                    throw new Error('Preimage too short for varint');
+                }
+                scriptCodeLen = data[scriptCodeLenStart + 1] | (data[scriptCodeLenStart + 2] << 8) |
+                    (data[scriptCodeLenStart + 3] << 16) | (data[scriptCodeLenStart + 4] << 24);
+                scriptCodeDataStart = scriptCodeLenStart + 5;
+            }
+            else {
+                // 0xff varint not expected for script lengths
+                return;
+            }
+            // Validate scriptCode length is reasonable (prevent DoS)
+            if (scriptCodeLen < 0 || scriptCodeLen > 10000) {
+                throw new Error('Invalid scriptCode length in preimage');
+            }
+            // hashOutputs starts after scriptCode + value(8) + sequence(4)
+            const hashOutputsStart = scriptCodeDataStart + scriptCodeLen + 8 + 4;
+            if (hashOutputsStart + 32 > data.length) {
+                throw new Error('Preimage too short to extract hashOutputs');
+            }
+            const hashOutputsBytes = data.slice(hashOutputsStart, hashOutputsStart + 32);
+            const preimageHashOutputs = Utils.toHex(hashOutputsBytes);
+            // SECURITY: Verify hashOutputs matches what user approved
+            if (preimageHashOutputs !== authorizedTx.hashOutputs) {
+                throw new Error('Transaction outputs do not match approved transaction. Possible attack detected.');
+            }
+        }
+        catch (error) {
+            // Re-throw security-critical errors
+            if (error instanceof Error &&
+                (error.message.includes('Unauthorized') ||
+                    error.message.includes('do not match') ||
+                    error.message.includes('attack'))) {
+                throw error;
+            }
+            // For parsing errors, fall back to session auth (don't block legitimate transactions)
+        }
+    }
+    /**
+     * Grants session authorization for an originator.
+     *
+     * SECURITY: Session authorization is time-limited (60s) to prevent replay attacks.
+     * After expiry, user must re-approve the transaction.
+     *
+     * @param originator - dApp identifier
+     */
+    grantSessionAuthorization(originator) {
+        if (!originator || typeof originator !== 'string') {
+            throw new Error('Invalid originator for session authorization');
+        }
+        this.sessionAuthorizations.set(originator, Date.now());
+    }
+    /**
+     * Checks if an originator has valid session authorization.
+     *
+     * SECURITY: Automatically expires and removes stale authorizations.
+     *
+     * @param originator - dApp identifier
+     * @returns true if valid session authorization exists
+     */
+    hasSessionAuthorization(originator) {
+        if (!originator || typeof originator !== 'string') {
+            return false;
+        }
+        const timestamp = this.sessionAuthorizations.get(originator);
+        if (!timestamp || typeof timestamp !== 'number') {
+            return false;
+        }
+        const elapsed = Date.now() - timestamp;
+        if (elapsed > this.SESSION_TIMEOUT_MS) {
+            // Auto-cleanup expired authorization
+            this.sessionAuthorizations.delete(originator);
+            this.authorizedTransactions.delete(originator);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Checks if a signature request is for token issuance by examining the BIP-143 preimage.
+     *
+     * ISSUANCE DETECTION: Parses the scriptCode from the preimage and checks for ISSUE_MARKER.
+     * This is needed because during issuance, createAction doesn't have P-basket outputs
+     * (basket is added later via internalizeAction), so handleCreateAction isn't triggered.
+     *
+     * @param preimage - BIP-143 preimage data
+     * @returns true if this is a token issuance signature
+     */
+    isIssuanceFromPreimage(preimage) {
+        if (!Array.isArray(preimage) || preimage.length < 157) {
+            return false;
+        }
+        try {
+            // Skip to scriptCode position
+            let offset = 4 + 32 + 32 + 36; // version + hashPrevouts + hashSequence + outpoint
+            if (offset >= preimage.length) {
+                return false;
+            }
+            // Parse varint scriptCode length
+            const firstByte = preimage[offset];
+            let scriptLength;
+            if (firstByte < 0xfd) {
+                scriptLength = firstByte;
+                offset += 1;
+            }
+            else if (firstByte === 0xfd) {
+                if (offset + 3 > preimage.length)
+                    return false;
+                scriptLength = preimage[offset + 1] | (preimage[offset + 2] << 8);
+                offset += 3;
+            }
+            else if (firstByte === 0xfe) {
+                if (offset + 5 > preimage.length)
+                    return false;
+                scriptLength = preimage[offset + 1] | (preimage[offset + 2] << 8) |
+                    (preimage[offset + 3] << 16) | (preimage[offset + 4] << 24);
+                offset += 5;
+            }
+            else {
+                return false; // 0xff not expected
+            }
+            // Validate scriptLength
+            if (scriptLength < 0 || scriptLength > 10000 || offset + scriptLength > preimage.length) {
+                return false;
+            }
+            // Extract and decode scriptCode
+            const scriptBytes = preimage.slice(offset, offset + scriptLength);
+            const lockingScript = LockingScript.fromBinary(scriptBytes);
+            const decoded = PushDrop.decode(lockingScript);
+            // Check for ISSUE_MARKER in first field
+            if (decoded.fields.length >= 1) {
+                const assetId = Utils.toUTF8(decoded.fields[BTMS_FIELD.ASSET_ID]);
+                return assetId === ISSUE_MARKER;
+            }
+        }
+        catch (e) {
+            // Not a valid PushDrop script or parsing failed
+            return false;
+        }
+        return false;
+    }
+    /**
+     * Handles listActions requests that query BTMS token labels.
+     *
+     * Prompts the user when an app tries to list token transactions.
+     * This provides transparency about which apps are accessing token history.
+     *
+     * @param args - listActions arguments
+     * @param originator - dApp identifier
+     * @throws Error if user denies authorization
+     */
+    async handleListActions(args, originator) {
+        // Extract asset ID from labels if present
+        let assetId;
+        if (args.labels && Array.isArray(args.labels)) {
+            for (const label of args.labels) {
+                if (typeof label === 'string') {
+                    // Parse p-label format: "p btms assetId <assetId>"
+                    const match = label.match(/^p btms assetId (.+)$/);
+                    if (match && match[1]) {
+                        assetId = match[1];
+                        break;
+                    }
+                }
+            }
+        }
+        await this.promptForBTMSAccess(originator, assetId);
+    }
+    /**
+     * Handles listOutputs requests that query BTMS token baskets.
+     *
+     * Prompts the user when an app tries to list token balances/UTXOs.
+     * This provides transparency about which apps are accessing token data.
+     *
+     * @param args - listOutputs arguments
+     * @param originator - dApp identifier
+     * @throws Error if user denies authorization
+     */
+    async handleListOutputs(args, originator) {
+        // Extract asset ID from basket if present
+        let assetId;
+        if (args.basket && typeof args.basket === 'string') {
+            // Parse p-basket format: "p btms" or with asset ID
+            const match = args.basket.match(/^p btms(?:\s+(.+))?$/);
+            if (match && match[1]) {
+                assetId = match[1];
+            }
+        }
+        await this.promptForBTMSAccess(originator, assetId);
+    }
+    /**
+     * Prompts user once per session for BTMS token access (listActions/listOutputs).
+     */
+    async promptForBTMSAccess(originator, assetId) {
+        if (this.hasSessionAuthorization(originator))
+            return;
+        const promptData = {
+            type: 'btms_access',
+            action: 'access BTMS tokens',
+            assetId
+        };
+        const message = JSON.stringify(promptData);
+        const approved = await this.requestTokenAccess(originator, message);
+        if (!approved) {
+            throw new Error('User denied permission to access BTMS tokens');
+        }
+        this.grantSessionAuthorization(originator);
+    }
+    /**
+     * Fetches metadata for a specific asset using btms.getAssetInfo.
+     *
+     * @param assetId - The asset ID to look up
+     * @returns Token metadata or null if not found
+     */
+    async getAssetMetadata(assetId) {
+        try {
+            const info = await this.btms.getAssetInfo(assetId);
+            if (info) {
+                return {
+                    name: info.name,
+                    iconURL: info.metadata?.iconURL
+                };
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return null;
+    }
+    /**
+     * Checks if the createAction is for token issuance.
+     *
+     * ISSUANCE DETECTION: Token issuance is detected by:
+     * 1. Output tags containing 'btms_type_issue'
+     * 2. Locking script contains ISSUE_MARKER in assetId field
+     *
+     * @param args - createAction arguments
+     * @returns true if this is a token issuance operation
+     */
+    isTokenIssuance(args) {
+        if (!args || !Array.isArray(args.outputs)) {
+            return false;
+        }
+        for (const output of args.outputs) {
+            if (!output || typeof output !== 'object') {
+                continue;
+            }
+            // Check for btms_type_issue tag
+            if (Array.isArray(output.tags) && output.tags.includes('btms_type_issue')) {
+                return true;
+            }
+            // Check locking script for ISSUE_MARKER
+            if (output.lockingScript && typeof output.lockingScript === 'string') {
+                try {
+                    const lockingScript = LockingScript.fromHex(output.lockingScript);
+                    const decoded = PushDrop.decode(lockingScript);
+                    if (decoded.fields.length >= 1) {
+                        const assetId = Utils.toUTF8(decoded.fields[BTMS_FIELD.ASSET_ID]);
+                        if (assetId === ISSUE_MARKER) {
+                            return true;
+                        }
+                    }
+                }
+                catch (e) {
+                    // Not a valid PushDrop script, continue checking
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Parses a BTMS token locking script to extract token information.
+     *
+     * BTMS TOKEN STRUCTURE:
+     * - Field 0: assetId (or "ISSUE" for issuance)
+     * - Field 1: amount (as string)
+     * - Field 2: metadata (optional JSON string)
+     * - Field 3: signature (present in signed PushDrop scripts)
+     *
+     * @param lockingScriptHex - Hex-encoded locking script
+     * @returns Parsed token info or null if parsing fails
+     */
+    parseTokenLockingScript(lockingScriptHex) {
+        if (!lockingScriptHex || typeof lockingScriptHex !== 'string') {
+            return null;
+        }
+        try {
+            const lockingScript = LockingScript.fromHex(lockingScriptHex);
+            const decoded = PushDrop.decode(lockingScript);
+            // BTMS tokens have 2-4 fields depending on metadata and signature presence
+            if (decoded.fields.length < 2 || decoded.fields.length > 4) {
+                return null;
+            }
+            // Extract assetId and amount
+            const assetId = Utils.toUTF8(decoded.fields[BTMS_FIELD.ASSET_ID]);
+            const amountStr = Utils.toUTF8(decoded.fields[BTMS_FIELD.AMOUNT]);
+            const amount = Number(amountStr);
+            // Validate amount
+            if (isNaN(amount) || amount <= 0 || !Number.isFinite(amount)) {
+                return null;
+            }
+            // Validate assetId
+            if (!assetId || typeof assetId !== 'string') {
+                return null;
+            }
+            // Try to parse metadata from field 2 if it exists
+            let metadata;
+            if (decoded.fields.length >= 3) {
+                try {
+                    const potentialMetadata = Utils.toUTF8(decoded.fields[BTMS_FIELD.METADATA]);
+                    // Only parse if it looks like JSON (starts with {)
+                    if (potentialMetadata && typeof potentialMetadata === 'string' && potentialMetadata.startsWith('{')) {
+                        const parsed = JSON.parse(potentialMetadata);
+                        // Validate metadata is an object
+                        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                            metadata = parsed;
+                        }
+                    }
+                }
+                catch (e) {
+                    // Field 2 might be a signature, not metadata - that's fine
+                }
+            }
+            return { assetId, amount, metadata };
+        }
+        catch (e) {
+            // Parsing failed - not a valid BTMS token
+            return null;
+        }
+    }
+}