Epistates/TurboMCP

Summary

TurboMCP v1.1.0 adds two new features:

1. RFC 9449 DPoP (Demonstration of Proof-of-Possession) - OAuth 2.0 security enhancement
2. Type-State Capability Builders - Compile-time capability validation

This release maintains full backward compatibility with existing MCP applications.

RFC 9449 DPoP Security Implementation

DPoP Implementation

TurboMCP v1.1.0 adds RFC 9449 DPoP support, providing cryptographic binding of access tokens to client keys for OAuth 2.0 security.

use turbomcp_dpop::{DpopKeyManager, DpopProofGenerator};

// DPoP integration
let key_manager = DpopKeyManager::new_redis("redis://localhost:6379").await?;
let proof_generator = DpopProofGenerator::new(key_manager.into());

// Generate cryptographically bound proof
let proof = proof_generator.generate_proof(
    "POST",
    "https://api.example.com/resource",
    Some("access_token")
).await?;

Security Features

• Token Binding: Cryptographically bind access tokens to client public keys
• Replay Protection: Nonce generation and validation with Redis/HSM storage
• Multi-Store Support: In-memory (dev), Redis (production), HSM (high-security)
• Algorithm Support: ES256, RS256 with key rotation policies
• HSM Integration: YubiHSM2, PKCS#11 support

Usage Example

#[server]
impl SecureApiServer {
    #[tool("Make authenticated API call with DPoP")]
    async fn secure_call(&self, url: String) -> McpResult<String> {
        let proof = self.dpop_generator.generate_proof("GET", &url, None).await?;
        // Proof includes cryptographic binding, timestamp validation,
        // nonce uniqueness, and algorithm verification
        Ok(format!("Secure request with DPoP binding"))
    }
}

Type-State Capability Builders

Compile-Time Capability Validation

New const-generic type-state builders provide compile-time validation of capability configurations, preventing runtime errors and misconfigurations.

use turbomcp_protocol::capabilities::builders::ServerCapabilitiesBuilder;

// ✅ This compiles - valid capability hierarchy
let server_caps = ServerCapabilitiesBuilder::new()
    .enable_tools()                    // Enables tools capability state
    .enable_tool_list_changed()        // ✅ Available because tools enabled
    .enable_resources()                // Enables resources capability state
    .enable_resources_subscribe()      // ✅ Available because resources enabled
    .with_simd_optimization("avx2")    // TurboMCP extension
    .build();

// ❌ This would NOT compile - impossible configuration
// ServerCapabilitiesBuilder::new()
//     // .enable_tools()  ← Missing this
//     .enable_tool_list_changed()  ← Compile error!

Implementation Details

• Zero Runtime Overhead: All validation happens at compile time
• Type Safety: Impossible states are unrepresentable in the type system
• Performance: No runtime capability checking or validation loops
• Safety: Prevents misconfigurations that could cause protocol violations

TurboMCP Extensions

let advanced_server = ServerCapabilitiesBuilder::new()
    .enable_experimental()
    .enable_tools()
    // TurboMCP extensions
    .with_simd_optimization("avx2")           // SIMD acceleration hints
    .with_enterprise_security(true)          // Enterprise security features
    .with_zero_copy_optimization(true)       // Memory optimization hints
    .build();

let advanced_client = ClientCapabilitiesBuilder::new()
    .enable_sampling()
    // TurboMCP extensions
    .with_llm_provider("openai", "gpt-4")                    // LLM integration
    .with_ui_capabilities(vec!["form", "dialog", "toast"])   // UI capability hints
    .build();

Convenience Builders

// Pre-configured capability patterns
let full_server = ServerCapabilitiesBuilder::full_featured().build();
let minimal_server = ServerCapabilitiesBuilder::minimal().build();
let sampling_client = ClientCapabilitiesBuilder::sampling_focused().build();

Quality & Compatibility Improvements

Dependency Updates

• Fixed: Eliminated all criterion::black_box deprecation warnings
• Fixed: Updated Redis AsyncIter to use safe_iterators feature
• Updated: All benchmark code uses std::hint::black_box
• Cleaned: Dependency tree for security compliance

WebSocket Transport

• Updated: tokio-tungstenite compatibility (v0.27.0)
• Fixed: Message::Text API changes
• Added: WebSocket examples with bidirectional communication
• Improved: WebSocket server patterns

Documentation

• Added: DPoP integration guide and examples
• Added: Type-state builder tutorial
• Improved: API documentation
• Enhanced: Example applications

Performance Impact

Benchmark Results

• DPoP Operations: <2ms proof generation, <1ms validation
• Type-State Builders: 0ms runtime overhead (compile-time only)
• Memory Usage: <500KB additional overhead for DPoP key management
• WebSocket Throughput: >50k messages/sec with enhanced transport

Performance Notes

• Existing MCP operations maintain sub-1ms latency
• Type-state builders compile to identical bytecode as manual configuration
• DPoP security adds minimal overhead only to authenticated operations

Breaking Changes

None - This release maintains full backward compatibility. All existing TurboMCP applications will continue to work without modification.

Migration Path

// v1.0.13 - Still works exactly the same
let caps = ServerCapabilities {
    tools: Some(ToolsCapability {}),
    resources: Some(ResourcesCapability {
        subscribe: true,
        list_changed: true,
    }),
    ..Default::default()
};

// v1.1.0 - Optional upgrade to type-safe builders
let caps = ServerCapabilitiesBuilder::new()
    .enable_tools()
    .enable_resources()
    .enable_resources_subscribe()
    .enable_resources_list_changed()
    .build();

Use Cases

DPoP Security Benefits

• Regulatory Compliance: Meets financial industry OAuth 2.0 requirements
• Zero-Trust Architecture: Cryptographic proof for every API request
• Token Theft Protection: Stolen tokens are useless without private keys
• Audit Trail: Cryptographic audit trail for all operations

Type-State Safety Benefits

• Configuration Validation: Prevents capability misconfigurations
• Development Speed: Catch errors at compile time, not in production
• Self-Documenting: Capability relationships are explicit in code
• Refactoring Safety: Capability changes are verified by compiler

Compatibility Matrix

| Component | v1.0.13 | v1.1.0 | Notes |
|-----------|---------|---------|-------|
| MCP Protocol | ✅ 2025-06-18 | ✅ 2025-06-18 | Full compliance maintained |
| Rust Version | 1.89.0+ | 1.89.0+ | No change |
| tokio | 1.40+ | 1.47+ | Enhanced async support |
| Dependencies | Stable | Enhanced | Security hardened |

Additional Resources

• DPoP Integration Guide - RFC 9449 implementation guide
• Type-State Builder Tutorial - Interactive demonstration
• Security Best Practices - Production deployment guidance
• Migration Guide - Upgrade assistance

Notes

• RFC 9449 DPoP implementation for Rust ecosystem
• Compile-time capability validation for MCP
• Full backward compatibility with existing applications