walletkit-web 0.21.3 → 0.22.1

package/README.md

@@ -1,28 +1,116 @@
-# `@worldcoin/walletkit-web`
+# `walletkit-web`
 
-Browser WebAssembly bindings for WalletKit.
+WalletKit's browser client. The package always runs Rust/WASM, cryptography,
+proof generation and SQLite in a dedicated Web Worker. Importing the package
+is safe during SSR; call `initializeWalletKit` in a browser.
 
-> PROTOTYPE: this package is private while its generation and publication
-> workflow is being validated.
+```ts
+import { initializeWalletKit } from "walletkit-web";
+
+const wallet = await initializeWalletKit({
+  databaseKey, // Uint8Array containing the resolved 32-byte K_intermediate
+  storageId: "my-account", // stable namespace for this consumer/account
+  environment: "staging", // defaults to production
+  region: "eu",
+});
+const recovery = await wallet.recoveryDataFromSeed(seed);
+// For an already registered account:
+await wallet.initializeAuthenticator(seed);
+const proofJson = await wallet.generateProof(requestJson);
+await wallet.close();
+```
+
+The host supplies the resolved `databaseKey`, for example after obtaining passkey
+PRF output and deriving the database key. PRF acquisition/derivation happens before
+initialization; WalletKit does not call WebAuthn or wrap this key in an envelope.
+The worker constructs `StorageKeys.fromBytes(databaseKey)` and passes those keys to
+`CredentialStore`. Both vault and cache use that key directly through sqlite3mc.
+
+Supply the same key and storage ID when reopening. The authenticator seed and
+database key are separate inputs. The package does not persist the database key;
+initialization copies it and the caller owns clearing its own copy. Rust keeps the
+resolved key in zeroizing memory until its last owner releases it.
+
+Mobile hosts can instead resolve `openOrCreateStorageKeys(paths, keystore,
+blobStore, now)` before constructing the same `CredentialStore(paths, keys)`.
+The store retains no keystore or blob-store references. It releases its key
+reference on destruction and requires a new instance to reopen. The host separately
+calls `deleteStorageKeyEnvelope(paths, blobStore)` if it owns an envelope that should
+be deleted. Existing envelope-backed databases still use their resolved intermediate
+key; the old wrapping secret is not a replacement for that database key.
+
+## Browser API
+
+All calls into the worker return Promises. The public client exposes
+`recoveryDataFromSeed`, `register`, `pollRegistration`, `initializeAuthenticator`,
+`prepareCredential`, `storeCredential`, and `generateProof`. Registration polling
+returns plain status records, including failure details. `prepareCredential`
+returns the subject and serialized blinding factor for an issuer flow;
+`storeCredential` accepts credential bytes and that factor. Issuer HTTP calls and
+relying-party request construction remain application code.
+
+This replaces the prototype API that returned the generated UniFFI namespace.
+Generated Rust objects are internal and never cross the worker boundary. Existing
+consumers must migrate their calls to the browser client; it is not a transparent
+proxy for every generated binding. See the Next.js demo for a complete registration,
+issuance and proof flow.
 
-The package owns the compiled WalletKit module, generated TypeScript bindings,
-UniFFI player setup, and WASM asset resolution. Browser applications initialize
-it through one interface:
+Operations run in order, including asynchronous work. `close()` drains queued
+operations, destroys owned Rust objects and terminates the worker. `terminate()`
+interrupts immediately and rejects pending requests. Worker failures also reject
+pending requests. An optional `signal` cancels initialization only; after it
+resolves, use `close()` or `terminate()`.
+
+## Assets and deployment
+
+Default URLs are resolved by the application's bundler. Both worker JavaScript
+and the roughly 40 MB WASM asset ship in `dist`. The worker is self-contained,
+including the generated glue and its runtime dependencies.
+
+Hosts with custom asset layouts can provide explicit URLs:
 
 ```ts
-const { initializeWalletKit } = await import("@worldcoin/walletkit-web");
-const walletKit = await initializeWalletKit();
+const wallet = await initializeWalletKit({
+  databaseKey,
+  workerUrl: "/assets/walletkit.worker.js",
+  wasmUrl: "/assets/walletkit.wasm",
+});
 ```
 
