feat: Add SigV4A authentication support for global AWS endpoints with auto-detection

[harv-aws]

Summary

Adds AWS Signature Version 4A (SigV4A) authentication support to the MCP Proxy for AWS, enabling seamless connections to global and multi-region AWS endpoints. The implementation includes intelligent auto-detection that automatically upgrades from SigV4 to SigV4A when required by the endpoint.

What is SigV4A?

SigV4A is an extension of AWS Signature Version 4 that supports multi-region signatures, allowing a single signed request to be valid across multiple AWS regions. This is essential for:

• AWS Global Accelerator
• CloudFront distributions
• Multi-region AWS services
• Global AWS endpoints

Key Features

1. Automatic Detection & Fallback

• Starts with SigV4 for compatibility
• Automatically detects when an endpoint requires SigV4A (via 403 error responses)
• Seamlessly retries with SigV4A without user intervention
• Caches detection result for subsequent requests

2. Global Endpoint Detection

• Automatically identifies global endpoints from URL patterns:
  • service.global.api.aws
  • global.service.api.aws
  • service.api.aws (without region)
• Defaults to us-east-1 region for global endpoints

3. Transparent Integration

• Auto-detection is built into SigV4HTTPXAuth class
• No configuration required - works automatically
• Fully backward compatible with existing regional endpoints

Implementation Details

Core Changes

• mcp_proxy_for_aws/sigv4_helper.py:

  • Enhanced SigV4HTTPXAuth with auto-detection logic
  • Implements _requires_sigv4a() to detect SigV4A requirement from error responses
  • Lazy initialization of SigV4A signer for performance
  • Comprehensive error logging for troubleshooting

• mcp_proxy_for_aws/utils.py:

  • Added is_global_endpoint() to detect global endpoint patterns
  • Enhanced determine_aws_region() to handle global endpoints

• mcp_proxy_for_aws/client.py:

  • Updated to use enhanced SigV4HTTPXAuth with auto-detection

Test Coverage

• Added comprehensive unit tests for auto-detection logic
• Added tests for global endpoint detection
• Added tests for SigV4A retry behavior
• All 112 unit tests pass

Usage Examples

Global Endpoint (Auto-detected)

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

# Automatically detects global endpoint and uses SigV4A if needed
async with aws_iam_streamablehttp_client(
    endpoint="https://service.global.api.aws/mcp",
    aws_service="my-service"
) as (read, write, get_session_id):
    # Use the client
    pass

Regional Endpoint (Existing behavior)

# Works exactly as before - uses SigV4
async with aws_iam_streamablehttp_client(
    endpoint="https://service.us-west-2.api.aws/mcp",
    aws_service="my-service",
    aws_region="us-west-2"
) as (read, write, get_session_id):
    # Use the client
    pass

Requirements Satisfied

✅ Requirement 1: Support for global AWS endpoints with SigV4A
✅ Requirement 2: Automatic detection without explicit configuration
✅ Requirement 3: Programmatic client library support
✅ Requirement 4: Clear error messages and logging
✅ Requirement 5: Maintains backward compatibility

Dependencies

• Requires botocore >= 1.31.0 for full SigV4A support
• Gracefully falls back to SigV4-only if older botocore version is installed

Backward Compatibility

✅ Fully backward compatible - All existing code continues to work without changes. Regional endpoints use SigV4 as before, and global endpoints automatically upgrade to SigV4A when needed.

Testing

# Run all tests
python -m pytest tests/unit/ -v

# Run SigV4A-specific tests
python -m pytest tests/unit/test_sigv4_helper.py::TestSigV4HTTPXAuthAutoDetect -v