bitcoin-auth-diagnostics

# Bitcoin Auth Diagnostics

## Overview

This skill enables comprehensive diagnosis of bitcoin-auth authentication issues across client and server implementations. Use this skill when encountering token generation failures, signature verification errors, or integration problems with the bitcoin-auth library.

## When to Use This Skill

Use this skill when:
- Bitcoin auth token verification is failing
- Investigating "invalid signature" or "invalid token" errors
- Debugging integration with bitcoin-auth in APIs (especially Sigma Auth)
- Token generation produces unexpected results
- Time skew or timestamp-related authentication failures occur
- Body hash mismatches are suspected
- Scheme confusion between bsm and brc77 exists

## Bitcoin Auth Token Format

All bitcoin-auth tokens follow this pipe-delimited format:

```
pubkey|scheme|timestamp|requestPath|signature
```

**Components:**
- `pubkey`: Hex-encoded public key (66 characters)
- `scheme`: Either `bsm` (legacy) or `brc77` (recommended)
- `timestamp`: ISO8601 format (e.g., `2025-01-15T14:30:00.000Z`)
- `requestPath`: Full path including query parameters (e.g., `/api/endpoint?param=value`)
- `signature`: Base64-encoded signature

**Example valid token:**
```
02a1b2c3d4e5f6...|brc77|2025-01-15T14:30:00.123Z|/api/status|dGVzdHNpZ25hdHVyZQ==
```

## Diagnostic Workflow

### Step 1: Token Structure Validation

First, validate the token structure before checking cryptographic validity:

```typescript
import { parseAuthToken } from 'bitcoin-auth';

const token = "..."; // The failing token
const parsed = parseAuthToken(token);

if (!parsed) {
  console.error("FAILED: Token structure is invalid");
  // Check: Does token have exactly 5 pipe-delimited parts?
  const parts = token.split('|');
  console.log(`Token has ${parts.length} parts (expected 5)`);
  console.log("Parts:", parts);

  // Common issues:
  // - Missing parts (incomplete token)
  // - Extra pipes in requestPath or other fields
  // - Invalid scheme (not 'bsm' or 'brc77')
} else {
  console.log("✅ Token structure is valid");
  console.log("Parsed token:", parsed);
}
```

### Step 2: Component Validation

Validate each component individually:

```typescript
const { pubkey, scheme, timestamp, requestPath, signature } = parsed;

// Validate public key
console.log("Public key length:", pubkey.length); // Should be 66 chars
console.log("Public key starts with 02/03:", pubkey.startsWith('02') || pubkey.startsWith('03'));

// Validate scheme
console.log("Scheme:", scheme); // Must be 'bsm' or 'brc77'

// Validate timestamp
const tokenTime = new Date(timestamp);
console.log("Token timestamp:", tokenTime.toISOString());
console.log("Current time:", new Date().toISOString());
console.log("Age (minutes):", (Date.now() - tokenTime.getTime()) / 60000);
// Default timePad is 5 minutes - token older than 5 minutes will fail

// Validate request path
console.log("Request path:", requestPath);
// Must match EXACTLY including query parameters and their order

// Validate signature
console.log("Signature (base64):", signature);
console.log("Signature length:", signature.length);
```

### Step 3: Signature Verification

If structure is valid, diagnose verification failures:

```typescript
import { verifyAuthToken } from 'bitcoin-auth';
import type { AuthPayload } from 'bitcoin-auth';

const authPayload: AuthPayload = {
  requestPath: "/api/endpoint?param=value", // Must match token exactly
  timestamp: new Date().toISOString(),       // Server's current time
  body: requestBody // Optional, must match if token was signed with body
};

const isValid = verifyAuthToken(
  token,
  authPayload,
  5,        // timePad in minutes (default 5)
  'utf8'    // bodyEncoding: 'utf8', 'hex', or 'base64'
);

if (!isValid) {
  console.error("FAILED: Signature verification failed");

  // Diagnose specific failures:

  // 1. Request path mismatch
  if (parsed.requestPath !== authPayload.requestPath) {
    console.error("❌ Request path mismatch:");
    console.error("  Token path:", parsed.requestPath);
    console.error("  Verify path:", authPayload.requestPath);
    // Common issue: Query parameter order differs
  }

  // 2. Timestamp issues
  const tokenTimestamp = new Date(parsed.timestamp);
  const targetTime = new Date(authPayload.timestamp);
  targetTime.setMinutes(targetTime.getMinutes() + 5); // Add timePad
  if (tokenTimestamp > targetTime) {
    console.error("❌ Token timestamp too far in future");
    console.error("  Token time:", tokenTimestamp.toISOString());
    console.error("  Target time:", targetTime.toISOString());
  }

  // 3. Body hash mismatch
  if (authPayload.body) {
    console.log("Verifying with body present");
    console.log("  Body encoding:", 'utf8'); // Check encoding matches
    console.log("  Body length:", authPayload.body.length);
    // Try different encodings if utf8 fails
  }

  // 4. Scheme-specific issues
  if (parsed.scheme === 'bsm') {
    console.log("Using legacy BSM signature scheme");
    // BSM uses different signature format than BRC77
  } else {
    console.log("Using BRC77 signature scheme (recommended)");
  }
}
```

