@abraca/dabra 1.0.21 → 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). */
@@ -621,6 +626,12 @@ interface AbracadabraProviderConfiguration extends Omit<AbracadabraBaseProviderC
   keystore?: CryptoIdentityKeystore;
   /** Shared WebSocket connection (use when multiplexing multiple root documents). */
   websocketProvider?: AbracadabraWS;
+  /**
+   * When true, the IndexedDB offline store is NOT scoped by server origin.
+   * This allows a single document to be synced across multiple servers while
+   * sharing one local store.  Used for the identity doc.
+   */
+  serverAgnostic?: boolean;
 }
 /**
  * AbracadabraProvider extends AbracadabraBaseProvider with:
@@ -2242,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;
 }
@@ -2271,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();
@@ -2309,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;
 }
@@ -2342,4 +2369,155 @@ 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, 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 };
+//#region packages/provider/src/IdentityDoc.d.ts
+/**
+ * Derives a deterministic UUID from an Ed25519 account-level public key.
+ *
+ * The result is a valid UUID v5-style string that any device sharing the
+ * same identity can independently compute.  The `abracadabra:identity:`
+ * prefix prevents collisions with randomly generated doc UUIDs.
+ *
+ * @param publicKeyB64 Base64url-encoded Ed25519 public key (32 bytes).
+ */
+declare function deriveIdentityDocId(publicKeyB64: string): string;
+interface IdentityProfile {
+  username?: string;
+  displayName?: string;
+  colorName?: string;
+  neutralColorName?: string;
+  locale?: string;
+  avatarUrl?: string;
+}
+interface IdentityServerEntry {
+  label: string;
+  hubDocId?: string;
+  entryDocId?: string;
+  defaultRole?: string;
+  spacesEnabled?: boolean;
+  addedAt: number;
+}
+interface IdentitySpaceEntry {
+  id: string;
+  name: string;
+  type: "local" | "remote";
+  serverUrl: string | null;
+  docId: string;
+  remoteSpaceId?: string;
+  visibility: "public" | "private" | "invite";
+  isHub: boolean;
+  order: number;
+  lastSyncedAt?: number;
+  createdAt: number;
+}
+interface IdentityDocConfiguration {
+  /** Base64url-encoded Ed25519 account public key. */
+  publicKey: string;
+  /**
+   * Trusted server URL for identity doc sync.
+   * Only this server (plus the local server) will receive the identity doc.
+   */
+  syncServerUrl?: string;
+  /** Local Tauri server URL for on-device persistence. */
+  localServerUrl?: string;
+  /**
+   * JWT token or async factory for authenticating with sync servers.
+   * When using multiple servers, provide a factory that returns the correct
+   * token for each.
+   */
+  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
+   * any connected server.
+   */
+  webrtc?: {
+    /** Server URL to use for signaling (any connected server works). */signalingServerUrl: string; /** Token for the signaling server. */
+    token: string | (() => string) | (() => Promise<string>); /** E2EE identity for the data channel. */
+    e2ee?: E2EEIdentity; /** ICE servers. */
+    iceServers?: RTCIceServer[];
+  };
+  /** Disable IndexedDB offline store. */
+  disableOfflineStore?: boolean;
+  /** Auto-connect on construction. Default: true. */
+  autoConnect?: boolean;
+  /** Additional provider config passed through to each AbracadabraProvider. */
+  providerDefaults?: Partial<AbracadabraProviderConfiguration>;
+}
+/**
+ * Manages a Y.Doc dedicated to user identity that syncs across trusted
+ * targets only: a designated sync server, a local Tauri server, and/or
+ * WebRTC P2P.
+ *
+ * The Y.Doc contains cross-device settings (profile, servers, spaces,
+ * plugins, preferences).  Each sync target gets its own
+ * AbracadabraProvider sharing the same Y.Doc, with `serverAgnostic: true`
+ * so they all use one IndexedDB store.
+ */
+declare class IdentityDocProvider extends EventEmitter {
+  readonly docId: string;
+  readonly document: Y.Doc;
+  private providers;
+  private websockets;
+  private webrtc;
+  private config;
+  private _destroyed;
+  constructor(configuration: IdentityDocConfiguration);
+  connect(): void;
+  connectToServer(key: string, serverUrl: string): void;
+  private _connectWebRTC;
+  get profileMap(): Y.Map<string>;
+  get serversMap(): Y.Map<Y.Map<any>>;
+  get spacesArray(): Y.Array<Y.Map<any>>;
+  get pluginsMap(): Y.Map<any>;
+  get preferencesMap(): Y.Map<any>;
+  getProfile(): IdentityProfile;
+  setProfile(profile: Partial<IdentityProfile>): void;
+  getServer(url: string): IdentityServerEntry | undefined;
+  setServer(url: string, entry: IdentityServerEntry): void;
+  removeServer(url: string): void;
+  getServers(): Map<string, IdentityServerEntry>;
+  getSpaces(): IdentitySpaceEntry[];
+  addSpace(space: IdentitySpaceEntry): void;
+  removeSpace(spaceId: string): void;
+  updateSpace(spaceId: string, updates: Partial<IdentitySpaceEntry>): void;
+  getExternalPlugins(): Y.Array<Y.Map<any>>;
+  getDisabledBuiltins(): Y.Array<string>;
+  getPreference<T = any>(key: string): T | undefined;
+  setPreference(key: string, value: any): 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 changes to the spaces array.
+   * Returns an unsubscribe function.
+   */
+  observeSpaces(callback: (event: Y.YArrayEvent<Y.Map<any>>, transaction: Y.Transaction) => void): () => void;
+  /**
+   * Returns true if the identity doc has no profile data yet (first use).
+   * Call this to decide whether to run migration from localStorage.
+   */
+  isEmpty(): boolean;
+  /**
+   * Update the sync server URL at runtime (e.g. when user changes their
+   * designated sync server in settings).
+   */
+  setSyncServer(url: string | null): void;
+  getProvider(key: string): AbracadabraProvider | undefined;
+  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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.0.21",
+  "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/AbracadabraProvider.ts

@@ -66,6 +66,13 @@ export interface AbracadabraProviderConfiguration
 
 	/** Shared WebSocket connection (use when multiplexing multiple root documents). */
 	websocketProvider?: AbracadabraWS;
+
+	/**
+	 * When true, the IndexedDB offline store is NOT scoped by server origin.
+	 * This allows a single document to be synced across multiple servers while
+	 * sharing one local store.  Used for the identity doc.
+	 */
+	serverAgnostic?: boolean;
 }
 
 /** Validate that a string is a UUID acceptable by the server's DocId parser. */
@@ -134,7 +141,9 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		this.abracadabraConfig = configuration;
 		this.subdocLoading = configuration.subdocLoading ?? "lazy";
 
-		const serverOrigin = AbracadabraProvider.deriveServerOrigin(configuration, client);
+		const serverOrigin = configuration.serverAgnostic
+			? undefined
+			: AbracadabraProvider.deriveServerOrigin(configuration, client);
 		this.offlineStore = configuration.disableOfflineStore
 			? null
 			: new OfflineStore(configuration.name, serverOrigin);