w3pk 0.10.3 → 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)
@@ -115,6 +116,7 @@ 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)
 }
 ```
 
@@ -125,18 +127,18 @@ interface RegisterResult {
 4. Encrypts mnemonic using WebAuthn credential (AES-GCM-256)
 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, username and whether a backup exists
+7. Returns Ethereum address, username, whether a backup exists and whether the browser may wipe the wallet
 
 **Example:**
 
 ```typescript
-const { address, username, hasBackup } = await w3pk.register({
+const { address, username, hasBackup, evictionRisk } = await w3pk.register({
   username: 'alice'
 })
 console.log('Registered:', username, 'with address:', address)
 
 if (!hasBackup) {
-  showBackupPrompt() // see getBackupStatus()
+  showBackupPrompt({ blocking: evictionRisk }) // see getBackupStatus()
 }
 ```
 
@@ -167,8 +169,8 @@ interface UserInfo {
 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()`
-- `WalletMissingError` if the credential metadata is here but the wallet record is gone (carries `credentialId` and `ethereumAddress`); offer a restore from backup
+- `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.
 
@@ -1365,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.
@@ -2276,6 +2333,7 @@ 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;
@@ -2287,11 +2345,15 @@ 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()
-if (!status.hasBackup) {
+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
@@ -2675,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
@@ -2693,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:**
 
@@ -2715,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
@@ -2738,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)
@@ -2762,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.
 
 ---
 
@@ -3944,7 +4023,9 @@ import {
   StorageError,
   ApiError,
   SyncRequiredError,
-  WalletMissingError
+  WalletMissingError,
+  SyncBootstrapError,
+  PrfUnsupportedError
 } from 'w3pk'
 ```
 
@@ -3959,6 +4040,8 @@ import {
   - `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
 
@@ -3974,10 +4057,11 @@ try {
   await w3pk.login()
 } catch (error) {
   if (error instanceof SyncRequiredError) {
-    // Passkey synced to this device, wallet data isn't: ask for the backup file
-    await w3pk.syncWalletWithPasskey(backupFile)
+    // Passkey synced to this device, wallet data isn't: ask for the password backup
+    await w3pk.syncWalletWithPasskey(backupFile, password)
   } else if (error instanceof WalletMissingError) {
-    console.error('No wallet for', error.ethereumAddress, '- restore from backup')
+    // 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) {

package/docs/BROWSER_COMPATIBILITY.md

@@ -110,6 +110,17 @@ The encrypted wallet, persistent sessions and backup metadata live in localStora
 
 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 |

package/docs/INTEGRATION_GUIDELINES.md

@@ -1225,13 +1225,20 @@ async function promptBackupOptions() {
 
 **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
 // ✅ Ask for a backup right after registration
-const { hasBackup } = await w3pk.register({ username })
+const { hasBackup, evictionRisk } = await w3pk.register({ username })
 
 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()
+  const choice = await showBackupNowPrompt({ blocking: evictionRisk })
 
   if (choice === 'file') {
     const { blob, filename } = await w3pk.createBackupFile('password', password)
@@ -1246,7 +1253,9 @@ if (!hasBackup) {
 async function checkBackup() {
   const status = await w3pk.getBackupStatus()
 
-  if (!status.hasBackup) {
+  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')
   }
 

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.

package/docs/RECOVERY.md

@@ -219,70 +219,81 @@ await sdk.importMnemonic(mnemonic);
 
 **Purpose**: Sync wallet to devices where passkey is already synced
 
-There are two approaches depending on whether you have an existing wallet session:
+There are two approaches: a PRF sync file needs no password, a password backup works everywhere.
 
-#### Option A: Sync with passkey + backup file (recommended for new devices)
+#### Option A: PRF sync file (no password)
 
-Use this when you're on a new device that already has your passkey synced (e.g., via iCloud/Google Password Manager) but doesn't have the wallet data yet.
+Use this when the wallet is active on Device A and the passkey synced to Device B (iCloud Keychain, Google Password Manager). Device B can be a fresh device with no data for the passkey.
 
+**Export from Device A:**
 ```typescript
 const sdk = createWeb3Passkey();
+await sdk.login(); // On device with wallet
 
-// Provide your backup file (any encryption method: password, passkey, or hybrid)
-const backupData = '...'; // JSON string or Blob from your backup file
-const { mnemonic, ethereumAddress } = await sdk.syncWalletWithPasskey(backupData);
-// 1. SDK prompts you to select your synced passkey
-// 2. Decrypts backup using the selected passkey
-// 3. Stores wallet data locally and starts a session ✅
+const { blob, filename, qrCode } = await sdk.exportForSync();
+// One passkey prompt. Transfer via QR code, AirDrop, email, etc.
 ```
 
-For password or hybrid backups, pass the password as a second argument:
-
+**Import on Device B:**
 ```typescript
-const { mnemonic, ethereumAddress } = await sdk.syncWalletWithPasskey(backupData, 'MyPassword123!');
+const sdk = createWeb3Passkey();
+
+await sdk.importFromSync(syncData); // or sdk.syncWalletWithPasskey(syncData)
+// 1. One passkey prompt, restricted to the file's passkey
+// 2. Decrypts the file and checks its address checksum
+// 3. Saves the passkey's metadata on this device if it's missing
+// 4. Stores wallet data locally, starts a session and fires onAuthStateChanged(true, user) ✅
 ```
 
-**Requirement**: Passkey must be synced to this device (iCloud/Google Password Manager)
+No `login()` first: on a device without the wallet, `login()` throws `SyncRequiredError` or `WalletMissingError`.
 
-**Supports**: All backup encryption methods (`password`, `passkey`, `hybrid`)
+**How it works**: the file (`encryptionMethod: 'prf'`) is encrypted with a key derived from the passkey's [WebAuthn PRF](https://w3c.github.io/webauthn/#prf-extension) output: HKDF-SHA256 over the PRF output at `SHA-256("w3pk-prf-sync-v1" || prfSalt)`, with a random `prfSalt` per file, then AES-256-GCM. The PRF secret syncs with the passkey but never leaves the authenticator, and the authenticator releases the output only on a user-verified assertion. So the file or its QR code alone decrypts nothing: it also takes the synced passkey and a biometric. An altered address checksum, address or ciphertext is rejected.
 
-#### Option B: Export/import sync file (between two active devices)
+The file also names its passkey (`credential: { id, publicKey }`) and carries the username. The public key is not a secret and doesn't decrypt the file. A fresh device needs it for `login()` and for the wallet key, and checks it against the assertion's signature first (`SyncBootstrapError` with `reason: 'PUBLIC_KEY_MISMATCH'` if it doesn't match).
 
-Use this when you have the wallet active on Device A and want to transfer to Device B.
+**Fallback**: PRF works in Chrome 108+ and Safari 17+ / iOS 17+, not in Firefox. Where the authenticator has no PRF support, `exportForSync()` throws `PrfUnsupportedError`; `exportForSync(password)` emits a password backup instead, to restore with Option B. Passkeys sync within one ecosystem only (Apple or Google), so moving between ecosystems also takes Option B.
 
-**Export from Device A:**
-```typescript
-const sdk = createWeb3Passkey();
-await sdk.login(); // On device with wallet
+#### Option B: Sync with passkey + password backup
 
-const { blob, filename, qrCode } = await sdk.exportForSync();
-// Transfer via QR code, AirDrop, email, etc.
-```
+Use this when PRF is unavailable, or when you only have a password backup. This is also a path to take when `login()` throws `SyncRequiredError` or `WalletMissingError`.
 
-**Import on Device B:**
 ```typescript
 const sdk = createWeb3Passkey();
-await sdk.login(); // Passkey must be synced to this device
 
-await sdk.importFromSync(syncData);
-// Wallet now available on Device B, credentials stored locally ✅
+const backupData = '...'; // JSON string or Blob from your password backup file
+const { mnemonic, ethereumAddress } = await sdk.syncWalletWithPasskey(backupData, 'MyPassword123!');
+// 1. SDK prompts you to select your synced passkey
+// 2. Decrypts the backup
+// 3. Saves the passkey's metadata on this device if it's missing
+// 4. Stores wallet data locally, starts a session and fires onAuthStateChanged(true, user) ✅
 ```
 
-**Encryption**: WebAuthn-derived key → AES-256-GCM
+A password backup made while logged in names its passkey (`credential: { id, publicKey }`), which is what lets a fresh device set the passkey up: an assertion doesn't carry the public key, and `login()` and the wallet key both need it. The public key is not a secret, and the fresh device checks it against the assertion's signature.
 
-**Use Case**: Wallet on desktop, want it on mobile (same passkey ecosystem)
+**Requirement**: Passkey must be synced to this device (iCloud/Google Password Manager)
+
+**Supports**:
+- On a device with no data for the passkey: PRF files and password backups made by the passkey's user
+- On a device that already has the passkey's metadata (the wallet record was lost): all backup encryption methods (`prf`, `password`, `passkey`, `hybrid`)
+
+On a fresh device, `syncWalletWithPasskey()` and `importFromSync()` throw `SyncBootstrapError` when they can't set the passkey up:
+- `reason: 'PASSKEY_BACKUP'`: passkey or hybrid backup, which can't be decrypted without the public key
+- `reason: 'NO_CREDENTIAL'`: password backup that doesn't name its passkey (made before 0.10.4); make a new one on a logged-in device
+- `reason: 'CREDENTIAL_MISMATCH'`: the backup names another passkey than the one selected (or than the logged-in one, for `importFromSync()`)
+- `reason: 'PUBLIC_KEY_MISMATCH'`: the backup's public key doesn't match the passkey's signature
 
-**Requirement**: Passkey must be synced via iCloud/Google Password Manager
+**Use Case**: Wallet on desktop, want it on mobile (same passkey ecosystem)
 
 **Pros:**
-- ✅ No password needed (passkey-encrypted backups)
+- ✅ No password needed with PRF sync files
 - ✅ Leverages existing passkey sync
 - ✅ Fast and convenient
-- ✅ `syncWalletWithPasskey()` works without an existing session
+- ✅ `syncWalletWithPasskey()` and `importFromSync()` work without an existing session
 
 **Cons:**
 - ⚠️ Requires passkey on target device
 - ⚠️ Platform-specific (iCloud or Google)
+- ⚠️ PRF sync files need Chrome 108+ or Safari 17+ / iOS 17+; elsewhere, use a password backup
 
 ---
 
@@ -527,17 +538,16 @@ await w3pk.importMnemonic(mnemonic);
 ### Cross-Device Sync
 
 ```typescript
-// Sync to new device using existing passkey + backup file (no prior session needed)
-const { mnemonic, ethereumAddress } = await w3pk.syncWalletWithPasskey(backupData);
-// or with password for password/hybrid backups:
-const result = await w3pk.syncWalletWithPasskey(backupData, 'MyPassword123!');
-
-// Export for sync (Device A - requires active session)
+// Export for sync (Device A - requires active session): PRF-encrypted, no password
 const { blob, qrCode } = await w3pk.exportForSync();
+// Or with a password fallback where PRF is unavailable
+const fallback = await w3pk.exportForSync('MyPassword123!');
+
+// Import on Device B where the passkey synced (no login needed, no password)
+await w3pk.importFromSync(syncData);
 
-// Import on another device (Device B - stores credentials locally)
-await w3pk.login(); // Must have passkey synced
-await w3pk.importFromSync(backupData);
+// Sync with a password backup (no prior session needed)
+const { mnemonic, ethereumAddress } = await w3pk.syncWalletWithPasskey(backupData, 'MyPassword123!');
 ```
 
 ### Social Recovery
@@ -747,8 +757,8 @@ Verification:
 1. Get new device (same ecosystem)
 2. Sign into cloud account (iCloud/Google) - passkey syncs automatically
 3. Go to w3pk website
-4. Provide your backup file (any encryption method)
-5. Call syncWalletWithPasskey(backupData) or use the app's "Sync Wallet" flow
+4. Provide your password backup file
+5. Call syncWalletWithPasskey(backupData, password) or use the app's "Sync Wallet" flow
 6. Authenticate with biometric when prompted
 7. Wallet decrypted and stored locally ✅
 
@@ -761,10 +771,10 @@ Platform-specific:
 **Option B: Export/import sync file (transfer from active device)**
 
 ```markdown
-1. On Device A: export sync file via exportForSync()
+1. On Device A: export sync file via exportForSync() (one passkey prompt)
 2. Transfer file to Device B (AirDrop, QR code, etc.)
-3. On Device B: sign in with synced passkey, then importFromSync(syncData)
-4. Wallet decrypted ✅
+3. On Device B: importFromSync(syncData), and confirm the synced passkey when prompted
+4. Wallet decrypted ✅ (no password; needs PRF: Chrome 108+, Safari 17+ / iOS 17+, not Firefox)
 ```
 
 #### **Method 3: Using Social Recovery**
@@ -822,7 +832,7 @@ A: **No!** This is a critical distinction. Your passkey (Face ID/Touch ID creden
 A: Only if you also transferred your wallet data or created a backup. The passkey will sync automatically, allowing you to authenticate, but the encrypted wallet data needs to be restored separately from a backup. Use `syncWalletWithPasskey(backupData)` to combine your synced passkey with a backup file in a single step.
 
 **Q: What's the difference between `syncWalletWithPasskey()` and `importFromSync()`?**
-A: `syncWalletWithPasskey()` is for new devices with no active session — it prompts for your synced passkey and accepts any backup file (password, passkey, or hybrid encrypted). `importFromSync()` requires you to already be logged in and uses a passkey-encrypted sync export from another device.
+A: `syncWalletWithPasskey()` takes any backup file and prompts for your synced passkey; on a device with no data for the passkey, that backup must be a PRF sync file or a password backup. `importFromSync()` takes only PRF sync files from `exportForSync()`, with no password. Both restore a PRF sync file the same way, and neither needs a prior `login()`.
 
 **Q: Can I use multiple backup methods?**
 A: Yes! We recommend using at least 2 methods for redundancy.
@@ -889,7 +899,7 @@ Your backup is automatically marked as "verified" when you successfully:
 - Restore from a backup file using `restoreFromBackupFile()`
 - Register a new passkey from backup using `registerWithBackupFile()`
 - Recover from guardian shares using `recoverFromGuardians()`
-- Import from device sync using `importFromSync()`
+- Import from device sync using `importFromSync()` or `syncWalletWithPasskey()`
 
 Verification proves that your backup actually works, increasing your security score.