Skip to main content

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}