chore: better encrypted sqlite ergonomics (#23231)

Adds some structure to typical decryption errors, and a couple of
convenience helpers for orchestrating encrypted store management from
embedded wallet, so that the most basic usage is straightforward and
downstream projects don't need to rewrite the same lines over and over.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 2 people

playground/vite.config.ts

@@ -45,7 +45,12 @@ const chunkSizeValidator = (limits: ChunkSizeLimit[]): Plugin => {
     configResolved(resolvedConfig) {
       config = resolvedConfig;
     },
-    closeBundle() {
+    // `writeBundle` is documented to fire AFTER the output bundle has been
+    // written to disk, whereas `closeBundle` (which we used previously) is the
+    // last hook to run and can fire before any chunks have been flushed in
+    // current vite/rollup versions — manifesting as ENOENT on `scandir 'dist'`
+    // for a build that otherwise transformed all modules cleanly.
+    writeBundle() {
       const outDir = this.meta?.watchMode ? null : 'dist';
       if (!outDir) return; // Skip in watch mode
 

yarn-project/kv-store/src/sqlite-opfs/encrypted_store.test.ts

@@ -6,6 +6,7 @@
 import { describe, expect, it } from 'vitest';
 
 import { mockLogger } from '../interfaces/utils.js';
+import { SqliteEncryptionError } from './errors.js';
 import { AztecSQLiteOPFSStore } from './store.js';
 
 function randomKey(): Uint8Array {
@@ -24,16 +25,16 @@ function cloneKey(k: Uint8Array): Uint8Array {
 describe('AztecSQLiteOPFSStore with encryption', () => {
   it('rejects keys that are not 32 bytes', async () => {
     const short = new Uint8Array(16);
-    await expect(AztecSQLiteOPFSStore.open(mockLogger, undefined, true, undefined, short)).rejects.toThrow(
-      /encryptionKey must be 32 bytes/,
-    );
+    const promise = AztecSQLiteOPFSStore.open(mockLogger, undefined, true, undefined, short);
+    await expect(promise).rejects.toThrow(SqliteEncryptionError);
+    await expect(promise).rejects.toMatchObject({ code: 'invalid_key_length' });
   });
 
   it('rejects encryption on ephemeral (:memory:) stores', async () => {
     const key = randomKey();
-    await expect(AztecSQLiteOPFSStore.open(mockLogger, undefined, true, undefined, key)).rejects.toThrow(
-      /not supported for ephemeral/,
-    );
+    const promise = AztecSQLiteOPFSStore.open(mockLogger, undefined, true, undefined, key);
+    await expect(promise).rejects.toThrow(SqliteEncryptionError);
+    await expect(promise).rejects.toMatchObject({ code: 'encryption_not_supported_for_ephemeral' });
   });
 
   it('round-trips values with the same key (persistent)', async () => {
@@ -51,37 +52,43 @@ describe('AztecSQLiteOPFSStore with encryption', () => {
     await b.delete();
   });
 
-  it('fails to open with the wrong key', async () => {
+  it('fails to open with the wrong key (throws SqliteEncryptionError, code=decrypt_failed)', async () => {
     const key = randomKey();
     const name = `test-wrong-${Date.now()}`;
     const dir = `/test-wrong-pool-${Date.now()}`;
     const a = await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir, cloneKey(key));
     await a.openMap<string, string>('m').set('k1', 'v1');
     await a.close();
 
-    await expect(async () => {
-      const b = await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir, randomKey());
-      await b.openMap<string, string>('m').getAsync('k1');
-      await b.close();
-    }).rejects.toThrow();
+    let caught: unknown;
+    try {
+      await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir, randomKey());
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(SqliteEncryptionError);
+    expect((caught as SqliteEncryptionError).code).toBe('decrypt_failed');
 
     const c = await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir, cloneKey(key));
     await c.delete();
   });
 
-  it('fails to open an encrypted DB without a key', async () => {
+  it('fails to open an encrypted DB without a key (throws SqliteEncryptionError, code=decrypt_failed)', async () => {
     const key = randomKey();
     const name = `test-nokey-${Date.now()}`;
     const dir = `/test-nokey-pool-${Date.now()}`;
     const a = await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir, cloneKey(key));
     await a.openMap<string, string>('m').set('k1', 'v1');
     await a.close();
 
-    await expect(async () => {
-      const b = await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir);
-      await b.openMap<string, string>('m').getAsync('k1');
-      await b.close();
-    }).rejects.toThrow();
+    let caught: unknown;
+    try {
+      await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(SqliteEncryptionError);
+    expect((caught as SqliteEncryptionError).code).toBe('decrypt_failed');
 
     const c = await AztecSQLiteOPFSStore.open(mockLogger, name, false, dir, cloneKey(key));
     await c.delete();

yarn-project/kv-store/src/sqlite-opfs/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Typed error surface for sqlite3mc-backed page-level encryption failures.
+ *
+ * Three concrete failure modes are surfaced:
+ *
+ *   - `invalid_key_length`: caller-side pre-flight (key not 32 bytes).
+ *   - `encryption_not_supported_for_ephemeral`: caller-side pre-flight (encryption was requested on an ephemeral
+ *     `:memory:` store, which sqlite3mc does not support).
+ *   - `decrypt_failed`: runtime failure raised when sqlite3mc cannot decode page 1 of an existing database. Covers
+ *     both "wrong key supplied" and "no key supplied to an encrypted DB".
+ */
+export type SqliteEncryptionErrorCode =
+  | 'invalid_key_length'
+  | 'encryption_not_supported_for_ephemeral'
+  | 'decrypt_failed';
+
+/**
+ * Error thrown by sqlite-opfs when an encryption operation fails.
+ **/
+export class SqliteEncryptionError extends Error {
+  readonly code: SqliteEncryptionErrorCode;
+
+  constructor(code: SqliteEncryptionErrorCode, message: string, opts?: { cause?: unknown }) {
+    super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+    this.name = 'SqliteEncryptionError';
+    this.code = code;
+  }
+}
+
+/**
+ * Strings raised by sqlite3mc when page 1 cannot be decoded.
+ **/
+const SQLITE3MC_DECRYPT_ERROR_PATTERNS: readonly RegExp[] = [
+  /file is not a database/i,
+  /file is encrypted or is not a database/i,
+];
+
+/**
+ * Returns `true` if `message` matches one of the known sqlite3mc decrypt-failure
+ * strings.
+ **/
+export function isDecryptFailureMessage(message: string): boolean {
+  return SQLITE3MC_DECRYPT_ERROR_PATTERNS.some(p => p.test(message));
+}

yarn-project/kv-store/src/sqlite-opfs/index.ts

@@ -5,6 +5,8 @@ import { initStoreForRollupAndSchemaVersion } from '../utils.js';
 import { AztecSQLiteOPFSStore } from './store.js';
 
 export { AztecSQLiteOPFSStore } from './store.js';
+export { SqliteEncryptionError } from './errors.js';
+export type { SqliteEncryptionErrorCode } from './errors.js';
 
 export async function createStore(
   name: string,

yarn-project/kv-store/src/sqlite-opfs/messages.ts

@@ -3,6 +3,7 @@
  * All requests carry a unique `id`; responses echo the same id so the main thread
  * can resolve the right pending promise.
  */
+import type { SqliteEncryptionErrorCode } from './errors.js';
 
 /** Matches `@sqlite.org/sqlite-wasm`'s internal SqlValue type. Boolean is not a native SQLite type. */
 export type SqlValue = string | number | bigint | null | Uint8Array;
@@ -23,6 +24,16 @@ export type WorkerRequest =
 
 export type WorkerResponse =
   | { type: 'ok'; id: number; rows?: ResultRow[]; changes?: number; bytes?: Uint8Array }
-  | { type: 'err'; id: number; message: string };
+  | {
+      type: 'err';
+      id: number;
+      message: string;
+      /**
+       * Set when the worker detected an encryption-shaped failure. The main thread
+       * uses this to re-throw the error as a {@link SqliteEncryptionError} with the
+       * matching code. Absent on non-encryption failures (untyped paths preserved).
+       */
+      encryptionCode?: SqliteEncryptionErrorCode;
+    };
 
 export type WorkerRequestType = WorkerRequest['type'];

yarn-project/kv-store/src/sqlite-opfs/store.ts

@@ -10,6 +10,7 @@ import type { AztecAsyncSet } from '../interfaces/set.js';
 import type { AztecAsyncSingleton } from '../interfaces/singleton.js';
 import type { AztecAsyncKVStore } from '../interfaces/store.js';
 import { SQLiteOPFSAztecArray } from './array.js';
+import { SqliteEncryptionError } from './errors.js';
 import { SQLiteOPFSAztecMap } from './map.js';
 import type { ResultRow, SqlValue, WorkerRequest, WorkerResponse } from './messages.js';
 import { SQLiteOPFSAztecMultiMap } from './multi_map.js';
@@ -86,10 +87,16 @@ export class AztecSQLiteOPFSStore implements AztecAsyncKVStore {
     encryptionKey?: Uint8Array,
   ): Promise<AztecSQLiteOPFSStore> {
     if (encryptionKey !== undefined && encryptionKey.length !== 32) {
-      throw new Error(`encryptionKey must be 32 bytes (got ${encryptionKey.length})`);
+      throw new SqliteEncryptionError(
+        'invalid_key_length',
+        `encryptionKey must be 32 bytes (got ${encryptionKey.length})`,
+      );
     }
     if (encryptionKey !== undefined && ephemeral) {
-      throw new Error('encryptionKey is not supported for ephemeral (:memory:) stores');
+      throw new SqliteEncryptionError(
+        'encryption_not_supported_for_ephemeral',
+        'encryptionKey is not supported for ephemeral (:memory:) stores',
+      );
     }
     const dbName = name && !ephemeral ? name : `tmp-${globalThis.crypto.getRandomValues(new Uint8Array(8)).join('')}`;
     log.debug(
@@ -265,7 +272,14 @@ export class AztecSQLiteOPFSStore implements AztecAsyncKVStore {
       this.#pending.set(req.id, {
         resolve: resp => {
           if (resp.type === 'err') {
-            reject(new Error(resp.message));
+            // 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.
+            if (resp.encryptionCode !== undefined) {
+              reject(new SqliteEncryptionError(resp.encryptionCode, resp.message));
+            } else {
+              reject(new Error(resp.message));
+            }
           } else {
             resolve(resp);
           }

yarn-project/kv-store/src/sqlite-opfs/worker.ts

@@ -1,6 +1,7 @@
 /// <reference lib="webworker" />
 import sqlite3InitModule, { type Database, type SAHPoolUtil, type Sqlite3Static } from '@aztec/sqlite3mc-wasm';
 
+import { SqliteEncryptionError, type SqliteEncryptionErrorCode, isDecryptFailureMessage } from './errors.js';
 import type { ResultRow, SqlValue, WorkerRequest, WorkerResponse } from './messages.js';
 
 const SCHEMA_SQL = `
@@ -72,7 +73,10 @@ async function handleInit(
   sqlite3 ??= await sqlite3InitModule();
   const s = sqlite3;
   if (encryptionKey !== undefined && ephemeral) {
-    throw new Error('encryptionKey is not supported for ephemeral (:memory:) stores');
+    throw new SqliteEncryptionError(
+      'encryption_not_supported_for_ephemeral',
+      'encryptionKey is not supported for ephemeral (:memory:) stores',
+    );
   }
   if (ephemeral) {
     db = new s.oo1.DB(':memory:', 'c');
@@ -189,6 +193,34 @@ function respond(msg: WorkerResponse): void {
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    respond({ type: 'err', id: req.id, message });
+    respond({ type: 'err', id: req.id, message, encryptionCode: detectEncryptionCode(req, err, message) });
   }
 };
+
+/**
+ * Maps a thrown error during request handling to a typed encryption code, so the
+ * main thread can re-hydrate it as a {@link SqliteEncryptionError}. Returns
+ * `undefined` for non-encryption errors (preserves the existing untyped path).
+ *
+ * Two sources:
+ *   - The error was already a `SqliteEncryptionError` (pre-flight throws inside
+ *     this worker — e.g. ephemeral + encryptionKey). Forward its code as-is.
+ *   - The error came from SQLite/sqlite3mc with a known decrypt-failure message
+ *     during an `init` request. Both "wrong key supplied" and "no key supplied
+ *     to an encrypted DB" surface as SQLITE_NOTADB ("file is not a database") —
+ *     we don't constrain on `req.encryptionKey` because the no-key-on-encrypted-DB
+ *     case is exactly when the caller most needs the typed signal.
+ */
+function detectEncryptionCode(
+  req: WorkerRequest,
+  err: unknown,
+  message: string,
+): SqliteEncryptionErrorCode | undefined {
+  if (err instanceof SqliteEncryptionError) {
+    return err.code;
+  }
+  if (req.type === 'init' && isDecryptFailureMessage(message)) {
+    return 'decrypt_failed';
+  }
+  return undefined;
+}

yarn-project/wallets/package.json

@@ -14,6 +14,7 @@
         "default": "./dest/embedded/entrypoints/node.js"
       }
     },
+    "./embedded/store-encryption": "./dest/embedded/store_encryption.js",
     "./testing": "./dest/testing.js"
   },
   "scripts": {

yarn-project/wallets/src/embedded/entrypoints/browser.ts

@@ -77,3 +77,10 @@ export { BrowserEmbeddedWallet as EmbeddedWallet };
 export type { EmbeddedWalletOptions, EmbeddedWalletPXEOptions } from '../embedded_wallet.js';
 export { WalletDB } from '../wallet_db.js';
 export type { AccountType } from '../wallet_db.js';
+
+// At-rest encryption helpers are intentionally NOT re-exported here. They live
+// on the `@aztec/wallets/embedded/store-encryption` sub-path so consumers
+// (and bundlers) of this entrypoint don't transitively pull in
+// `@aztec/kv-store/sqlite-opfs` and its `new Worker(new URL('./worker.js'))`
+// chain into `@aztec/sqlite3mc-wasm`. Apps that don't use encryption-at-rest
+// (e.g. the playground) should never see sqlite-opfs in their bundle.