-Build it from the repository root with the pinned toolchain:
+Relative overrides resolve against the page URL. These options change asset
+locations; they do not enable main-thread execution. Serve the worker from a
+permitted same-origin location and the WASM file as `application/wasm`.
+
+## Persistent storage
+
+Initialization acquires the OPFS sync-access-handle pool asynchronously. SQLite
+operations are synchronous afterward. The browser's direct-key path needs no envelope database. The encrypted credential
+vault/cache retain their existing format and use rollback journals on WASM.
+
+Closing a SQLite connection does not release the pool's OPFS handles: the pool
+remains alive until worker termination. Currently one worker owns the WalletKit
+pool per origin. A second tab/client receives an initialization error, even with
+a different storage ID. After shutdown, browser handle release may be asynchronous;
+a subsequent initializer may need to retry. There is no silent memory fallback.
+Pool capacity is reserved at startup rather than expanded during synchronous SQL.
+
+Browser storage requires a supported secure context (localhost is suitable for
+development). The SAH pool does not require cross-origin-isolation headers.
+Browser quota and eviction policy still apply.
+
+## Build and verify
 
 ```sh
-nix develop .#wasm --command npm --prefix web/walletkit install
-nix develop .#wasm --command npm --prefix web/walletkit run build
+nix develop .#wasm --command bun install --cwd web/walletkit --frozen-lockfile
+nix develop .#wasm --command bun run --cwd web/walletkit build
+nix develop .#wasm --command bun run --cwd web/walletkit test:browser
 ```
 
-The release build uses `crates/walletkit` directly, disables its default
-features except for `embed-zkeys`, and optimizes the generated module with
-`wasm-opt -Oz --converge`. Embedding the proving artifacts currently makes the
-optimized WASM roughly 40 MB; lazy artifact delivery and worker placement are
-still future production work.
+Browser tests use installed Google Chrome and a production Vite fixture. They
+cover worker startup and lifecycle, URL overrides, exclusive pool ownership,
+wrong-key rejection, and reopening storage with directly supplied keys.
+`bun run bundle` reuses generated bindings for TypeScript-only development.
+
+The example uses a new namespace and memory-only database keys on each load. Its encrypted
+files persist, but it intentionally cannot unlock them after reload; a production
+host must implement key recovery/unlock and stable account namespace selection.

package/dist/generated/walletkit_bg.d.ts

@@ -12,22 +12,32 @@ export function __wbg_addEventListener_520e749bbae24529(...args: any[]): any;
 export function __wbg_addEventListener_d85450ee1320c989(...args: any[]): any;
 export function __wbg_append_01c74e5c6b58aa64(...args: any[]): any;
 export function __wbg_arrayBuffer_3b637f0fa65c5351(...args: any[]): any;
+export function __wbg_buffer_54b87055582c8a81(arg0: any): any;
+export function __wbg_byteLength_41862ca4020b9c43(arg0: any): any;
+export function __wbg_byteOffset_d42e18c4441f628b(arg0: any): any;
 export function __wbg_call_8a2dd23819f8a60a(...args: any[]): any;
 export function __wbg_call_a6e5c5dce5018821(...args: any[]): any;
 export function __wbg_clearTimeout_333bba87532ab9d3(arg0: any): void;
 export function __wbg_clearTimeout_6b8d9a38b9263d65(arg0: any): void;
 export function __wbg_close_c65ca0257e895318(...args: any[]): any;
 export function __wbg_code_1fc52b4142a112ac(arg0: any): any;
+export function __wbg_createSyncAccessHandle_0caafebe31e4f2d9(arg0: any): any;
 export function __wbg_crypto_38df2bab126b63dc(arg0: any): any;
 export function __wbg_data_328de4280640da92(arg0: any): any;
 export function __wbg_dispatchEvent_ca78eaf3d469bc25(...args: any[]): any;
 export function __wbg_done_89b2b13e91a60321(arg0: any): any;
+export function __wbg_entries_3d99c52a47728e2f(arg0: any): any;
 export function __wbg_entries_900cefd6f70eb290(arg0: any): any;
 export function __wbg_fetch_074561c3e313c86f(arg0: any): Promise<Response>;
 export function __wbg_fetch_9dad4fe911207b37(arg0: any): Promise<Response>;
 export function __wbg_fetch_b5951fc96f52f786(arg0: any, arg1: any): any;
