@abraca/dabra 0.9.0 → 1.0.0

package/src/CryptoIdentityKeystore.ts

@@ -14,6 +14,7 @@
 import * as ed from "@noble/ed25519";
 import { hkdf } from "@noble/hashes/hkdf";
 import { sha256 } from "@noble/hashes/sha256";
+import { ed25519 as nobleEd25519Curves } from "@noble/curves/ed25519.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -125,7 +126,7 @@ export class CryptoIdentityKeystore {
 	 * @param rpId      - WebAuthn relying party ID (e.g. "example.com").
 	 * @param rpName    - Human-readable relying party name.
 	 */
-	async register(username: string, rpId: string, rpName: string): Promise<string> {
+	async register(username: string, rpId: string, rpName: string): Promise<{publicKey: string; x25519PublicKey: string}> {
 		// 1. Generate Ed25519 keypair
 		const privateKey = ed.utils.randomPrivateKey();
 		const publicKey = await ed.getPublicKeyAsync(privateKey);
@@ -194,7 +195,8 @@ export class CryptoIdentityKeystore {
 		});
 		db.close();
 
-		return toBase64url(publicKey);
+		const x25519Pub = nobleEd25519Curves.utils.toMontgomery(publicKey);
+		return { publicKey: toBase64url(publicKey), x25519PublicKey: toBase64url(x25519Pub) };
 	}
 
 	/**
@@ -303,4 +305,65 @@ export class CryptoIdentityKeystore {
 		await dbDelete(db);
 		db.close();
 	}
+
+	/**
+	 * Returns the X25519 public key derived from the stored Ed25519 private key.
+	 * Does NOT require WebAuthn — computed from the stored encrypted key... actually
+	 * we derive from the Ed25519 public key directly (Montgomery form), no decryption needed
+	 * since nobleEd25519Curves.utils.toMontgomery only needs the public key.
+	 * Returns null if no identity is stored.
+	 */
+	async getX25519PublicKey(): Promise<Uint8Array | null> {
+		const db = await openDb();
+		const stored = await dbGet(db);
+		db.close();
+		if (!stored) return null;
+		const edPub = fromBase64url(stored.publicKey);
+		return nobleEd25519Curves.utils.toMontgomery(edPub);
+	}
+
+	/**
+	 * Returns the X25519 private key derived from the stored Ed25519 private key.
+	 * Requires WebAuthn assertion to decrypt the private key.
+	 * The caller MUST wipe the returned Uint8Array after use.
+	 */
+	async getX25519PrivateKey(): Promise<Uint8Array> {
+		const db = await openDb();
+		const stored = await dbGet(db);
+		db.close();
+
+		if (!stored) {
+			throw new Error("No identity stored. Call register() first.");
+		}
+
+		const assertion = await navigator.credentials.get({
+			publicKey: {
+				challenge: crypto.getRandomValues(new Uint8Array(32)),
+				allowCredentials: [{ id: stored.credentialId, type: "public-key" }],
+				userVerification: "required",
+				extensions: {
+					prf: { eval: { first: stored.salt.buffer } },
+				} as AuthenticationExtensionsClientInputs,
+			},
+		}) as PublicKeyCredential | null;
+
+		if (!assertion) throw new Error("WebAuthn assertion failed");
+
+		const extResults = assertion.getClientExtensionResults() as {
+			prf?: { results?: { first?: ArrayBuffer } };
+		};
+		const prfOutput = extResults?.prf?.results?.first;
+		if (!prfOutput) throw new Error("PRF output not available from authenticator");
+
+		const aesKey = await deriveAesKey(prfOutput, stored.salt);
+		const privateKeyBytes = await crypto.subtle.decrypt(
+			{ name: "AES-GCM", iv: stored.iv },
+			aesKey,
+			stored.encryptedPrivateKey,
+		);
+		const edPrivKey = new Uint8Array(privateKeyBytes);
+		const x25519Priv = nobleEd25519Curves.utils.toMontgomerySecret(edPrivKey);
+		edPrivKey.fill(0);
+		return x25519Priv;
+	}
 }

