@abraca/dabra 0.8.0 → 1.0.0

package/src/AbracadabraClient.ts

@@ -9,8 +9,13 @@ import type {
 	ServerInfo,
 	InviteRow,
 } from "./types.ts";
+import type { DocEncryptionInfo } from "./types.ts";
 import type { DocumentCache } from "./DocumentCache.ts";
 
+function fromBase64(b64: string): Uint8Array {
+	return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
 export interface AbracadabraClientConfig {
 	/** Server base URL (http or https). WebSocket URL is derived automatically. */
 	url: string;
@@ -166,8 +171,8 @@ export class AbracadabraClient {
 	}
 
 	/** Add a new Ed25519 public key to the current user (multi-device). */
-	async addKey(opts: { publicKey: string; deviceName?: string }): Promise<void> {
-		await this.request("POST", "/auth/keys", { body: opts });
+	async addKey(opts: { publicKey: string; deviceName?: string; x25519Key?: string }): Promise<void> {
+		await this.request("POST", "/auth/keys", { body: { publicKey: opts.publicKey, deviceName: opts.deviceName, x25519Key: opts.x25519Key } });
 	}
 
 	/** List all registered public keys for the current user. */
@@ -181,6 +186,78 @@ export class AbracadabraClient {
 		await this.request("DELETE", `/auth/keys/${encodeURIComponent(keyId)}`);
 	}
 
+	// ── Encryption ───────────────────────────────────────────────────────────
+
+	/** Get encryption info for a document. */
+	async getDocEncryption(docId: string): Promise<DocEncryptionInfo> {
+		return this.request<DocEncryptionInfo>("GET", `/docs/${encodeURIComponent(docId)}/encryption`);
+	}
+
+	/** Set the encryption mode for a document (no downgrade). */
+	async setDocEncryption(docId: string, mode: "none" | "cse" | "e2e"): Promise<void> {
+		await this.request("PATCH", `/docs/${encodeURIComponent(docId)}/encryption`, { body: { mode } });
+	}
+
+	/** Get the caller's key envelope for a document (for decrypting the DocKey). */
+	async getMyKeyEnvelope(docId: string): Promise<{ encrypted_key: string; key_epoch: number } | null> {
+		try {
+			return await this.request<{ encrypted_key: string; key_epoch: number }>(
+				"GET",
+				`/docs/${encodeURIComponent(docId)}/key-envelope`,
+			);
+		} catch (e: unknown) {
+			if (typeof e === "object" && e !== null && "status" in e && (e as { status: number }).status === 404) {
+				return null;
+			}
+			throw e;
+		}
+	}
+
+	/** Upload key envelopes for a document (Owner only). */
+	async uploadKeyEnvelopes(
+		docId: string,
+		opts: { key_epoch: number; envelopes: { recipient_key_id: string; encrypted_key: string }[] },
+	): Promise<void> {
+		await this.request("POST", `/docs/${encodeURIComponent(docId)}/key-envelopes`, { body: opts });
+	}
+
+	/** Get the X25519 public key for a user. */
+	async getUserX25519Key(userId: string): Promise<string | null> {
+		try {
+			const res = await this.request<{ x25519_key: string }>(
+				"GET",
+				`/users/${encodeURIComponent(userId)}/x25519-key`,
+			);
+			return res.x25519_key;
+		} catch (e: unknown) {
+			if (typeof e === "object" && e !== null && "status" in e && (e as { status: number }).status === 404) {
+				return null;
+			}
+			throw e;
+		}
+	}
+
+	/** List all non-revoked keys for a user (Owner/Admin or self). */
+	async listUserKeys(userId: string): Promise<{ id: string; publicKey: string; x25519Key: string | null }[]> {
+		const res = await this.request<{ keys: { id: string; publicKey: string; x25519Key: string | null }[] }>(
+			"GET",
+			`/users/${encodeURIComponent(userId)}/keys`,
+		);
+		return res.keys;
+	}
+
+	/** Fetch encrypted E2E update blobs since a given sequence number. */
+	async getE2EUpdatesSince(docId: string, sinceSeq: number): Promise<{ seq: number; data: Uint8Array }[]> {
+		const res = await this.request<{ updates: { seq: number; data: string }[] }>(
+			"GET",
+			`/docs/${encodeURIComponent(docId)}/e2e-updates?since_seq=${sinceSeq}`,
+		);
+		return res.updates.map((u) => ({
+			seq: u.seq,
+			data: fromBase64(u.data),
+		}));
+	}
+
 	/** Clear token from memory and storage. */
 	logout(): void {
 		this.token = null;

package/src/AbracadabraProvider.ts

@@ -13,6 +13,8 @@ import type {
 } from "./types.ts";
 import { AuthenticationMessage } from "./OutgoingMessages/AuthenticationMessage.ts";
 import type { AbracadabraClient } from "./AbracadabraClient.ts";
+import type { DocKeyManager } from "./DocKeyManager.ts";
+import type { CryptoIdentityKeystore } from "./CryptoIdentityKeystore.ts";
 
 export interface AbracadabraProviderConfiguration
 	extends Omit<AbracadabraBaseProviderConfiguration, "url" | "websocketProvider"> {
@@ -57,6 +59,11 @@ export interface AbracadabraProviderConfiguration
 	/** WebSocket URL. Derived from client.wsUrl if client is provided. */
 	url?: string;
 
+	/** DocKeyManager for E2E/CSE encryption key management. */
+	docKeyManager?: DocKeyManager;
+	/** Keystore for X25519 key derivation. */
+	keystore?: CryptoIdentityKeystore;
+
 	/** Shared WebSocket connection (use when multiplexing multiple root documents). */
 	websocketProvider?: AbracadabraWS;
 }
@@ -158,7 +165,7 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	 * Used to namespace the IndexedDB key so docs from different servers
 	 * never share the same database.
 	 */
-	private static deriveServerOrigin(
+	protected static deriveServerOrigin(
 		config: AbracadabraProviderConfiguration,
 		client: AbracadabraClient | null,
 	): string | undefined {
@@ -208,8 +215,16 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	override authenticatedHandler(scope: string) {
 		super.authenticatedHandler(scope);
 
-		this.effectiveRole =
-			scope === "read-write" ? "editor" : "viewer";
+		const roleMap: Record<string, import("./types.ts").EffectiveRole> = {
+			service: "service",
+			admin: "admin",
+			owner: "owner",
+			editor: "editor",
+			viewer: "viewer",
+			"read-write": "editor",
+			readonly: "viewer",
+		};
+		this.effectiveRole = roleMap[scope] ?? "viewer";
 
 		this.offlineStore?.savePermissionSnapshot(this.effectiveRole);
 	}
@@ -283,7 +298,7 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	}
 
 	get canWrite(): boolean {
-		return this.effectiveRole === "owner" || this.effectiveRole === "editor";
+		return this.effectiveRole != null && this.effectiveRole !== "viewer";
 	}
 
 	/** The AbracadabraClient instance for REST API access, if configured. */
@@ -291,6 +306,11 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		return this._client;
 	}
 
+	/** The OfflineStore instance, or null if offline storage is disabled. */
+	get store(): OfflineStore | null {
+		return this.offlineStore;
+	}
+
 	// ── Stateless message interception ────────────────────────────────────────
 
 	/**
@@ -441,6 +461,8 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			client: this._client ?? undefined,
 			cryptoIdentity: this.abracadabraConfig.cryptoIdentity,
 			signChallenge: this.abracadabraConfig.signChallenge,
+			docKeyManager: this.abracadabraConfig.docKeyManager,
+			keystore: this.abracadabraConfig.keystore,
 		});
 
 		this.childProviders.set(childId, childProvider);

package/src/BackgroundSyncManager.ts

@@ -0,0 +1,400 @@
+/**
+ * BackgroundSyncManager
+ *
+ * Proactively syncs all documents in the root tree map to IndexedDB so they
+ * are available offline even if the user has never opened them directly.
+ *
+ * Key behaviours:
+ *  - Priority queue: sorted by updatedAt desc → never-synced first → errored last
+ *  - Concurrency: semaphore (default 2 parallel WS connections)
+ *  - Provider selection: non-E2E via rootProvider.loadChild(); E2E via
+ *    E2EAbracadabraProvider directly when docKeyManager + keystore are present
+ *  - File pre-caching: after sync, walks the Y.Doc for file refs and warms
+ *    the FileBlobStore cache (opt-in via prefetchFiles, default true)
+ *  - Cover images: at start of syncAll(), pre-caches all cover upload IDs
+ *    from the root tree map immediately (fire-and-forget)
+ *  - Periodic sync: startPeriodicSync() returns a cleanup function
+ *
+ * Note: This is in-page only (no Service Worker).  The existing
+ * flushPendingUpdates() handles offline → reconnect for open docs.
+ */
+
+import * as Y from "yjs";
+import type { AbracadabraProvider } from "./AbracadabraProvider.ts";
+import type { AbracadabraClient } from "./AbracadabraClient.ts";
+import type { FileBlobStore } from "./FileBlobStore.ts";
+import {
+	BackgroundSyncPersistence,
+	type DocSyncState,
+} from "./BackgroundSyncPersistence.ts";
+import EventEmitter from "./EventEmitter.ts";
+import { E2EAbracadabraProvider } from "./E2EAbracadabraProvider.ts";
+
+export interface BackgroundSyncManagerOptions {
+	/** Max parallel WS connections for background sync. Default: 2. */
+	concurrency?: number;
+	/** Timeout (ms) waiting for a provider to sync. Default: 15 000. */
+	syncTimeout?: number;
+	/** Pre-cache file blobs after syncing a doc. Default: true. */
+	prefetchFiles?: boolean;
+}
+
+/**
+ * Simple semaphore for capping concurrency.
+ */
+class Semaphore {
+	private slots: number;
+	private queue: Array<() => void> = [];
+
+	constructor(limit: number) {
+		this.slots = limit;
+	}
+
+	acquire(): Promise<void> {
+		if (this.slots > 0) {
+			this.slots--;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => this.queue.push(resolve));
+	}
+
+	release(): void {
+		const next = this.queue.shift();
+		if (next) {
+			next();
+		} else {
+			this.slots++;
+		}
+	}
+}
+
+export class BackgroundSyncManager extends EventEmitter {
+	private readonly rootProvider: AbracadabraProvider;
+	private readonly client: AbracadabraClient;
+	private readonly fileBlobStore: FileBlobStore | null;
+	private readonly opts: Required<BackgroundSyncManagerOptions>;
+
+	private readonly persistence: BackgroundSyncPersistence;
+	private readonly semaphore: Semaphore;
+	private readonly syncStates = new Map<string, DocSyncState>();
+
+	private _destroyed = false;
+
+	constructor(
+		rootProvider: AbracadabraProvider,
+		client: AbracadabraClient,
+		fileBlobStore?: FileBlobStore | null,
+		opts?: BackgroundSyncManagerOptions,
+	) {
+		super();
+		this.rootProvider = rootProvider;
+		this.client = client;
+		this.fileBlobStore = fileBlobStore ?? null;
+		this.opts = {
+			concurrency: opts?.concurrency ?? 2,
+			syncTimeout: opts?.syncTimeout ?? 15_000,
+			prefetchFiles: opts?.prefetchFiles ?? true,
+		};
+
+		// Derive server origin from client URL for IDB namespacing
+		let serverOrigin = "default";
+		try {
+			serverOrigin = new URL((client as any).baseUrl ?? "").hostname;
+		} catch {}
+
+		this.persistence = new BackgroundSyncPersistence(serverOrigin);
+		this.semaphore = new Semaphore(this.opts.concurrency);
+	}
+
+	// ── Public API ────────────────────────────────────────────────────────────
+
+	/** Sync all documents in the root tree. */
+	async syncAll(): Promise<void> {
+		if (this._destroyed) return;
+
+		const treeMap = this.rootProvider.document.getMap("doc-tree") as Y.Map<any>;
+		const entries = Array.from(treeMap.entries()) as Array<[string, any]>;
+
+		if (entries.length === 0) return;
+
+		// Pre-cache cover images immediately (fire-and-forget)
+		this._prefetchCovers(entries).catch(() => null);
+
+		// Build the priority queue
+		const queue = this._buildQueue(entries);
+
+		// Sync all docs respecting concurrency limit
+		await Promise.all(queue.map((docId) => this._syncWithSemaphore(docId)));
+	}
+
+	/** Sync a single document by ID. */
+	async syncDoc(docId: string): Promise<DocSyncState> {
+		const state = await this._doSyncDoc(docId);
+		this.syncStates.set(docId, state);
+		await this.persistence.setState(state).catch(() => null);
+		this.emit("stateChanged", { docId, state });
+		return state;
+	}
+
+	/** Return a snapshot of all known sync states. */
+	getSyncStatus(): Map<string, DocSyncState> {
+		return new Map(this.syncStates);
+	}
+
+	/**
+	 * Start periodic background sync.
+	 * @param intervalMs  Interval between sync runs. Default: 5 minutes.
+	 * @returns Cleanup function to stop the periodic sync.
+	 */
+	startPeriodicSync(intervalMs = 5 * 60 * 1000): () => void {
+		const handle = setInterval(() => {
+			if (!this._destroyed) {
+				this.syncAll().catch(() => null);
+			}
+		}, intervalMs);
+		return () => clearInterval(handle);
+	}
+
+	destroy(): void {
+		this._destroyed = true;
+		this.removeAllListeners();
+	}
+
+	// ── Internal ──────────────────────────────────────────────────────────────
+
+	/**
+	 * Build a priority-sorted list of doc IDs:
+	 *  1. Never-synced docs first (lastSynced === null, status !== "error")
+	 *  2. Synced docs sorted by updatedAt desc (most-recently-edited first)
+	 *  3. Errored docs last
+	 */
+	private _buildQueue(entries: Array<[string, any]>): string[] {
+		type Sortable = { docId: string; priority: number };
+
+		const items: Sortable[] = entries.map(([docId, v]) => {
+			const state = this.syncStates.get(docId);
+			const updatedAt: number = v?.updatedAt ?? v?.createdAt ?? 0;
+
+			let priority: number;
+			if (!state || state.status === "pending") {
+				// Never synced — high priority (large number so it sorts first when DESC)
+				priority = Number.MAX_SAFE_INTEGER - updatedAt;
+			} else if (state.status === "error") {
+				// Errored — lowest priority (large negative offset)
+				priority = -1;
+			} else {
+				// Synced — sort by updatedAt desc (most recent = highest priority)
+				priority = updatedAt;
+			}
+			return { docId, priority };
+		});
+
+		// Sort descending by priority
+		items.sort((a, b) => b.priority - a.priority);
+		return items.map((i) => i.docId);
+	}
+
+	private async _syncWithSemaphore(docId: string): Promise<void> {
+		if (this._destroyed) return;
+		await this.semaphore.acquire();
+		try {
+			const state = await this._doSyncDoc(docId);
+			this.syncStates.set(docId, state);
+			await this.persistence.setState(state).catch(() => null);
+			this.emit("stateChanged", { docId, state });
+		} finally {
+			this.semaphore.release();
+		}
+	}
+
+	private async _doSyncDoc(docId: string): Promise<DocSyncState> {
+		// Mark as syncing
+		const syncing: DocSyncState = {
+			docId,
+			status: "syncing",
+			lastSynced: this.syncStates.get(docId)?.lastSynced ?? null,
+			isE2E: false,
+		};
+		this.syncStates.set(docId, syncing);
+		this.emit("stateChanged", { docId, state: syncing });
+
+		try {
+			// Check encryption type
+			let isE2E = false;
+			try {
+				const enc = await this.client.getDocEncryption(docId);
+				isE2E = enc.mode === "e2e";
+			} catch {
+				// If we can't check, treat as non-E2E
+			}
+
+			if (isE2E) {
+				return await this._syncE2EDoc(docId);
+			} else {
+				return await this._syncNonE2EDoc(docId);
+			}
+		} catch (err) {
+			const error = err instanceof Error ? err.message : String(err);
+			return {
+				docId,
+				status: "error",
+				lastSynced: this.syncStates.get(docId)?.lastSynced ?? null,
+				error,
+				isE2E: false,
+			};
+		}
+	}
+
+	private async _syncNonE2EDoc(docId: string): Promise<DocSyncState> {
+		// loadChild() returns cached provider if already open
+		const childProvider = await this.rootProvider.loadChild(docId);
+
+		// Wait for ready (offline snapshot loaded) then synced (server sync done)
+		await childProvider.ready;
+		await this._waitForSynced(childProvider);
+
+		// Prefetch file blobs
+		if (this.opts.prefetchFiles && this.fileBlobStore) {
+			this._prefetchDocFiles(docId, childProvider.document).catch(() => null);
+		}
+
+		return { docId, status: "synced", lastSynced: Date.now(), isE2E: false };
+	}
+
+	private async _syncE2EDoc(docId: string): Promise<DocSyncState> {
+		// Attempt E2E sync only when docKeyManager and keystore are available
+		const docKeyManager = (this.rootProvider as any).abracadabraConfig
+			?.docKeyManager;
+		const keystore = (this.rootProvider as any).abracadabraConfig?.keystore;
+
+		if (!docKeyManager || !keystore) {
+			// No key management configured — skip silently
+			return { docId, status: "skipped", lastSynced: null, isE2E: true };
+		}
+
+		const childDoc = new Y.Doc({ guid: docId });
+		const childProvider = new E2EAbracadabraProvider({
+			name: docId,
+			document: childDoc,
+			client: this.client,
+			docKeyManager,
+			keystore,
+		});
+
+		try {
+			await childProvider.ready;
+			await this._waitForSynced(childProvider);
+
+			if (this.opts.prefetchFiles && this.fileBlobStore) {
+				this._prefetchDocFiles(docId, childDoc).catch(() => null);
+			}
+
+			return { docId, status: "synced", lastSynced: Date.now(), isE2E: true };
+		} finally {
+			childProvider.destroy();
+		}
+	}
+
+	/**
+	 * Wait for a provider to emit the "synced" event (with state=true),
+	 * timing out after opts.syncTimeout ms.
+	 */
+	private _waitForSynced(provider: any): Promise<void> {
+		// If already synced, resolve immediately
+		if (provider.synced === true) return Promise.resolve();
+
+		return new Promise<void>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				provider.off("synced", onSynced);
+				reject(new Error(`Sync timeout after ${this.opts.syncTimeout}ms`));
+			}, this.opts.syncTimeout);
+
+			function onSynced(state: boolean | { state: boolean }) {
+				// Hocuspocus passes `{ state }` or a boolean directly
+				const synced =
+					typeof state === "boolean" ? state : (state as any)?.state ?? state;
+				if (synced) {
+					clearTimeout(timer);
+					provider.off("synced", onSynced);
+					resolve();
+				}
+			}
+
+			provider.on("synced", onSynced);
+		});
+	}
+
+	/**
+	 * Pre-cache all cover images referenced in the root tree map.
+	 */
+	private async _prefetchCovers(entries: Array<[string, any]>): Promise<void> {
+		if (!this.fileBlobStore) return;
+		for (const [docId, v] of entries) {
+			const coverUploadId = v?.meta?.coverUploadId;
+			if (coverUploadId) {
+				this.fileBlobStore.getBlobUrl(docId, coverUploadId).catch(() => null);
+			}
+		}
+	}
+
+	/**
+	 * Pre-cache file blobs referenced in a synced Y.Doc.
+	 * Walks:
+	 *  - ydoc.getXmlFragment('default') for `fileBlock` nodes (TipTap)
+	 *  - ydoc.getMap('doc-tree') for meta.coverUploadId entries
+	 */
+	private async _prefetchDocFiles(
+		docId: string,
+		ydoc: Y.Doc,
+	): Promise<void> {
+		if (!this.fileBlobStore) return;
+
+		const refs = this._extractFileRefs(ydoc);
+		for (const { refDocId, uploadId } of refs) {
+			this.fileBlobStore
+				.getBlobUrl(refDocId ?? docId, uploadId)
+				.catch(() => null);
+		}
+	}
+
+	private _extractFileRefs(
+		ydoc: Y.Doc,
+	): Array<{ refDocId: string | null; uploadId: string }> {
+		const refs: Array<{ refDocId: string | null; uploadId: string }> = [];
+
+		// Walk XML fragment for fileBlock nodes
+		try {
+			const fragment = ydoc.getXmlFragment("default");
+			this._walkXml(fragment, refs);
+		} catch {}
+
+		// Walk doc-tree meta for cover upload IDs
+		try {
+			const treeMap = ydoc.getMap("doc-tree") as Y.Map<any>;
+			for (const [id, v] of treeMap.entries()) {
+				const coverUploadId = v?.meta?.coverUploadId;
+				if (coverUploadId) {
+					refs.push({ refDocId: id, uploadId: coverUploadId });
+				}
+			}
+		} catch {}
+
+		return refs;
+	}
+
+	private _walkXml(
+		node: Y.XmlFragment | Y.XmlElement,
+		refs: Array<{ refDocId: string | null; uploadId: string }>,
+	): void {
+		for (const child of node.toArray()) {
+			if (child instanceof Y.XmlElement) {
+				if (child.nodeName === "fileBlock") {
+					const uploadId = child.getAttribute("uploadId");
+					const refDocId = child.getAttribute("docId") ?? null;
+					if (uploadId) refs.push({ refDocId, uploadId });
+				}
+				this._walkXml(child, refs);
+			}
+		}
+	}
+}

