feat(collaboration): add peer metadata and WebSocket authentication support

- Add peer metadata system to PeerMessagingActor (localMetadata, peerMetadata)
- Add setLocalMetadata and updatePeerMetadata actions
- Add metadataChanged event for tracking peer metadata updates
- Add WebSocketAuthConfig supporting credentials, query params, and auth payload
- Add connectionError event for handling auth failures with error data
- Clean up metadata automatically when peers disconnect

Author: d-buckner

packages/collaboration/src/PeerMessagingActor.ts

@@ -2,6 +2,7 @@ import { Actor, action, effect, type IActorClient } from '@d-buckner/ensemble-co
 import type {
   PeerMessagingState,
   PeerMessagingEvents,
+  PeerMetadata,
   MessagePayload,
   SignalingPayload,
   RoomJoinedPayload,
@@ -20,6 +21,8 @@ export interface PeerMessagingDeps {
 export interface PeerMessagingActions {
   sendTo(peerId: string, message: Uint8Array): void;
   broadcast(message: Uint8Array): void;
+  setLocalMetadata(metadata: PeerMetadata): void;
+  updatePeerMetadata(peerId: string, metadata: PeerMetadata): void;
 }
 
 /**
@@ -41,6 +44,8 @@ export class PeerMessagingActor extends Actor<PeerMessagingState, PeerMessagingA
   static readonly initialState: PeerMessagingState = {
     connectedPeers: [],
     peerTransports: {},
+    peerMetadata: {},
+    localMetadata: null,
   };
 
   protected declare deps: PeerMessagingDeps;
@@ -102,6 +107,39 @@ export class PeerMessagingActor extends Actor<PeerMessagingState, PeerMessagingA
     }
   }
 
+  // ========================================
+  // Actions: Metadata management
+  // ========================================
+
+  /**
+   * Set metadata for the local user.
+   * This metadata can be shared with peers when they connect.
+   *
+   * @param metadata - Metadata object (displayName, instrument, color, etc.)
+   */
+  @action
+  setLocalMetadata(metadata: PeerMetadata): void {
+    this.setState(draft => {
+      draft.localMetadata = metadata;
+    });
+  }
+
+  /**
+   * Update metadata for a specific peer.
+   * Typically called when receiving metadata updates from the network.
+   *
+   * @param peerId - ID of the peer
+   * @param metadata - Metadata object for the peer
+   */
+  @action
+  updatePeerMetadata(peerId: string, metadata: PeerMetadata): void {
+    this.setState(draft => {
+      draft.peerMetadata[peerId] = metadata;
+    });
+
+    this.emit('metadataChanged', { peerId, metadata });
+  }
+
   // ========================================
   // Effects: WebSocket events
   // ========================================
@@ -161,7 +199,7 @@ export class PeerMessagingActor extends Actor<PeerMessagingState, PeerMessagingA
   /**
    * Handle peer left via WebSocket.
    * Removes peer from state and emits peerDisconnected.
-   * Also disconnects WebRTC connection.
+   * Also disconnects WebRTC connection and cleans up metadata.
    */
   @effect('websocket.peerLeft')
   private handleWebSocketPeerLeft(peerId: string): void {
@@ -172,6 +210,7 @@ export class PeerMessagingActor extends Actor<PeerMessagingState, PeerMessagingA
     this.setState(draft => {
       draft.connectedPeers = draft.connectedPeers.filter(id => id !== peerId);
       delete draft.peerTransports[peerId];
+      delete draft.peerMetadata[peerId];
     });
 
     // Disconnect WebRTC

packages/collaboration/src/WebSocketActor.ts

@@ -4,6 +4,7 @@ import type {
   WebSocketState,
   WebSocketEvents,
   WebSocketConfig,
+  WebSocketAuthConfig,
 } from './types';
 import type { SignalData } from '@d-buckner/peer-pressure';
 
@@ -36,6 +37,7 @@ export class WebSocketActor extends Actor<WebSocketState, WebSocketActions, WebS
     roomId: '',
     peerId: null,
     connectionState: 'disconnected',
+    authConfig: null,
   };
 
   private socket: Socket | null = null;
@@ -51,13 +53,14 @@ export class WebSocketActor extends Actor<WebSocketState, WebSocketActions, WebS
    * Initialize the WebSocket connection configuration.
    * Must be called before connect().
    *
-   * @param config - Configuration with Socket.IO URL and room ID
+   * @param config - Configuration with Socket.IO URL, room ID, and optional auth
    */
   @action
   initialize(config: WebSocketConfig): void {
     this.setState(draft => {
       draft.url = config.url;
       draft.roomId = config.roomId;
+      draft.authConfig = config.authConfig ?? null;
     });
   }
 
@@ -68,6 +71,11 @@ export class WebSocketActor extends Actor<WebSocketState, WebSocketActions, WebS
   /**
    * Connect to Socket.IO server and join room.
    * Server will assign a unique peer ID and return list of existing peers.
+   *
+   * Uses auth configuration if provided during initialize():
+   * - withCredentials: Include cookies for session-based auth
+   * - query: Custom query parameters (displayName, etc.)
+   * - auth: Socket.IO auth payload (token-based auth)
    */
   @action
   connect(): void {
@@ -84,14 +92,33 @@ export class WebSocketActor extends Actor<WebSocketState, WebSocketActions, WebS
     });
     this.emit('connectionStateChanged', 'connecting');
 
+    const authConfig = this.state.authConfig;
     this.socket = io(this.state.url, {
       autoConnect: false,
+      withCredentials: authConfig?.withCredentials ?? false,
+      query: authConfig?.query,
+      auth: this.buildAuthPayload(authConfig),
     });
 
     this.setupSocketListeners();
     this.socket.connect();
   }
 