package/src/DocKeyManager.ts

@@ -0,0 +1,107 @@
+/**
+ * DocKeyManager
+ *
+ * Manages AES-256-GCM document keys for CSE and E2E encrypted documents.
+ * Keys are wrapped per-user using X25519 ECDH + HKDF-SHA256 + AES-256-GCM.
+ */
+
+import { x25519 } from "@noble/curves/ed25519.js";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import type { AbracadabraClient } from "./AbracadabraClient.ts";
+import type { CryptoIdentityKeystore } from "./CryptoIdentityKeystore.ts";
+
+const HKDF_INFO = new TextEncoder().encode("abracadabra-dockey-v1");
+
+function fromBase64(b64: string): Uint8Array {
+	return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
+export class DocKeyManager {
+	private cache = new Map<string, { key: CryptoKey; epoch: number }>();
+
+	/** Generate a new random AES-256-GCM document key. */
+	static async generateDocKey(): Promise<CryptoKey> {
+		return crypto.subtle.generateKey(
+			{ name: "AES-GCM", length: 256 },
+			true,
+			["encrypt", "decrypt"],
+		);
+	}
+
+	/**
+	 * Get (or fetch) the DocKey for a document.
+	 * Returns null if no envelope exists (user not provisioned).
+	 */
+	async getDocKey(
+		docId: string,
+		client: AbracadabraClient,
+		keystore: CryptoIdentityKeystore,
+	): Promise<CryptoKey | null> {
+		const cached = this.cache.get(docId);
+		if (cached) return cached.key;
+
+		const envelope = await client.getMyKeyEnvelope(docId);
+		if (!envelope) return null;
+
+		const x25519PrivKey = await keystore.getX25519PrivateKey();
+		try {
+			const wrapped = fromBase64(envelope.encrypted_key);
+			const docKey = await this._unwrapKey(wrapped, x25519PrivKey, docId);
+			this.cache.set(docId, { key: docKey, epoch: envelope.key_epoch });
+			return docKey;
+		} finally {
+			x25519PrivKey.fill(0);
+		}
+	}
+
+	/**
+	 * Wrap a DocKey for a recipient.
+	 * Output: [ephemeralPub(32) || nonce(12) || ciphertext(~48)] bytes
+	 */
+	async wrapKeyForRecipient(
+		docKey: CryptoKey,
+		recipientX25519PubKey: Uint8Array,
+		docId: string,
+	): Promise<Uint8Array> {
+		const ephemeralPriv = crypto.getRandomValues(new Uint8Array(32));
+		const ephemeralPub = x25519.getPublicKey(ephemeralPriv);
+		const sharedSecret = x25519.getSharedSecret(ephemeralPriv, recipientX25519PubKey);
+
+		const salt = new TextEncoder().encode(docId);
+		const keyBytes = hkdf(sha256, sharedSecret, salt, HKDF_INFO, 32);
+		const wrapKey = await crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM" }, false, ["encrypt"]);
+
+		const rawDocKey = await crypto.subtle.exportKey("raw", docKey);
+		const nonce = crypto.getRandomValues(new Uint8Array(12));
+		const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, wrapKey, rawDocKey));
+
+		const result = new Uint8Array(32 + 12 + ciphertext.length);
+		result.set(ephemeralPub, 0);
+		result.set(nonce, 32);
+		result.set(ciphertext, 44);
+		return result;
+	}
+
+	private async _unwrapKey(wrapped: Uint8Array, recipientX25519PrivKey: Uint8Array, docId: string): Promise<CryptoKey> {
+		const ephemeralPub = wrapped.slice(0, 32);
+		const nonce = wrapped.slice(32, 44);
+		const ciphertext = wrapped.slice(44);
+
+		const sharedSecret = x25519.getSharedSecret(recipientX25519PrivKey, ephemeralPub);
+		const salt = new TextEncoder().encode(docId);
+		const keyBytes = hkdf(sha256, sharedSecret, salt, HKDF_INFO, 32);
+		const wrapKey = await crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM" }, false, ["decrypt"]);
+		const rawDocKey = await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce }, wrapKey, ciphertext);
+		return crypto.subtle.importKey("raw", rawDocKey, { name: "AES-GCM" }, true, ["encrypt", "decrypt"]);
+	}
+
+	/** Clear the cached key for a document (or all if docId omitted). */
+	clearCache(docId?: string): void {
+		if (docId) {
+			this.cache.delete(docId);
+		} else {
+			this.cache.clear();
+		}
+	}
+}

