@0xio/sdk 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to the 0xio Wallet SDK will be documented in this file.
 
+## [2.4.1] - 2026-04-14
+
+### Security
+- **[CRITICAL] postMessage origin validation**: Parent-frame messages now validated against a strict trusted origins set instead of accepting all origins. Prevents malicious pages from intercepting wallet requests via iframe embedding.
+- **[CRITICAL] Removed auto-trust for iframes**: SDK no longer assumes any iframe parent is a wallet bridge. Must receive a `walletReady` signal from a trusted origin first.
+- **[CRITICAL] Response binding**: Only responses with matching pending request IDs are processed. Forged responses from injected scripts are rejected.
+- **[HIGH] Removed `simulateExtensionEvent`**: Dev utility that could be exploited on staging builds to inject fake wallet events has been removed.
+- **[HIGH] No wildcard postMessage**: `postMessageToExtension` now uses specific trusted origins (`tauri://localhost`, etc.) instead of `'*'` for parent-frame communication.
+
+### Fixed
+- **No retry on user rejection**: `retry()` detects rejection/denied/cancelled errors and throws immediately. Prevents double confirmation popups.
+- **`withTimeout` timer leak**: Timer is now cleared via `.finally()` when the promise resolves, preventing 30s memory retention per request.
+- **`retry` off-by-one**: `maxRetries=1` now correctly means 1 initial + 1 retry = 2 total (was 3).
+- **Message listener cleanup**: `cleanup()` now removes the `window.addEventListener('message')` listener, preventing accumulation on re-instantiation.
+- **Type compatibility**: Replaced `NodeJS.Timeout` with `ReturnType<typeof setTimeout>` for browser-only environments.
+- **`process.env` guard**: `createLogger` now uses optional chaining for `process.env.NODE_ENV`, preventing ReferenceError when imported in browser without bundler.
+- **Duplicate `isValidNetworkId`**: Removed duplicate export from `utils.ts`, canonical version in `config/networks.ts`.
+
+### Added
+- **`setTrustedOrigins(origins)`**: New method to configure allowed parent-frame origins for iframe/bridge communication.
+
+### Documentation
+- Fixed all event listener examples to use `event.data.xxx` (WalletEvent wrapper)
+- Fixed `TransactionHistory` type (`totalCount`/`hasMore` instead of `total`/`limit`/`totalPages`)
+- Fixed `retry()` docs (positional args, not options object)
+- Fixed `formatZeroXIO` return value (no " OCT" suffix)
+- Fixed `toMicroZeroXIO` return type (string, not number)
+- Removed nonexistent `ConnectOptions.timeout`, `.requestPrivateAccess`
+- Removed nonexistent `ConnectionInfo.permissions`
+- Changed `ErrorCode.TIMEOUT` to `ErrorCode.NETWORK_ERROR`
+- Updated mainnet privacy support to "Yes"
+
 ## [2.4.0] - 2026-03-24
 
 ### Added

package/README.md

@@ -1,10 +1,15 @@
 # 0xio Wallet SDK
 
-**Version:** 2.4.0
+**Version:** 2.4.1
 
 Official TypeScript SDK for integrating DApps with 0xio Wallet on Octra Network.
 
-## What's New in v2.4.0
+## What's New in v2.4.1
+
+- **No retry on user rejection**: Transactions, contract calls, and sign requests rejected by the user no longer trigger automatic retry. Prevents double confirmation popups.
+- **Type fixes**: Replaced `NodeJS.Timeout` with `ReturnType<typeof setTimeout>` for browser compatibility.
+
+## v2.4.0
 
 - **Desktop/Mobile DApp Bridge**: SDK now supports running inside iframes (0xio Desktop) and WebViews (0xio App). Requests are relayed to the parent frame automatically.
 - **Auto Frame Detection**: When `window.parent !== window`, the SDK assumes a wallet bridge is available and marks the wallet as detected.
