Sigma Auth provides a secure cross-device backup and restore system that allows users to access their Bitcoin identity from any device using OAuth credentials and a backup password.

How It Works

Initial Setup

1. Authenticate with Bitcoin using your private key
2. Link OAuth accounts (Google, GitHub) to your Bitcoin identity
3. Encrypted backups are automatically stored when you link accounts

Restore from Another Device

1. Visit OAuth restore page (/oauth-restore)
2. Select your provider (Google or GitHub)
3. Complete OAuth flow - no Bitcoin key needed
4. Enter your password to decrypt the backup client-side
5. Wallet restored - you're logged in with your Bitcoin identity

This allows you to access your Bitcoin identity from any device using just your OAuth credentials and backup password.

Security Model

Client-Side Encryption

• All encryption happens in your browser - never on servers
• Your backup password never leaves your device
• Private keys are encrypted before transmission
• Only you can decrypt your backup

Backup Storage

• Encrypted blobs stored in Cloudflare KV
• 10-year retention period
• Automatic cleanup of expired backups
• No personally identifiable information stored

Access Control

• OAuth provider verification required
• Backup password required for decryption
• Rate limiting on restore attempts
• Audit logs for security monitoring

Backup Types Supported

Standard Formats

• WIF Keys: Wallet Import Format private keys
• BIP32 Seeds: Hierarchical deterministic wallet seeds
• JSON Backups: Structured backup format with metadata

Provider-Specific

• BAP Backups: Bitcoin Attestation Protocol identity data
• OneSat Backups: 1Sat Ordinals wallet format
• Custom Formats: Extensible for additional wallet types

Best Practices

For Users

• Use a strong backup password - at least 12 characters
• Store your backup password securely - in a password manager
• Test restore process on a secondary device
• Link multiple OAuth providers for redundancy

For Developers

• Encourage backup creation during onboarding
• Provide clear backup status indicators
• Test restore flows regularly
• Monitor backup success rates

Implementation

Using the bitcoin-backup Package

The backup system is powered by the bitcoin-backup npm package:

npm install bitcoin-backup

import { 
  encryptBackup, 
  decryptBackup,
  type WifBackup,
  type BapMasterBackup
} from 'bitcoin-backup';

// Encrypt a WIF private key
const wifBackup: WifBackup = {
  wif: privateKeyWif,
  label: 'My Bitcoin Wallet',
  createdAt: new Date().toISOString()
};
const encrypted = await encryptBackup(
  wifBackup,
  password,
  600000 // optional iterations count (default: 600,000)
);

// Or encrypt a BAP Type 42 backup
const bapBackup: BapMasterBackup = {
  ids: 'encrypted-bap-data',
  rootPk: 'L5EZftvrYaSudiozVRzTqLcHLNDoVn7H5HSfM9BAN6tMJX8oTWz6',
  label: 'My BAP Identity'
};
const encryptedBap = await encryptBackup(bapBackup, password);

// Decrypt a backup (automatically detects format)
try {
  const decrypted = await decryptBackup(encrypted, password);
  // Check the type of backup
  if ('wif' in decrypted && !('id' in decrypted)) {
    // It's a WifBackup
    const privateKey = decrypted.wif;
    console.log('WIF backup restored successfully');
  }
} catch (error) {
  console.error('Invalid password or corrupted backup');
}

Automatic Backup Creation

When a user links an OAuth account to their Bitcoin identity, Sigma Auth automatically:

1. Encrypts their private key using their chosen password via encryptBackup()
2. Stores the encrypted backup linked to their OAuth identity
3. Confirms successful backup to the user
4. Updates their profile to indicate backup availability

Manual Backup Management

Users can also:

• Download encrypted backups for offline storage
• Import existing backups from other systems
• Update backup passwords when needed
• Delete backups to revoke access

Error Handling

Common Issues

• Wrong backup password: Clear error message, retry allowed
• Corrupted backup: Fallback to manual key entry
• OAuth provider issues: Alternative provider options
• Network failures: Automatic retry with exponential backoff

Recovery Options

• Manual private key entry if backup restoration fails
• Alternative OAuth providers if primary is unavailable
• Support contact for complex recovery scenarios
• Backup validation before encryption

Privacy Considerations

Data Minimization

• Only encrypted key data stored - no personal information
• OAuth identity mapping uses opaque identifiers
• Automatic data expiration after 10 years
• No usage tracking or analytics

User Control

• Complete data portability through backup downloads
• Instant deletion of all stored data
• No vendor lock-in - backups work with any compatible system
• Full transparency about what data is stored

Resources

Documentation

• OAuth Restore Guide - Step-by-step restore process
• Security Details - Technical security implementation
• Integration Guide - Add backup to your app

bitcoin-backup Package

• NPM Package - Install and API documentation
• GitHub Repository - Source code and examples
• TypeScript Support - Full type definitions included

API Reference

import { 
  encryptBackup,      // Encrypt a backup object with password
  decryptBackup,      // Decrypt an encrypted backup
  // TypeScript types for different backup formats:
  type BapMasterBackup,   // BAP Type 42 or legacy format
  type BapMemberBackup,   // BAP member key backup
  type WifBackup,         // Simple WIF key backup
  type OneSatBackup,      // 1Sat Ordinals wallet backup
  type DecryptedBackup,   // Union type of all backup formats
  // PBKDF2 iteration constant:
  DEFAULT_PBKDF2_ITERATIONS      // 600,000
} from 'bitcoin-backup';