w3pk 0.10.2 → 0.10.3

package/docs/QUICK_START.md

@@ -26,7 +26,7 @@ Create a new w3pk instance:
 const w3pk = createWeb3Passkey()
 ```
 
-When you instantiate w3pk, the SDK initializes a connection to your browser's IndexedDB for secure local storage and sets up the WebAuthn configuration tailored to your device. 
+When you instantiate w3pk, the SDK uses your browser's localStorage for secure local storage and sets up the WebAuthn configuration tailored to your device. 
 
 It also prepares the session management system with a default duration of 1 hour, meaning you won't be repeatedly prompted for biometric authentication during that time. Everything happens client-side—no server connection is needed, keeping your wallet truly under your control.
 
@@ -45,7 +45,7 @@ console.log('Address:', address)
 
 Registration is where the magic happens. First, w3pk generates a fresh BIP39 mnemonic—a 12-word recovery phrase that serves as the master key to your wallet. Then your device's biometric prompt appears (Face ID, Touch ID, Windows Hello, or similar), creating a WebAuthn credential tied to your hardware. The SDK derives your Ethereum wallet from the mnemonic using the standard BIP44 path (m/44'/60'/0'/0/0), giving you a proper Ethereum address.
 
-Here's the security layer: the mnemonic gets encrypted using AES-GCM-256 with the WebAuthn credential as the encryption key, meaning only your biometric authentication can decrypt it. The encrypted wallet is stored safely in your browser's IndexedDB. To make your experience smooth, w3pk immediately starts a session by caching the decrypted mnemonic in memory for 1 hour, so you won't need to authenticate again right away. Finally, it returns your Ethereum address and username: you're ready to go!
+Here's the security layer: the mnemonic gets encrypted using AES-GCM-256 with the WebAuthn credential as the encryption key, meaning only your biometric authentication can decrypt it. The encrypted wallet is stored in your browser's localStorage, next to the credential metadata. To make your experience smooth, w3pk immediately starts a session by caching the decrypted mnemonic in memory for 1 hour, so you won't need to authenticate again right away. Finally, it returns your Ethereum address and username: you're ready to go!
 
 ### 4. Sign a Message
 
@@ -78,9 +78,9 @@ await w3pk.login()
 console.log('Logged in')
 ```
 
-Login is a beautifully streamlined process. The SDK retrieves your credential ID from IndexedDB and triggers WebAuthn authentication—this is when your biometric prompt appears. Notice there's no username or password to remember; your device recognizes you through your biometric data.
+Login is a beautifully streamlined process. The SDK retrieves your credential ID from localStorage and triggers WebAuthn authentication—this is when your biometric prompt appears. Notice there's no username or password to remember; your device recognizes you through your biometric data.
 
-Once authenticated, w3pk retrieves your encrypted wallet from IndexedDB and uses the WebAuthn signature as the decryption key to unlock your mnemonic. A fresh session starts immediately, caching the decrypted mnemonic in memory for 1 hour (this is configurable and balances security with user experience—long enough to avoid annoying prompts, short enough to stay secure). The method returns your user info (address and username), and you're good to go. For the next hour, all wallet operations will use this cached session without bothering you with repeated biometric prompts—smooth, secure, and user-friendly.
+Once authenticated, w3pk retrieves your encrypted wallet from localStorage and uses the WebAuthn signature as the decryption key to unlock your mnemonic. A fresh session starts immediately, caching the decrypted mnemonic in memory for 1 hour (this is configurable and balances security with user experience—long enough to avoid annoying prompts, short enough to stay secure). The method returns your user info (address and username), and you're good to go. For the next hour, all wallet operations will use this cached session without bothering you with repeated biometric prompts—smooth, secure, and user-friendly.
 
 ## Complete Example
 

package/docs/RECOVERY.md

@@ -58,6 +58,30 @@ Before diving into the recovery system, it's crucial to understand the differenc
 
 ---
 
