Add ENABLE_OVERWRITE_BASE_HEADERS configuration for advanced header passthrough

Summary

This PR introduces the ENABLE_OVERWRITE_BASE_HEADERS environment variable to provide advanced control over HTTP header passthrough behavior. When enabled, this allows client-provided headers to override gateway base headers like Content-Type and Authorization for specialized use cases.

What's Changed

Core Implementation

• Added environment variable mapping for ENABLE_OVERWRITE_BASE_HEADERS in config.py
• Fixed missing environment variable mapping for ENABLE_HEADER_PASSTHROUGH
• Implemented base header override logic in passthrough_headers.py
• Added startup logging to show current header override status

Configuration & Documentation

• Updated .env.example with ENABLE_OVERWRITE_BASE_HEADERS configuration
• Enhanced README.md configuration table with new setting
• Updated Helm charts (values.yaml) with new environment variable
• Comprehensive documentation updates across:
  • Header passthrough overview (docs/overview/passthrough.md)
  • Proxy authentication guides (docs/deployment/proxy-auth.md, docs/manage/proxy.md)
  • Main documentation (docs/index.md)

Testing

• Added comprehensive unit tests for base header override functionality
• Enhanced existing tests to cover both enabled/disabled scenarios
• Maintained backward compatibility with existing test suite

Quality Improvements

• Fixed trailing newlines in documentation files
• Added Xena deployment configurations for enterprise environments

Security Considerations

• Disabled by default - maintains secure-by-default approach
• Requires explicit configuration - users must understand implications
• Preserves existing auth conflicts detection - still prevents dangerous overrides
• Comprehensive logging - all override attempts are logged for audit

Use Cases

This feature enables:

• Custom authentication schemes requiring client-provided Authorization headers
• Specialized content negotiation needing client Content-Type override
• Advanced proxy scenarios with specific header requirements
• Enterprise integrations where client headers must take precedence

Breaking Changes

None - this is a purely additive feature with secure defaults.

Testing

All existing tests pass, plus new tests covering:

• Header override enabled/disabled scenarios
• Conflict detection with auth headers
• Base header preservation logic
• Security validation and sanitization
• Configuration hierarchy (gateway > global > defaults)

Implementation Details

Environment Variable Configuration

# Enable the advanced feature (disabled by default)
ENABLE_OVERWRITE_BASE_HEADERS=true

Code Changes

• mcpgateway/config.py: Added proper environment variable mapping
• mcpgateway/utils/passthrough_headers.py: Implemented override logic
• mcpgateway/main.py: Added startup logging
• tests/unit/mcpgateway/utils/test_passthrough_headers.py: Comprehensive test coverage

Configuration Hierarchy

1. Gateway-specific headers (highest priority)
2. Global database configuration
3. Environment variable defaults (lowest priority)

Checklist

• Environment variable properly mapped in config
• Logic implemented with security safeguards
• Comprehensive unit tests added
• Documentation updated across all relevant files
• Helm charts updated for Kubernetes deployments
• Backward compatibility maintained
• Security-by-default approach preserved

Ready for Review

This PR is ready for review and addresses the issue where ENABLE_OVERWRITE_BASE_HEADERS was not being read from environment variables, while adding the full advanced header override functionality requested.

Reference: #1046

Closes #1046