@aztec/kv-store 0.0.1-commit.a5db02d → 0.0.1-commit.aa0c64f

package/dest/sqlite-opfs/store.js

@@ -1,8 +1,10 @@
 import { SerialQueue } from '@aztec/foundation/queue';
 import { SQLiteOPFSAztecArray } from './array.js';
-import { SqliteEncryptionError } from './errors.js';
+import { SqliteCorruptionError, SqliteEncryptionError, isCorruptionMessage } from './errors.js';
 import { SQLiteOPFSAztecMap } from './map.js';
 import { SQLiteOPFSAztecMultiMap } from './multi_map.js';
+import { quarantineDuplicatePool } from './pool_integrity.js';
+import { acquirePoolLock, normalizePoolDirectory } from './pool_lock.js';
 import { SQLiteOPFSAztecSet } from './set.js';
 import { SQLiteOPFSAztecSingleton } from './singleton.js';
 /**
@@ -16,6 +18,7 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
  * nested ops bypass it to avoid deadlock.
  */ export class AztecSQLiteOPFSStore {
     isEphemeral;
+    poolLock;
     #worker;
     #pending;
     #txQueue;
@@ -24,13 +27,16 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
     #nextId;
     #inTx;
     #closed;
-    constructor(worker, name, log, isEphemeral){
+    #workerFailed;
+    constructor(worker, name, log, isEphemeral, poolLock){
         this.isEphemeral = isEphemeral;
+        this.poolLock = poolLock;
         this.#pending = new Map();
         this.#txQueue = new SerialQueue();
         this.#nextId = 0;
         this.#inTx = false;
         this.#closed = false;
+        this.#workerFailed = false;
         this.#worker = worker;
         this.#name = name;
         this.#log = log;
@@ -45,6 +51,7 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
             handler.resolve(ev.data);
         };
         this.#worker.onerror = (ev)=>{
+            this.#workerFailed = true;
             this.#log.error(`SQLite worker crashed: ${ev.message}`);
             this.#rejectPending(`SQLite worker crashed: ${ev.message}`);
         };
@@ -57,6 +64,10 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
    * required when multiple stores coexist in the same tab, because the SAH Pool holds
    * an exclusive lock on its directory.
    *
+   * Persistent stores hold an origin-wide Web Lock for the pool directory until close
+   * or delete. If another store instance already owns it, open fails immediately with
+   * `SqlitePoolBusyError`.
+   *
    * Pass `encryptionKey` (exactly 32 bytes) to enable at-rest encryption via sqlite3mc's
    * ChaCha20 page cipher. The key buffer is **transferred** to the worker — its
    * ArrayBuffer detaches on the caller side after `postMessage`. This is intentional:
@@ -74,30 +85,40 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
         }
         const dbName = name && !ephemeral ? name : `tmp-${globalThis.crypto.getRandomValues(new Uint8Array(8)).join('')}`;
         log.debug(`Opening SQLite-OPFS ${ephemeral ? 'ephemeral ' : ''}${encryptionKey ? 'encrypted ' : ''}database ${dbName}`);
-        const worker = new Worker(new URL('./worker.js', import.meta.url), {
-            type: 'module'
-        });
-        const store = new AztecSQLiteOPFSStore(worker, dbName, log, ephemeral);
-        // Transfer (not clone) the key buffer to the worker so we don't leave a
-        // second copy on the main thread. Caveat: this detaches the caller's
-        // encryptionKey.buffer — subsequent reads from the same Uint8Array are empty.
-        const transfer = encryptionKey ? [
-            encryptionKey.buffer
-        ] : undefined;
+        const effectivePoolDirectory = ephemeral ? undefined : normalizePoolDirectory(poolDirectory);
+        const poolLock = effectivePoolDirectory ? await acquirePoolLock(effectivePoolDirectory) : undefined;
+        let worker;
         try {
+            if (effectivePoolDirectory) {
+                const quarantine = await quarantineDuplicatePool(effectivePoolDirectory);
+                if (quarantine) {
+                    log.warn(`Quarantined SQLite-OPFS pool with duplicate logical file mappings`, quarantine);
+                }
+            }
+            worker = new Worker(new URL('./worker.js', import.meta.url), {
+                type: 'module'
+            });
+            const store = new AztecSQLiteOPFSStore(worker, dbName, log, ephemeral, poolLock);
+            // Transfer (not clone) the key buffer to the worker so we don't leave a
+            // second copy on the main thread. Caveat: this detaches the caller's
+            // encryptionKey.buffer — subsequent reads from the same Uint8Array are empty.
+            const transfer = encryptionKey ? [
+                encryptionKey.buffer
+            ] : undefined;
             await store.#sendRequest({
                 type: 'init',
                 id: store.#allocId(),
                 dbName,
                 ephemeral,
-                poolDirectory,
+                poolDirectory: effectivePoolDirectory,
                 encryptionKey
             }, transfer);
