@aztec/wallets 4.3.0-nightly.20260513 → 4.3.0-nightly.20260514

package/dest/embedded/entrypoints/browser.js

@@ -50,3 +50,9 @@ export class BrowserEmbeddedWallet extends EmbeddedWallet {
 }
 export { BrowserEmbeddedWallet as EmbeddedWallet };
 export { WalletDB } 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.

package/dest/embedded/store_encryption.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Wallet-layer helpers for opening the embedded wallet's two encrypted stores (PXE + walletDB) as a cohesive unit.
+ *
+ * Sits on top of `@aztec/kv-store/sqlite-opfs`'s typed `SqliteEncryptionError` and adds:
+ *
+ *   - `storeName: 'pxe' | 'wallet'`, telling callers WHICH store failed.
+ *   - Cleanup: when the wallet store fails to open, ensures the already-opened PXE store is closed before the error
+ *     surfaces, so callers don't leak the SAH Pool's OPFS lock.
+ */
+import type { Logger } from '@aztec/foundation/log';
+import { AztecSQLiteOPFSStore, SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
+/** Which of the embedded wallet's two stores failed to open. */
+export type EmbeddedStoreName = 'pxe' | 'wallet';
+/**
+ * Thrown by {@link openEncryptedEmbeddedStores} when one of the two stores cannot be decrypted with the supplied
+ * key. The original {@link SqliteEncryptionError} is preserved as `cause`.
+ */
+export declare class EmbeddedWalletEncryptionError extends Error {
+    readonly storeName: EmbeddedStoreName;
+    constructor(storeName: EmbeddedStoreName, opts: {
+        cause: SqliteEncryptionError;
+    });
+}
+/** Configuration for {@link openEncryptedEmbeddedStores}. */
+export interface OpenEncryptedEmbeddedStoresOptions {
+    pxe: {
+        name: string;
+        poolDirectory?: string;
+    };
+    wallet: {
+        name: string;
+        poolDirectory?: string;
+    };
+}
+/**
+ * Internal seam for tests to inject a fake store opener. Defaults to `AztecSQLiteOPFSStore.open`. Not part of the
+ * public API.
+ *
+ * @internal
+ */
+export type OpenSqliteEncryptedStoreFn = (log: Logger, name: string, poolDirectory: string | undefined, encryptionKey: Uint8Array) => Promise<AztecSQLiteOPFSStore>;
+/**
+ * Opens the PXE and wallet stores in sequence, both encrypted with keys obtained from `getEncryptionKey`.
+ *
+ * The callback is invoked once per store (twice total per call) because `AztecSQLiteOPFSStore.open` *transfers*
+ * the key buffer to its worker. A single buffer would detach between the two opens.
+ *
+ * Failure modes:
+ *
+ *   - PXE store fails to decrypt → throws `EmbeddedWalletEncryptionError({ storeName: 'pxe', cause })`. No cleanup
+ *     needed (nothing was opened).
+ *   - Wallet store fails to decrypt → closes the already-opened PXE store then throws
+ *     `EmbeddedWalletEncryptionError({ storeName: 'wallet', cause })`.
+ *   - Any non-decrypt error during the wallet open → still closes PXE, then re-throws the original error unwrapped
+ *     (preserves callers' existing untyped error handling for non-encryption faults).
+ *
+ * @param config           - Per-store name/poolDirectory.
+ * @param getEncryptionKey - Returns a fresh 32-byte key per call (the buffer
+ *                           detaches on transfer, so each call must allocate).
+ * @param log              - Logger for both stores.
+ * @param openStore        - Internal test seam. Do not pass in production code.
+ */
+export declare function openEncryptedEmbeddedStores(config: OpenEncryptedEmbeddedStoresOptions, getEncryptionKey: () => Promise<Uint8Array>, log: Logger, openStore?: OpenSqliteEncryptedStoreFn): Promise<{
+    pxeStore: AztecSQLiteOPFSStore;
+    walletStore: AztecSQLiteOPFSStore;
+}>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmVfZW5jcnlwdGlvbi5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2VtYmVkZGVkL3N0b3JlX2VuY3J5cHRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7O0dBUUc7QUFDSCxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUNwRCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUscUJBQXFCLEVBQUUsTUFBTSw2QkFBNkIsQ0FBQztBQUUxRixnRUFBZ0U7QUFDaEUsTUFBTSxNQUFNLGlCQUFpQixHQUFHLEtBQUssR0FBRyxRQUFRLENBQUM7QUFFakQ7OztHQUdHO0FBQ0gscUJBQWEsNkJBQThCLFNBQVEsS0FBSztJQUN0RCxRQUFRLENBQUMsU0FBUyxFQUFFLGlCQUFpQixDQUFDO0lBRXRDLFlBQVksU0FBUyxFQUFFLGlCQUFpQixFQUFFLElBQUksRUFBRTtRQUFFLEtBQUssRUFBRSxxQkFBcUIsQ0FBQTtLQUFFLEVBSS9FO0NBQ0Y7QUFFRCw2REFBNkQ7QUFDN0QsTUFBTSxXQUFXLGtDQUFrQztJQUNqRCxHQUFHLEVBQUU7UUFBRSxJQUFJLEVBQUUsTUFBTSxDQUFDO1FBQUMsYUFBYSxDQUFDLEVBQUUsTUFBTSxDQUFBO0tBQUUsQ0FBQztJQUM5QyxNQUFNLEVBQUU7UUFBRSxJQUFJLEVBQUUsTUFBTSxDQUFDO1FBQUMsYUFBYSxDQUFDLEVBQUUsTUFBTSxDQUFBO0tBQUUsQ0FBQztDQUNsRDtBQUVEOzs7OztHQUtHO0FBQ0gsTUFBTSxNQUFNLDBCQUEwQixHQUFHLENBQ3ZDLEdBQUcsRUFBRSxNQUFNLEVBQ1gsSUFBSSxFQUFFLE1BQU0sRUFDWixhQUFhLEVBQUUsTUFBTSxHQUFHLFNBQVMsRUFDakMsYUFBYSxFQUFFLFVBQVUsS0FDdEIsT0FBTyxDQUFDLG9CQUFvQixDQUFDLENBQUM7QUFLbkM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBb0JHO0FBQ0gsd0JBQXNCLDJCQUEyQixDQUMvQyxNQUFNLEVBQUUsa0NBQWtDLEVBQzFDLGdCQUFnQixFQUFFLE1BQU0sT0FBTyxDQUFDLFVBQVUsQ0FBQyxFQUMzQyxHQUFHLEVBQUUsTUFBTSxFQUNYLFNBQVMsR0FBRSwwQkFBNkMsR0FDdkQsT0FBTyxDQUFDO0lBQUUsUUFBUSxFQUFFLG9CQUFvQixDQUFDO0lBQUMsV0FBVyxFQUFFLG9CQUFvQixDQUFBO0NBQUUsQ0FBQyxDQVdoRiJ9

package/dest/embedded/store_encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store_encryption.d.ts","sourceRoot":"","sources":["../../src/embedded/store_encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAE1F,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEjD;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC,YAAY,SAAS,EAAE,iBAAiB,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,qBAAqB,CAAA;KAAE,EAI/E;CACF;AAED,6DAA6D;AAC7D,MAAM,WAAW,kCAAkC;IACjD,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,aAAa,EAAE,UAAU,KACtB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAKnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,kCAAkC,EAC1C,gBAAgB,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,EAC3C,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,0BAA6C,GACvD,OAAO,CAAC;IAAE,QAAQ,EAAE,oBAAoB,CAAC;IAAC,WAAW,EAAE,oBAAoB,CAAA;CAAE,CAAC,CAWhF"}

package/dest/embedded/store_encryption.js

@@ -0,0 +1,71 @@
+/**
+ * Wallet-layer helpers for opening the embedded wallet's two encrypted stores (PXE + walletDB) as a cohesive unit.
+ *
+ * Sits on top of `@aztec/kv-store/sqlite-opfs`'s typed `SqliteEncryptionError` and adds:
+ *
+ *   - `storeName: 'pxe' | 'wallet'`, telling callers WHICH store failed.
+ *   - Cleanup: when the wallet store fails to open, ensures the already-opened PXE store is closed before the error
+ *     surfaces, so callers don't leak the SAH Pool's OPFS lock.
+ */ import { AztecSQLiteOPFSStore, SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
+/**
+ * Thrown by {@link openEncryptedEmbeddedStores} when one of the two stores cannot be decrypted with the supplied
+ * key. The original {@link SqliteEncryptionError} is preserved as `cause`.
+ */ export class EmbeddedWalletEncryptionError extends Error {
+    storeName;
+    constructor(storeName, opts){
+        super(`Embedded wallet '${storeName}' store could not be decrypted with the provided key`, {
+            cause: opts.cause
+        });
+        this.name = 'EmbeddedWalletEncryptionError';
+        this.storeName = storeName;
+    }
+}
+const defaultOpenStore = (log, name, poolDirectory, encryptionKey)=>AztecSQLiteOPFSStore.open(log, name, false, poolDirectory, encryptionKey);
+/**
+ * Opens the PXE and wallet stores in sequence, both encrypted with keys obtained from `getEncryptionKey`.
+ *
+ * The callback is invoked once per store (twice total per call) because `AztecSQLiteOPFSStore.open` *transfers*
+ * the key buffer to its worker. A single buffer would detach between the two opens.
+ *
+ * Failure modes:
+ *
+ *   - PXE store fails to decrypt → throws `EmbeddedWalletEncryptionError({ storeName: 'pxe', cause })`. No cleanup
+ *     needed (nothing was opened).
+ *   - Wallet store fails to decrypt → closes the already-opened PXE store then throws
+ *     `EmbeddedWalletEncryptionError({ storeName: 'wallet', cause })`.
+ *   - Any non-decrypt error during the wallet open → still closes PXE, then re-throws the original error unwrapped
+ *     (preserves callers' existing untyped error handling for non-encryption faults).
+ *
+ * @param config           - Per-store name/poolDirectory.
+ * @param getEncryptionKey - Returns a fresh 32-byte key per call (the buffer
+ *                           detaches on transfer, so each call must allocate).
+ * @param log              - Logger for both stores.
+ * @param openStore        - Internal test seam. Do not pass in production code.
+ */ export async function openEncryptedEmbeddedStores(config, getEncryptionKey, log, openStore = defaultOpenStore) {
+    const pxeStore = await openOneStore('pxe', config.pxe, getEncryptionKey, log, openStore);
+    try {
+        const walletStore = await openOneStore('wallet', config.wallet, getEncryptionKey, log, openStore);
+        return {
+            pxeStore,
+            walletStore
+        };
+    } catch (err) {
+        // Cleanup is best-effort — if close() itself throws (e.g. worker already dead), swallow it so the original error
+        // surfaces unobstructed.
+        await pxeStore.close().catch(()=>{});
+        throw err;
+    }
+}
+async function openOneStore(storeName, { name, poolDirectory }, getEncryptionKey, log, openStore) {
+    const key = await getEncryptionKey();
+    try {
+        return await openStore(log, name, poolDirectory, key);
+    } catch (err) {
+        if (err instanceof SqliteEncryptionError && err.code === 'decrypt_failed') {
+            throw new EmbeddedWalletEncryptionError(storeName, {
+                cause: err
+            });
+        }
+        throw err;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aztec/wallets",
   "homepage": "https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/wallets",
-  "version": "4.3.0-nightly.20260513",
+  "version": "4.3.0-nightly.20260514",
   "type": "module",
   "exports": {
     "./embedded": {
@@ -14,6 +14,7 @@
         "default": "./dest/embedded/entrypoints/node.js"
       }
     },
+    "./embedded/store-encryption": "./dest/embedded/store_encryption.js",
     "./testing": "./dest/testing.js"
   },
   "scripts": {
@@ -27,15 +28,15 @@
     "../package.common.json"
   ],
   "dependencies": {
-    "@aztec/accounts": "4.3.0-nightly.20260513",
-    "@aztec/aztec.js": "4.3.0-nightly.20260513",
-    "@aztec/entrypoints": "4.3.0-nightly.20260513",
-    "@aztec/foundation": "4.3.0-nightly.20260513",
-    "@aztec/kv-store": "4.3.0-nightly.20260513",
-    "@aztec/protocol-contracts": "4.3.0-nightly.20260513",
-    "@aztec/pxe": "4.3.0-nightly.20260513",
-    "@aztec/stdlib": "4.3.0-nightly.20260513",
-    "@aztec/wallet-sdk": "4.3.0-nightly.20260513"
+    "@aztec/accounts": "4.3.0-nightly.20260514",
+    "@aztec/aztec.js": "4.3.0-nightly.20260514",
+    "@aztec/entrypoints": "4.3.0-nightly.20260514",
+    "@aztec/foundation": "4.3.0-nightly.20260514",
+    "@aztec/kv-store": "4.3.0-nightly.20260514",
+    "@aztec/protocol-contracts": "4.3.0-nightly.20260514",
+    "@aztec/pxe": "4.3.0-nightly.20260514",
+    "@aztec/stdlib": "4.3.0-nightly.20260514",
+    "@aztec/wallet-sdk": "4.3.0-nightly.20260514"
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",

package/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.

package/src/embedded/store_encryption.ts

@@ -0,0 +1,107 @@
+/**
+ * Wallet-layer helpers for opening the embedded wallet's two encrypted stores (PXE + walletDB) as a cohesive unit.
+ *
+ * Sits on top of `@aztec/kv-store/sqlite-opfs`'s typed `SqliteEncryptionError` and adds:
+ *
+ *   - `storeName: 'pxe' | 'wallet'`, telling callers WHICH store failed.
+ *   - Cleanup: when the wallet store fails to open, ensures the already-opened PXE store is closed before the error
+ *     surfaces, so callers don't leak the SAH Pool's OPFS lock.
+ */
+import type { Logger } from '@aztec/foundation/log';
+import { AztecSQLiteOPFSStore, SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
+
+/** Which of the embedded wallet's two stores failed to open. */
+export type EmbeddedStoreName = 'pxe' | 'wallet';
+
+/**
+ * Thrown by {@link openEncryptedEmbeddedStores} when one of the two stores cannot be decrypted with the supplied
+ * key. The original {@link SqliteEncryptionError} is preserved as `cause`.
+ */
+export class EmbeddedWalletEncryptionError extends Error {
+  readonly storeName: EmbeddedStoreName;
+
+  constructor(storeName: EmbeddedStoreName, opts: { cause: SqliteEncryptionError }) {
+    super(`Embedded wallet '${storeName}' store could not be decrypted with the provided key`, { cause: opts.cause });
+    this.name = 'EmbeddedWalletEncryptionError';
+    this.storeName = storeName;
+  }
+}
+
+/** Configuration for {@link openEncryptedEmbeddedStores}. */
+export interface OpenEncryptedEmbeddedStoresOptions {
+  pxe: { name: string; poolDirectory?: string };
+  wallet: { name: string; poolDirectory?: string };
+}
+
+/**
+ * Internal seam for tests to inject a fake store opener. Defaults to `AztecSQLiteOPFSStore.open`. Not part of the
+ * public API.
+ *
+ * @internal
+ */
+export type OpenSqliteEncryptedStoreFn = (
+  log: Logger,
+  name: string,
+  poolDirectory: string | undefined,
+  encryptionKey: Uint8Array,
+) => Promise<AztecSQLiteOPFSStore>;
+
+const defaultOpenStore: OpenSqliteEncryptedStoreFn = (log, name, poolDirectory, encryptionKey) =>
+  AztecSQLiteOPFSStore.open(log, name, false, poolDirectory, encryptionKey);
+
+/**
+ * Opens the PXE and wallet stores in sequence, both encrypted with keys obtained from `getEncryptionKey`.
+ *
+ * The callback is invoked once per store (twice total per call) because `AztecSQLiteOPFSStore.open` *transfers*
+ * the key buffer to its worker. A single buffer would detach between the two opens.
+ *
+ * Failure modes:
+ *
+ *   - PXE store fails to decrypt → throws `EmbeddedWalletEncryptionError({ storeName: 'pxe', cause })`. No cleanup
+ *     needed (nothing was opened).
+ *   - Wallet store fails to decrypt → closes the already-opened PXE store then throws
+ *     `EmbeddedWalletEncryptionError({ storeName: 'wallet', cause })`.
+ *   - Any non-decrypt error during the wallet open → still closes PXE, then re-throws the original error unwrapped
+ *     (preserves callers' existing untyped error handling for non-encryption faults).
+ *
+ * @param config           - Per-store name/poolDirectory.
+ * @param getEncryptionKey - Returns a fresh 32-byte key per call (the buffer
+ *                           detaches on transfer, so each call must allocate).
+ * @param log              - Logger for both stores.
+ * @param openStore        - Internal test seam. Do not pass in production code.
+ */
+export async function openEncryptedEmbeddedStores(
+  config: OpenEncryptedEmbeddedStoresOptions,
+  getEncryptionKey: () => Promise<Uint8Array>,
+  log: Logger,
+  openStore: OpenSqliteEncryptedStoreFn = defaultOpenStore,
+): Promise<{ pxeStore: AztecSQLiteOPFSStore; walletStore: AztecSQLiteOPFSStore }> {
+  const pxeStore = await openOneStore('pxe', config.pxe, getEncryptionKey, log, openStore);
+  try {
+    const walletStore = await openOneStore('wallet', config.wallet, getEncryptionKey, log, openStore);
+    return { pxeStore, walletStore };
+  } catch (err) {
+    // Cleanup is best-effort — if close() itself throws (e.g. worker already dead), swallow it so the original error
+    // surfaces unobstructed.
+    await pxeStore.close().catch(() => {});
+    throw err;
+  }
+}
+
+async function openOneStore(
+  storeName: EmbeddedStoreName,
+  { name, poolDirectory }: { name: string; poolDirectory?: string },
+  getEncryptionKey: () => Promise<Uint8Array>,
+  log: Logger,
+  openStore: OpenSqliteEncryptedStoreFn,
+): Promise<AztecSQLiteOPFSStore> {
+  const key = await getEncryptionKey();
+  try {
+    return await openStore(log, name, poolDirectory, key);
+  } catch (err) {
+    if (err instanceof SqliteEncryptionError && err.code === 'decrypt_failed') {
+      throw new EmbeddedWalletEncryptionError(storeName, { cause: err });
+    }
+    throw err;
+  }
+}