package/src/BackgroundSyncPersistence.ts

@@ -0,0 +1,107 @@
+/**
+ * BackgroundSyncPersistence
+ *
+ * Minimal IndexedDB store (`abracadabra:bgsync:{serverOrigin}`) that persists
+ * per-document sync state across page reloads.  A single object store,
+ * `sync_state`, is keyed by `docId`.
+ *
+ * Falls back to a no-op when IndexedDB is unavailable (SSR / Node.js).
+ */
+
+export interface DocSyncState {
+	docId: string;
+	/** Current lifecycle status of this document's background sync. */
+	status: "pending" | "syncing" | "synced" | "error" | "skipped";
+	/** Unix ms of the last successful sync, or null if never synced. */
+	lastSynced: number | null;
+	/** Human-readable error message if status === "error". */
+	error?: string;
+	/** Whether the document uses E2E encryption. */
+	isE2E: boolean;
+}
+
+const DB_VERSION = 1;
+
+function idbAvailable(): boolean {
+	return typeof globalThis !== "undefined" && "indexedDB" in globalThis;
+}
+
+function openDb(serverOrigin: string): Promise<IDBDatabase> {
+	return new Promise((resolve, reject) => {
+		const req = globalThis.indexedDB.open(
+			`abracadabra:bgsync:${serverOrigin}`,
+			DB_VERSION,
+		);
+		req.onupgradeneeded = (event) => {
+			const db = (event.target as IDBOpenDBRequest).result;
+			if (!db.objectStoreNames.contains("sync_state")) {
+				db.createObjectStore("sync_state", { keyPath: "docId" });
+			}
+		};
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => reject(req.error);
+	});
+}
+
+function idbPromise<T>(request: IDBRequest<T>): Promise<T> {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+
+export class BackgroundSyncPersistence {
+	private dbPromise: Promise<IDBDatabase | null> | null = null;
+	private readonly serverOrigin: string;
+
+	constructor(serverOrigin: string) {
+		this.serverOrigin = serverOrigin;
+	}
+
+	private getDb(): Promise<IDBDatabase | null> {
+		if (!idbAvailable()) return Promise.resolve(null);
+		if (!this.dbPromise) {
+			this.dbPromise = openDb(this.serverOrigin).catch(() => null);
+		}
+		return this.dbPromise;
+	}
+
+	async getState(docId: string): Promise<DocSyncState | null> {
+		const db = await this.getDb();
+		if (!db) return null;
+		const tx = db.transaction("sync_state", "readonly");
+		const result = await idbPromise<DocSyncState | undefined>(
+			tx.objectStore("sync_state").get(docId),
+		);
+		return result ?? null;
+	}
+
+	async getAllStates(): Promise<DocSyncState[]> {
+		const db = await this.getDb();
+		if (!db) return [];
+		return new Promise((resolve, reject) => {
+			const tx = db.transaction("sync_state", "readonly");
+			const req = tx.objectStore("sync_state").getAll();
+			req.onsuccess = () => resolve(req.result as DocSyncState[]);
+			req.onerror = () => reject(req.error);
+		});
+	}
+
+	async setState(state: DocSyncState): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("sync_state", "readwrite");
+		await idbPromise(tx.objectStore("sync_state").put(state));
+	}
+
+	async deleteState(docId: string): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("sync_state", "readwrite");
+		await idbPromise(tx.objectStore("sync_state").delete(docId));
+	}
+
+	destroy(): void {
+		// No cleanup needed — shared IDB connection managed by browser
+	}
+}