w3pk 0.10.2 → 0.10.4

package/docs/INTEGRATION_GUIDELINES.md

@@ -36,13 +36,13 @@ await w3pk.getAddress()
 
 ### Don't Import Internal Classes
 
-Internal implementation classes like `WalletSigner`, `SessionManager`, `IndexedDBWalletStorage`, etc. are **not part of the public API** and may change without notice:
+Internal implementation classes like `WalletSigner`, `SessionManager`, `LocalStorageWalletStorage`, etc. are **not part of the public API** and may change without notice:
 
 ```typescript
 // ❌ Don't do this - internal APIs
 import { WalletSigner } from 'w3pk/wallet/signing'
 import { SessionManager } from 'w3pk/core/session'
-import { IndexedDBWalletStorage } from 'w3pk/wallet/storage'
+import { LocalStorageWalletStorage } from 'w3pk/wallet/storage'
 
 // ✅ Do this instead - public SDK API
 import { createWeb3Passkey } from 'w3pk'
@@ -90,9 +90,9 @@ const auth2 = await w3pk.signAuthorization({
 ```typescript
 // ❌ Don't use internal WalletSigner class directly
 import { WalletSigner } from 'w3pk/wallet/signing'
-import { IndexedDBWalletStorage } from 'w3pk/wallet/storage'
+import { LocalStorageWalletStorage } from 'w3pk/wallet/storage'
 
-const storage = new IndexedDBWalletStorage()
+const storage = new LocalStorageWalletStorage()
 const signer = new WalletSigner(storage)
 
 // This bypasses session management and requires manual credential handling
