w3pk 0.7.6 → 0.7.7

package/README.md

@@ -1,5 +1,6 @@
 [![npm version](https://img.shields.io/npm/v/w3pk.svg)](https://www.npmjs.com/package/w3pk)
 [![npm downloads](https://img.shields.io/npm/dm/w3pk.svg)](https://www.npmjs.com/package/w3pk)
+[![Reproducible Build](https://img.shields.io/badge/reproducible-builds-blue?logo=ipfs)](https://github.com/w3hc/w3pk/blob/main/docs/BUILD_VERIFICATION.md)
 
 # w3pk
 
@@ -29,9 +30,9 @@ await w3pk.login()
 // Sign message
 const signature = await w3pk.signMessage('Hello World')
 
-// Derive addresses
-const wallet0 = await w3pk.deriveWallet(0)
-const wallet1 = await w3pk.deriveWallet(1)
+// Derive addresses (2 modes)
+const gamingWallet = await w3pk.deriveWallet('GAMING') // By tag - includes privateKey
+const mainWallet = await w3pk.deriveWallet() // Auto (MAIN tag) - public address only, no privateKey
 
 // Get RPC endpoints for any chain
 const endpoints = await w3pk.getEndpoints(1) // Ethereum
@@ -41,14 +42,16 @@ const rpcUrl = endpoints[0]
 ## Features
 
 - 🔐 Passwordless authentication (WebAuthn/FIDO2)
-- 🔒 Client-only biometric-gated wallet encryption (AES-GCM-256)
+- 🛡️ Origin-specific key isolation with tag-based access control
 - ⏱️ Session management (configurable duration, prevents repeated prompts)
 - 🌱 HD wallet generation (BIP39/BIP44)
 - 🔢 Multi-address derivation
-- 🥷 ERC-5564 stealth addresses (privacy-preserving transactions with view tags)
+- 🌐 Origin-specific addresses (deterministic derivation per website with tag support)
+- 🥷 ERC-5564 stealth addresses (opt-in, privacy-preserving transactions with view tags)
 - 🧮 ZK primitives (zero-knowledge proof generation and verification)
 - 🔗 Chainlist support (2390+ networks, auto-filtered RPC endpoints)
 - ⚡ EIP-7702 network detection (329+ supported networks)
+- 🔍 Build verification (IPFS CIDv1 hashing for package integrity)
 - 🛡️ Three-layer backup & recovery system
   - Passkey auto-sync (iCloud/Google/Microsoft)
   - Encrypted backups (ZIP/QR with password protection)
@@ -76,27 +79,38 @@ w3pk.user
 
 **Important: Backup your wallet!**
 ```typescript
-// After registration, users can create a backup
-const mnemonic = await w3pk.exportMnemonic({ requireAuth: true })
-console.log('⚠️  Save this recovery phrase:', mnemonic)
 
-// Or create encrypted backups:
+// Create encrypted backups:
 const zipBackup = await w3pk.createZipBackup('strong-password')
 const qrBackup = await w3pk.createQRBackup('optional-password')
 ```
 
 ### Wallet Operations
 
-```typescript
-// Derive addresses
-const wallet0 = await w3pk.deriveWallet(0)
-// Returns: { address, privateKey }
-
-// Export mnemonic
-const mnemonic = await w3pk.exportMnemonic()
+**SECURITY MODEL**: `deriveWallet()` supports two secure modes:
 
-// Sign message
-const signature = await w3pk.signMessage(message)
+```typescript
+// 1. MAIN tag (default) - ADDRESS ONLY, NO PRIVATE KEY
+const mainWallet = await w3pk.deriveWallet()
+// Returns: { address, index, origin, tag: 'MAIN' }
+// ✅ Safe for display
+// ❌ No privateKey exposed
+
+// 2. Custom tag - INCLUDES PRIVATE KEY for app-specific use
+const gamingWallet = await w3pk.deriveWallet('GAMING')
+const funWallet = await w3pk.deriveWallet('FUN')
+const basicWallet = await w3pk.deriveWallet('BASIC')
+// Returns: { address, privateKey, index, origin, tag }
+
+// Different tags = different addresses
+console.log(mainWallet.address !== gamingWallet.address) // true
+console.log(gamingWallet.address !== tradingWallet.address) // true
+
+// SECURITY: Applications CANNOT access master mnemonic
+// await w3pk.exportMnemonic() // ❌ Throws error
+
+// Sign message (works with any address - no key exposure needed)
+const signature = await w3pk.signMessage('Hello World')
 ```
 
 ### Session Management
@@ -113,10 +127,9 @@ const w3pk = createWeb3Passkey({
 await w3pk.login()
 
 // These operations use the cached session
-await w3pk.deriveWallet(0)
-await w3pk.exportMnemonic()
+await w3pk.deriveWallet('GAMING')
 await w3pk.signMessage('Hello')
-await w3pk.stealth.getKeys()
+await w3pk.stealth?.getKeys() // If stealth module enabled
 
 // Check session status
 w3pk.hasActiveSession() // true
@@ -274,10 +287,61 @@ console.log('Can recover:', result.canRecover)
 
 See [Recovery Guide](./docs/RECOVERY.md) for complete documentation.
 
+### Build Verification
+
+```typescript
+import { getCurrentBuildHash, verifyBuildHash } from 'w3pk'
+
+// Get IPFS hash of installed w3pk build
+const hash = await getCurrentBuildHash()
+console.log('Build hash:', hash)
+// => bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi
+
+// Verify against trusted hash (from GitHub releases)
+const trusted = 'bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi'
+const isValid = await verifyBuildHash(trusted)
+if (isValid) {
+  console.log('✅ Build integrity verified!')
+}
+```
+
+See [Build Verification Guide](./docs/BUILD_VERIFICATION.md) for complete documentation.
+
+## Security & Verification
+
+### Current Build Hash (v0.7.6)
+
+```
+bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi
+```
+
+**Verify package integrity:**
+
+```typescript
+import { verifyBuildHash } from 'w3pk'
+
+const TRUSTED_HASH = 'bafybeifysgwvsyog2akxjk4cjky2grqqyzfehamuwyk6zy56srgkc5jopi'
+const isValid = await verifyBuildHash(TRUSTED_HASH)
+
+if (!isValid) {
+  throw new Error('Package integrity check failed!')
+}
+```
+
+**Multi-source verification:**
+- **GitHub:** Check release notes for official hash
+- **On-chain:** Verify via DAO-maintained registry (coming soon)
+- **Local build:** `pnpm build && pnpm build:hash`
+
+See [Build Verification Guide](./docs/BUILD_VERIFICATION.md) for complete documentation.
+
+---
+
 ## Documentation
 
 - [Quick Start Guide](./docs/QUICK_START.md) - Get started in 5 minutes
 - [API Reference](./docs/API_REFERENCE.md) - Complete API documentation
+- [Build Verification](./docs/BUILD_VERIFICATION.md) - Package integrity verification
 - [Security Architecture](./docs/SECURITY.md) - Integration best practices
 - [Recovery & Backup System](./docs/RECOVERY.md) - Three-layer backup architecture
 - [ZK Proofs](./docs/ZK.md) - Zero-Knowledge cryptography utilities