+export function __wbg_fill_5663f5c647107cce(arg0: any, arg1: any, arg2: any, arg3: any): any;
+export function __wbg_flush_a4bd8d4e05ad23f6(...args: any[]): any;
 export function __wbg_getDate_a1a40c1c5f40fe3b(arg0: any): any;
 export function __wbg_getDay_aa318cce5da74c49(arg0: any): any;
+export function __wbg_getDirectoryHandle_cf175faf1a75a384(arg0: any, arg1: any, arg2: any, arg3: any): any;
+export function __wbg_getDirectory_389283588dfb8117(arg0: any): any;
+export function __wbg_getFileHandle_72de55ab3ca9ad57(arg0: any, arg1: any, arg2: any, arg3: any): any;
 export function __wbg_getFullYear_6af8b229792ae254(arg0: any): any;
 export function __wbg_getHours_9f6561095682ce51(arg0: any): any;
 export function __wbg_getMinutes_b0d5cd90bf9b8f22(arg0: any): any;
@@ -37,22 +47,29 @@ export function __wbg_getRandomValues_3f44b700395062e5(...args: any[]): any;
 export function __wbg_getRandomValues_bf16787eede473f5(...args: any[]): any;
 export function __wbg_getRandomValues_c44a50d8cfdaebeb(...args: any[]): any;
 export function __wbg_getSeconds_40c565b3a6cb05fe(arg0: any): any;
+export function __wbg_getSize_29187e13478442fb(...args: any[]): any;
 export function __wbg_getTime_d6f070c088c9b5ed(arg0: any): any;
 export function __wbg_getTimezoneOffset_dc9862c79e5a81a3(arg0: any): any;
+export function __wbg_getUint32_11fb2913bdb7d394(arg0: any, arg1: any): any;
 export function __wbg_get_507a50627bffa49b(arg0: any, arg1: any): any;
+export function __wbg_get_78f252d074a84d0b(...args: any[]): any;
 export function __wbg_get_c7eb1f358a7654df(...args: any[]): any;
+export function __wbg_get_index_e68b01fac18aa799(arg0: any, arg1: any): any;
 export function __wbg_has_8374cf06984d8bfc(...args: any[]): any;
 export function __wbg_headers_cf9c80f30e2a4eff(arg0: any): any;
 export function __wbg_instanceof_ArrayBuffer_4480b9e0068a8adb(arg0: any): boolean;
 export function __wbg_instanceof_Error_1fdac9f13a8181ba(arg0: any): boolean;
 export function __wbg_instanceof_Response_c8b64b2256f01bec(arg0: any): boolean;
+export function __wbg_instanceof_WorkerGlobalScope_8ec07b5e040a41c3(arg0: any): boolean;
 export function __wbg_isArray_0677c962b281d01a(arg0: any): arg0 is any[];
 export function __wbg_iterator_6f722e4a93058b71(): symbol;
 export function __wbg_length_1f0964f4a5e2c6d8(arg0: any): any;
 export function __wbg_message_8326fb1d549bebc5(arg0: any): any;
 export function __wbg_msCrypto_bd5a034af96bcba6(arg0: any): any;
 export function __wbg_name_b0b4809690944614(arg0: any): any;
+export function __wbg_navigator_51379c10a84aeec9(arg0: any): any;
 export function __wbg_new_0_3da9e97f24fc69be(): Date;
+export function __wbg_new_0c72e559145ea733(arg0: any, arg1: any, arg2: any): DataView<any>;
 export function __wbg_new_0d809930cd1354c6(...args: any[]): any;
 export function __wbg_new_4339b2a2675a03e3(...args: any[]): any;
 export function __wbg_new_bf8729ffe10e9ee7(...args: any[]): any;
@@ -66,11 +83,14 @@ export function __wbg_new_with_str_and_init_d95cbe11ce28e65e(...args: any[]): an
 export function __wbg_new_with_year_month_day_f2354b74b4b2a4f3(arg0: any, arg1: any, arg2: any): Date;
 export function __wbg_next_6dbf2c0ac8cde20f(arg0: any): any;
 export function __wbg_next_71f2aa1cb3d1e37e(...args: any[]): any;