@@ -120,6 +120,7 @@ await signer.signAuthorization(
 
 **Backup & Recovery:**
 - `createBackupFile()` - Create encrypted backup
+- `confirmRecoveryPhraseBackup()` - Record that the user wrote down the recovery phrase
 - `restoreFromBackupFile()` - Restore from backup
 - `setupSocialRecovery()` - Split backup among guardians
 - `recoverFromGuardians()` - Recover from guardian shares
@@ -696,6 +697,8 @@ const result = await w3pk.signMessage(message, {
 })
 ```
 
+SIWE works in STANDARD, STRICT and YOLO modes; PRIMARY mode throws. Get the address with the same mode and tag you sign with. In production, have the server issue the nonce and tie it to the address, as EIP-4361 recommends; see [examples/siwe-login.ts](../examples/siwe-login.ts).
+
 **Use for:**
 - Web3 authentication flows
 - App login
@@ -1220,23 +1223,46 @@ async function promptBackupOptions() {
 
 ### Allow Users Multiple Backup Options
 
-**Critical:** Users should set up at least one backup method immediately after registration.
+**Critical:** Users should set up at least one backup method immediately after registration. Browser storage can be wiped (eviction, Safari's 7-day cap, clearing site data), and a wallet without a backup is then lost for good.
+
+`evictionRisk` tells you whether this browser is likely to wipe the wallet: it is `true` on WebKit (every iOS browser, Safari and other WebKit browsers on desktop) in a tab whose storage is not persisted, and `false` in a home-screen app, once storage is persisted, and on Chromium and Firefox. Use it to choose how hard to push:
+
+- `!hasBackup && evictionRisk`: block the app until the user backs up
+- `!hasBackup` otherwise: show a dismissible banner
+- On iOS, also suggest "Add to Home Screen": home-screen apps are exempt from Safari's 7-day cap
 
 ```typescript
-// ✅ Provide multiple backup options
-async function setupBackups() {
-  const status = await w3pk.getBackupStatus()
+// ✅ Ask for a backup right after registration
+const { hasBackup, evictionRisk } = await w3pk.register({ username })
 
-  console.log('Security Score:', status.securityScore.score)
-  console.log('Has passkey sync:', status.securityScore.hasPasskeyBackup)
-  console.log('Has encrypted backup:', status.securityScore.hasEncryptedBackup)
-  console.log('Has social recovery:', status.securityScore.hasSocialRecovery)
+if (!hasBackup) {
+  // Blocking where the browser may wipe the wallet, dismissible otherwise
+  // "Back up now": a backup file, or the recovery phrase written down
+  const choice = await showBackupNowPrompt({ blocking: evictionRisk })
 
-  // Warn if security score is low
-  if (status.securityScore.score < 60) {
-    showBackupWarning()
+  if (choice === 'file') {
+    const { blob, filename } = await w3pk.createBackupFile('password', password)
+    downloadFile(blob, filename)
+  } else if (choice === 'phrase') {
+    await showRecoveryPhrase()
+    await w3pk.confirmRecoveryPhraseBackup()
   }
 }
+
+// ✅ Keep warning while no backup exists
+async function checkBackup() {
+  const status = await w3pk.getBackupStatus()
+
+  if (!status.hasBackup && status.evictionRisk) {
+    showBackupGate() // blocking; on iOS, suggest "Add to Home Screen"
+  } else if (!status.hasBackup) {
+    showBackupWarning() // the score is capped at 20 ('vulnerable')
+  }
+
+  console.log('Security Score:', status.securityScore.total)
+  console.log('Backup methods:', status.methods) // 'file' | 'qr' | 'phrase'
+  console.log('Last backup:', status.lastBackupAt)
+}
 ```
 
 ### Three-Layer Backup Strategy
@@ -1252,7 +1278,7 @@ Encourage users to enable multiple backup methods:
 // - Microsoft Account (Windows/Edge)
 
 const status = await w3pk.getBackupStatus()
-if (status.securityScore.hasPasskeyBackup) {
+if (status.passkeySync.enabled) {
   console.log('✅ Passkey synced to cloud')
 }
 ```
@@ -1316,11 +1342,10 @@ async function setupSocialRecovery() {
 // Check backup status regularly
 async function checkBackupReminder() {
   const status = await w3pk.getBackupStatus()
-  const daysSinceRegistration = calculateDaysSince(status.createdAt)
+  const daysSinceRegistration = calculateDaysSince(registeredAt) // tracked by your app
 
   // Remind users who haven't set up backup
-  if (!status.securityScore.hasEncryptedBackup &&
-      !status.securityScore.hasSocialRecovery) {
+  if (!status.hasBackup) {
 
     if (daysSinceRegistration === 1) {
       showBackupReminder('urgent')
@@ -1413,7 +1438,7 @@ const strictWallet = await w3pk.deriveWallet('STRICT')
 
 **Persistent Session Security:**
 - STANDARD / YOLO: persistent sessions allowed. STRICT: ❌ NEVER allowed.
-- Time-limited expiration; origin-isolated via IndexedDB.
+- Time-limited expiration; origin-isolated via localStorage.
 - ⚠️ The at-rest key is derived from **public** credential metadata in the same browser profile, not an authenticator secret — a persistent session is **decryptable by anyone who can read this origin's storage**, for the whole duration it's enabled. "Remember Me" is a UX-for-security trade-off that widens the exposure window; it does not add a new trust dependency beyond the origin-code integrity you already rely on. Keep the duration short for higher-value wallets and don't enable on shared devices.
 - Decide this deliberately against your threat model: **[SECURITY.md → At-Rest Encryption](./SECURITY.md#at-rest-encryption-what-it-protects-and-what-it-doesnt)**.
 

package/docs/PORTABILITY.md

@@ -9,10 +9,12 @@ This guide explains how to move, backup, and link your W3PK wallet across differ
 - [For End-Users](#for-end-users)
   - [Linking an External Wallet (MetaMask, etc.)](#linking-an-external-wallet-metamask-etc)
   - [Creating and Restoring Backups](#creating-and-restoring-backups)
+  - [Moving Your Wallet to a New Device](#moving-your-wallet-to-a-new-device)
   - [Extracting Your Mnemonic](#extracting-your-mnemonic)
 - [For Developers](#for-developers)
   - [Implementing External Wallet Linking](#implementing-external-wallet-linking)
   - [Implementing Backup/Restore Features](#implementing-backuprestore-features)
+  - [Implementing Device Sync](#implementing-device-sync)
   - [Building Mnemonic Export Tools](#building-mnemonic-export-tools)
 
 ---
@@ -99,6 +101,21 @@ Your backup contains:
 
 ---
 
+### Moving Your Wallet to a New Device
+
+If your passkey syncs to the new device (iCloud Keychain on Apple devices, Google Password Manager on Android and Chrome), you can move your wallet without a password:
+
+1. **On the device that has your wallet**, choose "Sync to another device" (or similar) and confirm with your passkey
+2. **Transfer the sync file**: scan the QR code, or send the file by AirDrop, email, etc.
+3. **On the new device**, open the app, load the sync file and confirm with the same passkey
+4. **Done**: your wallet is on the new device, with the same address
+
+The sync file can't be opened with the file alone: it also takes your passkey and your fingerprint or face. Still, keep it private and delete it once the sync is done.
+
+**When it doesn't work**: this needs a browser that supports the passkey PRF extension (Chrome 108+, Safari 17+ / iOS 17+; not Firefox), and passkeys only sync within one ecosystem (Apple or Google). In other cases, use a password-encrypted backup: the app asks for a password when it creates the sync file, and the new device asks for the same password.
+
+---
+
 ### Extracting Your Mnemonic
 
 If you need to import your W3PK wallet into another wallet application (like MetaMask, Trust Wallet, etc.), you can extract your mnemonic phrase.
@@ -378,6 +395,55 @@ See [src/core/sdk.ts](../src/core/sdk.ts) for implementation details of `createB
 
 ---
 
+### Implementing Device Sync
+
+`exportForSync()` makes a sync file encrypted with a key derived from the passkey's [WebAuthn PRF](https://w3c.github.io/webauthn/#prf-extension) output (`encryptionMethod: 'prf'`). Any device where the passkey synced restores it with one prompt and no password, even a fresh device with no data for the passkey.
+
+```typescript
+// Device A, logged in: one passkey prompt
+const { blob, filename, qrCode } = await sdk.exportForSync()
+
+// Device B, logged out: one passkey prompt, restricted to the file's passkey
+const { ethereumAddress } = await sdk.importFromSync(syncData)
+```
+
+`syncWalletWithPasskey(syncData)` restores the same files and also takes password backups.
+
+**Password fallback**: PRF works in Chrome 108+ and Safari 17+ / iOS 17+, not in Firefox. Without it, `exportForSync()` throws `PrfUnsupportedError`. Pass a password to fall back to a password backup, which the new device restores with `syncWalletWithPasskey(syncData, password)`:
+
+```typescript
+import { PrfUnsupportedError } from 'w3pk'
+
+let sync
+try {
+  sync = await sdk.exportForSync()
+} catch (error) {
+  if (!(error instanceof PrfUnsupportedError)) throw error
+  sync = await sdk.exportForSync(await askUserForPassword())
+}
+```
+
+Or pass the password up front: `exportForSync(password)` uses it only when PRF is unavailable. Passkeys sync within one ecosystem only (Apple or Google), so moving between ecosystems also takes a password backup.
+
+**PRF sync file structure:**
+
+```json
+{
+  "createdAt": "2026-10-25T10:30:00.000Z",
+  "ethereumAddress": "0x...",
+  "encryptedMnemonic": "base64(iv || AES-256-GCM ciphertext)",
+  "encryptionMethod": "prf",
+  "credential": { "id": "passkey credential id", "publicKey": "base64url SPKI" },
+  "prfSalt": "base64url, 32 random bytes",
+  "username": "alice",
+  "addressChecksum": "..."
+}
+```
+
+The key is HKDF-SHA256 over the PRF output evaluated at `SHA-256("w3pk-prf-sync-v1" || prfSalt)`. The public key doesn't decrypt anything; the new device needs it for later logins and checks it against the assertion's signature. The file fits in a QR code (`generateSyncQR()`).
+
+---
+
 ### Building Mnemonic Export Tools
 
 For advanced users who need to export their mnemonic to use in other wallets, W3PK provides a standalone extraction tool.