### Step 4: Common Integration Issues

Check for common integration mistakes:

**Server-side (verification):**
```typescript
// ❌ WRONG: Using token's timestamp (defeats the purpose)
const authPayload = {
  requestPath,
  timestamp: parsedToken.timestamp, // DON'T DO THIS
  body
};

// ✅ CORRECT: Use server's current time
const serverTime = new Date().toISOString();
const authPayload = {
  requestPath,
  timestamp: serverTime,
  body
};
```

**Client-side (generation):**
```typescript
// ✅ Token generation
import { getAuthToken } from 'bitcoin-auth';

const token = getAuthToken({
  privateKeyWif,
  requestPath: '/api/endpoint?param=value', // Include full path with query
  body: JSON.stringify(requestBody),        // If POST/PUT with body
  scheme: 'brc77',                          // Default, recommended
  bodyEncoding: 'utf8'                      // Default
});

// Include in request headers
fetch(url + requestPath, {
  method: 'POST',
  headers: {
    'X-Auth-Token': token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestBody)
});
```

## Common Error Patterns

### "Invalid bitcoin-auth token format"

**Cause**: Token doesn't have exactly 5 pipe-delimited parts

**Solutions:**
- Check token isn't truncated or corrupted
- Verify no extra pipes in requestPath or signature
- Ensure token is properly URL-encoded if passed in query params

### "Bitcoin signature verification failed"

**Cause**: Signature doesn't match the payload

**Solutions:**
1. Verify request path matches exactly (including query params)
2. Check timestamp isn't older than timePad (default 5 minutes)
3. Ensure body hash matches (if body present)
4. Confirm correct bodyEncoding (utf8, hex, base64)
5. Verify scheme matches (bsm vs brc77)

### "Invalid token: time skew"

**Cause**: Token timestamp too far from server time

**Solutions:**
- Increase timePad parameter (default 5 minutes)
- Check client/server clock synchronization
- Verify timestamp format is ISO8601

### "Request path mismatch"

**Cause**: Token requestPath doesn't match verification path

**Solutions:**
- Include full path with query parameters
- Ensure query parameter order is consistent
- Don't include domain/protocol in requestPath
- Match case sensitivity

### "Body hash mismatch"

**Cause**: Body used for signing doesn't match verification body

**Solutions:**
- Use exact same body string (not re-serialized JSON)
- Check bodyEncoding matches (utf8, hex, base64)
- Verify body isn't modified between signing and verification
- Ensure Content-Type header matches body encoding

## Integration with Sigma Auth

When working with Sigma Auth (auth.sigmaidentity.com), common patterns:

**Token verification endpoint:**
```typescript
// POST /api/auth/token-for-endpoint
// Body: { authToken: "...", requestBody: "..." }

// Server parses and verifies:
const parsed = parseAuthToken(authToken);
const authPayload = {
  requestPath: "/api/auth/token-for-endpoint",
  timestamp: new Date().toISOString(),
  body: requestBody
};
const isValid = verifyAuthToken(authToken, authPayload);
```

**Wallet connect flow:**
```typescript
// Uses BSM scheme for compatibility
const token = getAuthToken({
  privateKeyWif,
  requestPath: "/wallet/connect",
  scheme: 'bsm'
});
```

## Reference Documentation

For detailed API documentation and implementation examples, see:
- `references/bitcoin-auth-api.md` - Complete API reference
- `references/common-issues.md` - Detailed troubleshooting guide
- Bitcoin Auth GitHub: https://github.com/b-open-io/bitcoin-auth
- BRC-77 Specification: https://github.com/bitcoin-sv/BRCs/blob/master/peer-to-peer/0077.md

## Environment Requirements

- Node.js/Bun runtime with `@bsv/sdk` peer dependency
- bitcoin-auth library installed: `bun add bitcoin-auth`
- For testing: Access to bitcoin-auth repository test suite

## Security Considerations

**Never log private keys or WIF strings** - Only log public keys, tokens, and diagnostic information.

When diagnosing authentication issues:
- Use test/development keys for diagnostics
- Sanitize logs before sharing (remove signatures/private data)
- Verify token expiry (timePad) is appropriate for your use case
- Use BRC77 scheme (default) for new implementations