@abraca/dabra 1.0.23 → 1.0.25

package/dist/index.d.ts

@@ -2396,6 +2396,23 @@ interface IdentityServerEntry {
   spacesEnabled?: boolean;
   addedAt: number;
 }
+type DeviceTier = "master" | "paired";
+interface DeviceServerStatus {
+  registered: boolean;
+  registeredAt: number | null;
+  keyId: string | null;
+  lastVerifiedAt: number | null;
+  error: string | null;
+}
+interface IdentityDeviceEntry {
+  deviceName: string;
+  tier: DeviceTier;
+  x25519Key: string | null;
+  addedAt: number;
+  revokedAt: number | null;
+  revokedBy: string | null;
+  servers: Map<string, DeviceServerStatus>;
+}
 interface IdentitySpaceEntry {
   id: string;
   name: string;
@@ -2481,6 +2498,7 @@ declare class IdentityDocProvider extends EventEmitter {
   get serversMap(): Y.Map<Y.Map<any>>;
   get spacesArray(): Y.Array<Y.Map<any>>;
   get pluginsMap(): Y.Map<any>;
+  get devicesMap(): Y.Map<Y.Map<any>>;
   get preferencesMap(): Y.Map<any>;
   getProfile(): IdentityProfile;
   setProfile(profile: Partial<IdentityProfile>): void;
@@ -2496,11 +2514,22 @@ declare class IdentityDocProvider extends EventEmitter {
   getDisabledBuiltins(): Y.Array<string>;
   getPreference<T = any>(key: string): T | undefined;
   setPreference(key: string, value: any): void;
+  getDevice(publicKey: string): IdentityDeviceEntry | undefined;
+  getDevices(): Map<string, IdentityDeviceEntry>;
+  addDevice(publicKey: string, opts: {
+    deviceName: string;
+    tier: DeviceTier;
+    x25519Key?: string;
+    serverUrl?: string;
+    keyId?: string;
+  }): void;
+  revokeDevice(publicKey: string, revokedBy: string): void;
+  setDeviceServerStatus(devicePubKey: string, serverUrl: string, status: Partial<DeviceServerStatus>): void;
   /**
    * Observe deep changes on a specific top-level map.
    * Returns an unsubscribe function.
    */
-  observe(mapName: "profile" | "servers" | "plugins" | "preferences", callback: (events: Y.YEvent<any>[], transaction: Y.Transaction) => void): () => void;
+  observe(mapName: "profile" | "servers" | "plugins" | "preferences" | "devices", callback: (events: Y.YEvent<any>[], transaction: Y.Transaction) => void): () => void;
   /**
    * Observe changes to the spaces array.
    * Returns an unsubscribe function.
@@ -2520,4 +2549,60 @@ declare class IdentityDocProvider extends EventEmitter {
   destroy(): void;
 }
 //#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, DevicePairingChannel, type DevicePairingConfig, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, 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, deriveIdentityDocId, 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/DeviceRegistrationService.d.ts
+interface FanOutResult {
+  serverUrl: string;
+  success: boolean;
+  error?: string;
+}
+/**
+ * Handles cross-server device key registration and revocation propagation.
+ *
+ * All methods operate on the identity Y.Doc's `devicesMap` and authenticate
+ * independently on each server using the master key's `signChallenge`.
+ */
+declare class DeviceRegistrationService {
+  /**
+   * Fan out a device key to all servers in `serversMap` where it isn't registered.
+   *
+   * Must be called from a master device that can sign challenges with the
+   * account-level private key.
+   */
+  static fanOutDeviceKey(opts: {
+    devicePubKey: string;
+    x25519Key?: string;
+    deviceName?: string;
+    identityDoc: IdentityDocProvider;
+    masterPubKey: string;
+    signChallenge: (challenge: string) => Promise<string>;
+    skipServerUrl?: string;
+  }): Promise<FanOutResult[]>;
+  /**
+   * Propagate pending revocations from the identity Y.Doc to all servers.
+   *
+   * Scans `devicesMap` for entries with `revokedAt` set and revokes them
+   * on every server where they're still registered. Must be called from
+   * a master device.
+   */
+  static propagateRevocations(opts: {
+    identityDoc: IdentityDocProvider;
+    masterPubKey: string;
+    signChallenge: (challenge: string) => Promise<string>;
+  }): Promise<FanOutResult[]>;
+  /**
+   * Reconcile the identity Y.Doc's `devicesMap` with a server's actual
+   * device key list. Call this on every server connection.
+   *
+   * - Updates registration status in Y.Doc to match server reality
+   * - Imports unknown server keys as legacy entries
+   * - Executes pending revocations if the caller is a master device
+   */
+  static reconcile(opts: {
+    identityDoc: IdentityDocProvider;
+    serverUrl: string;
+    client: AbracadabraClient;
+    isMaster: boolean;
+  }): Promise<void>;
+}
+//#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, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, 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, deriveIdentityDocId, 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.23",
+  "version": "1.0.25",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/DeviceRegistrationService.ts

@@ -0,0 +1,243 @@
+import type * as Y from "yjs";
+import { AbracadabraClient } from "./AbracadabraClient.ts";
+import type { IdentityDocProvider } from "./IdentityDoc.ts";
+import type { PublicKeyInfo } from "./types.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface FanOutResult {
+	serverUrl: string;
+	success: boolean;
+	error?: string;
+}
+
+// ── DeviceRegistrationService ────────────────────────────────────────────────
+
+/**
+ * Handles cross-server device key registration and revocation propagation.
+ *
+ * All methods operate on the identity Y.Doc's `devicesMap` and authenticate
+ * independently on each server using the master key's `signChallenge`.
+ */
+export class DeviceRegistrationService {
+	/**
+	 * Fan out a device key to all servers in `serversMap` where it isn't registered.
+	 *
+	 * Must be called from a master device that can sign challenges with the
+	 * account-level private key.
+	 */
+	static async fanOutDeviceKey(opts: {
+		devicePubKey: string;
+		x25519Key?: string;
+		deviceName?: string;
+		identityDoc: IdentityDocProvider;
+		masterPubKey: string;
+		signChallenge: (challenge: string) => Promise<string>;
+		skipServerUrl?: string;
+	}): Promise<FanOutResult[]> {
+		const {
+			devicePubKey,
+			x25519Key,
+			deviceName,
+			identityDoc,
+			masterPubKey,
+			signChallenge,
+			skipServerUrl,
+		} = opts;
+
+		const servers = identityDoc.getServers();
+		const results: FanOutResult[] = [];
+
+		// Ensure the device entry exists in devicesMap
+		if (!identityDoc.getDevice(devicePubKey)) {
+			identityDoc.addDevice(devicePubKey, {
+				deviceName: deviceName ?? "Unknown",
+				tier: "paired",
+				x25519Key,
+			});
+		}
+
+		for (const [serverUrl] of servers) {
+			if (skipServerUrl && serverUrl === skipServerUrl) continue;
+
+			// Check if already registered on this server
+			const device = identityDoc.getDevice(devicePubKey);
+			const serverStatus = device?.servers.get(serverUrl);
+			if (serverStatus?.registered) continue;
+
+			try {
+				const client = new AbracadabraClient({ url: serverUrl });
+				await client.loginWithKey(masterPubKey, signChallenge);
+				await client.addKey({
+					publicKey: devicePubKey,
+					x25519Key,
+					deviceName,
+				});
+
+				// Get the keyId from the server for future revocation
+				const keys = await client.listKeys();
+				const match = keys.find(
+					(k) => k.publicKey === devicePubKey && !k.revoked,
+				);
+
+				identityDoc.setDeviceServerStatus(devicePubKey, serverUrl, {
+					registered: true,
+					registeredAt: Date.now(),
+					keyId: match?.id ?? null,
+					lastVerifiedAt: Date.now(),
+					error: null,
+				});
+
+				results.push({ serverUrl, success: true });
+			} catch (e: any) {
+				identityDoc.setDeviceServerStatus(devicePubKey, serverUrl, {
+					error: e?.message ?? "Registration failed",
+				});
+				results.push({
+					serverUrl,
+					success: false,
+					error: e?.message ?? "Registration failed",
+				});
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Propagate pending revocations from the identity Y.Doc to all servers.
+	 *
+	 * Scans `devicesMap` for entries with `revokedAt` set and revokes them
+	 * on every server where they're still registered. Must be called from
+	 * a master device.
+	 */
+	static async propagateRevocations(opts: {
+		identityDoc: IdentityDocProvider;
+		masterPubKey: string;
+		signChallenge: (challenge: string) => Promise<string>;
+	}): Promise<FanOutResult[]> {
+		const { identityDoc, masterPubKey, signChallenge } = opts;
+		const devices = identityDoc.getDevices();
+		const results: FanOutResult[] = [];
+
+		for (const [devicePubKey, device] of devices) {
+			if (!device.revokedAt) continue;
+
+			for (const [serverUrl, serverStatus] of device.servers) {
+				if (!serverStatus.registered || !serverStatus.keyId) continue;
+
+				try {
+					const client = new AbracadabraClient({ url: serverUrl });
+					await client.loginWithKey(masterPubKey, signChallenge);
+					await client.revokeKey(serverStatus.keyId);
+
+					identityDoc.setDeviceServerStatus(
+						devicePubKey,
+						serverUrl,
+						{
+							registered: false,
+							error: null,
+						},
+					);
+					results.push({ serverUrl, success: true });
+				} catch (e: any) {
+					results.push({
+						serverUrl,
+						success: false,
+						error: e?.message ?? "Revocation failed",
+					});
+				}
+			}
+		}
+
+		return results;
+	}
+
+	/**
+	 * Reconcile the identity Y.Doc's `devicesMap` with a server's actual
+	 * device key list. Call this on every server connection.
+	 *
+	 * - Updates registration status in Y.Doc to match server reality
+	 * - Imports unknown server keys as legacy entries
+	 * - Executes pending revocations if the caller is a master device
+	 */
+	static async reconcile(opts: {
+		identityDoc: IdentityDocProvider;
+		serverUrl: string;
+		client: AbracadabraClient;
+		isMaster: boolean;
+	}): Promise<void> {
+		const { identityDoc, serverUrl, client, isMaster } = opts;
+
+		let serverKeys: PublicKeyInfo[];
+		try {
+			serverKeys = await client.listKeys();
+		} catch {
+			return; // Server unreachable or auth issue — skip reconciliation
+		}
+
+		const devicesMap = identityDoc.devicesMap;
+
+		// 1. Verify Y.Doc matches server reality
+		devicesMap.forEach((yEntry, devicePub) => {
+			const serversYMap = yEntry.get("servers") as
+				| Y.Map<Y.Map<any>>
+				| undefined;
+			const serverEntry = serversYMap?.get(serverUrl);
+			const serverKey = serverKeys.find((k) => k.publicKey === devicePub);
+			const revokedAt = yEntry.get("revokedAt");
+
+			if (serverEntry?.get("registered") && !serverKey) {
+				// Y.Doc thinks registered but server doesn't have it
+				identityDoc.setDeviceServerStatus(devicePub, serverUrl, {
+					registered: false,
+					keyId: null,
+				});
+			}
+
+			if (serverKey && !serverKey.revoked) {
+				// Server has it — update Y.Doc if needed
+				if (!serverEntry?.get("registered")) {
+					identityDoc.setDeviceServerStatus(devicePub, serverUrl, {
+						registered: true,
+						keyId: serverKey.id,
+						lastVerifiedAt: Date.now(),
+					});
+				} else {
+					// Just update verification timestamp + keyId
+					identityDoc.setDeviceServerStatus(devicePub, serverUrl, {
+						lastVerifiedAt: Date.now(),
+						keyId: serverKey.id,
+					});
+				}
+
+				// Execute pending revocation if we're a master device
+				if (revokedAt && isMaster) {
+					client
+						.revokeKey(serverKey.id)
+						.then(() => {
+							identityDoc.setDeviceServerStatus(
+								devicePub,
+								serverUrl,
+								{ registered: false },
+							);
+						})
+						.catch(() => {});
+				}
+			}
+		});
+
+		// 2. Import unknown server keys into Y.Doc (migration)
+		for (const key of serverKeys) {
+			if (key.revoked) continue;
+			if (!devicesMap.has(key.publicKey)) {
+				identityDoc.addDevice(key.publicKey, {
+					deviceName: key.deviceName ?? "Unknown",
+					tier: "paired",
+					serverUrl,
+					keyId: key.id,
+				});
+			}
+		}
+	}
+}

package/src/IdentityDoc.ts

@@ -53,6 +53,26 @@ export interface IdentityServerEntry {
 	addedAt: number;
 }
 
+export type DeviceTier = "master" | "paired";
+
+export interface DeviceServerStatus {
+	registered: boolean;
+	registeredAt: number | null;
+	keyId: string | null;
+	lastVerifiedAt: number | null;
+	error: string | null;
+}
+
+export interface IdentityDeviceEntry {
+	deviceName: string;
+	tier: DeviceTier;
+	x25519Key: string | null;
+	addedAt: number;
+	revokedAt: number | null;
+	revokedBy: string | null;
+	servers: Map<string, DeviceServerStatus>;
+}
+
 export interface IdentitySpaceEntry {
 	id: string;
 	name: string;
@@ -275,6 +295,10 @@ export class IdentityDocProvider extends EventEmitter {
 		return this.document.getMap("plugins");
 	}
 
+	get devicesMap(): Y.Map<Y.Map<any>> {
+		return this.document.getMap("devices");
+	}
+
 	get preferencesMap(): Y.Map<any> {
 		return this.document.getMap("preferences");
 	}
@@ -445,6 +469,124 @@ export class IdentityDocProvider extends EventEmitter {
 		this.preferencesMap.set(key, value);
 	}
 
+	// ── Devices ─────────────────────────────────────────────────────────────
+
+	getDevice(publicKey: string): IdentityDeviceEntry | undefined {
+		const entry = this.devicesMap.get(publicKey);
+		if (!entry) return undefined;
+		const servers = new Map<string, DeviceServerStatus>();
+		const serversYMap = entry.get("servers") as Y.Map<Y.Map<any>> | undefined;
+		if (serversYMap) {
+			serversYMap.forEach((sEntry, url) => {
+				servers.set(url, {
+					registered: sEntry.get("registered") ?? false,
+					registeredAt: sEntry.get("registeredAt") ?? null,
+					keyId: sEntry.get("keyId") ?? null,
+					lastVerifiedAt: sEntry.get("lastVerifiedAt") ?? null,
+					error: sEntry.get("error") ?? null,
+				});
+			});
+		}
+		return {
+			deviceName: entry.get("deviceName") ?? "Unknown",
+			tier: entry.get("tier") ?? "paired",
+			x25519Key: entry.get("x25519Key") ?? null,
+			addedAt: entry.get("addedAt") ?? 0,
+			revokedAt: entry.get("revokedAt") ?? null,
+			revokedBy: entry.get("revokedBy") ?? null,
+			servers,
+		};
+	}
+
+	getDevices(): Map<string, IdentityDeviceEntry> {
+		const result = new Map<string, IdentityDeviceEntry>();
+		this.devicesMap.forEach((_entry, pubKey) => {
+			const device = this.getDevice(pubKey);
+			if (device) result.set(pubKey, device);
+		});
+		return result;
+	}
+
+	addDevice(
+		publicKey: string,
+		opts: {
+			deviceName: string;
+			tier: DeviceTier;
+			x25519Key?: string;
+			serverUrl?: string;
+			keyId?: string;
+		},
+	): void {
+		this.document.transact(() => {
+			let entry = this.devicesMap.get(publicKey);
+			if (!entry) {
+				entry = new Y.Map();
+				this.devicesMap.set(publicKey, entry);
+			}
+			entry.set("deviceName", opts.deviceName);
+			entry.set("tier", opts.tier);
+			if (opts.x25519Key) entry.set("x25519Key", opts.x25519Key);
+			entry.set("addedAt", Date.now());
+			entry.set("revokedAt", null);
+			entry.set("revokedBy", null);
+
+			if (opts.serverUrl) {
+				let servers = entry.get("servers") as Y.Map<Y.Map<any>> | undefined;
+				if (!servers) {
+					servers = new Y.Map();
+					entry.set("servers", servers);
+				}
+				const sEntry = new Y.Map();
+				sEntry.set("registered", true);
+				sEntry.set("registeredAt", Date.now());
+				sEntry.set("keyId", opts.keyId ?? null);
+				sEntry.set("lastVerifiedAt", Date.now());
+				sEntry.set("error", null);
+				servers.set(opts.serverUrl, sEntry);
+			}
+		});
+	}
+
+	revokeDevice(publicKey: string, revokedBy: string): void {
+		const entry = this.devicesMap.get(publicKey);
+		if (!entry) return;
+		this.document.transact(() => {
+			entry.set("revokedAt", Date.now());
+			entry.set("revokedBy", revokedBy);
+		});
+	}
+
+	setDeviceServerStatus(
+		devicePubKey: string,
+		serverUrl: string,
+		status: Partial<DeviceServerStatus>,
+	): void {
+		const entry = this.devicesMap.get(devicePubKey);
+		if (!entry) return;
+		this.document.transact(() => {
+			let servers = entry.get("servers") as Y.Map<Y.Map<any>> | undefined;
+			if (!servers) {
+				servers = new Y.Map();
+				entry.set("servers", servers);
+			}
+			let sEntry = servers.get(serverUrl);
+			if (!sEntry) {
+				sEntry = new Y.Map();
+				sEntry.set("registered", false);
+				sEntry.set("registeredAt", null);
+				sEntry.set("keyId", null);
+				sEntry.set("lastVerifiedAt", null);
+				sEntry.set("error", null);
+				servers.set(serverUrl, sEntry);
+			}
+			for (const [key, value] of Object.entries(status)) {
+				if (value !== undefined) {
+					sEntry.set(key, value);
+				}
+			}
+		});
+	}
+
 	// ── Observation ──────────────────────────────────────────────────────────
 
 	/**
@@ -452,7 +594,7 @@ export class IdentityDocProvider extends EventEmitter {
 	 * Returns an unsubscribe function.
 	 */
 	observe(
-		mapName: "profile" | "servers" | "plugins" | "preferences",
+		mapName: "profile" | "servers" | "plugins" | "preferences" | "devices",
 		callback: (events: Y.YEvent<any>[], transaction: Y.Transaction) => void,
 	): () => void {
 		const map = this.document.getMap(mapName);

package/src/index.ts

@@ -31,4 +31,8 @@ export type {
 	IdentityProfile,
 	IdentityServerEntry,
 	IdentitySpaceEntry,
+	IdentityDeviceEntry,
+	DeviceServerStatus,
+	DeviceTier,
 } from "./IdentityDoc.ts";
+export { DeviceRegistrationService } from "./DeviceRegistrationService.ts";

package/src/webrtc/AbracadabraWebRTC.ts

@@ -342,19 +342,25 @@ export class AbracadabraWebRTC extends EventEmitter {
 		if (!pc) return;
 
 		const channelName = "custom";
-		let channel = pc.router.getChannel(channelName);
-		if (!channel || channel.readyState !== "open") {
-			// Create on-demand.
-			channel = pc.router.createChannel(channelName, { ordered: true });
-			// Wait for open before sending.
-			channel.onopen = () => {
-				const data = new TextEncoder().encode(payload);
-				pc.router.send(channelName, data);
-			};
+		const channel = pc.router.getChannel(channelName);
+		if (channel && channel.readyState === "open") {
+			const data = new TextEncoder().encode(payload);
+			pc.router.send(channelName, data).catch(() => {});
 			return;
 		}
-		const data = new TextEncoder().encode(payload);
-		pc.router.send(channelName, data);
+
+		// Channel not open yet — queue via the router's channelOpen event.
+		// Do NOT create a new channel here. The "custom" channel must be
+		// created during initiateConnection to be included in the SDP offer.
+		// If it doesn't exist yet, the peer hasn't finished negotiation.
+		const onOpen = ({ name }: { name: string }) => {
+			if (name === channelName) {
+				pc.router.off("channelOpen", onOpen);
+				const data = new TextEncoder().encode(payload);
+				pc.router.send(channelName, data).catch(() => {});
+			}
+		};
+		pc.router.on("channelOpen", onOpen);
 	}
 
 	/**
@@ -475,8 +481,12 @@ export class AbracadabraWebRTC extends EventEmitter {
 			// Listen for key-exchange messages on the router.
 			pc.router.on("channelMessage", async ({ name, data }: { name: string; data: any }) => {
 				if (name === KEY_EXCHANGE_CHANNEL) {
-					const buf = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
-					await e2ee.handleKeyExchange(buf);
+					try {
+						const buf = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+						await e2ee.handleKeyExchange(buf);
+					} catch (err) {
+						this.emit("e2eeFailed", { peerId, error: err });
+					}
 				}
 			});
 
@@ -556,10 +566,16 @@ export class AbracadabraWebRTC extends EventEmitter {
 			enableFileTransfer: this.config.enableFileTransfer,
 		});
 
+		// Always create the "custom" channel for application messages
+		// (e.g. device pairing). Must be in the initial offer so the
+		// remote peer receives it via ondatachannel.
+		pc.router.createChannel("custom", { ordered: true });
+
 		try {
 			const sdp = await pc.createOffer();
 			this.signaling?.sendOffer(peerId, sdp);
-		} catch {
+		} catch (err) {
+			this.emit("error", { type: "offer-failed", peerId, error: err });
 			this.removePeer(peerId);
 		}
 	}
@@ -581,7 +597,8 @@ export class AbracadabraWebRTC extends EventEmitter {
 		try {
 			const answerSdp = await pc.setRemoteOffer(sdp);
 			this.signaling?.sendAnswer(from, answerSdp);
-		} catch {
+		} catch (err) {
+			this.emit("error", { type: "answer-failed", peerId: from, error: err });
 			this.removePeer(from);
 		}
 	}

package/src/webrtc/DevicePairingChannel.ts

@@ -378,6 +378,18 @@ export class DevicePairingChannel extends EventEmitter {
 			},
 		);
 
+		this.webrtc.on("e2eeFailed", ({ peerId, error }: { peerId: string; error: any }) => {
+			if (!this._destroyed) {
+				this.emit("error", new Error(`E2EE failed: ${error?.message ?? error}`));
+			}
+		});
+
+		this.webrtc.on("error", (err: any) => {
+			if (!this._destroyed) {
+				this.emit("error", new Error(`WebRTC: ${err?.type ?? err?.message ?? "unknown"}`));
+			}
+		});
+
 		this.webrtc.on("peerLeft", () => {
 			if (!this._destroyed) {
 				this.emit("error", new Error("Peer disconnected"));