AuthFlowOrchestrator

Unified authentication flow manager for intelligent routing through sign in, sign up, or wallet restoration

A comprehensive authentication flow manager that intelligently routes users through sign in, sign up, OAuth restoration, device linking, or file import flows. This component provides a unified entry point for all authentication scenarios with automatic flow detection and seamless transitions.

Installation

npx bigblocks add auth-flow-orchestrator

Import

import { AuthFlowOrchestrator } from 'bigblocks';

Props

Prop	Type	Required	Default	Description
flowType	`AuthFlowType`	No	`'unified'`	Initial flow type
initialStep	`AuthStep`	No	`'initial'`	Starting step in the flow
enableOAuth	`boolean`	No	`true`	Enable OAuth provider options
enableDeviceLink	`boolean`	No	`true`	Enable device linking flow
enableFileImport	`boolean`	No	`true`	Enable file import for backups
enableLocalBackup	`boolean`	No	`true`	Enable local backup storage
enableProfileSync	`boolean`	No	`false`	Enable profile synchronization
maxDiscoveryAttempts	`number`	No	`3`	Max attempts for profile discovery
oauthProviders	`OAuthProvider[]`	No	-	Custom OAuth provider configuration
onSuccess	`(user: {id: string, address: string}) => void`	No	-	Success callback
onError	`(error: string) => void`	No	-	Error callback
onFlowChange	`(flow: AuthFlowType) => void`	No	-	Flow change callback
onStepChange	`(step: AuthStep) => void`	No	-	Step change callback
title	`string`	No	-	Custom title
subtitle	`string`	No	-	Custom subtitle
showHeader	`boolean`	No	`true`	Show header section
showFooter	`boolean`	No	`true`	Show footer section
className	`string`	No	-	Additional CSS classes
layout	`'centered' \| 'full' \| 'custom'`	No	`'centered'`	Layout style
customLayout	`React.ComponentType`	No	-	Custom layout component
autoDetectFlow	`boolean`	No	`true`	Auto-detect best flow
persistFlow	`boolean`	No	`true`	Persist flow state
debug	`boolean`	No	`false`	Enable debug mode

Flow Types

type AuthFlowType = 
  | 'unified'      // Auto-detect best flow
  | 'signin'       // Direct sign in
  | 'signup'       // New account creation
  | 'oauth-restore' // Restore via OAuth
  | 'device-link'  // Link new device
  | 'import'       // Import backup file
  | 'custom';      // Custom flow

Auth Steps

type AuthStep = 
  | 'initial'           // Starting point
  | 'signin'           // Sign in form
  | 'signup'           // Sign up form
  | 'password'         // Password entry
  | 'confirm-password' // Password confirmation
  | 'backup-display'   // Show backup
  | 'backup-download'  // Download backup
  | 'oauth-link'       // Link OAuth provider
  | 'oauth-restore'    // Restore from OAuth
  | 'import-backup'    // Import backup file
  | 'success';         // Success state

Basic Usage

import { AuthFlowOrchestrator, BitcoinAuthProvider } from 'bigblocks';
import { useRouter } from 'next/navigation';

export default function AuthPage() {
  const router = useRouter();

  return (
    <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
      <AuthFlowOrchestrator
        onSuccess={(user) => {
          console.log('Auth successful:', user);
          router.push('/dashboard');
        }}
        onError={(error) => {
          console.error('Auth failed:', error);
        }}
      />
    </BitcoinAuthProvider>
  );
}

Advanced Usage

Specific Flow Type

import { AuthFlowOrchestrator } from 'bigblocks';

export default function SignUpOnly() {
  return (
    <AuthFlowOrchestrator
      flowType="signup"
      autoDetectFlow={false}
      onSuccess={(user) => {
        console.log('New user created:', user);
      }}
    />
  );
}

Custom OAuth Providers

import { AuthFlowOrchestrator } from 'bigblocks';
import { FaGoogle, FaGithub } from 'react-icons/fa';

export default function CustomOAuth() {
  const customProviders = [
    {
      id: 'google',
      name: 'Google',
      icon: <FaGoogle />
    },
    {
      id: 'github', 
      name: 'GitHub',
      icon: <FaGithub />
    }
  ];

  return (
    <AuthFlowOrchestrator
      oauthProviders={customProviders}
      enableOAuth={true}
      onSuccess={(user) => {
        console.log('OAuth auth successful');
      }}
    />
  );
}

Track Flow Progress

import { AuthFlowOrchestrator } from 'bigblocks';
import { useState } from 'react';

export default function TrackedAuth() {
  const [currentFlow, setCurrentFlow] = useState<AuthFlowType>('unified');
  const [currentStep, setCurrentStep] = useState<AuthStep>('initial');

  return (
    <div>
      <div className="mb-4">
        <p>Current Flow: {currentFlow}</p>
        <p>Current Step: {currentStep}</p>
      </div>
      
      <AuthFlowOrchestrator
        onFlowChange={setCurrentFlow}
        onStepChange={setCurrentStep}
        onSuccess={(user) => {
          analytics.track('auth_completed', {
            flow: currentFlow,
            userId: user.id
          });
        }}
      />
    </div>
  );
}

