@aztec/sqlite3mc-wasm: locateFile escape hatch is overwritten by the vendored loader, so bundled apps request sqlite3.wasm from a build-machine file:// path

[olehmisar]

Disclosure: this issue was written and filed by an AI coding agent (Claude, via Claude Code) on behalf of a developer who hit this while upgrading an app to Aztec v5.1.0. The diagnosis and the reproductions below were carried out by the agent; the root cause was confirmed by running the code, not only by reading it. Please treat the analysis as a starting point and verify before acting on it.

Summary

@aztec/sqlite3mc-wasm@5.1.0 wraps the vendored SQLite loader to keep it bundler-friendly, injecting a locateFile hook via globalThis.sqlite3InitModuleState.emscriptenLocateFile. That hook is unconditionally overwritten by the vendored loader before it is ever consulted, so it has no effect.

The visible consequence is that a bundled browser app asks for sqlite3.wasm at a file:// URL pointing at the build machine's node_modules, which the browser refuses to fetch:

Fetch API cannot load
file:///<build-dir>/node_modules/.pnpm/@aztec+sqlite3mc-wasm@5.1.0/node_modules/@aztec/sqlite3mc-wasm/vendor/jswasm/sqlite3.wasm
due to access control checks

Since v5 the browser PXE store is SQLite over OPFS, so this is on the path of anything that opens a wallet in a bundled app.

Root cause

yarn-project/sqlite3mc-wasm/src/index.ts sets the hook on the shared state object and then calls the loader:

state.emscriptenLocateFile = (path, prefix) =>
  path === 'sqlite3.wasm' ? SQLITE3_WASM_URL.href : new URL(path, prefix || import.meta.url).href;
return sqlite3InitModuleUnwrapped(...args);

The vendored sqlite3.mjs entrypoint begins by assigning that same property from its first argument:

const sIM = globalThis.sqlite3InitModule = function ff(...args){
    sIMS.emscriptenLocateFile = args[0]?.locateFile ;
    sIMS.emscriptenInstantiateWasm = args[0]?.instantiateWasm ;
    return originalInit(...args)...

So the wrapper's hook is replaced on every call — with undefined whenever the caller passes no options. Module['locateFile'] then takes its fallback branch:

Module['locateFile'] = function(path, prefix) {
    if( this.emscriptenLocateFile instanceof Function ){
      return this.emscriptenLocateFile(path, prefix);
    }
    return new URL(path, import.meta.url).href;   // <-- taken
}.bind(sIMS);

Bundlers inline import.meta.url as the module's path on the build machine, which is where the file:// URL comes from. The statically analyzable SQLITE3_WASM_URL is emitted and hashed correctly by the bundler — it is simply never used.

@aztec/kv-store is such a caller: yarn-project/kv-store/src/sqlite-opfs/worker.ts calls await sqlite3InitModule() with no arguments.

Note this is not bundler-specific — the hook is dead in unbundled usage too. It only goes unnoticed there because SQLITE3_WASM_URL and the fallback happen to resolve to the same vendored file.

Reproduction

No bundler required. With @aztec/sqlite3mc-wasm@5.1.0 installed, patch globalThis.fetch to log and call the wrapper:

const realFetch = globalThis.fetch;
globalThis.fetch = (u, ...r) => { console.log('>>> FETCHED:', String(u)); return realFetch(u, ...r); };
const { default: init } = await import('@aztec/sqlite3mc-wasm');
await init();

Observed — the raw vendored path, not SQLITE3_WASM_URL:

>>> FETCHED: file:///<path>/@aztec/sqlite3mc-wasm/vendor/jswasm/sqlite3.wasm

Calling the vendored loader directly with the option is honoured, which isolates the mechanism:

const { default: rawInit } = await import('@aztec/sqlite3mc-wasm/vendor/jswasm/sqlite3.mjs');
await rawInit({ locateFile: p => (p === 'sqlite3.wasm' ? 'https://example.test/marker.wasm' : p) });
// >>> FETCHED: https://example.test/marker.wasm

In a bundled app the same fallback produces the build-machine file:// URL, and the fetch is blocked.

Suggested fix

Pass locateFile as an init option instead of writing it onto shared state, so the loader copies it across itself. A caller-supplied locateFile should still win:

const locateFile = (path: string, prefix: string) =>
  path === 'sqlite3.wasm' ? SQLITE3_WASM_URL.href : new URL(path, prefix || import.meta.url).href;

const sqlite3InitModule: typeof sqlite3InitModuleUnwrapped = (opts, ...rest) =>
  sqlite3InitModuleUnwrapped({ locateFile, ...opts }, ...rest);

Verified against a production build of a bundled app: the wasm then resolves to the emitted hashed asset and is served as application/wasm (1058719 bytes). Applied downstream as a package patch in the meantime.

A regression test asserting that locateFile is consulted for sqlite3.wasm when sqlite3InitModule() is called with no arguments would catch this — the current wrapper passes type checking and bundling, and only fails at runtime.

Environment

• @aztec/sqlite3mc-wasm@5.1.0, reached via @aztec/kv-store@5.1.0 → @aztec/pxe → @aztec/wallets (browser entrypoint)
• Reproduced both under a webpack-based production build and standalone in Node 24
• Affected source: yarn-project/sqlite3mc-wasm/src/index.ts, vendored vendor/jswasm/sqlite3.mjs

[olehmisar]

Here is the patch being used downstream, in case it is useful.

It is a pnpm patch and therefore applies to the published build output (dest/index.js), since that is what is patchable from a consumer. The equivalent change against yarn-project/sqlite3mc-wasm/src/index.ts is in the issue body above.

patches/@aztec__sqlite3mc-wasm@5.1.0.patch

diff --git a/dest/index.js b/dest/index.js
index 9188e162ef28c6797ddb5eff4f4d6df5eb683ccd..25cfdfde1a4a8a6d92dfb090c5f4b30618d5650a 100644
--- a/dest/index.js
+++ b/dest/index.js
@@ -14,15 +14,18 @@
  * unaffected: the static URL resolves to the real vendored path.
  */ import sqlite3InitModuleUnwrapped from '../vendor/jswasm/sqlite3.mjs';
 /** Statically analyzable wasm reference: bundlers emit the asset and rewrite this URL to its final location. */ const SQLITE3_WASM_URL = new URL('../vendor/jswasm/sqlite3.wasm', import.meta.url);
-const sqlite3InitModule = (...args)=>{
-    // `sqlite3.mjs` creates `globalThis.sqlite3InitModuleState` at import time and the inner Emscripten factory
-    // captures it (and deletes the global) on init, binding it as `this` of `Module['locateFile']`. Mutate the live
-    // object; recreate it if a previous init already consumed it (`debugModule` must exist — the factory calls it).
-    const g = globalThis;
-    const state = g.sqlite3InitModuleState ??= Object.assign(Object.create(null), {
-        debugModule: ()=>{}
-    });
-    state.emscriptenLocateFile = (path, prefix)=>path === 'sqlite3.wasm' ? SQLITE3_WASM_URL.href : new URL(path, prefix || import.meta.url).href;
-    return sqlite3InitModuleUnwrapped(...args);
+const locateFile = (path, prefix)=>path === 'sqlite3.wasm' ? SQLITE3_WASM_URL.href : new URL(path, prefix || import.meta.url).href;
+const sqlite3InitModule = (opts, ...rest)=>{
+    // Pass `locateFile` as an init option rather than writing `emscriptenLocateFile` onto
+    // `globalThis.sqlite3InitModuleState`. The vendored loader's entrypoint starts with
+    // `sIMS.emscriptenLocateFile = args[0]?.locateFile`, so it overwrites whatever was put on the state object --
+    // with `undefined` when the caller passes no options, which is how `@aztec/kv-store` calls it. The hook was
+    // therefore always cleared before `Module['locateFile']` ran, and the loader fell back to
+    // `new URL(path, import.meta.url)`: the unhashed vendored path, which a bundled app cannot fetch.
+    // Going through the option means the loader copies it onto the same state object itself.
+    return sqlite3InitModuleUnwrapped({
+        locateFile,
+        ...opts
+    }, ...rest);
 };
 export default sqlite3InitModule;

Two notes on the shape of the change:

• { locateFile, ...opts } rather than { ...opts, locateFile }, so a caller that supplies its own locateFile still wins — which is the behaviour the vendored loader already documents.
• The signature becomes (opts, ...rest) instead of (...args), so that calling with no arguments still produces an options object for the loader to read. This is what makes the no-argument call in @aztec/kv-store work.

With this applied, a production bundle resolves the wasm to the bundler-emitted hashed asset and serves it as application/wasm, instead of requesting the build-machine file:// path.