package/src/E2EAbracadabraProvider.ts

@@ -0,0 +1,200 @@
+/**
+ * E2EAbracadabraProvider
+ *
+ * Extends AbracadabraProvider with full E2E encryption support.
+ *
+ * Differences from standard provider:
+ * - startSync() sends a stateless e2e_sync_request instead of SYNC_STEP1
+ * - On receiving e2e_ready, fetches all blobs via REST, decrypts, applies to Y.Doc
+ * - Local updates are AES-GCM encrypted before sending over WebSocket
+ * - Incoming e2e_update stateless messages are decrypted and applied
+ *
+ * Phase 2 offline support:
+ * - After the doc key is obtained, an E2EOfflineStore is created for this doc.
+ * - The stored encrypted snapshot is applied before fetching server updates.
+ * - The last-seen sequence number (e2e_seq) is persisted so only delta updates
+ *   are fetched on subsequent connects.
+ * - After sync, a fresh encrypted snapshot is saved.
+ *
+ * Key availability limitation: if the user's WebAuthn key is not in
+ * DocKeyManager's in-memory cache and there is no network, E2E docs show
+ * empty — the key fetch requires either a cached in-memory key or network.
+ */
+
+import * as Y from "yjs";
+import { AbracadabraProvider } from "./AbracadabraProvider.ts";
+import type { AbracadabraProviderConfiguration } from "./AbracadabraProvider.ts";
+import type { DocKeyManager } from "./DocKeyManager.ts";
+import type { CryptoIdentityKeystore } from "./CryptoIdentityKeystore.ts";
+import type { AbracadabraClient } from "./AbracadabraClient.ts";
+import { UpdateMessage } from "./OutgoingMessages/UpdateMessage.ts";
+import { encryptField, decryptField } from "./EncryptedY.ts";
+import { E2EOfflineStore } from "./E2EOfflineStore.ts";
+
+function fromBase64(b64: string): Uint8Array {
+	return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
+export interface E2EAbracadabraProviderConfiguration extends AbracadabraProviderConfiguration {
+	docKeyManager: DocKeyManager;
+	keystore: CryptoIdentityKeystore;
+	client: AbracadabraClient;
+}
+
+export class E2EAbracadabraProvider extends AbracadabraProvider {
+	private readonly docKeyManager: DocKeyManager;
+	private readonly keystore: CryptoIdentityKeystore;
+	private readonly e2eClient: AbracadabraClient;
+	private docKey: CryptoKey | null = null;
+	private lastSeq = -1;
+
+	/** E2E-encrypted offline store; created after the doc key is available. */
+	private e2eStore: E2EOfflineStore | null = null;
+	private readonly e2eServerOrigin: string | undefined;
+
+	constructor(configuration: E2EAbracadabraProviderConfiguration) {
+		// Disable the parent's offline store — E2E uses its own encrypted store.
+		super({ ...configuration, disableOfflineStore: true });
+		this.docKeyManager = configuration.docKeyManager;
+		this.keystore = configuration.keystore;
+		this.e2eClient = configuration.client;
+
+		// Derive server origin for E2EOfflineStore namespacing
+		this.e2eServerOrigin = E2EAbracadabraProvider.deriveServerOrigin(
+			configuration,
+			configuration.client,
+		);
+	}
+
+	/** Fetch the doc key from the server (requires WebAuthn if not cached). */
+	private async ensureDocKey(): Promise<CryptoKey | null> {
+		if (this.docKey) return this.docKey;
+		this.docKey = await this.docKeyManager.getDocKey(
+			this.configuration.name,
+			this.e2eClient,
+			this.keystore,
+		);
+
+		// Create the encrypted offline store now that we have the key
+		if (this.docKey && !this.e2eStore) {
+			this.e2eStore = new E2EOfflineStore(
+				this.configuration.name,
+				this.e2eServerOrigin,
+				this.docKey,
+			);
+		}
+
+		return this.docKey;
+	}
+
+	/** Handle stateless messages including e2e_ready and e2e_update. */
+	override receiveStateless(payload: string): void {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(payload);
+		} catch {
+			super.receiveStateless(payload);
+			return;
+		}
+
+		const msg = parsed as { type?: string; seq?: number; data?: string; doc_id?: string };
+
+		if (msg.type === "e2e_ready") {
+			// Fetch all blobs and hydrate doc
+			this._fetchAndApplyAllBlobs().catch((e) => {
+				console.error("[E2EAbracadabraProvider] failed to fetch e2e blobs:", e);
+			});
+			return;
+		}
+
+		if (msg.type === "e2e_update" && msg.data !== undefined && msg.seq !== undefined) {
+			if (msg.seq <= this.lastSeq) return; // Already applied
+			this._decryptAndApply(fromBase64(msg.data), msg.seq).catch((e) => {
+				console.error("[E2EAbracadabraProvider] failed to apply e2e_update:", e);
+			});
+			return;
+		}
+
+		super.receiveStateless(payload);
+	}
+
+	private async _fetchAndApplyAllBlobs(): Promise<void> {
+		const key = await this.ensureDocKey();
+		if (!key) {
+			console.warn("[E2EAbracadabraProvider] no doc key available, cannot decrypt blobs");
+			this.synced = true;
+			return;
+		}
+
+		// Phase 2: load stored snapshot + lastSeq before fetching from server
+		if (this.e2eStore) {
+			const storedSeqStr = await this.e2eStore.getMeta("e2e_seq").catch(() => null);
+			if (storedSeqStr !== null) {
+				this.lastSeq = parseInt(storedSeqStr, 10);
+			}
+
+			const snapshot = await this.e2eStore.getDocSnapshot().catch(() => null);
+			if (snapshot) {
+				Y.applyUpdate(this.document, snapshot, this.e2eStore);
+			}
+		}
+
+		// Only fetch updates newer than lastSeq
+		const updates = await this.e2eClient.getE2EUpdatesSince(
+			this.configuration.name,
+			this.lastSeq,
+		);
+		for (const { seq, data } of updates) {
+			await this._decryptAndApply(data, seq);
+		}
+
+		this.synced = true;
+
+		// Phase 2: persist updated snapshot and lastSeq
+		if (this.e2eStore) {
+			const snapshot = Y.encodeStateAsUpdate(this.document);
+			await this.e2eStore.saveDocSnapshot(snapshot).catch(() => null);
+			await this.e2eStore.setMeta("e2e_seq", String(this.lastSeq)).catch(() => null);
+		}
+	}
+
+	private async _decryptAndApply(encryptedData: Uint8Array, seq: number): Promise<void> {
+		const key = await this.ensureDocKey();
+		if (!key) return;
+		try {
+			const plaintext = await decryptField(encryptedData, key);
+			Y.applyUpdate(this.document, plaintext, this);
+			this.lastSeq = Math.max(this.lastSeq, seq);
+		} catch (e) {
+			console.error("[E2EAbracadabraProvider] decryption failed for seq", seq, e);
+		}
+	}
+
+	/** Encrypt local updates before sending over WebSocket. */
+	override documentUpdateHandler(update: Uint8Array, origin: unknown): void {
+		if (origin === this) return;
+		// Don't call super (which would send plaintext); encrypt first
+		this._encryptAndSend(update).catch((e) => {
+			console.error("[E2EAbracadabraProvider] failed to encrypt update:", e);
+		});
+	}
+
+	private async _encryptAndSend(update: Uint8Array): Promise<void> {
+		const key = await this.ensureDocKey();
+		if (!key) {
+			console.warn("[E2EAbracadabraProvider] no doc key, dropping update");
+			return;
+		}
+		const encrypted = await encryptField(update, key);
+		this.send(UpdateMessage, {
+			update: encrypted,
+			documentName: this.configuration.name,
+		});
+	}
+
+	override destroy(): void {
+		this.e2eStore?.destroy();
+		this.e2eStore = null;
+		super.destroy();
+	}
+}

