@abraca/dabra 0.9.0 → 1.0.1

package/dist/index.d.ts

@@ -131,6 +131,63 @@ declare class EventEmitter {
   removeAllListeners(): void;
 }
 //#endregion
+//#region packages/provider/src/OfflineStore.d.ts
+/**
+ * IndexedDB-backed offline store for a single Abracadabra document.
+ *
+ * Responsibilities:
+ *  - Persist CRDT updates locally so they survive page refreshes / network loss.
+ *  - Store the last-known state vector for fast reconnect diffs.
+ *  - Store a permission snapshot so the UI can gate writes without a network round-trip.
+ *  - Queue subdoc registration events created while offline.
+ *  - Store a full document snapshot so the app can load content without a server connection.
+ *
+ * Falls back to a silent no-op when IndexedDB is unavailable (e.g. SSR / Node.js).
+ *
+ * Database key is scoped by server origin to prevent cross-server data contamination
+ * when the same docId is used on multiple servers.
+ */
+interface PendingSubdoc {
+  childId: string;
+  parentId: string;
+  createdAt: number;
+}
+declare class OfflineStore {
+  private storeKey;
+  private db;
+  /**
+   * @param docId       The document UUID.
+   * @param serverOrigin  Hostname of the server (e.g. "abra.cou.sh").
+   *                    When provided the IndexedDB database is namespaced
+   *                    per-server, preventing cross-server data contamination.
+   */
+  constructor(docId: string, serverOrigin?: string);
+  private dbPromise;
+  private getDb;
+  persistUpdate(update: Uint8Array): Promise<void>;
+  getPendingUpdates(): Promise<Uint8Array[]>;
+  clearPendingUpdates(): Promise<void>;
+  /**
+   * Persist a full Y.js state snapshot (Y.encodeStateAsUpdate output).
+   * Replaces any previously stored snapshot.
+   */
+  saveDocSnapshot(snapshot: Uint8Array): Promise<void>;
+  /**
+   * Retrieve the stored full document snapshot, or null if none exists.
+   */
+  getDocSnapshot(): Promise<Uint8Array | null>;
+  getStateVector(): Promise<Uint8Array | null>;
+  saveStateVector(sv: Uint8Array): Promise<void>;
+  getPermissionSnapshot(): Promise<string | null>;
+  savePermissionSnapshot(role: string): Promise<void>;
+  queueSubdoc(entry: PendingSubdoc): Promise<void>;
+  getPendingSubdocs(): Promise<PendingSubdoc[]>;
+  removeSubdocFromQueue(childId: string): Promise<void>;
+  getMeta(key: string): Promise<string | null>;
+  setMeta(key: string, value: string): Promise<void>;
+  destroy(): void;
+}
+//#endregion
 //#region packages/provider/src/DocumentCache.d.ts
 interface DocumentCacheOptions {
   /** How long cached entries remain valid. Default: 5 minutes. */
@@ -245,11 +302,42 @@ declare class AbracadabraClient {
   addKey(opts: {
     publicKey: string;
     deviceName?: string;
+    x25519Key?: string;
   }): Promise<void>;
   /** List all registered public keys for the current user. */
   listKeys(): Promise<PublicKeyInfo[]>;
   /** Revoke a public key by its ID. */
   revokeKey(keyId: string): Promise<void>;
+  /** Get encryption info for a document. */
+  getDocEncryption(docId: string): Promise<DocEncryptionInfo>;
+  /** Set the encryption mode for a document (no downgrade). */
+  setDocEncryption(docId: string, mode: "none" | "cse" | "e2e"): Promise<void>;
+  /** Get the caller's key envelope for a document (for decrypting the DocKey). */
+  getMyKeyEnvelope(docId: string): Promise<{
+    encrypted_key: string;
+    key_epoch: number;
+  } | null>;
+  /** Upload key envelopes for a document (Owner only). */
+  uploadKeyEnvelopes(docId: string, opts: {
+    key_epoch: number;
+    envelopes: {
+      recipient_key_id: string;
+      encrypted_key: string;
+    }[];
+  }): Promise<void>;
+  /** Get the X25519 public key for a user. */
+  getUserX25519Key(userId: string): Promise<string | null>;
+  /** List all non-revoked keys for a user (Owner/Admin or self). */
+  listUserKeys(userId: string): Promise<{
+    id: string;
+    publicKey: string;
+    x25519Key: string | null;
+  }[]>;
+  /** Fetch encrypted E2E update blobs since a given sequence number. */
+  getE2EUpdatesSince(docId: string, sinceSeq: number): Promise<{
+    seq: number;
+    data: Uint8Array;
+  }[]>;
   /** Clear token from memory and storage. */
   logout(): void;
   /** Get the current user's profile. */
@@ -317,6 +405,98 @@ declare class AbracadabraClient {
   private clearPersistedToken;
 }
 //#endregion
+//#region packages/provider/src/CryptoIdentityKeystore.d.ts
+/**
+ * CryptoIdentityKeystore
+ *
+ * Per-device Ed25519 keypair, private key protected by WebAuthn PRF + AES-256-GCM.
+ * Stored in IndexedDB under "abracadabra:identity" / "identity" / key "current".
+ *
+ * No private key is ever shared between devices. Each device generates its own
+ * keypair, encrypts the private key with the PRF output from its own WebAuthn
+ * credential, and stores the ciphertext in IndexedDB.
+ *
+ * Dependencies: @noble/ed25519, @noble/hashes (for HKDF)
+ */
+declare class CryptoIdentityKeystore {
+  /**
+   * One-time setup for a device: generates an Ed25519 keypair, creates a
+   * WebAuthn credential with PRF extension, encrypts the private key, and
+   * stores everything in IndexedDB.
+   *
+   * Returns the base64url-encoded public key. The caller must register this
+   * key with the server via POST /auth/register (first device) or
+   * POST /auth/keys (additional device).
+   *
+   * @param username  - The user's account name.
+   * @param rpId      - WebAuthn relying party ID (e.g. "example.com").
+   * @param rpName    - Human-readable relying party name.
+   */
+  register(username: string, rpId: string, rpName: string): Promise<{
+    publicKey: string;
+    x25519PublicKey: string;
+  }>;
+  /**
+   * Sign a base64url-encoded challenge using the stored Ed25519 private key.
+   *
+   * This triggers a WebAuthn assertion (biometric / PIN prompt) to unlock the
+   * private key via PRF → HKDF → AES-GCM decryption. The private key is
+   * wiped from memory after signing.
+   *
+   * @param challengeB64 - base64url-encoded challenge bytes from the server.
+   * @returns base64url-encoded Ed25519 signature (64 bytes).
+   */
+  sign(challengeB64: string): Promise<string>;
+  /** Returns the stored base64url public key, or null if no identity exists. */
+  getPublicKey(): Promise<string | null>;
+  /**
+   * Returns the locally-stored internal username label, or null if no identity exists.
+   *
+   * This is NOT the auth identifier (the public key is). It can be used as a
+   * hint when calling POST /auth/register, or displayed before the user sets
+   * a real display name via PATCH /users/me.
+   */
+  getUsername(): Promise<string | null>;
+  /** Returns true if an identity is stored in IndexedDB. */
+  hasIdentity(): Promise<boolean>;
+  /** Remove the stored identity from IndexedDB. */
+  clear(): Promise<void>;
+  /**
+   * 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.
+   */
+  getX25519PublicKey(): Promise<Uint8Array | null>;
+  /**
+   * 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.
+   */
+  getX25519PrivateKey(): Promise<Uint8Array>;
+}
+//#endregion
+//#region packages/provider/src/DocKeyManager.d.ts
+declare class DocKeyManager {
+  private cache;
+  /** Generate a new random AES-256-GCM document key. */
+  static generateDocKey(): Promise<CryptoKey>;
+  /**
+   * Get (or fetch) the DocKey for a document.
+   * Returns null if no envelope exists (user not provisioned).
+   */
+  getDocKey(docId: string, client: AbracadabraClient, keystore: CryptoIdentityKeystore): Promise<CryptoKey | null>;
+  /**
+   * Wrap a DocKey for a recipient.
+   * Output: [ephemeralPub(32) || nonce(12) || ciphertext(~48)] bytes
+   */
+  wrapKeyForRecipient(docKey: CryptoKey, recipientX25519PubKey: Uint8Array, docId: string): Promise<Uint8Array>;
+  private _unwrapKey;
+  /** Clear the cached key for a document (or all if docId omitted). */
+  clearCache(docId?: string): void;
+}
+//#endregion
 //#region packages/provider/src/AbracadabraProvider.d.ts
 interface AbracadabraProviderConfiguration extends Omit<AbracadabraBaseProviderConfiguration, "url" | "websocketProvider"> {
   /**
@@ -352,6 +532,10 @@ interface AbracadabraProviderConfiguration extends Omit<AbracadabraBaseProviderC
   client?: AbracadabraClient;
   /** 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;
 }
@@ -398,7 +582,7 @@ declare 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;
   /**
    * Load the stored document snapshot (and any pending local edits) from
    * IndexedDB and apply them to the Y.Doc so the UI can render without a
@@ -425,6 +609,8 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   get canWrite(): boolean;
   /** The AbracadabraClient instance for REST API access, if configured. */
   get client(): AbracadabraClient | null;
+  /** The OfflineStore instance, or null if offline storage is disabled. */
+  get store(): OfflineStore | null;
   /**
    * Called when a MSG_STATELESS frame arrives from the server.
    * Abracadabra uses stateless frames to deliver subdoc confirmations
@@ -475,7 +661,7 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   destroy(): void;
 }
 //#endregion
-//#region node_modules/lib0/encoding.d.ts
+//#region packages/provider/node_modules/lib0/encoding.d.ts
 /**
  * A BinaryEncoder handles the encoding to an Uint8Array.
  */
@@ -519,7 +705,7 @@ declare const Forbidden: CloseEvent;
  */
 declare const ConnectionTimeout: CloseEvent;
 //#endregion
-//#region node_modules/lib0/decoding.d.ts
+//#region packages/provider/node_modules/lib0/decoding.d.ts
 /**
  * A Decoder handles the decoding of an Uint8Array.
  * @template {ArrayBufferLike} [Buf=ArrayBufferLike]
@@ -801,6 +987,11 @@ interface UploadQueueEntry {
   createdAt: number;
   error?: string;
 }
+interface DocEncryptionInfo {
+  mode: "none" | "cse" | "e2e";
+  effective_mode: "none" | "cse" | "e2e";
+  inherited_from?: string;
+}
 //#endregion
 //#region packages/provider/src/AbracadabraWS.d.ts
 type AbracadabraWebSocketConn = WebSocket & {
@@ -1061,61 +1252,6 @@ declare const HocuspocusProvider: typeof AbracadabraBaseProvider;
 /** @deprecated Use AbracadabraBaseProvider */
 type HocuspocusProvider = AbracadabraBaseProvider;
 //#endregion
-//#region packages/provider/src/OfflineStore.d.ts
-/**
- * IndexedDB-backed offline store for a single Abracadabra document.
- *
- * Responsibilities:
- *  - Persist CRDT updates locally so they survive page refreshes / network loss.
- *  - Store the last-known state vector for fast reconnect diffs.
- *  - Store a permission snapshot so the UI can gate writes without a network round-trip.
- *  - Queue subdoc registration events created while offline.
- *  - Store a full document snapshot so the app can load content without a server connection.
- *
- * Falls back to a silent no-op when IndexedDB is unavailable (e.g. SSR / Node.js).
- *
- * Database key is scoped by server origin to prevent cross-server data contamination
- * when the same docId is used on multiple servers.
- */
-interface PendingSubdoc {
-  childId: string;
-  parentId: string;
-  createdAt: number;
-}
-declare class OfflineStore {
-  private storeKey;
-  private db;
-  /**
-   * @param docId       The document UUID.
-   * @param serverOrigin  Hostname of the server (e.g. "abra.cou.sh").
-   *                    When provided the IndexedDB database is namespaced
-   *                    per-server, preventing cross-server data contamination.
-   */
-  constructor(docId: string, serverOrigin?: string);
-  private dbPromise;
-  private getDb;
-  persistUpdate(update: Uint8Array): Promise<void>;
-  getPendingUpdates(): Promise<Uint8Array[]>;
-  clearPendingUpdates(): Promise<void>;
-  /**
-   * Persist a full Y.js state snapshot (Y.encodeStateAsUpdate output).
-   * Replaces any previously stored snapshot.
-   */
-  saveDocSnapshot(snapshot: Uint8Array): Promise<void>;
-  /**
-   * Retrieve the stored full document snapshot, or null if none exists.
-   */
-  getDocSnapshot(): Promise<Uint8Array | null>;
-  getStateVector(): Promise<Uint8Array | null>;
-  saveStateVector(sv: Uint8Array): Promise<void>;
-  getPermissionSnapshot(): Promise<string | null>;
-  savePermissionSnapshot(role: string): Promise<void>;
-  queueSubdoc(entry: PendingSubdoc): Promise<void>;
-  getPendingSubdocs(): Promise<PendingSubdoc[]>;
-  removeSubdocFromQueue(childId: string): Promise<void>;
-  destroy(): void;
-}
-//#endregion
 //#region packages/provider/src/auth.d.ts
 declare enum AuthMessageType {
   Token = 0,
@@ -1150,61 +1286,6 @@ declare class SubdocMessage extends OutgoingMessage {
   get(args: Partial<OutgoingMessageArguments>): Encoder;
 }
 //#endregion
-//#region packages/provider/src/CryptoIdentityKeystore.d.ts
-/**
- * CryptoIdentityKeystore
- *
- * Per-device Ed25519 keypair, private key protected by WebAuthn PRF + AES-256-GCM.
- * Stored in IndexedDB under "abracadabra:identity" / "identity" / key "current".
- *
- * No private key is ever shared between devices. Each device generates its own
- * keypair, encrypts the private key with the PRF output from its own WebAuthn
- * credential, and stores the ciphertext in IndexedDB.
- *
- * Dependencies: @noble/ed25519, @noble/hashes (for HKDF)
- */
-declare class CryptoIdentityKeystore {
-  /**
-   * One-time setup for a device: generates an Ed25519 keypair, creates a
-   * WebAuthn credential with PRF extension, encrypts the private key, and
-   * stores everything in IndexedDB.
-   *
-   * Returns the base64url-encoded public key. The caller must register this
-   * key with the server via POST /auth/register (first device) or
-   * POST /auth/keys (additional device).
-   *
-   * @param username  - The user's account name.
-   * @param rpId      - WebAuthn relying party ID (e.g. "example.com").
-   * @param rpName    - Human-readable relying party name.
-   */
-  register(username: string, rpId: string, rpName: string): Promise<string>;
-  /**
-   * Sign a base64url-encoded challenge using the stored Ed25519 private key.
-   *
-   * This triggers a WebAuthn assertion (biometric / PIN prompt) to unlock the
-   * private key via PRF → HKDF → AES-GCM decryption. The private key is
-   * wiped from memory after signing.
-   *
-   * @param challengeB64 - base64url-encoded challenge bytes from the server.
-   * @returns base64url-encoded Ed25519 signature (64 bytes).
-   */
-  sign(challengeB64: string): Promise<string>;
-  /** Returns the stored base64url public key, or null if no identity exists. */
-  getPublicKey(): Promise<string | null>;
-  /**
-   * Returns the locally-stored internal username label, or null if no identity exists.
-   *
-   * This is NOT the auth identifier (the public key is). It can be used as a
-   * hint when calling POST /auth/register, or displayed before the user sets
-   * a real display name via PATCH /users/me.
-   */
-  getUsername(): Promise<string | null>;
-  /** Returns true if an identity is stored in IndexedDB. */
-  hasIdentity(): Promise<boolean>;
-  /** Remove the stored identity from IndexedDB. */
-  clear(): Promise<void>;
-}
-//#endregion
 //#region packages/provider/src/SearchIndex.d.ts
 declare class SearchIndex {
   private readonly origin;
@@ -1248,6 +1329,12 @@ declare class FileBlobStore extends EventEmitter {
    * URL.createObjectURL is unavailable (e.g. Node.js / SSR).
    */
   getBlobUrl(docId: string, uploadId: string): Promise<string | null>;
+  /**
+   * Store a blob directly into the cache under the given (docId, uploadId) key
+   * and return its object URL.  Use this to pre-populate the cache for files
+   * that haven't been uploaded to the server yet (e.g. offline upload queue).
+   */
+  putBlob(docId: string, uploadId: string, blob: Blob, filename: string): Promise<string>;
   /** Revoke the object URL and remove the blob from cache. */
   evictBlob(docId: string, uploadId: string): Promise<void>;
   /**
@@ -1268,4 +1355,212 @@ declare class FileBlobStore extends EventEmitter {
   destroy(): void;
 }
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DocumentCache, type DocumentCacheOptions, DocumentMeta, EffectiveRole, FileBlobStore, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, InviteRow, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, awarenessStatesToArray, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+//#region packages/provider/src/E2EAbracadabraProvider.d.ts
+interface E2EAbracadabraProviderConfiguration extends AbracadabraProviderConfiguration {
+  docKeyManager: DocKeyManager;
+  keystore: CryptoIdentityKeystore;
+  client: AbracadabraClient;
+}
+declare class E2EAbracadabraProvider extends AbracadabraProvider {
+  private readonly docKeyManager;
+  private readonly keystore;
+  private readonly e2eClient;
+  private docKey;
+  private lastSeq;
+  /** E2E-encrypted offline store; created after the doc key is available. */
+  private e2eStore;
+  private readonly e2eServerOrigin;
+  constructor(configuration: E2EAbracadabraProviderConfiguration);
+  /** Fetch the doc key from the server (requires WebAuthn if not cached). */
+  private ensureDocKey;
+  /** Handle stateless messages including e2e_ready and e2e_update. */
+  receiveStateless(payload: string): void;
+  private _fetchAndApplyAllBlobs;
+  private _decryptAndApply;
+  /** Encrypt local updates before sending over WebSocket. */
+  documentUpdateHandler(update: Uint8Array, origin: unknown): void;
+  private _encryptAndSend;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/E2EOfflineStore.d.ts
+declare class E2EOfflineStore extends OfflineStore {
+  private readonly docKey;
+  /**
+   * @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);
+  /**
+   * Encrypt the snapshot before storing it.
+   */
+  saveDocSnapshot(snapshot: Uint8Array): Promise<void>;
+  /**
+   * Decrypt the snapshot after loading it.
+   * Returns null if decryption fails (e.g. key mismatch or corrupt data).
+   */
+  getDocSnapshot(): Promise<Uint8Array | null>;
+}
+//#endregion
+//#region packages/provider/src/EncryptedY.d.ts
+/** Encrypt a field value with AES-256-GCM. Returns [nonce(12) || ciphertext]. */
+declare function encryptField(value: Uint8Array, docKey: CryptoKey): Promise<Uint8Array>;
+/** Decrypt a field value from [nonce(12) || ciphertext] format. */
+declare function decryptField(ciphertext: Uint8Array, docKey: CryptoKey): Promise<Uint8Array>;
+/**
+ * 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.
+ */
+declare class EncryptedYMap {
+  private readonly ymap;
+  private readonly docKey;
+  constructor(ymap: Y.Map<Uint8Array>, docKey: CryptoKey);
+  set(key: string, value: Uint8Array): Promise<void>;
+  get(key: string): Promise<Uint8Array | null>;
+  has(key: string): boolean;
+  delete(key: string): void;
+  get size(): number;
+  /** Get all keys (encrypted values remain opaque until .get() is called). */
+  keys(): string[];
+  /** Observe changes on the underlying Y.Map. */
+  observe(f: (event: Y.YMapEvent<Uint8Array>) => void): void;
+  unobserve(f: (event: Y.YMapEvent<Uint8Array>) => void): void;
+}
+/** Create an EncryptedYMap wrapping a Y.Map<Uint8Array>. */
+declare function makeEncryptedYMap(ymap: Y.Map<Uint8Array>, docKey: CryptoKey): EncryptedYMap;
+/**
+ * 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.
+ */
+declare class EncryptedYText {
+  private readonly docKey;
+  private readonly ymap;
+  constructor(ydoc: Y.Doc, fieldName: string, docKey: CryptoKey);
+  set(text: string): Promise<void>;
+  get(): Promise<string | null>;
+  observe(f: (event: Y.YMapEvent<Uint8Array>) => void): void;
+  unobserve(f: (event: Y.YMapEvent<Uint8Array>) => void): void;
+}
+/** Create an EncryptedYText for a field in a Y.Doc. */
+declare function makeEncryptedYText(ydoc: Y.Doc, fieldName: string, docKey: CryptoKey): EncryptedYText;
+//#endregion
+//#region packages/provider/src/TreeTimestamps.d.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.
+ */
+declare function attachUpdatedAtObserver(treeMap: Y.Map<any>, childDocId: string, childDoc: Y.Doc, offlineStore: OfflineStore | null): () => void;
+//#endregion
+//#region packages/provider/src/BackgroundSyncPersistence.d.ts
+/**
+ * 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).
+ */
+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;
+}
+declare class BackgroundSyncPersistence {
+  private dbPromise;
+  private readonly serverOrigin;
+  constructor(serverOrigin: string);
+  private getDb;
+  getState(docId: string): Promise<DocSyncState | null>;
+  getAllStates(): Promise<DocSyncState[]>;
+  setState(state: DocSyncState): Promise<void>;
+  deleteState(docId: string): Promise<void>;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/BackgroundSyncManager.d.ts
+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;
+}
+declare class BackgroundSyncManager extends EventEmitter {
+  private readonly rootProvider;
+  private readonly client;
+  private readonly fileBlobStore;
+  private readonly opts;
+  private readonly persistence;
+  private readonly semaphore;
+  private readonly syncStates;
+  private _destroyed;
+  constructor(rootProvider: AbracadabraProvider, client: AbracadabraClient, fileBlobStore?: FileBlobStore | null, opts?: BackgroundSyncManagerOptions);
+  /** Sync all documents in the root tree. */
+  syncAll(): Promise<void>;
+  /** Sync a single document by ID. */
+  syncDoc(docId: string): Promise<DocSyncState>;
+  /** Return a snapshot of all known sync states. */
+  getSyncStatus(): Map<string, DocSyncState>;
+  /**
+   * Start periodic background sync.
+   * @param intervalMs  Interval between sync runs. Default: 5 minutes.
+   * @returns Cleanup function to stop the periodic sync.
+   */
+  startPeriodicSync(intervalMs?: number): () => void;
+  destroy(): void;
+  /**
+   * 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;
+  private _syncWithSemaphore;
+  private _doSyncDoc;
+  private _syncNonE2EDoc;
+  private _syncE2EDoc;
+  /**
+   * Wait for a provider to emit the "synced" event (with state=true),
+   * timing out after opts.syncTimeout ms.
+   */
+  private _waitForSynced;
+  /**
+   * Pre-cache all cover images referenced in the root tree map.
+   */
+  private _prefetchCovers;
+  /**
+   * 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 _prefetchDocFiles;
+  private _extractFileRefs;
+  private _walkXml;
+}
+//#endregion
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EOfflineStore, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, InviteRow, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "0.9.0",
+  "version": "1.0.1",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -29,6 +29,7 @@
   ],
   "dependencies": {
     "@lifeomic/attempt": "^3.1.0",
+    "@noble/curves": "^2.0.1",
     "@noble/ed25519": "^2.3.0",
     "@noble/hashes": "^1.8.0",
     "lib0": "^0.2.117",