@abraca/dabra 1.0.20 → 1.0.22

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,