@abraca/dabra 1.0.21 → 1.0.22

package/dist/index.d.ts

@@ -621,6 +621,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:
@@ -2342,4 +2348,145 @@ 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>)>;
+  /**
+   * 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;
+  private _connectToServer;
+  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.22",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

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);

package/src/IdentityDoc.ts

@@ -0,0 +1,497 @@
+import * as Y from "yjs";
+import { sha256 } from "@noble/hashes/sha256";
+import EventEmitter from "./EventEmitter.ts";
+import { AbracadabraProvider } from "./AbracadabraProvider.ts";
+import type { AbracadabraProviderConfiguration } from "./AbracadabraProvider.ts";
+import { AbracadabraWS } from "./AbracadabraWS.ts";
+import { AbracadabraWebRTC } from "./webrtc/AbracadabraWebRTC.ts";
+import type { E2EEIdentity } from "./webrtc/E2EEChannel.ts";
+
+// ── Identity Doc ID Derivation ─────────────────────────────────────────────
+
+/**
+ * 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).
+ */
+export function deriveIdentityDocId(publicKeyB64: string): string {
+	const hash = sha256(
+		new TextEncoder().encode(`abracadabra:identity:${publicKeyB64}`),
+	);
+	const bytes = new Uint8Array(hash.buffer, hash.byteOffset, 16);
+	// Set UUID version 5 + variant 1 bits.
+	bytes[6] = (bytes[6] & 0x0f) | 0x50;
+	bytes[8] = (bytes[8] & 0x3f) | 0x80;
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
+		"",
+	);
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface IdentityProfile {
+	username?: string;
+	displayName?: string;
+	colorName?: string;
+	neutralColorName?: string;
+	locale?: string;
+	avatarUrl?: string;
+}
+
+export interface IdentityServerEntry {
+	label: string;
+	hubDocId?: string;
+	entryDocId?: string;
+	defaultRole?: string;
+	spacesEnabled?: boolean;
+	addedAt: number;
+}
+
+export 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;
+}
+
+export 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>)>;
+
+	/**
+	 * 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>;
+}
+
+// ── IdentityDocProvider ────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export class IdentityDocProvider extends EventEmitter {
+	public readonly docId: string;
+	public readonly document: Y.Doc;
+
+	private providers = new Map<string, AbracadabraProvider>();
+	private websockets = new Map<string, AbracadabraWS>();
+	private webrtc: AbracadabraWebRTC | null = null;
+	private config: IdentityDocConfiguration;
+	private _destroyed = false;
+
+	constructor(configuration: IdentityDocConfiguration) {
+		super();
+		this.config = configuration;
+		this.docId = deriveIdentityDocId(configuration.publicKey);
+		this.document = new Y.Doc({ guid: this.docId });
+
+		if (configuration.autoConnect !== false) {
+			this.connect();
+		}
+	}
+
+	// ── Connection Management ────────────────────────────────────────────────
+
+	connect(): void {
+		if (this._destroyed) return;
+
+		const targets: Array<{ url: string; key: string }> = [];
+
+		if (this.config.localServerUrl) {
+			targets.push({ url: this.config.localServerUrl, key: "local" });
+		}
+		if (this.config.syncServerUrl) {
+			targets.push({ url: this.config.syncServerUrl, key: "sync" });
+		}
+
+		for (const { url, key } of targets) {
+			if (this.providers.has(key)) continue;
+			this._connectToServer(key, url);
+		}
+
+		if (this.config.webrtc && !this.webrtc) {
+			this._connectWebRTC();
+		}
+	}
+
+	private _connectToServer(key: string, serverUrl: string): void {
+		const token =
+			this.config.tokens?.[serverUrl] ?? this.config.token ?? "";
+
+		const wsUrl = serverUrl
+			.replace(/^http/, "ws")
+			.replace(/\/$/, "")
+			.concat("/ws");
+
+		const ws = new AbracadabraWS({ url: wsUrl, WebSocketPolyfill: undefined as any });
+		this.websockets.set(key, ws);
+
+		const provider = new AbracadabraProvider({
+			name: this.docId,
+			document: this.document,
+			websocketProvider: ws,
+			token,
+			serverAgnostic: true,
+			disableOfflineStore: key !== "local" && key !== "sync"
+				? true
+				: this.config.disableOfflineStore ?? false,
+			...this.config.providerDefaults,
+		});
+
+		provider.on("synced", () => this.emit("synced", { server: key }));
+		provider.on("status", (data: any) =>
+			this.emit("status", { server: key, ...data }),
+		);
+
+		this.providers.set(key, provider);
+	}
+
+	private _connectWebRTC(): void {
+		const rtcConfig = this.config.webrtc;
+		if (!rtcConfig) return;
+
+		this.webrtc = new AbracadabraWebRTC({
+			docId: this.docId,
+			url: rtcConfig.signalingServerUrl,
+			token: rtcConfig.token,
+			document: this.document,
+			enableDocSync: true,
+			enableAwarenessSync: false,
+			enableFileTransfer: false,
+			e2ee: rtcConfig.e2ee,
+			iceServers: rtcConfig.iceServers,
+		});
+	}
+
+	// ── Y.Doc Schema Accessors ───────────────────────────────────────────────
+
+	get profileMap(): Y.Map<string> {
+		return this.document.getMap("profile");
+	}
+
+	get serversMap(): Y.Map<Y.Map<any>> {
+		return this.document.getMap("servers");
+	}
+
+	get spacesArray(): Y.Array<Y.Map<any>> {
+		return this.document.getArray("spaces");
+	}
+
+	get pluginsMap(): Y.Map<any> {
+		return this.document.getMap("plugins");
+	}
+
+	get preferencesMap(): Y.Map<any> {
+		return this.document.getMap("preferences");
+	}
+
+	// ── Profile ──────────────────────────────────────────────────────────────
+
+	getProfile(): IdentityProfile {
+		const m = this.profileMap;
+		return {
+			username: m.get("username"),
+			displayName: m.get("displayName"),
+			colorName: m.get("colorName"),
+			neutralColorName: m.get("neutralColorName"),
+			locale: m.get("locale"),
+			avatarUrl: m.get("avatarUrl"),
+		};
+	}
+
+	setProfile(profile: Partial<IdentityProfile>): void {
+		const m = this.profileMap;
+		this.document.transact(() => {
+			for (const [key, value] of Object.entries(profile)) {
+				if (value !== undefined) {
+					m.set(key, value);
+				}
+			}
+		});
+	}
+
+	// ── Servers ──────────────────────────────────────────────────────────────
+
+	getServer(url: string): IdentityServerEntry | undefined {
+		const entry = this.serversMap.get(url);
+		if (!entry) return undefined;
+		return {
+			label: entry.get("label") ?? url,
+			hubDocId: entry.get("hubDocId"),
+			entryDocId: entry.get("entryDocId"),
+			defaultRole: entry.get("defaultRole"),
+			spacesEnabled: entry.get("spacesEnabled"),
+			addedAt: entry.get("addedAt") ?? 0,
+		};
+	}
+
+	setServer(url: string, entry: IdentityServerEntry): void {
+		const m = this.serversMap;
+		this.document.transact(() => {
+			let yEntry = m.get(url);
+			if (!yEntry) {
+				yEntry = new Y.Map();
+				m.set(url, yEntry);
+			}
+			for (const [key, value] of Object.entries(entry)) {
+				if (value !== undefined) {
+					yEntry.set(key, value);
+				}
+			}
+		});
+	}
+
+	removeServer(url: string): void {
+		this.serversMap.delete(url);
+	}
+
+	getServers(): Map<string, IdentityServerEntry> {
+		const result = new Map<string, IdentityServerEntry>();
+		this.serversMap.forEach((entry, url) => {
+			result.set(url, {
+				label: entry.get("label") ?? url,
+				hubDocId: entry.get("hubDocId"),
+				entryDocId: entry.get("entryDocId"),
+				defaultRole: entry.get("defaultRole"),
+				spacesEnabled: entry.get("spacesEnabled"),
+				addedAt: entry.get("addedAt") ?? 0,
+			});
+		});
+		return result;
+	}
+
+	// ── Spaces ───────────────────────────────────────────────────────────────
+
+	getSpaces(): IdentitySpaceEntry[] {
+		const result: IdentitySpaceEntry[] = [];
+		this.spacesArray.forEach((yMap) => {
+			result.push({
+				id: yMap.get("id"),
+				name: yMap.get("name"),
+				type: yMap.get("type") ?? "remote",
+				serverUrl: yMap.get("serverUrl") ?? null,
+				docId: yMap.get("docId"),
+				remoteSpaceId: yMap.get("remoteSpaceId"),
+				visibility: yMap.get("visibility") ?? "private",
+				isHub: yMap.get("isHub") ?? false,
+				order: yMap.get("order") ?? 0,
+				lastSyncedAt: yMap.get("lastSyncedAt"),
+				createdAt: yMap.get("createdAt") ?? 0,
+			});
+		});
+		return result;
+	}
+
+	addSpace(space: IdentitySpaceEntry): void {
+		const yMap = new Y.Map();
+		this.document.transact(() => {
+			for (const [key, value] of Object.entries(space)) {
+				if (value !== undefined) {
+					yMap.set(key, value);
+				}
+			}
+			this.spacesArray.push([yMap]);
+		});
+	}
+
+	removeSpace(spaceId: string): void {
+		const arr = this.spacesArray;
+		for (let i = 0; i < arr.length; i++) {
+			if (arr.get(i).get("id") === spaceId) {
+				arr.delete(i, 1);
+				return;
+			}
+		}
+	}
+
+	updateSpace(spaceId: string, updates: Partial<IdentitySpaceEntry>): void {
+		const arr = this.spacesArray;
+		for (let i = 0; i < arr.length; i++) {
+			const yMap = arr.get(i);
+			if (yMap.get("id") === spaceId) {
+				this.document.transact(() => {
+					for (const [key, value] of Object.entries(updates)) {
+						if (value !== undefined) {
+							yMap.set(key, value);
+						}
+					}
+				});
+				return;
+			}
+		}
+	}
+
+	// ── Plugins ──────────────────────────────────────────────────────────────
+
+	getExternalPlugins(): Y.Array<Y.Map<any>> {
+		let arr = this.pluginsMap.get("external") as Y.Array<Y.Map<any>> | undefined;
+		if (!arr) {
+			arr = new Y.Array();
+			this.pluginsMap.set("external", arr);
+		}
+		return arr;
+	}
+
+	getDisabledBuiltins(): Y.Array<string> {
+		let arr = this.pluginsMap.get("disabledBuiltins") as Y.Array<string> | undefined;
+		if (!arr) {
+			arr = new Y.Array();
+			this.pluginsMap.set("disabledBuiltins", arr);
+		}
+		return arr;
+	}
+
+	// ── Preferences ──────────────────────────────────────────────────────────
+
+	getPreference<T = any>(key: string): T | undefined {
+		return this.preferencesMap.get(key);
+	}
+
+	setPreference(key: string, value: any): void {
+		this.preferencesMap.set(key, value);
+	}
+
+	// ── Observation ──────────────────────────────────────────────────────────
+
+	/**
+	 * 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 {
+		const map = this.document.getMap(mapName);
+		map.observeDeep(callback);
+		return () => map.unobserveDeep(callback);
+	}
+
+	/**
+	 * Observe changes to the spaces array.
+	 * Returns an unsubscribe function.
+	 */
+	observeSpaces(
+		callback: (event: Y.YArrayEvent<Y.Map<any>>, transaction: Y.Transaction) => void,
+	): () => void {
+		const arr = this.spacesArray;
+		arr.observe(callback);
+		return () => arr.unobserve(callback);
+	}
+
+	// ── Migration ────────────────────────────────────────────────────────────
+
+	/**
+	 * 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 {
+		return this.profileMap.size === 0 && this.serversMap.size === 0;
+	}
+
+	// ── Lifecycle ────────────────────────────────────────────────────────────
+
+	/**
+	 * Update the sync server URL at runtime (e.g. when user changes their
+	 * designated sync server in settings).
+	 */
+	setSyncServer(url: string | null): void {
+		// Tear down existing sync provider if any.
+		const existing = this.providers.get("sync");
+		if (existing) {
+			existing.destroy();
+			this.providers.delete("sync");
+		}
+		const existingWs = this.websockets.get("sync");
+		if (existingWs) {
+			existingWs.destroy();
+			this.websockets.delete("sync");
+		}
+
+		if (url) {
+			this.config = { ...this.config, syncServerUrl: url };
+			this._connectToServer("sync", url);
+		}
+	}
+
+	getProvider(key: string): AbracadabraProvider | undefined {
+		return this.providers.get(key);
+	}
+
+	destroy(): void {
+		if (this._destroyed) return;
+		this._destroyed = true;
+
+		for (const [, provider] of this.providers) {
+			provider.destroy();
+		}
+		for (const [, ws] of this.websockets) {
+			ws.destroy();
+		}
+		if (this.webrtc) {
+			(this.webrtc as any).disconnect?.();
+		}
+
+		this.providers.clear();
+		this.websockets.clear();
+		this.webrtc = null;
+		this.document.destroy();
+	}
+}