w3pk 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,8 @@
 # w3pk
 
-WebAuthn SDK for passwordless authentication with client-side encrypted Ethereum wallets.
+WebAuthn SDK for passwordless authentication, encrypted Ethereum wallets, and privacy-preserving stealth addresses.
+
+Live demo: **https://d2u.w3hc.org/web3**
 
 ## Install
 
@@ -8,53 +10,39 @@ WebAuthn SDK for passwordless authentication with client-side encrypted Ethereum
 npm install w3pk
 ```
 
+## 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
+- **🥷 Stealth Addresses**: Privacy-preserving stealth address generation with unlinkable transactions
+- **🛡️ Network Agnostic**: Works with any blockchain - you handle the transactions
+
 ## Quick Start
 
 ```typescript
 import { createWeb3Passkey } from 'w3pk'
-import { startRegistration, startAuthentication } from '@simplewebauthn/browser'
 
 const w3pk = createWeb3Passkey({
   apiBaseUrl: 'https://webauthn.w3hc.org'
 })
 
-// Generate wallet
-const wallet = await w3pk.generateWallet()
-console.log('Backup this mnemonic:', wallet.mnemonic)
+// Register new user (wallet generated automatically)
+const result = await w3pk.register({ username: 'alice' })
+console.log('⚠️ BACKUP THIS MNEMONIC:', result.mnemonic)
+console.log('Ethereum address:', result.ethereumAddress)
 
-// Register
-const beginRes = await fetch('https://webauthn.w3hc.org/webauthn/register/begin', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ username: 'alice', ethereumAddress: wallet.address })
-})
-const { data } = await beginRes.json()
-const credential = await startRegistration(data.options)
-
-await w3pk.register({
-  username: 'alice',
-  ethereumAddress: wallet.address,
-  mnemonic: wallet.mnemonic,
-  credentialId: credential.id,
-  challenge: data.options.challenge
-})
+// Login (usernameless)
+const loginResult = await w3pk.login()
+console.log('Logged in:', loginResult.user?.username)
+console.log('Address:', loginResult.user?.ethereumAddress)
 
-// Login
-const result = await w3pk.login()
-console.log('Logged in:', result.user?.username)
+// Sign message (handles fresh auth automatically)
+const signature = await w3pk.signMessage('Hello, Web3!')
+console.log('Signature:', signature)
 
-// Sign message
-const authBeginRes = await fetch('https://webauthn.w3hc.org/webauthn/authenticate/usernameless/begin', {
-  method: 'POST'
-})
-const authData = await authBeginRes.json()
-const authCredential = await startAuthentication(authData.data.options)
-
-const signature = await w3pk.signMessage(
-  'Hello, Web3!',
-  authCredential.id,
-  authData.data.options.challenge
-)
+// Logout
+w3pk.logout()
 ```
 
 ## API
@@ -67,43 +55,53 @@ createWeb3Passkey({
   timeout?: number,                // Optional: Request timeout (default: 30000ms)
   debug?: boolean,                 // Optional: Enable logs (default: false)
   onError?: (error) => void,       // Optional: Error handler
-  onAuthStateChanged?: (isAuth, user?) => void  // Optional: Auth callback
+  onAuthStateChanged?: (isAuth, user?) => void,  // Optional: Auth callback
+  stealthAddresses?: {}            // Optional: Enable stealth address generation
 })
 ```
 
 ### Methods
 
+#### Wallet Management
+
 ```typescript
 // Generate BIP39 wallet (12-word mnemonic)
 await w3pk.generateWallet()
 // Returns: { address: string, mnemonic: string }
 
-// Register new user
-await w3pk.register({
+// Check if wallet exists for current user
+await w3pk.hasWallet()
+// Returns: boolean
+```
+
+#### Authentication
+
+```typescript
+// Register new user (auto-generates wallet)
+await w3pk.register({ username: string })
+// Returns: { ethereumAddress: string, mnemonic?: string }
+
+// Register with existing wallet
+await w3pk.register({ 
   username: string,
   ethereumAddress: string,
-  mnemonic: string,
-  credentialId: string,
-  challenge: string
+  mnemonic: string 
 })
 
 // Login (usernameless)
 await w3pk.login()
-// Returns: { verified: boolean, user?: { id, username, ethereumAddress } }
-
-// Authenticate with address
-await w3pk.authenticate(ethereumAddress: string)
-
-// Sign message (requires fresh auth)
-await w3pk.signMessage(message: string, credentialId: string, challenge: string)
-// Returns: string (signature)
+// Returns: { verified: boolean, user?: UserInfo }
 
 // Logout
 w3pk.logout()
+```
 
