w3pk 0.10.2 → 0.10.3

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,37 @@ 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.
 
 ```typescript
-// ✅ Provide multiple backup options
-async function setupBackups() {
-  const status = await w3pk.getBackupStatus()
+// ✅ Ask for a backup right after registration
+const { hasBackup } = 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) {
+  // "Back up now": a backup file, or the recovery phrase written down
+  const choice = await showBackupNowPrompt()
 
-  // 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) {
+    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 +1269,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 +1333,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 +1429,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)**.