From sigma-auth
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/sigma-auth:bitcoin-auth-diagnosticsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
Use this skill when:
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 signatureExample valid token:
02a1b2c3d4e5f6...|brc77|2025-01-15T14:30:00.123Z|/api/status|dGVzdHNpZ25hdHVyZQ==
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);
}
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);
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)");
}
}
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)
});
Cause: Token doesn't have exactly 5 pipe-delimited parts
Solutions:
Cause: Signature doesn't match the payload
Solutions:
Cause: Token timestamp too far from server time
Solutions:
Cause: Token requestPath doesn't match verification path
Solutions:
Cause: Body used for signing doesn't match verification body
Solutions:
When working with Sigma Auth (auth.sigmaidentity.com), common patterns:
Better Auth / Sigma Plugin issues (403 on token exchange, CSRF/trustedOrigins, callback URL mismatches) are covered in references/common-issues.md under "Better Auth / Sigma Plugin Issues".
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'
});
For detailed API documentation and implementation examples, see:
references/bitcoin-auth-api.md - Complete API referencereferences/common-issues.md - Detailed troubleshooting guidereferences/identity-terminology.md - BAP ID vs BRC-31 identity key terminology matrix@bsv/sdk peer dependencybun add bitcoin-authNever log private keys or WIF strings - Only log public keys, tokens, and diagnostic information.
When diagnosing authentication issues:
npx claudepluginhub b-open-io/claude-plugins --plugin sigma-authImplements JWT authentication with algorithm pinning, short expiry, and server-side validation to prevent token forgery and algorithm confusion attacks.
Tests JWT implementations for algorithm confusion, none algorithm bypass, kid parameter injection, and weak secret exploitation to achieve authentication bypass and privilege escalation.
Tests JWT implementations for vulnerabilities including algorithm confusion, none algorithm bypass, kid injection, and weak secret exploitation during auth audits.