# 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 |
| Secret Key for setup codes | HPKE-sealed in the account record | in memory while unlocked, never persisted |

## Build and test

```sh
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 + onboarding 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.34 MB, **599 KB gzip**, 488 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`. `ItemSummary` also carries `tags` and `modifiedAt` (web only). **Every `VaultCore` method returns a `Promise`.**

```ts
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();
  // onboarding (kestrove-spec docs/10 §5)
  setupPayloadForKit(): Promise<string>;                        // Emergency Kit Setup Code
  addDevicePayload(): Promise<AddDevicePayload>;                // {payload, ticketId, expiresAt}
  revokeEnrollmentTicket(ticketId);
  loginWithSetup(setup: SetupInfo, masterPassword): Promise<LoginResult>;  // Argon2id
  joinStart(serverUrl): Promise<JoinSession>;                   // {qr, expiresAt}
  joinPoll(): Promise<JoinProgress>;                            // {code, setup}
  joinCancel(); joinApprove(qr): Promise<JoinConfirm>;          // {code, deviceName, platform, keyFingerprint}
  joinSend();
}
generatePassword(length, symbols): string; totpCode(secretOrUri, unixTime): TotpCode;
matchUrl(itemUrl, pageUrl): MatchLevel; coreVersion(): string;
parseSetupPayload(s): SetupInfo;                                // {serverUrl, spkiPins, accountId, secretKey, ticket}
```

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`, `DeviceRevoked`, `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:

```ts
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. The Secret Key that setup codes carry is kept in wasm memory only, set
   after an unlock/login proved it and dropped on `lock()`, `logout()` and any failed unlock or
   login; no getter exposes it (unlike kv-ffi, which keeps a sealed copy on disk). See
   kestrove-spec docs/10 §5 "Web vault". 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 `ItemDto`s 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. **Removed browser** (kestrove-spec docs/03 "Removed devices"). `DeviceRevoked` from any call means
   the server removed this browser's device id for good. The vault has already replaced the WebCrypto
   key and device id in IndexedDB (`deviceId()` changes), dropped the session and kept the local data.
   `loginWithSetup` with a ticket retries once by itself as the new device and normally resolves `"ok"`.
   Otherwise show "This device was removed from your account. Set it up again." and the sign-in: the
   next `login` enrols the new identity (`"pendingApproval"`). `resetDeviceIdentity()` does the same
   reset on demand. When the user removes a device, warn "To add it back later, set it up again as a new
   device."
8. **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.
9. **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).
10. **Import/export:** pass `new Uint8Array(await file.arrayBuffer())`; `exportEncrypted` resolves with
   the `.kvex` bytes for a `Blob` download.
11. `itemsForUrl` / `matchUrl` match the same host only (no Public Suffix List in this build).
12. **Onboarding** (docs/10). Same flows and names as kv-ffi; `expiresAt` is Unix **seconds**
    and codes look like `"123 456"`, as in kv-ffi.
    * *Sign in with a setup code*: `parseSetupPayload(text)` (scanned or pasted; it is a secret,
      so never put it in a URL or register `kestrove://` as a handler), then
      `loginWithSetup(setup, password)` and `syncNow()`. A code for a different server than this
      web vault's origin is refused with `Invalid` (the browser only talks to its own origin);
      tell the user to open the web vault at `setup.serverUrl`.
    * *Emergency Kit*: `setupPayloadForKit()` needs an unlocked vault.
    * *Add a device*: show `addDevicePayload().payload` as a QR until `expiresAt`; on Cancel call
      `revokeEnrollmentTicket(ticketId)`.
    * *Join from this browser* (no account yet): `joinStart(location.origin)`, show `qr`, call
      `joinPoll()` every 2 s; show `code` when it appears, and when `setup` arrives ask for the
      master password and `loginWithSetup`. `NotFound` = expired: start again. `joinCancel()` on
      leave.
    * *Approve another device's join* (signed in, unlocked): `joinApprove(qrText)` → show `code`,
      `deviceName`, `keyFingerprint`; after the user confirms the codes match, `joinSend()`.
    The join state lives in the worker: a reload or `close()` cancels it.