package/src/E2EOfflineStore.ts

@@ -0,0 +1,55 @@
+/**
+ * E2EOfflineStore
+ *
+ * Extends OfflineStore with transparent AES-GCM encryption of the document
+ * snapshot, ensuring that even if the device is compromised, the local
+ * IndexedDB data cannot be read without the doc key.
+ *
+ * Only the snapshot is encrypted (not the meta store entries, which contain
+ * non-sensitive data like sequence numbers).
+ *
+ * Key availability limitation: if the user's WebAuthn key is not in
+ * DocKeyManager's in-memory cache and there is no network, E2E docs show
+ * empty — this is expected Phase 2 behavior.
+ */
+
+import { OfflineStore } from "./OfflineStore.ts";
+import { encryptField, decryptField } from "./EncryptedY.ts";
+
+export class E2EOfflineStore extends OfflineStore {
+	private readonly docKey: CryptoKey;
+
+	/**
+	 * @param docId        The document UUID.
+	 * @param serverOrigin Hostname of the server (namespaces the IDB key).
+	 * @param docKey       AES-GCM CryptoKey used to encrypt/decrypt the snapshot.
+	 */
+	constructor(docId: string, serverOrigin: string | undefined, docKey: CryptoKey) {
+		super(docId, serverOrigin);
+		this.docKey = docKey;
+	}
+
+	/**
+	 * Encrypt the snapshot before storing it.
+	 */
+	override async saveDocSnapshot(snapshot: Uint8Array): Promise<void> {
+		const encrypted = await encryptField(snapshot, this.docKey);
+		await super.saveDocSnapshot(encrypted);
+	}
+
+	/**
+	 * Decrypt the snapshot after loading it.
+	 * Returns null if decryption fails (e.g. key mismatch or corrupt data).
+	 */
+	override async getDocSnapshot(): Promise<Uint8Array | null> {
+		const encrypted = await super.getDocSnapshot();
+		if (!encrypted) return null;
+		try {
+			return await decryptField(encrypted, this.docKey);
+		} catch {
+			// Key mismatch or tampered data — return null so the provider falls
+			// back to fetching from the server.
+			return null;
+		}
+	}
+}

