@bsv/btms-permission-module 1.0.0

package/dist/BasicTokenModule.d.ts

@@ -0,0 +1,307 @@
+import { PermissionsModule } from '@bsv/wallet-toolbox-client';
+import { BTMS } from '@bsv/btms';
+/**
+ * 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 declare class BasicTokenModule implements PermissionsModule {
+    private readonly requestTokenAccess;
+    private readonly 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)
+     */
+    private sessionAuthorizations;
+    private readonly SESSION_TIMEOUT_MS;
+    /**
+     * 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)
+     */
+    private authorizedTransactions;
+    /**
+     * 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: (app: string, message: string) => Promise<boolean>, btms: BTMS);
+    /**
+     * Periodic cleanup of expired session authorizations.
+     * Runs every 30 seconds to prevent memory leaks.
+     */
+    private startSessionCleanup;
+    /**
+     * 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
+     */
+    onRequest(req: {
+        method: string;
+        args: object;
+        originator: string;
+    }): Promise<{
+        args: object;
+    }>;
+    /**
+     * Transforms responses from the underlying wallet.
+     * For createAction: Captures signable transaction data for security verification.
+     */
+    onResponse(res: unknown, context: {
+        method: string;
+        originator: string;
+    }): Promise<unknown>;
+    /**
+     * 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
+     */
+    private captureAuthorizedTransaction;
+    /**
+     * 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
+     */
+    private computeHashOutputs;
+    /**
+     * 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
+     */
+    private handleCreateAction;
+    private enrichSpendInfoWithMetadata;
+    private classifyTokenAction;
+    /**
+     * 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.
+     */
+    private extractTokenSpendInfo;
+    /**
+     * 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
+     */
+    private promptForTokenSpend;
+    /**
+     * Prompts user for token burn authorization (burns all inputs with no token outputs).
+     */
+    private promptForTokenBurn;
+    /**
+     * 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
+     */
+    private promptForGenericAuthorization;
+    /**
+     * 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
+     */
+    private handleCreateSignature;
+    /**
+     * 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
+     */
+    private verifyPreimage;
+    /**
+     * 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
+     */
+    private grantSessionAuthorization;
+    /**
+     * 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
+     */
+    private hasSessionAuthorization;
+    /**
+     * 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
+     */
+    private isIssuanceFromPreimage;
+    /**
+     * 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
+     */
+    private handleListActions;
+    /**
+     * 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
+     */
+    private handleListOutputs;
+    /**
+     * Prompts user once per session for BTMS token access (listActions/listOutputs).
+     */
+    private promptForBTMSAccess;
+    /**
+     * 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
+     */
+    private getAssetMetadata;
+    /**
+     * 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
+     */
+    private isTokenIssuance;
+    /**
+     * 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
+     */
+    private parseTokenLockingScript;
+}
+//# sourceMappingURL=BasicTokenModule.d.ts.map

package/dist/BasicTokenModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicTokenModule.d.ts","sourceRoot":"","sources":["../src/BasicTokenModule.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,IAAI,EAAgB,MAAM,WAAW,CAAA;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoD;IACvF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAM;IAE3B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB,CAAiC;IAC9D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAE3C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,sBAAsB,CAAgD;IAE9E;;;;;;;OAOG;gBAED,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EACtE,IAAI,EAAE,IAAI;IAYZ;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;;;;;;;;OASG;IACG,SAAS,CAAC,GAAG,EAAE;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,UAAU,EAAE,MAAM,CAAA;KACnB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IA4B7B;;;OAGG;IACG,UAAU,CACd,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,GACA,OAAO,CAAC,OAAO,CAAC;IAUnB;;;;;;;;;;;;;;OAcG;YACW,4BAA4B;IAiD1C;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAsC1B;;;;;;;;;;;;;;;OAeG;YACW,kBAAkB;YA8ClB,2BAA2B;IAezC,OAAO,CAAC,mBAAmB;IAsB3B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAwJ7B;;;;;;;;;OASG;YACW,mBAAmB;IA+BjC;;OAEG;YACW,kBAAkB;IA4BhC;;;;;;;;OAQG;YACW,6BAA6B;IAe3C;;;;;;;;;;;;;;;;OAgBG;YACW,qBAAqB;IAuDnC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,cAAc;IA6FtB;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;IAOjC;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAsB/B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAwD9B;;;;;;;;;OASG;YACW,iBAAiB;IAoB/B;;;;;;;;;OASG;YACW,iBAAiB;IAe/B;;OAEG;YACW,mBAAmB;IAmBjC;;;;;OAKG;YACW,gBAAgB;IAe9B;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IAoCvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;CAsDhC"}