walletkit-web 0.21.3 → 0.22.0

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

@@ -1,8 +1,9 @@
 {
   "name": "walletkit-web",
-  "version": "0.21.3",
-  "description": "Browser WebAssembly bindings for WalletKit.",
+  "version": "0.22.0",
+  "description": "WalletKit enables users to hold credentials and prove their humanity with World ID .",
   "type": "module",
+  "packageManager": "bun@1.3.11",
   "files": [
     "dist/",
     "README.md"
@@ -15,20 +16,27 @@
   },
   "scripts": {
     "clean": "node scripts/clean.mjs",
+    "format": "prettier --write \"**/*.ts\"",
+    "format:check": "prettier --check \"**/*.ts\"",
     "patch:generator": "node scripts/patch-ubrn-wasm-bindgen.mjs",
-    "generate": "npm run patch:generator && ubrn build wasm2 --config ubrn.config.yaml --release && node scripts/optimize-wasm.mjs && node scripts/patch-generated-index.mjs",
-    "build": "npm run clean && npm run generate && tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/index.js --external:@ubjs/core --external:@ubjs/wasm && node scripts/copy-wasm.mjs",
-    "pack:check": "npm pack --dry-run"
+    "generate": "bun run patch:generator && ubrn build wasm2 --config ubrn.config.yaml --release && node scripts/optimize-wasm.mjs && node scripts/patch-generated-index.mjs",
+    "build": "bun run clean && bun run generate && bun run bundle",
+    "pack:check": "bun pm pack --dry-run",
+    "bundle": "tsc -p tsconfig.build.json && esbuild src/index.ts src/walletkit.worker.ts --bundle --format=esm --platform=browser --target=es2022 --outdir=dist --footer:js=\"export {};\" && node scripts/copy-wasm.mjs",
+    "test:serve": "vite preview --config tests/vite.config.ts --host 127.0.0.1 --port 4173 --strictPort",
+    "test:browser": "tsc -p tests/fixture/tsconfig.json && vite build --config tests/vite.config.ts && playwright test"
   },
   "dependencies": {
     "@ubjs/core": "0.31.0-5",
     "@ubjs/wasm": "0.31.0-5"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
     "esbuild": "0.25.9",
     "prettier": "3.6.2",
     "typescript": "5.9.2",
-    "uniffi-bindgen-react-native": "0.31.0-5"
+    "uniffi-bindgen-react-native": "0.31.0-5",
+    "vite": "^8.2.2"
   },
   "publishConfig": {
     "access": "public"

package/dist/generated/index.d.ts

@@ -1,11 +0,0 @@
-export * from "./walletkit";
-export * from "./walletkit_core";
-import * as walletkit from "./walletkit";
-import * as walletkit_core from "./walletkit_core";
-import { type WasmSource } from "@ubjs/wasm";
-export declare function uniffiInitAsync(source: WasmSource): Promise<void>;
-declare const _default: {
-    walletkit: typeof walletkit;
-    walletkit_core: typeof walletkit_core;
-};
-export default _default;