Sigma Auth
Key Backup

The OAuth restore process allows users to regain access to their Bitcoin identity on any device using just their OAuth credentials and backup password.

Prerequisites

Before starting the restore process, ensure:

  • You have previously linked an OAuth account (Google/GitHub) to your Bitcoin identity
  • You remember your backup password used during the initial backup
  • You have access to your OAuth provider account

Step-by-Step Restore

1. Navigate to Restore Page

Visit the OAuth restore page in your application:

  • Direct URL: /oauth-restore
  • From login page: Click "Restore from Backup" link

2. Select OAuth Provider

Choose the OAuth provider you previously linked:

  • Google - if you linked your Google account
  • GitHub - if you linked your GitHub account
  • Multiple options - if you linked both providers

3. Complete OAuth Flow

  1. Click your provider (Google or GitHub)
  2. Sign in to your OAuth account if not already logged in
  3. Grant permissions to access your linked identity
  4. Return to the app with your OAuth identity confirmed

4. Enter Backup Password

  1. Password prompt appears after successful OAuth verification
  2. Enter the same password you used when creating the backup
  3. Click "Restore Wallet" to decrypt your private key
  4. Wait for decryption - this happens in your browser using bitcoin-backup

The decryption process uses the bitcoin-backup package:

import { decryptBackup } from 'bitcoin-backup';

try {
  // Decrypt the backup fetched via OAuth
  const privateKey = await decryptBackup(encryptedBackup, password);
  
  // Success - user is now authenticated
  console.log('Identity restored successfully');
} catch (error) {
  // Invalid password or corrupted backup
  console.error('Restoration failed:', error.message);
}

5. Successful Restore

Upon successful restoration:

  • Your Bitcoin identity is loaded into the current session
  • You're automatically logged in to the application
  • Your private key is available for signing operations
  • Backup remains available for future use on other devices

Troubleshooting

"Backup not found"

Cause: No backup exists for this OAuth account Solution:

  • Try a different OAuth provider
  • Check if you used a different account
  • Create a new Bitcoin identity if needed

"Invalid backup password"

Cause: Entered password doesn't match the backup Solution:

  • Try alternative passwords you might have used
  • Check for typos or caps lock
  • Consider password variations you commonly use

"Backup corrupted"

Cause: Stored backup data is damaged Solution:

  • Try restoring from a different device
  • Contact support if backup was recently created
  • Fall back to manual private key entry

"OAuth provider error"

Cause: Issue with Google/GitHub authentication Solution:

  • Try logging out and back in to your OAuth provider
  • Clear browser cookies and try again
  • Try a different OAuth provider if available

Security Considerations

Browser Security

  • Decryption happens locally - your password never leaves your device
  • Use a secure network when performing restore operations
  • Close browser tabs containing sensitive information after restore
  • Use private/incognito mode on shared computers

Password Management

  • Use unique backup passwords - don't reuse other passwords
  • Store passwords securely - in a password manager if possible
  • Never share backup passwords with anyone
  • Update passwords periodically if you suspect compromise

Account Security

  • Enable 2FA on your OAuth provider accounts
  • Monitor OAuth account activity for suspicious logins
  • Revoke access if you no longer use the application
  • Use strong OAuth passwords as they protect your Bitcoin identity

Multiple Device Workflow

Scenario: New Phone Setup

  1. Install your app on the new device
  2. Visit OAuth restore page instead of creating new identity
  3. Use Google/GitHub login to verify your identity
  4. Enter backup password to decrypt your Bitcoin keys
  5. Continue using your existing Bitcoin identity seamlessly

Scenario: Computer Replacement

  1. Open your app in a new browser
  2. Choose "Restore from Backup" on the login screen
  3. Authenticate with OAuth to confirm your identity
  4. Decrypt backup with your password
  5. Access your Bitcoin identity immediately

Advanced Options

Manual Backup Import

If automatic restore fails, you can manually import backups:

  1. Download your encrypted backup from a working device
  2. Use "Import Backup File" option on the restore page
  3. Select your backup file and enter your password
  4. Verify successful import and test functionality

Provider Switching

To change your primary OAuth provider:

  1. Restore using current provider to access your identity
  2. Link additional OAuth accounts from within the app
  3. Test restore with the new provider
  4. Optionally unlink the old provider

Backup Verification

To verify your backup before needing it:

  1. Use a different browser/device to test restore
  2. Complete the OAuth flow with your linked account
  3. Enter your backup password to verify it works
  4. Confirm your Bitcoin identity loads correctly
  5. Log out without making changes

Next Steps

Key Backup Overview

Secure cross-device Bitcoin key backup and restore system

Key Backup Security

Technical security implementation details for the Bitcoin key backup system