+export function __wbg_next_dfa6c7f0ee891663(...args: any[]): any;
 export function __wbg_node_84ea875411254db1(arg0: any): any;
 export function __wbg_process_44c7a14e11e9f69e(arg0: any): any;
 export function __wbg_prototypesetcall_4770620bbe4688a0(arg0: any, arg1: any, arg2: any): void;
 export function __wbg_randomFillSync_6c25eac9869eb53c(...args: any[]): any;
 export function __wbg_random_039a7d5d06e0d333(): number;
+export function __wbg_read_27d98fb08886b1fc(...args: any[]): any;
+export function __wbg_read_ab82a1efee669e3b(...args: any[]): any;
 export function __wbg_readyState_50bc38c2a9e83db6(arg0: any): any;
 export function __wbg_reason_5dc8e429d537d6a9(arg0: any, arg1: any): void;
 export function __wbg_removeEventListener_a3f23c70077bdcc1(...args: any[]): any;
@@ -79,10 +99,15 @@ export function __wbg_send_a321b376d40ec867(...args: any[]): any;
 export function __wbg_send_df98dd5ede9b3f4d(...args: any[]): any;
 export function __wbg_setTimeout_3a808dd861dd3c12(arg0: any, arg1: any): number;
 export function __wbg_setTimeout_f757f00851f76c42(arg0: any, arg1: any): number;
+export function __wbg_setUint32_1a26b3818324ed47(arg0: any, arg1: any, arg2: any): void;
+export function __wbg_set_4d7dd76f3dae2926(arg0: any, arg1: any, arg2: any): void;
+export function __wbg_set_at_674f6538cd77adef(arg0: any, arg1: any): void;
 export function __wbg_set_binaryType_a37b086c78ca7c29(arg0: any, arg1: any): void;
 export function __wbg_set_body_029f2d171e0a005f(arg0: any, arg1: any): void;
 export function __wbg_set_cache_b4a740b195c051f4(arg0: any, arg1: any): void;
 export function __wbg_set_code_9d09aecd77d789f4(arg0: any, arg1: any): void;
+export function __wbg_set_create_a807a6e9ac628698(arg0: any, arg1: any): void;
+export function __wbg_set_create_fa1dfa475fac91e9(arg0: any, arg1: any): void;
 export function __wbg_set_credentials_bb34a40189e3b43b(arg0: any, arg1: any): void;
 export function __wbg_set_headers_9c61d123c3ee1f10(arg0: any, arg1: any): void;
 export function __wbg_set_method_5532d59b92d76467(arg0: any, arg1: any, arg2: any): void;
@@ -96,15 +121,20 @@ export function __wbg_static_accessor_GLOBAL_THIS_8d1badc68b5a74f4(): any;
 export function __wbg_static_accessor_SELF_146583524fe1469b(): any;
 export function __wbg_static_accessor_WINDOW_f2829a2234d7819e(): any;
 export function __wbg_status_c45b3b9b3033184a(arg0: any): any;
+export function __wbg_storage_3c893ad40b9e831e(arg0: any): any;
 export function __wbg_stringify_b54333f60f1e4dad(...args: any[]): any;
 export function __wbg_subarray_3ed232c8a6baee09(arg0: any, arg1: any, arg2: any): any;
 export function __wbg_text_d3a29f7525a132c3(...args: any[]): any;
 export function __wbg_then_16d107c451e9905d(arg0: any, arg1: any, arg2: any): any;
 export function __wbg_toString_bac9199ff382784d(arg0: any): any;
+export function __wbg_truncate_8832884f3fa99eab(...args: any[]): any;
+export function __wbg_truncate_98a6032d23095328(...args: any[]): any;
 export function __wbg_url_abdb8fb08377f8c0(arg0: any, arg1: any): void;
 export function __wbg_value_a5d5488a9589444a(arg0: any): any;
 export function __wbg_versions_276b2795b1c6a219(arg0: any): any;
 export function __wbg_wasClean_3c7aa2335da09e74(arg0: any): any;
+export function __wbg_write_66c6f8f1293992eb(...args: any[]): any;
+export function __wbg_write_e557b5312ec23477(...args: any[]): any;
 export function __wbindgen_cast_0000000000000001(arg0: any, arg1: any): {
     (...args: any[]): any;
     _wbg_cb_unref(): void;