+            return store;
         } catch (err) {
-            worker.terminate();
+            worker?.terminate();
+            await poolLock?.release();
             throw err;
         }
-        return store;
     }
     openMap(name) {
         return new SQLiteOPFSAztecMap(this, name);
@@ -157,14 +178,18 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
             return;
         }
         this.#closed = true;
-        await this.#txQueue.end();
-        await this.#sendRequest({
-            type: 'deleteDb',
-            id: this.#allocId(),
-            dbName: this.#name
-        }).catch((err)=>this.#log.warn(`SQLite deleteDb failed: ${err instanceof Error ? err.message : err}`));
-        this.#worker.terminate();
-        this.#rejectPending('SQLite store deleted');
+        try {
+            await this.#txQueue.end();
+            await this.#sendRequest({
+                type: 'deleteDb',
+                id: this.#allocId(),
+                dbName: this.#name
+            }).catch((err)=>this.#log.warn(`SQLite deleteDb failed: ${err instanceof Error ? err.message : err}`));
+        } finally{
+            this.#worker.terminate();
+            this.#rejectPending('SQLite store deleted');
+            await this.poolLock?.release();
+        }
     }
     /**
    * Placeholder — returns zeros to mirror the IndexedDB backend. SQLite exposes real
@@ -186,13 +211,17 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
             return;
         }
         this.#closed = true;
-        await this.#txQueue.end();
-        await this.#sendRequest({
-            type: 'close',
-            id: this.#allocId()
-        }).catch(()=>{});
-        this.#worker.terminate();
-        this.#rejectPending('SQLite store closed');
+        try {
+            await this.#txQueue.end();
+            await this.#sendRequest({
+                type: 'close',
+                id: this.#allocId()
+            }).catch(()=>{});
+        } finally{
+            this.#worker.terminate();
+            this.#rejectPending('SQLite store closed');
+            await this.poolLock?.release();
+        }
     }
     backupTo(_dstPath, _compact) {
         throw new Error('Method not implemented.');
@@ -253,15 +282,22 @@ import { SQLiteOPFSAztecSingleton } from './singleton.js';
         this.#pending.clear();
     }
     #sendRequest(req, transfer) {
+        if (this.#workerFailed) {
+            return Promise.reject(new Error('SQLite worker has crashed'));
+        }
         return new Promise((resolve, reject)=>{
             this.#pending.set(req.id, {
                 resolve: (resp)=>{
                     if (resp.type === 'err') {
-                        // Re-hydrate encryption-shaped errors as the typed class so consumers
-                        // can pattern-match on `instanceof SqliteEncryptionError`. Plain
-                        // errors stay plain — the wire protocol only tags encryption paths.
+                        // Re-hydrate typed errors so consumers can pattern-match on
+                        // `instanceof`. Encryption is tagged on the wire (some cases are
+                        // pre-flight throws with no message to match); corruption is a
+                        // single unambiguous message, so we classify it here rather than
+                        // adding a redundant wire field. Everything else stays a plain Error.
                         if (resp.encryptionCode !== undefined) {
                             reject(new SqliteEncryptionError(resp.encryptionCode, resp.message));
+                        } else if (isCorruptionMessage(resp.message)) {
+                            reject(new SqliteCorruptionError(resp.message));
                         } else {
                             reject(new Error(resp.message));
                         }

package/dest/sqlite-opfs/worker.js

@@ -1,6 +1,7 @@
 /// <reference lib="webworker" />
 import sqlite3InitModule from '@aztec/sqlite3mc-wasm';
 import { SqliteEncryptionError, isDecryptFailureMessage } from './errors.js';
+import { DEFAULT_SAH_POOL_DIRECTORY } from './pool_lock.js';
 const SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS data (
     slot TEXT NOT NULL PRIMARY KEY,
@@ -15,7 +16,6 @@ const SCHEMA_SQL = `
   CREATE UNIQUE INDEX IF NOT EXISTS idx_container_key_count ON data(container, key, key_count);
   CREATE UNIQUE INDEX IF NOT EXISTS idx_container_key_hash ON data(container, key, hash);
 `;
-const DEFAULT_SAH_POOL_DIRECTORY = '.aztec-kv';
 const SAH_POOL_VFS_NAME = 'aztec-kv-opfs';
 const MC_SAH_POOL_VFS_NAME = `multipleciphers-${SAH_POOL_VFS_NAME}`;
 let sqlite3;
@@ -74,10 +74,13 @@ async function handleInit(dbName, ephemeral, directory, encryptionKey) {
     runSql(SCHEMA_SQL);
 }
 function handleClose() {
-    db?.close();
-    db = undefined;
-    dbPath = undefined;
-    releasePool();
+    try {
+        db?.close();
+    } finally{
+        db = undefined;
+        dbPath = undefined;
+        releasePool();
+    }
 }
 /**
  * Releases the SAH pool's OPFS sync access handles before the terminal RPC is acked. Worker
@@ -232,11 +235,19 @@ self.onmessage = async (ev)=>{
         }
     } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const encryptionCode = detectEncryptionCode(req, err, message);
+        if (req.type === 'init') {
+            try {
+                handleClose();
+            } catch  {
+            // The main thread terminates this worker after a failed init, which releases any remaining OPFS handles.
+            }
+        }
         respond({
             type: 'err',
             id: req.id,
             message,
-            encryptionCode: detectEncryptionCode(req, err, message)
+            encryptionCode
         });
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/kv-store",
-  "version": "0.0.1-commit.a5db02d",
+  "version": "0.0.1-commit.aa0c64f",
   "type": "module",
   "exports": {
     ".": "./dest/interfaces/index.js",
@@ -36,12 +36,12 @@
     "./package.local.json"
   ],
   "dependencies": {
-    "@aztec/constants": "0.0.1-commit.a5db02d",
-    "@aztec/ethereum": "0.0.1-commit.a5db02d",
-    "@aztec/foundation": "0.0.1-commit.a5db02d",
-    "@aztec/native": "0.0.1-commit.a5db02d",
-    "@aztec/sqlite3mc-wasm": "0.0.1-commit.a5db02d",
-    "@aztec/stdlib": "0.0.1-commit.a5db02d",
+    "@aztec/constants": "0.0.1-commit.aa0c64f",
+    "@aztec/ethereum": "0.0.1-commit.aa0c64f",
+    "@aztec/foundation": "0.0.1-commit.aa0c64f",
+    "@aztec/native": "0.0.1-commit.aa0c64f",
+    "@aztec/sqlite3mc-wasm": "0.0.1-commit.aa0c64f",
+    "@aztec/stdlib": "0.0.1-commit.aa0c64f",
     "idb": "^8.0.0",
     "lmdb": "^3.2.0",
     "msgpackr": "^1.11.2",

package/src/sqlite-opfs/errors.ts

@@ -42,3 +42,53 @@ const SQLITE3MC_DECRYPT_ERROR_PATTERNS: readonly RegExp[] = [
 export function isDecryptFailureMessage(message: string): boolean {
   return SQLITE3MC_DECRYPT_ERROR_PATTERNS.some(p => p.test(message));
 }
+
+/**
+ * Error thrown by sqlite-opfs when the on-disk database image is corrupt
+ * (`SQLITE_CORRUPT`, result code 11 — "database disk image is malformed").
+ *
+ * Distinct from {@link SqliteEncryptionError}: no key recovers a corrupt image,
+ * so there is nothing to retry. The only escape is to delete the store and start
+ * fresh, so consumers pattern-match on `instanceof SqliteCorruptionError` to wipe
+ * and reopen rather than surfacing a dead-end error.
+ **/
+export class SqliteCorruptionError extends Error {
+  constructor(message: string, opts?: { cause?: unknown }) {
+    super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+    this.name = 'SqliteCorruptionError';
+  }
+}
+
+/** Error thrown when another browser context already owns a store's OPFS pool. */
+export class SqlitePoolBusyError extends Error {
+  constructor(public readonly poolDirectory: string) {
+    super(`SQLite-OPFS pool "${poolDirectory}" is already in use by another store instance`);
+    this.name = 'SqlitePoolBusyError';
+  }
+}
+
+/** Error thrown when the browser context does not expose the Web Locks API required by the OPFS SAH pool. */
+export class SqliteWebLocksUnavailableError extends Error {
+  constructor() {
+    super('SQLite-OPFS requires the Web Locks API, but it is unavailable in this browser context');
+    this.name = 'SqliteWebLocksUnavailableError';
+  }
+}
+
+/**
+ * Strings/codes raised by SQLite when a database image is corrupt. Kept disjoint
+ * from {@link SQLITE3MC_DECRYPT_ERROR_PATTERNS}: "file is not a database"
+ * (SQLITE_NOTADB) is the decrypt signal, whereas a malformed image is the
+ * genuinely-unrecoverable SQLITE_CORRUPT.
+ **/
+const SQLITE_CORRUPTION_ERROR_PATTERNS: readonly RegExp[] = [
+  /database disk image is malformed/i,
+  /\bSQLITE_CORRUPT\b/i,
+];
+
+/**
+ * Returns `true` if `message` matches one of the known SQLite corruption strings.
+ **/
+export function isCorruptionMessage(message: string): boolean {
+  return SQLITE_CORRUPTION_ERROR_PATTERNS.some(p => p.test(message));
+}

