mindoodb 0.0.2 → 0.0.4

package/README.md

@@ -11,6 +11,9 @@ Your data is encrypted on the client before it ever touches a server. No plainte
 
 > ⚠️ **Alpha software**: This project is in early development and not yet recommended for production use. APIs may change without notice.
 
+Use AI to explore this repository:
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/klehmann/MindooDB)
 
 ## The Problem
 
@@ -44,7 +47,7 @@ Traditional databases trust the server. If your hosting provider is compromised,
 └──────────────────────────────────────────────────────────────────┘
 ```
 
-**Sync happens through content-addressed stores**: clients exchange only the encrypted entries they're missing. Works peer-to-peer, client-server, or any combination.
+**Sync happens through content-addressed stores**: clients exchange only the encrypted entries they're missing. Works peer-to-peer, client-server, or any combination - for documents and attached files.
 
 ## Key Features
 
@@ -65,37 +68,43 @@ Traditional databases trust the server. If your hosting provider is compromised,
 npm install mindoodb
 ```
 
+> 📱 **React Native / Expo?** See the [React Native setup guide](./docs/reactnative.md) for mobile-specific instructions with native performance.
+
+### Pick Your Runtime
+
+| Runtime | Fastest start | Recommended path |
+|---------|---------------|------------------|
+| Node.js | Use `mindoodb` directly in a Node script | [Getting Started](./docs/getting-started.md#nodejs) |
+| Web | Import from `mindoodb/browser` | [Getting Started](./docs/getting-started.md#web-browser) |
+| React Native / Expo | Run `npx mindoodb setup-react-native` in your app root | [React Native Guide](./docs/reactnative.md) |
+
+### React Native Recommendation
+
+- Use **native Automerge** (`react-native-automerge-generated`) and native crypto for production.
+- Treat Expo Go / JS fallback as a convenience path for prototyping, not the default production runtime.
+
 ### Create a Tenant and Start Working
 
 ```typescript
 import { 
   BaseMindooTenantFactory, 
-  InMemoryAppendOnlyStoreFactory,
-  KeyBag 
+  InMemoryContentAddressedStoreFactory,
 } from "mindoodb";
 
 // 1. Set up storage (in-memory for demo; use file/server-backed for production)
-const storeFactory = new InMemoryAppendOnlyStoreFactory();
+const storeFactory = new InMemoryContentAddressedStoreFactory();
 const factory = new BaseMindooTenantFactory(storeFactory);
 
-// 2. Create a user (generates signing + encryption key pairs)
-const user = await factory.createUserId("CN=alice/O=acme", "user-password");
-const keyBag = new KeyBag(user.userEncryptionKeyPair.privateKey, "user-password");
-
-// 3. Create admin keys (for managing users)
-const adminKeyPair = await factory.createSigningKeyPair("admin-password");
-
-// 4. Create a tenant (an organization that shares documents)
-const tenant = await factory.createTenant(
-  "acme-corp",
-  adminKeyPair.publicKey,
-  "tenant-key-password",
-  user,
-  "user-password",
-  keyBag
-);
+// 2. Create tenant (generates all keys, opens tenant, registers user — single call)
+const { tenant, adminUser, appUser, keyBag } = await factory.createTenant({
+  tenantId: "acme-corp",
+  adminName: "cn=admin/o=acme",
+  adminPassword: "admin-password",
+  userName: "cn=alice/o=acme",
+  userPassword: "user-password",
+});
 
-// 5. Open a database and create documents
+// 3. Open a database and create documents
 const db = await tenant.openDB("contacts");
 const doc = await db.createDocument();
 
@@ -105,7 +114,7 @@ await db.changeDoc(doc, async (d) => {
   data.email = "john@example.com";
 });
 
-// 6. Read it back
+// 4. Read it back
 const contacts = await db.getAllDocumentIds();
 const loaded = await db.getDocument(contacts[0]);
 console.log(loaded.getData()); // { name: "John Doe", email: "john@example.com" }
@@ -200,20 +209,20 @@ All encryption keys are stored in the **KeyBag**—a local, password-protected k
 | **`default` key** | Used when no other key is specified | All tenant members |
 | **Named keys** | Fine-grained access for sensitive docs | Only users you share it with |
 
-Keys are distributed offline (email, phone, in-person). The `default` key is typically shared during onboarding; named keys are shared as needed for specific documents.
+Keys are distributed offline (e.g. password protected via email or a shared drive). The `default` key is typically shared during onboarding; named keys are shared as needed for specific documents.
 
 ## Security
 
 ### Cryptographic Guarantees
-- **Signatures**: Ed25519 on every change—proves who wrote it
-- **Encryption**: AES-256-GCM—servers see only ciphertext
-- **Integrity**: Changes are hash-chained—tampering breaks the chain
+- **Signatures**: Ed25519 on every change - proves who wrote it
+- **Encryption**: AES-256-GCM - servers see only ciphertext
+- **Integrity**: Changes are hash-chained - tampering breaks the chain
 
 ### User Revocation
 Revoked users:
 - ❌ Cannot sync with peers or servers
 - ❌ Cannot make new changes (signatures rejected)
-- ⚠️ Can still read previously-synced data (fundamental trade-off of E2E encryption)
+- ⚠️ Can currently read previously-synced local data (planned: data wipe on first connect after revocation)
 
 MindooDB includes **revocation timestamp protection** to prevent backdated changes from revoked users. See: [Revocation Protection](./docs/revocation-timestamp-protection.md)
 
@@ -223,6 +232,13 @@ Append-only storage means nothing is ever deleted:
 - Cryptographic proof of all operations
 - GDPR compliance via `purgeDocHistory()` when legally required
 
+## Supported Platforms
+
+- ✅ **Node.js** - Server-side and desktop apps
+- ✅ **Web Browsers** - Progressive web apps with Web Crypto API
+- ✅ **React Native / Expo** - iOS and Android with native Automerge (Rust via JSI)
+- ✅ **Electron** - Cross-platform desktop apps
+
 ## Use Cases
 
 - **Multi-Tenant SaaS**: Each customer isolated with encrypted data
@@ -230,21 +246,66 @@ Append-only storage means nothing is ever deleted:
 - **Secure File Sharing**: Named keys for need-to-know access
 - **Audit-Critical Systems**: Tamperproof history meets compliance requirements
 - **Offline-First Apps**: Full functionality without network; sync when connected
+- **Mobile Apps**: End-to-end encrypted sync with native performance
 
 See: [Use Cases Documentation](./docs/usecases/README.md)
 
 ## Documentation
 
+- [Getting Started](./docs/getting-started.md) — Fast setup for Node.js, Web, and React Native
+- [Example Snippets](./docs/examples/README.md) — Copy-paste Todo starters for all runtimes
 - [Architecture Specification](./docs/specification.md) — Full technical details
+- [React Native Guide](./docs/reactnative.md) — Native Automerge setup and troubleshooting
 - [Virtual Views](./docs/virtualview.md) — Aggregations and cross-database views
 - [Data Indexing](./docs/dataindexing.md) — Incremental indexing and search integration
 - [Time Travel](./docs/timetravel.md) — Historical document retrieval and history traversal
 - [P2P Sync](./docs/p2psync.md) — Peer-to-peer synchronization
 - [Attachments](./docs/attachments.md) — File storage and streaming
 
+## Testing
+
+Run tests from the command line:
+
+```bash
+# Node.js unit/integration tests (Jest)
+npm test
+
+# Install Chromium once for browser tests
+npm run test:browser:install
+
+# Real browser runtime tests (Playwright + headless Chromium)
+npm run test:browser
+
+# Run Node + browser lanes
+npm run test:all
+```
+
+### Test coverage by environment
+
+| Environment | Command | What is covered today |
+|-------------|---------|------------------------|
+| Node.js | `npm test` | Full Jest suite for core APIs (documents, sync logic, indexing, virtual views, settings, trust model, attachments, etc.) |
+| Browser | `npm run test:browser` | Real Chromium runtime via Playwright, including browser entrypoint usage, document lifecycle, real HTTP sync endpoint flows, and browser Virtual View update behavior |
+| React Native / Expo | `npm test -- ReactNativeCrypto.test.ts` | Crypto adapter behavior in Jest (uses `src/__mocks__/expo-standard-web-crypto.ts`), not a device/simulator E2E run |
+
+### Browser sync test behavior
+
+- Browser tests run in headless Chromium and execute MindooDB browser code in a real page runtime.
+- During test setup, an ephemeral HTTP server is started automatically and exposes the real sync endpoints.
+- Sync assertions use real HTTP requests against that temporary endpoint (no mocked transport for sync tests).
+- The server binds to an OS-assigned free port and is shut down after the suite completes.
+
+### Current parity status
+
+- The package exports and core API shape are aligned across Node.js, browser, and React Native entrypoints.
+- Node and browser now have executable CLI lanes with runtime validation.
+- React Native coverage is currently adapter-focused in Jest and does not yet validate full app-level behavior inside a real React Native runtime.
+- For high confidence in three-environment parity, add a React Native integration lane (Expo/Detox or RN test app) that exercises document lifecycle, sync, and virtual view updates on device/simulator.
+- For Expo Go / JS fallback scenarios, PBKDF2 iterations can be tuned at runtime; native RN builds should keep strong defaults.
+
 ## Support
 
-Need help, have questions, or want to request a feature? We're here to help! :-)
+Need commercial support, have questions, or want to request a feature? We're here to help! :-)
 
 - 🐛 **Bug Reports**: [Open an issue on GitHub](https://github.com/klehmann/mindoodb/issues)
 - 💬 **Questions & Discussions**: [GitHub Discussions](https://github.com/klehmann/mindoodb/discussions)

package/dist/__mocks__/expo-standard-web-crypto.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mock for expo-standard-web-crypto
+ * Uses Node.js crypto for getRandomValues in tests
+ */
+export declare function getRandomValues(array: Uint8Array): Uint8Array;
+declare const _default: {
+    getRandomValues: typeof getRandomValues;
+};
+export default _default;
+//# sourceMappingURL=expo-standard-web-crypto.d.ts.map

package/dist/__mocks__/expo-standard-web-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expo-standard-web-crypto.d.ts","sourceRoot":"","sources":["../../src/__mocks__/expo-standard-web-crypto.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAI7D;;;;AAGD,wBAEE"}

package/dist/__mocks__/expo-standard-web-crypto.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Mock for expo-standard-web-crypto
+ * Uses Node.js crypto for getRandomValues in tests
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRandomValues = getRandomValues;
+const crypto_1 = __importDefault(require("crypto"));
+// Export getRandomValues directly for CommonJS compatibility
+function getRandomValues(array) {
+    const randomBytes = crypto_1.default.randomBytes(array.length);
+    array.set(randomBytes);
+    return array;
+}
+// Also export as default for ESM compatibility
+exports.default = {
+    getRandomValues,
+};
+//# sourceMappingURL=expo-standard-web-crypto.js.map

package/dist/__mocks__/expo-standard-web-crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expo-standard-web-crypto.js","sourceRoot":"","sources":["../../src/__mocks__/expo-standard-web-crypto.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;AAKH,0CAIC;AAPD,oDAA4B;AAE5B,6DAA6D;AAC7D,SAAgB,eAAe,CAAC,KAAiB;IAC/C,MAAM,WAAW,GAAG,gBAAM,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACrD,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+CAA+C;AAC/C,kBAAe;IACb,eAAe;CAChB,CAAC"}

package/dist/appendonlystores/BasicOnDiskContentAddressedStoreFactory.d.ts

@@ -0,0 +1,8 @@
+import { ContentAddressedStoreFactory, CreateStoreResult, OpenStoreOptions } from "../core/types";
+/**
+ * Factory for creating persistent on-disk content-addressed stores.
+ */
+export declare class BasicOnDiskContentAddressedStoreFactory implements ContentAddressedStoreFactory {
+    createStore(dbId: string, options?: OpenStoreOptions): CreateStoreResult;
+}
+//# sourceMappingURL=BasicOnDiskContentAddressedStoreFactory.d.ts.map

package/dist/appendonlystores/BasicOnDiskContentAddressedStoreFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicOnDiskContentAddressedStoreFactory.d.ts","sourceRoot":"","sources":["../../src/appendonlystores/BasicOnDiskContentAddressedStoreFactory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAElG;;GAEG;AACH,qBAAa,uCAAwC,YAAW,4BAA4B;IAC1F,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,iBAAiB;CAKzE"}

package/dist/appendonlystores/BasicOnDiskContentAddressedStoreFactory.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BasicOnDiskContentAddressedStoreFactory = void 0;
+const BasicOnDiskContentAddressedStore_1 = require("../node/appendonlystores/BasicOnDiskContentAddressedStore");
+/**
+ * Factory for creating persistent on-disk content-addressed stores.
+ */
+class BasicOnDiskContentAddressedStoreFactory {
+    createStore(dbId, options) {
+        return {
+            docStore: new BasicOnDiskContentAddressedStore_1.BasicOnDiskContentAddressedStore(dbId, undefined, options),
+        };
+    }
+}
+exports.BasicOnDiskContentAddressedStoreFactory = BasicOnDiskContentAddressedStoreFactory;
+//# sourceMappingURL=BasicOnDiskContentAddressedStoreFactory.js.map

package/dist/appendonlystores/BasicOnDiskContentAddressedStoreFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicOnDiskContentAddressedStoreFactory.js","sourceRoot":"","sources":["../../src/appendonlystores/BasicOnDiskContentAddressedStoreFactory.ts"],"names":[],"mappings":";;;AAAA,gHAA6G;AAG7G;;GAEG;AACH,MAAa,uCAAuC;IAClD,WAAW,CAAC,IAAY,EAAE,OAA0B;QAClD,OAAO;YACL,QAAQ,EAAE,IAAI,mEAAgC,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC;SACzE,CAAC;IACJ,CAAC;CACF;AAND,0FAMC"}

package/dist/appendonlystores/InMemoryContentAddressedStoreFactory.d.ts

@@ -1,5 +1,5 @@
 import { ContentAddressedStoreFactory, CreateStoreResult, OpenStoreOptions } from "../core/types";
 export declare class InMemoryContentAddressedStoreFactory implements ContentAddressedStoreFactory {
-    createStore(dbId: string, _options?: OpenStoreOptions): CreateStoreResult;
+    createStore(dbId: string, options?: OpenStoreOptions): CreateStoreResult;
 }
 //# sourceMappingURL=InMemoryContentAddressedStoreFactory.d.ts.map

package/dist/appendonlystores/InMemoryContentAddressedStoreFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryContentAddressedStoreFactory.d.ts","sourceRoot":"","sources":["../../src/appendonlystores/InMemoryContentAddressedStoreFactory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAElG,qBAAa,oCAAqC,YAAW,4BAA4B;IACvF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,iBAAiB;CAS1E"}
+{"version":3,"file":"InMemoryContentAddressedStoreFactory.d.ts","sourceRoot":"","sources":["../../src/appendonlystores/InMemoryContentAddressedStoreFactory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAElG,qBAAa,oCAAqC,YAAW,4BAA4B;IACvF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,iBAAiB;CASzE"}

package/dist/appendonlystores/InMemoryContentAddressedStoreFactory.js

@@ -3,12 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryContentAddressedStoreFactory = void 0;
 const InMemoryContentAddressedStore_1 = require("../core/appendonlystores/InMemoryContentAddressedStore");
 class InMemoryContentAddressedStoreFactory {
-    createStore(dbId, _options) {
+    createStore(dbId, options) {
         // For in-memory stores, we use a single store for both documents and attachments
         // (no separate attachment store needed for simple/test scenarios)
         // Note: options are ignored for in-memory stores but accepted for interface compatibility
         return {
-            docStore: new InMemoryContentAddressedStore_1.InMemoryContentAddressedStore(dbId),
+            docStore: new InMemoryContentAddressedStore_1.InMemoryContentAddressedStore(dbId, undefined, options),
             // attachmentStore not provided - will use docStore for attachments
         };
     }

package/dist/appendonlystores/InMemoryContentAddressedStoreFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"InMemoryContentAddressedStoreFactory.js","sourceRoot":"","sources":["../../src/appendonlystores/InMemoryContentAddressedStoreFactory.ts"],"names":[],"mappings":";;;AAAA,0GAAuG;AAGvG,MAAa,oCAAoC;IAC/C,WAAW,CAAC,IAAY,EAAE,QAA2B;QACnD,iFAAiF;QACjF,kEAAkE;QAClE,0FAA0F;QAC1F,OAAO;YACL,QAAQ,EAAE,IAAI,6DAA6B,CAAC,IAAI,CAAC;YACjD,mEAAmE;SACpE,CAAC;IACJ,CAAC;CACF;AAVD,oFAUC"}
+{"version":3,"file":"InMemoryContentAddressedStoreFactory.js","sourceRoot":"","sources":["../../src/appendonlystores/InMemoryContentAddressedStoreFactory.ts"],"names":[],"mappings":";;;AAAA,0GAAuG;AAGvG,MAAa,oCAAoC;IAC/C,WAAW,CAAC,IAAY,EAAE,OAA0B;QAClD,iFAAiF;QACjF,kEAAkE;QAClE,0FAA0F;QAC1F,OAAO;YACL,QAAQ,EAAE,IAAI,6DAA6B,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC;YACrE,mEAAmE;SACpE,CAAC;IACJ,CAAC;CACF;AAVD,oFAUC"}

package/dist/appendonlystores/network/ClientNetworkContentAddressedStore.d.ts

@@ -1,7 +1,9 @@
 import type { ContentAddressedStore } from "../../core/types";
-import type { StoreEntry, StoreEntryMetadata, StoreEntryType } from "../../core/types";
+import type { StoreEntry, StoreEntryMetadata, StoreEntryType, StoreScanCursor, StoreScanFilters, StoreScanResult, StoreIdBloomSummary, StoreCompactionStatus } from "../../core/types";
+import type { DocumentMaterializationBatchPlan, DocumentMaterializationPlan, MaterializationPlanOptions } from "../../core/appendonlystores/types";
 import type { CryptoAdapter } from "../../core/crypto/CryptoAdapter";
 import type { NetworkTransport } from "../../core/appendonlystores/network/NetworkTransport";
+import type { NetworkSyncCapabilities } from "../../core/appendonlystores/network/types";
 import { Logger } from "../../core/logging";
 /**
  * Client-side network ContentAddressedStore that forwards all operations to a remote server.
@@ -28,6 +30,8 @@ export declare class ClientNetworkContentAddressedStore implements ContentAddres
     private accessToken;
     private tokenExpiry;
     private logger;
+    private capabilitiesCache;
+    private syncAuthOverride;
     /**
      * Create a new ClientNetworkContentAddressedStore.
      *
@@ -41,6 +45,7 @@ export declare class ClientNetworkContentAddressedStore implements ContentAddres
      */
     constructor(dbId: string, transport: NetworkTransport, cryptoAdapter: CryptoAdapter, username: string, signingKey: CryptoKey, privateEncryptionKey: CryptoKey | string, logger?: Logger);
     getId(): string;
+    getCacheIdentity(): string;
     /**
      * Store entries to the remote store.
      * The entries are pushed to the server immediately.
@@ -80,6 +85,16 @@ export declare class ClientNetworkContentAddressedStore implements ContentAddres
      * Used for synchronization to identify which entries the remote has.
      */
     getAllIds(): Promise<string[]>;
+    /**
+     * Cursor-based metadata scan from the remote store.
+     * Uses transport-native scan support when available, with a compatibility fallback.
+     */
+    scanEntriesSince(cursor: StoreScanCursor | null, limit?: number, filters?: StoreScanFilters): Promise<StoreScanResult>;
+    getIdBloomSummary(): Promise<StoreIdBloomSummary>;
+    getCapabilities(): Promise<NetworkSyncCapabilities>;
+    getCompactionStatus(): Promise<StoreCompactionStatus>;
+    planDocumentMaterialization(docId: string, options?: MaterializationPlanOptions): Promise<DocumentMaterializationPlan>;
+    planDocumentMaterializationBatch(docIds: string[], options?: MaterializationPlanOptions): Promise<DocumentMaterializationBatchPlan>;
     /**
      * Resolve dependencies for an entry.
      *
@@ -104,6 +119,7 @@ export declare class ClientNetworkContentAddressedStore implements ContentAddres
      * Sign a challenge with the user's private signing key.
      */
     private signChallenge;
+    private signChallengeWithKey;
     /**
      * Decrypt network-encrypted entries.
      * Transforms NetworkEncryptedEntry[] to StoreEntry[].
@@ -114,5 +130,18 @@ export declare class ClientNetworkContentAddressedStore implements ContentAddres
      * Call this if you need to force re-authentication.
      */
     clearAuthCache(): void;
+    /**
+     * Set or clear a temporary per-sync authentication override.
+     * Intended for bootstrap scenarios (for example authenticating as admin).
+     */
+    setSyncAuthOverride(override: {
+        username: string;
+        signingKey: CryptoKey;
+        privateEncryptionKey?: CryptoKey | string;
+    } | null): void;
+    clearSyncAuthOverride(): void;
+    private getActiveAuthUsername;
+    private getActiveSigningKey;
+    private getActivePrivateEncryptionKey;
 }
 //# sourceMappingURL=ClientNetworkContentAddressedStore.d.ts.map

package/dist/appendonlystores/network/ClientNetworkContentAddressedStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientNetworkContentAddressedStore.d.ts","sourceRoot":"","sources":["../../../src/appendonlystores/network/ClientNetworkContentAddressedStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sDAAsD,CAAC;AAI7F,OAAO,EAAE,MAAM,EAAoC,MAAM,oBAAoB,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,qBAAa,kCAAmC,YAAW,qBAAqB;IAC9E,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,aAAa,CAAgB;IAGrC,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;;;;;;OAUG;gBAED,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,gBAAgB,EAC3B,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,EACrB,oBAAoB,EAAE,SAAS,GAAG,MAAM,EACxC,MAAM,CAAC,EAAE,MAAM;IAejB,KAAK,IAAI,MAAM;IAIf;;;OAGG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAatD;;;;;OAKG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAmBtD;;;;;OAKG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAclD;;;;;OAKG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAWvE;;OAEG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAU5F;;OAEG;IACG,WAAW,CACf,IAAI,EAAE,cAAc,EACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,EAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAehC;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAUpC;;;;OAIG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC;IAUpB;;;;;;;;OAQG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD;;OAEG;YACW,mBAAmB;IA8CjC;;OAEG;YACW,aAAa;IAa3B;;;OAGG;YACW,qBAAqB;IAkCnC;;;OAGG;IACH,cAAc,IAAI,IAAI;CAIvB"}
+{"version":3,"file":"ClientNetworkContentAddressedStore.d.ts","sourceRoot":"","sources":["../../../src/appendonlystores/network/ClientNetworkContentAddressedStore.ts"],"names":[],"mappings":"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"}

package/dist/appendonlystores/network/ClientNetworkContentAddressedStore.js

@@ -4,6 +4,7 @@ exports.ClientNetworkContentAddressedStore = void 0;
 const types_1 = require("../../core/appendonlystores/network/types");
 const RSAEncryption_1 = require("../../core/crypto/RSAEncryption");
 const logging_1 = require("../../core/logging");
+const bloom_1 = require("../../core/appendonlystores/bloom");
 /**
  * Client-side network ContentAddressedStore that forwards all operations to a remote server.
  *
@@ -34,6 +35,8 @@ class ClientNetworkContentAddressedStore {
         // Cached access token
         this.accessToken = null;
         this.tokenExpiry = 0;
+        this.capabilitiesCache = null;
+        this.syncAuthOverride = null;
         this.dbId = dbId;
         this.transport = transport;
         this.cryptoAdapter = cryptoAdapter;
@@ -49,6 +52,10 @@ class ClientNetworkContentAddressedStore {
     getId() {
         return this.dbId;
     }
+    getCacheIdentity() {
+        const transportId = this.transport.getIdentity?.() ?? "unknown";
+        return `net:${transportId}/${this.dbId}`;
+    }
     /**
      * Store entries to the remote store.
      * The entries are pushed to the server immediately.
@@ -142,6 +149,115 @@ class ClientNetworkContentAddressedStore {
         this.logger.debug(`Remote has ${allIds.length} entry IDs`);
         return allIds;
     }
+    /**
+     * Cursor-based metadata scan from the remote store.
+     * Uses transport-native scan support when available, with a compatibility fallback.
+     */
+    async scanEntriesSince(cursor, limit = Number.MAX_SAFE_INTEGER, filters) {
+        const token = await this.ensureAuthenticated();
+        const capabilities = await this.getCapabilities();
+        if (capabilities.supportsCursorScan && this.transport.scanEntriesSince) {
+            return this.transport.scanEntriesSince(token, cursor, limit, filters);
+        }
+        // Compatibility fallback: fetch metadata via legacy endpoint and paginate client-side.
+        const all = await this.findNewEntries([]);
+        const filtered = all
+            .filter((meta) => {
+            if (filters?.docId && meta.docId !== filters.docId) {
+                return false;
+            }
+            if (filters?.entryTypes && filters.entryTypes.length > 0 && !filters.entryTypes.includes(meta.entryType)) {
+                return false;
+            }
+            if (filters?.creationDateFrom !== undefined && filters.creationDateFrom !== null && meta.createdAt < filters.creationDateFrom) {
+                return false;
+            }
+            if (filters?.creationDateUntil !== undefined && filters.creationDateUntil !== null && meta.createdAt >= filters.creationDateUntil) {
+                return false;
+            }
+            return true;
+        })
+            .sort((a, b) => (a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt - b.createdAt));
+        const startIndex = cursor === null
+            ? 0
+            : filtered.findIndex((meta) => meta.createdAt > cursor.createdAt || (meta.createdAt === cursor.createdAt && meta.id > cursor.id));
+        if (startIndex === -1) {
+            return { entries: [], nextCursor: cursor, hasMore: false };
+        }
+        const page = filtered.slice(startIndex, startIndex + limit);
+        const last = page.length > 0 ? page[page.length - 1] : null;
+        return {
+            entries: page,
+            nextCursor: last ? { createdAt: last.createdAt, id: last.id } : cursor,
+            hasMore: startIndex + page.length < filtered.length,
+        };
+    }
+    async getIdBloomSummary() {
+        const token = await this.ensureAuthenticated();
+        const capabilities = await this.getCapabilities();
+        if (capabilities.supportsIdBloomSummary && this.transport.getIdBloomSummary) {
+            return this.transport.getIdBloomSummary(token);
+        }
+        // Compatibility fallback for older transports.
+        const ids = await this.getAllIds();
+        return (0, bloom_1.createIdBloomSummary)(ids);
+    }
+    async getCapabilities() {
+        if (this.capabilitiesCache) {
+            return this.capabilitiesCache;
+        }
+        const token = await this.ensureAuthenticated();
+        if (this.transport.getCapabilities) {
+            this.capabilitiesCache = await this.transport.getCapabilities(token);
+            return this.capabilitiesCache;
+        }
+        this.capabilitiesCache = {
+            protocolVersion: "sync-v1",
+            supportsCursorScan: false,
+            supportsIdBloomSummary: false,
+            supportsCompactionStatus: false,
+            supportsMaterializationPlanning: false,
+            supportsBatchMaterializationPlanning: false,
+        };
+        return this.capabilitiesCache;
+    }
+    async getCompactionStatus() {
+        const token = await this.ensureAuthenticated();
+        const capabilities = await this.getCapabilities();
+        if (capabilities.supportsCompactionStatus && this.transport.getCompactionStatus) {
+            return this.transport.getCompactionStatus(token);
+        }
+        // Compatibility fallback for older transports.
+        return {
+            enabled: false,
+            compactionMinFiles: 0,
+            compactionMaxBytes: 0,
+            totalCompactions: 0,
+            totalCompactedFiles: 0,
+            totalCompactedBytes: 0,
+            totalCompactionDurationMs: 0,
+            lastCompactionAt: null,
+            lastCompactedFiles: 0,
+            lastCompactedBytes: 0,
+            lastCompactionDurationMs: 0,
+        };
+    }
+    async planDocumentMaterialization(docId, options) {
+        const token = await this.ensureAuthenticated();
+        const capabilities = await this.getCapabilities();
+        if (!capabilities.supportsMaterializationPlanning || !this.transport.planDocumentMaterialization) {
+            throw new Error("Remote server does not support required materialization planning protocol");
+        }
+        return this.transport.planDocumentMaterialization(token, docId, options);
+    }
+    async planDocumentMaterializationBatch(docIds, options) {
+        const token = await this.ensureAuthenticated();
+        const capabilities = await this.getCapabilities();
+        if (!capabilities.supportsBatchMaterializationPlanning || !this.transport.planDocumentMaterializationBatch) {
+            throw new Error("Remote server does not support required batch materialization planning protocol");
+        }
+        return this.transport.planDocumentMaterializationBatch(token, docIds, options);
+    }
     /**
      * Resolve dependencies for an entry.
      *
@@ -176,12 +292,13 @@ class ClientNetworkContentAddressedStore {
         if (this.accessToken && this.tokenExpiry > now + 60000) { // 1 minute buffer
             return this.accessToken;
         }
-        this.logger.debug(`Authenticating user: ${this.username}`);
+        const authUsername = this.getActiveAuthUsername();
+        this.logger.debug(`Authenticating user: ${authUsername}`);
         // Request a challenge
-        const challenge = await this.transport.requestChallenge(this.username);
+        const challenge = await this.transport.requestChallenge(authUsername);
         this.logger.debug(`Received challenge: ${challenge}`);
         // Sign the challenge
-        const signature = await this.signChallenge(challenge);
+        const signature = await this.signChallengeWithKey(challenge, this.getActiveSigningKey());
         this.logger.debug(`Signed challenge`);
         // Authenticate
         const result = await this.transport.authenticate(challenge, signature);
@@ -208,9 +325,12 @@ class ClientNetworkContentAddressedStore {
      * Sign a challenge with the user's private signing key.
      */
     async signChallenge(challenge) {
+        return this.signChallengeWithKey(challenge, this.signingKey);
+    }
+    async signChallengeWithKey(challenge, signingKey) {
         const subtle = this.cryptoAdapter.getSubtle();
         const messageBytes = new TextEncoder().encode(challenge);
-        const signature = await subtle.sign({ name: "Ed25519" }, this.signingKey, messageBytes);
+        const signature = await subtle.sign({ name: "Ed25519" }, signingKey, messageBytes);
         return new Uint8Array(signature);
     }
     /**
@@ -221,7 +341,7 @@ class ClientNetworkContentAddressedStore {
         const results = [];
         for (const enc of encryptedEntries) {
             // Decrypt the RSA layer to get the original symmetric-encrypted payload
-            const encryptedData = await this.rsaEncryption.decrypt(enc.rsaEncryptedPayload, this.privateEncryptionKey);
+            const encryptedData = await this.rsaEncryption.decrypt(enc.rsaEncryptedPayload, this.getActivePrivateEncryptionKey());
             // Create the full StoreEntry using metadata from the network entry
             const entry = {
                 entryType: enc.entryType,
@@ -232,6 +352,8 @@ class ClientNetworkContentAddressedStore {
                 createdAt: enc.createdAt,
                 createdByPublicKey: enc.createdByPublicKey,
                 decryptionKeyId: enc.decryptionKeyId,
+                snapshotHeadHashes: enc.snapshotHeadHashes,
+                snapshotHeadEntryIds: enc.snapshotHeadEntryIds,
                 signature: enc.signature,
                 originalSize: enc.originalSize,
                 encryptedSize: enc.encryptedSize,
@@ -248,6 +370,31 @@ class ClientNetworkContentAddressedStore {
     clearAuthCache() {
         this.accessToken = null;
         this.tokenExpiry = 0;
+        this.capabilitiesCache = null;
+    }
+    /**
+     * Set or clear a temporary per-sync authentication override.
+     * Intended for bootstrap scenarios (for example authenticating as admin).
+     */
+    setSyncAuthOverride(override) {
+        this.syncAuthOverride = override;
+        // Changing auth identity requires token refresh.
+        this.clearAuthCache();
+    }
+    clearSyncAuthOverride() {
+        if (this.syncAuthOverride) {
+            this.syncAuthOverride = null;
+            this.clearAuthCache();
+        }
+    }
+    getActiveAuthUsername() {
+        return this.syncAuthOverride?.username ?? this.username;
+    }
+    getActiveSigningKey() {
+        return this.syncAuthOverride?.signingKey ?? this.signingKey;
+    }
+    getActivePrivateEncryptionKey() {
+        return this.syncAuthOverride?.privateEncryptionKey ?? this.privateEncryptionKey;
     }
 }
 exports.ClientNetworkContentAddressedStore = ClientNetworkContentAddressedStore;