Custom Layout

import { AuthFlowOrchestrator } from 'bigblocks';

const CustomAuthLayout = ({ children }) => (
  <div className="custom-auth-container">
    <div className="auth-branding">
      <img src="/logo.png" alt="Logo" />
    </div>
    <div className="auth-content">
      {children}
    </div>
  </div>
);

export default function CustomLayoutAuth() {
  return (
    <AuthFlowOrchestrator
      layout="custom"
      customLayout={CustomAuthLayout}
      showHeader={false}
      onSuccess={(user) => {
        console.log('Auth completed');
      }}
    />
  );
}

Debug Mode

import { AuthFlowOrchestrator } from 'bigblocks';

export default function DebugAuth() {
  return (
    <AuthFlowOrchestrator
      debug={true}
      onSuccess={(user) => {
        console.log('Debug auth successful:', user);
      }}
      onError={(error) => {
        console.error('Debug auth error:', error);
      }}
    />
  );
}

Common Patterns

With Loading State

import { AuthFlowOrchestrator } from 'bigblocks';
import { useEffect, useState } from 'react';

export function SmartAuth() {
  const [hasExistingBackup, setHasExistingBackup] = useState(false);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // Check for existing backup
    const backup = localStorage.getItem('encryptedBackup');
    setHasExistingBackup(!!backup);
    setLoading(false);
  }, []);

  if (loading) {
    return <div>Loading...</div>;
  }

  return (
    <AuthFlowOrchestrator
      flowType={hasExistingBackup ? 'signin' : 'signup'}
      autoDetectFlow={false}
      onSuccess={(user) => {
        console.log('Auth successful');
      }}
    />
  );
}

import { AuthFlowOrchestrator } from 'bigblocks';
import { Modal } from '@radix-ui/themes';

export function AuthModal({ isOpen, onClose }) {
  return (
    <Modal open={isOpen} onOpenChange={onClose}>
      <Modal.Content maxWidth="450px">
        <AuthFlowOrchestrator
          layout="full"
          showHeader={false}
          onSuccess={(user) => {
            console.log('Modal auth successful');
            onClose();
          }}
        />
      </Modal.Content>
    </Modal>
  );
}

Profile Sync Enabled

import { AuthFlowOrchestrator } from 'bigblocks';

export function ProfileSyncAuth() {
  return (
    <AuthFlowOrchestrator
      enableProfileSync={true}
      maxDiscoveryAttempts={5}
      onSuccess={(user) => {
        console.log('Auth with profile sync completed');
      }}
    />
  );
}

Flow Behavior

Unified Flow (Default)

Detects if user has existing backup
Routes to appropriate flow automatically
Seamless transitions between states

Password entry
Backup decryption
Identity verification
Success

Identity generation
Password creation
Backup creation
Download/save backup
Optional OAuth linking
Success

OAuth Restore Flow

Select OAuth provider
Authenticate with provider
Retrieve encrypted backup
Decrypt with password
Success

Device Link Flow

Generate device link code
Scan QR or enter code
Authorize on primary device
Sync backup to new device
Success

Troubleshooting

Flow Not Auto-Detecting

Check that autoDetectFlow is enabled
Verify local storage is accessible
Ensure BitcoinAuthProvider is properly configured

OAuth Not Working

Verify OAuth providers are configured in your backend
Check that enableOAuth is true
Ensure callback URLs are properly set

Custom Layout Issues

Layout component must accept children prop
Ensure proper CSS/styling is applied
Check that layout prop is set to 'custom'

LoginForm - Standalone login form
SignupFlow - Signup flow component
OAuthRestoreFlow - OAuth restoration
BackupImport - File import component
DeviceLinkQR - Device linking QR

API Reference

Success Callback

The onSuccess callback receives a user object:

{
  id: string;      // User's BAP ID
  address: string; // Bitcoin address
}

Error Handling

Errors are passed as strings to the onError callback. Common error types:

'USER_EXISTS' - Account already exists
'INVALID_PASSWORD' - Incorrect password
'INVALID_BACKUP' - Corrupted backup file
'OAUTH_FAILED' - OAuth authentication failed
'DEVICE_LINK_FAILED' - Device linking failed

Flow State

The component manages internal state including:

Current flow type
Current step
Form data
Error states
Loading states

Notes for Improvement

Implementation Note: The prompt described props like mode, allowModeSwitch, showOAuthProviders, and customSteps which don't exist in the actual implementation. The actual component uses flowType, enableOAuth, and other boolean flags for configuration. The component is more feature-rich than the prompt suggested, with support for device linking, profile sync, and debug mode.

AuthFlowOrchestrator

On this page