package/src/EncryptedY.ts

@@ -0,0 +1,145 @@
+/**
+ * EncryptedY - CSE (Client-Side Encryption) primitives for Yjs documents.
+ *
+ * Wire format for encrypted fields: [nonce(12) || AES-GCM ciphertext]
+ *
+ * Limitations (documented):
+ * - Concurrent writes to the same Y.Map key produce last-write-wins semantics
+ *   (not character-level CRDT merge), because encrypted values are opaque to Yrs.
+ */
+
+import * as Y from "yjs";
+
+// ── Field-level encryption ─────────────────────────────────────────────────────
+
+/** Encrypt a field value with AES-256-GCM. Returns [nonce(12) || ciphertext]. */
+export async function encryptField(value: Uint8Array, docKey: CryptoKey): Promise<Uint8Array> {
+	const nonce = crypto.getRandomValues(new Uint8Array(12));
+	const ciphertext = new Uint8Array(
+		await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, docKey, value),
+	);
+	const result = new Uint8Array(12 + ciphertext.length);
+	result.set(nonce, 0);
+	result.set(ciphertext, 12);
+	return result;
+}
+
+/** Decrypt a field value from [nonce(12) || ciphertext] format. */
+export async function decryptField(ciphertext: Uint8Array, docKey: CryptoKey): Promise<Uint8Array> {
+	const nonce = ciphertext.slice(0, 12);
+	const ct = ciphertext.slice(12);
+	return new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce }, docKey, ct));
+}
+
+// ── EncryptedYMap ─────────────────────────────────────────────────────────────
+
+/**
+ * A proxy wrapper around a Y.Map<Uint8Array> that transparently encrypts
+ * values on .set() and decrypts on .get().
+ *
+ * NOTE: Concurrent writes to the same key produce last-write-wins (LWW)
+ * because encrypted values are opaque blobs from Yrs's perspective.
+ */
+export class EncryptedYMap {
+	constructor(
+		private readonly ymap: Y.Map<Uint8Array>,
+		private readonly docKey: CryptoKey,
+	) {}
+
+	async set(key: string, value: Uint8Array): Promise<void> {
+		const encrypted = await encryptField(value, this.docKey);
+		this.ymap.set(key, encrypted);
+	}
+
+	async get(key: string): Promise<Uint8Array | null> {
+		const encrypted = this.ymap.get(key);
+		if (!encrypted) return null;
+		try {
+			return await decryptField(encrypted, this.docKey);
+		} catch {
+			return null; // Decryption failed (wrong key or corrupted)
+		}
+	}
+
+	has(key: string): boolean {
+		return this.ymap.has(key);
+	}
+
+	delete(key: string): void {
+		this.ymap.delete(key);
+	}
+
+	get size(): number {
+		return this.ymap.size;
+	}
+
+	/** Get all keys (encrypted values remain opaque until .get() is called). */
+	keys(): string[] {
+		return Array.from(this.ymap.keys());
+	}
+
+	/** Observe changes on the underlying Y.Map. */
+	observe(f: (event: Y.YMapEvent<Uint8Array>) => void): void {
+		this.ymap.observe(f);
+	}
+
+	unobserve(f: (event: Y.YMapEvent<Uint8Array>) => void): void {
+		this.ymap.unobserve(f);
+	}
+}
+
+/** Create an EncryptedYMap wrapping a Y.Map<Uint8Array>. */
+export function makeEncryptedYMap(ymap: Y.Map<Uint8Array>, docKey: CryptoKey): EncryptedYMap {
+	return new EncryptedYMap(ymap, docKey);
+}
+
+// ── EncryptedYText ────────────────────────────────────────────────────────────
+
+/**
+ * Stores full text as a single encrypted blob in a Y.Map<Uint8Array> under a
+ * fixed field name. This is last-write-wins for the entire text field.
+ *
+ * NOTE: This does NOT preserve character-level CRDT merge for concurrent edits.
+ * It trades CRDT merge for confidentiality.
+ */
+export class EncryptedYText {
+	private readonly ymap: Y.Map<Uint8Array>;
+
+	constructor(
+		ydoc: Y.Doc,
+		fieldName: string,
+		private readonly docKey: CryptoKey,
+	) {
+		this.ymap = ydoc.getMap(`_encrypted_${fieldName}`);
+	}
+
+	async set(text: string): Promise<void> {
+		const encoded = new TextEncoder().encode(text);
+		const encrypted = await encryptField(encoded, this.docKey);
+		this.ymap.set("v", encrypted);
+	}
+
+	async get(): Promise<string | null> {
+		const encrypted = this.ymap.get("v");
+		if (!encrypted) return null;
+		try {
+			const decoded = await decryptField(encrypted, this.docKey);
+			return new TextDecoder().decode(decoded);
+		} catch {
+			return null;
+		}
+	}
+
+	observe(f: (event: Y.YMapEvent<Uint8Array>) => void): void {
+		this.ymap.observe(f);
+	}
+
+	unobserve(f: (event: Y.YMapEvent<Uint8Array>) => void): void {
+		this.ymap.unobserve(f);
+	}
+}
+
+/** Create an EncryptedYText for a field in a Y.Doc. */
+export function makeEncryptedYText(ydoc: Y.Doc, fieldName: string, docKey: CryptoKey): EncryptedYText {
+	return new EncryptedYText(ydoc, fieldName, docKey);
+}

