@abraca/dabra 1.0.3 → 1.0.5

package/dist/index.d.ts

@@ -941,6 +941,8 @@ interface UserProfile {
   email: string | null;
   displayName: string | null;
   role: string;
+  /** Account-level Ed25519 public key (base64url). Canonical user identity. */
+  publicKey: string | null;
 }
 interface DocumentMeta {
   id: string;
@@ -1597,11 +1599,66 @@ declare class BackgroundSyncManager extends EventEmitter {
   private _walkXml;
 }
 //#endregion
+//#region packages/provider/src/webrtc/E2EEChannel.d.ts
+interface E2EEIdentity {
+  /** Raw 32-byte Ed25519 public key. */
+  publicKey: Uint8Array;
+  /** Raw 32-byte X25519 private key. Caller must wipe after E2EEChannel.destroy(). */
+  x25519PrivateKey: Uint8Array;
+}
+declare class E2EEChannel extends EventEmitter {
+  private readonly identity;
+  private readonly docId;
+  private sessionKey;
+  private remotePublicKey;
+  private _isEstablished;
+  constructor(identity: E2EEIdentity, docId: string);
+  get isEstablished(): boolean;
+  /**
+   * Process a key-exchange message from the remote peer.
+   * Called when the `key-exchange` data channel receives a message.
+   *
+   * The message is the remote peer's raw 32-byte Ed25519 public key.
+   * After receiving it, ECDH is computed and the session key derived.
+   */
+  handleKeyExchange(remoteEdPubKey: Uint8Array): Promise<void>;
+  /**
+   * Returns the local Ed25519 public key to send to the remote peer
+   * via the `key-exchange` data channel.
+   */
+  getKeyExchangeMessage(): Uint8Array;
+  /**
+   * Encrypt a message for sending over a data channel.
+   * Returns `[12-byte nonce || AES-256-GCM ciphertext]`.
+   *
+   * @throws if the session key has not been established yet.
+   */
+  encrypt(plaintext: Uint8Array): Promise<Uint8Array>;
+  /**
+   * Decrypt a message received from a data channel.
+   * Expects `[12-byte nonce || AES-256-GCM ciphertext]`.
+   *
+   * @throws if the session key has not been established or decryption fails.
+   */
+  decrypt(data: Uint8Array): Promise<Uint8Array>;
+  /** Destroy the session key and wipe sensitive material. */
+  destroy(): void;
+  /** Sort two keys lexicographically so both peers produce the same order. */
+  private sortKeys;
+}
+//#endregion
 //#region packages/provider/src/webrtc/DataChannelRouter.d.ts
+/** Name of the data channel used for E2EE key exchange. */
+declare const KEY_EXCHANGE_CHANNEL = "key-exchange";
 declare class DataChannelRouter extends EventEmitter {
   private connection;
   private channels;
+  private encryptor;
+  /** Channels excluded from encryption (key-exchange itself, awareness). */
+  private plaintextChannels;
   constructor(connection: RTCPeerConnection);
+  /** Attach an E2EE encryptor. All channels (except key-exchange) will be encrypted. */
+  setEncryptor(encryptor: E2EEChannel): void;
   /** Create a named data channel (initiator side). */
   createChannel(name: string, options?: RTCDataChannelInit): RTCDataChannel;
   /** Create the standard set of channels for Abracadabra WebRTC. */
@@ -1610,8 +1667,21 @@ declare class DataChannelRouter extends EventEmitter {
     enableAwareness: boolean;
     enableFileTransfer: boolean;
   }): void;
+  /**
+   * Create namespaced channels for a child/subdocument.
+   * Channel names are prefixed with `{childId}:` to avoid collisions.
+   */
+  createSubdocChannels(childId: string, opts: {
+    enableDocSync: boolean;
+    enableAwareness: boolean;
+  }): void;
   getChannel(name: string): RTCDataChannel | null;
   isOpen(name: string): boolean;
+  /**
+   * Send data on a named channel, encrypting if E2EE is active.
+   * Falls back to plaintext if no encryptor is set or for exempt channels.
+   */
+  send(name: string, data: Uint8Array): Promise<void>;
   private registerChannel;
   close(): void;
   destroy(): void;
@@ -1729,6 +1799,12 @@ interface AbracadabraWebRTCConfiguration {
   docId: string;
   /** Server base URL (http/https). Signaling URL derived automatically. */
   url: string;
+  /**
+   * Override the signaling WebSocket URL. When set, signaling connects to
+   * this server instead of deriving from `url`. Useful for local spaces that
+   * piggyback a remote server's signaling endpoint.
+   */
+  signalingUrl?: string;
   /** JWT token or async token factory. */
   token: string | (() => string) | (() => Promise<string>);
   /** Optional Y.Doc to sync over data channels (hybrid mode). */
@@ -1751,6 +1827,12 @@ interface AbracadabraWebRTCConfiguration {
   fileChunkSize?: number;
   /** Auto-connect on construction. Default: true. */
   autoConnect?: boolean;
+  /**
+   * E2EE identity for application-level encryption on data channels.
+   * When provided, all data channel messages (except key-exchange) are
+   * encrypted with AES-256-GCM using X25519 ECDH-derived session keys.
+   */
+  e2ee?: E2EEIdentity;
   /** WebSocket polyfill for signaling (e.g. for Node.js). */
   WebSocketPolyfill?: any;
 }
@@ -1809,6 +1891,7 @@ declare class AbracadabraWebRTC extends EventEmitter {
   private peerConnections;
   private yjsChannels;
   private fileChannels;
+  private e2eeChannels;
   private readonly config;
   readonly peers: Map<string, PeerState>;
   localPeerId: string | null;
@@ -1846,6 +1929,7 @@ declare class AbracadabraWebRTC extends EventEmitter {
   private removeAllPeers;
   private createPeerConnection;
   private attachDataHandlers;
+  private startDataSync;
   private initiateConnection;
   private handleOffer;
   private buildSignalingUrl;
@@ -1940,7 +2024,16 @@ declare class YjsDataChannel {
   private awarenessUpdateHandler;
   private channelOpenHandler;
   private channelMessageHandler;
-  constructor(document: Y.Doc, awareness: Awareness | null, router: DataChannelRouter);
+  /** Channel names used for sync and awareness (supports namespaced subdoc channels). */
+  private readonly syncChannelName;
+  private readonly awarenessChannelName;
+  /**
+   * @param document - The Y.Doc to sync
+   * @param awareness - Optional Awareness instance
+   * @param router - DataChannelRouter for the peer connection
+   * @param channelPrefix - Optional prefix for subdocument channels (e.g. `"{childId}:"`)
+   */
+  constructor(document: Y.Doc, awareness: Awareness | null, router: DataChannelRouter, channelPrefix?: string);
   /** Start listening for Y.js updates and data channel messages. */
   attach(): void;
   /** Stop listening and clean up handlers. */
@@ -1951,4 +2044,74 @@ declare class YjsDataChannel {
   private handleAwarenessMessage;
 }
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, CHANNEL_NAMES, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EOfflineStore, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, InviteRow, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, decryptField, encryptField, makeEncryptedYMap, makeEncryptedYText, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+//#region packages/provider/src/webrtc/ManualSignaling.d.ts
+interface ManualSignalingBlob {
+  /** SDP offer or answer. */
+  sdp: string;
+  /** Gathered ICE candidates. */
+  candidates: string[];
+  /** Peer ID of the sender. */
+  peerId: string;
+}
+declare class ManualSignaling extends EventEmitter {
+  localPeerId: string;
+  isConnected: boolean;
+  private pc;
+  private iceServers;
+  constructor(iceServers?: RTCIceServer[]);
+  /**
+   * Initiator: create an offer blob with gathered ICE candidates.
+   * Returns a blob to share with the remote peer.
+   */
+  createOfferBlob(): Promise<ManualSignalingBlob>;
+  /**
+   * Responder: accept an offer blob and create an answer blob.
+   * The answer blob should be shared back to the initiator.
+   */
+  acceptOffer(offerBlob: ManualSignalingBlob): Promise<ManualSignalingBlob>;
+  /**
+   * Initiator: accept the answer blob from the responder.
+   * Completes the connection.
+   */
+  acceptAnswer(answerBlob: ManualSignalingBlob): Promise<void>;
+  sendOffer(_to: string, _sdp: string): void;
+  sendAnswer(_to: string, _sdp: string): void;
+  sendIce(_to: string, _candidate: string): void;
+  sendMute(_muted: boolean): void;
+  sendMediaState(_video: boolean, _screen: boolean): void;
+  sendProfile(_name: string, _color: string): void;
+  sendLeave(): void;
+  connect(): Promise<void>;
+  disconnect(): void;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/sync/BroadcastChannelSync.d.ts
+declare class BroadcastChannelSync extends EventEmitter {
+  private readonly document;
+  private readonly awareness;
+  private readonly channelName;
+  private channel;
+  private docUpdateHandler;
+  private awarenessUpdateHandler;
+  private destroyed;
+  constructor(document: Y.Doc, awareness: Awareness | null, channelName: string);
+  /** Convenience factory using standard channel naming. */
+  static forDoc(document: Y.Doc, docId: string, awareness?: Awareness | null): BroadcastChannelSync;
+  /** Start syncing. Opens the BroadcastChannel and initiates a sync handshake. */
+  connect(): void;
+  /** Stop syncing and close the BroadcastChannel. */
+  disconnect(): void;
+  /** Disconnect and prevent reconnection. */
+  destroy(): void;
+  private broadcastUpdate;
+  private broadcastAwareness;
+  private sendSyncStep1;
+  private broadcastQueryPeers;
+  private handleMessage;
+  private handleSyncMessage;
+  private handleUpdateMessage;
+  private handleAwarenessMessage;
+}
+//#endregion
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, decryptField, encryptField, makeEncryptedYMap, makeEncryptedYText, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraProvider.ts

@@ -442,19 +442,18 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		const childDoc = new Y.Doc({ guid: childId });
 
 		// Fire-and-forget: tell the server this child belongs to the parent.
-		// The child provider's own WebSocket handshake (TCP + TLS + auth) is
-		// slow enough that the server will have processed the registration
-		// before the child's first SyncStep1 arrives.  In the rare race the
-		// child's built-in reconnect logic retries automatically.
 		this.registerSubdoc(childDoc);
 
-		// Each child gets its own WebSocket connection.  Omitting
-		// websocketProvider lets AbracadabraBaseProvider create one automatically
-		// (manageSocket = true), so we do NOT call attach() manually.
+		// Reuse the parent's WebSocket for multiplexing — all children share a
+		// single TCP connection instead of each opening its own.  The shared
+		// AbracadabraWS demuxes frames by documentName, so each child provider
+		// still syncs independently.  Because we pass websocketProvider the
+		// child's manageSocket will be false, meaning destroy() detaches
+		// without tearing down the shared connection.
 		const childProvider = new AbracadabraProvider({
 			name: childId,
 			document: childDoc,
-			url: this.abracadabraConfig.url ?? this.configuration.websocketProvider?.url,
+			websocketProvider: this.configuration.websocketProvider,
 			token: this.configuration.token,
 			subdocLoading: this.subdocLoading,
 			disableOfflineStore: this.abracadabraConfig.disableOfflineStore,
@@ -465,6 +464,10 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			keystore: this.abracadabraConfig.keystore,
 		});
 
+		// Shared websocketProvider means manageSocket is false, so the base
+		// class constructor skips auto-attach.  Attach explicitly.
+		childProvider.attach();
+
 		this.childProviders.set(childId, childProvider);
 
 		this.emit("subdocLoaded", { childId, provider: childProvider });

package/src/AbracadabraWS.ts

@@ -512,7 +512,7 @@ export class AbracadabraWS extends EventEmitter {
 
     // Detect server-side rate-limit close (code 4429).
     // `event` may be a CloseEvent (browser) with `.code`, or a raw number (ws/Node.js).
-    console.log('[DEBUG] onClose event:', typeof event, JSON.stringify(event), 'code:', (event as any)?.code);
+    // `event` may be a CloseEvent (browser) with `.code`, or a raw number (ws/Node.js).
     const isRateLimited = (event as any)?.code === 4429 || event === 4429;
     this.emit("disconnect", { event });
     if (isRateLimited) {

package/src/index.ts

@@ -24,3 +24,4 @@ export type { BackgroundSyncManagerOptions } from "./BackgroundSyncManager.ts";
 export { BackgroundSyncPersistence } from "./BackgroundSyncPersistence.ts";
 export type { DocSyncState } from "./BackgroundSyncPersistence.ts";
 export * from "./webrtc/index.ts";
+export { BroadcastChannelSync } from "./sync/BroadcastChannelSync.ts";

package/src/sync/BroadcastChannelSync.ts

@@ -0,0 +1,235 @@
+import * as Y from "yjs";
+import * as syncProtocol from "y-protocols/sync";
+import {
+	encodeAwarenessUpdate,
+	applyAwarenessUpdate,
+	type Awareness,
+} from "y-protocols/awareness";
+import * as encoding from "lib0/encoding";
+import * as decoding from "lib0/decoding";
+import EventEmitter from "../EventEmitter.ts";
+
+/**
+ * Cross-tab Y.js document and awareness sync via the BroadcastChannel API.
+ *
+ * Opens a BroadcastChannel per document, relays Y.js updates and awareness
+ * state between tabs on the same origin. No server, no WebRTC — just same-device
+ * multi-tab sync. Same-origin means same trust boundary, so no encryption needed.
+ *
+ * Uses the same y-protocols/sync encoding as `YjsDataChannel` for consistency.
+ */
+
+const CHANNEL_PREFIX = "abra:sync:";
+
+/** Message type discriminators (first byte). */
+const MSG = {
+	SYNC: 0x00,
+	UPDATE: 0x01,
+	AWARENESS: 0x02,
+	/** Request all tabs to respond with SyncStep1. */
+	QUERY_PEERS: 0x03,
+} as const;
+
+export class BroadcastChannelSync extends EventEmitter {
+	private channel: BroadcastChannel | null = null;
+	private docUpdateHandler: ((update: Uint8Array, origin: any) => void) | null =
+		null;
+	private awarenessUpdateHandler:
+		| ((
+				changes: { added: number[]; updated: number[]; removed: number[] },
+				origin: any,
+			) => void)
+		| null = null;
+	private destroyed = false;
+
+	constructor(
+		private readonly document: Y.Doc,
+		private readonly awareness: Awareness | null,
+		private readonly channelName: string,
+	) {
+		super();
+	}
+
+	/** Convenience factory using standard channel naming. */
+	static forDoc(
+		document: Y.Doc,
+		docId: string,
+		awareness?: Awareness | null,
+	): BroadcastChannelSync {
+		return new BroadcastChannelSync(
+			document,
+			awareness ?? null,
+			`${CHANNEL_PREFIX}${docId}`,
+		);
+	}
+
+	/** Start syncing. Opens the BroadcastChannel and initiates a sync handshake. */
+	connect(): void {
+		if (this.destroyed || this.channel) return;
+
+		if (typeof globalThis.BroadcastChannel === "undefined") {
+			// Environment doesn't support BroadcastChannel (e.g. some Node.js builds).
+			return;
+		}
+
+		this.channel = new BroadcastChannel(this.channelName);
+		this.channel.onmessage = (event) => this.handleMessage(event.data);
+
+		// Listen for local doc updates → broadcast to other tabs.
+		this.docUpdateHandler = (update: Uint8Array, origin: any) => {
+			if (origin === this) return; // Don't echo.
+			this.broadcastUpdate(update);
+		};
+		this.document.on("update", this.docUpdateHandler);
+
+		// Listen for local awareness changes → broadcast to other tabs.
+		if (this.awareness) {
+			this.awarenessUpdateHandler = (
+				{
+					added,
+					updated,
+					removed,
+				}: { added: number[]; updated: number[]; removed: number[] },
+				_origin: any,
+			) => {
+				const changedClients = added.concat(updated).concat(removed);
+				const update = encodeAwarenessUpdate(this.awareness!, changedClients);
+				this.broadcastAwareness(update);
+			};
+			this.awareness.on("update", this.awarenessUpdateHandler);
+		}
+
+		// Announce presence — other tabs reply with SyncStep1.
+		this.broadcastQueryPeers();
+
+		// Send our SyncStep1 to trigger state exchange.
+		this.sendSyncStep1();
+
+		this.emit("connected");
+	}
+
+	/** Stop syncing and close the BroadcastChannel. */
+	disconnect(): void {
+		if (this.docUpdateHandler) {
+			this.document.off("update", this.docUpdateHandler);
+			this.docUpdateHandler = null;
+		}
+		if (this.awarenessUpdateHandler && this.awareness) {
+			this.awareness.off("update", this.awarenessUpdateHandler);
+			this.awarenessUpdateHandler = null;
+		}
+		if (this.channel) {
+			this.channel.close();
+			this.channel = null;
+		}
+		this.emit("disconnected");
+	}
+
+	/** Disconnect and prevent reconnection. */
+	destroy(): void {
+		this.disconnect();
+		this.destroyed = true;
+		this.removeAllListeners();
+	}
+
+	// ── Outgoing ────────────────────────────────────────────────────────────
+
+	private broadcastUpdate(update: Uint8Array): void {
+		if (!this.channel) return;
+		const encoder = encoding.createEncoder();
+		encoding.writeVarUint(encoder, MSG.UPDATE);
+		encoding.writeVarUint8Array(encoder, update);
+		this.channel.postMessage(encoding.toUint8Array(encoder));
+	}
+
+	private broadcastAwareness(update: Uint8Array): void {
+		if (!this.channel) return;
+		const encoder = encoding.createEncoder();
+		encoding.writeVarUint(encoder, MSG.AWARENESS);
+		encoding.writeVarUint8Array(encoder, update);
+		this.channel.postMessage(encoding.toUint8Array(encoder));
+	}
+
+	private sendSyncStep1(): void {
+		if (!this.channel) return;
+		const encoder = encoding.createEncoder();
+		encoding.writeVarUint(encoder, MSG.SYNC);
+		syncProtocol.writeSyncStep1(encoder, this.document);
+		this.channel.postMessage(encoding.toUint8Array(encoder));
+	}
+
+	private broadcastQueryPeers(): void {
+		if (!this.channel) return;
+		const encoder = encoding.createEncoder();
+		encoding.writeVarUint(encoder, MSG.QUERY_PEERS);
+		this.channel.postMessage(encoding.toUint8Array(encoder));
+	}
+
+	// ── Incoming ────────────────────────────────────────────────────────────
+
+	private handleMessage(data: any): void {
+		if (!(data instanceof ArrayBuffer || data instanceof Uint8Array)) return;
+		const buf = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+		const decoder = decoding.createDecoder(buf);
+		const msgType = decoding.readVarUint(decoder);
+
+		switch (msgType) {
+			case MSG.SYNC:
+				this.handleSyncMessage(decoder);
+				break;
+			case MSG.UPDATE:
+				this.handleUpdateMessage(decoder);
+				break;
+			case MSG.AWARENESS:
+				this.handleAwarenessMessage(decoder);
+				break;
+			case MSG.QUERY_PEERS:
+				// Another tab joined — respond with our SyncStep1.
+				this.sendSyncStep1();
+				if (this.awareness) {
+					const update = encodeAwarenessUpdate(
+						this.awareness,
+						Array.from(this.awareness.getStates().keys()),
+					);
+					this.broadcastAwareness(update);
+				}
+				break;
+		}
+	}
+
+	private handleSyncMessage(decoder: decoding.Decoder): void {
+		const encoder = encoding.createEncoder();
+		const syncMessageType = syncProtocol.readSyncMessage(
+			decoder,
+			encoder,
+			this.document,
+			this,
+		);
+
+		// If the sync protocol generated a response (SyncStep2), broadcast it.
+		if (encoding.length(encoder) > 0) {
+			const responseEncoder = encoding.createEncoder();
+			encoding.writeVarUint(responseEncoder, MSG.SYNC);
+			encoding.writeUint8Array(
+				responseEncoder,
+				encoding.toUint8Array(encoder),
+			);
+			this.channel?.postMessage(encoding.toUint8Array(responseEncoder));
+		}
+
+		if (syncMessageType === syncProtocol.messageYjsSyncStep2) {
+			this.emit("synced");
+		}
+	}
+
+	private handleUpdateMessage(decoder: decoding.Decoder): void {
+		const update = decoding.readVarUint8Array(decoder);
+		Y.applyUpdate(this.document, update, this);
+	}
+
+	private handleAwarenessMessage(decoder: decoding.Decoder): void {
+		if (!this.awareness) return;
+		const update = decoding.readVarUint8Array(decoder);
+		applyAwarenessUpdate(this.awareness, update, this);
+	}
+}

package/src/types.ts

@@ -166,6 +166,8 @@ export interface UserProfile {
   email: string | null;
   displayName: string | null;
   role: string;
+  /** Account-level Ed25519 public key (base64url). Canonical user identity. */
+  publicKey: string | null;
 }
 
 export interface DocumentMeta {