epistery 1.4.4 → 1.5.0

package/MobileIdentity.md

@@ -6,32 +6,6 @@ Safari's Intelligent Tracking Prevention (ITP) deletes localStorage and IndexedD
 
 Epistery uses non-extractable CryptoKeys stored in IndexedDB to create device-locked wallets ("rivets"). These keys never leave the device and cannot be extracted even via XSS attacks. On iOS Safari, Apple purges these keys after 7 days of inactivity.
 
-## The Security Tradeoff
-
-Because Apple will not allow persistent secure storage, iOS users cannot benefit from the same security model as Android and desktop users.
-
-| Platform | Key Storage | Security Property |
-|----------|-------------|-------------------|
-| Android/Desktop | Non-extractable CryptoKey in IndexedDB | Private key **never** leaves device, immune to XSS extraction |
-| iOS Safari | Extractable key, server-escrowed | Key exists on server (encrypted), theoretically extractable |
-
-This is not a design choice. It is a forced degradation. To maintain continuity for iOS users, Epistery must backup keys to the server, fundamentally weakening the security model.
-
-**Implementation consequence:**
-
-```javascript
-const isIOSSafari = /iPad|iPhone|iPod/.test(navigator.userAgent) &&
-                    !window.MSStream &&
-                    /Safari/.test(navigator.userAgent);
-
-if (isIOSSafari) {
-  // BrowserWallet with server escrow - extractable, less secure
-  // Because Apple won't let us keep non-extractable keys
-} else {
-  // RivetWallet - non-extractable, device-locked, actually private
-}
-```
-
 ## The FIDO/Passkey Double Standard
 
 Apple, Google, and Microsoft control the FIDO Alliance, which develops the WebAuthn/Passkey standards. These passkeys receive special treatment that third-party cryptographic keys do not.
@@ -74,140 +48,125 @@ These companies "led development of this expanded set of capabilities and are no
 
 The technical difference? Passkeys live in Apple-controlled infrastructure. Developer-created keys do not.
 
