@abraca/dabra 1.0.19 → 1.0.21

package/dist/index.d.ts

@@ -315,8 +315,31 @@ declare class AbracadabraClient {
   }): Promise<void>;
   /** List all registered public keys for the current user. */
   listKeys(): Promise<PublicKeyInfo[]>;
+  /** Rename a registered device key. */
+  renameKey(keyId: string, deviceName: string): Promise<void>;
   /** Revoke a public key by its ID. */
   revokeKey(keyId: string): Promise<void>;
+  /** Create a single-use device invite code for pairing a new device to this account. */
+  createDeviceInvite(opts?: {
+    expiresIn?: number;
+  }): Promise<{
+    code: string;
+    expiresAt: number;
+  }>;
+  /** Redeem a device invite code to register a new device key. Returns a JWT token. */
+  redeemDeviceInvite(opts: {
+    code: string;
+    publicKey: string;
+    x25519Key?: string;
+    deviceName?: string;
+  }): Promise<{
+    token: string;
+    user: {
+      id: string;
+      username: string;
+      publicKey: string;
+    };
+  }>;
   /** Get encryption info for a document. */
   getDocEncryption(docId: string): Promise<DocEncryptionInfo>;
   /** Set the encryption mode for a document (no downgrade). */
@@ -1008,6 +1031,9 @@ interface PublicKeyInfo {
   publicKey: string;
   deviceName: string | null;
   revoked: boolean;
+  createdAt?: number | null;
+  pairedBy?: string | null;
+  pairedVia?: string | null;
 }
 interface PermissionEntry {
   user_id: string;
@@ -2040,6 +2066,7 @@ declare class AbracadabraWebRTC extends EventEmitter {
   broadcastFile(file: File | Blob, filename: string): Promise<FileTransferHandle[]>;
   /**
    * Send a custom string message to a specific peer via a data channel.
+   * When E2EE is active, the message is encrypted through the router.
    */
   sendCustomMessage(peerId: string, payload: string): void;
   /**
@@ -2211,6 +2238,82 @@ declare class ManualSignaling extends EventEmitter {
   destroy(): void;
 }
 //#endregion
+//#region packages/provider/src/webrtc/DevicePairingChannel.d.ts
+interface DevicePairingConfig {
+  /** Server base URL (http/https). */
+  serverUrl: string;
+  /** JWT token or async token factory for signaling auth. */
+  token: string | (() => string) | (() => Promise<string>);
+  /** E2EE identity (Ed25519 public key + X25519 private key). */
+  e2ee: E2EEIdentity;
+  /** ICE servers. Defaults to Google STUN. */
+  iceServers?: RTCIceServer[];
+  /** WebSocket polyfill (for Node.js). */
+  WebSocketPolyfill?: any;
+}
+interface PairingRequest {
+  /** Device B's Ed25519 public key (base64url). */
+  publicKey: string;
+  /** Device B's X25519 public key (base64url). */
+  x25519Key: string;
+  /** Human-readable device label. */
+  deviceName: string;
+}
+interface PairingResult {
+  success: boolean;
+  error?: string;
+}
+type PairingRole = "approver" | "requester";
+declare class DevicePairingChannel extends EventEmitter {
+  private readonly config;
+  private webrtc;
+  private timeoutHandle;
+  private _destroyed;
+  private _pendingRequest;
+  private _connectedPeerId;
+  readonly role: PairingRole;
+  readonly pairingCode: string;
+  private constructor();
+  /**
+   * Create an approver session (Device A). Returns the channel and a
+   * 6-character pairing code to share with Device B.
+   */
+  static createApprover(config: DevicePairingConfig): {
+    channel: DevicePairingChannel;
+    pairingCode: string;
+  };
+  /**
+   * Create a requester session (Device B). Joins with a pairing code
+   * obtained from Device A.
+   */
+  static createRequester(config: DevicePairingConfig, pairingCode: string): DevicePairingChannel;
+  /**
+   * Approve the pending pairing request. Calls `client.addKey()` to
+   * register Device B's public key, then notifies Device B.
+   */
+  approve(client: AbracadabraClient): Promise<PairingResult>;
+  /**
+   * Approve via server-side device invite. Creates a single-use invite code
+   * and sends it to Device B over the E2EE channel. Device B redeems it
+   * independently via HTTP — Device A can go offline after this.
+   */
+  approveWithInvite(client: AbracadabraClient): Promise<PairingResult>;
+  /**
+   * Reject the pending pairing request.
+   */
+  reject(reason?: string): void;
+  /**
+   * Send a pairing request to Device A. Call this after the "connected"
+   * event fires.
+   */
+  requestPairing(request: PairingRequest): void;
+  get isDestroyed(): boolean;
+  destroy(): void;
+  private start;
+  private sendMessage;
+  private handleMessage;
+}
+//#endregion
 //#region packages/provider/src/sync/BroadcastChannelSync.d.ts
 declare class BroadcastChannelSync extends EventEmitter {
   private readonly document;
@@ -2239,4 +2342,4 @@ declare class BroadcastChannelSync extends EventEmitter {
   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, EffectivePermissionEntry, EffectivePermissionsResponse, 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 };
+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, 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, 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.19",
+  "version": "1.0.21",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraClient.ts

@@ -195,11 +195,38 @@ export class AbracadabraClient {
 		return res.keys;
 	}
 
+	/** Rename a registered device key. */
+	async renameKey(keyId: string, deviceName: string): Promise<void> {
+		await this.request("PATCH", `/auth/keys/${encodeURIComponent(keyId)}`, { body: { deviceName } });
+	}
+
 	/** Revoke a public key by its ID. */
 	async revokeKey(keyId: string): Promise<void> {
 		await this.request("DELETE", `/auth/keys/${encodeURIComponent(keyId)}`);
 	}
 
+	// ── Device Invites ───────────────────────────────────────────────────────
+
+	/** Create a single-use device invite code for pairing a new device to this account. */
+	async createDeviceInvite(opts?: { expiresIn?: number }): Promise<{ code: string; expiresAt: number }> {
+		return this.request<{ code: string; expiresAt: number }>("POST", "/auth/device-invite", {
+			body: opts?.expiresIn != null ? { expiresIn: opts.expiresIn } : {},
+		});
+	}
+
+	/** Redeem a device invite code to register a new device key. Returns a JWT token. */
+	async redeemDeviceInvite(opts: {
+		code: string;
+		publicKey: string;
+		x25519Key?: string;
+		deviceName?: string;
+	}): Promise<{ token: string; user: { id: string; username: string; publicKey: string } }> {
+		return this.request("POST", "/auth/device-redeem", {
+			body: { code: opts.code, publicKey: opts.publicKey, x25519Key: opts.x25519Key, deviceName: opts.deviceName },
+			auth: false,
+		});
+	}
+
 	// ── Encryption ───────────────────────────────────────────────────────────
 
 	/** Get encryption info for a document. */

package/src/AbracadabraWS.ts

@@ -220,9 +220,8 @@ export class AbracadabraWS extends EventEmitter {
   attach(provider: AbracadabraBaseProvider) {
     const existing = this.configuration.providerMap.get(provider.configuration.name);
     if (existing && existing !== provider) {
-      console.warn(
-        `[AbracadabraWS] attach: overwriting provider for "${provider.configuration.name}". ` +
-        `This may indicate a duplicate loadChild for the same document.`
+      console.debug(
+        `[AbracadabraWS] attach: replacing provider for "${provider.configuration.name}".`
       );
     }
     this.configuration.providerMap.set(provider.configuration.name, provider);

package/src/BackgroundSyncManager.ts

@@ -394,6 +394,25 @@ export class BackgroundSyncManager extends EventEmitter {
 		// Check if the provider already exists (user is viewing it) before loading.
 		const alreadyCached = this.rootProvider.children.has(docId);
 
+		// Another provider (e.g. a nested renderer) may have already loaded
+		// this doc through a different parent.  The shared WS providerMap
+		// tracks all attached providers; if one exists, the doc is already
+		// syncing — skip to avoid creating a duplicate.
+		if (!alreadyCached) {
+			const wsProviderMap = (this.rootProvider as any).configuration
+				?.websocketProvider?.configuration?.providerMap as
+				| Map<string, unknown>
+				| undefined;
+			if (wsProviderMap?.has(docId)) {
+				return {
+					docId,
+					status: "synced",
+					lastSynced: Date.now(),
+					isE2E: false,
+				};
+			}
+		}
+
 		const childProvider = await this.rootProvider.loadChild(docId);
 
 		// Wait for ready (offline snapshot loaded) then synced (server sync done)

package/src/types.ts

@@ -195,6 +195,9 @@ export interface PublicKeyInfo {
   publicKey: string;
   deviceName: string | null;
   revoked: boolean;
+  createdAt?: number | null;
+  pairedBy?: string | null;
+  pairedVia?: string | null;
 }
 
 export interface PermissionEntry {

package/src/webrtc/AbracadabraWebRTC.ts

@@ -335,22 +335,26 @@ export class AbracadabraWebRTC extends EventEmitter {
 
 	/**
 	 * Send a custom string message to a specific peer via a data channel.
+	 * When E2EE is active, the message is encrypted through the router.
 	 */
 	sendCustomMessage(peerId: string, payload: string): void {
 		const pc = this.peerConnections.get(peerId);
 		if (!pc) return;
 
-		let channel = pc.router.getChannel("custom");
+		const channelName = "custom";
+		let channel = pc.router.getChannel(channelName);
 		if (!channel || channel.readyState !== "open") {
 			// Create on-demand.
-			channel = pc.router.createChannel("custom", { ordered: true });
+			channel = pc.router.createChannel(channelName, { ordered: true });
 			// Wait for open before sending.
 			channel.onopen = () => {
-				channel!.send(payload);
+				const data = new TextEncoder().encode(payload);
+				pc.router.send(channelName, data);
 			};
 			return;
 		}
-		channel.send(payload);
+		const data = new TextEncoder().encode(payload);
+		pc.router.send(channelName, data);
 	}
 
 	/**

package/src/webrtc/DevicePairingChannel.ts

@@ -0,0 +1,384 @@
+/**
+ * DevicePairingChannel
+ *
+ * Enables cross-device identity pairing over an E2EE WebRTC data channel.
+ * Device A (approver) creates a pairing session with a short code. Device B
+ * (requester) joins with the code. After E2EE is established, Device B sends
+ * its public key and Device A registers it via `addKey()`.
+ *
+ * Reuses the existing WebRTC stack: SignalingSocket, PeerConnection,
+ * DataChannelRouter, and E2EEChannel (X25519 ECDH + AES-256-GCM).
+ */
+
+import { sha256 } from "@noble/hashes/sha256";
+import EventEmitter from "../EventEmitter.ts";
+import type { AbracadabraClient } from "../AbracadabraClient.ts";
+import { AbracadabraWebRTC } from "./AbracadabraWebRTC.ts";
+import type { E2EEIdentity } from "./E2EEChannel.ts";
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/** Ambiguity-free charset (no 0/O/1/I). */
+const CODE_CHARSET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+const CODE_LENGTH = 6;
+const PAIRING_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const PAIRING_CHANNEL = "device-pairing";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface DevicePairingConfig {
+	/** Server base URL (http/https). */
+	serverUrl: string;
+	/** JWT token or async token factory for signaling auth. */
+	token: string | (() => string) | (() => Promise<string>);
+	/** E2EE identity (Ed25519 public key + X25519 private key). */
+	e2ee: E2EEIdentity;
+	/** ICE servers. Defaults to Google STUN. */
+	iceServers?: RTCIceServer[];
+	/** WebSocket polyfill (for Node.js). */
+	WebSocketPolyfill?: any;
+}
+
+export interface PairingRequest {
+	/** Device B's Ed25519 public key (base64url). */
+	publicKey: string;
+	/** Device B's X25519 public key (base64url). */
+	x25519Key: string;
+	/** Human-readable device label. */
+	deviceName: string;
+}
+
+export interface PairingResult {
+	success: boolean;
+	error?: string;
+}
+
+type PairingRole = "approver" | "requester";
+
+// ── Internal wire messages ──────────────────────────────────────────────────
+
+interface PairRequestMsg {
+	type: "pair-request";
+	publicKey: string;
+	x25519Key: string;
+	deviceName: string;
+}
+
+interface PairApprovedMsg {
+	type: "pair-approved";
+}
+
+interface PairInviteCodeMsg {
+	type: "pair-invite-code";
+	code: string;
+}
+
+interface PairRejectedMsg {
+	type: "pair-rejected";
+	reason: string;
+}
+
+type PairingMsg = PairRequestMsg | PairApprovedMsg | PairRejectedMsg | PairInviteCodeMsg;
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function generatePairingCode(): string {
+	const bytes = crypto.getRandomValues(new Uint8Array(CODE_LENGTH));
+	return Array.from(bytes)
+		.map((b) => CODE_CHARSET[b % CODE_CHARSET.length])
+		.join("");
+}
+
+function codeToRoomId(code: string): string {
+	const hash = sha256(new TextEncoder().encode(code.toUpperCase()));
+	// Take first 16 hex chars for the room ID.
+	const hex = Array.from(hash.slice(0, 8))
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+	return `__pairing_${hex}`;
+}
+
+// ── DevicePairingChannel ────────────────────────────────────────────────────
+
+export class DevicePairingChannel extends EventEmitter {
+	private webrtc: AbracadabraWebRTC | null = null;
+	private timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+	private _destroyed = false;
+	private _pendingRequest: PairingRequest | null = null;
+	private _connectedPeerId: string | null = null;
+
+	readonly role: PairingRole;
+	readonly pairingCode: string;
+
+	private constructor(
+		role: PairingRole,
+		pairingCode: string,
+		private readonly config: DevicePairingConfig,
+	) {
+		super();
+		this.role = role;
+		this.pairingCode = pairingCode;
+	}
+
+	// ── Factory Methods ───────────────────────────────────────────────────
+
+	/**
+	 * Create an approver session (Device A). Returns the channel and a
+	 * 6-character pairing code to share with Device B.
+	 */
+	static createApprover(config: DevicePairingConfig): {
+		channel: DevicePairingChannel;
+		pairingCode: string;
+	} {
+		const code = generatePairingCode();
+		const channel = new DevicePairingChannel("approver", code, config);
+		channel.start();
+		return { channel, pairingCode: code };
+	}
+
+	/**
+	 * Create a requester session (Device B). Joins with a pairing code
+	 * obtained from Device A.
+	 */
+	static createRequester(
+		config: DevicePairingConfig,
+		pairingCode: string,
+	): DevicePairingChannel {
+		const channel = new DevicePairingChannel(
+			"requester",
+			pairingCode.toUpperCase().replace(/[^A-Z2-9]/g, ""),
+			config,
+		);
+		channel.start();
+		return channel;
+	}
+
+	// ── Approver API ──────────────────────────────────────────────────────
+
+	/**
+	 * Approve the pending pairing request. Calls `client.addKey()` to
+	 * register Device B's public key, then notifies Device B.
+	 */
+	async approve(client: AbracadabraClient): Promise<PairingResult> {
+		if (this.role !== "approver") {
+			return { success: false, error: "Only the approver can approve" };
+		}
+		if (!this._pendingRequest) {
+			return { success: false, error: "No pending pairing request" };
+		}
+		if (!this._connectedPeerId) {
+			return { success: false, error: "Peer not connected" };
+		}
+
+		const req = this._pendingRequest;
+
+		try {
+			await client.addKey({
+				publicKey: req.publicKey,
+				deviceName: req.deviceName,
+				x25519Key: req.x25519Key,
+			});
+
+			this.sendMessage({ type: "pair-approved" });
+			this._pendingRequest = null;
+			this.emit("pairingComplete", { success: true } as PairingResult);
+			return { success: true };
+		} catch (err: any) {
+			const error = err?.message ?? "Failed to register device key";
+			this.sendMessage({ type: "pair-rejected", reason: error });
+			this._pendingRequest = null;
+			const result: PairingResult = { success: false, error };
+			this.emit("pairingComplete", result);
+			return result;
+		}
+	}
+
+	/**
+	 * Approve via server-side device invite. Creates a single-use invite code
+	 * and sends it to Device B over the E2EE channel. Device B redeems it
+	 * independently via HTTP — Device A can go offline after this.
+	 */
+	async approveWithInvite(client: AbracadabraClient): Promise<PairingResult> {
+		if (this.role !== "approver") {
+			return { success: false, error: "Only the approver can approve" };
+		}
+		if (!this._pendingRequest) {
+			return { success: false, error: "No pending pairing request" };
+		}
+		if (!this._connectedPeerId) {
+			return { success: false, error: "Peer not connected" };
+		}
+
+		try {
+			const { code } = await client.createDeviceInvite();
+			this.sendMessage({ type: "pair-invite-code", code });
+			this._pendingRequest = null;
+			this.emit("pairingComplete", { success: true } as PairingResult);
+			return { success: true };
+		} catch (err: any) {
+			const error = err?.message ?? "Failed to create device invite";
+			this.sendMessage({ type: "pair-rejected", reason: error });
+			this._pendingRequest = null;
+			const result: PairingResult = { success: false, error };
+			this.emit("pairingComplete", result);
+			return result;
+		}
+	}
+
+	/**
+	 * Reject the pending pairing request.
+	 */
+	reject(reason = "Rejected by user"): void {
+		if (this.role !== "approver" || !this._pendingRequest) return;
+		this.sendMessage({ type: "pair-rejected", reason });
+		this._pendingRequest = null;
+		this.emit("pairingComplete", {
+			success: false,
+			error: reason,
+		} as PairingResult);
+	}
+
+	// ── Requester API ─────────────────────────────────────────────────────
+
+	/**
+	 * Send a pairing request to Device A. Call this after the "connected"
+	 * event fires.
+	 */
+	requestPairing(request: PairingRequest): void {
+		if (this.role !== "requester") return;
+		this.sendMessage({
+			type: "pair-request",
+			publicKey: request.publicKey,
+			x25519Key: request.x25519Key,
+			deviceName: request.deviceName,
+		});
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────
+
+	get isDestroyed(): boolean {
+		return this._destroyed;
+	}
+
+	destroy(): void {
+		if (this._destroyed) return;
+		this._destroyed = true;
+
+		if (this.timeoutHandle) {
+			clearTimeout(this.timeoutHandle);
+			this.timeoutHandle = null;
+		}
+
+		if (this.webrtc) {
+			this.webrtc.destroy();
+			this.webrtc = null;
+		}
+
+		this.removeAllListeners();
+	}
+
+	// ── Private ─────────────────────────────────────────────────────────
+
+	private start(): void {
+		const roomId = codeToRoomId(this.pairingCode);
+
+		this.webrtc = new AbracadabraWebRTC({
+			docId: roomId,
+			url: this.config.serverUrl,
+			token: this.config.token,
+			iceServers: this.config.iceServers,
+			e2ee: this.config.e2ee,
+			enableDocSync: false,
+			enableAwarenessSync: false,
+			enableFileTransfer: false,
+			autoConnect: false,
+			WebSocketPolyfill: this.config.WebSocketPolyfill,
+		});
+
+		this.webrtc.on("e2eeEstablished", ({ peerId }: { peerId: string }) => {
+			this._connectedPeerId = peerId;
+			this.emit("connected");
+		});
+
+		this.webrtc.on(
+			"customMessage",
+			({ peerId, payload }: { peerId: string; payload: string }) => {
+				this.handleMessage(peerId, payload);
+			},
+		);
+
+		this.webrtc.on("peerLeft", () => {
+			if (!this._destroyed) {
+				this.emit("error", new Error("Peer disconnected"));
+			}
+		});
+
+		this.webrtc.on(
+			"signalingError",
+			(err: { code: string; message: string }) => {
+				this.emit("error", new Error(`Signaling: ${err.message}`));
+			},
+		);
+
+		// Auto-destroy after timeout.
+		this.timeoutHandle = setTimeout(() => {
+			if (!this._destroyed) {
+				this.emit("error", new Error("Pairing timed out"));
+				this.destroy();
+			}
+		}, PAIRING_TIMEOUT_MS);
+
+		this.webrtc.connect();
+	}
+
+	private sendMessage(msg: PairingMsg): void {
+		if (!this.webrtc || !this._connectedPeerId) return;
+		// Send via the custom message path — the E2EE layer on the data channel
+		// encrypts all non-key-exchange traffic via the DataChannelRouter.
+		this.webrtc.sendCustomMessage(
+			this._connectedPeerId,
+			JSON.stringify(msg),
+		);
+	}
+
+	private handleMessage(peerId: string, payload: string): void {
+		let msg: PairingMsg;
+		try {
+			msg = JSON.parse(payload);
+		} catch {
+			return;
+		}
+
+		switch (msg.type) {
+			case "pair-request":
+				if (this.role !== "approver") return;
+				this._pendingRequest = {
+					publicKey: msg.publicKey,
+					x25519Key: msg.x25519Key,
+					deviceName: msg.deviceName,
+				};
+				this.emit("pairingRequest", this._pendingRequest);
+				break;
+
+			case "pair-approved":
+				if (this.role !== "requester") return;
+				this.emit("approved");
+				this.emit("pairingComplete", { success: true } as PairingResult);
+				break;
+
+			case "pair-rejected":
+				if (this.role !== "requester") return;
+				this.emit("rejected", msg.reason);
+				this.emit("pairingComplete", {
+					success: false,
+					error: msg.reason,
+				} as PairingResult);
+				break;
+
+			case "pair-invite-code":
+				if (this.role !== "requester") return;
+				this.emit("inviteCode", msg.code);
+				break;
+		}
+	}
+}

package/src/webrtc/index.ts

@@ -8,6 +8,8 @@ export { E2EEChannel } from "./E2EEChannel.ts";
 export type { E2EEIdentity } from "./E2EEChannel.ts";
 export { ManualSignaling } from "./ManualSignaling.ts";
 export type { ManualSignalingBlob } from "./ManualSignaling.ts";
+export { DevicePairingChannel } from "./DevicePairingChannel.ts";
+export type { DevicePairingConfig, PairingRequest, PairingResult } from "./DevicePairingChannel.ts";
 export type {
 	AbracadabraWebRTCConfiguration,
 	PeerInfo,