@bsv/btms-permission-module 1.0.0

package/dist/TokenUsagePrompt.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+interface TokenUsagePromptProps {
+    app: string;
+    message: string;
+    onAllow: () => void;
+    onDeny: () => void;
+}
+/**
+ * Modal dialog for prompting user to approve BTMS token spending.
+ * Displays comprehensive token information in an elegant, user-friendly format.
+ */
+declare const TokenUsagePromptDialog: React.FC<TokenUsagePromptProps>;
+/**
+ * Focus handlers for window management (optional)
+ */
+export interface FocusHandlers {
+    isFocused: () => Promise<boolean>;
+    onFocusRequested: () => Promise<void>;
+    onFocusRelinquished: () => Promise<void>;
+}
+/**
+ * Hook for managing BTMS token usage prompts.
+ * Returns a function that can be called to prompt the user and a component to render.
+ *
+ * @param focusHandlers - Optional focus management handlers for desktop apps
+ */
+export declare const useTokenUsagePrompt: (focusHandlers?: FocusHandlers) => {
+    promptUser: (app: string, message: string) => Promise<boolean>;
+    PromptComponent: () => import("react/jsx-runtime").JSX.Element | null;
+};
+export default TokenUsagePromptDialog;
+//# sourceMappingURL=TokenUsagePrompt.d.ts.map

package/dist/TokenUsagePrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenUsagePrompt.d.ts","sourceRoot":"","sources":["../src/TokenUsagePrompt.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAiD,MAAM,OAAO,CAAA;AAmBrE,UAAU,qBAAqB;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB;AAkED;;;GAGG;AACH,QAAA,MAAM,sBAAsB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA4O3D,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACjC,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,mBAAmB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACzC;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,gBAAgB,aAAa;sBASpB,MAAM,WAAW,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;;CAsDtF,CAAA;AAED,eAAe,sBAAsB,CAAA"}

package/dist/TokenUsagePrompt.js

