Skip to content

AUTHENTICATION.md

Latest commit

 

History

History
168 lines (122 loc) · 5.26 KB

AUTHENTICATION.md

File metadata and controls

168 lines (122 loc) · 5.26 KB

Bitcoin Wallet Authentication System

This application implements a secure Bitcoin wallet-based authentication system using cryptographic signatures and address whitelisting.

Security Features

🔐 Cryptographic Authentication

  • Message Signing: Users must sign a challenge message with their Bitcoin private key
  • Address Verification: Only whitelisted Bitcoin addresses can access the application
  • Session Management: Secure server-side sessions with automatic expiration
  • Route Protection: Middleware automatically protects all sensitive routes

🛡️ Security Architecture

  1. Whitelist Database: Authorized addresses stored securely in Supabase
  2. Challenge-Response: Unique challenge messages prevent replay attacks
  3. Server-Side Verification: All authentication logic runs on the server
  4. Secure Cookies: HttpOnly cookies prevent client-side manipulation
  5. Row Level Security: Database policies prevent unauthorized access

How It Works

1. User Authentication Flow

```

  1. User visits protected page
  2. Middleware redirects to /login
  3. User connects Bitcoin wallet (UniSat, Xverse, etc.)
  4. System generates unique challenge message
  5. User signs challenge with wallet private key
  6. Server verifies signature and checks whitelist
  7. If valid, creates secure session and redirects to app ```

2. Address Whitelisting

Authorized addresses are stored in the whitelist table:

```sql CREATE TABLE whitelist ( id UUID PRIMARY KEY, bitcoin_address TEXT UNIQUE NOT NULL, label TEXT, is_active BOOLEAN DEFAULT true, created_at TIMESTAMP DEFAULT NOW() ); ```

3. Route Protection

The middleware automatically protects these routes:

  • / - Main PSBT builder interface
  • /api/psbt/* - PSBT creation APIs
  • /api/analyze-psbt - Transaction analysis
  • All other sensitive endpoints

Public routes (no authentication required):

  • /login - Authentication page
  • /api/auth/* - Authentication endpoints

Configuration

Environment Variables

The following environment variables are automatically configured:

  • NEXT_PUBLIC_SUPABASE_URL - Supabase project URL
  • SUPABASE_SERVICE_ROLE_KEY - Server-side Supabase key
  • NEXT_PUBLIC_SUPABASE_ANON_KEY - Client-side Supabase key

Adding Authorized Addresses

To add new authorized Bitcoin addresses, run this SQL in your Supabase dashboard:

```sql INSERT INTO whitelist (bitcoin_address, label) VALUES ('bc1qyour_address_here', 'Description of user'); ```

Or use the provided script:

```bash

Run the whitelist creation script

npm run dev

Then execute: scripts/002_create_whitelist_table.sql

```

Security Considerations

✅ What This System Prevents

  • Unauthorized Access: Only whitelisted addresses can authenticate
  • Session Hijacking: HttpOnly cookies prevent client-side access
  • Replay Attacks: Unique challenge messages with timestamps
  • Client-Side Bypass: All verification happens server-side
  • Database Tampering: Row Level Security policies protect data

⚠️ Important Notes

  1. Private Key Security: Users must keep their Bitcoin private keys secure
  2. Wallet Compatibility: Requires compatible Bitcoin wallet (UniSat, Xverse, OKX)
  3. Network Security: Use HTTPS in production
  4. Session Expiration: Sessions expire after 24 hours
  5. Address Management: Remove addresses from whitelist to revoke access

API Endpoints

Authentication APIs

  • GET /api/auth/challenge - Generate challenge message
  • POST /api/auth/verify - Verify signature and create session
  • GET /api/auth/session - Check current session status
  • POST /api/auth/logout - Clear session and logout

Protected APIs

All PSBT and transaction APIs require authentication:

  • POST /api/psbt/create - Create new PSBT
  • POST /api/analyze-psbt - Analyze transaction metrics

Development

Testing Authentication

  1. Add your Bitcoin address to the whitelist: ```sql INSERT INTO whitelist (bitcoin_address, label) VALUES ('your_bitcoin_address', 'Development Testing'); ```

  2. Connect your wallet and sign the challenge message

  3. Access should be granted to the main application

Debugging

Enable debug logging by checking the browser console and server logs:

  • [v0] prefixed messages show authentication flow
  • Check Network tab for API request/response details
  • Verify cookies are set correctly in Application tab

Production Deployment

  1. Update Whitelist: Replace example addresses with real authorized addresses
  2. Environment Variables: Ensure all Supabase variables are configured
  3. HTTPS: Enable HTTPS for secure cookie transmission
  4. Database Security: Review and test Row Level Security policies
  5. Session Security: Consider shorter session timeouts for high-security environments

Troubleshooting

Common Issues

"Address not authorized"

  • Check if address is in whitelist table
  • Verify is_active = true for the address

"Invalid signature"

  • Ensure wallet is properly connected
  • Try signing the message again
  • Check wallet compatibility

"Session expired"

  • Sessions expire after 24 hours
  • Re-authenticate by visiting /login

Middleware redirect loops

  • Check middleware configuration
  • Verify public routes are properly excluded
  • Clear browser cookies and try again