-// Check wallet exists
-await w3pk.hasWallet()
-// Returns: boolean
+#### Message Signing
+
+```typescript
+// Sign message (handles WebAuthn authentication internally)
+await w3pk.signMessage(message: string)
+// Returns: string (signature)
 ```
 
 ### Properties
@@ -113,6 +111,161 @@ w3pk.isAuthenticated        // boolean
 w3pk.user                   // UserInfo | null
 w3pk.version                // string
 w3pk.isBrowserEnvironment   // boolean
+w3pk.stealth                // StealthAddressModule | null
+```
+
+### Stealth Address API
+
+When configured with `stealthAddresses` option, the SDK provides privacy-preserving stealth address generation:
+
+```typescript
+// Generate a fresh stealth address for privacy-preserving transactions
+await w3pk.stealth.generateStealthAddress()
+// Returns: { stealthAddress, stealthPrivateKey, ephemeralPublicKey }
+
+// Get stealth keys for advanced operations
+await w3pk.stealth.getKeys()
+// Returns: { metaAddress, viewingKey, spendingKey }
+
+// Check if a stealth address belongs to you (from crypto utils)
+import { canControlStealthAddress } from 'w3pk'
+canControlStealthAddress(viewingKey, ephemeralPublicKey, targetAddress)
+// Returns: boolean
+```
+
+### Types
+
+```typescript
+interface UserInfo {
+  id: string
+  username: string
+  displayName: string
+  ethereumAddress: string
+}
+
+interface WalletInfo {
+  address: string
+  mnemonic: string
+}
+
+interface AuthResult {
+  verified: boolean
+  user?: UserInfo
+}
+
+interface StealthKeys {
+  metaAddress: string
+  viewingKey: string
+  spendingKey: string
+}
+
+interface StealthAddressResult {
+  stealthAddress: string
+  stealthPrivateKey: string
+  ephemeralPublicKey: string
+}
+```
+
+## Stealth Address Example
+
+```typescript
+import { createWeb3Passkey } from 'w3pk'
+import { ethers } from 'ethers'
+
+// Initialize SDK with stealth addresses enabled
+const w3pk = createWeb3Passkey({
+  apiBaseUrl: 'https://webauthn.w3hc.org',
+  stealthAddresses: {}
+})
+
+// 1. Login with w3pk
+await w3pk.login()
+
+// 2. Generate a fresh stealth address
+const stealthResult = await w3pk.stealth.generateStealthAddress()
+console.log('Stealth address:', stealthResult.stealthAddress)
+console.log('Private key:', stealthResult.stealthPrivateKey)
+console.log('Ephemeral public key:', stealthResult.ephemeralPublicKey)
+
+// 3. Use the private key with any blockchain library
+const stealthWallet = new ethers.Wallet(stealthResult.stealthPrivateKey)
+
+// 4. Sign transactions with any provider
+const provider = new ethers.JsonRpcProvider('https://ethereum-sepolia-rpc.publicnode.com')
+const connectedWallet = stealthWallet.connect(provider)
+
+// 5. Send transactions normally - now unlinkable!
+const tx = await connectedWallet.sendTransaction({
+  to: '0x742d35Cc6139FE1C2f1234567890123456789014',
+  value: ethers.parseEther('0.001')
+})
+console.log('Transaction sent from stealth address:', tx.hash)
+
+// 6. Get stealth keys for advanced operations
+const keys = await w3pk.stealth.getKeys()
+console.log('Your stealth meta address:', keys.metaAddress)
+console.log('Your viewing key (keep private):', keys.viewingKey)
+```
+
+## Complete Example
+
+```typescript
+import { createWeb3Passkey } from 'w3pk'
+
+// Initialize SDK
+const w3pk = createWeb3Passkey({
+  apiBaseUrl: 'https://webauthn.w3hc.org',
+  debug: true,
+  onError: (error) => {
+    console.error('SDK Error:', error.message)
+  },
+  onAuthStateChanged: (isAuth, user) => {
+    console.log('Auth changed:', isAuth, user?.username)
+  }
+})
+
+// 1. Register new user
+try {
+  const result = await w3pk.register({ username: 'alice' })
+  
+  // User MUST backup this mnemonic!
+  if (result.mnemonic) {
+    alert(`⚠️ SAVE THIS: ${result.mnemonic}`)
+  }
+} catch (error) {
+  console.error('Registration failed:', error)
+}
+
+// 2. Login existing user
+try {
+  const result = await w3pk.login()
+  
+  if (result.verified) {
+    console.log('Welcome back,', result.user?.username)
+    
+    // Check if wallet is available on this device
+    const hasWallet = await w3pk.hasWallet()
+    console.log('Wallet available:', hasWallet)
+  }
+} catch (error) {
+  console.error('Login failed:', error)
+}
+
+// 3. Sign a message
+if (w3pk.isAuthenticated) {
+  try {
+    // This will prompt for WebAuthn authentication
+    const signature = await w3pk.signMessage('Hello, Web3!')
+    console.log('Signature:', signature)
+    
+    // Verify on Etherscan: https://etherscan.io/verifiedSignatures
+  } catch (error) {
+    console.error('Signing failed:', error)
+  }
+}
+
+// 4. Logout
+w3pk.logout()
 ```
 
 ## Backend
@@ -129,24 +282,99 @@ pnpm start:dev
 ## Security
 
 - ✅ Client-side AES-GCM-256 encryption
-- ✅ PBKDF2 key derivation from WebAuthn credentials
+- ✅ PBKDF2 key derivation (100,000 iterations) from WebAuthn credentials
 - ✅ Private keys never leave the browser
 - ✅ IndexedDB encrypted storage per device
+- ✅ BIP39 standard 12-word mnemonic
+- ✅ BIP44 HD wallet derivation (m/44'/60'/0'/0/0)
 - ⚠️ Users MUST backup their 12-word mnemonic
 
-## Testing
+### Security Notes
+
+- Your wallet is protected by device biometrics (fingerprint, Face ID, etc.)
+- If you lose your device or passkey, your wallet **cannot be recovered** without the mnemonic
+- The mnemonic is only shown once during registration
+- Each device stores its own encrypted copy of the wallet
+
+## React Integration
+
+View live example: **https://d2u.w3hc.org/web3** 
+
+```typescript
+import { createWeb3Passkey } from 'w3pk'
+import { useState, useEffect } from 'react'
+
+function App() {
+  const [w3pk, setW3pk] = useState(null)
+  const [user, setUser] = useState(null)
+
+  useEffect(() => {
+    const sdk = createWeb3Passkey({
+      apiBaseUrl: 'https://webauthn.w3hc.org',
+      onAuthStateChanged: (isAuth, user) => {
+        setUser(isAuth ? user : null)
+      }
+    })
+    setW3pk(sdk)
+  }, [])
+
+  const handleRegister = async () => {
+    const result = await w3pk.register({ username: 'alice' })
+    alert(`Save this mnemonic: ${result.mnemonic}`)
+  }
+
+  const handleLogin = async () => {
+    await w3pk.login()
+  }
+
+  const handleSign = async () => {
+    const sig = await w3pk.signMessage('Hello!')
+    console.log('Signature:', sig)
+  }
+
+  return (
+    <div>
+      {!user ? (
+        <>
+          <button onClick={handleRegister}>Register</button>
+          <button onClick={handleLogin}>Login</button>
+        </>
+      ) : (
+        <>
+          <p>Welcome {user.username}!</p>
+          <button onClick={handleSign}>Sign Message</button>
+          <button onClick={() => w3pk.logout()}>Logout</button>
+        </>
+      )}
+    </div>
+  )
+}
+```
+
+## Development
 
 ```bash
