Bitcoin authentication leverages the same cryptographic principles that secure the Bitcoin network - ECDSA signatures on the secp256k1 curve. Instead of passwords, users prove ownership of their identity through cryptographic signatures.

Sigma Auth uses the bitcoin-auth library for all Bitcoin cryptographic operations.

Installation

Install the bitcoin-auth library to get started:

npm install bitcoin-auth

How Bitcoin Authentication Works

The Authentication Process

1. Key Generation

Users generate or import a Bitcoin keypair:

import { PrivateKey } from '@bsv/sdk';

// Generate new keypair
const privateKey = PrivateKey.fromRandom();
const publicKey = privateKey.toPublicKey();

// Both of these return the address as a string:
const address = privateKey.toAddress(); // Returns string directly
// or
const addressFromPubKey = publicKey.toAddress(); // Also returns string directly

console.log('Private Key (WIF):', privateKey.toWif());
console.log('Public Key:', publicKey.toString());
console.log('Address:', address); // Already a string, no need for .toString()

2. Token Generation

The client creates an authentication token:

import { getAuthToken } from 'bitcoin-auth';

const authToken = getAuthToken({
    privateKeyWif: privateKey.toWif(),
    requestPath: '/sigma/authorize'
});

3. Server Verification

The server verifies the signature:

import { verifyAuthToken, parseAuthToken } from 'bitcoin-auth';

// Parse the token to get timestamp and other data
const parsed = parseAuthToken(authToken);

const authPayload = {
    requestPath: '/sigma/authorize',
    timestamp: parsed.timestamp
};

const isValid = verifyAuthToken(authToken, authPayload);

if (isValid) {
    // Token is valid, user is authenticated
    console.log('Authentication successful');
}

Security Properties

Mathematical Foundation

Bitcoin authentication is based on the Elliptic Curve Digital Signature Algorithm (ECDSA):

• Private Key: A 256-bit random number (k)
• Public Key: k × G (where G is the generator point)
• Signature: Proves knowledge of k without revealing it

Security Guarantees

Cryptographic Proof: Each signature mathematically proves the signer controls the private key without revealing it.

Replay Protection: Timestamps ensure signatures can't be reused beyond a time window.

Request Binding: Signatures include the request path, preventing signature reuse across different endpoints.

No Server Secrets: Private keys never leave the client, eliminating server-side credential theft.

Key Formats

Wallet Import Format (WIF)

Most common format for private keys:

// Mainnet WIF (starts with 'K' or 'L')
const wif = 'KxFC1jmwwCoACiCAWZ3eXa96mBM6tb3TYzGmf6YwgdGWZgawvrtJ';

// Testnet WIF (starts with 'c')
const testnetWif = 'cMsFwXXjC9nLrTAg8Y1SxdgfkF9MNsqgdGQYWrD9mZr8qfM4Wrhe';

Bitcoin Attestation Protocol (BAP)

BAP provides decentralized identity management on the Bitcoin blockchain:

BAP Structure

// BAP Identity
const bapIdentity = {
    identityKey: '0x...',  // Root identity key
    currentKey: '0x...',   // Current signing key
    profile: {
        name: 'John Doe',
        email: 'john@example.com',
        avatar: 'https://...',
        bio: 'Software developer'
    },
    attestations: [
        {
            field: 'email',
            value: 'john@example.com',
            verifier: '0x...',
            signature: '0x...'
        }
    ]
};

BAP Integration

Sigma Auth automatically fetches BAP profiles:

// When user authenticates, server looks up BAP profile
const bapProfile = await fetchBAPProfile(publicKey);

const userSession = {
    address: publicKey.toAddress(),
    publicKey: publicKey.toString(),
    profile: bapProfile || null
};

Usage with API Request

import { getAuthToken } from 'bitcoin-auth';

// Make authenticated request to Sigma Auth
const authToken = getAuthToken({
    privateKeyWif: privateKey.toWif(),
    requestPath: '/sigma/authorize'
});

const response = await fetch('https://auth.sigmaidentity.com/sigma/authorize', {
    method: 'POST',
    headers: {
        'X-Auth-Token': authToken,
        'Content-Type': 'application/json'
    }
});

if (response.ok) {
    const userData = await response.json();
    console.log('Authenticated user:', userData);
}

Security Considerations

Client-Side Security

Private Key Storage: Never store private keys in localStorage. Use sessionStorage, encrypted storage, or hardware wallets.

Memory Management: Clear sensitive data from memory when possible.

Secure Transmission: Always use HTTPS to prevent man-in-the-middle attacks.

Server-Side Security

Signature Verification: Always verify signatures server-side, never trust client claims.

Time Window Validation: Implement reasonable time windows (5-10 minutes) for timestamp validation.

Rate Limiting: Implement rate limiting to prevent brute force attacks.

Best Practices

1. Use Hardware Wallets for high-value applications
2. Implement Key Rotation for long-lived applications
3. Monitor for Suspicious Activity (multiple failed attempts)
4. Backup Key Management (encrypted backup solutions)
5. Multi-Factor Authentication (combine with other factors for sensitive operations)

Token Format

The getAuthToken function returns a token string in the format:

sigma:address:timestamp:pubkey:signature

Where:

• sigma: Authentication scheme identifier
• address: Bitcoin address derived from the public key
• timestamp: ISO timestamp when token was generated
• pubkey: Compressed public key in hex format
• signature: Base64-encoded signature

Library Reference

For complete API documentation and examples, see the bitcoin-auth GitHub repository.

Key Functions

• getAuthToken(options) - Generate authentication token
• verifyAuthToken(token, payload) - Verify token signature
• parseAuthToken(token) - Parse token components

Resources

• GitHub Repository - Source code and documentation
• NPM Package - Install via npm
• API Examples - Usage examples and patterns