@@ -163,11 +168,11 @@ console.log('Signature:', signature);
 ### Events
 
 ```typescript
-wallet.on('connect', (event) => console.log('Connected:', event.address));
+wallet.on('connect', (event) => console.log('Connected:', event.data.address));
 wallet.on('disconnect', (event) => console.log('Disconnected'));
-wallet.on('balanceChanged', (event) => console.log('New balance:', event.newBalance.total));
-wallet.on('accountChanged', (event) => console.log('Account changed:', event.newAddress));
-wallet.on('networkChanged', (event) => console.log('Network:', event.newNetwork.name));
+wallet.on('balanceChanged', (event) => console.log('New balance:', event.data.newBalance.total));
+wallet.on('accountChanged', (event) => console.log('Account changed:', event.data.newAddress));
+wallet.on('networkChanged', (event) => console.log('Network:', event.data.newNetwork.name));
 ```
 
 ## Error Handling
@@ -227,7 +232,7 @@ console.log(mainnet.supportsPrivacy); // true
 
 | Network | Privacy (FHE) | Explorer |
 |---------|:---:|---|
-| Mainnet Alpha | No | [octrascan.io](https://octrascan.io) |
+| Mainnet Alpha | Yes | [octrascan.io](https://octrascan.io) |
 | Devnet | Yes | [devnet.octrascan.io](https://devnet.octrascan.io) |
 
 ### NetworkInfo Type

package/dist/index.d.ts

@@ -412,7 +412,7 @@ declare class ZeroXIOWallet extends EventEmitter {
  * to ensure secure wallet interactions.
  *
  * @module communication
- * @version 2.2.0
+ * @version 2.4.1
  * @license MIT
  */
 
@@ -452,6 +452,10 @@ declare class ExtensionCommunicator extends EventEmitter {
     private extensionDetectionInterval;
     /** Current extension availability state */
     private isExtensionAvailableState;
+    /** Message listener reference for cleanup */
+    private messageListener;
+    /** Trusted parent origins for iframe communication */
+    private trustedOrigins;
     /** Maximum number of concurrent pending requests */
     private readonly MAX_CONCURRENT_REQUESTS;
     /** Time window for rate limiting (milliseconds) */
@@ -465,7 +469,12 @@ declare class ExtensionCommunicator extends EventEmitter {
      *
      * @param {boolean} debug - Enable debug logging
      */
-    constructor(debug?: boolean);
+    constructor(debug?: boolean, trustedOrigins?: string[]);
+    /**
+     * Add trusted origins for iframe/bridge communication
+     * Call this before connecting if your dApp runs inside a trusted frame
+     */
+    setTrustedOrigins(origins: string[]): void;
     /**
      * Initialize communication with the wallet extension
      *
@@ -614,6 +623,10 @@ declare function getNetworkConfig(networkId?: string): NetworkInfo;
  * Get all available networks
  */
 declare function getAllNetworks(): NetworkInfo[];
+/**
+ * Check if network ID is valid
+ */
+declare function isValidNetworkId(networkId: string): boolean;
 
 /**
  * Default balance structure
@@ -623,7 +636,7 @@ declare function createDefaultBalance(total?: number): Balance;
  * SDK Configuration constants
  */
 declare const SDK_CONFIG: {
-    readonly version: "2.3.0";
+    readonly version: "2.4.1";
     readonly defaultNetworkId: "mainnet";
     readonly communicationTimeout: 30000;
     readonly retryAttempts: 3;
@@ -647,10 +660,6 @@ declare function isValidAddress(address: string): boolean;
  * Validate transaction amount
  */
 declare function isValidAmount(amount: number): boolean;
-/**
- * Validate network ID
- */
-declare function isValidNetworkId(networkId: string): boolean;
 /**
  * Validate transaction message
  */
@@ -750,7 +759,7 @@ declare function createLogger(prefix: string, debug: boolean): {
     groupEnd: () => void;
 };
 
-declare const SDK_VERSION = "2.3.0";
+declare const SDK_VERSION = "2.4.1";
 declare const MIN_EXTENSION_VERSION = "2.0.1";
 declare const MIN_EXTENSION_VERSION_DEVNET = "2.2.1";
 declare const SUPPORTED_EXTENSION_VERSIONS = "^2.0.1";

package/dist/index.esm.js

@@ -164,16 +164,6 @@ function isValidAmount(amount) {
         Number.isFinite(amount) &&
         amount <= Number.MAX_SAFE_INTEGER;
 }
-/**
- * Validate network ID
- */
-function isValidNetworkId(networkId) {
-    if (!networkId || typeof networkId !== 'string') {
-        return false;
-    }
-    const validNetworks = ['mainnet', 'devnet', 'custom'];
-    return validNetworks.includes(networkId.toLowerCase());
-}
 /**
  * Validate transaction message
  */
@@ -317,14 +307,21 @@ function delay(ms) {
  */
 async function retry(operation, maxRetries = 3, baseDelay = 1000) {
     let lastError;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    // maxRetries = number of retries AFTER the first attempt
+    // Total attempts = 1 (initial) + maxRetries
+    for (let attempt = 0; attempt < 1 + maxRetries; attempt++) {
         try {
             return await operation();
         }
         catch (error) {
             lastError = error;
-            if (attempt === maxRetries) {
-                break; // Last attempt failed
+            // Never retry user rejections — these are intentional
+            const msg = lastError.message?.toLowerCase() || '';
+            if (msg.includes('rejected') || msg.includes('denied') || msg.includes('cancelled') || msg.includes('user refused')) {
+                throw lastError;
+            }
+            if (attempt >= maxRetries) {
+                break; // All retries exhausted
             }
             // Exponential backoff: 1s, 2s, 4s, etc.
             const delayMs = baseDelay * Math.pow(2, attempt);
@@ -337,12 +334,15 @@ async function retry(operation, maxRetries = 3, baseDelay = 1000) {
  * Timeout wrapper for promises
  */
 function withTimeout(promise, timeoutMs, timeoutMessage = 'Operation timed out') {
+    let timer;
     const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
+        timer = setTimeout(() => {
             reject(new ZeroXIOWalletError(ErrorCode.NETWORK_ERROR, timeoutMessage));
         }, timeoutMs);
     });
-    return Promise.race([promise, timeoutPromise]);
+    return Promise.race([promise, timeoutPromise]).finally(() => {
+        clearTimeout(timer);
+    });
 }
 // ===================
 // BROWSER UTILITIES
@@ -409,7 +409,8 @@ function generateMockData() {
  * Create development logger
  */
 function createLogger(prefix, debug) {
-    const isDevelopment = typeof window !== 'undefined' && (window.location.hostname === 'localhost' ||
+    const isDevelopment = typeof window !== 'undefined' && ((typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') ||
+        window.location.hostname === 'localhost' ||
         window.location.hostname === '127.0.0.1' ||
         window.__OCTRA_SDK_DEBUG__);
     // Only enable logging in development mode AND when debug is explicitly enabled
@@ -467,7 +468,7 @@ function createLogger(prefix, debug) {
  * to ensure secure wallet interactions.
  *
  * @module communication
- * @version 2.2.0
+ * @version 2.4.1
  * @license MIT
  */
 /**
@@ -499,7 +500,7 @@ class ExtensionCommunicator extends EventEmitter {
      *
      * @param {boolean} debug - Enable debug logging
      */
-    constructor(debug = false) {
+    constructor(debug = false, trustedOrigins = []) {
         super(debug);
         /** Legacy request counter (deprecated, kept for fallback) */
         this.requestId = 0;
@@ -511,6 +512,10 @@ class ExtensionCommunicator extends EventEmitter {
         this.extensionDetectionInterval = null;
         /** Current extension availability state */
         this.isExtensionAvailableState = false;
+        /** Message listener reference for cleanup */
+        this.messageListener = null;
+        /** Trusted parent origins for iframe communication */
+        this.trustedOrigins = [];
         // Rate limiting configuration
         /** Maximum number of concurrent pending requests */
         this.MAX_CONCURRENT_REQUESTS = 50;
@@ -521,9 +526,17 @@ class ExtensionCommunicator extends EventEmitter {
         /** Timestamps of recent requests for rate limiting */
         this.requestTimestamps = [];
         this.logger = createLogger('ExtensionCommunicator', debug);
+        this.trustedOrigins = trustedOrigins;
         this.setupMessageListener();
         this.startExtensionDetection();
     }
+    /**
+     * Add trusted origins for iframe/bridge communication
+     * Call this before connecting if your dApp runs inside a trusted frame
+     */
+    setTrustedOrigins(origins) {
+        this.trustedOrigins = origins;
+    }
     /**
      * Initialize communication with the wallet extension
      *
@@ -649,34 +662,51 @@ class ExtensionCommunicator extends EventEmitter {
             return; // Not in browser environment
         }
         const allowedOrigin = window.location.origin;
-        window.addEventListener('message', (event) => {
-            // Accept messages from same origin OR from parent frame (desktop/mobile bridge)
+        // Store allowed origins for parent frame communication
+        // Desktop (Tauri): tauri://localhost or https://tauri.localhost
+        // Mobile (Expo): about:blank or custom scheme
+        const trustedParentOrigins = new Set([
+            allowedOrigin,
+            'tauri://localhost',
+            'https://tauri.localhost',
+            'http://localhost',
+            'https://localhost',
+        ]);
+        // Allow dApps to register additional trusted origins
+        if (this.trustedOrigins) {
+            for (const origin of this.trustedOrigins) {
+                trustedParentOrigins.add(origin);
+            }
+        }
+        this.messageListener = (event) => {
+            // Strict origin validation
             const isFromSameOrigin = event.origin === allowedOrigin;
-            const isFromParent = event.source === window.parent && window.parent !== window;
-            if (!isFromSameOrigin && !isFromParent) {
+            const isFromTrustedParent = event.source === window.parent
+                && window.parent !== window
+                && trustedParentOrigins.has(event.origin);
+            if (!isFromSameOrigin && !isFromTrustedParent) {
                 return;
             }
-            // Accept from same window or parent frame
+            // Only accept from same window (extension content script) or trusted parent frame
             if (event.source !== window && event.source !== window.parent) {
                 return;
             }
-            // Check if it's a 0xio SDK response
+            // Verify message structure
             if (!event.data || event.data.source !== '0xio-sdk-bridge') {
                 return;
             }
-            // Handle different types of messages
+            // Validate response has a pending request (prevents forged responses)
             if (event.data.response) {
-                // Regular request/response
                 const response = event.data.response;
-                if (response && response.id) {
+                if (response && response.id && this.pendingRequests.has(response.id)) {
                     this.handleExtensionResponse(response);
                 }
             }
             else if (event.data.event) {
-                // Event notification from extension
                 this.handleExtensionEvent(event.data.event);
             }
-        });
+        };
+        window.addEventListener('message', this.messageListener);
         this.logger.log('Message listener setup complete');
     }
     /**
@@ -732,9 +762,28 @@ class ExtensionCommunicator extends EventEmitter {
         const msg = { source: '0xio-sdk-request', request };
         // Post to same window (extension content script picks it up)
         window.postMessage(msg, window.location.origin);
-        // Also post to parent frame if in an iframe (desktop/mobile bridge picks it up)
+        // Also post to parent frame if in an iframe (desktop/mobile bridge)
+        // Use specific origin instead of wildcard to prevent interception
         if (window.parent !== window) {
-            window.parent.postMessage(msg, '*');
+            try {
+                // Try same-origin first (works for Tauri, same-domain iframes)
+                window.parent.postMessage(msg, window.location.origin);
+            }
+            catch {
+                // Cross-origin parent (e.g. tauri://localhost) — use known trusted origins only
+                const trustedOrigins = ['tauri://localhost', 'https://tauri.localhost'];
+                if (this.trustedOrigins) {
+                    trustedOrigins.push(...this.trustedOrigins);
+                }
+                for (const origin of trustedOrigins) {
+                    try {
+                        window.parent.postMessage(msg, origin);
+                    }
+                    catch {
+                        // Origin not matching, skip
+                    }
+                }
+            }
         }
     }
     /**
@@ -830,17 +879,26 @@ class ExtensionCommunicator extends EventEmitter {
             this.logger.log('Received octraWalletReady event');
             this.isExtensionAvailableState = true;
         });
-        // Listen for desktop/mobile bridge walletReady via postMessage
+        // Listen for desktop/mobile bridge walletReady via postMessage (with origin validation)
         window.addEventListener('message', (event) => {
             if (event.data?.source === '0xio-sdk-bridge' && event.data?.event?.type === 'walletReady') {
-                this.logger.log('Received walletReady via postMessage (desktop/mobile bridge)');
-                this.isExtensionAvailableState = true;
+                const isSameOrigin = event.origin === window.location.origin;
+                const isTrusted = this.trustedOrigins.includes(event.origin)
+                    || event.origin === 'tauri://localhost'
+                    || event.origin === 'https://tauri.localhost';
+                if (isSameOrigin || isTrusted) {
+                    this.logger.log('Received walletReady via postMessage from trusted origin');
+                    this.isExtensionAvailableState = true;
+                }
+                else {
+                    this.logger.warn(`Ignored walletReady from untrusted origin: ${event.origin}`);
+                }
             }
         });
-        // Also detect if running inside a frame with a wallet bridge parent
+        // If running inside a frame, do NOT auto-trust the parent.
+        // Wait for a walletReady message from a trusted origin instead.
         if (window.parent !== window) {
-            this.logger.log('Running inside a frame — checking for parent wallet bridge');
-            this.isExtensionAvailableState = true;
+            this.logger.log('Running inside a frame — waiting for trusted walletReady signal');
         }
         // Initial check (in case extension was already injected)
         this.checkExtensionAvailability();
@@ -977,6 +1035,11 @@ class ExtensionCommunicator extends EventEmitter {
         this.pendingRequests.clear();
         this.isInitialized = false;
         this.isExtensionAvailableState = false;
+        // Remove message listener to prevent accumulation
+        if (this.messageListener) {
+            window.removeEventListener('message', this.messageListener);
+            this.messageListener = null;
+        }
         // Call parent cleanup
         this.removeAllListeners();
         this.logger.log('Communication cleanup complete');
@@ -1050,6 +1113,12 @@ function getNetworkConfig(networkId = DEFAULT_NETWORK_ID) {
 function getAllNetworks() {
     return Object.values(NETWORKS);
 }
+/**
+ * Check if network ID is valid
+ */
+function isValidNetworkId(networkId) {
+    return networkId in NETWORKS;
+}
 
 /**
  * SDK Configuration
@@ -1069,7 +1138,7 @@ function createDefaultBalance(total = 0) {
  * SDK Configuration constants
  */
 const SDK_CONFIG = {
-    version: '2.3.0',
+    version: '2.4.1',
     defaultNetworkId: DEFAULT_NETWORK_ID,
     communicationTimeout: 30000, // 30 seconds
     retryAttempts: 3,
@@ -1770,7 +1839,7 @@ var wallet = /*#__PURE__*/Object.freeze({
  */
 // Main exports
 // Version information
-const SDK_VERSION = '2.3.0';
+const SDK_VERSION = '2.4.1';
 const MIN_EXTENSION_VERSION = '2.0.1'; // Mainnet Alpha
 const MIN_EXTENSION_VERSION_DEVNET = '2.2.1'; // Devnet (contract calls, privacy)
 const SUPPORTED_EXTENSION_VERSIONS = '^2.0.1'; // Supports all versions >= 2.0.1
@@ -1825,7 +1894,8 @@ if (typeof window !== 'undefined') {
     window.__OCTRA_SDK_VERSION__ = SDK_VERSION;
     window.__ZEROXIO_SDK_VERSION__ = SDK_VERSION;
     // Development mode detection
-    const isDevelopment = window.location.hostname === 'localhost' ||
+    const isDevelopment = (typeof globalThis !== 'undefined' && globalThis.process?.env?.NODE_ENV === 'development') ||
+        window.location.hostname === 'localhost' ||
         window.location.hostname === '127.0.0.1';
     if (isDevelopment) {
         // Set debug flag but don't automatically log
@@ -1850,13 +1920,7 @@ if (typeof window !== 'undefined') {
                 debugMode: !!window.__ZEROXIO_SDK_DEBUG__,
                 environment: isDevelopment ? 'development' : 'production'
             }),
-            simulateExtensionEvent: (eventType, data) => {
-                window.postMessage({
-                    source: '0xio-sdk-bridge',
-                    event: { type: eventType, data }
-                }, window.location.origin);
-                console.log('[0xio SDK] Simulated extension event:', eventType, data);
-            },
+            // simulateExtensionEvent removed for security — could be exploited on staging builds
             showWelcome: () => {
                 console.log(`[0xio SDK] Development mode - SDK v${SDK_VERSION}`);
                 console.log('[0xio SDK] Debug utilities available at window.__ZEROXIO_SDK_UTILS__');