GitHub Issue #3: Enhanced Debug Logging for Authentication Flow Troubleshooting

Issue Type

✨ Feature Request

Summary

The SDK currently provides basic debug logging, but developers need more comprehensive visibility into the authentication flow for troubleshooting. Enhanced debug logging would significantly improve the developer experience when diagnosing authentication issues.

Current Behavior

The SDK has basic debug logging enabled with debug: true, but it lacks:

• Transport layer visibility: Raw request/response data
• Authentication flow tracing: Step-by-step authentication process
• Format detection details: Input format analysis and conversion
• Error context: Detailed failure reasons with actionable insights

Motivation

During real-world integration testing, we discovered that authentication issues can be challenging to debug without visibility into:

1. Raw incoming requests: What data is actually being received
2. Format conversions: String-to-object parsing, validation steps
3. Proof verification details: Step-by-step verification process
4. Tool name extraction: How resource names are parsed and matched

Developer Pain Points

Without enhanced debugging, developers face:

• Hours of troubleshooting authentication failures
• Unclear error messages that don't indicate root cause
• Difficulty understanding format requirements
• Limited visibility into SDK internal processing

Proposed Solution

Add comprehensive debug logging option that provides full visibility into the authentication flow.

Required Debug Capabilities

Transport Layer Visibility

• Request Analysis: What data is actually being received from MCP clients
• Format Detection: Whether __evmauth is sent as string or object
• Request Validation: Basic structural validation of incoming requests

Authentication Flow Tracing

• Step-by-Step Processing: Clear visibility into each authentication step
• Proof Verification Details: Signature recovery, validation, and comparison results
• Resource Name Processing: How prefixed resource names are parsed and matched

Error Context Enhancement

• Failure Analysis: Rich context when authentication fails
• Root Cause Identification: Clear indication of what went wrong and why
• Actionable Debugging: Suggestions for resolving common authentication issues

Configurable Debug Levels

• Granular Control: Different debug levels for different types of information
• Production Safety: Debug modes that are safe for limited production use
• Performance Conscious: Minimal impact when debugging is disabled

Developer Experience Goals

Current Debugging Challenges

1. Limited Visibility: Basic debug output doesn't show transport layer details
2. Authentication Mysteries: When auth fails, unclear what step caused the failure
3. Format Issues: No visibility into whether clients send strings vs objects
4. Time-Intensive Troubleshooting: Hours spent debugging what could be resolved quickly with better logging

Expected Debugging Experience

1. Rapid Problem Identification: Clear logs show exactly where authentication fails
2. Transport Transparency: Full visibility into what data clients actually send
3. Step-by-Step Tracing: Authentication flow is visible from start to finish
4. Actionable Error Context: When something fails, logs suggest potential solutions

Benefits

• Faster Debugging: Developers can quickly identify authentication issues
• Better Error Messages: Rich context helps understand what went wrong
• Learning Tool: Developers can understand how authentication works
• Integration Confidence: Clear visibility into what the SDK expects vs receives
• Production Troubleshooting: Can be selectively enabled for specific issues

Implementation Considerations

Performance Impact

• Debug logging should have minimal performance impact when disabled
• Use conditional logging to avoid string interpolation costs
• Consider log level filtering

Security Considerations

• Never log sensitive data: Private keys, full signatures, personal info
• Configurable sensitivity: Allow developers to control what gets logged
• Production warnings: Clear warnings about debug mode in production

Backward Compatibility

✅ Fully backward compatible - existing debug: true behavior unchanged, new options are additive.

Use Cases

1. Development Integration: Debugging authentication during MCP server development
2. Client Compatibility: Understanding how different MCP clients format requests
3. Production Troubleshooting: Investigating authentication issues in live environments (with appropriate security controls)
4. SDK Contribution: Contributors need visibility into authentication flow for improvements

Documentation Updates

• Add debug configuration options to README
• Create troubleshooting guide with debug examples
• Include common authentication issues and their debug signatures
• Add section on production debug considerations

Environment

• SDK Version: Latest
• Use Cases: Development, integration testing, production troubleshooting
• Target Audience: SDK integrators, MCP server developers

Additional Context

This enhancement was identified during integration with Claude Web, where authentication issues required extensive manual debugging. Enhanced logging would have reduced debugging time from hours to minutes.

Acceptance Criteria

• Multiple debug logging levels (basic, verbose, transport, proof-details)
• Backward compatible with existing debug configuration
• No performance impact when debugging is disabled
• Security-conscious logging (no sensitive data exposure)
• Comprehensive test coverage for logging features
• Updated documentation with debug examples
• Production safety warnings for debug modes

---

Labels: enhancement, developer-experience, debugging, logging
Priority: Low
Milestone: Future Release