turbomcp-auth 2.1.0

# TurboMCP Auth

OAuth 2.1 and authentication for TurboMCP with MCP protocol compliance.

## Features

- **OAuth 2.1 Flows** - RFC 8707/9728/7591 compliant with PKCE support
  - Authorization Code flow (with PKCE for public/confidential clients)
  - Client Credentials flow (server-to-server)
  - Token refresh and validation
- **Multi-Provider Support** - Google, GitHub, Microsoft, GitLab (with provider-specific configurations)
- **OAuth2Provider** - Full AuthProvider implementation for OAuth 2.1
- **API Key Authentication** - Simple API key-based authentication
- **Server-Side Helpers** - RFC 9728 Protected Resource Metadata and WWW-Authenticate headers
- **Session Management** - Secure token management with configurable storage
- **DPoP Support** - Optional RFC 9449 proof-of-possession tokens
- **Comprehensive Validation** - RFC 8707 canonical URI validation, token format validation

## Quick Start

### Client: OAuth 2.1 Authorization Code Flow

```rust
use turbomcp_auth::{
    oauth2::OAuth2Client,
    config::{OAuth2Config, OAuth2FlowType, ProviderType},
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create OAuth2 configuration
    let config = OAuth2Config {
        client_id: "my-client-id".to_string(),
        client_secret: "my-client-secret".to_string(),
        auth_url: "https://provider.example.com/oauth/authorize".to_string(),
        token_url: "https://provider.example.com/oauth/token".to_string(),
        redirect_uri: "http://localhost:8080/callback".to_string(),
        scopes: vec!["openid".to_string(), "profile".to_string()],
        flow_type: OAuth2FlowType::AuthorizationCode,
        additional_params: Default::default(),
        security_level: Default::default(),
        #[cfg(feature = "dpop")]
        dpop_config: None,
        mcp_resource_uri: None,
        auto_resource_indicators: true,
    };

    // Create OAuth2 client
    let client = OAuth2Client::new(&config, ProviderType::Generic)?;

    // Step 1: Generate authorization URL with PKCE
    let state = uuid::Uuid::new_v4().to_string();
    let (auth_url, code_verifier) = client.authorization_code_flow(config.scopes, state);

    println!("1. Open authorization URL in browser:\n{}\n", auth_url);

    // Step 2: User authorizes, redirect comes with code
    // After user authorizes and redirects with code...

    // Step 3: Exchange code for token
    let token = client.exchange_code_for_token("auth_code".to_string(), code_verifier).await?;
    println!("Access token: {}", token.access_token);

    // Step 4: Use token to access protected resources
    // Authorization: Bearer {token.access_token}

    // Step 5: Refresh token when expired
    if let Some(refresh_token) = &token.refresh_token {
        let new_token = client.refresh_access_token(refresh_token).await?;
        println!("Refreshed token: {}", new_token.access_token);
    }

    Ok(())
}
```

### Server: Protected Resource with RFC 9728 Metadata

```rust
use turbomcp_auth::server::{
    ProtectedResourceMetadataBuilder, WwwAuthenticateBuilder, BearerTokenValidator,
};

// Serve Protected Resource Metadata at /.well-known/protected-resource
fn get_metadata() -> Result<String, Box<dyn std::error::Error>> {
    let metadata = ProtectedResourceMetadataBuilder::new(
        "https://mcp.example.com".to_string(),
        "https://auth.example.com/.well-known/oauth-authorization-server".to_string(),
    )
    .with_scopes(vec!["mcp:read".to_string(), "mcp:write".to_string()])
    .with_documentation("https://mcp.example.com/docs".to_string())
    .build();

    Ok(serde_json::to_string_pretty(&metadata)?)
}

// Handle 401 Unauthorized responses
fn handle_unauthorized() -> (String, String) {
    let www_auth = WwwAuthenticateBuilder::new(
        "https://mcp.example.com/.well-known/protected-resource".to_string(),
    )
    .with_scope("mcp:read".to_string())
    .build();

    (www_auth, "Unauthorized".to_string())
}

// Validate incoming bearer tokens
fn extract_token(auth_header: &str) -> Result<String, Box<dyn std::error::Error>> {
    let token = BearerTokenValidator::extract_from_header(auth_header)?;
    BearerTokenValidator::validate_format(&token)?;
    Ok(token)
}
```

## Usage

```toml
[dependencies]
turbomcp-auth = "2.1.0"

# With DPoP support for enhanced security
turbomcp-auth = { version = "2.1.0", features = ["dpop"] }

# With tokio runtime
tokio = { version = "1", features = ["full"] }
uuid = { version = "1", features = ["v4"] }
```

## Feature Flags

- `default` - Core authentication (no optional features)
- `dpop` - Enable DPoP (RFC 9449) token binding support via `turbomcp-dpop`

## Architecture

### Core Components

- **OAuth2Client** (`oauth2::OAuth2Client`)
  - Authorization Code flow with PKCE (RFC 7636)
  - Client Credentials flow (server-to-server)
  - Token refresh and validation
  - Provider-specific configurations for Google, GitHub, Microsoft, GitLab

- **OAuth2Provider** (`providers::OAuth2Provider`)
  - Implements AuthProvider trait
  - Token validation via userinfo endpoint
  - Token caching and refresh management
  - Integration with authentication manager

- **AuthManager** (`manager::AuthManager`)
  - Coordinates multiple authentication providers
  - Stateless authentication (MCP compliant)
  - Token validation on every request

- **Server Helpers** (`server::*`)
  - `ProtectedResourceMetadataBuilder` - RFC 9728 metadata generation
  - `WwwAuthenticateBuilder` - RFC 9728 401 response headers
  - `BearerTokenValidator` - Token extraction and validation

### RFC Compliance

- **RFC 7636** - PKCE (Proof Key for Public OAuth Clients)
- **RFC 7591** - Dynamic Client Registration Protocol
- **RFC 8707** - Resource Indicators for OAuth 2.0
- **RFC 9728** - OAuth 2.0 Protected Resource Metadata
- **RFC 9449** - DPoP (optional, via `turbomcp-dpop`)

## Examples

Run the examples to see the implementations in action:

```bash
# OAuth 2.1 Authorization Code Flow
cargo run --example oauth2_auth_code_flow

# Protected Resource Server with RFC 9728
cargo run --example protected_resource_server
```

## Security Best Practices

1. **Use HTTPS** - Always use HTTPS for redirect URIs and token endpoints
2. **PKCE** - Automatically enabled for Authorization Code flow (RFC 7636)
3. **Token Storage** - Tokens are never logged or serialized unnecessarily
4. **Constant-Time Comparison** - Token validation uses constant-time comparison
5. **DPoP** - Enable DPoP feature for enhanced security (RFC 9449)
6. **Scope Validation** - Always validate token scopes server-side
7. **Short Expiration** - Use short-lived access tokens with refresh tokens

## Testing

```bash
cargo test --lib --package turbomcp-auth
cargo test --lib --package turbomcp-dpop  # If dpop feature enabled
```

## License

MIT