iframe.io 1.2.0 → 1.3.0

package/src/index.ts

@@ -3,6 +3,52 @@ export type PeerType = 'WINDOW' | 'IFRAME'
 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
+  /**
+   * Enable session-derived keys for enhanced security.
+   * When enabled, a unique session key is derived from the master secret
+   * and exchanged session IDs during connection handshake.
+   * Recommended for long-lived connections and high-security applications.
+   * Default: false
+   */
+  enableSessionKeys?: boolean
+  /**
+   * How often to rotate session keys (in milliseconds).
+   * Only applies when enableSessionKeys is true.
+   * Default: 3600000 (1 hour)
+   */
+  sessionKeyRotationInterval?: number
+}
+
+export type SessionKeyInfo = {
+  keyId: string
+  key: string
+  createdAt: number
+  expiresAt: number
+}
+
 export type Options = {
   type?: PeerType
   debug?: boolean
@@ -22,6 +68,11 @@ export type Options = {
    * Return false to drop a message; an 'error' event will be emitted.
    */
   validateIncoming?: ( event: string, payload: any, origin: string ) => boolean
+  /**
+   * Optional cryptographic message authentication (HMAC-SHA256).
+   * When enabled, use `emitSigned` / `emitAsyncSigned` to send signed messages.
+   */
+  cryptoAuth?: CryptoAuthOptions
 }
 
 export interface RegisteredEvents {
@@ -34,14 +85,25 @@ export type Peer = {
   origin?: string
   connected?: boolean
   lastHeartbeat?: number
+  protocolVersion?: number
+  sessionId?: string
 }
 
 export type MessageData = {
+  v: number // Protocol version
   _event: string
   payload: any
   cid: string | undefined
   timestamp?: number
   size?: number
+  auth?: {
+    alg: 'HMAC-SHA256'
+    ts: number
+    nonce: string
+    sig: string
+    keyId?: string // Used for session key rotation
+  }
+  sessionId?: string // Used for session key exchange
 }
 
 export type Message = {
@@ -57,6 +119,9 @@ export type QueuedMessage = {
   timestamp: number
 }
 
+// Current protocol version
+const PROTOCOL_VERSION = 1
+
 function newObject( data: object ){
   return JSON.parse( JSON.stringify( data ) )
 }
@@ -77,13 +142,119 @@ function sanitizePayload( payload: any, maxSize: number ): any {
   return JSON.parse( JSON.stringify( payload ) )
 }
 
+function constantTimeEqual( a: string, b: string ): boolean {
+  if( a.length !== b.length ) return false
+  let out = 0
+  for( let i = 0; i < a.length; i++ ) out |= a.charCodeAt( i ) ^ b.charCodeAt( i )
+  return out === 0
+}
+
+function getGlobalCrypto(){
+  return (typeof crypto !== 'undefined'
+    ? crypto
+    : (typeof window !== 'undefined' && (window as any).crypto)
+      || (typeof globalThis !== 'undefined' && (globalThis as any).crypto))
+}
+
+function randomHex( bytes: number ): string {
+  try {
+    const globalCrypto = getGlobalCrypto()
+    if( globalCrypto && typeof globalCrypto.getRandomValues === 'function' ){
+      const buf = new Uint8Array( bytes )
+      globalCrypto.getRandomValues( buf )
+      return Array.from( buf ).map( b => b.toString( 16 ).padStart( 2, '0' ) ).join('')
+    }
+  }
+  catch{}
+
+  // Fallback (NOT cryptographically strong)
+  return Array.from({ length: bytes }, () => Math.floor( Math.random() * 256 ).toString( 16 ).padStart( 2, '0' ) ).join('')
+}
+
+async function hmacSha256Base64Url( secret: string, message: string ): Promise<string> {
+  // Browser/WebCrypto
+  try {
+    const globalCrypto = getGlobalCrypto() as any
+    const subtle = globalCrypto?.subtle
+    if( subtle && typeof subtle.importKey === 'function' ){
+      const enc = new TextEncoder()
+      const key = await subtle.importKey(
+        'raw',
+        enc.encode( secret ),
+        { name: 'HMAC', hash: 'SHA-256' },
+        false,
+        ['sign']
+      )
+      const sig = await subtle.sign( 'HMAC', key, enc.encode( message ) )
+      const bytes = new Uint8Array( sig )
+      const b64 = btoa( String.fromCharCode( ...bytes ) )
+      return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+    }
+  }
+  catch{
+    // fallthrough to Node implementation
+  }
+
+  // Node.js (commonjs) - optional
+  try {
+    const nodeCrypto = (globalThis as any).__iof_node_crypto
+      || ((globalThis as any).__iof_node_crypto = (typeof (globalThis as any).require === 'function'
+        ? (globalThis as any).require('crypto')
+        : undefined))
+
+    if( !nodeCrypto ) throw new Error('node crypto unavailable')
+
+    const b64 = nodeCrypto.createHmac('sha256', secret).update( message ).digest('base64')
+    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+  }
+  catch{
+    throw new Error('No crypto implementation available for HMAC-SHA256')
+  }
+}
+
+/**
+ * Derive a session key using HKDF-like construction
+ * HKDF(masterSecret, salt, info) where:
+ * - masterSecret: the shared secret
+ * - salt: combined session IDs
+ * - info: context string
+ */
+async function deriveSessionKey( masterSecret: string, sessionId1: string, sessionId2: string, keyId: string ): Promise<string> {
+  /**
+   * Two HMAC steps, both through `hmacSha256Base64Url`, deliberately.
+   *
+   * This used to have a WebCrypto branch alongside this one, and the two did
+   * not agree: the WebCrypto path fed the extract step's RAW bytes into the
+   * expand step and appended \x01 to the info string, while this path fed the
+   * base64url TEXT of those bytes and appended nothing. Same inputs, different
+   * keys.
+   *
+   * Peers do not have to share an implementation for that to matter, only an
+   * environment: `crypto.subtle` is undefined outside a secure context, so a
+   * WebView or iframe served over plain HTTP took one branch while an HTTPS
+   * host took the other. Every signed message then failed to verify — and
+   * because the WebCrypto branch was also entered from a silent catch, a
+   * single transient failure on one side desynchronised the pair for the rest
+   * of the connection.
+   *
+   * `hmacSha256Base64Url` already resolves WebCrypto vs Node internally and
+   * returns the same string either way, so deriving through it twice is both
+   * shorter and the only version that can agree with itself.
+   */
+  const
+  salt = sessionId1 + '|' + sessionId2,
+  // Extract: PRK = HMAC( masterSecret, salt )
+  prk = await hmacSha256Base64Url( masterSecret, salt ),
+  // Expand: OKM = HMAC( PRK, info )
+  info = 'iframe.io-session-key-' + keyId
+
+  return await hmacSha256Base64Url( prk, info )
+}
+
 const ackId = () => {
   // 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))
+    const globalCrypto = getGlobalCrypto()
 
     if( globalCrypto && typeof globalCrypto.getRandomValues === 'function' ){
       const buffer = new Uint32Array(4)
@@ -106,11 +277,22 @@ const ackId = () => {
   return `${timestampFallback}_${randomFallback}`
 }
 
+// Answered before authentication, so they are gated separately — see the
+// handlers in initiate() and listen().
+const RESERVED_SESSION_KEY_EVENTS = [
+  '__session_key_init',
+  '__session_key_rotate',
+  '__session_key_ack'
+]
+
 const RESERVED_EVENTS = [
   'ping',
   'pong',
   '__heartbeat',
-  '__heartbeat_response'
+  '__heartbeat_response',
+  '__session_key_init',
+  '__session_key_rotate',
+  '__session_key_ack'
 ]
 
 export default class IOF {
@@ -120,10 +302,18 @@ export default class IOF {
   private messageListener?: ( event: MessageEvent ) => void
   private heartbeatTimer?: number
   private reconnectTimer?: number
+  private sessionKeyRotationTimer?: number
   private messageQueue: QueuedMessage[] = []
   private messageRateTracker: number[] = []
   private reconnectAttempts: number = 0
   private maxReconnectAttempts: number = 5
+  private seenNonces: Map<string, number> = new Map()
+  
+  // Session key management
+  private currentSessionKey?: SessionKeyInfo
+  private pendingSessionKey?: SessionKeyInfo
+  private previousSessionKey?: SessionKeyInfo
+  private mySessionId?: string
 
   constructor( options: Options = {} ){
     if( options && typeof options !== 'object' )
@@ -146,6 +336,414 @@ export default class IOF {
       this.peer.type = options.type.toUpperCase() as PeerType
   }
 
+  private cryptoCfg(){
+    if( !this.options.cryptoAuth ) return undefined
+    return {
+      secret: this.options.cryptoAuth.secret,
+      requireSigned: !!this.options.cryptoAuth.requireSigned,
+      maxSkewMs: this.options.cryptoAuth.maxSkewMs ?? 2 * 60 * 1000,
+      replayWindowSize: this.options.cryptoAuth.replayWindowSize ?? 500,
+      enableSessionKeys: !!this.options.cryptoAuth.enableSessionKeys,
+      sessionKeyRotationInterval: this.options.cryptoAuth.sessionKeyRotationInterval ?? 3600000 // 1 hour
+    }
+  }
+
+  /**
+   * Forget nonces that can no longer be replayed, and only then cap the map.
+   *
+   * Age is what actually 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 — as this did — 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,
+   * so anything captured could simply be replayed after five seconds.
+   *
+   * The count cap stays as a memory bound. Reaching it means the rate limiter
+   * is admitting more traffic than the window can remember, so it is reported
+   * rather than applied in silence.
+   */
+  private pruneNonces( maxSize: number ){
+    const cutoff = Date.now() - ( this.cryptoCfg()?.maxSkewMs ?? 2 * 60 * 1000 )
+
+    for( const [ nonce, ts ] of this.seenNonces )
+      if( ts < cutoff ) this.seenNonces.delete( nonce )
+
+    if( this.seenNonces.size <= maxSize ) return
+
+    this.fire('error', {
+      type: 'REPLAY_WINDOW_EXCEEDED',
+      remembered: this.seenNonces.size,
+      maxSize
+    })
+
+    // Oldest first — Map iterates in insertion order, and nonces are inserted
+    // as they arrive.
+    const toRemove = this.seenNonces.size - maxSize
+    let i = 0
+    for( const key of this.seenNonces.keys() ){
+      this.seenNonces.delete( key )
+      if( ++i >= toRemove ) break
+    }
+  }
+
+  /**
+   * Get the appropriate secret for signing messages
+   * Uses session key if available, otherwise falls back to master secret
+   */
+  private getSigningSecret(): { secret: string, keyId?: string } {
+    const cfg = this.cryptoCfg()
+    if( !cfg ) return { secret: '' }
+
+    // Use session key if enabled and available
+    if( cfg.enableSessionKeys && this.currentSessionKey ){
+      return {
+        secret: this.currentSessionKey.key,
+        keyId: this.currentSessionKey.keyId
+      }
+    }
+
+    // Fall back to master secret
+    return { secret: cfg.secret }
+  }
+
+  /**
+   * Get the appropriate secret for verifying incoming messages
+   * Tries current key, then pending, then previous, then master
+   */
+  private getVerificationSecrets(): Array<{ secret: string, keyId?: string }> {
+    const cfg = this.cryptoCfg()
+    if( !cfg ) return []
+
+    const secrets: Array<{ secret: string, keyId?: string }> = []
+
+    if( cfg.enableSessionKeys ){
+      // Try current session key first
+      if( this.currentSessionKey ){
+        secrets.push({
+          secret: this.currentSessionKey.key,
+          keyId: this.currentSessionKey.keyId
+        })
+      }
+
+      // Try pending key during rotation
+      if( this.pendingSessionKey ){
+        secrets.push({
+          secret: this.pendingSessionKey.key,
+          keyId: this.pendingSessionKey.keyId
+        })
+      }
+
+      // Try previous key for grace period
+      if( this.previousSessionKey ){
+        const now = Date.now()
+        if( now < this.previousSessionKey.expiresAt ){
+          secrets.push({
+            secret: this.previousSessionKey.key,
+            keyId: this.previousSessionKey.keyId
+          })
+        }
+      }
+    }
+
+    // Always try master secret as fallback
+    secrets.push({ secret: cfg.secret })
+
+    return secrets
+  }
+
+  /**
+   * Application-level admission check for one incoming message.
+   *
+   * Reserved events bypass it deliberately: the handshake and the heartbeats
+   * must survive an allow-list that does not name them, or configuring one
+   * would silently sever the connection.
+   *
+   * This lives in a method because it used to be written out at each place a
+   * message can arrive — the authenticated and unauthenticated branches of
+   * `initiate()` and of `listen()` — and `listen()`'s unauthenticated branch
+   * never got a copy. An embedded bridge configured with an allow-list and no
+   * cryptoAuth, which is exactly how de.eui runs it, therefore accepted every
+   * event name a host cared to send.
+   */
+  private acceptIncoming( _event: string, payload: any, origin: string ): boolean {
+    if( RESERVED_EVENTS.includes( _event ) ) return true
+
+    if( this.options.allowedIncomingEvents
+        && !this.options.allowedIncomingEvents.includes( _event ) ){
+      this.fire('error', {
+        type: 'DISALLOWED_EVENT',
+        direction: 'incoming',
+        event: _event,
+        origin
+      })
+      return false
+    }
+
+    if( this.options.validateIncoming
+        && !this.options.validateIncoming( _event, payload, origin ) ){
+      this.fire('error', {
+        type: 'INVALID_MESSAGE',
+        direction: 'incoming',
+        event: _event,
+        origin
+      })
+      return false
+    }
+
+    return true
+  }
+
+  /**
+   * Initialize session key exchange
+   * Called after connection is established if enableSessionKeys is true
+   */
+  private async initiateSessionKeyExchange(){
+    const cfg = this.cryptoCfg()
+    if( !cfg || !cfg.enableSessionKeys ) return
+
+    this.debug(`[${this.peer.type}] Initiating session key exchange`)
+
+    // Generate my session ID
+    this.mySessionId = randomHex( 32 )
+
+    // Send session ID to peer
+    this.emit('__session_key_init', { sessionId: this.mySessionId })
+  }
+
+  /**
+   * Handle incoming session key initialization
+   */
+  private async handleSessionKeyInit( peerSessionId: string ){
+    const cfg = this.cryptoCfg()
+    if( !cfg || !cfg.enableSessionKeys ) return
+
+    this.debug(`[${this.peer.type}] Received session key init from peer`)
+
+    // Generate my session ID if not already done
+    if( !this.mySessionId ){
+      this.mySessionId = randomHex( 32 )
+    }
+
+    // Store peer session ID
+    this.peer.sessionId = peerSessionId
+
+    // Derive session key
+    const keyId = `key-${Date.now()}-${randomHex(8)}`
+    const sessionKey = await this.deriveAndStoreSessionKey( keyId )
+
+    // Send acknowledgment with my session ID
+    this.emit('__session_key_ack', {
+      sessionId: this.mySessionId,
+      keyId: keyId
+    })
+
+    this.debug(`[${this.peer.type}] Session key established: ${keyId}`)
+    
+    // Start rotation timer
+    this.startSessionKeyRotation()
+  }
+
+  /**
+   * Handle session key acknowledgment
+   */
+  private async handleSessionKeyAck( data: { sessionId: string, keyId: string } ){
+    const cfg = this.cryptoCfg()
+    if( !cfg || !cfg.enableSessionKeys ) return
+
+    this.debug(`[${this.peer.type}] Received session key ack from peer`)
+
+    // Store peer session ID
+    this.peer.sessionId = data.sessionId
+
+    // Derive session key using the same keyId
+    await this.deriveAndStoreSessionKey( data.keyId )
+
+    this.debug(`[${this.peer.type}] Session key established: ${data.keyId}`)
+    
+    // Start rotation timer
+    this.startSessionKeyRotation()
+  }
+
+  /**
+   * Derive and store a session key
+   */
+  private async deriveAndStoreSessionKey( keyId: string ): Promise<SessionKeyInfo> {
+    const cfg = this.cryptoCfg()
+    if( !cfg || !this.mySessionId || !this.peer.sessionId ){
+      throw new Error('Cannot derive session key: missing session IDs')
+    }
+
+    // Ensure consistent ordering of session IDs
+    const [id1, id2] = [this.mySessionId, this.peer.sessionId].sort()
+
+    const key = await deriveSessionKey( cfg.secret, id1, id2, keyId )
+
+    const now = Date.now()
+    const sessionKeyInfo: SessionKeyInfo = {
+      keyId,
+      key,
+      createdAt: now,
+      expiresAt: now + cfg.sessionKeyRotationInterval + 60000 // Grace period of 1 minute
+    }
+
+    // Rotate keys: current -> previous, new -> current
+    if( this.currentSessionKey ){
+      this.previousSessionKey = this.currentSessionKey
+    }
+
+    this.currentSessionKey = sessionKeyInfo
+    
+    this.fire('session_key_established', { keyId })
+
+    return sessionKeyInfo
+  }
+
+  /**
+   * Start session key rotation timer
+   */
+  private startSessionKeyRotation(){
+    const cfg = this.cryptoCfg()
+    if( !cfg || !cfg.enableSessionKeys ) return
+
+    // Clear existing timer
+    if( this.sessionKeyRotationTimer ){
+      clearInterval( this.sessionKeyRotationTimer )
+    }
+
+    this.sessionKeyRotationTimer = setInterval(() => {
+      this.rotateSessionKey()
+    }, cfg.sessionKeyRotationInterval )
+
+    this.debug(`[${this.peer.type}] Session key rotation timer started (${cfg.sessionKeyRotationInterval}ms)`)
+  }
+
+  /**
+   * Rotate session key
+   */
+  private async rotateSessionKey(){
+    const cfg = this.cryptoCfg()
+    if( !cfg || !cfg.enableSessionKeys || !this.isConnected() ) return
+
+    this.debug(`[${this.peer.type}] Rotating session key`)
+
+    const newKeyId = `key-${Date.now()}-${randomHex(8)}`
+
+    // Derive new key
+    const newSessionKey = await this.deriveAndStoreSessionKey( newKeyId )
+
+    // Set as pending until peer acknowledges
+    this.pendingSessionKey = newSessionKey
+
+    // Notify peer of rotation
+    this.emit('__session_key_rotate', { keyId: newKeyId })
+
+    this.fire('session_key_rotating', { keyId: newKeyId })
+  }
+
+  /**
+   * Handle incoming session key rotation
+   */
+  private async handleSessionKeyRotate( data: { keyId: string } ){
+    const cfg = this.cryptoCfg()
+    if( !cfg || !cfg.enableSessionKeys ) return
+
+    this.debug(`[${this.peer.type}] Peer rotating session key to: ${data.keyId}`)
+
+    // Derive the same key
+    await this.deriveAndStoreSessionKey( data.keyId )
+
+    this.fire('session_key_rotated', { keyId: data.keyId })
+  }
+
+  /**
+   * Stop session key rotation timer
+   */
+  private stopSessionKeyRotation(){
+    if( this.sessionKeyRotationTimer ){
+      clearInterval( this.sessionKeyRotationTimer )
+      this.sessionKeyRotationTimer = undefined
+    }
+  }
+
+  private async signOutgoing( messageData: Omit<MessageData, 'auth'> ): Promise<MessageData['auth']> {
+    const cfg = this.cryptoCfg()
+    if( !cfg ) return undefined
+
+    const { secret, keyId } = this.getSigningSecret()
+
+    const ts = Date.now()
+    const nonce = randomHex( 16 )
+    const canonical = JSON.stringify({
+      v: messageData.v,
+      _event: messageData._event,
+      payload: messageData.payload,
+      cid: messageData.cid,
+      timestamp: messageData.timestamp,
+      size: messageData.size,
+      ts,
+      nonce
+    })
+    const sig = await hmacSha256Base64Url( secret, canonical )
+
+    return { alg: 'HMAC-SHA256', ts, nonce, sig, keyId }
+  }
+
+  private async verifyIncomingAuth( data: MessageData, origin: string ): Promise<boolean> {
+    const cfg = this.cryptoCfg()
+    if( !cfg ) return true
+
+    if( !data.auth ){
+      return !cfg.requireSigned
+    }
+
+    const { alg, ts, nonce, sig, keyId } = data.auth
+    if( alg !== 'HMAC-SHA256' ) return false
+    if( typeof ts !== 'number' || typeof nonce !== 'string' || typeof sig !== 'string' ) return false
+
+    const now = Date.now()
+    if( Math.abs( now - ts ) > cfg.maxSkewMs ) return false
+
+    // Replay protection. The nonce is only recorded once the signature has been
+    // checked, further down: burning it here let an unsigned or badly signed
+    // message consume the nonce of a legitimate one still in flight.
+    if( this.seenNonces.has( nonce ) ) return false
+
+    const canonical = JSON.stringify({
+      v: data.v,
+      _event: data._event,
+      payload: data.payload,
+      cid: data.cid,
+      timestamp: data.timestamp,
+      size: data.size,
+      ts,
+      nonce
+    })
+
+    // Try all available secrets
+    const secrets = this.getVerificationSecrets()
+
+    for( const { secret, keyId: secretKeyId } of secrets ){
+      // If message has keyId, only try matching secret
+      if( keyId && secretKeyId && keyId !== secretKeyId ) continue
+
+      try {
+        const expected = await hmacSha256Base64Url( secret, canonical )
+        if( constantTimeEqual( expected, sig ) ){
+          this.seenNonces.set( nonce, ts )
+          this.pruneNonces( cfg.replayWindowSize )
+
+          this.debug(`[${this.peer.type}] Auth verified${keyId ? ` with key: ${keyId}` : ''}`)
+          return true
+        }
+      }
+      catch( error ){
+        this.debug(`[${this.peer.type}] Auth verification error:`, error)
+      }
+    }
+
+    return false
+  }
+
   debug( ...args: any[] ){
     this.options.debug && console.debug( ...args )
   }
@@ -194,6 +792,7 @@ export default class IOF {
 
     this.peer.connected = false
     this.stopHeartbeat()
+    this.stopSessionKeyRotation()
     this.fire('disconnect', { reason: 'CONNECTION_LOST' })
 
     this.options.autoReconnect
@@ -318,7 +917,50 @@ export default class IOF {
             || typeof data !== 'object'
             || !data.hasOwnProperty('_event') ) return
 
-        const { _event, payload, cid, timestamp } = data as Message['data']
+        const { v, _event, payload, cid, timestamp, sessionId } = data as Message['data']
+
+        // Protocol version check
+        const messageVersion = v || 1
+        if( messageVersion > PROTOCOL_VERSION ){
+          this.fire('error', {
+            type: 'UNSUPPORTED_VERSION',
+            received: messageVersion,
+            supported: PROTOCOL_VERSION
+          })
+          return
+        }
+
+        // Store peer protocol version
+        if( !this.peer.protocolVersion || this.peer.protocolVersion < messageVersion ){
+          this.peer.protocolVersion = messageVersion
+        }
+
+        /**
+         * Session key control events.
+         *
+         * These are answered before authentication — they are what establishes
+         * the key authentication will use — so they are gated on the feature
+         * actually being switched on. Without that, a peer that never enabled
+         * session keys would still derive and rotate them on request, and a
+         * malformed payload would throw out of the handler.
+         */
+        if( RESERVED_SESSION_KEY_EVENTS.includes( _event ) ){
+          if( !this.cryptoCfg()?.enableSessionKeys ){
+            this.fire('error', { type: 'SESSION_KEYS_DISABLED', event: _event, origin })
+            return
+          }
+
+          if( !payload || typeof payload !== 'object' ){
+            this.fire('error', { type: 'MALFORMED_SESSION_KEY_EVENT', event: _event, origin })
+            return
+          }
+
+          if( _event === '__session_key_init' ) this.handleSessionKeyInit( payload.sessionId )
+          else if( _event === '__session_key_ack' ) this.handleSessionKeyAck( payload )
+          else this.handleSessionKeyRotate( payload )
+
+          return
+        }
 
         // Handle heartbeat responses
         if( _event === '__heartbeat_response' ){
@@ -333,7 +975,7 @@ export default class IOF {
           return
         }
 
-        this.debug(`[${this.peer.type}] Message: ${_event}`, payload || '')
+        this.debug(`[${this.peer.type}] Message v${messageVersion}: ${_event}`, payload || '')
 
         // Handshake or availability check events
         if( _event == 'pong' ){
@@ -344,37 +986,35 @@ export default class IOF {
           
           this.startHeartbeat()
           this.fire('connect')
+          
+          // Initiate session key exchange if enabled
+          this.initiateSessionKeyExchange()
+          
           this.processMessageQueue()
           this.debug(`[${this.peer.type}] connected`)
 
           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,
-              origin
-            })
-            return
-          }
+        // Cryptographic authentication (optional)
+        if( this.options.cryptoAuth ){
+          this.verifyIncomingAuth( data as MessageData, origin )
+            .then( ok => {
+              if( !ok ){
+                this.fire('error', { type: 'AUTH_FAILED', origin, event: _event })
+                return
+              }
+
+              if( !this.acceptIncoming( _event, payload, origin ) ) return
 
-          if( this.options.validateIncoming
-              && !this.options.validateIncoming( _event, payload, origin ) ){
-            this.fire('error', {
-              type: 'INVALID_MESSAGE',
-              direction: 'incoming',
-              event: _event,
-              origin
+              this.fire( _event, payload, cid )
             })
-            return
-          }
+            .catch( error => this.fire('error', { type: 'AUTH_ERROR', origin, event: _event, error: String(error) }) )
+          return
         }
 
+        if( !this.acceptIncoming( _event, payload, origin ) ) return
+
         // Fire available event listeners
         this.fire( _event, payload, cid )
       }
@@ -442,7 +1082,50 @@ export default class IOF {
           return
         }
 
-        const { _event, payload, cid, timestamp } = data
+        const { v, _event, payload, cid, timestamp } = data
+
+        // Protocol version check
+        const messageVersion = v || 1
+        if( messageVersion > PROTOCOL_VERSION ){
+          this.fire('error', {
+            type: 'UNSUPPORTED_VERSION',
+            received: messageVersion,
+            supported: PROTOCOL_VERSION
+          })
+          return
+        }
+
+        // Store peer protocol version
+        if( !this.peer.protocolVersion || this.peer.protocolVersion < messageVersion ){
+          this.peer.protocolVersion = messageVersion
+        }
+
+        /**
+         * Session key control events.
+         *
+         * These are answered before authentication — they are what establishes
+         * the key authentication will use — so they are gated on the feature
+         * actually being switched on. Without that, a peer that never enabled
+         * session keys would still derive and rotate them on request, and a
+         * malformed payload would throw out of the handler.
+         */
+        if( RESERVED_SESSION_KEY_EVENTS.includes( _event ) ){
+          if( !this.cryptoCfg()?.enableSessionKeys ){
+            this.fire('error', { type: 'SESSION_KEYS_DISABLED', event: _event, origin })
+            return
+          }
+
+          if( !payload || typeof payload !== 'object' ){
+            this.fire('error', { type: 'MALFORMED_SESSION_KEY_EVENT', event: _event, origin })
+            return
+          }
+
+          if( _event === '__session_key_init' ) this.handleSessionKeyInit( payload.sessionId )
+          else if( _event === '__session_key_ack' ) this.handleSessionKeyAck( payload )
+          else this.handleSessionKeyRotate( payload )
+
+          return
+        }
 
         // Handle heartbeat responses
         if( _event === '__heartbeat_response' ){
@@ -457,7 +1140,7 @@ export default class IOF {
           return
         }
 
-        this.debug(`[${this.peer.type}] Message: ${_event}`, payload || '')
+        this.debug(`[${this.peer.type}] Message v${messageVersion}: ${_event}`, payload || '')
 
         // Handshake or availability check events
         if( _event == 'ping' ){
@@ -469,12 +1152,35 @@ export default class IOF {
           this.peer.lastHeartbeat = Date.now()
           this.startHeartbeat()
           this.fire('connect')
+          
+          // Initiate session key exchange if enabled
+          this.initiateSessionKeyExchange()
+          
           this.processMessageQueue()
 
           this.debug(`[${this.peer.type}] connected`)
           return
         }
 
+        // Cryptographic authentication (optional)
+        if( this.options.cryptoAuth ){
+          this.verifyIncomingAuth( data as MessageData, origin )
+            .then( ok => {
+              if( !ok ){
+                this.fire('error', { type: 'AUTH_FAILED', origin, event: _event })
+                return
+              }
+
+              if( !this.acceptIncoming( _event, payload, origin ) ) return
+
+              this.fire( _event, payload, cid )
+            })
+            .catch( error => this.fire('error', { type: 'AUTH_ERROR', origin, event: _event, error: String(error) }) )
+          return
+        }
+
+        if( !this.acceptIncoming( _event, payload, origin ) ) return
+
         // Fire available event listeners
         this.fire( _event, payload, cid )
       }
@@ -570,6 +1276,7 @@ export default class IOF {
       }
 
       const messageData = {
+        v: PROTOCOL_VERSION,
         _event,
         payload: sanitizedPayload,
         cid,
@@ -595,6 +1302,91 @@ export default class IOF {
     return this
   }
 
+  /**
+   * Send a signed message (HMAC-SHA256) when `options.cryptoAuth` is configured.
+   * This is async because WebCrypto signing is async.
+   */
+  async emitSigned<T = any>( _event: string, payload?: T | AckFunction, fn?: AckFunction ): Promise<this> {
+    // Check rate limiting
+    if( !this.checkRateLimit() ) return this
+
+    if( !this.options.cryptoAuth ){
+      // If auth not enabled, fall back to normal emit behavior
+      this.emit( _event as any, payload as any, fn )
+      return this
+    }
+
+    if( !this.isConnected() && !RESERVED_EVENTS.includes(_event) ){
+      this.queueMessage( _event, payload, fn )
+      return this
+    }
+
+    if( !this.peer.source ){
+      this.fire('error', { type: 'NO_CONNECTION', event: _event })
+      return this
+    }
+
+    if( typeof payload == 'function' ){
+      fn = payload as AckFunction
+      payload = undefined
+    }
+
+    try {
+      const sanitizedPayload = payload
+        ? sanitizePayload( payload, this.options.maxMessageSize! )
+        : payload
+
+      let cid: string | undefined
+      if( typeof fn === 'function' ){
+        const ackFunction = fn
+        cid = ackId()
+        this.once(`${_event}--${cid}--@ack`, ({ error, args }) => ackFunction( error, ...args ))
+      }
+
+      const unsigned: Omit<MessageData, 'auth'> = {
+        v: PROTOCOL_VERSION,
+        _event,
+        payload: sanitizedPayload,
+        cid,
+        timestamp: Date.now(),
+        size: getMessageSize( sanitizedPayload )
+      }
+
+      const auth = await this.signOutgoing( unsigned )
+      const messageData: MessageData = { ...unsigned, auth }
+
+      this.peer.source.postMessage( newObject( messageData ), this.peer.origin as string )
+    }
+    catch( error ){
+      this.debug(`[${this.peer.type}] EmitSigned error:`, error)
+      this.fire('error', {
+        type: 'EMIT_ERROR',
+        event: _event,
+        error: error instanceof Error ? error.message : String(error)
+      })
+      typeof fn === 'function'
+      && fn( error instanceof Error ? error.message : String(error) )
+    }
+
+    return this
+  }
+
+  async emitAsyncSigned<T = any, R = any>( _event: string, payload?: T, timeout: number = 5000 ): Promise<R> {
+    return new Promise(( resolve, reject ) => {
+      const timeoutId = setTimeout(() => reject( new Error(`Event '${_event}' acknowledgment timeout after ${timeout}ms`) ), timeout )
+
+      this.emitSigned( _event, payload as any, ( error, ...args ) => {
+        clearTimeout( timeoutId )
+        error
+          ? reject( new Error( typeof error === 'string' ? error : 'Ack error' ) )
+          : resolve( args.length === 0 ? undefined : args.length === 1 ? args[0] : args as any )
+      }).catch( err => {
+        clearTimeout( timeoutId )
+        reject( err )
+      })
+    })
+  }
+
   on( _event: string, fn: Listener ){
     // Add Event listener
     if( !this.Events[_event] ) this.Events[_event] = []
@@ -698,6 +1490,7 @@ export default class IOF {
     }
 
     this.stopHeartbeat()
+    this.stopSessionKeyRotation()
 
     if( this.reconnectTimer ){
       clearTimeout( this.reconnectTimer )
@@ -713,9 +1506,18 @@ export default class IOF {
     this.peer.source = undefined
     this.peer.origin = undefined
     this.peer.lastHeartbeat = undefined
+    this.peer.protocolVersion = undefined
+    this.peer.sessionId = undefined
+    
     this.messageQueue = []
     this.messageRateTracker = []
     this.reconnectAttempts = 0
+    
+    // Clear session keys
+    this.currentSessionKey = undefined
+    this.pendingSessionKey = undefined
+    this.previousSessionKey = undefined
+    this.mySessionId = undefined
 
     this.removeListeners()
 
@@ -735,7 +1537,11 @@ export default class IOF {
       queuedMessages: this.messageQueue.length,
       reconnectAttempts: this.reconnectAttempts,
       activeListeners: Object.keys( this.Events ).length,
-      messageRate: this.messageRateTracker.length
+      messageRate: this.messageRateTracker.length,
+      protocolVersion: PROTOCOL_VERSION,
+      peerProtocolVersion: this.peer.protocolVersion,
+      sessionKeyActive: !!this.currentSessionKey,
+      sessionKeyId: this.currentSessionKey?.keyId
     }
   }
 
@@ -747,4 +1553,4 @@ export default class IOF {
     this.debug(`[${this.peer.type}] Cleared ${queueSize} queued messages`)
     return this
   }
-}
+}