w3pk 0.10.2 → 0.10.4

package/docs/API_REFERENCE.md

@@ -10,6 +10,7 @@ Complete reference for all methods, types, and utilities in the w3pk SDK.
   - [Origin-Specific Address Derivation](#origin-specific-address-derivation)
   - [`sendTransaction()`](#sendtransactiontx-options-promisetransactionresult)
   - [`getEIP1193Provider()`](#geteip1193provideroptions-eip1193providerinterface)
+  - [`derivePrfSecret()`](#deriveprfsecrettag-string-promiseprfsecret)
 - [Stealth Addresses (ERC-5564)](#stealth-addresses-erc-5564)
 - [Zero-Knowledge Proofs](#zero-knowledge-proofs)
 - [Backup & Recovery](#backup--recovery)
@@ -43,7 +44,7 @@ interface Web3PasskeyConfig {
   debug?: boolean;                    // Enable debug mode (default: false)
   onError?: (error: Web3PasskeyError) => void;  // Global error handler
   onAuthStateChanged?: (isAuthenticated: boolean, user?: UserInfo) => void;  // Auth state callback
-  storage?: Storage;                  // Custom storage backend (default: IndexedDB)
+  storage?: Storage;                  // Custom storage backend (default: localStorage)
   sessionDuration?: number;           // Session duration in hours (default: 1)
   persistentSession?: Partial<PersistentSessionConfig>;  // Enable "Remember Me" functionality
   stealthAddresses?: StealthAddressConfig;  // Enable stealth addresses
@@ -57,7 +58,7 @@ interface PersistentSessionConfig {
 }
 ```
 
-**PRF requirement:** persistent sessions are encrypted under a key derived from the WebAuthn PRF extension, which the authenticator only releases during a user-verified assertion. On authenticators without PRF support, no persistent session is stored — the device falls back to in-memory sessions only (there is no weaker at-rest fallback). The session is re-keyed at every real (prompted) login; the configured `duration` is therefore also the renewal interval. With `requireReauth: true` the decryption key is never written to disk; with `requireReauth: false` it is stored as a non-extractable `CryptoKey` to allow silent restore. See [SECURITY.md](./SECURITY.md#at-rest-encryption-what-it-protects-and-what-it-doesnt) for the full model.
+**PRF requirement:** persistent sessions are encrypted under a key derived from the WebAuthn PRF extension, which the authenticator only releases during a user-verified assertion. On authenticators without PRF support, no persistent session is stored — the device falls back to in-memory sessions only (there is no weaker at-rest fallback). The session is re-keyed at every real (prompted) login; the configured `duration` is therefore also the renewal interval. With `requireReauth: true` the decryption key is never written to disk; with `requireReauth: false` it is stored next to the blob in localStorage to allow silent restore. See [SECURITY.md](./SECURITY.md#at-rest-encryption-what-it-protects-and-what-it-doesnt) for the full model.
 
 **Example:**
 
@@ -114,6 +115,8 @@ Register a new user with WebAuthn passkey authentication.
 interface RegisterResult {
   address: string;      // Ethereum address (account #0 derived from BIP44)
   username: string;     // Registered username
+  hasBackup: boolean;   // false for a new wallet: prompt for a backup now
+  evictionRisk: boolean; // true where the browser may wipe the wallet (WebKit tab, storage not persisted)
 }
 ```
 
@@ -122,17 +125,21 @@ interface RegisterResult {
 2. Creates WebAuthn credential (triggers biometric prompt)
 3. Derives Ethereum wallet from mnemonic (path: m/44'/60'/0'/0/0)
 4. Encrypts mnemonic using WebAuthn credential (AES-GCM-256)
-5. Stores encrypted wallet in IndexedDB
+5. Stores encrypted wallet in localStorage, next to the credential metadata
 6. Starts 1-hour session with decrypted mnemonic in memory
-7. Returns Ethereum address and username
+7. Returns Ethereum address, username, whether a backup exists and whether the browser may wipe the wallet
 
 **Example:**
 
 ```typescript
-const { address, username } = await w3pk.register({
+const { address, username, hasBackup, evictionRisk } = await w3pk.register({
   username: 'alice'
 })
 console.log('Registered:', username, 'with address:', address)
+
+if (!hasBackup) {
+  showBackupPrompt({ blocking: evictionRisk }) // see getBackupStatus()
+}
 ```
 
 ---
@@ -153,14 +160,20 @@ interface UserInfo {
 ```
 
 **What happens:**
-1. Retrieves credential ID from IndexedDB
+1. Retrieves credential ID from localStorage
 2. Triggers WebAuthn authentication (biometric prompt)
-3. Retrieves encrypted wallet from IndexedDB
+3. Retrieves encrypted wallet from localStorage
 4. Decrypts mnemonic using WebAuthn signature
 5. Starts new session (1 hour by default)
 6. Returns user info
 7. Subsequent operations use cached session - no repeated biometric prompts
 
+**Throws:**
+- `SyncRequiredError` if the passkey authenticated but this device has no credential metadata for it (carries `credentialId`); start a sync with `syncWalletWithPasskey()` and a password backup
+- `WalletMissingError` if the credential metadata is here but the wallet record is gone (carries `credentialId` and `ethereumAddress`); restore with `syncWalletWithPasskey()` or `importFromSync()`
+
+In both cases the user is not logged in and `onAuthStateChanged(true, …)` is not called.
+
 **Example:**
 
 ```typescript
@@ -218,6 +231,23 @@ if (currentUser) {
 
 ---
 
+### `storagePersisted: boolean | null` (property)
+
+Whether the browser granted persistent storage. w3pk calls `navigator.storage.persist()` after each register, login and restore without waiting for it. `true` means the origin's storage is exempt from storage-pressure eviction. `null` until the browser answers (Firefox asks the user), or where the API is missing.
+
+Persisted storage still doesn't survive Safari's 7-day cap, clearing site data or private browsing: see [SECURITY.md → Storage durability](./SECURITY.md#storage-durability-what-can-still-wipe-the-wallet).
+
+**Example:**
+
+```typescript
+await w3pk.login()
+if (w3pk.storagePersisted === false) {
+  console.warn('Storage may be evicted: make sure the user has a backup')
+}
+```
+
+---
+
 ### `hasExistingCredential(): Promise<boolean>`
 
 Check if there are existing credentials (wallets) on this device.
@@ -772,6 +802,7 @@ interface SignatureResult {
 - Uses EIP-191 prefix (for EOA accounts)
 - See https://docs.login.xyz for message format
 - Use `createSiweMessage()` helper for proper formatting
+- Not supported in PRIMARY mode (throws): use STANDARD, STRICT or YOLO
 
 **EIP-712 Signing:**
 - Signs structured typed data according to EIP-712 standard
@@ -1336,6 +1367,61 @@ await accountAbstractionContract.verifyWebAuthnSignature({
 
 ---
 
+### `derivePrfSecret(tag: string): Promise<PrfSecret>`
+
+Derive a 32-byte secret bound to the passkey, separate per origin and tag, for an identity in an anonymous protocol or a per-feature encryption key.
+
+It uses the [WebAuthn PRF extension](https://w3c.github.io/webauthn/#prf-extension): the authenticator holds a per-credential secret and releases `PRF(input)` only on a live, user-verified assertion. The secret is never derived from or stored with the mnemonic.
+
+**Parameters:**
+- `tag: string` - Non-empty label without `:`, such as `"zk-identity"`. Case-sensitive.
+
+**Returns:** `PrfSecret`
+
+```typescript
+interface PrfSecret {
+  secret: Uint8Array;    // 32 bytes
+  credentialId: string;  // passkey the secret is bound to
+}
+```
+
+**What happens:**
+1. Prompts for the passkey with `userVerification: "required"`; when logged in, only the current user's passkey is allowed, otherwise the user picks one
+2. Evaluates the PRF at `SHA-256("w3pk-prf-v1:" + origin + ":" + tag)`, with `origin` the normalized current origin (the browser further hashes it with the `"WebAuthn PRF"` context)
+3. Returns `HKDF-SHA256(PRF output, salt "w3pk-prf-secret-v1", info "w3pk-prf-v1:" + origin + ":" + tag)`, 32 bytes
+
+The same passkey, origin and tag always give the same secret. A different tag, origin or passkey gives an unrelated one. Store `credentialId` next to whatever the secret protects: when it changes (a new passkey), so does the secret.
+
+**Example:**
+
+```typescript
+import { PrfUnsupportedError } from 'w3pk'
+
+try {
+  const { secret, credentialId } = await w3pk.derivePrfSecret('zk-identity')
+  // Use the secret, keep it in memory only
+} catch (error) {
+  if (error instanceof PrfUnsupportedError) {
+    // This authenticator can't provide a passkey-bound secret
+  }
+}
+```
+
+**Throws:**
+- `PrfUnsupportedError` (`code: 'PRF_UNSUPPORTED'`, with `credentialId`) if the authenticator returns no PRF output. There is no fallback.
+- `AuthenticationError` if the prompt is cancelled or the passkey isn't available
+- `CryptoError` if `tag` is empty or contains `:`
+
+**Threat model:**
+- **Not in backups.** The secret depends only on the authenticator's PRF, so backup files, recovery phrases, social recovery shares and sync exports don't contain it, and their leak doesn't leak it.
+- **Not stored.** w3pk never writes the secret or the PRF output to localStorage or sessions, and zeroes its copy of the PRF output after the derivation. Each call prompts the user. If the app stores the secret, its storage is the weakest link.
+- **Bound to the passkey, not the wallet.** Restoring the wallet from a backup with a different passkey gives a different secret. The secret survives only as long as the passkey: a synced passkey (iCloud Keychain, Google Password Manager) carries it to other devices, a deleted or device-bound passkey loses it. Anything encrypted under it must be recoverable another way.
+- **Origin separation is w3pk's, not the browser's.** Passkeys are scoped to the RP ID (the hostname), so another origin on the same hostname (another port or scheme) can use the same passkey. The origin in the PRF input keeps `derivePrfSecret()` from giving one origin another's secret, but a script running on such an origin can evaluate the PRF itself with any input. Serve one app per hostname when that matters.
+- **Script on the origin.** Code running on the page (XSS, a compromised dependency) can call `derivePrfSecret()` or the PRF directly and get the secret after the user approves a prompt. User verification bounds it to a user action, not to the app's intent.
+- **Separate from the persistent session key.** That key uses a different PRF input, so no tag gives it.
+
+---
+
 ### `sendTransaction(tx, options?): Promise<TransactionResult>`
 
 Send an on-chain transaction using the wallet derived for the active security mode.
@@ -2243,7 +2329,13 @@ Get comprehensive backup status showing what protects the wallet.
 **Returns:**
 
 ```typescript
+type BackupMethod = 'file' | 'qr' | 'phrase';
+
 interface BackupStatus {
+  hasBackup: boolean;        // a backup file, QR code or confirmed phrase exists
+  evictionRisk: boolean;     // the browser may wipe the wallet: WebKit outside a home-screen app, storage not persisted
+  lastBackupAt?: string;     // ISO 8601 time of the latest backup
+  methods: BackupMethod[];
   passkeySync: PasskeySyncStatus;
   recoveryPhrase: RecoveryPhraseStatus;
   socialRecovery?: SocialRecoveryStatus;
@@ -2251,18 +2343,42 @@ interface BackupStatus {
 }
 ```
 
+Browser storage can be wiped (eviction, Safari's 7-day cap, clearing site data), so a wallet without a backup can be lost for good. While `hasBackup` is `false`, the security score is capped at 20 and its level is `vulnerable`.
+
+`evictionRisk` is computed on each call from `navigator.storage.persisted()` and the display mode: `true` on WebKit (every iOS browser, Safari and other WebKit browsers on desktop) in a tab whose storage is not persisted, `false` in a home-screen app, once storage is persisted, and on Chromium and Firefox.
+
 **Example:**
 
 ```typescript
 const status = await w3pk.getBackupStatus()
-console.log('Security Score:', status.securityScore.score) // 0-100
-console.log('Passkey sync:', status.passkeySync.enabled)
-console.log('Recovery phrase:', status.recoveryPhrase.status)
+if (!status.hasBackup && status.evictionRisk) {
+  showBackupGate() // blocking; on iOS, suggest "Add to Home Screen"
+} else if (!status.hasBackup) {
+  showBackupWarning()
+}
+console.log('Security Score:', status.securityScore.total) // 0-100
+console.log('Level:', status.securityScore.level)
+console.log('Backup methods:', status.methods)
 console.log('Social recovery:', status.socialRecovery?.enabled)
 ```
 
 ---
 
+### `confirmRecoveryPhraseBackup(): Promise<void>`
+
+Record that the user wrote down their recovery phrase. Call it once the user confirms, so `getBackupStatus()` reports `hasBackup: true` with the `phrase` method.
+
+**Example:**
+
+```typescript
+await showRecoveryPhrase()
+if (await userConfirmsPhraseWrittenDown()) {
+  await w3pk.confirmRecoveryPhraseBackup()
+}
+```
+
+---
+
 ### `createBackupFile(encryptionType?: 'password' | 'passkey' | 'hybrid', password?: string): Promise<{ blob: Blob; filename: string }>`
 
 Create simplified backup file for wallet recovery.
@@ -2621,14 +2737,17 @@ console.log('Estimated devices:', capabilities.estimatedDevices)
 
 ---
 
-### `exportForSync(): Promise<{ blob: Blob; filename: string; qrCode?: string }>`
+### `exportForSync(password?: string): Promise<{ blob: Blob; filename: string; qrCode?: string }>`
 
 Export wallet for syncing to another device.
 
-Uses passkey encryption so it works on devices where the passkey is synced.
+Runs a fresh assertion restricted to the current passkey and encrypts the mnemonic with a key derived from its [WebAuthn PRF](https://w3c.github.io/webauthn/#prf-extension) output (`encryptionMethod: 'prf'`). Any device where the passkey synced restores the file with one prompt and no password, including a fresh device.
 
 **Use case:** User wants to sync wallet to another device that has the same passkey.
 
+**Parameters:**
+- `password?: string` - Fallback when the authenticator has no PRF support: the file is then a password backup that names its passkey, to restore with `syncWalletWithPasskey(syncData, password)`
+
 **Returns:**
 
 ```typescript
@@ -2639,7 +2758,11 @@ Uses passkey encryption so it works on devices where the passkey is synced.
 }
 ```
 
-**Security:** Forces fresh authentication
+**File format (`prf`):** `encryptedMnemonic`, `prfSalt` (32 random bytes per file, base64url), `credential: { id, publicKey }`, `username`, `addressChecksum`. Key: HKDF-SHA256 over the PRF output evaluated at `SHA-256("w3pk-prf-sync-v1" || prfSalt)`, then AES-256-GCM. The public key doesn't decrypt the file; a fresh device needs it for `login()` and checks it against the assertion's signature.
+
+**Security:** The PRF assertion is the fresh user verification; with an active session, export takes one prompt.
+
+**Browser support:** PRF works in Chrome 108+ and Safari 17+ / iOS 17+, not in Firefox. Passkeys sync within one ecosystem only (Apple or Google); across ecosystems, use a password backup.
 
 **Example:**
 
@@ -2661,13 +2784,18 @@ if (qrCode) {
 }
 ```
 
+**Throws:**
+- `WalletError` if not logged in
+- `PrfUnsupportedError` if the authenticator returns no PRF output and no `password` was given
+- `AuthenticationError` if the assertion fails or is cancelled
+
 ---
 
 ### `importFromSync(syncData: string | Blob): Promise<{ ethereumAddress: string; success: boolean }>`
 
-Import wallet from another device (sync wallet to this device).
+Import a PRF sync file from `exportForSync()`. No prior `login()` and no password required: one assertion restricted to the file's passkey decrypts it.
 
-**Use case:** User has passkey on both devices, wallet only on one.
+**Use case:** User has the passkey on both devices (synced through iCloud Keychain or Google Password Manager) and the wallet on one. Works on a fresh device with no data for the passkey: the SDK checks the file's public key against the assertion's signature, saves the passkey's metadata, stores the wallet, starts a session and fires `onAuthStateChanged(true, user)`.
 
 **Parameters:**
 - `syncData: string | Blob` - Sync file data
@@ -2684,23 +2812,29 @@ Import wallet from another device (sync wallet to this device).
 **Example:**
 
 ```typescript
-// User must be logged in first
-await w3pk.login()
-
-// Import from sync file
-const syncData = '...' // From file upload or QR scan
+const syncData = '...' // From exportForSync(), by file upload or QR scan
 
 const result = await w3pk.importFromSync(syncData)
 console.log('Wallet synced:', result.ethereumAddress)
 ```
 
+**Throws:**
+- `WalletError` if the file isn't a PRF sync file (use `syncWalletWithPasskey()` for other backups, including `exportForSync(password)`'s fallback)
+- `SyncBootstrapError` with `reason: 'CREDENTIAL_MISMATCH'` if logged in with another passkey than the file's
+- `SyncBootstrapError` with `reason: 'PUBLIC_KEY_MISMATCH'` if the file's public key doesn't match the passkey's signature
+- `AuthenticationError` if the passkey isn't on this device or the prompt is cancelled
+- `PrfUnsupportedError` if the authenticator returns no PRF output
+- `CryptoError` or `Error` if the file was altered (ciphertext, address or address checksum)
+
 ---
 
 ### `syncWalletWithPasskey(backupData: string | Blob, password?: string): Promise<{ mnemonic: string; ethereumAddress: string }>`
 
 Sync wallet to this device using an existing cloud-synced passkey and a backup file. No prior session required.
 
-**Use case:** New device that already has a passkey synced via iCloud/Google Password Manager. The user provides their backup file; the SDK prompts them to select the passkey, decrypts the backup, stores wallet data locally, and starts a session.
+**Use case:** New device that already has a passkey synced via iCloud/Google Password Manager. The user provides their backup file; the SDK prompts them to select the passkey, decrypts the backup, saves the passkey's metadata if this device has none, stores wallet data locally, starts a session and fires `onAuthStateChanged(true, user)`.
+
+A PRF sync file from `exportForSync()` takes no password: it's restored as `importFromSync()` does, with one assertion restricted to its passkey. On a device with no data for the passkey, the other backups that work are password backups made by a logged-in user: they name their passkey (`credential: { id, publicKey }`), and the username comes from the passkey's user handle. In both cases the backup's public key is checked against the assertion's signature.
 
 **Parameters:**
 - `backupData: string | Blob` - Backup file content (JSON string or Blob)
@@ -2708,26 +2842,25 @@ Sync wallet to this device using an existing cloud-synced passkey and a backup f
 
 **Returns:** `{ mnemonic: string; ethereumAddress: string }`
 
-**Supported encryption methods:** `password`, `passkey`, `hybrid`
+**Supported encryption methods:** `prf` and `password` everywhere; `passkey` and `hybrid` only where this device already has the passkey's metadata
 
 **Example:**
 
 ```typescript
-// Passkey-encrypted backup (no password needed)
-const result = await w3pk.syncWalletWithPasskey(backupData)
+const result = await w3pk.syncWalletWithPasskey(backupData, 'MyPassword123!')
 console.log('Synced wallet address:', result.ethereumAddress)
-
-// Password or hybrid backup
-const result2 = await w3pk.syncWalletWithPasskey(backupData, 'MyPassword123!')
-console.log('Synced wallet address:', result2.ethereumAddress)
 ```
 
 **Throws:**
 - `WalletError` if password is required but not provided
-- `WalletError` if passkey public key is not available on this device
 - `WalletError` if backup uses an unknown encryption method
+- `SyncBootstrapError` on a device with no data for the passkey (carries `reason` and `credentialId`):
+  - `'PASSKEY_BACKUP'`: passkey or hybrid backup
+  - `'NO_CREDENTIAL'`: password backup that doesn't name its passkey (made before 0.10.4)
+  - `'CREDENTIAL_MISMATCH'`: the backup names another passkey than the one selected
+  - `'PUBLIC_KEY_MISMATCH'`: the backup's public key doesn't match the passkey's signature
 
-**Note:** Differs from `importFromSync()` in that it does not require a prior `login()` call and accepts any backup encryption method, not just passkey-encrypted sync exports.
+**Note:** Differs from `importFromSync()` in that it also accepts password, passkey and hybrid backups.
 
 ---
 
@@ -2736,7 +2869,7 @@ console.log('Synced wallet address:', result2.ethereumAddress)
 w3pk provides two types of sessions:
 
 1. **In-Memory Sessions** (default): Cached in RAM, cleared on page refresh
-2. **Persistent Sessions** (opt-in): Encrypted in IndexedDB, survives page refresh
+2. **Persistent Sessions** (opt-in): Encrypted in localStorage, survives page refresh
 
 **Security Modes & Persistence:**
 - **STANDARD mode**: Persistent sessions allowed ✅
@@ -2844,14 +2977,14 @@ Enable persistent sessions to maintain user login across page refreshes.
 
 **How it works:**
 1. On login, mnemonic is encrypted with WebAuthn-derived key
-2. Encrypted session stored in IndexedDB
+2. Encrypted session stored in localStorage
 3. On page refresh, session is automatically restored (if not expired)
 4. `requireReauth: true` prompts for biometric on refresh (more secure)
 5. `requireReauth: false` silently restores session (more convenient)
 
 **Security (read the trade-off):**
 - Sessions only persist for STANDARD and YOLO modes; STRICT mode is NEVER persisted
-- Time-limited expiration; origin-isolated via IndexedDB
+- Time-limited expiration; origin-isolated via localStorage
 - ⚠️ The "WebAuthn-derived key" is derived from **public** credential metadata stored in the same browser profile, **not** from an authenticator-held secret. A persistent session is therefore **decryptable by anyone who can read this origin's storage** (malicious extension, XSS exfil, disk image), and it keeps the seed in that state for the whole duration it's enabled. This is a UX-for-security trade-off, not hardware-backed protection.
 - Enabling "Remember Me" does not add a new trust dependency (you already trust your origin's code), it **widens the window** in which a compromise of your origin can reach the seed. Keep `duration` short for higher-value wallets; don't enable on shared/untrusted devices.
 - Full threat model: **[SECURITY.md → At-Rest Encryption](./SECURITY.md#at-rest-encryption-what-it-protects-and-what-it-doesnt)**.
@@ -3389,9 +3522,10 @@ Encrypt data using ML-KEM-1024 (post-quantum KEM) + AES-256-GCM for one or more
 **Returns:**
 ```typescript
 {
+  version: 2;             // Payload format (absent on legacy v1 payloads)
   recipients: Array<{
     publicKey: string;    // Base64 recipient public key (1568 bytes)
-    ciphertext: string;   // Base64 ML-KEM ciphertext for this recipient (1600 bytes)
+    ciphertext: string;   // Base64 ML-KEM ciphertext + AES-KW wrapped key (1608 bytes)
   }>;
   encryptedData: string;  // Base64 AES-encrypted data (shared across all recipients)
   iv: string;             // Base64 initialization vector (12 bytes)
@@ -3887,7 +4021,11 @@ import {
   WalletError,
   CryptoError,
   StorageError,
-  ApiError
+  ApiError,
+  SyncRequiredError,
+  WalletMissingError,
+  SyncBootstrapError,
+  PrfUnsupportedError
 } from 'w3pk'
 ```
 
@@ -3898,18 +4036,33 @@ import {
   - `RegistrationError` - Registration failures
   - `WalletError` - Wallet operations (derivation, signing)
   - `CryptoError` - Cryptographic operations (encryption, decryption)
-  - `StorageError` - Storage operations (IndexedDB)
+  - `StorageError` - Storage operations (localStorage)
   - `ApiError` - API/network errors (RPC, chainlist)
+  - `SyncRequiredError` - `login()`: passkey authenticated, but this device has no credential metadata (`credentialId`)
+  - `WalletMissingError` - `login()`: credential metadata found, but the wallet record is gone (`credentialId`, `ethereumAddress`)
+  - `SyncBootstrapError` - `syncWalletWithPasskey()`, `importFromSync()`: the backup can't set this device up for the passkey (`reason`, `credentialId`)
+  - `PrfUnsupportedError` - `derivePrfSecret()`, `exportForSync()`, `importFromSync()`: the authenticator returned no WebAuthn PRF output (`credentialId`)
 
 ### Error Handling
 
 ```typescript
-import { AuthenticationError, WalletError } from 'w3pk'
+import {
+  AuthenticationError,
+  WalletError,
+  SyncRequiredError,
+  WalletMissingError
+} from 'w3pk'
 
 try {
   await w3pk.login()
 } catch (error) {
-  if (error instanceof AuthenticationError) {
+  if (error instanceof SyncRequiredError) {
+    // Passkey synced to this device, wallet data isn't: ask for the password backup
+    await w3pk.syncWalletWithPasskey(backupFile, password)
+  } else if (error instanceof WalletMissingError) {
+    // Metadata here, wallet record gone: any backup of this passkey restores it
+    await w3pk.syncWalletWithPasskey(backupFile, password)
+  } else if (error instanceof AuthenticationError) {
     console.error('Authentication failed:', error.message)
   } else if (error instanceof WalletError) {
     console.error('Wallet error:', error.message)

package/docs/ARCHITECTURE.md

@@ -105,7 +105,7 @@ interface WebAuthnCredential {
 - Standards: BIP32, BIP39, BIP44, EIP-155
 - Curve: secp256k1 (Bitcoin/Ethereum standard)
 - Algorithm: ECDSA + Keccak-256
-- Storage: IndexedDB (AES-256-GCM encrypted)
+- Storage: localStorage (AES-256-GCM encrypted)
 - Managed by: Application (w3pk)
 
 **Capabilities**:
@@ -231,10 +231,10 @@ STEP 3: Derive Encryption Key
 
 STEP 4: Encrypt & Store
 ┌────────────────────────────┬────────────────────────────┐
-│  localStorage              │  IndexedDB                 │
+│  localStorage              │  localStorage              │
 │  ─────────────             │  ─────────────             │
 │                            │                            │
-│  w3pk_credential_*:        │  Web3PasskeyWallet:        │
+│  w3pk_credential_*:        │  w3pk_wallet_<address>:    │
 │  {                         │  {                         │
 │    id: "hash(abc123)",     │    ethereumAddress,        │
 │    publicKey (plaintext),  │    encryptedMnemonic,      │
@@ -268,9 +268,9 @@ STEP 1: WebAuthn Authentication
 
 STEP 2: Fetch Stored Data
 ┌────────────────────────────┬────────────────────────────┐
-│  localStorage              │  IndexedDB                 │
+│  localStorage              │  localStorage              │
 │                            │                            │
-│  Get by credentialId:      │  Get by credentialId:      │
+│  Get by credentialId:      │  Get by address:           │
 │  → publicKey               │  → encryptedMnemonic       │
 └─────────────┬──────────────┴──────────────┬─────────────┘
               │                             │
@@ -393,15 +393,16 @@ User wants to send 1 ETH
 
 **Why publicKey is plaintext**: It's needed to derive the encryption key. It's the **public** part of the WebAuthn key pair—not sensitive.
 
-### IndexedDB Structure
+### Wallet Storage
 
-**Database**: `Web3PasskeyWallet`
-**Store**: `wallets`
-**Key Path**: `ethereumAddress`
+**Storage**: localStorage, next to the credential metadata, so browser eviction removes both or neither
+**Key**: `w3pk_wallet_<ethereumAddress>`
 **Purpose**: Encrypted wallet storage
 
+Persistent sessions use `w3pk_session_<ethereumAddress>` and backup metadata `w3pk_backups`, in the same localStorage.
+
 ```typescript
-// Example record in IndexedDB
+// Example record in localStorage
 {
   ethereumAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
   encryptedMnemonic: "U2FsdGVkX1+vupppZksvRf...",  // AES-256-GCM blob
@@ -563,7 +564,7 @@ Layer 2: Encryption Key Derivation
 Layer 3: Encrypted Mnemonic Storage
 ┌─────────────────────────────────────┐
 │  ✅ AES-256-GCM encryption          │
-│  ✅ IndexedDB storage               │
+│  ✅ localStorage storage            │
 │  ✅ Cannot decrypt without Layers 1&2│
 └─────────────────────────────────────┘
          ↓ REVEALS
@@ -749,7 +750,7 @@ Passkey (Face ID) → Decrypt mnemonic → Use wallet
 |---------|----------|---------------|------------|
 | **Curve** | P-256 | secp256k1 | N/A (uses AES) |
 | **Purpose** | Authentication | Transactions | Encryption |
-| **Storage** | Secure Enclave | IndexedDB | None (derived) |
+| **Storage** | Secure Enclave | localStorage | None (derived) |
 | **Backup** | iCloud/Google | 12-word phrase | N/A |
 | **Standards** | FIDO2, W3C | BIP32/39/44 | PBKDF2, AES-GCM |
 | **Managed By** | OS | App | App |
@@ -808,7 +809,7 @@ Scenarios:
 }
 ```
 
-### What's in IndexedDB?
+### What's in `w3pk_wallet_<address>`?
 
 ```json
 {

package/docs/BROWSER_COMPATIBILITY.md

@@ -97,6 +97,30 @@ This document details WebAuthn support across browsers, operating systems, and d
 | **VirtualBox/VMs** | No biometric passthrough | Use password fallback |
 | **Remote Desktop** | Biometrics not forwarded | Use local device |
 
+#### 🗑️ **Storage That Can Be Wiped**
+
+The encrypted wallet, persistent sessions and backup metadata live in localStorage, next to the credential metadata, so they are either all there or all gone. The passkey itself lives in the authenticator and survives all of the cases below, but the wallet does not: the mnemonic is random and can't be rebuilt from the passkey. Users need a backup file or the recovery phrase.
+
+| Environment | What happens | Mitigation |
+|-------------|--------------|------------|
+| **Safari (macOS, iOS)** | localStorage deleted after 7 days of browser use without the user interacting with the site | Add the web app to the Home Screen (exempt), keep a backup |
+| **Any browser: clearing site data** | localStorage deleted with cookies and site data | Keep a backup |
+| **Private/Incognito windows** | localStorage discarded when the window closes | Don't use for a long-lived wallet |
+| **Chrome/Firefox under storage pressure** | Origins without persistent storage can be evicted | w3pk calls `navigator.storage.persist()`; check `w3pk.storagePersisted` |
+
+Chrome grants persistent storage from engagement heuristics (bookmarked, installed, frequently visited) without a prompt; Firefox asks the user; Safari doesn't exempt sites from its 7-day cap. See [SECURITY.md → Storage durability](./SECURITY.md#storage-durability-what-can-still-wipe-the-wallet).
+
+`register()` and `getBackupStatus()` return `evictionRisk`, computed on each call:
+
+| Environment | `evictionRisk` |
+|-------------|----------------|
+| **WebKit tab, storage not persisted** (every iOS browser, Safari and other WebKit browsers on desktop) | `true` |
+| **WebKit home-screen app** (`display-mode: standalone` or `navigator.standalone`) | `false` |
+| **WebKit, `navigator.storage.persisted()` is `true`** | `false` |
+| **Chromium, Firefox** | `false` |
+
+Block on a backup while `!hasBackup && evictionRisk`, and show a dismissible banner on `!hasBackup` otherwise. See [Integration Guidelines → Backup & Recovery](./INTEGRATION_GUIDELINES.md#backup--recovery).
+
 ### Hardware Security Keys
 
 | Key Type | CTAP Version | w3pk Support | Release Date |