@aztec/kv-store 0.0.1-commit.3fd054f6 → 0.0.1-commit.431c48d

package/dest/sqlite-opfs/pool_integrity.js

@@ -0,0 +1,282 @@
+import { normalizePoolDirectory } from './pool_lock.js';
+// The constants below mirror the opaque-file header format of the pinned opfs-sahpool VFS
+// (`yarn-project/sqlite3mc-wasm/vendor/jswasm/sqlite3.mjs`, class `OpfsSAHPool`). The pool names its files randomly
+// under `.opaque/` and prepends a header that maps each one back to its logical SQLite path:
+//
+//   bytes [0, 512)    logical path, NUL-terminated UTF-8 (HEADER_MAX_PATH_SIZE)
+//   bytes [512, 516)  SQLite open-flags of the file, big-endian uint32 (HEADER_FLAGS_SIZE)
+//   bytes [516, 524)  digest over the preceding 516 bytes, two uint32 words (HEADER_DIGEST_SIZE)
+//
+// Database content starts at byte 4096 (the pool's SECTOR_SIZE). We re-read the header ourselves rather than asking
+// the VFS because the upstream pool "repairs" anything it cannot validate by disassociating the file — destroying
+// exactly the evidence this module exists to quarantine. The browser regression test writes a real pool through the
+// pinned VFS before duplicating an opaque file, so a vendor upgrade that changes the layout breaks detection loudly
+// rather than silently.
+const OPAQUE_DIRECTORY = '.opaque';
+const HEADER_MAX_PATH_SIZE = 512;
+const HEADER_FLAGS_SIZE = 4;
+const HEADER_DIGEST_SIZE = 8;
+const HEADER_CORPUS_SIZE = HEADER_MAX_PATH_SIZE + HEADER_FLAGS_SIZE;
+const HEADER_SIZE = HEADER_CORPUS_SIZE + HEADER_DIGEST_SIZE;
+// Standard SQLite open-flag bit values (sqlite3.h). Restated as literals because the header stores them numerically
+// and this module runs on the main thread, without the sqlite3 WASM bundle that defines `capi.SQLITE_OPEN_*`.
+const SQLITE_OPEN_DELETEONCLOSE = 0x00000008;
+const SQLITE_OPEN_MEMORY = 0x00000080;
+const SQLITE_OPEN_MAIN_DB = 0x00000100;
+const SQLITE_OPEN_MAIN_JOURNAL = 0x00000800;
+const SQLITE_OPEN_SUPER_JOURNAL = 0x00004000;
+const SQLITE_OPEN_WAL = 0x00080000;
+// A live association must name one of the file types the pool persists; transient types (temp DBs, statement
+// journals) never survive in a valid header.
+const PERSISTENT_FILE_TYPES = SQLITE_OPEN_MAIN_DB | SQLITE_OPEN_MAIN_JOURNAL | SQLITE_OPEN_SUPER_JOURNAL | SQLITE_OPEN_WAL;
+// The upstream VFS repurposes SQLITE_OPEN_MEMORY — meaningless for a file that exists on disk — as a header version
+// marker: headers written with it set carry a real digest, while legacy headers leave it unset and store all-zero
+// digest words.
+const FLAG_COMPUTE_DIGEST_V2 = SQLITE_OPEN_MEMORY;
+export const OPFS_QUARANTINE_ROOT_DIRECTORY = '.aztec-sqlite-quarantine';
+/**
+ * Detects duplicate SAH logical-file associations and, if found, copies the complete pool into quarantine before
+ * removing the original. The caller must hold the pool's exclusive Web Lock for the whole operation.
+ */ export async function quarantineDuplicatePool(poolDirectory) {
+    poolDirectory = normalizePoolDirectory(poolDirectory);
+    const root = await navigator.storage.getDirectory();
+    const source = await getDirectory(root, poolDirectory);
+    if (!source) {
+        return undefined;
+    }
+    const opaque = await getChildDirectory(source, OPAQUE_DIRECTORY);
+    if (!opaque) {
+        return undefined;
+    }
+    const duplicateAssociations = await findDuplicateAssociations(opaque);
+    if (duplicateAssociations.length === 0) {
+        return undefined;
+    }
+    const quarantineRoot = await root.getDirectoryHandle(OPFS_QUARANTINE_ROOT_DIRECTORY, {
+        create: true
+    });
+    const quarantineName = createQuarantineName();
+    const destination = await quarantineRoot.getDirectoryHandle(quarantineName, {
+        create: true
+    });
+    const metadata = {
+        formatVersion: 1,
+        originalPoolDirectory: poolDirectory,
+        quarantinedAt: new Date().toISOString(),
+        duplicateAssociations
+    };
+    let quarantineComplete = false;
+    try {
+        await copyDirectory(source, destination);
+        await verifyDirectoryCopy(source, destination);
+        await writeJson(destination, 'quarantine.json', metadata);
+        quarantineComplete = true;
+        await removeDirectory(root, poolDirectory);
+    } catch (err) {
+        if (!quarantineComplete) {
+            await quarantineRoot.removeEntry(quarantineName, {
+                recursive: true
+            }).catch(()=>{});
+        }
+        throw err;
+    }
+    return {
+        ...metadata,
+        quarantineDirectory: `${OPFS_QUARANTINE_ROOT_DIRECTORY}/${quarantineName}`
+    };
+}
+async function findDuplicateAssociations(opaque) {
+    const associations = new Map();
+    for await (const [opaqueName, handle] of opaque.entries()){
+        if (handle.kind !== 'file') {
+            continue;
+        }
+        const logicalPath = await readAssociatedPath(handle);
+        if (logicalPath) {
+            const names = associations.get(logicalPath) ?? [];
+            names.push(opaqueName);
+            associations.set(logicalPath, names);
+        }
+    }
+    return [
+        ...associations.entries()
+    ].filter(([, names])=>names.length > 1).map(([logicalPath, opaqueFileNames])=>({
+            logicalPath,
+            opaqueFileNames: opaqueFileNames.sort()
+        })).sort((a, b)=>a.logicalPath.localeCompare(b.logicalPath));
+}
+/**
+ * Returns the logical SQLite path an opaque SAH file is associated with, or undefined if the file is not a live,
+ * valid association. Applies the same checks as the vendored pool's `getAssociatedPath`: a non-empty NUL-terminated
+ * path, open-flags naming a persistent file type without DELETEONCLOSE, and a matching header digest. Files failing
+ * any check are the pool's free-list or garbage entries — the VFS itself would disassociate them on open — so they
+ * cannot participate in a duplicate mapping.
+ */ async function readAssociatedPath(handle) {
+    const file = await handle.getFile();
+    if (file.size < HEADER_SIZE) {
+        return undefined;
+    }
+    const header = new Uint8Array(await file.slice(0, HEADER_SIZE).arrayBuffer());
+    const pathEnd = header.subarray(0, HEADER_MAX_PATH_SIZE).indexOf(0);
+    if (pathEnd <= 0) {
+        return undefined;
+    }
+    const dataView = new DataView(header.buffer, header.byteOffset, header.byteLength);
+    const flags = dataView.getUint32(HEADER_MAX_PATH_SIZE);
+    if ((flags & SQLITE_OPEN_DELETEONCLOSE) !== 0 || (flags & PERSISTENT_FILE_TYPES) === 0) {
+        return undefined;
+    }
+    if (!hasValidDigest(header, flags)) {
+        return undefined;
+    }
+    try {
+        return new TextDecoder('utf-8', {
+            fatal: true
+        }).decode(header.subarray(0, pathEnd));
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Byte-for-byte port of the vendored pool's `computeDigest`, checked against the digest words stored in the header.
+ */ function hasValidDigest(header, flags) {
+    let expected0 = 0;
+    let expected1 = 0;
+    if ((flags & FLAG_COMPUTE_DIGEST_V2) !== 0) {
+        // These seeds (0xdeadbeef, 0x41c6ce57) and odd multipliers (2654435761, 104729) are the upstream author's choices
+        // (a cyrb53-hash variant) and carry no meaning here beyond having to match the vendored implementation bit for
+        // bit.
+        expected0 = 0xdeadbeef;
+        expected1 = 0x41c6ce57;
+        for (const value of header.subarray(0, HEADER_CORPUS_SIZE)){
+            expected0 = Math.imul(expected0 ^ value, 2654435761);
+            expected1 = Math.imul(expected1 ^ value, 104729);
+        }
+        expected0 >>>= 0;
+        expected1 >>>= 0;
+    }
+    const dataView = new DataView(header.buffer, header.byteOffset, header.byteLength);
+    return dataView.getUint32(HEADER_CORPUS_SIZE, true) === expected0 && dataView.getUint32(HEADER_CORPUS_SIZE + 4, true) === expected1;
+}
+async function getDirectory(root, path) {
+    let current = root;
+    try {
+        for (const segment of path.split('/')){
+            current = await current.getDirectoryHandle(segment);
+        }
+        return current;
+    } catch (err) {
+        if (err instanceof DOMException && err.name === 'NotFoundError') {
+            return undefined;
+        }
+        throw err;
+    }
+}
+async function getChildDirectory(parent, name) {
+    try {
+        return await parent.getDirectoryHandle(name);
+    } catch (err) {
+        if (err instanceof DOMException && err.name === 'NotFoundError') {
+            return undefined;
+        }
+        throw err;
+    }
+}
+async function removeDirectory(root, path) {
+    const segments = path.split('/');
+    const name = segments.pop();
+    let parent = root;
+    for (const segment of segments){
+        parent = await parent.getDirectoryHandle(segment);
+    }
+    await parent.removeEntry(name, {
+        recursive: true
+    });
+}
+async function copyDirectory(source, destination) {
+    for await (const [name, handle] of source.entries()){
+        if (handle.kind === 'directory') {
+            const childDestination = await destination.getDirectoryHandle(name, {
+                create: true
+            });
+            await copyDirectory(handle, childDestination);
+            continue;
+        }
+        const sourceFile = await handle.getFile();
+        const destinationHandle = await destination.getFileHandle(name, {
+            create: true
+        });
+        const writable = await destinationHandle.createWritable();
+        try {
+            await writable.write(sourceFile);
+            await writable.close();
+        } catch (err) {
+            await writable.abort().catch(()=>{});
+            throw err;
+        }
+    }
+}
+async function verifyDirectoryCopy(source, destination) {
+    const sourceEntries = await getSortedEntries(source);
+    const destinationEntries = await getSortedEntries(destination);
+    if (sourceEntries.length !== destinationEntries.length || sourceEntries.some(([name, handle], index)=>{
+        const destinationEntry = destinationEntries[index];
+        return name !== destinationEntry[0] || handle.kind !== destinationEntry[1].kind;
+    })) {
+        throw new Error('Failed to verify quarantined OPFS directory structure');
+    }
+    for(let i = 0; i < sourceEntries.length; i++){
+        const [, sourceHandle] = sourceEntries[i];
+        const [, destinationHandle] = destinationEntries[i];
+        if (sourceHandle.kind === 'directory') {
+            await verifyDirectoryCopy(sourceHandle, destinationHandle);
+        } else {
+            await verifyFilesEqual(sourceHandle, destinationHandle);
+        }
+    }
+}
+async function getSortedEntries(directory) {
+    const entries = [];
+    for await (const entry of directory.entries()){
+        entries.push(entry);
+    }
+    return entries.sort(([a], [b])=>a.localeCompare(b));
+}
+async function verifyFilesEqual(sourceHandle, destinationHandle) {
+    const source = await sourceHandle.getFile();
+    const destination = await destinationHandle.getFile();
+    if (source.size !== destination.size) {
+        throw new Error(`Failed to verify quarantined OPFS file "${source.name}"`);
+    }
+    const chunkSize = 1024 * 1024;
+    for(let offset = 0; offset < source.size; offset += chunkSize){
+        const [sourceChunk, destinationChunk] = await Promise.all([
+            source.slice(offset, offset + chunkSize).arrayBuffer(),
+            destination.slice(offset, offset + chunkSize).arrayBuffer()
+        ]);
+        const sourceBytes = new Uint8Array(sourceChunk);
+        const destinationBytes = new Uint8Array(destinationChunk);
+        if (sourceBytes.some((value, index)=>value !== destinationBytes[index])) {
+            throw new Error(`Failed to verify quarantined OPFS file "${source.name}"`);
+        }
+    }
+}
+async function writeJson(directory, name, value) {
+    const handle = await directory.getFileHandle(name, {
+        create: true
+    });
+    const writable = await handle.createWritable();
+    try {
+        await writable.write(JSON.stringify(value, undefined, 2));
+        await writable.close();
+    } catch (err) {
+        await writable.abort().catch(()=>{});
+        throw err;
+    }
+}
+function createQuarantineName() {
+    const random = globalThis.crypto.getRandomValues(new Uint8Array(8));
+    return `${Date.now()}-${[
+        ...random
+    ].map((byte)=>byte.toString(16).padStart(2, '0')).join('')}`;
+}

package/dest/sqlite-opfs/pool_lock.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_SAH_POOL_DIRECTORY = ".aztec-kv";
+export interface PoolLockLease {
+    release(): Promise<void>;
+}
+export declare function normalizePoolDirectory(poolDirectory?: string): string;
+export declare function acquirePoolLock(poolDirectory?: string): Promise<PoolLockLease>;
+export declare function withPoolLock<T>(poolDirectory: string, callback: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9vbF9sb2NrLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3FsaXRlLW9wZnMvcG9vbF9sb2NrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLGVBQU8sTUFBTSwwQkFBMEIsY0FBYyxDQUFDO0FBSXRELE1BQU0sV0FBVyxhQUFhO0lBQzVCLE9BQU8sSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUM7Q0FDMUI7QUFFRCx3QkFBZ0Isc0JBQXNCLENBQUMsYUFBYSxDQUFDLEVBQUUsTUFBTSxHQUFHLE1BQU0sQ0FNckU7QUFFRCx3QkFBc0IsZUFBZSxDQUFDLGFBQWEsQ0FBQyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsYUFBYSxDQUFDLENBa0NwRjtBQUVELHdCQUFzQixZQUFZLENBQUMsQ0FBQyxFQUFFLGFBQWEsRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLE1BQU0sT0FBTyxDQUFDLENBQUMsQ0FBQyxHQUFHLE9BQU8sQ0FBQyxDQUFDLENBQUMsQ0FPbkcifQ==

package/dest/sqlite-opfs/pool_lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool_lock.d.ts","sourceRoot":"","sources":["../../src/sqlite-opfs/pool_lock.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,0BAA0B,cAAc,CAAC;AAItD,MAAM,WAAW,aAAa;IAC5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAgB,sBAAsB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAMrE;AAED,wBAAsB,eAAe,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAkCpF;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOnG"}

package/dest/sqlite-opfs/pool_lock.js

@@ -0,0 +1,47 @@
+import { SqlitePoolBusyError, SqliteWebLocksUnavailableError } from './errors.js';
+export const DEFAULT_SAH_POOL_DIRECTORY = '.aztec-kv';
+const WEB_LOCK_PREFIX = 'aztec.sqlite-opfs.pool:';
+export function normalizePoolDirectory(poolDirectory) {
+    const path = poolDirectory?.split('/').filter((segment)=>segment.length > 0).join('/');
+    return path || DEFAULT_SAH_POOL_DIRECTORY;
+}
+export async function acquirePoolLock(poolDirectory) {
+    if (!navigator.locks) {
+        throw new SqliteWebLocksUnavailableError();
+    }
+    const normalizedDirectory = normalizePoolDirectory(poolDirectory);
+    const acquired = Promise.withResolvers();
+    const hold = Promise.withResolvers();
+    const request = navigator.locks.request(`${WEB_LOCK_PREFIX}${normalizedDirectory}`, {
+        mode: 'exclusive',
+        ifAvailable: true
+    }, async (lock)=>{
+        acquired.resolve(lock);
+        if (lock) {
+            await hold.promise;
+        }
+    });
+    request.catch(acquired.reject);
+    if (!await acquired.promise) {
+        await request;
+        throw new SqlitePoolBusyError(normalizedDirectory);
+    }
+    let released = false;
+    return {
+        release: async ()=>{
+            if (!released) {
+                released = true;
+                hold.resolve();
+            }
+            await request;
+        }
+    };
+}
+export async function withPoolLock(poolDirectory, callback) {
+    const lease = await acquirePoolLock(poolDirectory);
+    try {
+        return await callback();
+    } finally{
+        await lease.release();
+    }
+}

package/dest/sqlite-opfs/set.d.ts

@@ -0,0 +1,13 @@
+import type { Key, Range } from '../interfaces/common.js';
+import type { AztecAsyncSet } from '../interfaces/set.js';
+import type { AztecSQLiteOPFSStore } from './store.js';
+/** Set backed by SQLite. Composes a Map<K, true>. */
+export declare class SQLiteOPFSAztecSet<K extends Key> implements AztecAsyncSet<K> {
+    #private;
+    constructor(store: AztecSQLiteOPFSStore, name: string);
+    hasAsync(key: K): Promise<boolean>;
+    add(key: K): Promise<void>;
+    delete(key: K): Promise<void>;
+    entriesAsync(range?: Range<K>): AsyncIterableIterator<K>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0LmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3FsaXRlLW9wZnMvc2V0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLEdBQUcsRUFBRSxLQUFLLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssRUFBRSxhQUFhLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUUxRCxPQUFPLEtBQUssRUFBRSxvQkFBb0IsRUFBRSxNQUFNLFlBQVksQ0FBQztBQUV2RCxxREFBcUQ7QUFDckQscUJBQWEsa0JBQWtCLENBQUMsQ0FBQyxTQUFTLEdBQUcsQ0FBRSxZQUFXLGFBQWEsQ0FBQyxDQUFDLENBQUM7O0lBR3hFLFlBQVksS0FBSyxFQUFFLG9CQUFvQixFQUFFLElBQUksRUFBRSxNQUFNLEVBRXBEO0lBRUQsUUFBUSxDQUFDLEdBQUcsRUFBRSxDQUFDLEdBQUcsT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQUVqQztJQUVELEdBQUcsQ0FBQyxHQUFHLEVBQUUsQ0FBQyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFekI7SUFFRCxNQUFNLENBQUMsR0FBRyxFQUFFLENBQUMsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBRTVCO0lBRU0sWUFBWSxDQUFDLEtBQUssR0FBRSxLQUFLLENBQUMsQ0FBQyxDQUFNLEdBQUcscUJBQXFCLENBQUMsQ0FBQyxDQUFDLENBRWxFO0NBQ0YifQ==

package/dest/sqlite-opfs/set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["../../src/sqlite-opfs/set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,qDAAqD;AACrD,qBAAa,kBAAkB,CAAC,CAAC,SAAS,GAAG,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;;IAGxE,YAAY,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,EAEpD;IAED,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAEjC;IAED,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzB;IAED,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5B;IAEM,YAAY,CAAC,KAAK,GAAE,KAAK,CAAC,CAAC,CAAM,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAElE;CACF"}

package/dest/sqlite-opfs/set.js

@@ -0,0 +1,19 @@
+import { SQLiteOPFSAztecMap } from './map.js';
+/** Set backed by SQLite. Composes a Map<K, true>. */ export class SQLiteOPFSAztecSet {
+    #map;
+    constructor(store, name){
+        this.#map = new SQLiteOPFSAztecMap(store, name);
+    }
+    hasAsync(key) {
+        return this.#map.hasAsync(key);
+    }
+    add(key) {
+        return this.#map.set(key, true);
+    }
+    delete(key) {
+        return this.#map.delete(key);
+    }
+    async *entriesAsync(range = {}) {
+        yield* this.#map.keysAsync(range);
+    }
+}

package/dest/sqlite-opfs/singleton.d.ts

@@ -0,0 +1,13 @@
+import type { Value } from '../interfaces/common.js';
+import type { AztecAsyncSingleton } from '../interfaces/singleton.js';
+import type { AztecSQLiteOPFSStore } from './store.js';
+/** Stores a single value identified by `name`. */
+export declare class SQLiteOPFSAztecSingleton<T extends Value> implements AztecAsyncSingleton<T> {
+    #private;
+    private readonly store;
+    constructor(store: AztecSQLiteOPFSStore, name: string);
+    getAsync(): Promise<T | undefined>;
+    set(val: T): Promise<boolean>;
+    delete(): Promise<boolean>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2luZ2xldG9uLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3FsaXRlLW9wZnMvc2luZ2xldG9uLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUlBLE9BQU8sS0FBSyxFQUFFLEtBQUssRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFDdEUsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFFdkQsa0RBQWtEO0FBQ2xELHFCQUFhLHdCQUF3QixDQUFDLENBQUMsU0FBUyxLQUFLLENBQUUsWUFBVyxtQkFBbUIsQ0FBQyxDQUFDLENBQUM7O0lBTXBGLE9BQU8sQ0FBQyxRQUFRLENBQUMsS0FBSztJQUR4QixZQUNtQixLQUFLLEVBQUUsb0JBQW9CLEVBQzVDLElBQUksRUFBRSxNQUFNLEVBSWI7SUFFSyxRQUFRLElBQUksT0FBTyxDQUFDLENBQUMsR0FBRyxTQUFTLENBQUMsQ0FVdkM7SUFFSyxHQUFHLENBQUMsR0FBRyxFQUFFLENBQUMsR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLENBT2xDO0lBRUssTUFBTSxJQUFJLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FHL0I7Q0FDRiJ9

package/dest/sqlite-opfs/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../../src/sqlite-opfs/singleton.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,kDAAkD;AAClD,qBAAa,wBAAwB,CAAC,CAAC,SAAS,KAAK,CAAE,YAAW,mBAAmB,CAAC,CAAC,CAAC;;IAMpF,OAAO,CAAC,QAAQ,CAAC,KAAK;IADxB,YACmB,KAAK,EAAE,oBAAoB,EAC5C,IAAI,EAAE,MAAM,EAIb;IAEK,QAAQ,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAUvC;IAEK,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAOlC;IAEK,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAG/B;CACF"}

package/dest/sqlite-opfs/singleton.js

@@ -0,0 +1,48 @@
+import { Encoder } from '#msgpackr';
+import { toBufferKey } from '#ordered-binary';
+import { hash } from 'ohash';
+/** Stores a single value identified by `name`. */ export class SQLiteOPFSAztecSingleton {
+    store;
+    #container;
+    #slot;
+    #encoder;
+    constructor(store, name){
+        this.store = store;
+        this.#encoder = new Encoder();
+        this.#container = `singleton:${name}`;
+        this.#slot = `singleton:${name}:value`;
+    }
+    async getAsync() {
+        const rows = await this.store.allAsync('SELECT value FROM data WHERE slot = ? LIMIT 1', [
+            this.#slot
+        ]);
+        if (rows.length === 0) {
+            return undefined;
+        }
+        const raw = rows[0][0];
+        if (raw instanceof Uint8Array) {
+            return this.#encoder.unpack(raw);
+        }
+        return undefined;
+    }
+    async set(val) {
+        const { changes } = await this.store.runAsync(`INSERT OR REPLACE INTO data (slot, container, key, key_count, hash, value)
+       VALUES (?, ?, ?, ?, ?, ?)`, [
+            this.#slot,
+            this.#container,
+            toBufferKey([
+                this.#slot
+            ]),
+            1,
+            hash(val),
+            this.#encoder.pack(val)
+        ]);
+        return changes > 0;
+    }
+    async delete() {
+        await this.store.runAsync('DELETE FROM data WHERE slot = ?', [
+            this.#slot
+        ]);
+        return true;
+    }
+}

package/dest/sqlite-opfs/store.d.ts

@@ -0,0 +1,84 @@
+import type { Logger } from '@aztec/foundation/log';
+import type { AztecAsyncArray } from '../interfaces/array.js';
+import type { Key, StoreSize, Value } from '../interfaces/common.js';
+import type { AztecAsyncCounter } from '../interfaces/counter.js';
+import type { AztecAsyncMap } from '../interfaces/map.js';
+import type { AztecAsyncMultiMap } from '../interfaces/multi_map.js';
+import type { AztecAsyncSet } from '../interfaces/set.js';
+import type { AztecAsyncSingleton } from '../interfaces/singleton.js';
+import type { AztecAsyncKVStore } from '../interfaces/store.js';
+import type { ResultRow, SqlValue } from './messages.js';
+/**
+ * Main-thread handle for a SQLite database persisted to OPFS via the `opfs-sahpool`
+ * VFS. Owns a dedicated Web Worker (the SAH Pool VFS requires Worker context) and
+ * routes every SQL op through it via typed postMessage RPC.
+ *
+ * Transaction ordering is guaranteed by a `SerialQueue` on the main thread combined
+ * with an `#inTx` flag: outside a `transactionAsync` block, each op acquires the
+ * queue for its own auto-commit; inside a block, the outer call holds the queue and
+ * nested ops bypass it to avoid deadlock.
+ */
+export declare class AztecSQLiteOPFSStore implements AztecAsyncKVStore {
+    #private;
+    readonly isEphemeral: boolean;
+    private readonly poolLock?;
+    private constructor();
+    /**
+     * Opens (or creates) a SQLite database stored in the OPFS SAH Pool. When `ephemeral`
+     * is true the database lives only in memory and is lost when the worker terminates.
+     * Pass `poolDirectory` to place the SAH Pool in a non-default OPFS subdirectory —
+     * 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:
+     * the API encodes a one-key-one-owner invariant. A caller that wants to use the same
+     * key for multiple stores must explicitly clone it per call (e.g.
+     * `new Uint8Array(savedKey)`), making the duplication a visible, deliberate decision
+     * rather than a silent structured-clone operation. The default path (one `.open()`,
+     * one consumption of the key) leaves zero key bytes on the main thread after the call.
+     */
+    static open(log: Logger, name?: string, ephemeral?: boolean, poolDirectory?: string, encryptionKey?: Uint8Array): Promise<AztecSQLiteOPFSStore>;
+    openMap<K extends Key, V extends Value>(name: string): AztecAsyncMap<K, V>;
+    openSet<K extends Key>(name: string): AztecAsyncSet<K>;
+    openMultiMap<K extends Key, V extends Value>(name: string): AztecAsyncMultiMap<K, V>;
+    openCounter<K extends Key>(_name: string): AztecAsyncCounter<K>;
+    openArray<T extends Value>(name: string): AztecAsyncArray<T>;
+    openSingleton<T extends Value>(name: string): AztecAsyncSingleton<T>;
+    transactionAsync<T>(callback: () => Promise<T>): Promise<T>;
+    clear(): Promise<void>;
+    delete(): Promise<void>;
+    /**
+     * Placeholder — returns zeros to mirror the IndexedDB backend. SQLite exposes real
+     * numbers cheaply via `PRAGMA page_count` / `page_size` / `freelist_count` and
+     * `SELECT COUNT(*) FROM data`, which would populate `physicalFileSize`, `actualSize`,
+     * and `numItems` meaningfully (`mappingSize` stays 0 — it's an LMDB mmap concept).
+     * Upgrade when any caller actually consumes these values; all current consumers
+     * tolerate zeros.
+     */
+    estimateSize(): Promise<StoreSize>;
+    close(): Promise<void>;
+    backupTo(_dstPath: string, _compact?: boolean): Promise<void>;
+    /**
+     * Returns a raw SQLite image (bytes suitable for writing as a `.sqlite` file and
+     * opening in any SQLite tool). Works only for non-ephemeral DBs because the OPFS
+     * SAH Pool has to be initialized. Useful for inspection/debugging.
+     */
+    exportDb(): Promise<Uint8Array>;
+    /**
+     * Runs a write statement (INSERT/UPDATE/DELETE/DDL). If called inside a
+     * `transactionAsync` block, bypasses the queue; otherwise acquires it so the
+     * op runs in its own auto-commit.
+     */
+    runAsync(sql: string, bind?: SqlValue[]): Promise<{
+        changes: number;
+    }>;
+    /** Runs a SELECT statement and returns rows in array row-mode. */
+    allAsync(sql: string, bind?: SqlValue[]): Promise<ResultRow[]>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmUuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9zcWxpdGUtb3Bmcy9zdG9yZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUdwRCxPQUFPLEtBQUssRUFBRSxlQUFlLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUM5RCxPQUFPLEtBQUssRUFBRSxHQUFHLEVBQUUsU0FBUyxFQUFFLEtBQUssRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ3JFLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDbEUsT0FBTyxLQUFLLEVBQUUsYUFBYSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDMUQsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUNyRSxPQUFPLEtBQUssRUFBRSxhQUFhLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUMxRCxPQUFPLEtBQUssRUFBRSxtQkFBbUIsRUFBRSxNQUFNLDRCQUE0QixDQUFDO0FBQ3RFLE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFJaEUsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLFFBQVEsRUFBaUMsTUFBTSxlQUFlLENBQUM7QUFPeEY7Ozs7Ozs7OztHQVNHO0FBQ0gscUJBQWEsb0JBQXFCLFlBQVcsaUJBQWlCOzthQWUxQyxXQUFXLEVBQUUsT0FBTztJQUNwQyxPQUFPLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQztJQUw1QixPQUFPLGVBMEJOO0lBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7T0FtQkc7SUFDSCxPQUFhLElBQUksQ0FDZixHQUFHLEVBQUUsTUFBTSxFQUNYLElBQUksQ0FBQyxFQUFFLE1BQU0sRUFDYixTQUFTLEdBQUUsT0FBZSxFQUMxQixhQUFhLENBQUMsRUFBRSxNQUFNLEVBQ3RCLGFBQWEsQ0FBQyxFQUFFLFVBQVUsR0FDekIsT0FBTyxDQUFDLG9CQUFvQixDQUFDLENBMkMvQjtJQUVELE9BQU8sQ0FBQyxDQUFDLFNBQVMsR0FBRyxFQUFFLENBQUMsU0FBUyxLQUFLLEVBQUUsSUFBSSxFQUFFLE1BQU0sR0FBRyxhQUFhLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUV6RTtJQUVELE9BQU8sQ0FBQyxDQUFDLFNBQVMsR0FBRyxFQUFFLElBQUksRUFBRSxNQUFNLEdBQUcsYUFBYSxDQUFDLENBQUMsQ0FBQyxDQUVyRDtJQUVELFlBQVksQ0FBQyxDQUFDLFNBQVMsR0FBRyxFQUFFLENBQUMsU0FBUyxLQUFLLEVBQUUsSUFBSSxFQUFFLE1BQU0sR0FBRyxrQkFBa0IsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBRW5GO0lBRUQsV0FBVyxDQUFDLENBQUMsU0FBUyxHQUFHLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxpQkFBaUIsQ0FBQyxDQUFDLENBQUMsQ0FFOUQ7SUFFRCxTQUFTLENBQUMsQ0FBQyxTQUFTLEtBQUssRUFBRSxJQUFJLEVBQUUsTUFBTSxHQUFHLGVBQWUsQ0FBQyxDQUFDLENBQUMsQ0FFM0Q7SUFFRCxhQUFhLENBQUMsQ0FBQyxTQUFTLEtBQUssRUFBRSxJQUFJLEVBQUUsTUFBTSxHQUFHLG1CQUFtQixDQUFDLENBQUMsQ0FBQyxDQUVuRTtJQUVELGdCQUFnQixDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsTUFBTSxPQUFPLENBQUMsQ0FBQyxDQUFDLEdBQUcsT0FBTyxDQUFDLENBQUMsQ0FBQyxDQXdCMUQ7SUFFSyxLQUFLLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUUzQjtJQUVLLE1BQU0sSUFBSSxPQUFPLENBQUMsSUFBSSxDQUFDLENBZTVCO0lBRUQ7Ozs7Ozs7T0FPRztJQUNILFlBQVksSUFBSSxPQUFPLENBQUMsU0FBUyxDQUFDLENBRWpDO0lBRUssS0FBSyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FhM0I7SUFFRCxRQUFRLENBQUMsUUFBUSxFQUFFLE1BQU0sRUFBRSxRQUFRLENBQUMsRUFBRSxPQUFPLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUU1RDtJQUVEOzs7O09BSUc7SUFDRyxRQUFRLElBQUksT0FBTyxDQUFDLFVBQVUsQ0FBQyxDQU1wQztJQUVEOzs7O09BSUc7SUFDSCxRQUFRLENBQUMsR0FBRyxFQUFFLE1BQU0sRUFBRSxJQUFJLENBQUMsRUFBRSxRQUFRLEVBQUUsR0FBRyxPQUFPLENBQUM7UUFBRSxPQUFPLEVBQUUsTUFBTSxDQUFBO0tBQUUsQ0FBQyxDQU1yRTtJQUVELGtFQUFrRTtJQUNsRSxRQUFRLENBQUMsR0FBRyxFQUFFLE1BQU0sRUFBRSxJQUFJLENBQUMsRUFBRSxRQUFRLEVBQUUsR0FBRyxPQUFPLENBQUMsU0FBUyxFQUFFLENBQUMsQ0FJN0Q7Q0F1REYifQ==

package/dest/sqlite-opfs/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sqlite-opfs/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAIhE,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAiC,MAAM,eAAe,CAAC;AAOxF;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;;aAe1C,WAAW,EAAE,OAAO;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAL5B,OAAO,eA0BN;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAa,IAAI,CACf,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,GAAE,OAAe,EAC1B,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,UAAU,GACzB,OAAO,CAAC,oBAAoB,CAAC,CA2C/B;IAED,OAAO,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAEzE;IAED,OAAO,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAErD;IAED,YAAY,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAEnF;IAED,WAAW,CAAC,CAAC,SAAS,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAE9D;IAED,SAAS,CAAC,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,CAE3D;IAED,aAAa,CAAC,CAAC,SAAS,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAEnE;IAED,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAwB1D;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAEK,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAe5B;IAED;;;;;;;OAOG;IACH,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC,CAEjC;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAa3B;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;IAED;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAMpC;IAED;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAMrE;IAED,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAI7D;CAuDF"}