feat: enhanced debug logging for authentication flow troubleshooting

[ryanRfox]

Summary

Implements comprehensive debug logging capabilities with configurable levels to significantly improve the developer experience when troubleshooting authentication issues.

Resolves #5

Key Features

Debug Levels

• none: No debug logging (default)
• basic: Auth flow start/end (backward compatible with debug: true)
• verbose: Detailed step-by-step flow
• transport: Includes raw request/response data (sanitized)
• trace: Everything including internal state changes

Data Sanitization

• Wallet addresses: Shows only first 6 and last 4 characters
• Signatures: Shows only first 10 and last 8 characters
• Sensitive fields (privateKey, secret, password): Completely redacted
• Long strings: Truncated at 1000 characters

Configuration Options

// Backward compatible
{ debug: true }  // Maps to 'basic' level

// String level
{ debug: 'verbose' }

// Full control
{ 
  debug: {
    level: 'transport',
    timestamps: false,
    logger: customLogger
  }
}

Implementation Details

TypeScript Compliance

• Zero any types in implementation
• All functions have explicit return types
• Proper type guards throughout
• Passes strict mode compilation

Testing

• 26 comprehensive tests for DebugLogger
• Tests for all debug levels
• Sanitization verification
• Edge case handling
• All existing tests updated and passing

Performance

• Minimal overhead when disabled
• Conditional logging prevents unnecessary string operations
• Lazy evaluation of debug messages

Security

• Never logs private keys or secrets
• Sanitizes wallet addresses and signatures
• Truncates large payloads
• Production safety warnings

Backward Compatibility

✅ Fully backward compatible

• Existing debug: true behavior unchanged (maps to 'basic' level)
• No breaking changes to public API
• All existing tests pass

Developer Experience

Before

• Limited visibility into authentication flow
• Difficult to debug client compatibility issues
• No insight into request/response formats

After

• Granular control over debug output
• Clear visibility into authentication steps
• Transport layer transparency
• Actionable error messages with context

Testing

npm test
✓ 63 tests passed
✓ TypeScript strict mode: PASSING
✓ 100% backward compatibility

Documentation

Updated inline documentation and TypeScript definitions provide full IntelliSense support for the new debug configuration options.