spaps-mcp 0.1.0

package/dist/wizard/step-05-wallet-auth.md

@@ -0,0 +1,368 @@
+# SPAPS Integration Step 5/12: Wallet Authentication
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1-4: Project setup through email authentication
+- ✅ TokenManager working with email auth
+- ✅ Error handling implemented
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Add wallet connection UI with shadcn/ui", status: "pending", activeForm: "Adding wallet connection UI" },
+    { content: "Implement authenticateWallet method (NOT signInWithWallet)", status: "pending", activeForm: "Implementing authenticateWallet" },
+    { content: "Create complete signature callback function", status: "pending", activeForm: "Creating signature callback" },
+    { content: "Use WalletUtils.detectChainType for chain detection", status: "pending", activeForm: "Using WalletUtils for chain detection" },
+    { content: "Test with address 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8", status: "pending", activeForm: "Testing wallet authentication" },
+    { content: "Store tokens and setup auto-refresh", status: "pending", activeForm: "Setting up token storage" },
+    { content: "Handle wallet-specific errors", status: "pending", activeForm: "Handling wallet errors" },
+    { content: "Request step 6 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Critical Method Name Warning
+
+⚠️ **EXTREMELY IMPORTANT - READ THIS CAREFULLY** ⚠️
+
+The correct method is `authenticateWallet` NOT `signInWithWallet`:
+
+```typescript
+// ✅ CORRECT - This is the ONLY method that exists
+const auth = await sdk.auth.authenticateWallet(
+  walletAddress,
+  signatureCallback,
+  chainType
+)
+
+// ❌ WRONG - These methods DO NOT EXIST
+sdk.auth.signInWithWallet(...)      // NO! This doesn't exist!
+sdk.auth.walletLogin(...)           // NO! This doesn't exist!
+sdk.auth.walletSignIn(...)          // NO! This doesn't exist!
+sdk.auth.connectWallet(...)         // NO! This doesn't exist!
+```
+
+## Implementation Guide
+
+### 1. Import Requirements
+```typescript
+import { SweetPotatoSDK, TokenManager, WalletUtils, SweetPotatoAPIError } from 'spaps-sdk'
+import { sdk } from '@/lib/spaps'
+import { ethers } from 'ethers' // For Ethereum wallet interaction
+
+// UI Components
+import { Button } from "@/components/ui/button"
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { toast } from "sonner"
+```
+
+### 2. Wallet Authentication Implementation
+
+The `authenticateWallet` method has this EXACT signature:
+
+```typescript
+authenticateWallet(
+  walletAddress: string,
+  signatureFunction: (message: string) => Promise<string> | string,
+  chainType?: 'ethereum' | 'solana' | 'bitcoin' | 'base',
+  username?: string
+): Promise<AuthResponse>
+```
+
+**Bitcoin scope note:** the server verifies BIP-137 signed messages
+(Bitcoin Core / Electrum / Trezor style) for mainnet P2PKH, P2WPKH (`bc1q`),
+and P2SH-P2WPKH addresses. Taproot (`bc1p`) addresses require BIP-322 and are
+rejected with a clear error — do not offer Taproot wallets for sign-in.
+Testnet addresses are rejected.
+
+### 3. Complete Implementation Example
+
+```typescript
+'use client'
+
+import { useState } from 'react'
+import { Button } from "@/components/ui/button"
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { toast } from "sonner"
+import { sdk } from '@/lib/spaps'
+import { SweetPotatoAPIError, TokenManager, WalletUtils } from 'spaps-sdk'
+import { ethers } from 'ethers'
+
+export function WalletAuthForm() {
+  const [isLoading, setIsLoading] = useState(false)
+  const [walletAddress, setWalletAddress] = useState('')
+
+  const handleWalletConnect = async () => {
+    setIsLoading(true)
+    
+    try {
+      // Step 1: Check for MetaMask
+      if (!window.ethereum) {
+        throw new Error('Please install MetaMask to use wallet authentication')
+      }
+
+      // Step 2: Request account access
+      const accounts = await window.ethereum.request({ 
+        method: 'eth_requestAccounts' 
+      }) as string[]
+      
+      if (!accounts || accounts.length === 0) {
+        throw new Error('No accounts found in wallet')
+      }
+
+      const address = accounts[0]
+      setWalletAddress(address)
+      
+      // Step 3: Detect chain type (optional, will auto-detect if not provided)
+      const chainType = WalletUtils.detectChainType(address)
+      console.log('Detected chain type:', chainType)
+      
+      // Step 4: Create signature callback
+      // ⚠️ CRITICAL: This callback receives the message to sign
+      const signatureCallback = async (message: string): Promise<string> => {
+        console.log('Message to sign:', message)
+        
+        // Create ethers provider and signer
+        const provider = new ethers.BrowserProvider(window.ethereum)
+        const signer = await provider.getSigner()
+        
+        // Sign the message
+        const signature = await signer.signMessage(message)
+        console.log('Signature:', signature)
+        
+        return signature
+      }
+      
+      // Step 5: Authenticate with SPAPS
+      // ✅ CORRECT METHOD NAME: authenticateWallet
+      const authResponse = await sdk.auth.authenticateWallet(
+        address,
+        signatureCallback,
+        'ethereum' // or chainType from detection
+      )
+      
+      // Step 6: Store tokens
+      TokenManager.storeTokens(authResponse)
+      
+      // Step 7: Setup auto-refresh
+      TokenManager.autoRefreshToken(sdk)
+      
+      toast.success('Wallet authenticated successfully!')
+      console.log('Auth response:', authResponse)
+      
+    } catch (error) {
+      handleWalletError(error)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+  
+  const handleWalletError = (error: any) => {
+    if (error instanceof SweetPotatoAPIError) {
+      switch (error.code) {
+        case 'INVALID_SIGNATURE':
+          toast.error('Invalid wallet signature')
+          break
+        case 'WALLET_NOT_FOUND':
+          toast.error('Wallet not registered')
+          break
+        case 'RATE_LIMITED':
+          toast.error('Too many attempts. Please wait.')
+          break
+        default:
+          toast.error(error.message)
+      }
+    } else if (error?.code === 4001) {
+      // User rejected the signature request in MetaMask
+      toast.error('Signature request rejected')
+    } else if (error?.code === -32002) {
+      // Request already pending in MetaMask
+      toast.error('Please check MetaMask for pending request')
+    } else {
+      toast.error(error.message || 'Wallet authentication failed')
+    }
+    console.error('Wallet auth error:', error)
+  }
+
+  // Test wallet button
+  const fillTestWallet = () => {
+    setWalletAddress('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8')
+  }
+
+  return (
+    <Card className="w-[400px]">
+      <CardHeader>
+        <CardTitle>Wallet Authentication</CardTitle>
+        <CardDescription>
+          Connect your Ethereum wallet to authenticate
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="p-4 bg-muted rounded-lg">
+          <p className="text-sm font-medium">Current Address:</p>
+          <p className="text-xs font-mono mt-1">
+            {walletAddress || 'Not connected'}
+          </p>
+        </div>
+        
+        <Button 
+          onClick={handleWalletConnect}
+          className="w-full" 
+          disabled={isLoading}
+        >
+          {isLoading ? 'Connecting...' : 'Connect Ethereum Wallet'}
+        </Button>
+        
+        <Button 
+          variant="outline"
+          className="w-full"
+          onClick={fillTestWallet}
+        >
+          Use Test Wallet Address
+        </Button>
+        
+        <p className="text-xs text-muted-foreground">
+          Test wallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8
+        </p>
+      </CardContent>
+    </Card>
+  )
+}
+
+// TypeScript declarations for MetaMask
+declare global {
+  interface Window {
+    ethereum?: {
+      request: (args: { method: string; params?: any[] }) => Promise<any>
+      on: (event: string, handler: (...args: any[]) => void) => void
+      removeListener: (event: string, handler: (...args: any[]) => void) => void
+    }
+  }
+}
+```
+
+## How authenticateWallet Works
+
+The SDK handles these steps automatically:
+1. **Gets nonce** from server for the wallet address
+2. **Creates message** to sign with nonce
+3. **Calls your callback** with the message
+4. **Receives signature** from your callback
+5. **Verifies signature** on server
+6. **Returns auth tokens** if valid
+
+You only need to provide the signature callback!
+
+## Testing Without Real Wallet
+
+For testing without MetaMask:
+
+```typescript
+const mockSignatureCallback = async (message: string): Promise<string> => {
+  console.log('Would sign message:', message)
+  // Return mock signature for testing
+  return '0xmocked_signature_for_testing_purposes_only'
+}
+
+// Use in test mode
+const auth = await sdk.auth.authenticateWallet(
+  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8',
+  mockSignatureCallback,
+  'ethereum'
+)
+```
+
+## Validation Checklist
+
+✅ **Method Name**:
+- Uses `authenticateWallet` (NOT signInWithWallet)
+- Three parameters: address, callback, chainType
+
+✅ **Signature Callback**:
+- Receives message as parameter
+- Returns signature as string or Promise<string>
+- Properly signs with wallet
+
+✅ **Chain Detection**:
+- Uses `WalletUtils.detectChainType(address)`
+- Passes correct chain type ('ethereum', 'solana', etc.)
+
+✅ **Token Storage**:
+- Calls `TokenManager.storeTokens(authResponse)`
+- Sets up `TokenManager.autoRefreshToken(sdk)`
+
+✅ **Error Handling**:
+- Handles MetaMask not installed
+- Handles signature rejection (code 4001)
+- Handles SweetPotatoAPIError codes
+
+## Common Mistakes to Avoid
+
+❌ **Wrong method name**:
+```typescript
+// WRONG - This method doesn't exist!
+sdk.auth.signInWithWallet(address, signature, chain)
+```
+
+❌ **Not providing callback**:
+```typescript
+// WRONG - Missing signature callback
+sdk.auth.authenticateWallet(address)
+```
+
+❌ **Signing outside of callback**:
+```typescript
+// WRONG - Don't pre-sign
+const signature = await signer.signMessage('some message')
+sdk.auth.authenticateWallet(address, signature) // NO!
+```
+
+✅ **CORRECT - Provide callback**:
+```typescript
+sdk.auth.authenticateWallet(
+  address,
+  async (message) => await signer.signMessage(message),
+  'ethereum'
+)
+```
+
+## Testing Requirements
+
+1. **With MetaMask**:
+   - Install MetaMask extension
+   - Connect to any network
+   - Click "Connect Wallet"
+   - Sign the message when prompted
+   - Should authenticate successfully
+
+2. **Test Address**:
+   - Address: `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8`
+   - Should work with mock signature in local mode
+
+3. **Error Cases**:
+   - Reject signature → Should show "rejected" error
+   - No MetaMask → Should show "install MetaMask" error
+
+## Next Step
+
+When ALL todos are ✅ complete and wallet auth works:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 6
+})
+```
+
+## Remember
+
+🔴 **CRITICAL**: The method is `authenticateWallet` NOT `signInWithWallet`!
+- This is the #1 mistake that causes integration failures
+- Double-check your code uses the correct method name
+- The signature must be provided via callback, not directly