+  /**
+   * Build the auth payload for Socket.IO from auth config.
+   */
+  private buildAuthPayload(authConfig: WebSocketAuthConfig | null): Record<string, unknown> | undefined {
+    if (!authConfig?.auth) {
+      return undefined;
+    }
+
+    if (typeof authConfig.auth === 'string') {
+      return { token: authConfig.auth };
+    }
+
+    return authConfig.auth;
+  }
+
   /**
    * Leave the current room and disconnect from server.
    */
@@ -231,12 +258,13 @@ export class WebSocketActor extends Actor<WebSocketState, WebSocketActions, WebS
     });
 
     // Error handling
-    this.socket.on('connect_error', (error: Error) => {
+    this.socket.on('connect_error', (error: Error & { data?: unknown }) => {
       console.error('[WebSocketActor] Connection error:', error.message);
+      this.emit('connectionError', { message: error.message, data: error.data });
       this.throw('Socket.IO connection error', { error: error.message });
     });
 
-    this.socket.on('error', (error: any) => {
+    this.socket.on('error', (error: unknown) => {
       console.error('[WebSocketActor] Server error:', error);
     });
   }

packages/collaboration/src/__tests__/PeerMessagingActor.test.ts

@@ -1,5 +1,5 @@
 import { ActorSystem, createActorToken } from '@d-buckner/ensemble-core';
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { PeerMessagingActor } from '../PeerMessagingActor';
 import { WebRTCActor } from '../WebRTCActor';
 import { WebSocketActor } from '../WebSocketActor';
@@ -173,4 +173,85 @@ describe('PeerMessagingActor', () => {
     });
   });
 
+  describe('Peer Metadata', () => {
+    it('should start with empty peerMetadata and null localMetadata', () => {
+      const client = system.getClient(PeerMessagingToken)!;
+
+      expect(client.state.peerMetadata).toEqual({});
+      expect(client.state.localMetadata).toBeNull();
+    });
+
+    it('should set local metadata', async () => {
+      const client = system.getClient(PeerMessagingToken)!;
+
+      client.actions.setLocalMetadata({ displayName: 'TestUser', instrument: 'piano' });
+      await flushMicrotask();
+
+      expect(client.state.localMetadata).toEqual({
+        displayName: 'TestUser',
+        instrument: 'piano',
+      });
+    });
+
+    it('should update local metadata with new values', async () => {
+      const client = system.getClient(PeerMessagingToken)!;
+
+      client.actions.setLocalMetadata({ displayName: 'User1' });
+      await flushMicrotask();
+
+      client.actions.setLocalMetadata({ displayName: 'User2', color: 'blue' });
+      await flushMicrotask();
+
+      expect(client.state.localMetadata).toEqual({
+        displayName: 'User2',
+        color: 'blue',
+      });
+    });
+
+    it('should update peer metadata', async () => {
+      const client = system.getClient(PeerMessagingToken)!;
+
+      client.actions.updatePeerMetadata('peer-123', { displayName: 'RemoteUser', instrument: 'synth' });
+      await flushMicrotask();
+
+      expect(client.state.peerMetadata['peer-123']).toEqual({
+        displayName: 'RemoteUser',
+        instrument: 'synth',
+      });
+    });
+
+    it('should update metadata for multiple peers', async () => {
+      const client = system.getClient(PeerMessagingToken)!;
+
+      client.actions.updatePeerMetadata('peer-1', { displayName: 'Alice' });
+      client.actions.updatePeerMetadata('peer-2', { displayName: 'Bob' });
+      await flushMicrotask();
+
+      expect(client.state.peerMetadata['peer-1']).toEqual({ displayName: 'Alice' });
+      expect(client.state.peerMetadata['peer-2']).toEqual({ displayName: 'Bob' });
+    });
+
+    it('should emit metadataChanged event when updating peer metadata', async () => {
+      const client = system.getClient(PeerMessagingToken)!;
+      const metadataHandler = vi.fn();
+
+      client.on('metadataChanged', metadataHandler);
+
+      client.actions.updatePeerMetadata('peer-123', { displayName: 'TestUser' });
+      await flushMicrotask();
+
+      expect(metadataHandler).toHaveBeenCalledWith({
+        peerId: 'peer-123',
+        metadata: { displayName: 'TestUser' },
+      });
+    });
+
+    it('should handle empty metadata object', async () => {
+      const client = system.getClient(PeerMessagingToken)!;
+
+      expect(() => client.actions.setLocalMetadata({})).not.toThrow();
+      expect(() => client.actions.updatePeerMetadata('peer-1', {})).not.toThrow();
+    });
+  });
+
 });