webview.io 1.0.6 → 1.1.0

package/README.md

@@ -106,9 +106,11 @@ function MapComponent() {
 
 ```javascript
 // In your HTML/JS loaded in the WebView
+// The bridge is automatically available as window._wio after injection
 
-// The bridge is automatically available as window._wio
+// IMPORTANT: You must manually call listen() to start the connection
 const wio = window._wio
+wio.listen() // Required to initiate connection handshake
 
 // Handle connection
 wio.on('connect', () => {
@@ -140,7 +142,9 @@ const wio = new WIO({
   maxMessageSize: 1024 * 1024,       // Max message size in bytes (1MB)
   maxMessagesPerSecond: 100,         // Rate limit (100 messages/second)
   autoReconnect: true,               // Enable automatic reconnection
-  messageQueueSize: 50               // Max queued messages when disconnected
+  messageQueueSize: 50,              // Max queued messages when disconnected
+  allowedIncomingEvents: ['hello', 'response'], // Optional incoming event allowlist (non-reserved events)
+  validateIncoming: (event, payload) => true    // Optional custom incoming validator
 })
 ```
 
@@ -180,12 +184,28 @@ This prevents:
 - Fires `connect_timeout` event if all attempts fail
 
 **EMBEDDED Side:**
-- Automatically announces `__embedded_ready` when loaded
+- Bridge is available as `window._wio` after injection
+- **Must manually call `window._wio.listen()` to start connection**
+- Automatically announces `__embedded_ready` when `listen()` is called
 - Retries announcement every 2 seconds until connected
 - Handles race condition if loaded before React Native
 - Responds to `ping` with `pong` containing same token
 - Confirms connection upon receiving `__connection_ack`
 
+## Reserved Events
+
+The library uses several internal events for connection management. These events are handled automatically and **bypass normal message queuing** to ensure reliable connection establishment:
+
+- **`ping`** - Initial connection request from WEBVIEW
+- **`pong`** - Connection response from EMBEDDED
+- **`__heartbeat`** - Periodic health check request
+- **`__heartbeat_response`** - Health check response
+- **`__embedded_ready`** - EMBEDDED announces it's ready to connect
+- **`__connection_ack`** - Final handshake acknowledgment from WEBVIEW
+- **`__webview_ready`** - Signal that WEBVIEW peer is ready (currently logged but not actively used)
+
+**Important:** These events are sent immediately even when disconnected, unlike regular events which are queued. Do not use these event names for your application logic.
+
 ## Async/Await Support
 
 ### Send Messages with Acknowledgments
@@ -231,7 +251,7 @@ console.log('User data received:', userData)
 ### Connection Timeout Handling
 
 ```javascript
-// Handle connection timeout (new event)
+// Handle connection timeout
 wio.on('connect_timeout', ({ attempts }) => {
   console.log(`Failed to connect after ${attempts} attempts`)
   // Optionally retry manually or show error to user
@@ -267,13 +287,13 @@ const stats = wio.getStats()
 console.log(stats)
 // {
 //   connected: true,
-//   embeddedReady: true,              // NEW: EMBEDDED peer readiness state
+//   embeddedReady: true,              // EMBEDDED peer readiness state
 //   peerType: 'WEBVIEW',
 //   origin: 'https://example.com',
 //   lastHeartbeat: 1609459200000,
 //   queuedMessages: 0,
 //   reconnectAttempts: 0,
-//   connectionAttempts: 0,            // NEW: Current connection attempts
+//   connectionAttempts: 0,            // Current connection attempts
 //   activeListeners: 5,
 //   messageRate: 2
 // }
@@ -288,7 +308,7 @@ Each connection uses a unique token for validation:
 ```javascript
 // Automatically generated and validated during handshake
 // Prevents accepting messages from previous connections
-// Tokens are only used for connection-related events
+// Tokens are only used for reserved connection events
 ```
 
 ### Origin Validation
@@ -312,6 +332,29 @@ wio.emit('data', {
 })
 ```
 
+### Incoming Event Allowlist & Validation
+
+For defense-in-depth, you can restrict which **application-level** events are accepted and/or validate incoming payloads. Reserved internal events (handshake/heartbeat/readiness) are always allowed.
+
+```javascript
+const wio = new WIO({
+  type: 'WEBVIEW',
+  debug: true,
+  allowedIncomingEvents: ['get:location', 'location:picked'],
+  validateIncoming: (event, payload) => {
+    // Example: simple checks
+    if (event === 'location:picked') return payload && typeof payload.lat === 'number'
+    return true
+  }
+})
+
+wio.on('error', (error) => {
+  if (error.type === 'DISALLOWED_EVENT' || error.type === 'INVALID_MESSAGE') {
+    console.warn('Dropped incoming message:', error)
+  }
+})
+```
+
 ### Rate Limiting
 
 ```javascript
@@ -356,6 +399,7 @@ wio.on('error', (error) => {
 
 ```javascript
 // Messages are automatically queued when disconnected
+// Reserved events bypass the queue for reliable connection handling
 wio.emit('important-data', { data: 'This will be queued if disconnected' })
 
 // Clear queue manually if needed
@@ -382,7 +426,7 @@ console.log(`${stats.queuedMessages} messages queued`)
 
 #### Connection Methods
 - **`initiate(webViewRef, origin)`** - Establish connection with retry logic (WEBVIEW peer only)
-- **`listen(hostOrigin?)`** - Listen for connection with readiness announcement (EMBEDDED peer only)
+- **`listen(hostOrigin?)`** - Start listening for connection (EMBEDDED peer only). The `hostOrigin` parameter is informational only and used for logging - no validation is performed.
 - **`handleMessage(event)`** - Handle incoming message from WebView
 - **`disconnect(callback?)`** - Disconnect and cleanup all resources
 - **`isConnected()`** - Check connection status
@@ -399,15 +443,19 @@ console.log(`${stats.queuedMessages} messages queued`)
 #### Connection Events
 - **`connect`** - Connection established (after 3-way handshake)
 - **`disconnect`** - Connection lost with reason
-- **`connect_timeout`** - Initial connection failed after all attempts (NEW)
+- **`connect_timeout`** - Initial connection failed after all attempts
 - **`reconnecting`** - Reconnection attempt started
 - **`reconnection_failed`** - All reconnection attempts failed
 
-#### Internal Events (handled automatically)
+#### Reserved Internal Events
+These events are handled automatically by the library. Do not use these names for your application events:
+- **`ping`** - Connection initiation from WEBVIEW
+- **`pong`** - Connection response from EMBEDDED
 - **`__embedded_ready`** - EMBEDDED peer announces readiness
 - **`__connection_ack`** - Final acknowledgment in 3-way handshake
-- **`__heartbeat`** - Connection health check
+- **`__heartbeat`** - Connection health check request
 - **`__heartbeat_response`** - Heartbeat response
+- **`__webview_ready`** - WEBVIEW ready signal (informational)
 
 #### Error Events
 - **`error`** - Various error conditions with detailed error objects
@@ -575,6 +623,8 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 | `MESSAGE_HANDLING_ERROR` | Error processing incoming message |
 | `EMIT_ERROR` | Error sending message |
 | `LISTENER_ERROR` | Error in event listener |
+| `DISALLOWED_EVENT` | Incoming event rejected by `allowedIncomingEvents` |
+| `INVALID_MESSAGE` | Incoming message rejected by `validateIncoming` |
 | `RATE_LIMIT_EXCEEDED` | Too many messages sent |
 | `NO_CONNECTION` | Attempted to send without connection |
 
@@ -600,12 +650,13 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 **Symptoms:** `connect_timeout` event fires, connection never succeeds
 
 **Solutions:**
-1. Check that `injectedJavaScript` is properly set on WebView
-2. Verify `javaScriptEnabled={true}` is set
-3. Check browser console for JavaScript errors in WebView
-4. Ensure origin matches exactly (including protocol)
-5. Increase `connectionTimeout` for slow networks
-6. Check that WebView content loads successfully
+1. **Verify `listen()` is called** - The EMBEDDED side must manually call `window._wio.listen()` to start the connection
+2. Check that `injectedJavaScript` is properly set on WebView
+3. Verify `javaScriptEnabled={true}` is set
+4. Check browser console for JavaScript errors in WebView
+5. Ensure origin matches exactly (including protocol)
+6. Increase `connectionTimeout` for slow networks
+7. Check that WebView content loads successfully
 
 ### Messages Not Received
 
@@ -617,6 +668,7 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 3. Look for errors in `error` event listener
 4. Check if rate limiting is being exceeded
 5. Verify message size is under `maxMessageSize`
+6. Ensure you're not using reserved event names
 
 ### Frequent Disconnections
 
@@ -637,7 +689,7 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 - Already handled! The three-way handshake with readiness announcements prevents this
 - EMBEDDED announces readiness periodically until connected
 - WEBVIEW retries connection attempts automatically
-- No action needed from your side
+- Just ensure `window._wio.listen()` is called in your WebView code
 
 ## Differences from iframe.io
 
@@ -647,6 +699,7 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 - **Initialization**: Uses `RefObject<WebView>` instead of `Window` object
 - **Message Handling**: Requires explicit `handleMessage()` call in `onMessage` prop
 - **Injected Script**: Uses `getInjectedJavaScript()` to setup bridge in WebView
+- **Manual Connection**: EMBEDDED side must call `listen()` to start connection
 - **No DOM Dependencies**: Works in React Native environment without DOM APIs
 - **Enhanced Handshake**: Three-way handshake with token validation for mobile reliability
 - **Connection Retry**: Built-in retry logic for spotty mobile connections

package/dist/index.d.ts

@@ -14,6 +14,16 @@ export type Options = {
     messageQueueSize?: number;
     connectionPingInterval?: number;
     maxConnectionAttempts?: number;
+    /**
+     * Optional allowlist of incoming application-level events.
+     * Reserved internal events (ping/pong/heartbeat/handshake) are always allowed.
+     */
+    allowedIncomingEvents?: string[];
+    /**
+     * Optional custom validator for incoming messages.
+     * Return false to drop a message; an 'error' event will be emitted.
+     */
+    validateIncoming?: (event: string, payload: any) => boolean;
 };
 export interface RegisteredEvents {
     [index: string]: Listener[];

package/dist/index.js

@@ -45,6 +45,22 @@ var ackId = function () {
     return "".concat(timestamp, "_").concat(random);
 };
 var generateToken = function () {
+    // Prefer cryptographically strong randomness when available
+    try {
+        var globalCrypto = (typeof crypto !== 'undefined'
+            ? crypto
+            : (typeof window !== 'undefined' && window.crypto)
+                || (typeof globalThis !== 'undefined' && globalThis.crypto));
+        if (globalCrypto && typeof globalCrypto.getRandomValues === 'function') {
+            var buffer = new Uint32Array(4);
+            globalCrypto.getRandomValues(buffer);
+            var randomPart = Array.from(buffer).map(function (n) { return n.toString(16); }).join('');
+            return "".concat(Date.now(), "_").concat(randomPart);
+        }
+    }
+    catch (_a) {
+        // Fall back to Math.random-based implementation below
+    }
     return "".concat(Date.now(), "_").concat(Math.random().toString(36).substring(2, 15));
 };
 var RESERVED_EVENTS = [
@@ -419,6 +435,27 @@ var WIO = /** @class */ (function () {
                 }
                 return;
             }
+            // Optional application-level incoming validation (non-reserved events only)
+            if (!RESERVED_EVENTS.includes(_event)) {
+                if (this.options.allowedIncomingEvents
+                    && !this.options.allowedIncomingEvents.includes(_event)) {
+                    this.fire('error', {
+                        type: 'DISALLOWED_EVENT',
+                        direction: 'incoming',
+                        event: _event
+                    });
+                    return;
+                }
+                if (this.options.validateIncoming
+                    && !this.options.validateIncoming(_event, payload)) {
+                    this.fire('error', {
+                        type: 'INVALID_MESSAGE',
+                        direction: 'incoming',
+                        event: _event
+                    });
+                    return;
+                }
+            }
             // Fire available event listeners
             this.fire(_event, payload, cid);
         }
@@ -673,7 +710,7 @@ var WIO = /** @class */ (function () {
      * NOTE: Does not auto-initialize - page must call window._wio.listen()
      */
     WIO.prototype.getInjectedJavaScript = function () {
-        return "\n      (function() {\n        try {\n          console.log('[EMBEDDED] Initializing WIO bridge...')\n          \n          const RESERVED_EVENTS = [\n            'ping',\n            'pong',\n            '__heartbeat',\n            '__heartbeat_response',\n            '__embedded_ready',\n            '__connection_ack',\n            '__webview_ready'\n          ]\n          \n          // Use closure variable to avoid 'this' binding issues\n          window._wio = {\n            type: 'EMBEDDED',\n            connected: false,\n            Events: {},\n            messageQueue: [],\n            connectionToken: null,\n            setupComplete: false,\n\n            listen: function(){\n              if( this.setupComplete ){\n                console.warn('[EMBEDDED] Already listening')\n                return this\n              }\n\n              console.log('[EMBEDDED] Setting up message listeners...')\n\n              // Listen to messages from React Native\n              window.addEventListener('message', function( event ){\n                try {\n                  const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                  window._wio.handleMessage( message )\n                }\n                catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n              })\n              \n              // Android support\n              if( typeof document !== 'undefined' ){\n                document.addEventListener('message', function( event ){\n                  try {\n                    const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                    window._wio.handleMessage( message )\n                  }\n                  catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n                })\n              }\n\n              this.setupComplete = true\n              console.log('[EMBEDDED] Setup complete, starting ready announcements')\n\n              // Start announcing readiness\n              this.announceReady()\n\n              return this\n            },\n            \n            ackId: function(){\n              const\n              rmin = 100000,\n              rmax = 999999,\n              timestamp = Date.now(),\n              random = Math.floor( Math.random() * ( rmax - rmin + 1 ) + rmin )\n\n              return timestamp + '_' + random\n            },\n            \n            fire: function( _event, payload, cid ){\n              if( !window._wio.Events[_event] && !window._wio.Events[_event + '--@once'] ){\n                console.log('[EMBEDDED] No listener for:', _event)\n                return\n              }\n              \n              const ackFn = cid\n                ? ( error, ...args ) => window._wio.emit( _event + '--' + cid + '--@ack', { error: error || false, args } )\n                : undefined\n              \n              let listeners = []\n              if( window._wio.Events[_event + '--@once'] ){\n                _event += '--@once'\n                listeners = window._wio.Events[_event]\n\n                delete window._wio.Events[_event]\n              }\n              else listeners = window._wio.Events[_event] || []\n              \n              listeners.forEach( fn => {\n                try { payload !== undefined ? fn( payload, ackFn ) : fn( ackFn ) }\n                catch( error ){ console.error('[EMBEDDED] Listener error:', error ) }\n              })\n            },\n            \n            emit: function( _event, payload, fn ){\n              if( typeof payload === 'function' ){\n                fn = payload\n                payload = undefined\n              }\n              \n              if( !window._wio.connected && !RESERVED_EVENTS.includes(_event) ){\n                window._wio.messageQueue.push({ _event, payload, fn, timestamp: Date.now() })\n                console.log('[EMBEDDED] Queued message:', _event)\n                return\n              }\n              \n              try {\n                let cid\n                if( typeof fn === 'function' ){\n                  cid = window._wio.ackId()\n                  window._wio.once( _event + '--' + cid + '--@ack', ({ error, args }) => fn( error, ...args ) )\n                }\n                \n                const messageData = {\n                  _event,\n                  payload,\n                  cid,\n                  timestamp: Date.now(),\n                  token: RESERVED_EVENTS.includes(_event) ? window._wio.connectionToken : undefined\n                }\n                \n                if( typeof window.ReactNativeWebView !== 'undefined' )\n                  window.ReactNativeWebView.postMessage( JSON.stringify( messageData ) )\n                else console.error('[EMBEDDED] ReactNativeWebView not available')\n              }\n              catch( error ){\n                console.error('[EMBEDDED] Emit error:', error )\n                typeof fn === 'function' && fn( String(error) )\n              }\n            },\n            \n            on: function( _event, fn ){\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            once: function( _event, fn ){\n              _event += '--@once'\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            off: function( _event, fn ){\n              if( fn && window._wio.Events[_event] ){\n                const index = window._wio.Events[_event].indexOf( fn )\n                if( index > -1 ){\n                  window._wio.Events[_event].splice( index, 1 )\n                  if( window._wio.Events[_event].length === 0 ) delete window._wio.Events[_event]\n                }\n              }\n              else delete window._wio.Events[_event]\n\n              return window._wio\n            },\n            \n            processMessageQueue: function(){\n              if( !window._wio.connected || window._wio.messageQueue.length === 0 ) return\n              \n              console.log('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')\n              const queue = [ ...window._wio.messageQueue ]\n              window._wio.messageQueue = []\n              \n              queue.forEach( msg => {\n                try { window._wio.emit( msg._event, msg.payload, msg.fn ) }\n                catch( error ){ console.error('[EMBEDDED] Queue process error:', error ) }\n              })\n            },\n            \n            handleMessage: function( data ){\n              if( !data || !data._event ) return\n              \n              const { _event, payload, cid, token } = data\n              \n              console.log('[EMBEDDED] Received:', _event )\n              \n              // Handle heartbeat response\n              if( _event === '__heartbeat_response' )\n                return\n              \n              // Handle heartbeat request\n              if( _event === '__heartbeat' ){\n                window._wio.emit('__heartbeat_response', { timestamp: Date.now() })\n                return\n              }\n              \n              // Handle webview ready signal\n              if( _event === '__webview_ready' ){\n                console.log('[EMBEDDED] WebView ready signal received')\n                return\n              }\n              \n              // Handle ping from WEBVIEW\n              if( _event === 'ping' ){\n                console.log('[EMBEDDED] Received ping, sending pong')\n                window._wio.connectionToken = token\n\n                window._wio.emit('pong', { token: window._wio.connectionToken })\n                return\n              }\n              \n              // Handle connection acknowledgment\n              if( _event === '__connection_ack' ){\n                if( token && token !== window._wio.connectionToken ){\n                  console.error('[EMBEDDED] Invalid connection token in ack')\n                  return\n                }\n                \n                console.log('[EMBEDDED] Connection established (received ack)')\n\n                window._wio.connected = true\n                window._wio.processMessageQueue()\n                window._wio.fire('connect')\n\n                return\n              }\n              \n              // Fire event listeners\n              window._wio.fire( _event, payload, cid )\n            },\n            \n            announceReady: function(){\n              let attempts = 0\n              const maxAttempts = 10\n              const interval = 1000\n              \n              console.log('[EMBEDDED] Starting ready announcements')\n              \n              const announce = () => {\n                if( window._wio.connected ){\n                  console.log('[EMBEDDED] Connected, stopping announcements')\n                  return\n                }\n                \n                attempts++\n                if( attempts > maxAttempts ){\n                  console.log('[EMBEDDED] Max announcement attempts reached')\n                  return\n                }\n                \n                console.log('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')\n                window._wio.emit('__embedded_ready')\n                \n                setTimeout( announce, interval )\n              }\n              \n              announce()\n            }\n          }\n\n          console.log('[EMBEDDED] WIO bridge ready. Call window._wio.listen() to connect.')\n        }\n        catch( error ){\n          console.error('[EMBEDDED] Setup failed:', error )\n          \n          // Create minimal fallback\n          window._wio = {\n            error: error.toString(),\n            listen: function(){ console.error('[EMBEDDED] WIO failed to initialize') },\n            emit: function(){ console.error('[EMBEDDED] WIO failed to initialize') },\n            on: function(){},\n            once: function(){},\n            off: function(){}\n          }\n        }\n\n        true\n      })()\n    ";
+        return "\n      (function() {\n        try {\n          console.debug('[EMBEDDED] Initializing WIO bridge...')\n          \n          const RESERVED_EVENTS = [\n            'ping',\n            'pong',\n            '__heartbeat',\n            '__heartbeat_response',\n            '__embedded_ready',\n            '__connection_ack',\n            '__webview_ready'\n          ]\n          \n          // Use closure variable to avoid 'this' binding issues\n          window._wio = {\n            type: 'EMBEDDED',\n            connected: false,\n            Events: {},\n            messageQueue: [],\n            connectionToken: null,\n            setupComplete: false,\n\n            listen: function(){\n              if( this.setupComplete ){\n                console.warn('[EMBEDDED] Already listening')\n                return this\n              }\n\n              console.debug('[EMBEDDED] Setting up message listeners...')\n\n              // Listen to messages from React Native\n              window.addEventListener('message', function( event ){\n                try {\n                  const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                  window._wio.handleMessage( message )\n                }\n                catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n              })\n              \n              // Android support\n              if( typeof document !== 'undefined' ){\n                document.addEventListener('message', function( event ){\n                  try {\n                    const message = typeof event.data === 'string' ? JSON.parse( event.data ) : event.data\n                    window._wio.handleMessage( message )\n                  }\n                  catch( error ){ console.error('[EMBEDDED] Parse error:', error ) }\n                })\n              }\n\n              this.setupComplete = true\n              console.debug('[EMBEDDED] Setup complete, starting ready announcements')\n\n              // Start announcing readiness\n              this.announceReady()\n\n              return this\n            },\n            \n            ackId: function(){\n              const\n              rmin = 100000,\n              rmax = 999999,\n              timestamp = Date.now(),\n              random = Math.floor( Math.random() * ( rmax - rmin + 1 ) + rmin )\n\n              return timestamp + '_' + random\n            },\n            \n            fire: function( _event, payload, cid ){\n              if( !window._wio.Events[_event] && !window._wio.Events[_event + '--@once'] ){\n                console.debug('[EMBEDDED] No listener for:', _event)\n                return\n              }\n              \n              const ackFn = cid\n                ? ( error, ...args ) => window._wio.emit( _event + '--' + cid + '--@ack', { error: error || false, args } )\n                : undefined\n              \n              let listeners = []\n              if( window._wio.Events[_event + '--@once'] ){\n                _event += '--@once'\n                listeners = window._wio.Events[_event]\n\n                delete window._wio.Events[_event]\n              }\n              else listeners = window._wio.Events[_event] || []\n              \n              listeners.forEach( fn => {\n                try { payload !== undefined ? fn( payload, ackFn ) : fn( ackFn ) }\n                catch( error ){ console.error('[EMBEDDED] Listener error:', error ) }\n              })\n            },\n            \n            emit: function( _event, payload, fn ){\n              if( typeof payload === 'function' ){\n                fn = payload\n                payload = undefined\n              }\n              \n              if( !window._wio.connected && !RESERVED_EVENTS.includes(_event) ){\n                window._wio.messageQueue.push({ _event, payload, fn, timestamp: Date.now() })\n                console.debug('[EMBEDDED] Queued message:', _event)\n                return\n              }\n              \n              try {\n                let cid\n                if( typeof fn === 'function' ){\n                  cid = window._wio.ackId()\n                  window._wio.once( _event + '--' + cid + '--@ack', ({ error, args }) => fn( error, ...args ) )\n                }\n                \n                const messageData = {\n                  _event,\n                  payload,\n                  cid,\n                  timestamp: Date.now(),\n                  token: RESERVED_EVENTS.includes(_event) ? window._wio.connectionToken : undefined\n                }\n                \n                if( typeof window.ReactNativeWebView !== 'undefined' )\n                  window.ReactNativeWebView.postMessage( JSON.stringify( messageData ) )\n                else console.error('[EMBEDDED] ReactNativeWebView not available')\n              }\n              catch( error ){\n                console.error('[EMBEDDED] Emit error:', error )\n                typeof fn === 'function' && fn( String(error) )\n              }\n            },\n            \n            on: function( _event, fn ){\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            once: function( _event, fn ){\n              _event += '--@once'\n              if( !window._wio.Events[_event] ) window._wio.Events[_event] = []\n\n              window._wio.Events[_event].push( fn )\n\n              return window._wio\n            },\n            \n            off: function( _event, fn ){\n              if( fn && window._wio.Events[_event] ){\n                const index = window._wio.Events[_event].indexOf( fn )\n                if( index > -1 ){\n                  window._wio.Events[_event].splice( index, 1 )\n                  if( window._wio.Events[_event].length === 0 ) delete window._wio.Events[_event]\n                }\n              }\n              else delete window._wio.Events[_event]\n\n              return window._wio\n            },\n            \n            processMessageQueue: function(){\n              if( !window._wio.connected || window._wio.messageQueue.length === 0 ) return\n              \n              console.debug('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')\n              const queue = [ ...window._wio.messageQueue ]\n              window._wio.messageQueue = []\n              \n              queue.forEach( msg => {\n                try { window._wio.emit( msg._event, msg.payload, msg.fn ) }\n                catch( error ){ console.error('[EMBEDDED] Queue process error:', error ) }\n              })\n            },\n            \n            handleMessage: function( data ){\n              if( !data || !data._event ) return\n              \n              const { _event, payload, cid, token } = data\n              \n              console.debug('[EMBEDDED] Received:', _event )\n              \n              // Handle heartbeat response\n              if( _event === '__heartbeat_response' )\n                return\n              \n              // Handle heartbeat request\n              if( _event === '__heartbeat' ){\n                window._wio.emit('__heartbeat_response', { timestamp: Date.now() })\n                return\n              }\n              \n              // Handle webview ready signal\n              if( _event === '__webview_ready' ){\n                console.debug('[EMBEDDED] WebView ready signal received')\n                return\n              }\n              \n              // Handle ping from WEBVIEW\n              if( _event === 'ping' ){\n                console.debug('[EMBEDDED] Received ping, sending pong')\n                window._wio.connectionToken = token\n\n                window._wio.emit('pong', { token: window._wio.connectionToken })\n                return\n              }\n              \n              // Handle connection acknowledgment\n              if( _event === '__connection_ack' ){\n                if( token && token !== window._wio.connectionToken ){\n                  console.error('[EMBEDDED] Invalid connection token in ack')\n                  return\n                }\n                \n                console.debug('[EMBEDDED] Connection established (received ack)')\n\n                window._wio.connected = true\n                window._wio.processMessageQueue()\n                window._wio.fire('connect')\n\n                return\n              }\n              \n              // Fire event listeners\n              window._wio.fire( _event, payload, cid )\n            },\n            \n            announceReady: function(){\n              let attempts = 0\n              const maxAttempts = 10\n              const interval = 1000\n              \n              console.debug('[EMBEDDED] Starting ready announcements')\n              \n              const announce = () => {\n                if( window._wio.connected ){\n                  console.debug('[EMBEDDED] Connected, stopping announcements')\n                  return\n                }\n                \n                attempts++\n                if( attempts > maxAttempts ){\n                  console.debug('[EMBEDDED] Max announcement attempts reached')\n                  return\n                }\n                \n                console.debug('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')\n                window._wio.emit('__embedded_ready')\n                \n                setTimeout( announce, interval )\n              }\n              \n              announce()\n            }\n          }\n\n          console.debug('[EMBEDDED] WIO bridge ready. Call window._wio.listen() to connect.')\n        }\n        catch( error ){\n          console.error('[EMBEDDED] Setup failed:', error )\n          \n          // Create minimal fallback\n          window._wio = {\n            error: error.toString(),\n            listen: function(){ console.error('[EMBEDDED] WIO failed to initialize') },\n            emit: function(){ console.error('[EMBEDDED] WIO failed to initialize') },\n            on: function(){},\n            once: function(){},\n            off: function(){}\n          }\n        }\n\n        true\n      })()\n    ";
     };
     return WIO;
 }());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webview.io",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Easy and friendly API to connect and interact between React Native and WebView with enhanced security, reliability, and modern async/await support.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -17,6 +17,16 @@ export type Options = {
   messageQueueSize?: number
   connectionPingInterval?: number
   maxConnectionAttempts?: number
+  /**
+   * Optional allowlist of incoming application-level events.
+   * Reserved internal events (ping/pong/heartbeat/handshake) are always allowed.
+   */
+  allowedIncomingEvents?: string[]
+  /**
+   * Optional custom validator for incoming messages.
+   * Return false to drop a message; an 'error' event will be emitted.
+   */
+  validateIncoming?: ( event: string, payload: any ) => boolean
 }
 
 export interface RegisteredEvents {
@@ -83,7 +93,26 @@ const ackId = () => {
 }
 
 const generateToken = () => {
-  return `${Date.now()}_${Math.random().toString(36).substring(2, 15)}`
+  // Prefer cryptographically strong randomness when available
+  try {
+    const globalCrypto = (typeof crypto !== 'undefined'
+      ? crypto
+      : (typeof window !== 'undefined' && (window as any).crypto)
+        || (typeof globalThis !== 'undefined' && (globalThis as any).crypto))
+
+    if( globalCrypto && typeof globalCrypto.getRandomValues === 'function' ){
+      const buffer = new Uint32Array(4)
+      globalCrypto.getRandomValues( buffer )
+
+      const randomPart = Array.from( buffer ).map( n => n.toString( 16 ) ).join('')
+      return `${Date.now()}_${randomPart}`
+    }
+  }
+  catch{
+    // Fall back to Math.random-based implementation below
+  }
+
+  return `${Date.now()}_${Math.random().toString( 36 ).substring( 2, 15 )}`
 }
 
 const RESERVED_EVENTS = [
@@ -544,6 +573,29 @@ export default class WIO {
         return
       }
 
+      // Optional application-level incoming validation (non-reserved events only)
+      if( !RESERVED_EVENTS.includes( _event ) ){
+        if( this.options.allowedIncomingEvents
+            && !this.options.allowedIncomingEvents.includes( _event ) ){
+          this.fire('error', {
+            type: 'DISALLOWED_EVENT',
+            direction: 'incoming',
+            event: _event
+          })
+          return
+        }
+
+        if( this.options.validateIncoming
+            && !this.options.validateIncoming( _event, payload ) ){
+          this.fire('error', {
+            type: 'INVALID_MESSAGE',
+            direction: 'incoming',
+            event: _event
+          })
+          return
+        }
+      }
+
       // Fire available event listeners
       this.fire( _event, payload, cid )
     }
@@ -821,7 +873,7 @@ export default class WIO {
     return `
       (function() {
         try {
-          console.log('[EMBEDDED] Initializing WIO bridge...')
+          console.debug('[EMBEDDED] Initializing WIO bridge...')
           
           const RESERVED_EVENTS = [
             'ping',
@@ -848,7 +900,7 @@ export default class WIO {
                 return this
               }
 
-              console.log('[EMBEDDED] Setting up message listeners...')
+              console.debug('[EMBEDDED] Setting up message listeners...')
 
               // Listen to messages from React Native
               window.addEventListener('message', function( event ){
@@ -871,7 +923,7 @@ export default class WIO {
               }
 
               this.setupComplete = true
-              console.log('[EMBEDDED] Setup complete, starting ready announcements')
+              console.debug('[EMBEDDED] Setup complete, starting ready announcements')
 
               // Start announcing readiness
               this.announceReady()
@@ -891,7 +943,7 @@ export default class WIO {
             
             fire: function( _event, payload, cid ){
               if( !window._wio.Events[_event] && !window._wio.Events[_event + '--@once'] ){
-                console.log('[EMBEDDED] No listener for:', _event)
+                console.debug('[EMBEDDED] No listener for:', _event)
                 return
               }
               
@@ -922,7 +974,7 @@ export default class WIO {
               
               if( !window._wio.connected && !RESERVED_EVENTS.includes(_event) ){
                 window._wio.messageQueue.push({ _event, payload, fn, timestamp: Date.now() })
-                console.log('[EMBEDDED] Queued message:', _event)
+                console.debug('[EMBEDDED] Queued message:', _event)
                 return
               }
               
@@ -983,7 +1035,7 @@ export default class WIO {
             processMessageQueue: function(){
               if( !window._wio.connected || window._wio.messageQueue.length === 0 ) return
               
-              console.log('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')
+              console.debug('[EMBEDDED] Processing', window._wio.messageQueue.length, 'queued messages')
               const queue = [ ...window._wio.messageQueue ]
               window._wio.messageQueue = []
               
@@ -998,7 +1050,7 @@ export default class WIO {
               
               const { _event, payload, cid, token } = data
               
-              console.log('[EMBEDDED] Received:', _event )
+              console.debug('[EMBEDDED] Received:', _event )
               
               // Handle heartbeat response
               if( _event === '__heartbeat_response' )
@@ -1012,13 +1064,13 @@ export default class WIO {
               
               // Handle webview ready signal
               if( _event === '__webview_ready' ){
-                console.log('[EMBEDDED] WebView ready signal received')
+                console.debug('[EMBEDDED] WebView ready signal received')
                 return
               }
               
               // Handle ping from WEBVIEW
               if( _event === 'ping' ){
-                console.log('[EMBEDDED] Received ping, sending pong')
+                console.debug('[EMBEDDED] Received ping, sending pong')
                 window._wio.connectionToken = token
 
                 window._wio.emit('pong', { token: window._wio.connectionToken })
@@ -1032,7 +1084,7 @@ export default class WIO {
                   return
                 }
                 
-                console.log('[EMBEDDED] Connection established (received ack)')
+                console.debug('[EMBEDDED] Connection established (received ack)')
 
                 window._wio.connected = true
                 window._wio.processMessageQueue()
@@ -1050,21 +1102,21 @@ export default class WIO {
               const maxAttempts = 10
               const interval = 1000
               
-              console.log('[EMBEDDED] Starting ready announcements')
+              console.debug('[EMBEDDED] Starting ready announcements')
               
               const announce = () => {
                 if( window._wio.connected ){
-                  console.log('[EMBEDDED] Connected, stopping announcements')
+                  console.debug('[EMBEDDED] Connected, stopping announcements')
                   return
                 }
                 
                 attempts++
                 if( attempts > maxAttempts ){
-                  console.log('[EMBEDDED] Max announcement attempts reached')
+                  console.debug('[EMBEDDED] Max announcement attempts reached')
                   return
                 }
                 
-                console.log('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')
+                console.debug('[EMBEDDED] Announcing ready (attempt', attempts + '/' + maxAttempts + ')')
                 window._wio.emit('__embedded_ready')
                 
                 setTimeout( announce, interval )
@@ -1074,7 +1126,7 @@ export default class WIO {
             }
           }
 
-          console.log('[EMBEDDED] WIO bridge ready. Call window._wio.listen() to connect.')
+          console.debug('[EMBEDDED] WIO bridge ready. Call window._wio.listen() to connect.')
         }
         catch( error ){
           console.error('[EMBEDDED] Setup failed:', error )