w3pk 0.4.1 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # w3pk
 
-WebAuthn SDK for passwordless authentication, encrypted Ethereum wallets, and privacy-preserving stealth addresses.
+WebAuthn SDK for passwordless authentication, encrypted Ethereum wallets, privacy-preserving stealth addresses, and zero-knowledge proofs.
 
 Live demo: **https://d2u.w3hc.org/voting**
 
@@ -10,13 +10,24 @@ Live demo: **https://d2u.w3hc.org/voting**
 npm install w3pk
 ```
 
+### Optional Zero-Knowledge Proofs
+
+ZK proofs require additional dependencies. Install only if you need ZK features:
+
+```bash
+# Install ZK dependencies (optional)
+npm install snarkjs circomlibjs
+```
+
 ## Features
 
 - **🔐 Passwordless Authentication**: WebAuthn/FIDO2 biometric authentication
 - **💰 Encrypted Wallet Management**: Client-side AES-GCM-256 encrypted wallets  
-- **🌱 HD Wallet Generation**: BIP39/BIP44 compliant wallet derivation
+- **🌱 HD Wallet Generation**: BIP39/BIP44 compliant wallet derivation with multi-address support
 - **🥷 Stealth Addresses**: Privacy-preserving stealth address generation with unlinkable transactions
+- **🔬 Zero-Knowledge Proofs**: Privacy-preserving proofs (membership, threshold, range, ownership)
 - **🛡️ Network Agnostic**: Works with any blockchain - you handle the transactions
+- **⚡ React Optimized**: Streamlined for modern React applications
 
 ## Quick Start
 
@@ -56,7 +67,10 @@ createWeb3Passkey({
   debug?: boolean,                 // Optional: Enable logs (default: false)
   onError?: (error) => void,       // Optional: Error handler
   onAuthStateChanged?: (isAuth, user?) => void,  // Optional: Auth callback
-  stealthAddresses?: {}            // Optional: Enable stealth address generation
+  stealthAddresses?: {},           // Optional: Enable stealth address generation
+  zkProofs?: {                     // Optional: Enable zero-knowledge proofs
+    enabledProofs: ['membership', 'threshold', 'range', 'ownership']
+  }
 })
 ```
 
@@ -118,6 +132,7 @@ w3pk.user                   // UserInfo | null - Current user data
 w3pk.version                // string - SDK version
 w3pk.isBrowserEnvironment   // boolean - Browser environment detection
 w3pk.stealth                // StealthAddressModule | null - Stealth address module
+w3pk.zk                     // ZKProofModule | null - Zero-knowledge proof module
 ```
 
 ### Error Handling
@@ -304,6 +319,229 @@ console.log('Your stealth meta address:', keys.metaAddress)
 console.log('Your viewing key (keep private):', keys.viewingKey)
 ```
 
