turbomcp_auth/
lib.rs

1//! # TurboMCP Auth - Unified Authentication Framework
2//!
3//! World-class authentication and authorization for TurboMCP with standards-compliant
4//! implementations of OAuth 2.1, JWT, API keys, and DPoP token binding.
5//!
6//! ## Design Principles
7//!
8//! - **Single Source of Truth**: ONE canonical `AuthContext` type used everywhere
9//! - **Feature-Gated Complexity**: Simple by default, powerful when needed
10//! - **Zero-Cost Abstractions**: No overhead for unused features
11//! - **Standards-Compliant**: OAuth 2.1, RFC 7519 (JWT), RFC 9449 (DPoP), RFC 9728
12//!
13//! ## Key Features
14//!
15//! - **Unified AuthContext** - Single type for all authentication scenarios
16//! - **OAuth 2.1** - RFC 8707/9728/7591 compliant with PKCE support
17//! - **Multi-Provider** - Google, GitHub, Microsoft, GitLab out of the box
18//! - **API Key Auth** - Simple and secure API key authentication
19//! - **RBAC Support** - Role-based access control with fine-grained permissions
20//! - **Session Management** - Flexible token storage and lifecycle management
21//! - **DPoP Support** - Optional RFC 9449 proof-of-possession tokens
22//!
23//! ## Architecture
24//!
25//! - [`context`] - Unified `AuthContext` type (THE canonical auth representation)
26//! - [`types`] - Core types (UserInfo, TokenInfo, provider traits)
27//! - [`config`] - Configuration types for authentication providers
28//! - [`providers`] - Authentication provider implementations
29//!   - `api_key` - API key authentication
30//!   - `oauth2` - OAuth 2.1 provider
31//! - [`manager`] - Authentication manager for provider orchestration
32//! - [`oauth2`] - OAuth 2.1 client with authorization flows
33//! - [`server`] - Server-side authentication helpers (RFC 9728 Protected Resource)
34//!
35//! ## Quick Start
36//!
37//! ```rust
38//! use turbomcp_auth::{AuthContext, UserInfo};
39//! use std::time::SystemTime;
40//! use std::collections::HashMap;
41//!
42//! // Create an auth context using the builder
43//! let user = UserInfo {
44//!     id: "user123".to_string(),
45//!     username: "alice".to_string(),
46//!     email: Some("alice@example.com".to_string()),
47//!     display_name: Some("Alice".to_string()),
48//!     avatar_url: None,
49//!     metadata: HashMap::new(),
50//! };
51//!
52//! let auth = AuthContext::builder()
53//!     .subject("user123")
54//!     .user(user)
55//!     .provider("api-key")
56//!     .roles(vec!["admin".to_string(), "user".to_string()])
57//!     .permissions(vec!["write:data".to_string()])
58//!     .build()
59//!     .unwrap();
60//!
61//! // Check authorization
62//! if auth.has_role("admin") && auth.has_permission("write:data") {
63//!     println!("User {} has write access", auth.sub);
64//! }
65//! ```
66//!
67//! ## Feature Flags
68//!
69//! ### Default Features
70//! - `api-key` - API key authentication
71//! - `oauth2` - OAuth 2.1 flows and providers
72//!
73//! ### Core Authentication Methods
74//! - `jwt` - JWT token validation
75//! - `custom` - Custom auth provider support (traits only)
76//!
77//! ### Advanced Features
78//! - `dpop` - RFC 9449 DPoP token binding
79//! - `rbac` - Role-based access control helpers
80//!
81//! ### Token Lifecycle
82//! - `token-refresh` - Automatic token refresh
83//! - `token-revocation` - Token revocation support
84//!
85//! ### Observability
86//! - `metrics` - Metrics collection (future)
87//! - `tracing-ext` - Extended tracing support
88//!
89//! ### Middleware
90//! - `middleware` - Tower middleware support (future)
91//!
92//! ### Batteries-Included
93//! - `full` - All features enabled
94//!
95//! ## Standards Compliance
96//!
97//! - **RFC 7519** - JSON Web Token (JWT)
98//! - **RFC 6749** - OAuth 2.0 Authorization Framework
99//! - **RFC 7636** - Proof Key for Code Exchange (PKCE)
100//! - **RFC 8707** - OAuth 2.0 Resource Indicators
101//! - **RFC 9449** - OAuth 2.0 Demonstrating Proof-of-Possession (DPoP)
102//! - **RFC 9728** - OAuth 2.0 Protected Resource Metadata
103
104// Submodules
105pub mod api_key_validation; // Sprint 2.3: Constant-time API key validation
106pub mod config;
107pub mod context;
108pub mod introspection;
109pub mod jwt;
110pub mod manager;
111pub mod oauth2;
112pub mod providers;
113pub mod server;
114pub mod types;
115
116// Re-export configuration types
117#[doc(inline)]
118pub use config::*;
119
120// Re-export legacy types (excluding old AuthContext to avoid conflict with unified version)
121#[doc(inline)]
122pub use types::{
123    AccessToken, AuthCredentials, AuthMiddleware, AuthProvider, DefaultAuthMiddleware, TokenInfo,
124    TokenStorage, UserInfo,
125};
126
127// Re-export unified context types (this is the canonical AuthContext)
128#[doc(inline)]
129pub use context::{AuthContext, AuthContextBuilder, ValidationConfig};
130
131// Re-export providers
132#[doc(inline)]
133pub use providers::*;
134
135// Re-export manager
136#[doc(inline)]
137pub use manager::AuthManager;
138
139// Re-export DPoP types when feature is enabled
140#[cfg(feature = "dpop")]
141pub use turbomcp_dpop as dpop;
turbomcp_auth/lib.rs

turbomcp_auth/
lib.rs
