Add comprehensive mTLS documentation and plugin TLS support

[crivetimihai]

🔐 feat: Add comprehensive mTLS documentation and plugin TLS support

Closes #568

📋 Summary

This PR delivers production-ready mTLS support for MCP Gateway through comprehensive documentation and plugin-level TLS implementation. While native gateway TLS termination remains a future enhancement, this provides immediate value through proxy-based mTLS patterns and secure plugin communication.

🎯 What This PR Delivers

1. Complete mTLS Documentation (docs/docs/manage/mtls.md)

• 943 lines of comprehensive mTLS configuration guide
• Multiple deployment patterns with working examples:
  • ✅ Docker Compose with Nginx mTLS
  • ✅ Caddy reverse proxy configuration
  • ✅ Kubernetes with Istio service mesh
  • ✅ HAProxy with client certificates
  • ✅ Helm chart integration with TLS ingress

2. Plugin mTLS Support

• Gateway as mTLS client to external plugins
• Per-plugin certificate configuration in plugins/config.yaml
• Environment variables for plugin TLS settings:

  PLUGINS_MTLS_CA_BUNDLE: ""
  PLUGINS_MTLS_CLIENT_CERT: ""
  PLUGINS_MTLS_CLIENT_KEY: ""
  PLUGINS_MTLS_VERIFY: "true"
  PLUGINS_MTLS_CHECK_HOSTNAME: "true"

3. Implementation Details

New Files Created:

• docs/docs/manage/mtls.md - Complete mTLS guide
• tests/unit/mcpgateway/plugins/framework/test_models_tls.py - TLS configuration tests

Files Modified:

• mcpgateway/plugins/framework/external/mcp/client.py - Added TLS support to MCP client (+51 lines)
• mcpgateway/plugins/framework/models.py - Added TLSConfig model (+92 lines)
• charts/mcp-stack/values.yaml - Added plugin mTLS environment variables
• plugins/config.yaml - Example TLS configuration for external plugins
• .env.example - Added plugin mTLS configuration examples

🚀 Key Features Implemented

Proxy-Based mTLS (Ready Today)

• Complete working examples for production deployment
• Certificate generation scripts
• Docker Compose with volume mounts for certificates
• Kubernetes secrets management
• Enterprise PKI integration patterns

Plugin Security (New Capability)

# External plugin with mTLS
plugins:
  - name: "SecurePlugin"
    kind: "external"
    mcp:
      proto: STREAMABLEHTTP
      url: https://plugins.internal:9443/mcp
      tls:
        ca_bundle: /app/certs/plugins/ca.crt
        client_cert: /app/certs/plugins/gateway-client.pem
        verify: true
        check_hostname: true

Enterprise Integration

• Istio service mesh with EnvoyFilter for CN extraction
• Cert-manager integration for automatic rotation
• Monitoring and alerting for certificate expiration
• Certificate pinning examples
• Rate limiting by certificate fingerprint

📊 Impact Analysis

Lines Changed

• +1,271 additions across 28 files
• -23 deletions (cleanup)
• 943 lines of new documentation

Test Coverage

• Unit tests for TLS configuration models
• Integration examples in documentation
• Certificate validation test scripts

✅ Acceptance Criteria Met

From issue #568, this PR addresses:

• Plugin mTLS - Gateway presents client certificate to external plugins
• Per-plugin certificate configuration - Individual TLS settings per plugin
• Global default certificates - Environment variables for defaults
• Certificate verification bypass - verify: false for development
• Documentation - Complete mTLS configuration guide
• Certificate generation examples - OpenSSL commands included
• Kubernetes deployment with mTLS - Helm chart and raw manifests
• Enterprise Integration - Istio, cert-manager, PKI patterns

🔄 Migration Path

This PR provides a pragmatic approach:

1. Immediate Solution: Use proxy-based mTLS (documented)
2. Plugin Security: Native mTLS for external plugins (implemented)
3. Future Enhancement: Native gateway TLS termination (tracked separately)

🧪 Testing Instructions

1. Generate Test Certificates

mkdir -p certs/mtls
# Follow commands in docs/docs/manage/mtls.md

2. Test Docker Compose Setup

docker-compose -f docker-compose-mtls.yml up -d
curl --cert certs/mtls/client.pem \
     --cacert certs/mtls/ca.crt \
     https://localhost/health

3. Test Plugin mTLS

# Set environment variables
export PLUGINS_MTLS_CLIENT_CERT=/app/certs/plugins/gateway-client.pem
export PLUGINS_MTLS_CA_BUNDLE=/app/certs/plugins/ca.crt

# Configure plugin with TLS
# Run gateway and verify secure connection to plugin

📚 Documentation

The new docs/docs/manage/mtls.md includes:

• Architecture diagrams (Mermaid)
• Step-by-step setup instructions
• Production best practices
• Troubleshooting guide
• Security considerations
• Certificate lifecycle management

🚦 Status

• Code complete
• Documentation complete
• Tests added
• Helm charts updated
• Examples provided
• Ready for review

🔮 Future Work (Not in This PR)

Native mTLS termination in the gateway itself would require:

• FastAPI/Uvicorn SSL context configuration
• X.509 certificate parsing in Python
• CRL/OCSP checking implementation
• Hot reload of certificates
• Database models for certificate storage

These remain tracked in #568 for future enhancement.

🔗 Related Issues

• Closes [Feature]: mTLS support (gateway and plugins), configurable client require TLS cert, and certificate setup for MCP Servers with private CA #568 - TLS/mTLS support
• Related to [Feature Request]: AI Middleware Integration / Plugin Framework for extensible gateway capabilities #319 - Plugin framework (adds TLS support)
• Related to [Feature]: Add tool hooks (tool_pre_invoke / tool_post_invoke) to plugin system #682 - External plugins (now with mTLS)

📋 Checklist

• Documentation added/updated
• Tests added for new functionality
• Environment variables documented
• Helm values updated
• Examples provided
• Backward compatible (no breaking changes)
• Security reviewed (certificate validation, no hardcoded secrets)