auth_framework/prelude.rs
1//! Auth Framework Prelude
2//!
3//! This module provides a convenient way to import the most commonly used types
4//! and traits from the auth framework. Instead of importing individual types,
5//! you can simply use:
6//!
7//! ```rust
8//! use auth_framework::prelude::*;
9//! ```
10//!
11//! This imports all the essential types you need to get started with authentication
12//! and authorization in your application.
13//!
14//! # Recommended Entry Points
15//!
16//! - Use [`AuthFramework`] for the normal library entry point.
17//! - [`ModularAuthFramework`] is deprecated (removed in `0.7.0`); name
18//! `auth_modular::AuthFramework` by path for direct access to the component managers.
19//! - Use [`AuthFramework::users`], [`AuthFramework::sessions`],
20//! [`AuthFramework::tokens`], and [`AuthFramework::authorization`] when you
21//! want grouped operations instead of the full façade.
22//! - [`AppConfigBuilder`] is deprecated (removed in `0.7.0`); use [`LayeredConfigBuilder`].
23//! - Use [`LayeredConfigBuilder`] and [`ConfigManager`] for layered config
24//! sourced from files and environment variables.
25//! - Use [`SessionManager`] for the standard session engine and
26//! [`SecureSessionManager`] when you need the hardened secure-session layer.
27//!
28//! # What's Included
29//!
30//! ## Core Framework Types
31//! - [`AuthFramework`] - Main authentication framework
32//! - [`AuthConfig`] - Configuration builder
33//! - [`AuthError`] - Error type with detailed error variants
34//! - [`AuthFrameworkResult`] - Convenient Result type alias
35//!
36//! ## Authentication Methods
37//! - [`JwtMethod`] - JWT authentication
38//! - [`OAuth2Method`] - OAuth 2.0 authentication
39//! - [`ApiKeyMethod`] - API key authentication
40//! - [`PasswordMethod`] - Password-based authentication
41//!
42//! ## Tokens and Sessions
43//! - [`AuthToken`] - Authentication token representation
44//! - [`SessionData`] - Session data structure
45//! - [`ProviderProfile`] - Provider-backed user profile information
46//!
47//! ## Permissions and Authorization
48//! - [`Permission`] - Permission representation
49//! - [`Role`] - Role representation with builder methods
50//! - [`AbacPolicy`] - Attribute-based access control policy with builder methods
51//! - [`Delegation`] - Permission delegation with builder methods
52//! - [`PermissionChecker`] - Permission validation trait
53//!
54//! ## Storage Abstractions
55//! - [`AuthStorage`] - Storage trait for persistence
56//! - [`MemoryStorage`] - In-memory storage implementation
57//!
58//! ## Web Framework Integration
59//! - `RequireAuth` - Middleware for requiring authentication
60//! - `AuthenticatedUser` - Extractor for authenticated users
61//! - `RequirePermission` - Middleware for permission checking
62//!
63//! ## Builder Patterns and Helpers
64//! - [`AuthBuilder`] - Fluent builder for framework setup
65//! - [`AuthConfigBuilder`] - Organized builder for AuthConfig with grouped settings
66//! - [`SecurityPreset`] - Pre-configured security levels
67//! - [`AppConfigBuilder`] - Deprecated simple configuration builder (removed in `0.7.0`)
68//! - [`LayeredConfigBuilder`] - Layered configuration builder
69//! - [`AdvancedPermissionCheck`] - Builder for multi-source permission checks
70//! - [`ExecutionMode`] - `DryRun` vs `Execute` for maintenance operations
71//! - [`UserStatus`] - `Active` vs `Inactive` for user account state
72//! - [`SessionFilter`] - `ActiveOnly` vs `IncludeInactive` for session listing
73//!
74//! ## Time and Rate Limiting Helpers
75//! - Time duration helpers: [`hours`], [`minutes`], [`days`], [`weeks`]
76//! - Rate limiting helpers: [`requests`], [`RequestCount::per_second`],
77//! [`RequestCount::per_minute`], [`RequestCount::per_hour`]
78//!
79//! # Quick Start Example
80//!
81//! ```rust,no_run
82//! use auth_framework::prelude::*;
83//!
84//! #[tokio::main]
85//! async fn main() -> AuthFrameworkResult<()> {
86//! // Create auth framework with sensible defaults
87//! let auth = AuthFramework::quick_start()
88//! .jwt_auth_from_env()
89//! .with_postgres_from_env()
90//! .build().await?;
91//!
92//! // Create a token
93//! let token = auth.create_auth_token(
94//! "user123",
95//! vec!["read".to_string()],
96//! "jwt",
97//! None
98//! ).await?;
99//!
100//! // Validate token
101//! if auth.validate_token(&token).await? {
102//! println!("Token is valid!");
103//! }
104//!
105//! Ok(())
106//! }
107//! ```
108
109// Re-export core framework types
110pub use crate::AuthFramework;
111#[allow(deprecated)]
112pub use crate::ModularAuthFramework;
113pub use crate::auth::{
114 AdminOperations, AuditOperations, AuthStats, AuthorizationOperations, MfaOperations,
115 MonitoringOperations, SessionOperations, TokenOperations, UserInfo, UserOperations,
116};
117
118// Re-export request / query structs for operations facades
119pub use crate::auth_operations::{
120 AuditLogQuery, DelegationRequest, ExecutionMode, PermissionContext, SessionCreateRequest,
121 SessionFilter, TokenCreateRequest, UserListQuery, UserStatus,
122};
123
124// Re-export configuration types
125#[allow(deprecated)]
126pub use crate::AppConfigBuilder;
127pub use crate::config::app_config::AppConfig;
128pub use crate::config::config_manager::{
129 ApiServerSettings, AuthFrameworkSettings, ConfigBuilder as LayeredConfigBuilder, ConfigManager,
130};
131pub use crate::config::{
132 AuditConfig, AuthConfig, AuthConfigBuilder, CookieSameSite, CorsConfig, JwtAlgorithm,
133 PasswordHashAlgorithm, RateLimitConfig, SecurityConfig, StorageConfig,
134};
135
136// Re-export error types
137pub use crate::errors::{
138 AuthError, DeviceFlowError, MfaError, OAuthProviderError, PermissionError, Result,
139 StorageError, TokenError,
140};
141
142// Re-export authentication methods
143pub use crate::methods::{
144 ApiKeyMethod, AuthMethod, AuthMethodEnum, JwtMethod, MethodResult, OAuth2Method, PasswordMethod,
145};
146
147// Re-export common domain types
148pub use crate::types::{
149 AdditionalParams, GrantTypes, IpList, Permissions, RedirectUris, ResponseTypes, Roles, Scopes,
150 UserAttributes, UserAttributesString,
151};
152
153// Re-export SAML if available
154#[cfg(feature = "saml")]
155pub use crate::methods::saml;
156
157// Re-export tokens and user data
158pub use crate::authentication::credentials::Credential;
159pub use crate::providers::{
160 OAuthProvider, OAuthProviderConfig, OAuthProviderConfigBuilder, ProviderProfile,
161};
162pub use crate::tokens::{AuthToken, AuthTokenBuilder, TokenMetadata, TokenMetadataBuilder};
163
164// Re-export permissions and roles
165pub use crate::permissions::{
166 AbacPolicy, AdvancedPermissionCheck, Delegation, Permission, PermissionChecker, Role,
167};
168
169// Re-export authorization if enhanced RBAC is enabled
170#[cfg(feature = "enhanced-rbac")]
171pub use crate::authorization::{
172 AbacPermission as AuthzPermission, AbacRole as AuthzRole, AccessCondition, AuthorizationEngine,
173};
174
175// Re-export storage abstractions
176pub use crate::storage::{AuthStorage, MemoryStorage, SessionData};
177
178// Re-export session management
179pub use crate::security::secure_session::{
180 DeviceFingerprint, SecureSession, SecureSessionConfig, SecureSessionManager, SecurityFlags,
181};
182pub use crate::session::manager::{
183 DeviceInfo, Session, SessionConfig, SessionManager, SessionState,
184};
185
186// Re-export middleware and extractors for web frameworks
187#[cfg(feature = "axum-integration")]
188pub use crate::integrations::axum::{
189 AuthMiddleware, AuthenticatedUser, RequireAuth, RequirePermission,
190};
191
192#[cfg(feature = "actix-integration")]
193pub use crate::integrations::actix_web::AuthMiddleware as ActixAuthMiddleware;
194
195#[cfg(feature = "warp-integration")]
196pub use crate::integrations::warp::{with_auth, with_permission};
197
198// Re-export monitoring and observability
199pub use crate::monitoring::{
200 HealthCheckResult, HealthStatus, MonitoringManager, PerformanceMetrics, SecurityEvent,
201 SecurityEventBuilder, SecurityEventSeverity, SecurityEventType,
202};
203
204// Re-export audit logging
205pub use crate::audit::{
206 AuditEvent, AuditEventBuilder, AuditEventType, AuditLogger, AuditQuery, AuditQueryBuilder,
207 EventOutcome, RiskLevel,
208};
209
210// Re-export security utilities
211pub use crate::security::secure_jwt::{SecureJwtClaims, SecureJwtConfig, SecureJwtValidator};
212pub use crate::security::secure_utils::{SecureComparison, SecureRandomGen};
213pub use crate::security::{
214 SecurityAuditReport, SecurityAuditStatus, SecurityIssue, SecuritySeverity,
215};
216
217// Re-export rate limiting
218pub use crate::utils::rate_limit::RateLimiter;
219
220// Re-export testing utilities
221#[cfg(test)]
222pub use crate::testing::{MockAuthMethod, MockStorage};
223
224// Re-export CLI tools if available
225#[cfg(feature = "cli")]
226pub use crate::cli;
227
228// Re-export API server if available
229#[cfg(feature = "api-server")]
230pub use crate::api::{ApiError, ApiResponse, ApiServer, ApiState};
231
232// Re-export OIDC server components
233pub use crate::server::oidc::core::{IdTokenRequest, OidcConfigBuilder};
234pub use crate::server::oidc::{
235 IdTokenClaims, Jwk, JwkSet, OidcConfig, OidcDiscoveryDocument, OidcProvider,
236 UserInfo as OidcUserInfo,
237};
238
239// Re-export OAuth2 server
240pub use crate::oauth2_server::{
241 AuthorizationRequest, GrantType, OAuth2Config, OAuth2ConfigBuilder, OAuth2Server, ResponseType,
242 TokenRequest, TokenResponse,
243};
244
245// Builder patterns and ergonomic helpers
246pub use crate::builders::*;
247
248// Time duration helpers for ergonomic configuration
249pub mod time {
250 use std::time::Duration;
251
252 /// Create a duration representing the specified number of hours
253 pub fn hours(h: u64) -> Duration {
254 Duration::from_secs(h * 3600)
255 }
256
257 /// Create a duration representing the specified number of minutes
258 pub fn minutes(m: u64) -> Duration {
259 Duration::from_secs(m * 60)
260 }
261
262 /// Create a duration representing the specified number of days
263 pub fn days(d: u64) -> Duration {
264 Duration::from_secs(d * 86400)
265 }
266
267 /// Create a duration representing the specified number of weeks
268 pub fn weeks(w: u64) -> Duration {
269 Duration::from_secs(w * 604800)
270 }
271
272 /// Create a duration representing the specified number of seconds
273 pub fn seconds(s: u64) -> Duration {
274 Duration::from_secs(s)
275 }
276}
277
278// Rate limiting helpers for ergonomic configuration
279pub mod rate {
280 use std::time::Duration;
281
282 /// Helper for specifying request counts in rate limiting
283 pub struct RequestCount(pub u32);
284
285 /// Helper for creating request count specifications
286 pub fn requests(count: u32) -> RequestCount {
287 RequestCount(count)
288 }
289
290 impl RequestCount {
291 /// Specify rate limit as "per second"
292 pub fn per_second(self) -> (u32, Duration) {
293 (self.0, Duration::from_secs(1))
294 }
295
296 /// Specify rate limit as "per minute"
297 pub fn per_minute(self) -> (u32, Duration) {
298 (self.0, Duration::from_secs(60))
299 }
300
301 /// Specify rate limit as "per hour"
302 pub fn per_hour(self) -> (u32, Duration) {
303 (self.0, Duration::from_secs(3600))
304 }
305
306 /// Specify rate limit as "per day"
307 pub fn per_day(self) -> (u32, Duration) {
308 (self.0, Duration::from_secs(86400))
309 }
310
311 /// Specify custom rate limit window
312 pub fn per(self, duration: Duration) -> (u32, Duration) {
313 (self.0, duration)
314 }
315 }
316}
317
318// Re-export time and rate helpers at the top level for convenience
319pub use rate::{RequestCount, requests};
320pub use time::{days, hours, minutes, seconds, weeks};
321
322// Common type aliases for ergonomics
323/// Convenience alias for `Result<T, AuthError>`.
324pub type AuthFrameworkResult<T> = Result<T, AuthError>;
325
326/// A boxed, `Send`-safe async future returning `AuthFrameworkResult<()>`.
327///
328/// Useful for storing async handler callbacks in collections.
329pub type AsyncAuthHandler =
330 std::pin::Pin<Box<dyn std::future::Future<Output = AuthFrameworkResult<()>> + Send>>;
331
332// Import security presets from the security module
333pub use crate::security::SecurityPreset; // Performance presets for optimization
334#[derive(Debug, Clone)]
335pub enum PerformancePreset {
336 /// Optimized for high request throughput
337 HighThroughput,
338 /// Optimized for low latency responses
339 LowLatency,
340 /// Optimized for minimal memory usage
341 LowMemory,
342 /// Balanced performance settings
343 Balanced,
344}
345
346// Use case presets for common application types
347#[derive(Debug, Clone)]
348pub enum UseCasePreset {
349 /// Web application with sessions and cookies
350 WebApp,
351 /// REST API service with JWT tokens
352 ApiService,
353 /// Microservices with distributed auth
354 Microservices,
355 /// Mobile app backend
356 MobileBackend,
357 /// Enterprise application with RBAC
358 Enterprise,
359}