+## 🚦 Backup Status
+
+Browser storage can be wiped (eviction, Safari's 7-day cap, clearing site data). Without a backup, the wallet is then lost for good, so ask for one right after registration and warn while none exists.
+
+```typescript
+const { hasBackup } = await sdk.register({ username: 'alice' });
+
+if (!hasBackup) {
+  // "Back up now": download a backup file...
+  const { blob, filename } = await sdk.createBackupFile('password', password);
+  // ...or show the recovery phrase, then record the user's confirmation
+  await sdk.confirmRecoveryPhraseBackup();
+}
+
+const status = await sdk.getBackupStatus();
+status.hasBackup;     // true once a backup file, QR code or confirmed phrase exists
+status.lastBackupAt;  // ISO 8601 time of the latest backup
+status.methods;       // e.g. ['file', 'phrase']
+```
+
+While `hasBackup` is `false`, the security score is capped at 20 and its level is `vulnerable`. Backups are recorded per wallet, in localStorage on this device.
+
+---
+
 ## 🎯 Backup File Format
 
 All workflows use the same universal format:
@@ -478,6 +502,16 @@ const { blob, filename } = await w3pk.createBackupFile('passkey');
 const { blob, filename } = await w3pk.createBackupFile('hybrid', password);
 ```
 
+### Backup Status
+
+```typescript
+// Record that the user wrote down the recovery phrase
+await w3pk.confirmRecoveryPhraseBackup();
+
+// { hasBackup, lastBackupAt, methods, ..., securityScore }
+const status = await w3pk.getBackupStatus();
+```
+
 ### Restore from Backup
 
 ```typescript
@@ -621,7 +655,7 @@ src/backup/
 ├── backup-file.ts              # Main backup orchestration
 ├── types.ts                    # TypeScript interfaces
 ├── encryption.ts               # PBKDF2 + AES-256-GCM utilities
-└── storage.ts                  # IndexedDB for metadata
+└── storage.ts                  # localStorage for metadata
 
 src/sync/
 ├── backup-sync.ts              # DeviceSyncManager class

package/docs/SECURITY.md

@@ -31,22 +31,22 @@ key = PBKDF2( SHA-256("w3pk-v4:" + credentialId + ":" + publicKey),
 
 Every input to that key lives in the browser profile:
 
-- `credentialId` — stored next to the ciphertext in **IndexedDB**
+- `credentialId` — stored next to the ciphertext in **localStorage**
 - `publicKey` — stored in **plaintext in localStorage** (it's needed for key derivation)
 - `salt` — a **constant string** in the open-source code
 
-So an attacker who can read this origin's localStorage **and** IndexedDB — a malicious browser extension, a one-shot XSS that exfiltrates storage, a disk image of an unlocked device, or a Time Machine / cloud backup of the browser profile — can recompute the key and decrypt the seed **offline, with no biometric/PIN prompt and without ever calling the SDK.** The prompt gates SDK control flow (a UX and anti-casual-misuse boundary), not the cryptography at rest.
+So an attacker who can read this origin's localStorage — a malicious browser extension, a one-shot XSS that exfiltrates storage, a disk image of an unlocked device, or a Time Machine / cloud backup of the browser profile — can recompute the key and decrypt the seed **offline, with no biometric/PIN prompt and without ever calling the SDK.** The prompt gates SDK control flow (a UX and anti-casual-misuse boundary), not the cryptography at rest.
 
-**What at-rest encryption does buy you:** protection against a wallet blob that leaks *in isolation* (e.g. only the IndexedDB object, without localStorage's public key) and against casual inspection. It is **not** a defense against read access to the full browser profile. The [Threat Model](#threat-model) section has the per-scenario matrix.
+**What at-rest encryption does buy you:** protection against a wallet record that leaks *in isolation* (e.g. only the `w3pk_wallet_<address>` entry, without the credential record's public key) and against casual inspection. It is **not** a defense against read access to the full browser profile. The [Threat Model](#threat-model) section has the per-scenario matrix.
 
 ### "Remember Me" (persistent sessions): PRF-keyed, renewed at every real login
 
-`persistentSession.enabled: true` stores the encrypted mnemonic in IndexedDB so the user isn't prompted on every page refresh. Unlike wallet storage, the persistent-session blob is **not** encrypted under a public-data-derived key. It is encrypted under a key derived (HKDF-SHA256) from the **WebAuthn PRF extension output** — a per-credential secret the authenticator releases only during a user-verified (biometric/PIN) assertion. Nothing stored on disk can recompute it. Every real login re-evaluates the PRF (with a fixed input, so the output is deterministic per credential) and re-keys the blob; the session expiry *is* the renewal boundary.
+`persistentSession.enabled: true` stores the encrypted mnemonic in localStorage so the user isn't prompted on every page refresh. Unlike wallet storage, the persistent-session blob is **not** encrypted under a public-data-derived key. It is encrypted under a key derived (HKDF-SHA256) from the **WebAuthn PRF extension output** — a per-credential secret the authenticator releases only during a user-verified (biometric/PIN) assertion. Nothing stored on disk can recompute it. Every real login re-evaluates the PRF (with a fixed input, so the output is deterministic per credential) and re-keys the blob; the session expiry *is* the renewal boundary.
 
 The at-rest guarantee then depends on `requireReauth`:
 
 - **`requireReauth: true` (default):** the key is **never stored**. Every restore re-derives it from a live assertion's PRF output. A storage-read attacker (extension, storage-exfiltrating XSS, disk image, cloud backup of the profile) gets ciphertext that cannot be decrypted without the physical authenticator — the blob is hardware-bound at rest.
-- **`requireReauth: false` (silent "Remember Me"):** the PRF-derived key is stored alongside the blob as a **non-extractable `CryptoKey`**, so restore works without a prompt. Scripts (including XSS) can *use* it while it lives but can never read its bytes, and it cannot be recomputed from any stored strings. The honest limit: an attacker who copies the **full browser profile** at the storage-engine level carries the key material with it. Silent restore fundamentally requires a usable key on disk; this is the strongest form it can take.
+- **`requireReauth: false` (silent "Remember Me"):** the PRF-derived key is stored as base64url next to the blob, so restore works without a prompt; it is re-imported as a non-extractable `CryptoKey` before use. Anyone who can read this origin's localStorage (XSS, an extension, a disk image or profile backup) can decrypt the blob. This is less of a change than it sounds: when the key was a non-extractable `CryptoKey` in IndexedDB, script on the origin could already *use* it to decrypt, and the browser wrote its raw bytes to the profile on disk. Silent restore fundamentally requires a usable key at rest. The [cross-origin wallet](https://github.com/w3hc/w3pk/issues/156) moves this storage out of the host app's origin, so script on the host page can no longer read it.
 - **No PRF support** (older authenticators, some browser/OS combos): persistent sessions are **not stored at all** — the device gets in-memory sessions only. There is deliberately no fallback to weaker encryption.
 
 What "Remember Me" still changes is the **exposure window**, not the trust model: a compromise of the already-trusted origin (XSS, a malicious npm dependency, a compromised script/CDN) can use the live session *any time within the configured duration*, including while the tab is idle and across browser restarts — instead of only while the wallet is actively in use.
@@ -58,6 +58,21 @@ What "Remember Me" still changes is the **exposure window**, not the trust model
 - `requireReauth: true` (default) still prompts on page refresh and keeps the blob hardware-bound; `requireReauth: false` restores silently for the whole duration.
 - Do not enable it on shared or untrusted devices.
 
+### Storage durability: what can still wipe the wallet
+
+The encrypted wallet, persistent sessions and backup metadata live in localStorage, next to the credential metadata. Browsers evict or clear an origin's storage as a whole or by storage type, so they are either all there or all gone: a passkey is never left logging in to a missing wallet. Before v0.10.3 the wallet lived in IndexedDB, and Chrome's storage-pressure eviction could delete it while keeping the credential in localStorage, leaving a wallet that could not be rebuilt from the passkey.
+
+After register, login and restore, w3pk calls `navigator.storage.persist()`. `w3pk.storagePersisted` reports the answer (`null` until the browser answers, or where the API is missing). Persisted storage is exempt from storage-pressure eviction.
+
+What still wipes localStorage, and with it the wallet:
+
+- **Safari's 7-day cap** on script-writable storage: Safari (macOS and iOS) deletes localStorage for a site the user hasn't interacted with for 7 days of browser use. Web apps added to the Home Screen are exempt.
+- **Clearing site data**: "Clear browsing data", site settings, or developer tools.
+- **Private browsing**: storage is discarded when the private window closes.
+- **Storage-pressure eviction** in browsers that don't grant persistence: Chrome grants it from engagement heuristics and Firefox asks the user, so `storagePersisted` may be `false`.
+
+The mnemonic is random, so it cannot be rebuilt from the passkey. Users need a backup file or the recovery phrase to survive any of the above (see [RECOVERY.md](./RECOVERY.md)).
+
 ### Origin / hostname / URL scoping
 
 What the credential and stored data are bound to — three *different* scopes, and none of them is the full URL:
@@ -383,7 +398,7 @@ console.assert(
 
 ### ⚠️ NOT Protected Against
 
-1. **Full browser-profile read access** - An attacker who can read this origin's localStorage **and** IndexedDB derives the key and decrypts the seed offline, with no prompt (see [At-Rest Encryption](#at-rest-encryption-what-it-protects-and-what-it-doesnt))
+1. **Full browser-profile read access** - An attacker who can read this origin's localStorage derives the key and decrypts the seed offline, with no prompt (see [At-Rest Encryption](#at-rest-encryption-what-it-protects-and-what-it-doesnt))
 2. **Malicious extension / XSS exfil / disk image / profile backup** - All are forms of the above storage-read attack
 3. **Compromised origin code** - XSS, a malicious dependency, or a compromised CDN runs *as* your origin and can use an active or persistent session
 4. **Physical coercion** - Forcing the user to authenticate
@@ -425,11 +440,11 @@ Understanding w3pk's security boundaries is critical for proper deployment. The
 **How it works:**
 - Wallet encrypted with AES-256-GCM
 - Key derived from credential ID + public key (PBKDF2, 210k iterations)
-- Requires both localStorage (metadata) AND IndexedDB (encrypted wallet)
+- Requires both the credential record and the wallet record from localStorage
 
 **Limitations:**
 - **Key is deterministic** - same metadata = same key
-- An attacker with BOTH localStorage AND IndexedDB can decrypt offline
+- An attacker with read access to localStorage can decrypt offline
 - Does NOT require fresh authentication to derive the key
 - Protection is authentication-gating by SDK, not cryptographic impossibility
 
@@ -1312,17 +1327,25 @@ If you discover a security vulnerability in w3pk, please report it responsibly:
 - Attempt to exploit in production systems
 
 **Do:**
-- Email security details to the maintainers (see README.md)
+- Report privately via [GitHub Security Advisories](https://github.com/w3hc/w3pk/security/advisories/new)
 - Provide detailed reproduction steps
 - Wait for confirmation before public disclosure
 - Follow responsible disclosure timeline (typically 90 days)
 
 **We will:**
-- Acknowledge receipt within 48 hours
+- Acknowledge receipt within 48 hours (within 24 hours for a vulnerability reported as actively exploited)
 - Investigate and provide updates
 - Work on a fix and coordinate disclosure
 - Credit you in security advisories (if desired)
 
+### Coordinated Disclosure and Downstream Compliance (EU Cyber Resilience Act)
+
+w3pk is FOSS (GPL-3.0) published outside the course of a commercial activity, which keeps it outside direct CRA "manufacturer" obligations. Applications that embed w3pk and are placed on the EU market commercially are generally the "manufacturer" under the CRA, and carry its vulnerability-handling duties — including the 24-hour early warning and 72-hour report to ENISA/CSIRTs for an actively exploited vulnerability, once the relevant CRA provisions apply.
+
+The acknowledgment timeline above exists to support that: a fast, accurate advisory from us is what lets a downstream integrator meet their own reporting clock. If you are shipping a commercial product built on w3pk, treat our GitHub Security Advisories as your upstream source and don't wait on us past those windows — file your own report on the timeline the CRA requires and update it as we provide details.
+
+**Outside the EU:** no direct equivalent imposes the same fixed vulnerability-reporting clock on a wallet SDK. The US has no mandatory product-security law comparable to the CRA — the closest analogue, the FCC's Cyber Trust Mark, is a voluntary IoT label; sector-specific rules (the SEC's 4-business-day incident disclosure, CISA's CIRCIA reporting) apply to public companies and critical-infrastructure operators, not FOSS maintainers or typical wallet integrators. China's amended Cybersecurity Law (effective January 1, 2026) tightens incident-reporting timelines and adds personal liability for responsible officers, but it is a data/incident-security regime, not a CRA-style product certification, and applies to entities operating in China rather than to this project. Integrators distributing into those markets should check their own obligations under those regimes separately; this section covers the EU CRA specifically because it is the one with reporting deadlines that reach this project's disclosure process.
+
 ## How It Works
 
 ### 1. Encryption Key Derivation
@@ -1378,17 +1401,17 @@ const encryptionKey = await crypto.subtle.deriveKey(
 **Important security properties (read honestly):**
 
 - The encryption key is **deterministic** - the same credential metadata always produces the same key.
-- Both key inputs live in the browser profile: `credentialId` in IndexedDB, `publicKey` in plaintext in localStorage, and the salt is a constant in the source. **An attacker who can read this origin's storage can derive the key and decrypt the seed offline.**
+- Both key inputs live in the browser profile: `credentialId` next to the ciphertext and `publicKey` in plaintext, both in localStorage, and the salt is a constant in the source. **An attacker who can read this origin's storage can derive the key and decrypt the seed offline.**
 - The biometric/PIN prompt is an **SDK control-flow gate**, not a cryptographic barrier. It stops someone from driving *your SDK* without authenticating; it does **not** stop someone who bypasses the SDK and decrypts the files directly.
 - This is **not** signature-based or PRF-based encryption — the key is not bound to any authenticator-held secret.
 
 **What an attacker with storage read access can actually do:**
 
 ```typescript
-// Attacker has copied this origin's localStorage + IndexedDB
-const stolenCredentialId  = "..."   // from IndexedDB (next to the ciphertext)
-const stolenPublicKey     = "..."   // from localStorage (plaintext)
-const stolenEncryptedSeed = "..."   // from IndexedDB
+// Attacker has copied this origin's localStorage
+const stolenCredentialId  = "..."   // from w3pk_wallet_<address> (next to the ciphertext)
+const stolenPublicKey     = "..."   // from w3pk_credential_<id> (plaintext)
+const stolenEncryptedSeed = "..."   // from w3pk_wallet_<address>
 
 // Recompute the key from public metadata — no authenticator, no prompt
 const key = deriveEncryptionKeyFromWebAuthn(stolenCredentialId, stolenPublicKey)
@@ -1417,7 +1440,7 @@ The only thing PBKDF2's 210k iterations add here is a mild slowdown; since the i
 }
 ```
 
-#### IndexedDB (Encrypted Wallet)
+#### LocalStorage (Encrypted Wallet, `w3pk_wallet_<address>`)
 ```json
 {
   "ethereumAddress": "0x1234...5678",
@@ -1579,9 +1602,8 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 │  └────────────────────────────────────────────────────────┘ │
 │                                                              │
 │  ┌────────────────────────────────────────────────────────┐ │
-│  │ IndexedDB (Origin-Scoped)                              │ │
-│  │ Database: w3pk                                          │ │
-│  │ Store: wallets                                          │ │
+│  │ localStorage (Origin-Scoped)                           │ │
+│  │ Key: w3pk_wallet_<address>                             │ │
 │  │                                                          │ │
 │  │ {                                                        │ │
 │  │   "ethereumAddress": "0x1234...",     // PUBLIC        │ │
@@ -1592,7 +1614,7 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 │  │                                                          │ │
 │  │ ⚠️  Encrypted mnemonic requires decryption key          │ │
 │  │ ⚠️  Key can be derived from localStorage metadata       │ │
-│  │ ⚠️  Both needed for offline decryption                  │ │
+│  │ ⚠️  Both records needed for offline decryption          │ │
 │  └────────────────────────────────────────────────────────┘ │
 │                                                              │
 │  ┌────────────────────────────────────────────────────────┐ │
@@ -1635,17 +1657,13 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 │  │ File System (Browser Profile Directory)                │ │
 │  │                                                          │ │
 │  │ ~/Library/Application Support/Google/Chrome/Default/   │ │
-│  │   ├─ Local Storage/                                    │ │
-│  │   │   └─ https_example.com_0.localstorage              │ │
-│  │   │       → Contains credential metadata (plaintext)   │ │
-│  │   │                                                      │ │
-│  │   └─ IndexedDB/                                        │ │
-│  │       └─ https_example.com_0/w3pk/                     │ │
-│  │           → Contains encrypted wallet                   │ │
+│  │   └─ Local Storage/                                    │ │
+│  │       └─ https_example.com_0.localstorage              │ │
+│  │           → Credential metadata and encrypted wallet   │ │
 │  │                                                          │ │
 │  │ ⚠️  Files stored on disk (not encrypted by browser)     │ │
 │  │ ⚠️  OS-level encryption (FileVault/BitLocker) needed    │ │
-│  │ ⚠️  Attacker with file access can copy both             │ │
+│  │ ⚠️  Attacker with file access can copy all of it        │ │
 │  └────────────────────────────────────────────────────────┘ │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
@@ -1654,7 +1672,7 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 #### Browser Security Mechanisms
 
 **Origin Isolation:**
-- localStorage and IndexedDB are **automatically scoped** to origin
+- localStorage is **automatically scoped** to origin
 - `https://example.com` cannot access `https://attacker.com` storage
 - Even subdomains are isolated: `app.example.com` ≠ `example.com`
 - Protocol matters: `http://example.com` ≠ `https://example.com`
@@ -1688,7 +1706,7 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 | Storage Layer | What's Stored | Protection | Attack Surface |
 |---------------|---------------|------------|----------------|
 | **localStorage** | Credential metadata (public) | Origin isolation | ⚠️ XSS, file access |
-| **IndexedDB** | Encrypted wallet | Origin isolation + AES-256-GCM | ⚠️ XSS, file access + decryption |
+| **localStorage** | Encrypted wallet, persistent sessions | Origin isolation + AES-256-GCM | ⚠️ XSS, file access + decryption |
 | **Memory** | Plaintext mnemonic (during session) | Process isolation (weak) | ❌ XSS, memory dumps |
 | **Secure Enclave** | WebAuthn private key | Hardware protection | ✅ Very strong (HW attacks only) |
 | **File System** | Browser profile directory | OS permissions | ⚠️ Malware, physical access |
@@ -1707,7 +1725,7 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 8. SDK encrypts mnemonic with AES-256-GCM
 9. SDK stores:
    - localStorage: credentialId, publicKey, address (plaintext)
-   - IndexedDB: encryptedMnemonic (ciphertext)
+   - localStorage: encryptedMnemonic (ciphertext)
 10. Secure Enclave stores: privateKey (hardware-protected)
 ```
 
@@ -1720,7 +1738,7 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 5. Browser returns: signature
 6. SDK verifies signature matches publicKey
 7. SDK derives encryption key from credentialId + publicKey
-8. SDK decrypts wallet from IndexedDB
+8. SDK decrypts wallet from localStorage
 9. SDK stores plaintext mnemonic in memory (session)
 10. Session expires after configured duration
 ```
@@ -1751,24 +1769,20 @@ Understanding where w3pk stores data and how browser security mechanisms protect
 **Chrome/Chromium (macOS):**
 ```
 ~/Library/Application Support/Google/Chrome/Default/
-  ├─ Local Storage/leveldb/
-  │   └─ https_example.com_0.localstorage
-  └─ IndexedDB/
-      └─ https_example.com_0/
+  └─ Local Storage/leveldb/
+      └─ https_example.com_0.localstorage
 ```
 
 **Chrome/Chromium (Windows):**
 ```
 %LOCALAPPDATA%\Google\Chrome\User Data\Default\
-  ├─ Local Storage\leveldb\
-  └─ IndexedDB\
+  └─ Local Storage\leveldb\
 ```
 
 **Firefox (macOS):**
 ```
 ~/Library/Application Support/Firefox/Profiles/<profile>/
-  ├─ webappsstore.sqlite  (localStorage)
-  └─ storage/default/https+++example.com/  (IndexedDB)
+  └─ storage/default/https+++example.com/ls/  (localStorage)
 ```
 
 **Safari (macOS):**
@@ -2020,7 +2034,7 @@ await w3pk.deriveWallet(1)      // ✅ Prompts for biometric (session expired)
 w3pk supports **two types of sessions** (v0.8.2+):
 
 1. **In-Memory Sessions** (default): RAM-only, 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
 
 **In-Memory Session (default):**
 - ✅ Decrypted mnemonic cached in RAM only
@@ -2031,10 +2045,10 @@ w3pk supports **two types of sessions** (v0.8.2+):
 - ✅ Cleared when browser tab closes
 
 **Persistent Session (opt-in — "Remember Me"):**
-- Mnemonic encrypted in IndexedDB under a **WebAuthn-PRF-derived key** (HKDF-SHA256 of the authenticator's per-credential PRF secret); survives page refresh for the configured duration
+- Mnemonic encrypted in localStorage under a **WebAuthn-PRF-derived key** (HKDF-SHA256 of the authenticator's per-credential PRF secret); survives page refresh for the configured duration
 - Re-keyed at every real (prompted) login — the session expiry is the renewal boundary
 - `requireReauth: true`: the key is never stored; every restore re-derives it from a live user-verified assertion (blob is hardware-bound at rest)
-- `requireReauth: false`: the key is stored as a **non-extractable `CryptoKey`** for silent restore — usable by scripts, never readable, not recomputable from stored data
+- `requireReauth: false`: the key is stored as base64url next to the blob for silent restore — readable by anything that can read this origin's localStorage, until the [cross-origin wallet](https://github.com/w3hc/w3pk/issues/156) moves it out of the host app's origin
 - Requires a PRF-capable authenticator; without PRF, no persistent session is stored (in-memory only, no weaker fallback)
 - Only for STANDARD and YOLO modes; **NEVER** persisted for STRICT mode
 - Time-limited expiration; cleared on logout / `clearSession()`
@@ -2045,7 +2059,7 @@ w3pk supports **two types of sessions** (v0.8.2+):
 
 **Security properties:**
 - Default (in-memory) sessions exist **only in RAM** - never written to disk
-- Persistent sessions are keyed to the authenticator hardware via the PRF extension — a storage-read attacker cannot recompute the key from anything on disk (with `requireReauth: false`, the residual risk is a full browser-profile copy carrying the non-extractable key material at the storage-engine level; see [At-Rest Encryption → "Remember Me"](#at-rest-encryption-what-it-protects-and-what-it-doesnt))
+- Persistent sessions are keyed to the authenticator hardware via the PRF extension — a storage-read attacker cannot recompute the key from anything on disk (except with `requireReauth: false`, where the key is stored next to the blob; see [At-Rest Encryption → "Remember Me"](#at-rest-encryption-what-it-protects-and-what-it-doesnt))
 - Automatically cleared after expiration; cleared on logout (both RAM and persistent)
 - STRICT mode **always** requires fresh authentication (no persistence)
 
@@ -2843,7 +2857,6 @@ await w3pk.login()
 
 The attacker **cannot** use your `example.com` credential even if they:
 - Copy your localStorage data
-- Copy your IndexedDB data
 - Trick you into visiting their site
 - Use an identical UI
 
@@ -2854,7 +2867,6 @@ The browser enforces that credentials for `example.com` can only be used on `exa
 ```typescript
 // Browser storage is automatically scoped by origin
 localStorage  // Scoped to "https://example.com"
-IndexedDB     // Scoped to "https://example.com"
 
 // A different origin cannot access this storage
 // - https://attacker.com → different origin
@@ -2955,8 +2967,8 @@ const w3pk = createWeb3Passkey({
   "createdAt": 1234567890
 }
 
-// IndexedDB (origin-scoped by browser)
-// Store: wallets
+// localStorage (origin-scoped by browser)
+// Key: w3pk_wallet_<address>
 {
   "ethereumAddress": "0x1234...",
   "encryptedMnemonic": "v1kT...",  // AES-GCM encrypted
@@ -2973,9 +2985,8 @@ const w3pk = createWeb3Passkey({
 
 **Security properties:**
 
-1. **localStorage**: Origin-scoped by browser (cannot access from different origin)
-2. **IndexedDB**: Origin-scoped by browser + encrypted with WebAuthn signature
-3. **Authenticator**: RP ID-bound + hardware-protected
+1. **localStorage**: Origin-scoped by browser (cannot access from different origin); the wallet is also encrypted under a key derived from the credential metadata
+2. **Authenticator**: RP ID-bound + hardware-protected
 
 ### Common Questions
 
@@ -3079,10 +3090,6 @@ Modern authenticators (TouchID, Windows Hello, YubiKey) have **built-in secure s
 │  │ • Username                       │    │
 │  │ • Public key (safe)              │    │
 │  │ • Ethereum address              │    │
-│  └─────────────────────────────────┘    │
-│                                          │
-│  IndexedDB                               │
-│  ┌─────────────────────────────────┐    │
 │  │ • Encrypted wallet              │    │
 │  │ • Credential ID                 │    │
 │  └─────────────────────────────────┘    │
@@ -3138,7 +3145,7 @@ Modern authenticators (TouchID, Windows Hello, YubiKey) have **built-in secure s
 - ❌ **NOT** the wallet mnemonic
 
 **The wallet mnemonic is stored:**
-- In browser IndexedDB (encrypted)
+- In browser localStorage (encrypted)
 - Can only be decrypted with WebAuthn signature
 - Requires fresh biometric authentication
 
@@ -3598,7 +3605,7 @@ console.log('Write this down:', mnemonic)
 | Best for | Convenience + Security | General use | High-value holdings |
 
 **\*File access = theft?**
-- **w3pk:** Can decrypt mnemonic with localStorage + IndexedDB. Requires device encryption for full protection.
+- **w3pk:** Can decrypt mnemonic with localStorage. Requires device encryption for full protection.
 - **MetaMask:** Can decrypt vault with password. Weak passwords are vulnerable to brute force.
 - **Hardware Wallet:** Private keys never leave device. File access doesn't help attacker.
 
@@ -3792,7 +3799,7 @@ w3pk's security model combines **WebAuthn authentication** with **deterministic
 An attacker would need different things depending on their goal:
 
 **To decrypt the wallet offline (outside w3pk):**
-- Access to browser storage files (localStorage + IndexedDB)
+- Access to browser storage files (localStorage)
 - Can then import mnemonic into any wallet
 
 **To use the wallet via w3pk SDK:**