+### Zero-Knowledge Proofs API
+
+**Prerequisites**: Install ZK dependencies first:
+```bash
+npm install snarkjs circomlibjs
+```
+
+When configured with `zkProofs` option, the SDK provides privacy-preserving zero-knowledge proof generation:
+
+```typescript
+// Initialize SDK with ZK proofs enabled
+const w3pk = createWeb3Passkey({
+  apiBaseUrl: 'https://webauthn.w3hc.org',
+  zkProofs: {
+    enabledProofs: ['membership', 'threshold', 'range', 'ownership', 'nft']
+  }
+})
+
+// Login first
+await w3pk.login()
+
+// 1. Membership Proof - Prove you're in a set without revealing identity
+const members = ['user1', 'user2', 'user3']
+const membershipProof = await w3pk.zk.proveMembership({
+  value: 'user2',
+  pathIndices: [1, 0], 
+  pathElements: ['hash1', 'hash2'],
+  root: 'merkle_root'
+})
+
+// 2. Threshold Proof - Prove balance > threshold without revealing balance
+const thresholdProof = await w3pk.zk.proveThreshold({
+  value: 5000n,
+  blinding: 123456n,
+  threshold: 1000n,
+  commitment: 'commitment_hash'
+})
+
+// 3. Range Proof - Prove age is 18-65 without revealing exact age
+const rangeProof = await w3pk.zk.proveRange({
+  value: 25n,
+  blinding: 789012n, 
+  min: 18n,
+  max: 65n,
+  commitment: 'age_commitment'
+})
+
+// 4. Ownership Proof - Prove you own an address without revealing private key
+const ownershipProof = await w3pk.zk.proveOwnership({
+  privateKey: 'your_private_key',
+  nonce: 345678n,
+  address: '0x...',
+  challenge: 'challenge_string'
+})
+
+// 5. NFT Ownership Proof - Prove you own an NFT from a collection
+import { generateNFTOwnershipProofInputs } from 'w3pk'
+
+const holderAddresses = [
+  '0x742d35Cc6139FE1C2f1234567890123456789014',
+  '0x1234567890123456789012345678901234567890',  // Your address
+  '0x9876543210987654321098765432109876543210'
+]
+const contractAddress = '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D'  // Human Passport SBT contract
+
+const { nftProofInput } = await generateNFTOwnershipProofInputs(
+  '0x1234567890123456789012345678901234567890',  // Your address
+  contractAddress,
+  holderAddresses
+)
+
+const nftProof = await w3pk.zk.proveNFTOwnership(nftProofInput)
+
+// Verify any proof
+const isValid = await w3pk.zk.verify(membershipProof)
+const nftIsValid = await w3pk.zk.verifyNFTOwnership(nftProof, contractAddress, nftProofInput.holdersRoot)
+console.log('Proof valid:', isValid)
+console.log('NFT proof valid:', nftIsValid)
+```
+
+### ZK Proof Utilities
+
+**Note**: These functions require `snarkjs` and `circomlibjs` to be installed.
+
+```typescript
+// Create commitments for hiding values (requires circomlibjs)
+const commitment = await w3pk.zk.createCommitment(value, blinding)
+
+// Compute merkle roots for membership proofs (requires circomlibjs)  
+const root = await w3pk.zk.computeMerkleRoot(leaf, pathIndices, pathElements)
+
+// Direct utility functions
+import { 
+  generateBlinding, 
+  buildMerkleTree, 
+  generateMerkleProof,
+  buildNFTHoldersMerkleTree,
+  generateNFTOwnershipProofInputs,
+  validateNFTOwnershipProofInputs 
+} from 'w3pk'
+
+const blinding = generateBlinding()
+const { root, tree } = await buildMerkleTree(['leaf1', 'leaf2', 'leaf3'])
+const { pathIndices, pathElements } = generateMerkleProof(tree, 1)
+
+// NFT-specific utilities
+const holderAddresses = ['0x...', '0x...', '0x...']
+const contractAddress = '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D'
+const { root: nftRoot, tree: nftTree } = await buildNFTHoldersMerkleTree(holderAddresses, contractAddress)
+const { nftProofInput } = await generateNFTOwnershipProofInputs('0x...', contractAddress, holderAddresses)
+```
+
+**Note:** ZK proofs require circuit compilation:
+```bash
+# Compile circuits (required for proof generation)
+pnpm build:zk
+
+# Run comprehensive ZK demo (optional)
+tsx examples/zk-proof-demo.ts
+```
+
+## NFT Ownership Proof Example
+
+Prove you own an NFT from a collection without revealing which specific NFT or your exact wallet address:
+
+```typescript
+import { createWeb3Passkey, generateNFTOwnershipProofInputs } from 'w3pk'
+
+// Initialize SDK with NFT proofs enabled
+const w3pk = createWeb3Passkey({
+  apiBaseUrl: 'https://webauthn.w3hc.org',
+  zkProofs: {
+    enabledProofs: ['nft']
+  }
+})
+
+// Login first
+await w3pk.login()
+
+// Example: Human Passport SBT contract
+const HumanPassportSBTContract = '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D'
+const SBTHolders = [
+  '0x742d35Cc6139FE1C2f1234567890123456789014',
+  '0x1234567890123456789012345678901234567890',  // Your address
+  '0x9876543210987654321098765432109876543210',
+  '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd'
+]
+
+// 1. Generate proof inputs for your address
+const yourAddress = '0x1234567890123456789012345678901234567890'
+const { nftProofInput, holderLeaves } = await generateNFTOwnershipProofInputs(
+  yourAddress,
+  HumanPassportSBTContract,
+  SBTHolders,
+  1n  // Minimum balance requirement
+)
+
+// 2. Generate NFT ownership proof
+const nftOwnershipProof = await w3pk.zk.proveNFTOwnership(nftProofInput)
+
+console.log('NFT Ownership Proof Generated!')
+console.log('Holder index:', nftProofInput.holderIndex)  // Your position in holder list (private)
+console.log('Proof type:', nftOwnershipProof.type)      // "nft"
+console.log('Public signals:', nftOwnershipProof.publicSignals)  // Only merkle root visible
+
+// 3. Verify the proof
+const isValid = await w3pk.zk.verifyNFTOwnership(
+  nftOwnershipProof,
+  HumanPassportSBTContract,
+  nftProofInput.holdersRoot,
+  1n  // Expected minimum balance
+)
+
+console.log('NFT proof is valid:', isValid)
+
+// 4. Use case: Gated content access
+if (isValid) {
+  console.log('✅ Access granted to Human Passport SBT holders-only content!')
+  console.log('✅ Your exact NFT and wallet address remain private')
+} else {
+  console.log('❌ Access denied - proof verification failed')
+}
+
+// Example: SBT (Soulbound Token) Proof
+const sbtContract = '0x1234567890123456789012345678901234567890'
+const sbtHolders = [
+  '0xuser1...',
+  '0xuser2...',
+  yourAddress,  // You have this SBT
+  '0xuser3...'
+]
+
+const { nftProofInput: sbtProofInput } = await generateNFTOwnershipProofInputs(
+  yourAddress,
+  sbtContract, 
+  sbtHolders
+)
+
+const sbtProof = await w3pk.zk.proveNFTOwnership(sbtProofInput)
+const sbtValid = await w3pk.zk.verifyNFTOwnership(sbtProof, sbtContract, sbtProofInput.holdersRoot)
+
+if (sbtValid) {
+  console.log('✅ SBT ownership verified - access granted to exclusive community!')
+}
+```
+
+### NFT Proof Privacy Features
+
+- **🔒 Private NFT ID**: Nobody knows which specific NFT you own from the collection
+- **🔒 Private Wallet**: Your exact wallet address is not revealed
+- **🔒 Private Balance**: Only proves you meet minimum balance requirement
+- **✅ Public Verification**: Anyone can verify you own an NFT from the specified collection
+- **⚡ Efficient Proofs**: Uses merkle trees for scalable verification (supports thousands of holders)
+
+### Supported Use Cases
+
+- **🎨 NFT-Gated Content**: Prove ownership for exclusive access without linking to specific wallet
+- **🏅 SBT Credentials**: Verify soulbound token ownership for reputation systems  
+- **🎪 Community Access**: Join exclusive groups based on NFT ownership
+- **🗳️ DAO Voting**: Anonymous voting rights based on NFT collection membership
+- **🎮 Gaming**: Unlock features based on NFT ownership across multiple games
+- **📚 Education**: Access courses/content based on credential NFTs/SBTs
+
 ## Complete Example
 
 ```typescript
@@ -367,15 +605,29 @@ w3pk.logout()
 
 ## Backend
 
-Requires [nestjs-webauthn](https://github.com/w3hc/nestjs-webauthn):
+### Using Hosted Backend (Recommended)
 
-```bash
-git clone https://github.com/w3hc/nestjs-webauthn
-cd nestjs-webauthn
-pnpm install
-pnpm start:dev
+The easiest way to get started is to use the hosted WebAuthn backend:
+
+```typescript
+const w3pk = createWeb3Passkey({
+  apiBaseUrl: 'https://webauthn.w3hc.org'
+})
 ```
 
