@abraca/dabra 1.0.21 → 1.0.23

package/src/IdentityDoc.ts

@@ -0,0 +1,533 @@
+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 { CryptoIdentity } from "./types.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>)>;
+
+	/**
+	 * 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>;
+}
+
+// ── 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();
+		}
+	}
+
+	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 ?? "";
+
+		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 providerConfig: AbracadabraProviderConfiguration = {
+			name: this.docId,
+			document: this.document,
+			websocketProvider: ws,
+			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) =>
+			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();
+	}
+}

package/src/index.ts

@@ -25,3 +25,10 @@ export { BackgroundSyncPersistence } from "./BackgroundSyncPersistence.ts";
 export type { DocSyncState } from "./BackgroundSyncPersistence.ts";
 export * from "./webrtc/index.ts";
 export { BroadcastChannelSync } from "./sync/BroadcastChannelSync.ts";
+export { IdentityDocProvider, deriveIdentityDocId } from "./IdentityDoc.ts";
+export type {
+	IdentityDocConfiguration,
+	IdentityProfile,
+	IdentityServerEntry,
+	IdentitySpaceEntry,
+} from "./IdentityDoc.ts";