feat(web): WebAuthn PRF-based key encryption for web client

[WiktorStarczewski]

Part of a solution to #30 alongside #1835
Note, the vite-plugin is already merged into main, and is cherry-picked here without changes to be used in the example (should not produce merge conflicts when main goes to next), so doesnt need to be reviewed.

Summary

Adds opt-in passkey-based encryption for secret keys at rest in the web client. When enabled, keys stored in IndexedDB are encrypted using AES-256-GCM with a wrapping key derived from the WebAuthn PRF extension (Touch ID, Face ID, Windows Hello).

Without this feature, secret keys are stored as plaintext in IndexedDB, accessible to any JavaScript running in the same origin (XSS payloads, compromised dependencies, browser extensions). Passkey encryption adds a hardware-backed layer of protection — decrypting keys requires a biometric prompt.

Zero Rust/WASM changes — the entire feature uses the existing external keystore callback system from JavaScript.

How it works

1. Registration (once): navigator.credentials.create() with PRF extension registers a passkey bound to the origin
2. Authentication (each session): navigator.credentials.get() evaluates PRF, returning a deterministic 32-byte secret from the authenticator's secure enclave (requires biometric)
3. Key derivation: PRF output → HKDF-SHA256 → non-extractable AES-256-GCM CryptoKey
4. Encrypt on write: insertKey callback encrypts secret key → stores ciphertext in dedicated MidenKeystore_* IndexedDB
5. Decrypt on read: getKey callback reads ciphertext → decrypts with wrapping key → returns plaintext bytes to WASM
6. Signing: No sign callback — Rust calls getKey (triggers decryption), then signs locally in WASM

Testing

The wallet example in packages/react/examples is configured to use the new functionality (needs a 0.14 local node).

Encrypted format

[4B: "MWEB"] [1B: version=0x01] [12B: IV] [NB: AES-GCM ciphertext + 16B auth tag]

Distinct from the native CLI's MENC format (Argon2id + ChaCha20-Poly1305). Public key commitment bytes are used as AES-GCM additional authenticated data (AAD), binding each ciphertext to its key and preventing ciphertext-swapping attacks.

Security properties

Property	Detail
Wrapping key	Non-extractable CryptoKey — raw bytes never exposed to JS
IV (nonce)	Fresh random 12-byte IV per encryption
Authentication	AES-GCM 16-byte auth tag detects tampering
AAD binding	Ciphertext bound to public key commitment
Authenticator	Platform-bound (hardware), not roaming/USB keys
User verification	Biometric/PIN required on every session
Key derivation	HKDF-SHA256 with application-specific salt and info strings

Usage

Web SDK

import { MidenClient } from "@miden-sdk/miden-sdk";

// Just pass passkeyEncryption: true — the client checks browser support
// internally and silently falls back to unencrypted keystore if PRF
// is not available (e.g. Firefox).
const client = await MidenClient.create({
  passkeyEncryption: true,
});

isPasskeyPrfSupported() is also exported for UI purposes (e.g., conditionally showing a "biometric encryption" toggle), but is not required — MidenClient.create() handles the check internally.

React SDK

<MidenProvider config={{
  passkeyEncryption: true,
}}>

Both SDKs silently fall back to standard (unencrypted) keystore on browsers that don't support WebAuthn PRF (Firefox, older browsers).

Browser support

Browser	Min Version	PRF Support
Chrome	116+	Yes
Edge	116+	Yes
Safari	18+	Yes
Firefox	—	Not supported (graceful fallback)

Additional changes

• @miden-sdk/vite-plugin — Brought from main branch. Provides COOP/COEP headers, worker format config, and WASM resolve aliases for Vite-based dApps.
• StrictMode fix — Fixed a React 18 StrictMode bug in MidenProvider where the double-mount cycle prevented client initialization (isInitializedRef was not reset in the effect cleanup).
• Wallet example — Updated to use local packages, the vite plugin, and passkeyEncryption: true.
• Migration — When getKey finds no encrypted entry, it reads plaintext from the main DB, re-encrypts, verifies round-trip (byte comparison), then deletes the plaintext. Seamless upgrade path.

Files changed

File	Change
crates/web-client/js/passkey-keystore.js	New — WebAuthn PRF, AES-GCM wrapping, credential persistence, callback factory
crates/web-client/js/client.js	Passkey resolution + fallback in MidenClient.create()
crates/web-client/js/types/api-types.d.ts	PasskeyEncryptionOptions, ClientOptions.passkeyEncryption, optional keystore.sign
crates/web-client/js/index.js	Export isPasskeyPrfSupported, createPasskeyKeystore
crates/web-client/test/passkey-keystore.test.ts	Playwright tests with CDP virtual authenticator (8 test cases)
packages/react-sdk/src/context/MidenProvider.tsx	Passkey branch + fallback, StrictMode fix
packages/react-sdk/src/types/index.ts	PasskeyEncryptionOptions, config types
packages/react-sdk/src/index.ts	Re-export isPasskeyPrfSupported
packages/vite-plugin/*	New package — Vite plugin for Miden dApps
docs/external/src/web-client/passkey-encryption.md	Full documentation page

Test plan

• isPasskeyPrfSupported() returns true in Chrome/Safari/Edge, false in Firefox
• MidenClient.create({ passkeyEncryption: true }) triggers biometric prompt
• Create wallet → verify MidenKeystore_* DB has MWEB-prefixed entry
• Reload page → wallet operations work (key decrypts from existing credential)
• Standard MidenClient.create() without passkey — existing flow unchanged
• Firefox/unsupported browser — silently falls back to unencrypted keystore
• Playwright tests pass: yarn test in crates/web-client/

[TomasArrachea]

I tried the wallet example locally and it runs correctly. However, I have some doubts on how the user relies on the passkey. IIUC, the passkey is used to encrypt the keys stored in IndexedDb, so if the user somehow loses the passkey, they lose complete access to the wallet. Would the wallet implementation do that? I don't think it would be correct, at least we should expose the seed phrase so users can eventually restore the keys. It might be worth mentioning in the wallet example as a warning.

[JereSalo]

I tried the wallet example against a local node as well and it worked fine :)