+This hosted service handles WebAuthn registration and authentication flows.
+
+### Self-Hosted Backend
+
+For production use, you may want to self-host your WebAuthn backend. The backend should implement:
+
+- `POST /webauthn/register/begin` - Start WebAuthn registration
+- `POST /webauthn/register/complete` - Complete WebAuthn registration  
+- `POST /webauthn/authenticate/usernameless/begin` - Start usernameless authentication
+- `POST /webauthn/authenticate/usernameless/complete` - Complete usernameless authentication
+
+See the [WebAuthn specification](https://w3c.github.io/webauthn/) for implementation details.
+
 ## Security
 
 ### Encryption & Storage
@@ -490,17 +742,24 @@ pnpm build
 pnpm dev
 
 # Run tests
-pnpm test                    # Run basic + comprehensive test suite
+pnpm test                    # Run basic + comprehensive + ZK test suites
 pnpm test:basic             # Run basic functionality tests only
-pnpm test:comprehensive     # Run full 23-test comprehensive suite
+pnpm test:comprehensive     # Run full 23-test comprehensive suite  
+pnpm test:zk                # Run ZK proof module tests
+pnpm test:nft               # Run NFT ownership proof tests (6 tests)
+
+# ZK circuit compilation (optional)
+pnpm build:zk               # Compile circom circuits for proof generation
 
 # Publish to npm
 pnpm prepublishOnly         # Builds before publishing
 ```
 
+Watch [Asciinema video](https://asciinema.org/a/s9EAGyxNpBH2UZilZvEUHcGSO) (running the tests)
+
 ### Test Coverage
 
-The SDK includes a comprehensive test suite with **23 test cases** covering:
+The SDK includes a comprehensive test suite with **37 test cases** covering:
 
 - ✅ **Core SDK functionality** - Constructor, configuration, environment detection
 - ✅ **Wallet generation** - BIP39/BIP44 compliance, HD derivation, consistency
@@ -508,7 +767,10 @@ The SDK includes a comprehensive test suite with **23 test cases** covering:
 - ✅ **Storage operations** - IndexedDB CRUD, multiple wallets, cleanup
 - ✅ **Message signing** - Signature generation, address verification
 - ✅ **HD wallet derivation** - Multi-index support, validation, consistency
-- ✅ **Error handling** - Graceful failure scenarios
+- ✅ **ZK proof operations** - Commitment creation, merkle trees, proof setup
+- ✅ **NFT ownership proofs** - NFT merkle trees, proof generation, SBT support
+- ✅ **Circuit compilation** - Circom circuit status, dependency detection
+- ✅ **Error handling** - Graceful failure scenarios, mock mode fallbacks
 - ✅ **Integration testing** - End-to-end workflows
 
 ### Architecture
@@ -520,9 +782,14 @@ w3pk/
 │   ├── wallet/         # Wallet generation, signing, storage
 │   ├── auth/           # WebAuthn authentication flows  
 │   ├── stealth/        # Privacy-preserving stealth addresses
+│   ├── zk/             # Zero-knowledge proof module
+│   │   ├── circuits/   # Circom circuit definitions (membership, threshold, range, ownership, nft)
+│   │   ├── templates/  # Compiled circuit artifacts (.r1cs, .sym, .wasm)
+│   │   └── wasm/       # WebAssembly circuit files
 │   ├── utils/          # API client, validation utilities
 │   └── types/          # TypeScript type definitions
-├── test/               # Comprehensive test suite
+├── test/               # Comprehensive test suite (37 test cases)
+├── scripts/            # Circuit compilation and build scripts
 └── dist/               # Built output (CJS + ESM + types)
 ```
 
@@ -544,6 +811,6 @@ Contact [Julien Béranger](https://github.com/julienbrg):
 
 ## License
 
-GPL-3.0-or-later
+GPL-3.0
 
 <img src="https://bafkreid5xwxz4bed67bxb2wjmwsec4uhlcjviwy7pkzwoyu5oesjd3sp64.ipfs.w3s.link" alt="built-with-ethereum-w3hc" width="100"/>