@abraca/dabra 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@abraca/dabra",
+  "version": "0.1.0",
+  "description": "abracadabra provider",
+  "keywords": [
+    "abracadabra",
+    "websocket",
+    "provider",
+    "yjs"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/abracadabra-provider.cjs",
+  "module": "dist/abracadabra-provider.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "source": {
+      "import": "./src/index.ts"
+    },
+    "default": {
+      "import": "./dist/abracadabra-provider.esm.js",
+      "require": "./dist/abracadabra-provider.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "dependencies": {
+    "@abraca/dabra-common": "workspace:^",
+    "@lifeomic/attempt": "^3.0.2",
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.4.0",
+    "lib0": "^0.2.87",
+    "ws": "^8.17.1"
+  },
+  "peerDependencies": {
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.8"
+  }
+}

package/src/AbracadabraProvider.ts

@@ -0,0 +1,381 @@
+import * as Y from "yjs";
+import { HocuspocusProvider } from "./HocuspocusProvider.ts";
+import type { HocuspocusProviderConfiguration } from "./HocuspocusProvider.ts";
+import type { HocuspocusProviderWebsocket } from "./HocuspocusProviderWebsocket.ts";
+import { OfflineStore } from "./OfflineStore.ts";
+import { SubdocMessage } from "./OutgoingMessages/SubdocMessage.ts";
+import { UpdateMessage } from "./OutgoingMessages/UpdateMessage.ts";
+import type {
+	CryptoIdentity,
+	EffectiveRole,
+	onSubdocRegisteredParameters,
+	onSubdocLoadedParameters,
+} from "./types.ts";
+import { AuthenticationMessage } from "./OutgoingMessages/AuthenticationMessage.ts";
+
+export interface AbracadabraProviderConfiguration
+	extends HocuspocusProviderConfiguration {
+	/**
+	 * Subdocument loading strategy.
+	 * - "lazy"  (default) – child providers are created only when explicitly requested.
+	 * - "eager" – all children returned by the server on connect are loaded automatically.
+	 */
+	subdocLoading?: "lazy" | "eager";
+
+	/** Called when the server confirms a subdoc registration. */
+	onSubdocRegistered?: (data: onSubdocRegisteredParameters) => void;
+
+	/** Called when a child AbracadabraProvider has been created and attached. */
+	onSubdocLoaded?: (data: onSubdocLoadedParameters) => void;
+
+	/**
+	 * Disable the IndexedDB offline store.  Useful for server-side rendering
+	 * or testing environments that lack IndexedDB.
+	 */
+	disableOfflineStore?: boolean;
+
+	/**
+	 * Identity for passwordless crypto auth (Model B multi-key).
+	 * Mutually exclusive with token.
+	 */
+	cryptoIdentity?: CryptoIdentity | (() => Promise<CryptoIdentity>);
+
+	/**
+	 * Signs a base64url challenge and returns a base64url signature.
+	 * Required when cryptoIdentity is set.
+	 */
+	signChallenge?: (challenge: string) => Promise<string>;
+}
+
+/**
+ * AbracadabraProvider extends HocuspocusProvider with:
+ *
+ *  1. Subdocument lifecycle – intercepts Y.Doc subdoc events and syncs them
+ *     with the server via MSG_SUBDOC (4) frames.  Child documents get their
+ *     own AbracadabraProvider instances sharing the same WebSocket connection.
+ *
+ *  2. Offline-first – persists CRDT updates to IndexedDB so they survive
+ *     page reloads and network outages.  On reconnect, pending updates are
+ *     flushed before resuming normal sync.
+ *
+ *  3. Permission snapshotting – stores the resolved role locally so the UI
+ *     can gate write operations without a network round-trip.  Role is
+ *     refreshed from the server on every reconnect.
+ */
+export class AbracadabraProvider extends HocuspocusProvider {
+	public effectiveRole: EffectiveRole = null;
+
+	private offlineStore: OfflineStore | null;
+	private childProviders = new Map<string, AbracadabraProvider>();
+	private subdocLoading: "lazy" | "eager";
+
+	private abracadabraConfig: AbracadabraProviderConfiguration;
+
+	private readonly boundHandleYSubdocsChange = this.handleYSubdocsChange.bind(this);
+
+	constructor(configuration: AbracadabraProviderConfiguration) {
+		super(configuration);
+		this.abracadabraConfig = configuration;
+		this.subdocLoading = configuration.subdocLoading ?? "lazy";
+
+		this.offlineStore = configuration.disableOfflineStore
+			? null
+			: new OfflineStore(configuration.name);
+
+		this.on(
+			"subdocRegistered",
+			configuration.onSubdocRegistered ?? (() => null),
+		);
+		this.on("subdocLoaded", configuration.onSubdocLoaded ?? (() => null));
+
+		// Intercept Y.Doc subdoc lifecycle events.
+		this.document.on("subdocs", this.boundHandleYSubdocsChange);
+
+		// Flush offline updates once we're back online and synced.
+		this.on("synced", () => this.flushPendingUpdates());
+
+		// Restore permission snapshot while offline.
+		this.restorePermissionSnapshot();
+	}
+
+	// ── Auth / permission snapshot ────────────────────────────────────────────
+
+	override authenticatedHandler(scope: string) {
+		super.authenticatedHandler(scope);
+
+		this.effectiveRole =
+			scope === "read-write" ? "editor" : "viewer";
+
+		this.offlineStore?.savePermissionSnapshot(this.effectiveRole);
+	}
+
+	/**
+	 * Override sendToken to send an identity declaration instead of a JWT
+	 * when cryptoIdentity is configured.
+	 */
+	override async sendToken() {
+		const { cryptoIdentity } = this.abracadabraConfig;
+		if (cryptoIdentity) {
+			const id =
+				typeof cryptoIdentity === "function"
+					? await cryptoIdentity()
+					: cryptoIdentity;
+			const json = JSON.stringify({
+				type: "identity",
+				username: id.username,
+				publicKey: id.publicKey,
+			});
+			this.send(AuthenticationMessage, {
+				token: json,
+				documentName: this.configuration.name,
+			});
+		} else {
+			await super.sendToken();
+		}
+	}
+
+	/** Handle an auth_challenge message from the server. */
+	private async handleAuthChallenge(
+		challenge: string,
+		expiresAt: number,
+	): Promise<void> {
+		const { signChallenge, cryptoIdentity } = this.abracadabraConfig;
+		if (!signChallenge || !cryptoIdentity) {
+			this.permissionDeniedHandler("No signChallenge callback configured");
+			return;
+		}
+		if (Date.now() > expiresAt * 1000) {
+			this.permissionDeniedHandler("Challenge expired");
+			return;
+		}
+		const id =
+			typeof cryptoIdentity === "function"
+				? await cryptoIdentity()
+				: cryptoIdentity;
+		const signature = await signChallenge(challenge);
+		const proof = JSON.stringify({
+			type: "proof",
+			username: id.username,
+			publicKey: id.publicKey,
+			signature,
+			challenge,
+		});
+		this.send(AuthenticationMessage, {
+			token: proof,
+			documentName: this.configuration.name,
+		});
+	}
+
+	private async restorePermissionSnapshot() {
+		if (!this.offlineStore) return;
+		const role = await this.offlineStore.getPermissionSnapshot();
+		if (role && !this.effectiveRole) {
+			this.effectiveRole = role as EffectiveRole;
+		}
+	}
+
+	get canWrite(): boolean {
+		return this.effectiveRole === "owner" || this.effectiveRole === "editor";
+	}
+
+	// ── Stateless message interception ────────────────────────────────────────
+
+	/**
+	 * Called when a MSG_STATELESS frame arrives from the server.
+	 * Abracadabra uses stateless frames to deliver subdoc confirmations
+	 * ({ type: "subdoc_registered", child_id, parent_id }).
+	 */
+	override receiveStateless(payload: string) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(payload);
+		} catch {
+			super.receiveStateless(payload);
+			return;
+		}
+
+		const msg = parsed as {
+			type?: string;
+			child_id?: string;
+			parent_id?: string;
+			challenge?: string;
+			expiresAt?: number;
+		};
+
+		// Intercept auth_challenge before subdoc handling.
+		if (msg.type === "auth_challenge" && msg.challenge && msg.expiresAt) {
+			this.handleAuthChallenge(msg.challenge, msg.expiresAt).catch(() => null);
+			return;
+		}
+
+		if (msg.type === "subdoc_registered" && msg.child_id && msg.parent_id) {
+			const event: onSubdocRegisteredParameters = {
+				childId: msg.child_id,
+				parentId: msg.parent_id,
+			};
+			this.emit("subdocRegistered", event);
+
+			// Remove from the offline queue now the server confirmed.
+			this.offlineStore?.removeSubdocFromQueue(msg.child_id);
+
+			// Eager mode: auto-load the confirmed child.
+			if (this.subdocLoading === "eager") {
+				this.loadChild(msg.child_id);
+			}
+			return;
+		}
+
+		// Unknown stateless payload – pass through to base class.
+		super.receiveStateless(payload);
+	}
+
+	// ── Subdocument support ───────────────────────────────────────────────────
+
+	/**
+	 * Y.Doc emits 'subdocs' whenever subdocuments are added, removed, or loaded.
+	 * We intercept additions to register them with the Abracadabra server.
+	 */
+	private handleYSubdocsChange({
+		added,
+		removed,
+	}: {
+		added: Set<Y.Doc>;
+		removed: Set<Y.Doc>;
+		loaded: Set<Y.Doc>;
+	}) {
+		for (const subdoc of added) {
+			this.registerSubdoc(subdoc);
+		}
+		for (const subdoc of removed) {
+			this.unloadChild(subdoc.guid);
+		}
+	}
+
+	/**
+	 * Send a subdoc registration frame to the server.
+	 * If offline the event is queued in IndexedDB and replayed on reconnect.
+	 */
+	private registerSubdoc(subdoc: Y.Doc) {
+		const childId = subdoc.guid;
+
+		if (this.isConnected) {
+			this.send(SubdocMessage, {
+				documentName: this.configuration.name,
+				childDocumentName: childId,
+			} as any);
+		} else {
+			// Queue for later replay when we reconnect.
+			this.offlineStore?.queueSubdoc({
+				childId,
+				parentId: this.configuration.name,
+				createdAt: Date.now(),
+			});
+		}
+	}
+
+	/**
+	 * Create (or return cached) a child AbracadabraProvider for a given
+	 * child document id.  The child shares the parent's WebSocket connection.
+	 */
+	async loadChild(childId: string): Promise<AbracadabraProvider> {
+		if (this.childProviders.has(childId)) {
+			return this.childProviders.get(childId)!;
+		}
+
+		const childDoc = new Y.Doc({ guid: childId });
+
+		const parentWsp = this.configuration.websocketProvider as HocuspocusProviderWebsocket;
+		const childProvider = new AbracadabraProvider({
+			name: childId,
+			document: childDoc,
+			url: parentWsp.configuration.url,
+			WebSocketPolyfill: parentWsp.configuration.WebSocketPolyfill,
+			token: this.configuration.token,
+			subdocLoading: this.subdocLoading,
+			disableOfflineStore: this.abracadabraConfig.disableOfflineStore,
+		});
+		this.childProviders.set(childId, childProvider);
+
+		this.emit("subdocLoaded", { childId, provider: childProvider });
+
+		return childProvider;
+	}
+
+	private unloadChild(childId: string) {
+		const provider = this.childProviders.get(childId);
+		if (provider) {
+			provider.destroy();
+			this.childProviders.delete(childId);
+		}
+	}
+
+	/** Return all currently-loaded child providers. */
+	get children(): Map<string, AbracadabraProvider> {
+		return this.childProviders;
+	}
+
+	// ── Offline-first update persistence ─────────────────────────────────────
+
+	/**
+	 * Override to persist every local update to IndexedDB before sending it
+	 * over the wire, ensuring no work is lost during connection outages.
+	 */
+	override documentUpdateHandler(update: Uint8Array, origin: unknown) {
+		if (origin === this) return;
+
+		// Persist locally first (fire-and-forget; errors are non-fatal).
+		this.offlineStore?.persistUpdate(update).catch(() => null);
+
+		super.documentUpdateHandler(update, origin);
+	}
+
+	/**
+	 * After reconnect + sync, flush any updates that were generated while
+	 * offline, then flush any queued subdoc registrations.
+	 */
+	private async flushPendingUpdates() {
+		if (!this.offlineStore) return;
+
+		const updates = await this.offlineStore.getPendingUpdates();
+		if (updates.length > 0) {
+			for (const update of updates) {
+				this.send(UpdateMessage, {
+					update,
+					documentName: this.configuration.name,
+				});
+			}
+			await this.offlineStore.clearPendingUpdates();
+		}
+
+		const pendingSubdocs = await this.offlineStore.getPendingSubdocs();
+		for (const { childId } of pendingSubdocs) {
+			this.send(SubdocMessage, {
+				documentName: this.configuration.name,
+				childDocumentName: childId,
+			} as any);
+		}
+	}
+
+	get isConnected(): boolean {
+		return (
+			(this.configuration.websocketProvider as HocuspocusProviderWebsocket)
+				.status === "connected"
+		);
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────────
+
+	override destroy() {
+		this.document.off("subdocs", this.boundHandleYSubdocsChange);
+
+		for (const provider of this.childProviders.values()) {
+			provider.destroy();
+		}
+		this.childProviders.clear();
+
+		this.offlineStore?.destroy();
+		this.offlineStore = null;
+
+		super.destroy();
+	}
+}