-# Node.js test (wallet generation)
-pnpm test
+# Install dependencies
+pnpm install
 
 # Build
 pnpm build
 
 # Watch mode
 pnpm dev
+
+# Test (Node.js environment - wallet generation)
+pnpm test
 ```
 
+## Browser Compatibility
+
+Requires browsers with WebAuthn support:
+- Chrome/Edge 67+
+- Firefox 60+
+- Safari 13+
+- All modern mobile browsers
+
 ## Support
 
 Contact [Julien Béranger](https://github.com/julienbrg):
@@ -155,4 +383,8 @@ Contact [Julien Béranger](https://github.com/julienbrg):
 - Telegram: [@julienbrg](https://t.me/julienbrg)
 - Twitter: [@julienbrg](https://twitter.com/julienbrg)
 
-<img src="https://bafkreid5xwxz4bed67bxb2wjmwsec4uhlcjviwy7pkzwoyu5oesjd3sp64.ipfs.w3s.link" alt="built-with-ethereum-w3hc" width="100"/>
+## License
+
+GPL-3.0-or-later
+
+<img src="https://bafkreid5xwxz4bed67bxb2wjmwsec4uhlcjviwy7pkzwoyu5oesjd3sp64.ipfs.w3s.link" alt="built-with-ethereum-w3hc" width="100"/>

package/dist/index.d.mts

@@ -1,9 +1,59 @@
+/**
+ * Stealth address cryptography for privacy-preserving transactions
+ */
+interface StealthKeys {
+    metaAddress: string;
+    viewingKey: string;
+    spendingKey: string;
+}
+/**
+ * Check if a stealth address can be controlled by the stealth keys
+ * Useful for scanning and proving ownership of stealth addresses
+ */
+declare function canControlStealthAddress(viewingKey: string, spendingKey: string, ephemeralPubkey: string, targetAddress: string): boolean;
+
+/**
+ * Stealth Address Module for w3pk SDK
+ * Provides privacy-preserving stealth address generation capabilities
+ */
+
+interface StealthAddressConfig$1 {
+}
+interface StealthAddressResult {
+    stealthAddress: string;
+    stealthPrivateKey: string;
+    ephemeralPublicKey: string;
+}
+/**
+ * Main Stealth Address Module
+ * Integrates with w3pk WebAuthn for seamless privacy-preserving stealth address generation
+ */
+declare class StealthAddressModule {
+    private config;
+    private getMnemonic;
+    constructor(config: StealthAddressConfig$1, getMnemonic: () => Promise<string | null>);
+    /**
+     * Generate a fresh stealth address for privacy-preserving transactions
+     * Returns the stealth address and private key for the user to handle transactions
+     */
+    generateStealthAddress(): Promise<StealthAddressResult>;
+    /**
+     * Get stealth keys for manual operations
+     */
+    getKeys(): Promise<StealthKeys>;
+    /**
+     * Check if stealth addresses are available (always true if properly configured)
+     */
+    get isAvailable(): boolean;
+}
+
 /**
  * Shared types used across the SDK
  */
 interface UserInfo {
     id: string;
     username: string;
+    displayName: string;
     ethereumAddress: string;
 }
 interface WalletInfo {
@@ -43,6 +93,8 @@ declare class ApiError extends Web3PasskeyError {
  * SDK Configuration
  */
 
+interface StealthAddressConfig {
+}
 interface Web3PasskeyConfig {
     /**
      * Base URL of the WebAuthn API
@@ -67,25 +119,21 @@ interface Web3PasskeyConfig {
      * Auth state change callback
      */
     onAuthStateChanged?: (isAuthenticated: boolean, user?: UserInfo) => void;
+    /**
+     * Optional stealth address configuration
+     * If provided, enables privacy-preserving stealth address generation
+     */
+    stealthAddresses?: StealthAddressConfig;
 }
 
 /**
- * Authentication-related types
+ * Main Web3Passkey SDK class
  */
 
 interface AuthResult {
     verified: boolean;
-    user?: {
-        id: string;
-        username: string;
-        ethereumAddress: string;
-    };
+    user?: UserInfo;
 }
-
-/**
- * Main Web3Passkey SDK class
- */
-
 declare class Web3Passkey {
     private config;
     private apiClient;
@@ -94,11 +142,18 @@ declare class Web3Passkey {
     private currentUser;
     private isAuthenticatedState;
     private isBrowser;
+    private stealthAddresses;
     constructor(config: Web3PasskeyConfig);
     private loadAuthState;
     private saveAuthState;
     private clearAuthState;
     private notifyAuthStateChange;
+    private createUserInfo;
+    /**
+     * Get mnemonic for current authenticated user
+     * Used by stealth address module
+     */
+    private getMnemonic;
     /**
      * Generate a new BIP39 wallet
      * @returns Wallet info with mnemonic (user MUST backup)
@@ -110,23 +165,22 @@ declare class Web3Passkey {
     hasWallet(): Promise<boolean>;
     /**
      * Register a new user with WebAuthn
+     * Handles the complete registration flow internally
+     * Automatically generates wallet if not provided
+     *
      * @param username Username for the account
-     * @param ethereumAddress Ethereum address from generated wallet
-     * @param mnemonic BIP39 mnemonic to encrypt and store
-     * @param credentialId WebAuthn credential ID (from registration response)
-     * @param challenge Challenge used in registration
+     * @param ethereumAddress Optional: Ethereum address (will generate if not provided)
+     * @param mnemonic Optional: BIP39 mnemonic (will generate if not provided)
+     * @returns Object containing ethereumAddress and mnemonic (only if generated)
      */
     register(options: {
         username: string;
+        ethereumAddress?: string;
+        mnemonic?: string;
+    }): Promise<{
         ethereumAddress: string;
-        mnemonic: string;
-        credentialId: string;
-        challenge: string;
-    }): Promise<void>;
-    /**
-     * Authenticate with Ethereum address
-     */
-    authenticate(ethereumAddress: string): Promise<AuthResult>;
+        mnemonic?: string;
+    }>;
     /**
      * Authenticate without username (usernameless flow)
      */
@@ -137,12 +191,11 @@ declare class Web3Passkey {
     logout(): void;
     /**
      * Sign a message with encrypted wallet
-     * Requires fresh WebAuthn authentication
+     * Handles fresh WebAuthn authentication internally
+     *
      * @param message Message to sign
-     * @param credentialId WebAuthn credential ID (from fresh auth)
-     * @param challenge Challenge from fresh auth
      */
-    signMessage(message: string, credentialId: string, challenge: string): Promise<string>;
+    signMessage(message: string): Promise<string>;
     /**
      * Check if user is authenticated
      */
@@ -159,6 +212,10 @@ declare class Web3Passkey {
      * Check if running in browser environment
      */
     get isBrowserEnvironment(): boolean;
+    /**
+     * Get stealth address module (if configured)
+     */
+    get stealth(): StealthAddressModule | null;
 }
 
 /**
@@ -168,4 +225,4 @@ declare class Web3Passkey {
 
 declare function createWeb3Passkey(config: Web3PasskeyConfig): Web3Passkey;
 
-export { ApiError, type AuthResult, AuthenticationError, CryptoError, RegistrationError, StorageError, type UserInfo, WalletError, type WalletInfo, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, createWeb3Passkey, createWeb3Passkey as default };
+export { ApiError, AuthenticationError, CryptoError, RegistrationError, type StealthAddressConfig, StealthAddressModule, type StealthAddressResult, type StealthKeys, StorageError, type UserInfo, WalletError, type WalletInfo, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, canControlStealthAddress, createWeb3Passkey, createWeb3Passkey as default };