fix: Allows creating external keystore with the Worker (#1569)

* feat: enable external keystore through callbacks in worker thread

* fix: handle callback requests and change base to main

* chore: rebase main

Author: 0xnullifier

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.12.6 (TBD)
+
+* Enables Workers with `createClientWithExternalKeystore` via callbacks ([#1569](https://github.com/0xMiden/miden-client/pull/1569))
+
 ## 0.12.5 (2025-12-01)
 
 * Removed the top-level await from the web-client JS entry point by lazily loading the WASM module, allowing `@demox-labs/miden-sdk` to be imported normally (including in Next.js SSR builds), and updated the worker bootstrap to match.

crates/web-client/js/constants.js

@@ -1,6 +1,13 @@
 export const WorkerAction = Object.freeze({
   INIT: "init",
   CALL_METHOD: "callMethod",
+  EXECUTE_CALLBACK: "executeCallback",
+});
+
+export const CallbackType = Object.freeze({
+  GET_KEY: "getKey",
+  INSERT_KEY: "insertKey",
+  SIGN: "sign",
 });
 
 export const MethodName = Object.freeze({

crates/web-client/js/index.js

@@ -1,5 +1,5 @@
 import loadWasm from "./wasm.js";
-import { MethodName, WorkerAction } from "./constants.js";
+import { CallbackType, MethodName, WorkerAction } from "./constants.js";
 export * from "../Cargo.toml";
 
 const buildTypedArraysExport = (exportObject) => {
@@ -104,12 +104,7 @@ export class WebClient {
     this.signCb = signCb;
 
     // Check if Web Workers are available.
-    if (
-      typeof Worker !== "undefined" &&
-      !this.getKeyCb &&
-      !this.insertKeyCb &&
-      !this.signCb
-    ) {
+    if (typeof Worker !== "undefined") {
       console.log("WebClient: Web Workers are available.");
       // Create the worker.
       this.worker = new Worker(
@@ -131,7 +126,7 @@ export class WebClient {
       });
 
       // Listen for messages from the worker.
-      this.worker.addEventListener("message", (event) => {
+      this.worker.addEventListener("message", async (event) => {
         const data = event.data;
 
         // Worker script loaded.
@@ -146,6 +141,36 @@ export class WebClient {
           return;
         }
 
+        if (data.action === WorkerAction.EXECUTE_CALLBACK) {
+          const { callbackType, args, requestId } = data;
+          try {
+            const callbackMapping = {
+              [CallbackType.GET_KEY]: this.getKeyCb,
+              [CallbackType.INSERT_KEY]: this.insertKeyCb,
+              [CallbackType.SIGN]: this.signCb,
+            };
+            if (!callbackMapping[callbackType]) {
+              throw new Error(`Callback ${callbackType} not available`);
+            }
+            const callbackFunction = callbackMapping[callbackType];
+            let result = callbackFunction.apply(this, args);
+            if (result instanceof Promise) {
+              result = await result;
+            }
+
+            this.worker.postMessage({
+              callbackResult: result,
+              callbackRequestId: requestId,
+            });
+          } catch (error) {
+            this.worker.postMessage({
+              callbackError: error.message,
+              callbackRequestId: requestId,
+            });
+          }
+          return;
+        }
+
         // Handle responses for method calls.
         const { requestId, error, result, methodName } = data;
         if (requestId && this.pendingRequests.has(requestId)) {
@@ -171,9 +196,9 @@ export class WebClient {
             this.rpcUrl,
             this.noteTransportUrl,
             this.seed,
-            this.getKeyCb,
-            this.insertKeyCb,
-            this.signCb,
+            !!this.getKeyCb,
+            !!this.insertKeyCb,
+            !!this.signCb,
           ],
         });
       });

crates/web-client/js/types/index.d.ts

@@ -102,6 +102,23 @@ export declare class WebClient extends WasmWebClient {
     seed?: string
   ): Promise<WebClient & WasmWebClient>;
 
+  static createClientWithExternalKeystore(
+    rpcUrl?: string,
+    noteTransportUrl?: string,
+    seed?: string,
+    getKeyCb?: (
+      pubKey: Uint8Array
+    ) => Promise<Uint8Array | null | undefined> | Uint8Array | null | undefined,
+    insertKeyCb?: (
+      pubKey: Uint8Array,
+      secretKey: Uint8Array
+    ) => Promise<void> | void,
+    signCb?: (
+      pubKey: Uint8Array,
+      signingInputs: Uint8Array
+    ) => Promise<Uint8Array> | Uint8Array
+  ): Promise<WebClient & WasmWebClient>;
+
   /** Returns the default transaction prover configured on the client. */
   defaultTransactionProver(): TransactionProver;
 

crates/web-client/js/workers/web-client-methods-worker.js

@@ -1,5 +1,5 @@
 import loadWasm from "../../dist/wasm.js";
-import { MethodName, WorkerAction } from "../constants.js";
+import { CallbackType, MethodName, WorkerAction } from "../constants.js";
 
 let wasmModule = null;
 
@@ -54,6 +54,52 @@ let ready = false; // Indicates if the worker is fully initialized.
 let messageQueue = []; // Queue for sequential processing.
 let processing = false; // Flag to ensure one message is processed at a time.
 
+// Track pending callback requests
+let pendingCallbacks = new Map();
+
+// Define proxy functions for callbacks that communicate with main thread
+const callbackProxies = {
+  getKey: async (pubKey) => {
+    return new Promise((resolve, reject) => {
+      const requestId = `${CallbackType.GET_KEY}-${Date.now()}-${Math.random()}`;
+      pendingCallbacks.set(requestId, { resolve, reject });
+
+      self.postMessage({
+        action: WorkerAction.EXECUTE_CALLBACK,
+        callbackType: CallbackType.GET_KEY,
+        args: [pubKey],
+        requestId,
+      });
+    });
+  },
+  insertKey: async (pubKey, secretKey) => {
+    return new Promise((resolve, reject) => {
+      const requestId = `${CallbackType.INSERT_KEY}-${Date.now()}-${Math.random()}`;
+      pendingCallbacks.set(requestId, { resolve, reject });
+
+      self.postMessage({
+        action: WorkerAction.EXECUTE_CALLBACK,
+        callbackType: CallbackType.INSERT_KEY,
+        args: [pubKey, secretKey],
+        requestId,
+      });
+    });
+  },
+  sign: async (pubKey, signingInputs) => {
+    return new Promise((resolve, reject) => {
+      const requestId = `${CallbackType.SIGN}-${Date.now()}-${Math.random()}`;
+      pendingCallbacks.set(requestId, { resolve, reject });
+
+      self.postMessage({
+        action: WorkerAction.EXECUTE_CALLBACK,
+        callbackType: CallbackType.SIGN,
+        args: [pubKey, signingInputs],
+        requestId,
+      });
+    });
+  },
+};
+
 // Define a mapping from method names to handler functions.
 const methodHandlers = {
   [MethodName.NEW_WALLET]: async (args) => {
@@ -235,11 +281,23 @@ async function processMessage(event) {
   const { action, args, methodName, requestId } = event.data;
   try {
     if (action === WorkerAction.INIT) {
-      const [rpcUrl, noteTransportUrl, seed] = args;
       // Initialize the WASM WebClient.
+      const [rpcUrl, noteTransportUrl, seed, getKey, insertKey, sign] = args;
       const wasm = await getWasmOrThrow();
       wasmWebClient = new wasm.WebClient();
-      await wasmWebClient.createClient(rpcUrl, noteTransportUrl, seed);
+      // Initialize the WASM WebClient.
+      if (getKey || insertKey || sign) {
+        await wasmWebClient.createClientWithExternalKeystore(
+          rpcUrl,
+          noteTransportUrl,
+          seed,
+          getKey && callbackProxies.getKey,
+          insertKey && callbackProxies.insertKey,
+          sign && callbackProxies.sign
+        );
+      } else {
+        await wasmWebClient.createClient(rpcUrl, noteTransportUrl, seed);
+      }
 
       wasmSeed = seed;
       ready = true;
@@ -287,6 +345,20 @@ async function processQueue() {
 
 // Enqueue incoming messages and process them sequentially.
 self.onmessage = (event) => {
+  if (
+    event.data.callbackRequestId &&
+    pendingCallbacks.has(event.data.callbackRequestId)
+  ) {
+    const { callbackRequestId, callbackResult, callbackError } = event.data;
+    const { resolve, reject } = pendingCallbacks.get(callbackRequestId);
+    pendingCallbacks.delete(callbackRequestId);
+    if (!callbackError) {
+      resolve(callbackResult);
+    } else {
+      reject(new Error(callbackError));
+    }
+    return;
+  }
   messageQueue.push(event);
   processQueue();
 };