package/src/OfflineStore.ts

@@ -226,6 +226,29 @@ export class OfflineStore {
 		);
 	}
 
+	// ── Generic meta accessors ────────────────────────────────────────────────
+
+	async getMeta(key: string): Promise<string | null> {
+		const db = await this.getDb();
+		if (!db) return null;
+		const tx = db.transaction("meta", "readonly");
+		const result = await txPromise<string | undefined>(
+			tx.objectStore("meta"),
+			tx.objectStore("meta").get(key),
+		);
+		return result ?? null;
+	}
+
+	async setMeta(key: string, value: string): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("meta", "readwrite");
+		await txPromise(
+			tx.objectStore("meta"),
+			tx.objectStore("meta").put(value, key),
+		);
+	}
+
 	// ── Lifecycle ─────────────────────────────────────────────────────────────
 
 	destroy() {

package/src/TreeTimestamps.ts

@@ -0,0 +1,51 @@
+/**
+ * TreeTimestamps
+ *
+ * Attaches an afterUpdate observer on a child Y.Doc so that whenever a
+ * non-offline update is applied, the `updatedAt` timestamp on the
+ * corresponding entry in the root doc's `doc-tree` map is written.
+ *
+ * This propagates "last edited" timestamps to all peers via the root CRDT,
+ * without requiring any server-side changes.
+ *
+ * Limitation: at least one client must have the child doc open after an edit
+ * for the timestamp to propagate (eventually consistent).
+ */
+
+import * as Y from "yjs";
+import type { OfflineStore } from "./OfflineStore.ts";
+
+/**
+ * Attach an observer that writes `updatedAt: Date.now()` to the root
+ * doc-tree entry for `childDocId` whenever the child doc receives a
+ * non-offline update.
+ *
+ * @param treeMap     The root doc's "doc-tree" Y.Map.
+ * @param childDocId  The child document's UUID (key in treeMap).
+ * @param childDoc    The child Y.Doc to observe.
+ * @param offlineStore  The child provider's OfflineStore (used to detect
+ *                      offline-replay origins and skip them). Pass null when
+ *                      the offline store is disabled.
+ * @returns           Cleanup function — call on provider destroy.
+ */
+export function attachUpdatedAtObserver(
+	treeMap: Y.Map<any>,
+	childDocId: string,
+	childDoc: Y.Doc,
+	offlineStore: OfflineStore | null,
+): () => void {
+	function handler(update: Uint8Array, origin: unknown): void {
+		// Skip updates replayed from the local offline store — they represent
+		// content that was already "seen" and shouldn't advance updatedAt.
+		if (offlineStore !== null && origin === offlineStore) return;
+
+		// Update the root tree entry (no-op if the entry doesn't exist).
+		const entry = treeMap.get(childDocId);
+		if (!entry) return;
+
+		treeMap.set(childDocId, { ...entry, updatedAt: Date.now() });
+	}
+
+	childDoc.on("update", handler);
+	return () => childDoc.off("update", handler);
+}

package/src/index.ts

@@ -13,3 +13,13 @@ export { DocumentCache } from "./DocumentCache.ts";
 export type { DocumentCacheOptions } from "./DocumentCache.ts";
 export { SearchIndex } from "./SearchIndex.ts";
 export { FileBlobStore } from "./FileBlobStore.ts";
+export { DocKeyManager } from "./DocKeyManager.ts";
+export { E2EAbracadabraProvider } from "./E2EAbracadabraProvider.ts";
+export { E2EOfflineStore } from "./E2EOfflineStore.ts";
+export * from "./EncryptedY.ts";
+export type { DocEncryptionInfo } from "./types.ts";
+export { attachUpdatedAtObserver } from "./TreeTimestamps.ts";
+export { BackgroundSyncManager } from "./BackgroundSyncManager.ts";
+export type { BackgroundSyncManagerOptions } from "./BackgroundSyncManager.ts";
+export { BackgroundSyncPersistence } from "./BackgroundSyncPersistence.ts";
+export type { DocSyncState } from "./BackgroundSyncPersistence.ts";