@@ -0,0 +1,181 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useCallback, useMemo, useRef } from 'react';
+import { Dialog, DialogContent, DialogActions, Button, Typography, Box, Stack, Divider, Avatar, Chip } from '@mui/material';
+import TokenIcon from '@mui/icons-material/Token';
+import AppsIcon from '@mui/icons-material/Apps';
+import SendIcon from '@mui/icons-material/Send';
+import PersonIcon from '@mui/icons-material/Person';
+import SwapHorizIcon from '@mui/icons-material/SwapHoriz';
+/**
+ * Parses the BTMS token message to extract structured information.
+ * Now supports JSON-encoded spend info from BasicTokenModule.
+ */
+const parseTokenMessage = (message) => {
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed.type === 'btms_spend') {
+            return parsed;
+        }
+    }
+    catch {
+        // Not JSON, fall back to legacy parsing
+    }
+    // Legacy format: "Spend {amount} {tokenName} token(s)\n\nAsset ID: {assetId}\nApp: {app}"
+    const lines = message.split('\n');
+    const firstLine = lines[0] || '';
+    const spendMatch = firstLine.match(/Spend (\d+) (.+?) token/);
+    const amount = spendMatch?.[1] ? parseInt(spendMatch[1], 10) : 0;
+    const tokenName = spendMatch?.[2] || 'Unknown Token';
+    const assetIdMatch = message.match(/Asset ID: (.+?)(?:\n|$)/);
+    const assetId = assetIdMatch?.[1] || '';
+    return {
+        type: 'btms_spend',
+        sendAmount: amount,
+        tokenName,
+        assetId,
+        changeAmount: 0,
+        totalInputAmount: amount
+    };
+};
+/**
+ * Formats a number with locale-aware separators
+ */
+const formatAmount = (amount) => {
+    return amount.toLocaleString();
+};
+/**
+ * Truncates a hex string (like identity key or asset ID) for display
+ */
+const truncateHex = (hex, startChars = 8, endChars = 6) => {
+    if (hex.length <= startChars + endChars + 3)
+        return hex;
+    return `${hex.slice(0, startChars)}...${hex.slice(-endChars)}`;
+};
+/**
+ * Modal dialog for prompting user to approve BTMS token spending.
+ * Displays comprehensive token information in an elegant, user-friendly format.
+ */
+const TokenUsagePromptDialog = ({ app, message, onAllow, onDeny }) => {
+    const spendInfo = useMemo(() => parseTokenMessage(message), [message]);
+    if (!spendInfo) {
+        return null;
+    }
+    const hasRecipient = spendInfo.recipient && spendInfo.recipient.length > 0;
+    const hasChange = spendInfo.changeAmount > 0;
+    const hasAssetId = spendInfo.assetId && spendInfo.assetId.length > 0;
+    return (_jsxs(Dialog, { open: true, onClose: onDeny, maxWidth: "sm", fullWidth: true, PaperProps: {
+            sx: {
+                borderRadius: 3,
+                overflow: 'hidden'
+            }
+        }, children: [_jsx(Box, { sx: {
+                    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+                    p: 3,
+                    color: 'white'
+                }, children: _jsxs(Box, { display: "flex", alignItems: "center", gap: 1.5, children: [_jsx(Avatar, { sx: { bgcolor: 'rgba(255,255,255,0.2)', width: 48, height: 48 }, children: _jsx(TokenIcon, { sx: { fontSize: 28 } }) }), _jsxs(Box, { children: [_jsx(Typography, { variant: "h6", fontWeight: "bold", children: "Token Transfer Request" }), _jsx(Typography, { variant: "body2", sx: { opacity: 0.9 }, children: "Review and approve this transaction" })] })] }) }), _jsx(DialogContent, { sx: { p: 3 }, children: _jsxs(Stack, { spacing: 3, children: [_jsxs(Box, { sx: {
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: 1.5,
+                                p: 2,
+                                backgroundColor: 'grey.50',
+                                borderRadius: 2
+                            }, children: [_jsx(AppsIcon, { color: "action" }), _jsxs(Box, { children: [_jsx(Typography, { variant: "caption", color: "text.secondary", display: "block", children: "Requesting App" }), _jsx(Typography, { variant: "body1", fontWeight: "medium", children: app })] })] }), _jsxs(Box, { sx: {
+                                textAlign: 'center',
+                                p: 4,
+                                background: 'linear-gradient(135deg, rgba(102, 126, 234, 0.08) 0%, rgba(118, 75, 162, 0.08) 100%)',
+                                borderRadius: 3,
+                                border: '2px solid',
+                                borderColor: 'primary.light'
+                            }, children: [spendInfo.iconURL && (_jsx(Avatar, { src: spendInfo.iconURL, sx: { width: 64, height: 64, mx: 'auto', mb: 2 }, children: _jsx(TokenIcon, { sx: { fontSize: 32 } }) })), _jsx(Typography, { variant: "h3", fontWeight: "bold", color: "primary.main", gutterBottom: true, children: formatAmount(spendInfo.sendAmount) }), _jsx(Typography, { variant: "h5", color: "text.primary", fontWeight: "medium", children: spendInfo.tokenName }), hasAssetId && (_jsx(Chip, { label: truncateHex(spendInfo.assetId, 12, 8), size: "small", variant: "outlined", sx: { mt: 1.5, fontFamily: 'monospace', fontSize: '0.75rem' } }))] }), _jsxs(Box, { sx: {
+                                backgroundColor: 'grey.50',
+                                borderRadius: 2,
+                                overflow: 'hidden'
+                            }, children: [hasRecipient && (_jsxs(Box, { sx: {
+                                        display: 'flex',
+                                        alignItems: 'center',
+                                        gap: 2,
+                                        p: 2,
+                                        borderBottom: '1px solid',
+                                        borderColor: 'divider'
+                                    }, children: [_jsx(Avatar, { sx: { bgcolor: 'success.light', width: 36, height: 36 }, children: _jsx(PersonIcon, { sx: { fontSize: 20, color: 'success.dark' } }) }), _jsxs(Box, { sx: { flex: 1, minWidth: 0 }, children: [_jsx(Typography, { variant: "caption", color: "text.secondary", display: "block", children: "Recipient" }), _jsxs(Typography, { variant: "body2", fontFamily: "monospace", sx: {
+                                                        overflow: 'hidden',
+                                                        textOverflow: 'ellipsis',
+                                                        whiteSpace: 'nowrap'
+                                                    }, children: [spendInfo.recipient, "..."] })] }), _jsx(SendIcon, { color: "action", sx: { fontSize: 20 } })] })), hasChange && (_jsxs(Box, { sx: {
+                                        display: 'flex',
+                                        alignItems: 'center',
+                                        gap: 2,
+                                        p: 2
+                                    }, children: [_jsx(Avatar, { sx: { bgcolor: 'info.light', width: 36, height: 36 }, children: _jsx(SwapHorizIcon, { sx: { fontSize: 20, color: 'info.dark' } }) }), _jsxs(Box, { sx: { flex: 1 }, children: [_jsx(Typography, { variant: "caption", color: "text.secondary", display: "block", children: "Change (returned to you)" }), _jsxs(Typography, { variant: "body2", fontWeight: "medium", children: [formatAmount(spendInfo.changeAmount), " ", spendInfo.tokenName] })] })] })), spendInfo.totalInputAmount > spendInfo.sendAmount && (_jsx(Box, { sx: {
+                                        p: 2,
+                                        backgroundColor: 'grey.100',
+                                        borderTop: '1px solid',
+                                        borderColor: 'divider'
+                                    }, children: _jsxs(Box, { display: "flex", justifyContent: "space-between", alignItems: "center", children: [_jsx(Typography, { variant: "body2", color: "text.secondary", children: "Total from wallet" }), _jsxs(Typography, { variant: "body2", fontWeight: "medium", children: [formatAmount(spendInfo.totalInputAmount), " tokens"] })] }) }))] }), _jsx(Box, { sx: {
+                                p: 2,
+                                backgroundColor: 'warning.lighter',
+                                borderRadius: 2,
+                                border: '1px solid',
+                                borderColor: 'warning.light'
+                            }, children: _jsxs(Typography, { variant: "body2", color: "warning.dark", children: [_jsx("strong", { children: "Review carefully:" }), " This action will transfer tokens from your wallet. Only approve if you trust this application."] }) })] }) }), _jsx(Divider, {}), _jsxs(DialogActions, { sx: { p: 2.5, gap: 1.5 }, children: [_jsx(Button, { onClick: onDeny, color: "inherit", variant: "outlined", size: "large", fullWidth: true, sx: { borderRadius: 2, py: 1.5 }, children: "Deny" }), _jsx(Button, { onClick: onAllow, color: "primary", variant: "contained", size: "large", autoFocus: true, fullWidth: true, sx: {
+                            borderRadius: 2,
+                            py: 1.5,
+                            background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+                            '&:hover': {
+                                background: 'linear-gradient(135deg, #5a6fd6 0%, #6a4190 100%)'
+                            }
+                        }, children: "Approve Transfer" })] })] }));
+};
+/**
+ * Hook for managing BTMS token usage prompts.
+ * Returns a function that can be called to prompt the user and a component to render.
+ *
+ * @param focusHandlers - Optional focus management handlers for desktop apps
+ */
+export const useTokenUsagePrompt = (focusHandlers) => {
+    const wasOriginallyFocusedRef = useRef(false);
+    const [promptState, setPromptState] = useState(null);
+    const promptUser = useCallback(async (app, message) => {
+        // Request focus before showing the prompt (if handlers provided)
+        if (focusHandlers) {
+            const currentlyFocused = await focusHandlers.isFocused();
+            wasOriginallyFocusedRef.current = currentlyFocused;
+            if (!currentlyFocused) {
+                await focusHandlers.onFocusRequested();
+            }
+        }
+        return new Promise((resolve) => {
+            setPromptState({ app, message, resolver: resolve });
+        });
+    }, [focusHandlers]);
+    const handleAllow = useCallback(() => {
+        if (promptState) {
+            promptState.resolver(true);
+            setPromptState(null);
+            // Relinquish focus if we weren't originally focused
+            if (focusHandlers && !wasOriginallyFocusedRef.current) {
+                focusHandlers.onFocusRelinquished();
+            }
+        }
+    }, [promptState, focusHandlers]);
+    const handleDeny = useCallback(() => {
+        if (promptState) {
+            promptState.resolver(false);
+            setPromptState(null);
+            // Relinquish focus if we weren't originally focused
+            if (focusHandlers && !wasOriginallyFocusedRef.current) {
+                focusHandlers.onFocusRelinquished();
+            }
+        }
+    }, [promptState, focusHandlers]);
+    const PromptComponent = useCallback(() => {
+        if (!promptState)
+            return null;
+        return (_jsx(TokenUsagePromptDialog, { app: promptState.app, message: promptState.message, onAllow: handleAllow, onDeny: handleDeny }));
+    }, [promptState, handleAllow, handleDeny]);
+    return {
+        promptUser,
+        PromptComponent
+    };
+};
+export default TokenUsagePromptDialog;

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * BTMS Permission Module (Core)
+ *
+ * Provides wallet permission module for BTMS token spending authorization.
+ * This is the core module without UI dependencies - framework agnostic.
+ *
+ * For React/MUI UI components, see @bsv/btms-permission-module-ui
+ */
+import type { WalletInterface } from '@bsv/sdk';
+import { BasicTokenModule } from './BasicTokenModule.js';
+export type PermissionPromptHandler = (app: string, message: string) => Promise<boolean>;
+export type PermissionModuleFactoryArgs = {
+    wallet: WalletInterface;
+    promptHandler?: PermissionPromptHandler;
+};
+export declare const createBtmsModule: ({ wallet, promptHandler }: PermissionModuleFactoryArgs) => BasicTokenModule;
+export { BasicTokenModule };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,MAAM,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAExF,MAAM,MAAM,2BAA2B,GAAG;IACxC,MAAM,EAAE,eAAe,CAAA;IACvB,aAAa,CAAC,EAAE,uBAAuB,CAAA;CACxC,CAAA;AAID,eAAO,MAAM,gBAAgB,GAAI,2BAA2B,2BAA2B,qBAGtF,CAAA;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * BTMS Permission Module (Core)
+ *
+ * Provides wallet permission module for BTMS token spending authorization.
+ * This is the core module without UI dependencies - framework agnostic.
+ *
+ * For React/MUI UI components, see @bsv/btms-permission-module-ui
+ */
+import { BTMS } from '@bsv/btms';
+import { BasicTokenModule } from './BasicTokenModule.js';
+const denyPrompt = async () => false;
+export const createBtmsModule = ({ wallet, promptHandler }) => {
+    const btms = new BTMS({ wallet, networkPreset: 'local' });
+    return new BasicTokenModule(promptHandler ?? denyPrompt, btms);
+};
+export { BasicTokenModule };

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+/** Permissioned basket prefix - aligns with btms-core */
+export declare const P_BASKET_PREFIX = "p btms";
+/** Literal used in field[0] to indicate token issuance - aligns with btms-core */
+export declare const ISSUE_MARKER = "ISSUE";
+/** Index positions for BTMS PushDrop token fields */
+export declare const BTMS_FIELD: {
+    readonly ASSET_ID: 0;
+    readonly AMOUNT: 1;
+    readonly METADATA: 2;
+};
+/**
+ * Parsed information about a BTMS token from its locking script
+ */
+export interface ParsedTokenInfo {
+    assetId: string;
+    amount: number;
+    metadata?: {
+        name?: string;
+        description?: string;
+        iconURL?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Comprehensive token spend information extracted from createAction args
+ */
+export interface TokenSpendInfo {
+    /** Total amount being sent to recipient (not including change) */
+    sendAmount: number;
+    /** Total amount being spent from inputs */
+    totalInputAmount: number;
+    /** Change amount (totalInputAmount - sendAmount) */
+    changeAmount: number;
+    /** Total amount sent in token outputs (derived from outputs) */
+    outputSendAmount: number;
+    /** Total amount returned as change in token outputs (derived from outputs) */
+    outputChangeAmount: number;
+    /** Whether any token outputs were parsed */
+    hasTokenOutputs: boolean;
+    /** Source of totalInputAmount */
+    inputAmountSource: 'beef' | 'descriptions' | 'derived' | 'none';
+    /** Token name from metadata */
+    tokenName: string;
+    /** Asset ID */
+    assetId: string;
+    /** Recipient identity key (truncated) */
+    recipient?: string;
+    /** Token icon URL if available */
+    iconURL?: string;
+    /** Full action description */
+    actionDescription: string;
+}
+/**
+ * Authorized transaction data captured from createAction response.
+ * Used to verify createSignature calls are signing what was actually authorized.
+ */
+export interface AuthorizedTransaction {
+    /** The reference from the signable transaction */
+    reference: string;
+    /** Hash of all outputs (BIP-143 hashOutputs) */
+    hashOutputs: string;
+    /** Set of authorized outpoints (txid.vout format) */
+    authorizedOutpoints: Set<string>;
+    /** Timestamp when this authorization was created */
+    timestamp: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAUA,yDAAyD;AACzD,eAAO,MAAM,eAAe,WAAW,CAAA;AAEvC,kFAAkF;AAClF,eAAO,MAAM,YAAY,UAAU,CAAA;AAEnC,qDAAqD;AACrD,eAAO,MAAM,UAAU;;;;CAIb,CAAA;AAEV;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;CACF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAA;IAClB,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAA;IACxB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAA;IACxB,8EAA8E;IAC9E,kBAAkB,EAAE,MAAM,CAAA;IAC1B,4CAA4C;IAC5C,eAAe,EAAE,OAAO,CAAA;IACxB,iCAAiC;IACjC,iBAAiB,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,GAAG,MAAM,CAAA;IAC/D,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe;IACf,OAAO,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,iBAAiB,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAA;IACnB,qDAAqD;IACrD,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAChC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAA;CAClB"}

package/dist/types.js

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// BTMS Permission Module Constants and Types
+// ---------------------------------------------------------------------------
+// BRC-99: Baskets prefixed with "p " are permissioned and require wallet
+// permission module support. The scheme ID is "btms".
+//
+// Token basket format: "p btms <assetId>"
+// Example: "p btms abc123def456.0"
+// ---------------------------------------------------------------------------
+/** Permissioned basket prefix - aligns with btms-core */
+export const P_BASKET_PREFIX = 'p btms';
+/** Literal used in field[0] to indicate token issuance - aligns with btms-core */
+export const ISSUE_MARKER = 'ISSUE';
+/** Index positions for BTMS PushDrop token fields */
+export const BTMS_FIELD = {
+    ASSET_ID: 0,
+    AMOUNT: 1,
+    METADATA: 2
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@bsv/btms-permission-module",
+  "version": "1.0.0",
+  "description": "BTMS Permission Module for wallet integration",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "btms",
+    "tokens",
+    "permissions",
+    "wallet"
+  ],
+  "author": "BSV Blockchain Association",
+  "license": "Open BSV",
+  "peerDependencies": {
+    "@bsv/btms": ">=1.0.0",
+    "@bsv/sdk": ">=2.0.3",
+    "@bsv/wallet-toolbox-client": ">=2.0.16"
+  },
+  "devDependencies": {
+    "@bsv/btms": "^1.0.0",
+    "@bsv/sdk": "^2.0.3",
+    "@bsv/wallet-toolbox-client": "^2.0.16",
+    "typescript": "^5.2.2"
+  }
+}