SkillAgentSearch skills...

bitcoin-auth-diagnostics

Diagnose and troubleshoot bitcoin-auth token generation and verification issues. This skill should be used when users encounter authentication failures, signature verification errors, or integration problems with the bitcoin-auth library.

Install / Use

npx skills add Microck/ordinary-claude-skills --skill bitcoin-auth-diagnostics

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Supported Platforms

Universal

Tags

Our assessment of bitcoin-auth-diagnostics

bitcoin-auth-diagnostics scores 90/100 on our quality scale, 1171st of 4,705 Development & Engineering skills we index (top 25%).

Its SKILL.md is 9.5 KB long, well organised into 19 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.

It has 399 GitHub stars, a meaningful sign that others use it.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
11/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 3 months ago, so bitcoin-auth-diagnostics is actively maintained.
  • Our last check on 2026-11-20 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

bitcoin-auth-diagnostics compared with similar skills

All 4 of these similar skills score higher than bitcoin-auth-diagnostics; compare them before choosing.

SkillScoreStarsUpdatedFormat
bitcoin-auth-diagnostics (this skill)by Microck903993mo agoSKILL.md
taste-skillby Leonxlnx100120.0ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md
ai-job-searchby ai-job-search-dev10073.0ktodayCLAUDE.md
claude-howtoby luongnv8910047.5k1d agoCLAUDE.md

Frequently asked questions

How do I install bitcoin-auth-diagnostics?
Run npx skills add Microck/ordinary-claude-skills --skill bitcoin-auth-diagnostics. The install tabs above show the steps for each supported agent.
Which AI agents does bitcoin-auth-diagnostics work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is bitcoin-auth-diagnostics safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is bitcoin-auth-diagnostics still maintained?
The repository was last updated about 3 months ago, so bitcoin-auth-diagnostics is actively maintained.

version: 1.0.0 name: bitcoin-auth-diagnostics description: Diagnose and troubleshoot bitcoin-auth token generation and verification issues. This skill should be used when users encounter authentication failures, signature verification errors, or integration problems with the bitcoin-auth library. location: user

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:

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:

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:

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):

// ❌ 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):

// ✅ 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:

// 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:

// 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

Related Skills

View on GitHub
GitHub Stars399
CategoryDevelopment
Updated2mo ago
Forks53

Languages

Python

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium