Authentication

Learn how Bitcoin-based authentication works in BigBlocks.

Overview

BigBlocks implements a revolutionary authentication system where Bitcoin private keys ARE the identity. This eliminates traditional usernames, emails, and passwords in favor of cryptographic authentication.

Key Principles

1. Client-Side Key Generation

Private keys are generated in the browser only
Keys never leave the user's device unencrypted
Uses hierarchical deterministic (HD) key derivation

2. Password Encryption

Users set a password to encrypt their private keys
Password is used for local encryption only
Lost passwords cannot be recovered (by design)

3. OAuth Backup Storage

Encrypted backups stored via OAuth providers (Google, GitHub, X)
OAuth is used for storage only, not authentication
Multiple backup locations for redundancy

4. BSM Authentication

Bitcoin Signed Messages (BSM) authenticate API requests
Time-bound signatures prevent replay attacks
No session cookies or JWT tokens needed

Authentication Components

AuthFlowOrchestrator

Complete authentication flow management:

import { AuthFlowOrchestrator } from 'bigblocks';

function AuthPage() {
  return (
    <AuthFlowOrchestrator
      onSuccess={(user) => {
        console.log('Authenticated:', user);
      }}
      onError={(error) => {
        console.error('Auth failed:', error);
      }}
    />
  );
}

LoginForm

Standalone login component:

import { LoginForm } from 'bigblocks';

function LoginPage() {
  return (
    <LoginForm
      onSuccess={() => router.push('/dashboard')}
      showBackupImport={true}
      showOAuthRestore={true}
    />
  );
}

SignupFlow

Multi-step signup process:

import { SignupFlow } from 'bigblocks';

function SignupPage() {
  return (
    <SignupFlow
      steps={['identity', 'backup', 'profile']}
      onComplete={(user) => {
        console.log('Signup complete:', user);
      }}
    />
  );
}

Authentication Flow

graph TD
    A[User Clicks Signup] --> B[Generate HD Keys]
    B --> C[User Sets Password]
    C --> D[Encrypt Private Keys]
    D --> E[Create BAP Identity]
    E --> F[OAuth Backup Storage]
    F --> G[Authentication Complete]

graph TD
    A[User Enters Password] --> B[Decrypt Local Storage]
    B --> C{Keys Found?}
    C -->|Yes| D[Authenticate with BSM]
    C -->|No| E[Import from Backup]
    E --> F[OAuth Provider Selection]
    F --> G[Download Encrypted Backup]
    G --> H[Decrypt with Password]
    H --> D

3. OAuth Restore Flow

import { OAuthRestoreFlow } from 'bigblocks';

function RestorePage() {
  return (
    <OAuthRestoreFlow
      providers={['google', 'github', 'x']}
      onRestore={(backup) => {
        console.log('Backup restored:', backup);
      }}
    />
  );
}

API Authentication

Setting Up API Routes

// api/protected/route.ts
import { verifyBSM } from 'bigblocks/auth';

export async function POST(request: Request) {
  try {
    const { address, signature, message } = await request.json();
    
    // Verify the BSM signature
    const isValid = await verifyBSM({
      address,
      signature,
      message,
      maxAge: 600 // 10 minutes
    });
    
    if (!isValid) {
      return new Response('Unauthorized', { status: 401 });
    }
    
    // Process authenticated request
    return new Response('Success');
  } catch (error) {
    return new Response('Invalid signature', { status: 401 });
  }
}

Client-Side API Calls

import { useAuth, signMessage } from 'bigblocks';

function MyComponent() {
  const { address, privateKey } = useAuth();
  
  const callAPI = async () => {
    const message = `Authenticate ${Date.now()}`;
    const signature = await signMessage(message, privateKey);
    
    const response = await fetch('/api/protected', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        address,
        signature,
        message,
      }),
    });
  };
}