webview.io 1.1.0 → 1.2.0

package/README.md

@@ -144,7 +144,11 @@ const wio = new WIO({
   autoReconnect: true,               // Enable automatic reconnection
   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
+  validateIncoming: (event, payload) => true,   // Optional custom incoming validator
+  cryptoAuth: {                                 // Optional cryptographic message authentication (HMAC-SHA256)
+    secret: 'replace-with-shared-secret',
+    requireSigned: false
+  }
 })
 ```
 
@@ -355,6 +359,24 @@ wio.on('error', (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
@@ -625,6 +647,8 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 | `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 |
 

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;
@@ -24,12 +48,19 @@ export type Options = {
      * 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;
@@ -37,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;
@@ -68,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;
@@ -103,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;