BitcoinAuthProvider

Core provider component that manages Bitcoin-based authentication state and context throughout the application

Core provider component that manages Bitcoin-based authentication state and context throughout the application. This provider wraps your app to enable Bitcoin authentication flows, session management, and user state tracking.

Demo

Demo NoteThis demonstrates the BitcoinAuthProvider context. The provider wraps your entire app to provide authentication state and actions to all child components.

Live Provider Context

Authentication State

Authenticated:No

Loading:No

User:None

Profiles:0 profiles

Provider Configuration

App ID: demo-app-123API URL: https://api.bigblocks.ioStorage: BigBlocks MemoryStorage

API Reference

This component extends the React Context API for state management and uses AuthManager for core authentication logic.

Overview

The BitcoinAuthProvider is the foundation of BigBlocks authentication. It creates a React context that provides authentication state and actions to all child components, enabling seamless Bitcoin-based authentication throughout your application.

Key Features

Centralized Auth State: Manages user authentication status, profile data, and session information
Real-time Updates: Automatically updates components when authentication state changes
Event System: Subscribes to authentication events (login, logout, errors, OAuth linking)
Custom Messages: Supports customizable UI messages for authentication flows
Legacy Compatibility: Maintains backward compatibility with previous API versions

Props

config

Type: BitcoinAuthConfig
Required: Yes
Description: Configuration object for Bitcoin authentication

interface BitcoinAuthConfig {
  apiUrl?: string;           // BigBlocks API base URL
  appId: string;            // Your application ID
  redirectUrl?: string;     // OAuth redirect URL
  storage?: 'localStorage' | 'sessionStorage' | 'memory';
  debug?: boolean;          // Enable debug logging
}

children

Type: React.ReactNode
Required: Yes
Description: Child components that will have access to auth context

messages

Type: Partial<AuthMessages>
Required: No
Description: Custom messages for authentication UI elements

interface AuthMessages {
  signIn: string;
  signUp: string;
  signOut: string;
  loading: string;
  error: string;
  // ... more message keys
}

Context Value

The provider exposes the following through React context:

Authentication State

isAuthenticated: boolean - Whether user is logged in
user: User | null - Current user data
profile: Profile | null - Current active profile
profiles: Profile[] - All user profiles
isLoading: boolean - Loading state
error: string | null - Current error message

Authentication Actions

signIn() - Initiate sign-in flow
signUp() - Initiate sign-up flow
signOut() - Sign out current user
selectProfile(id) - Switch active profile
linkOAuth(provider) - Link OAuth provider

Configuration

config: BitcoinAuthConfig - The configuration object passed to provider

Usage

Basic Setup

import { BitcoinAuthProvider } from 'bigblocks';

const config = {
  appId: 'your-app-id',
  apiUrl: 'https://api.bigblocks.io',
  redirectUrl: window.location.origin + '/auth/callback'
};

function App() {
  return (
    <BitcoinAuthProvider config={config}>
      <YourApp />
    </BitcoinAuthProvider>
  );
}

With Custom Messages

const customMessages = {
  signIn: 'Connect Bitcoin Wallet',
  signUp: 'Create Bitcoin Account',
  loading: 'Connecting to Bitcoin network...',
  error: 'Bitcoin connection failed'
};

<BitcoinAuthProvider 
  config={config} 
  messages={customMessages}
>
  <YourApp />
</BitcoinAuthProvider>

Accessing Context

import { useBitcoinAuth } from 'bigblocks';

function AuthButton() {
  const { isAuthenticated, user, signIn, signOut } = useBitcoinAuth();

  if (isAuthenticated) {
    return (
      <div>
        <span>Welcome, {user?.name}</span>
        <button onClick={signOut}>Sign Out</button>
      </div>
    );
  }

  return <button onClick={signIn}>Sign In</button>;
}

Event Handling

The provider automatically handles authentication events:

// Events are handled internally and update component state
// You can access the current state through the context

useEffect(() => {
  if (isAuthenticated) {
    console.log('User signed in:', user);
  }
}, [isAuthenticated, user]);

Configuration Examples

Development Setup

const devConfig = {
  appId: 'dev-app-123',
  apiUrl: 'http://localhost:3000/api',
  storage: 'sessionStorage',
  debug: true
};

Production Setup

const prodConfig = {
  appId: process.env.NEXT_PUBLIC_BIGBLOCKS_APP_ID,
  apiUrl: 'https://api.bigblocks.io',
  redirectUrl: 'https://yourapp.com/auth/callback',
  storage: 'localStorage'
};

Memory-Only (Testing)

const testConfig = {
  appId: 'test-app',
  storage: 'memory', // No persistence
  debug: true
};

Integration with Other Providers

With Theme Provider

<ThemeProvider>
  <BitcoinAuthProvider config={config}>
    <BitcoinThemeProvider>
      <YourApp />
    </BitcoinThemeProvider>
  </BitcoinAuthProvider>
</ThemeProvider>

With Query Provider

<QueryClientProvider client={queryClient}>
  <BitcoinAuthProvider config={config}>
    <YourAuthenticatedApp />
  </BitcoinAuthProvider>
</QueryClientProvider>

Security Considerations

Always use HTTPS in production
Store sensitive config in environment variables
Use appropriate storage option for your security requirements
Validate redirect URLs to prevent attacks

Troubleshooting

Provider Not Found Error

Error: useBitcoinAuth must be used within a BitcoinAuthProvider

Ensure your component is wrapped with BitcoinAuthProvider:

// ❌ Wrong
<YourComponent /> // Will throw error

// ✅ Correct  
<BitcoinAuthProvider config={config}>
  <YourComponent />
</BitcoinAuthProvider>

Authentication Not Working

Check your appId is correct
Verify apiUrl is accessible
Ensure redirectUrl matches your OAuth settings
Check browser console for network errors

Installation

npm install bigblocks

AuthButton - Authentication buttons
AuthManager - Core authentication logic
useBitcoinAuth - Authentication hook
AuthLayout - Authentication layouts

BitcoinAuthProvider

On this page