package/src/sqlite-opfs/index.ts

@@ -3,9 +3,14 @@ import { createLogger } from '@aztec/foundation/log';
 import { AztecSQLiteOPFSStore } from './store.js';
 
 export { AztecSQLiteOPFSStore } from './store.js';
-export { SqliteEncryptionError } from './errors.js';
+export {
+  SqliteCorruptionError,
+  SqliteEncryptionError,
+  SqlitePoolBusyError,
+  SqliteWebLocksUnavailableError,
+} from './errors.js';
 export type { SqliteEncryptionErrorCode } from './errors.js';
-export { OPFS_POOL_DIR_PREFIX, deleteStore, listStores, storePoolDirectory } from './manage.js';
+export { OPFS_POOL_DIR_PREFIX, deletePoolDirectory, deleteStore, listStores, storePoolDirectory } from './manage.js';
 
 export function openTmpStore(ephemeral: boolean = false): Promise<AztecSQLiteOPFSStore> {
   return AztecSQLiteOPFSStore.open(createLogger('kv-store:sqlite-opfs'), undefined, ephemeral);

package/src/sqlite-opfs/manage.ts

@@ -1,3 +1,5 @@
+import { normalizePoolDirectory, withPoolLock } from './pool_lock.js';
+
 /** Prefix for the per-store OPFS SAH pool directories owned by this package. */
 export const OPFS_POOL_DIR_PREFIX = '.aztec-kv-';
 
@@ -28,9 +30,17 @@ export async function listStores(): Promise<string[]> {
 
 /**
  * Permanently deletes a store by effective name (as returned by {@link listStores}). The store must be closed:
- * an open store's SAH pool holds locks on the directory and the removal will reject.
+ * an open store holds the directory's Web Lock and the removal will reject with `SqlitePoolBusyError`.
  */
 export async function deleteStore(effectiveName: string): Promise<void> {
-  const root = await navigator.storage.getDirectory();
-  await root.removeEntry(storePoolDirectory(effectiveName), { recursive: true });
+  await deletePoolDirectory(storePoolDirectory(effectiveName));
+}
+
+/** Permanently deletes one OPFS SAH-pool directory after exclusively locking it. */
+export async function deletePoolDirectory(poolDirectory: string): Promise<void> {
+  poolDirectory = normalizePoolDirectory(poolDirectory);
+  await withPoolLock(poolDirectory, async () => {
+    const root = await navigator.storage.getDirectory();
+    await root.removeEntry(poolDirectory, { recursive: true });
+  });
 }