kestrove-core/crates/kv-wasm/README.md

kv-wasm: the Kestrove core for the web vault

The web vault runs the same Rust core as the apps, compiled to WebAssembly: same 2SKD (Argon2id + Secret Key), same envelopes, same item model, same OPAQUE login, RFC 9421 request signing and sync engine (three-way merge, signed manifests, replay checks). The server stays zero-knowledge: only ciphertext leaves the browser.

Concern	Apps (kv-ffi)	Web (kv-wasm)
Local replica	SQLite (SqliteStore)	WebStore: in-memory, each changed entry written to IndexedDB before the call resolves
Transport	reqwest + rustls, TLS 1.3, SPKI pins	reqwest over fetch; the browser's TLS; same origin; pins accepted but not enforced
Device key	Secure Enclave / StrongBox / TPM	non-extractable WebCrypto ECDSA P-256 key, kept in IndexedDB
Randomness, clock	OS	crypto.getRandomValues, Date.now()
Biometric unlock (LUK)	yes	no: every unlock needs master password + Secret Key
URL matching	eTLD+1 via the Public Suffix List	same host only (the list would be a third of the download)
Passkeys	create, assert, list, delete	list, delete

Build and test

crates/kv-wasm/build.sh                      # pkg/: wasm-pack (size profile, wasm-opt -Oz) + worker files
wasm-pack test --headless --chrome crates/kv-wasm   # in Chrome: IndexedDB, WebCrypto, native fixture
node crates/kv-wasm/js/smoke.mjs             # the built package in Node (in-memory), Argon2 timing
cargo test -p kv-wasm                        # native: store, fixtures vs kv-ffi, sync with kv-ffi via test server

wasm-pack build crates/kv-wasm --target web alone also works (opt-level 3, a bit bigger). smoke.mjs runs a two-device sync round trip against a real server when KESTROVE_SERVER_URL and KESTROVE_SETUP_TOKEN are set (see the file header).

Size (build.sh): kv_wasm_bg.wasm 1.27 MB, 572 KB gzip, 467 KB brotli. JS glue ~60 KB. Serve it with compression and Content-Type: application/wasm.

Argon2id (m = 64 MiB, t = 3, p = 4, the account default): about 100–120 ms per derivation in Chrome and Node on an Apple Silicon Mac (native is in the same range). Expect several times that on low-end phones. It runs on the calling thread, hence the worker below.

Envelope compatibility is checked both ways with shared fixtures in tests/fixtures/: native-vault.json is made by kv-ffi and opened in Chrome; wasm-vault.json is made by the wasm package and opened by kv-ffi (tests/fixture.rs).

JS API

The generated pkg/kv_wasm.d.ts is the reference. It mirrors kv-ffi's VaultCore in camelCase; records are plain objects with the same fields as kv-ffi's records (ItemDto, ItemSummary, SyncReport, DeviceDto, PasskeySummary, ImportPreview, …); enums are camelCase strings ("login" | "secureNote" | "card" | "identity", "ok" | "pendingApproval"); bytes are Uint8Array; absent optionals come back as null. Every VaultCore method returns a Promise.

class VaultCore {
  static open(dbName?: string | null): Promise<VaultCore>;      // IndexedDB, default "kestrove"
  static newInMemory(): Promise<VaultCore>;                     // persists nothing
  createAccount(masterPassword): Promise<string>;               // -> Secret Key. Argon2id
  unlock(masterPassword, secretKey): Promise<void>;             // Argon2id
  lock(): Promise<void>; isLocked(); hasAccount(); accountId(); accountFingerprint();
  listItems(); getItem(id); saveItem(item: ItemDto): Promise<string>; deleteItem(id);
  itemHistory(id); itemsForUrl(pageUrl); listPasskeys(); deletePasskey(credentialId: Uint8Array);
  importPreview(data: Uint8Array, format: ImportFormat); importCommit(data, format, options);
  exportEncrypted(passphrase): Promise<Uint8Array>;             // Argon2id
  configureServer(url, spkiPins?); setDevice(name, platform?); deviceId(); deviceKeyFingerprint();
  serverInfo(); registerAccount(setupToken); login(masterPassword, secretKey, totp?): Promise<LoginResult>;
  syncNow(): Promise<SyncReport>; listDevices(); approveDevice(deviceId); revokeDevice(deviceId);
  logout(); isLoggedIn(); wipe();
}
generatePassword(length, symbols): string; totpCode(secretOrUri, unixTime): TotpCode;
matchUrl(itemUrl, pageUrl): MatchLevel; coreVersion(): string;

Errors reject with an Error whose name is "CoreError" and whose code is one of kv-ffi's CoreError cases (Locked, NoAccount, BadCredentials, Invalid, NotFound, Internal, NotConfigured, NotAuthenticated, PendingApproval, Network, Server + status, IntegrityAlarm + vaultId/reason), plus Busy (a sync is already running) and, from the worker client, InUse (another tab has the vault open).

Use it from a Web Worker

createAccount, unlock, login, exportEncrypted and importing a .kvex run Argon2id and block their thread. The package ships a worker and a typed client:

import { connectVault } from "@kestrove/kv-wasm/client.js";
const vault = await connectVault();          // RemoteVault: every VaultCore method + free functions, async
await vault.configureServer(location.origin);
if (await vault.hasAccount()) await vault.unlock(password, secretKey);
const items = await vault.listItems();
await vault.close();                          // frees the core (zeroizing keys) and ends the worker

The worker holds a Web Lock per database for its lifetime, so a second tab gets InUse instead of two replicas overwriting each other.

What the web UI must handle

1. Run the core in the worker (connectVault), never on the main thread.
2. Same origin. Serve the web vault from the server's origin and call configureServer(location.origin). CSP needs script-src 'self' 'wasm-unsafe-eval' and worker-src 'self'; connect-src 'self'.
3. Enrollment. The browser is a device. A first login returns "pendingApproval": show deviceKeyFingerprint() and ask the user to approve it on an enrolled device (which shows the same fingerprint in listDevices), then call login again. setDevice("Firefox on Mac") names it; the platform defaults to the OS from the user agent because the server has no web platform yet.
4. Every unlock needs the master password and Secret Key. There is no Local Unlock Key on the web: nothing secret is ever written to IndexedDB, so a reload, lock() or closing the tab leaves the vault locked. Lock on idle and on visibilitychange/pagehide as the UI sees fit; close() drops the worker and every key in it.
5. Secrets in JS. Master password, Secret Key and decrypted ItemDtos are JS strings the core cannot wipe. Do not keep them in long-lived state, logs or URLs. The core zeroizes its own copies.
6. Sync. Call syncNow() after login, on an interval and on focus. Handle Busy (skip), NotAuthenticated (ask for the password and login again), PendingApproval, IntegrityAlarm (stop and alert: the server rolled back or tampered with a vault) and restoredItemIds (tell the user an edit brought a deleted item back).
7. Storage. Call navigator.storage.persist(). If the browser evicts IndexedDB, unsynced edits and the device key are lost and the browser must be approved again.
8. Sign out of this browser: logout() (ends the server session), then wipe() (removes the replica and device key; the next login is a new device).
9. Import/export: pass new Uint8Array(await file.arrayBuffer()); exportEncrypted resolves with the .kvex bytes for a Blob download.
10. itemsForUrl / matchUrl match the same host only (no Public Suffix List in this build).