@abraca/dabra 1.0.22 → 1.0.23

package/dist/index.d.ts

@@ -340,6 +340,11 @@ declare class AbracadabraClient {
       publicKey: string;
     };
   }>;
+  /**
+   * Fetch a short-lived anonymous pairing token for WebRTC signaling.
+   * No authentication required. The token only grants access to `__pairing_*` rooms.
+   */
+  static getPairingToken(serverUrl: string): Promise<string>;
   /** Get encryption info for a document. */
   getDocEncryption(docId: string): Promise<DocEncryptionInfo>;
   /** Set the encryption mode for a document (no downgrade). */
@@ -2248,12 +2253,22 @@ declare class ManualSignaling extends EventEmitter {
 interface DevicePairingConfig {
   /** Server base URL (http/https). */
   serverUrl: string;
-  /** JWT token or async token factory for signaling auth. */
-  token: string | (() => string) | (() => Promise<string>);
+  /**
+   * JWT token or async token factory for signaling auth.
+   * When omitted, a short-lived anonymous pairing token is fetched automatically
+   * from `POST /auth/pairing-token`.
+   */
+  token?: string | (() => string) | (() => Promise<string>);
   /** E2EE identity (Ed25519 public key + X25519 private key). */
   e2ee: E2EEIdentity;
   /** ICE servers. Defaults to Google STUN. */
   iceServers?: RTCIceServer[];
+  /**
+   * Fallback signaling server URL. If the primary server is unreachable,
+   * signaling will retry through this server. The actual pairing data is
+   * E2EE-encrypted, so the relay server cannot read it.
+   */
+  fallbackSignalingUrl?: string;
   /** WebSocket polyfill (for Node.js). */
   WebSocketPolyfill?: any;
 }
@@ -2277,6 +2292,8 @@ declare class DevicePairingChannel extends EventEmitter {
   private _destroyed;
   private _pendingRequest;
   private _connectedPeerId;
+  private _usingFallback;
+  private _resolvedIceServers;
   readonly role: PairingRole;
   readonly pairingCode: string;
   private constructor();
@@ -2315,7 +2332,11 @@ declare class DevicePairingChannel extends EventEmitter {
   requestPairing(request: PairingRequest): void;
   get isDestroyed(): boolean;
   destroy(): void;
+  private resolveToken;
   private start;
+  private connectToServer;
+  /** Whether the connection fell back to the fallback signaling server. */
+  get usingFallback(): boolean;
   private sendMessage;
   private handleMessage;
 }
@@ -2406,6 +2427,16 @@ interface IdentityDocConfiguration {
   token?: string | (() => string) | (() => Promise<string>);
   /** Per-server token factories keyed by base URL. */
   tokens?: Record<string, string | (() => string) | (() => Promise<string>)>;
+  /**
+   * Crypto identity for Ed25519 challenge-response auth.
+   * When provided, used instead of JWT tokens for authenticating with servers.
+   */
+  cryptoIdentity?: CryptoIdentity | (() => Promise<CryptoIdentity>);
+  /**
+   * Signs a base64url challenge and returns a base64url signature.
+   * Required when cryptoIdentity is set.
+   */
+  signChallenge?: (challenge: string) => Promise<string>;
   /**
    * WebRTC configuration for P2P identity sync.
    * When provided, enables E2EE peer-to-peer sync using signaling from
@@ -2444,7 +2475,7 @@ declare class IdentityDocProvider extends EventEmitter {
   private _destroyed;
   constructor(configuration: IdentityDocConfiguration);
   connect(): void;
-  private _connectToServer;
+  connectToServer(key: string, serverUrl: string): void;
   private _connectWebRTC;
   get profileMap(): Y.Map<string>;
   get serversMap(): Y.Map<Y.Map<any>>;

package/package.json

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

package/src/AbracadabraClient.ts

@@ -227,6 +227,23 @@ export class AbracadabraClient {
 		});
 	}
 
+	// ── Pairing ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Fetch a short-lived anonymous pairing token for WebRTC signaling.
+	 * No authentication required. The token only grants access to `__pairing_*` rooms.
+	 */
+	static async getPairingToken(serverUrl: string): Promise<string> {
+		let base = serverUrl;
+		while (base.endsWith("/")) base = base.slice(0, -1);
+		const resp = await fetch(`${base}/auth/pairing-token`, { method: "POST" });
+		if (!resp.ok) {
+			throw new Error(`Failed to fetch pairing token: ${resp.status}`);
+		}
+		const { token } = (await resp.json()) as { token: string };
+		return token;
+	}
+
 	// ── Encryption ───────────────────────────────────────────────────────────
 
 	/** Get encryption info for a document. */

package/src/IdentityDoc.ts

@@ -5,6 +5,7 @@ import { AbracadabraProvider } from "./AbracadabraProvider.ts";
 import type { AbracadabraProviderConfiguration } from "./AbracadabraProvider.ts";
 import { AbracadabraWS } from "./AbracadabraWS.ts";
 import { AbracadabraWebRTC } from "./webrtc/AbracadabraWebRTC.ts";
+import type { CryptoIdentity } from "./types.ts";
 import type { E2EEIdentity } from "./webrtc/E2EEChannel.ts";
 
 // ── Identity Doc ID Derivation ─────────────────────────────────────────────
@@ -89,6 +90,18 @@ export interface IdentityDocConfiguration {
 	/** Per-server token factories keyed by base URL. */
 	tokens?: Record<string, string | (() => string) | (() => Promise<string>)>;
 
+	/**
+	 * Crypto identity for Ed25519 challenge-response auth.
+	 * When provided, used instead of JWT tokens for authenticating with servers.
+	 */
+	cryptoIdentity?: CryptoIdentity | (() => Promise<CryptoIdentity>);
+
+	/**
+	 * Signs a base64url challenge and returns a base64url signature.
+	 * Required when cryptoIdentity is set.
+	 */
+	signChallenge?: (challenge: string) => Promise<string>;
+
 	/**
 	 * WebRTC configuration for P2P identity sync.
 	 * When provided, enables E2EE peer-to-peer sync using signaling from
@@ -164,7 +177,7 @@ export class IdentityDocProvider extends EventEmitter {
 
 		for (const { url, key } of targets) {
 			if (this.providers.has(key)) continue;
-			this._connectToServer(key, url);
+			this.connectToServer(key, url);
 		}
 
 		if (this.config.webrtc && !this.webrtc) {
@@ -172,7 +185,21 @@ export class IdentityDocProvider extends EventEmitter {
 		}
 	}
 
-	private _connectToServer(key: string, serverUrl: string): void {
+	connectToServer(key: string, serverUrl: string): void {
+		if (this._destroyed) return;
+
+		// Tear down existing connection for this key (idempotent reconnect)
+		const existingProvider = this.providers.get(key);
+		if (existingProvider) {
+			existingProvider.destroy();
+			this.providers.delete(key);
+		}
+		const existingWs = this.websockets.get(key);
+		if (existingWs) {
+			existingWs.destroy();
+			this.websockets.delete(key);
+		}
+
 		const token =
 			this.config.tokens?.[serverUrl] ?? this.config.token ?? "";
 
@@ -184,17 +211,26 @@ export class IdentityDocProvider extends EventEmitter {
 		const ws = new AbracadabraWS({ url: wsUrl, WebSocketPolyfill: undefined as any });
 		this.websockets.set(key, ws);
 
-		const provider = new AbracadabraProvider({
+		const providerConfig: AbracadabraProviderConfiguration = {
 			name: this.docId,
 			document: this.document,
 			websocketProvider: ws,
-			token,
 			serverAgnostic: true,
 			disableOfflineStore: key !== "local" && key !== "sync"
 				? true
 				: this.config.disableOfflineStore ?? false,
 			...this.config.providerDefaults,
-		});
+		};
+
+		// Use crypto identity auth if available, otherwise JWT token
+		if (this.config.cryptoIdentity && this.config.signChallenge) {
+			providerConfig.cryptoIdentity = this.config.cryptoIdentity;
+			providerConfig.signChallenge = this.config.signChallenge;
+		} else {
+			providerConfig.token = token;
+		}
+
+		const provider = new AbracadabraProvider(providerConfig);
 
 		provider.on("synced", () => this.emit("synced", { server: key }));
 		provider.on("status", (data: any) =>
@@ -467,7 +503,7 @@ export class IdentityDocProvider extends EventEmitter {
 
 		if (url) {
 			this.config = { ...this.config, syncServerUrl: url };
-			this._connectToServer("sync", url);
+			this.connectToServer("sync", url);
 		}
 	}
 

package/src/webrtc/DevicePairingChannel.ts

@@ -12,7 +12,7 @@
 
 import { sha256 } from "@noble/hashes/sha256";
 import EventEmitter from "../EventEmitter.ts";
-import type { AbracadabraClient } from "../AbracadabraClient.ts";
+import { AbracadabraClient } from "../AbracadabraClient.ts";
 import { AbracadabraWebRTC } from "./AbracadabraWebRTC.ts";
 import type { E2EEIdentity } from "./E2EEChannel.ts";
 
@@ -22,6 +22,7 @@ import type { E2EEIdentity } from "./E2EEChannel.ts";
 const CODE_CHARSET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 const CODE_LENGTH = 6;
 const PAIRING_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const SIGNALING_CONNECT_TIMEOUT_MS = 5_000; // 5 seconds before trying fallback
 const PAIRING_CHANNEL = "device-pairing";
 
 // ── Types ───────────────────────────────────────────────────────────────────
@@ -29,12 +30,22 @@ const PAIRING_CHANNEL = "device-pairing";
 export interface DevicePairingConfig {
 	/** Server base URL (http/https). */
 	serverUrl: string;
-	/** JWT token or async token factory for signaling auth. */
-	token: string | (() => string) | (() => Promise<string>);
+	/**
+	 * JWT token or async token factory for signaling auth.
+	 * When omitted, a short-lived anonymous pairing token is fetched automatically
+	 * from `POST /auth/pairing-token`.
+	 */
+	token?: string | (() => string) | (() => Promise<string>);
 	/** E2EE identity (Ed25519 public key + X25519 private key). */
 	e2ee: E2EEIdentity;
 	/** ICE servers. Defaults to Google STUN. */
 	iceServers?: RTCIceServer[];
+	/**
+	 * Fallback signaling server URL. If the primary server is unreachable,
+	 * signaling will retry through this server. The actual pairing data is
+	 * E2EE-encrypted, so the relay server cannot read it.
+	 */
+	fallbackSignalingUrl?: string;
 	/** WebSocket polyfill (for Node.js). */
 	WebSocketPolyfill?: any;
 }
@@ -106,6 +117,8 @@ export class DevicePairingChannel extends EventEmitter {
 	private _destroyed = false;
 	private _pendingRequest: PairingRequest | null = null;
 	private _connectedPeerId: string | null = null;
+	private _usingFallback = false;
+	private _resolvedIceServers: RTCIceServer[] | undefined;
 
 	readonly role: PairingRole;
 	readonly pairingCode: string;
@@ -279,14 +292,66 @@ export class DevicePairingChannel extends EventEmitter {
 
 	// ── Private ─────────────────────────────────────────────────────────
 
+	private async resolveToken(
+		serverUrl?: string,
+	): Promise<string | (() => string) | (() => Promise<string>)> {
+		// Use provided token if connecting to the primary server.
+		if (this.config.token && serverUrl === this.config.serverUrl) {
+			return this.config.token;
+		}
+
+		// Fetch a short-lived anonymous pairing token from the target server.
+		let base = serverUrl ?? this.config.serverUrl;
+		while (base.endsWith("/")) base = base.slice(0, -1);
+		const resp = await fetch(`${base}/auth/pairing-token`, {
+			method: "POST",
+		});
+		if (!resp.ok) {
+			throw new Error(
+				`Failed to fetch pairing token: ${resp.status} ${resp.statusText}`,
+			);
+		}
+		const { token } = (await resp.json()) as { token: string };
+		return token;
+	}
+
 	private start(): void {
+		this.connectToServer(this.config.serverUrl);
+
+		// Auto-destroy after timeout.
+		this.timeoutHandle = setTimeout(() => {
+			if (!this._destroyed) {
+				this.emit("error", new Error("Pairing timed out"));
+				this.destroy();
+			}
+		}, PAIRING_TIMEOUT_MS);
+	}
+
+	private connectToServer(serverUrl: string, signalingUrl?: string): void {
 		const roomId = codeToRoomId(this.pairingCode);
 
+		// Resolve token (possibly async) — uses a factory so SignalingSocket can await it.
+		const tokenPromise = this.resolveToken(serverUrl);
+		const tokenFactory = async (): Promise<string> => {
+			const t = await tokenPromise;
+			if (typeof t === "function") return await t();
+			return t;
+		};
+
+		// Fetch ICE servers from the target server if none configured.
+		if (!this.config.iceServers) {
+			const client = new AbracadabraClient({ url: serverUrl });
+			client.getIceServers().then((servers) => {
+				if (servers.length > 0) this._resolvedIceServers = servers;
+			});
+		}
+
 		this.webrtc = new AbracadabraWebRTC({
 			docId: roomId,
-			url: this.config.serverUrl,
-			token: this.config.token,
-			iceServers: this.config.iceServers,
+			url: serverUrl,
+			signalingUrl: signalingUrl ?? undefined,
+			token: tokenFactory,
+			iceServers: this.config.iceServers ?? this._resolvedIceServers,
 			e2ee: this.config.e2ee,
 			enableDocSync: false,
 			enableAwarenessSync: false,
@@ -295,6 +360,12 @@ export class DevicePairingChannel extends EventEmitter {
 			WebSocketPolyfill: this.config.WebSocketPolyfill,
 		});
 
+		let connected = false;
+
+		this.webrtc.on("connected", () => {
+			connected = true;
+		});
+
 		this.webrtc.on("e2eeEstablished", ({ peerId }: { peerId: string }) => {
 			this._connectedPeerId = peerId;
 			this.emit("connected");
@@ -320,17 +391,34 @@ export class DevicePairingChannel extends EventEmitter {
 			},
 		);
 
-		// Auto-destroy after timeout.
-		this.timeoutHandle = setTimeout(() => {
-			if (!this._destroyed) {
-				this.emit("error", new Error("Pairing timed out"));
-				this.destroy();
-			}
-		}, PAIRING_TIMEOUT_MS);
+		// If a fallback signaling server is configured, try it after a timeout.
+		if (this.config.fallbackSignalingUrl && !signalingUrl) {
+			const fallbackTimer = setTimeout(() => {
+				if (this._destroyed || connected) return;
+				// Primary server didn't connect in time — try fallback.
+				if (this.webrtc) {
+					this.webrtc.destroy();
+					this.webrtc = null;
+				}
+				this._usingFallback = true;
+				this.emit("fallback", { url: this.config.fallbackSignalingUrl });
+				this.connectToServer(
+					this.config.fallbackSignalingUrl!,
+				);
+			}, SIGNALING_CONNECT_TIMEOUT_MS);
+
+			// Clear fallback timer if primary succeeds.
+			this.webrtc.on("connected", () => clearTimeout(fallbackTimer));
+		}
 
 		this.webrtc.connect();
 	}
 
+	/** Whether the connection fell back to the fallback signaling server. */
+	get usingFallback(): boolean {
+		return this._usingFallback;
+	}
+
 	private sendMessage(msg: PairingMsg): void {
 		if (!this.webrtc || !this._connectedPeerId) return;
 		// Send via the custom message path — the E2EE layer on the data channel

package/src/webrtc/SignalingSocket.ts

@@ -238,8 +238,8 @@ export class SignalingSocket extends EventEmitter {
 
 			case "joined":
 				this.emit("joined", {
-					peerId: msg.peer_id,
-					userId: msg.user_id,
+					peer_id: msg.peer_id,
+					user_id: msg.user_id,
 					muted: msg.muted,
 					video: msg.video,
 					screen: msg.screen,