webview.io 1.0.6 → 1.2.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,13 @@ 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
+  cryptoAuth: {                                 // Optional cryptographic message authentication (HMAC-SHA256)
+    secret: 'replace-with-shared-secret',
+    requireSigned: false
+  }
 })
 ```
 
@@ -180,12 +188,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 +255,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 +291,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 +312,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 +336,47 @@ 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)
+  }
+})
+```
+
+### Cryptographic Message Authentication (HMAC)
+
+If you need **message integrity/authenticity** beyond the default transport guarantees, enable `cryptoAuth` and use the signed APIs. This adds an HMAC-SHA256 signature + timestamp + nonce (with basic replay protection).
+
+**Important security note:** if your WebView loads untrusted content, that content can read the shared secret. This protects against some injection/misrouting scenarios—but not against a fully compromised WebView page.
+
+```javascript
+// React Native side
+const wio = new WIO({
+  type: 'WEBVIEW',
+  cryptoAuth: { secret: 'replace-with-shared-secret', requireSigned: true }
+})
+
+// Send signed
+await wio.emitSigned('hello', { msg: 'signed' })
+const reply = await wio.emitAsyncSigned('getData', { id: 123 }, 5000)
+```
+
 ### Rate Limiting
 
 ```javascript
@@ -356,6 +421,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 +448,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 +465,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 +645,10 @@ 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` |
+| `AUTH_FAILED` | Incoming message failed cryptographic authentication |
+| `AUTH_ERROR` | Cryptographic verification errored (missing crypto, etc.) |
 | `RATE_LIMIT_EXCEEDED` | Too many messages sent |
 | `NO_CONNECTION` | Attempted to send without connection |
 
@@ -600,12 +674,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 +692,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 +713,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 +723,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

@@ -3,6 +3,30 @@ import type { WebView } from 'react-native-webview';
 export type PeerType = 'WEBVIEW' | 'EMBEDDED';
 export type AckFunction = (error: boolean | string, ...args: any[]) => void;
 export type Listener = (payload?: any, ack?: AckFunction) => void;
+export type CryptoAuthOptions = {
+    /**
+     * Shared secret used for HMAC-SHA256 signing.
+     *
+     * IMPORTANT: If an attacker can execute JS in either peer, they can read the secret.
+     * This is for authenticity/integrity between cooperating peers, not a sandbox boundary.
+     */
+    secret: string;
+    /**
+     * If true, drop any incoming message that doesn't carry valid auth.
+     * Default: false (accept unsigned messages)
+     */
+    requireSigned?: boolean;
+    /**
+     * Maximum allowed clock skew for signed messages (ms).
+     * Default: 2 minutes
+     */
+    maxSkewMs?: number;
+    /**
+     * Replay window size (max number of nonces kept in memory).
+     * Default: 500
+     */
+    replayWindowSize?: number;
+};
 export type Options = {
     type?: PeerType;
     debug?: boolean;
@@ -14,12 +38,29 @@ 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;
+    /**
+     * Optional cryptographic message authentication (HMAC-SHA256).
+     * When enabled, use `emitSigned` / `emitAsyncSigned` to send signed messages.
+     * For EMBEDDED (WebView content) you must set the secret in injected bridge too (handled by `getInjectedJavaScript()` when configured).
+     */
+    cryptoAuth?: CryptoAuthOptions;
 };
 export interface RegisteredEvents {
     [index: string]: Listener[];
 }
 export type Peer = {
     type: PeerType;
+    protocolVersion?: number;
     webViewRef?: RefObject<WebView>;
     origin?: string;
     connected?: boolean;
@@ -27,12 +68,19 @@ export type Peer = {
     embeddedReady?: boolean;
 };
 export type MessageData = {
+    v?: number;
     _event: string;
     payload: any;
     cid: string | undefined;
     timestamp?: number;
     size?: number;
     token?: string;
+    auth?: {
+        alg: 'HMAC-SHA256';
+        ts: number;
+        nonce: string;
+        sig: string;
+    };
 };
 export type Message = {
     data: MessageData;
@@ -58,7 +106,21 @@ export default class WIO {
     private maxReconnectAttempts;
     private connectionToken?;
     private connectionAttempts;
+    private seenNonces;
     constructor(options?: Options);
+    private cryptoCfg;
+    /**
+     * Forget nonces that can no longer be replayed, and only then cap the map.
+     *
+     * Age is what decides replayability: a captured message is refused once its
+     * `ts` falls outside maxSkewMs, so a nonce is only worth keeping that long.
+     * Pruning purely by count made the two defaults contradict each other — 500
+     * remembered nonces at the default 100 messages a second is five seconds of
+     * history guarding a two-minute acceptance window.
+     */
+    private pruneNonces;
+    private signOutgoing;
+    private verifyIncomingAuth;
     debug(...args: any[]): void;
     isConnected(): boolean;
     private startHeartbeat;
@@ -93,6 +155,12 @@ export default class WIO {
     }): void;
     fire(_event: string, payload?: MessageData['payload'], cid?: string): void;
     emit<T = any>(_event: string, payload?: T | AckFunction, fn?: AckFunction): this;
+    /**
+     * Send a signed message (HMAC-SHA256) when `options.cryptoAuth` is configured.
+     * This is async because WebCrypto signing is async.
+     */
+    emitSigned<T = any>(_event: string, payload?: T | AckFunction, fn?: AckFunction): Promise<this>;
+    emitAsyncSigned<T = any, R = any>(_event: string, payload?: T, timeout?: number): Promise<R>;
     on(_event: string, fn: Listener): this;
     once(_event: string, fn: Listener): this;
     off(_event: string, fn?: Listener): this;