-This is not a privacy measure. It is a competitive moat. The W3C WebAuthn working group has acknowledged this tension - see [Issue #1569: Prevent browsers from deleting credentials that the RP wanted to be server-side](https://github.com/w3c/webauthn/issues/1569).
+This is not a privacy measure. It is a competitive moat. The W3C WebAuthn working group has acknowledged this tension — see [Issue #1569: Prevent browsers from deleting credentials that the RP wanted to be server-side](https://github.com/w3c/webauthn/issues/1569).
 
-## Strategic Implications for Epistery
+## Epistery's Response: PRF-Wraps-Rivet
 
-### The Messaging Opportunity
+Rather than fight the platform, use its tools — but do not surrender the threat model.
 
-Apple's "privacy" policies force less private implementations:
-
-> "On Android and desktop, your Epistery wallet keys never leave your device. On iOS, Apple's storage policies require server backup, making your keys objectively less secure. Apple claims this is for privacy while their own passkey credentials - also device-bound keys - are exempt and sync through iCloud. The difference is control: they purge your secure keys while preserving theirs."
-
-This is factual, documentable, and inverts Apple's privacy narrative.
+The WebAuthn **PRF extension** lets a relying party ask a passkey to evaluate a pseudo-random function over a fixed input, producing deterministic output bytes that never leave the device. We use those bytes to derive an AES key that wraps the user's secp256k1 rivet private key. The encrypted blob is stored on the epistery server, indexed by the FIDO credential ID and domain. On unlock, the device performs the FIDO ceremony, the PRF output decrypts the blob in memory, and the rivet signs as usual.
 
-### The Multi-Domain Advantage
+This pattern is already in production in the ReefRootz reference implementation (`skswave/reefrootz`), where it solves the iOS purge problem for an existing user base.
 
-Epistery's architecture provides some resilience:
+### Components
 
-- Each publisher domain runs its own Epistery instance (first-party context)
-- Chain verification is the shared layer, not browser storage
-- There is no single `epistery.com` domain to classify as a tracker
-- ITP's cross-site tracking heuristics don't easily apply
+| Component | Role | Where it lives |
+|-----------|------|---------------|
+| FIDO credential | Persistent unlock factor | Secure Enclave + iCloud Keychain (OS-managed, ITP-exempt) |
+| PRF output | AES-256 key material | Computed on device per ceremony; never persisted, never transmitted |
+| secp256k1 rivet keypair | Ethereum-compatible signing key | Generated at registration; private key encrypted before any storage |
+| Encrypted blob | AES-GCM(rivet private key, PRF-derived key) | Epistery server, keyed by `(domain, credentialId)` |
+| Whitelist entry | Public identity | `WhitelistEntry { addr, name, role, meta }` in the domain's agent contract |
 
-### Recovery Mechanisms
+### Registration Ceremony
 
-The Identity Contract provides a path forward:
+1. User triggers "Secure this device" on a domain.
+2. Browser invokes `navigator.credentials.create()` with the PRF extension; user does Face ID / Touch ID.
+3. Client derives the AES-256 key from a domain-constant PRF eval input.
+4. Client generates a fresh secp256k1 keypair (the rivet).
+5. Client AES-GCM-encrypts the rivet private key with the PRF-derived key.
+6. Client posts `{ credentialId, publicKey, rivetAddress, encryptedBlob }` to the epistery server; server stores the blob.
+7. The new rivet address is added to a whitelist in the domain's agent contract under the user's existing name (admin-mediated or via auto-approval, depending on domain policy).
 
-1. **First device/site**: Creates invisible rivet, registers on-chain
-2. **Additional devices**: Authorized by existing device via multi-sig
-3. **Recovery after iOS purge (with other devices live)**: Invisible re-authorization
-4. **Recovery with no devices live**: One-time re-affirmation required
+The rivet private key only exists in JS memory during the ceremony and is discarded after the blob is uploaded.
 
-Server-set httpOnly cookies (not subject to the same ITP rules as script-writable storage) can bridge the gap by maintaining an encrypted pointer to the user's chain identity.
+### Unlock Ceremony (Including After iOS Purge)
 
-## FidoWallet Integration
+1. User visits a domain. IndexedDB may have been purged; the session cookie or a credential lookup identifies which FIDO credential to use.
+2. Browser invokes `navigator.credentials.get()` with the same PRF eval input.
+3. Client recovers the AES-256 key on device.
+4. Client fetches the encrypted blob from the epistery server.
+5. Client AES-GCM-decrypts the blob in memory to recover the secp256k1 private key.
+6. Rivet signs the session challenge; key exchange completes as for any other wallet.
 
-Rather than fight the platform, use its tools. FIDO/WebAuthn credentials persist because Apple blesses them. By integrating FidoWallet as a third wallet type alongside RivetWallet and Web3Wallet, Epistery can leverage platform-blessed persistence while maintaining the on-chain identity as the sovereign anchor.
+After the request completes, the private key is dropped. The next session repeats the ceremony, transparent to the user behind a single biometric touch.
 
-### Wallet Type Comparison
+### Threat Model
 
-| Wallet Type | Key Location | Persistence | User Experience | iOS Safari |
-|-------------|--------------|-------------|-----------------|------------|
-| **RivetWallet** | IndexedDB (non-extractable) | Fragile (ITP purge) | Invisible | Unreliable |
-| **Web3Wallet** | MetaMask / external | Persistent | Popup on connect + each sign | Works |
-| **FidoWallet** | Secure Enclave | Persistent | One biometric touch | **Reliable** |
+| Threat | Mitigation |
+|--------|------------|
+| iOS ITP purges IndexedDB | The encrypted blob lives on the epistery server; the decryption key derives from a credential outside ITP scope |
+| Server compromise | The blob is AES-GCM-encrypted with a key the server never sees and cannot derive; without the user's biometric, the blob is inert ciphertext |
+| XSS exfiltrates the rivet private key | The key exists in JS memory only during the unlock window. Larger surface than a non-extractable IndexedDB key, but only at the moment of use |
+| Lost device | Same as Tier 1 today — another device whitelisted under the same name retains access; admin can re-issue or whitelist a fresh credential |
 
-### User Experience Flow
+This sits between the two extremes the previous design framed: stronger than full server-escrow (the server has the blob but not the key), weaker than non-extractable IndexedDB on a device ITP doesn't touch. It is the right tradeoff for iOS specifically, and acceptable as a uniform pattern across platforms for implementation simplicity.
 
-**First visit (registration):**
-1. User triggers "Secure this device" (prompted or via status page)
-2. Single biometric touch (Face ID / Touch ID / fingerprint)
-3. WebAuthn credential created, stored in Secure Enclave
-4. Epistery stores credential ID + public key server-side, tied to session or chain identity
+## Tier 1 Identity Integration
 
-**Return visit (authentication):**
-1. Server sees session cookie, knows user has FIDO credential
-2. Requests WebAuthn assertion
-3. Single biometric touch
-4. Session re-established
+Epistery has two identity tiers, and FIDO fits the casual (default) tier:
 
-**Recovery after iOS purge:**
-- Cookie survives (server-set httpOnly, not subject to ITP)
-- One touch to re-authenticate
-- New rivet created and linked to existing Identity Contract
-- Chain state intact, local key reconstructed
+- **Tier 1 — Domain-scoped named whitelist.** The user's name is recorded in `WhitelistEntry.name` on the domain's agent contract (`contracts/agent.sol`). Multiple device addresses can share the same name; each is a "device of the same person" to the domain. A FIDO-bound rivet on the user's phone is just another whitelisted device under the same name.
+- **Tier 2 — Identity Contract.** Per-user contract with `authorizedRivets[]` and multi-sig recovery. Gas-costly. Use when sovereign portability across domains matters.
 
-### UX Comparison by Scenario
+A FIDO rivet **does not require an Identity Contract**. The casual tier handles the common case: the user has a phone (FIDO-protected rivet) and a desktop (RivetWallet rivet), both whitelisted under the same name on the domains they use. The address-to-name resolver in the auth middleware surfaces the same name for both addresses, so the domain treats them as one person.
 
-| Scenario | RivetWallet | Web3Wallet | FidoWallet |
-|----------|-------------|------------|------------|
-| First visit | Invisible | Popup + approve | One touch |
-| Return (storage intact) | Invisible | Reconnect popup | Invisible (cookie) |
-| Return (storage purged) | **Broken** | Reconnect popup | One touch |
-| Sign operation | Invisible | Popup each time | Invisible (rivet signs) |
-| iOS Safari | Unreliable | Works (external app) | **Reliable** |
+## The Curve Problem (Resolved)
 
-FidoWallet is less intrusive than Web3Wallet while providing the persistence that RivetWallet lacks on iOS.
+FIDO uses P-256 (secp256r1). Ethereum uses secp256k1. Earlier iterations of this design proposed using the FIDO credential directly for chain signing, which would have required ERC-4337 account abstraction or P-256 verifier contracts.
 
-### The Curve Problem
+PRF-wraps-rivet sidesteps the problem: PRF derives an AES-256 key (curve-agnostic), and the rivet that signs on-chain is a freshly generated secp256k1 keypair. FIDO never signs chain transactions; it only protects the AES wrap. The curve mismatch dissolves because the FIDO credential and the rivet are decoupled.
 
-FIDO uses P-256 (secp256r1). Ethereum uses secp256k1. Direct on-chain signature verification requires reconciliation:
+## UX Comparison
 
-| Approach | Tradeoff |
-|----------|----------|
-| **Account abstraction (ERC-4337)** | Smart contract wallets can verify P-256, adds complexity |
-| **FIDO as auth, rivet for signing** | FIDO proves identity, authorizes secp256k1 rivet for chain ops |
-| **PRF-derived key** | Derive secp256k1 from passkey, but extractable |
+| Scenario | RivetWallet (IndexedDB) | Web3Wallet (MetaMask) | FidoWallet (PRF-wraps-rivet) |
+|----------|------|------|------|
+| First visit | Invisible | Popup + approve | One biometric touch |
+| Return visit (storage intact) | Invisible | Reconnect popup | One touch per session |
+| Return visit (iOS purged storage) | **Broken** | Reconnect popup | One touch (fetches blob) |
+| Sign operation | Invisible | Popup each time | Invisible after unlock (rivet signs) |
+| iOS Safari reliability | Unreliable | Works (external app) | **Reliable** |
 
-**Recommended architecture:** FIDO as the persistence/recovery anchor, rivet as the signing key.
+FidoWallet adds a single biometric gesture per session in exchange for surviving ITP purges and avoiding MetaMask's per-signature popups.
 
-This mirrors the Web3Wallet model:
-- MetaMask holds keys externally, Epistery requests signatures
-- FIDO holds credential externally, Epistery uses it to authorize rivets
+## Strategic Position
 
-The FIDO credential proves "I am this user" to the server. The server trusts the FIDO-authenticated session to authorize rivet keys. Those rivets do the actual chain signing.
+Using FIDO means accepting Apple/Google's infrastructure for credential persistence. The architecture limits the dependency:
 
-### Server Configuration
+1. **The FIDO server is the epistery host** — no platform servers in the auth path; the relying party is the domain itself.
+2. **The on-chain identity remains sovereign** — whitelist entries and (optionally) Identity Contracts are the anchor; FIDO is a local unlock factor.
+3. **The PRF output never leaves the device** — Apple's iCloud sync handles the credential, but the AES key the credential produces is computed locally each ceremony.
+4. **Users can extricate further** — Tier 2 graduation, hardware tokens, or pure RivetWallet on non-iOS devices remain available.
 
-The epistery host already decides which wallet types to accept. FidoWallet becomes a third option:
+## The Messaging Opportunity
 
-```
-Wallet types accepted by publisher:
-├── RivetWallet  (device-locked, invisible, iOS-fragile)
-├── Web3Wallet   (external, persistent, popup-heavy)
-└── FidoWallet   (platform-blessed, one-touch, persistent)
-```
-
-Server config example: `acceptWallets: ['rivet', 'fido']` or `['fido', 'web3']`
-
-### Status Page Integration
+Apple's "privacy" policies force less private implementations:
 
-The status page at `/.well-known/epistery/status` already allows users to manage wallet selection. FidoWallet credentials would appear alongside existing options, letting power users manage their constellation of keys across the Identity Contract.
+> "On Android and desktop, your Epistery wallet keys never leave your device. On iOS, Apple purges those keys after 7 days while their own passkey credentials — also device-bound keys — are preserved indefinitely. We bridge the gap by using their passkeys to protect ours: the AES key that unlocks your wallet is computed by your phone's biometric and never sent to any server, including ours. Apple's purge becomes an inconvenience instead of a kill switch."
 
-### Strategic Position
+This is factual, documentable, and inverts Apple's privacy narrative — while making the right technical choice.
 
-Using FIDO means accepting Apple/Google's infrastructure for credential persistence. However:
+## The Multi-Domain Advantage
 
-1. **The FIDO server is independent** - Epistery runs its own relying party, no platform servers in the auth flow
-2. **The Identity Contract remains sovereign** - On-chain identity is the anchor, FIDO is a convenience bridge
-3. **Users can extricate further** - Add more devices, hardware keys, full self-custody at their own pace
-4. **Playing by their rules** - FIDO is an open standard; using it is legitimate, not an exploit
+Epistery's architecture provides natural resilience:
 
-The gesture is heavier than invisible rivet creation, but lighter than MetaMask, and it survives the iOS purge.
+- Each publisher domain runs its own Epistery instance (first-party context).
+- Chain verification is the shared layer, not browser storage.
+- There is no single `epistery.com` domain to classify as a tracker.
+- ITP's cross-site tracking heuristics don't easily apply.
 
 ## Conclusion
 
-The mobile identity landscape is shaped by platform vendors who have constructed privacy policies that handicap alternatives while exempting their own infrastructure. iOS Safari's localStorage purging is not a neutral privacy measure - it is a selective restriction that degrades third-party security while preserving first-party (Apple-controlled) credential persistence.
+The mobile identity landscape is shaped by platform vendors who construct privacy policies that handicap alternatives while exempting their own infrastructure. iOS Safari's localStorage purging is not a neutral privacy measure — it is a selective restriction that degrades third-party security while preserving first-party (Apple-controlled) credential persistence.
 
 Epistery's response:
 
-1. **Document the tradeoff** - iOS users get weaker security, and they should know why
-2. **Implement graceful degradation** - Server escrow for iOS, full device-lock for others
-3. **Leverage on-chain identity** - The chain is the persistent layer; local storage is reconstructible
-4. **Build the coalition** - Every publisher using Epistery has incentive to amplify this message
+1. **Use the blessed credential as an unlock factor, not the signing key.** PRF-wraps-rivet preserves Ethereum-compatibility and on-chain sovereignty.
+2. **Store the encrypted blob, not the key.** The server holds ciphertext; the decryption material lives in the user's Secure Enclave.
+3. **Lean on Tier 1 identity.** Most users don't need an Identity Contract; the domain whitelist with stable names already supports multi-device.
+4. **Build the coalition.** Every publisher using Epistery has incentive to amplify this messaging — the technical case and the political case align.
 
-The monopolies assume identity lives in their silos. Epistery puts identity on-chain, making their storage sabotage an inconvenience rather than a kill switch.
+The monopolies assume identity lives in their silos. Epistery puts identity on-chain, makes the local unlock factor opaque to them, and turns their storage sabotage into a routine biometric touch.
 
 ---
 
@@ -220,3 +179,4 @@ The monopolies assume identity lives in their silos. Epistery puts identity on-c
 - [Corbado: Passkeys & WebAuthn PRF for E2E Encryption](https://www.corbado.com/blog/passkeys-prf-webauthn)
 - [Didomi: Apple 7-Day Cap on Script-Writable Storage](https://support.didomi.io/apple-adds-a-7-day-cap-on-all-script-writable-storage)
 - [Safari ITP Current Status - cookiestatus.com](https://www.cookiestatus.com/safari/)
+- ReefRootz reference implementation: `skswave/reefrootz`