Struct AuthFramework 

pub struct AuthFramework { /* private fields */ }

The primary authentication and authorization framework for Rust applications.

AuthFramework is the central component that orchestrates all authentication and authorization operations. It provides a unified interface for multiple authentication methods, token management, session handling, and security monitoring.

Core Capabilities

• Multi-Method Authentication: Support for password, OAuth2, MFA, passkeys, and custom methods
• Token Management: JWT token creation, validation, and lifecycle management
• Session Management: Secure session handling with configurable storage backends
• Permission System: Role-based and resource-based authorization
• Security Monitoring: Real-time threat detection and audit logging
• Rate Limiting: Configurable rate limiting for brute force protection

Thread Safety

The framework is designed for concurrent use and can be safely shared across multiple threads using Arc<AuthFramework>.

Storage Backends

Supports multiple storage backends:

• In-memory (for development/testing)
• Redis (for production with clustering)
• PostgreSQL (for persistent storage)
• Custom implementations via the AuthStorage trait

Example

use auth_framework::{AuthFramework, AuthConfig};
use auth_framework::authentication::credentials::Credential;
use auth_framework::methods::AuthMethodEnum;

// Create framework with default configuration
let config = AuthConfig::default();
let mut auth = AuthFramework::new(config);

// Register an authentication method
auth.register_method("password", password_method);

// Authenticate a user
let result = auth.authenticate("password", credential).await?;

Security Considerations

• All tokens are signed with cryptographically secure keys
• Session data is encrypted at rest when using persistent storage
• Rate limiting prevents brute force attacks
• Audit logging captures all security-relevant events
• Configurable security policies for enterprise compliance

Implementations

impl AuthFramework

pub fn users(&self) -> UserOperations<'_>

Access focused user-management operations.

pub fn sessions(&self) -> SessionOperations<'_>

Access focused session-management operations.

pub fn tokens(&self) -> TokenOperations<'_>

Access focused token-management operations.

pub fn authorization(&self) -> AuthorizationOperations<'_>

Access focused authorization operations.

pub fn mfa(&self) -> MfaOperations<'_>

Access focused multi-factor authentication operations.

pub fn monitoring(&self) -> MonitoringOperations<'_>

Access focused monitoring and health operations.

pub fn audit(&self) -> AuditOperations<'_>

Access focused audit log operations.

pub fn maintenance(&self) -> MaintenanceOperations<'_>

Access focused maintenance operations.

pub async fn runtime_config(&self) -> RuntimeConfig

Read the current runtime-mutable configuration.

pub async fn update_runtime_config( &self, update: RuntimeConfig, ) -> Result<RuntimeConfig>

Apply a partial or full update to the runtime-mutable configuration.

The update is applied atomically. Returns the updated configuration. Returns Err if any field value is out of range (e.g. zero token lifetime).

pub fn admin(&self) -> AdminOperations<'_>

Access focused advanced administration operations (ABAC, delegation, role hierarchy).

pub fn new(config: AuthConfig) -> Self

Create a new authentication framework.

This method is infallible and creates a basic framework instance. Configuration validation and component initialization is deferred to initialize(). An ephemeral random secret is used for the token manager until initialize() replaces it with the configured secret. Tokens issued before initialization will NOT be valid afterwards.

pub fn new_validated(config: AuthConfig) -> Result<Self>

Create a new authentication framework with validation.

This method validates the configuration immediately and returns an error if the configuration is invalid. Use this when you want early validation.

pub fn replace_storage(&mut self, storage: Arc<dyn AuthStorage>)

Replace the storage backend with a custom implementation.

This will swap the internal storage Arc so subsequent operations use the provided storage instance. Implementations that rely on a different concrete storage may need additional reconfiguration by the caller.

pub fn set_distributed_store(&mut self, store: Arc<dyn DistributedSessionStore>)

Replace the distributed session store.

Call this during application startup after configuring a distributed cache (Redis, Valkey, Hazelcast, etc.) so that coordinate_distributed_sessions reports accurate cross-node session counts instead of 0.

pub fn new_with_storage( config: AuthConfig, storage: Arc<dyn AuthStorage>, ) -> Self

Convenience constructor that creates a framework with a custom storage instance.

pub fn register_method( &mut self, name: impl Into<String>, method: AuthMethodEnum, )

Register an authentication method.

pub async fn initialize(&mut self) -> Result<()>

Initialize the authentication framework.

This method performs configuration validation, sets up secure components, and prepares the framework for use. It must be called before any other operations.

Security Note

This method validates JWT secrets and replaces any temporary secrets with properly configured ones for production security.

pub async fn authenticate( &self, method_name: &str, credential: Credential, ) -> Result<AuthResult>

Authenticate a user with the specified method.

method_name must match a previously registered authentication method (e.g. "password", "jwt", "oauth2").

Returns

• AuthResult::Success — authentication succeeded; contains the issued token.
• AuthResult::MfaRequired — first factor passed but MFA is required.
• AuthResult::Failure — invalid credentials.

Example

let result = auth.authenticate("password", Credential::password("alice", "S3cur3P@ss!")).await?;
match result {
    AuthResult::Success(token) => println!("Token: {}", token.access_token),
    AuthResult::MfaRequired(challenge) => println!("MFA needed: {:?}", challenge),
    AuthResult::Failure(msg) => eprintln!("Login failed: {msg}"),
}

pub async fn authenticate_with_metadata( &self, method_name: &str, credential: Credential, metadata: CredentialMetadata, ) -> Result<AuthResult>

Authenticate a user with the specified method and metadata.

pub async fn complete_mfa( &self, challenge: MfaChallenge, mfa_code: &str, ) -> Result<AuthToken>

Complete multi-factor authentication.

pub async fn complete_mfa_by_id( &self, challenge_id: &str, mfa_code: &str, ) -> Result<AuthToken>

Complete MFA using a previously issued challenge ID.

pub async fn validate_token(&self, token: &AuthToken) -> Result<bool>

Validate a token.

pub async fn get_user_info(&self, token: &AuthToken) -> Result<UserInfo>

Get user information from a token.

pub async fn check_permission( &self, token: &AuthToken, action: &str, resource: &str, ) -> Result<bool>

Check if a token has permission to perform an action on a resource.

This method validates the token and checks if the authenticated user has the required permission for the specified action on the given resource.

Parameters

• token: The authentication token to validate and check permissions for
• action: The action being requested (e.g., “read”, “write”, “delete”)
• resource: The resource being accessed (e.g., “documents”, “users”, “reports/123”)

Returns

Returns true if the token is valid and the user has the required permission, false if the token is invalid or the user lacks permission.

Example

if auth.check_permission(token, "read", "documents").await? {
    println!("User can read documents");
} else {
    println!("Access denied");
}

pub async fn refresh_token(&self, token: &AuthToken) -> Result<AuthToken>

Refresh a token.

pub async fn revoke_token(&self, token: &AuthToken) -> Result<()>

Revoke a token.

pub async fn create_api_key( &self, user_id: &str, expires_in: Option<Duration>, ) -> Result<String>

Create a new API key for a user.

pub async fn validate_api_key(&self, api_key: &str) -> Result<UserInfo>

Validate an API key and return user information.

pub async fn revoke_api_key(&self, api_key: &str) -> Result<()>

Revoke an API key.

pub async fn create_session( &self, user_id: &str, expires_in: Duration, ip_address: Option<String>, user_agent: Option<String>, ) -> Result<String>

Create a new session.

pub async fn create_session_with_request( &self, req: SessionCreateRequest, ) -> Result<String>

Create a new session using a SessionCreateRequest for better readability.

Prefer create_session_with_request with a SessionCreateRequest for better readability when using optional fields.

Example

let session_id = auth.create_session_with_request(
    SessionCreateRequest::new("user_123", Duration::from_secs(3600))
        .ip_address("192.168.1.1")
        .user_agent("MyApp/1.0")
).await?;

pub async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>>

Get session information.

pub async fn delete_session(&self, session_id: &str) -> Result<()>

Delete a session.

pub async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>>

Get all tokens for a user.

pub async fn cleanup_expired_data(&self) -> Result<()>

Clean up expired data.

pub async fn get_stats(&self) -> Result<AuthStats>

Get authentication framework statistics.

pub fn token_manager(&self) -> &TokenManager

Returns a reference to the underlying TokenManager.

Useful for advanced token operations not exposed by the TokenOperations facade.

pub async fn validate_username(&self, username: &str) -> Result<bool>

Validates a username against the configured format rules.

Returns Ok(true) when the name is acceptable, or an error describing the specific rule that was violated (length, characters, etc.).

Errors

Returns AuthError if the username is empty, too long, or contains forbidden characters per the active [SecurityConfig].

pub async fn validate_display_name(&self, display_name: &str) -> Result<bool>

Validates a display name against the configured format rules.

Errors

Returns AuthError if the display name is empty or exceeds the configured maximum length.

pub async fn validate_password_strength(&self, password: &str) -> Result<bool>

Checks a password against the active security policy.

Validates minimum length, character-class requirements, and (optionally) checks against known-breached password lists.

Errors

Returns AuthError describing which policy rule the password violates.

pub async fn validate_user_input(&self, input: &str) -> Result<bool>

Validates arbitrary user input against common injection patterns.

Checks for SQL injection, XSS, and command injection markers. Returns Ok(true) when the input is safe.

pub async fn create_auth_token( &self, user_id: impl Into<String>, scopes: impl Into<Scopes>, method_name: impl Into<String>, lifetime: Option<Duration>, ) -> Result<AuthToken>

Creates an authentication token directly.

This is a low-level API intended for testing, migration tools, and administrative tasks. In production, tokens should be created through authenticate instead.

Parameters

• user_id — the subject the token is issued to.
• scopes — OAuth-style scopes (accepts Vec<String>, Scopes, or &[&str]).
• method_name — the auth method to record (must be registered).
• lifetime — override the default token TTL; None uses the framework-configured default.

Errors

• AuthError::AuthMethod if method_name is not registered.
• AuthError::RateLimit if the user already holds the maximum number of active tokens.

pub async fn initiate_sms_challenge(&self, user_id: &str) -> Result<String>

Initiates an SMS-based MFA challenge for user_id.

Sends a one-time code via the configured SMS provider and returns a challenge ID that must be passed to verify_sms_code.

Errors

Returns AuthError if no phone number is registered or the SMS provider fails to deliver.

pub async fn verify_sms_code( &self, challenge_id: &str, code: &str, ) -> Result<bool>

Verifies an SMS challenge code previously issued by initiate_sms_challenge.

Errors

Returns AuthError if the challenge has expired or if the code is invalid.

pub async fn register_email(&self, user_id: &str, email: &str) -> Result<()>

Registers an email address for email-based MFA for user_id.

Errors

Returns AuthError if the email format is invalid or the user does not exist.

pub async fn generate_totp_secret(&self, user_id: &str) -> Result<String>

Generates a new TOTP secret and stores it for user_id.

The returned string is a Base32-encoded secret suitable for importing into authenticator apps. Pair with generate_totp_qr_code for a scan-ready URI.

Errors

Returns AuthError if secret generation or storage fails.

pub async fn generate_totp_qr_code( &self, user_id: &str, app_name: &str, secret: &str, ) -> Result<String>

Generates an otpauth:// URI suitable for rendering as a QR code.

Parameters

• user_id — identifies the user in the authenticator label.
• app_name — the issuer name shown in the authenticator app.
• secret — the Base32 TOTP secret from generate_totp_secret.

pub async fn generate_totp_code(&self, secret: &str) -> Result<String>

Generates the current TOTP code for the given Base32 secret.

Primarily useful for testing; in production the user generates the code on their device.

pub async fn generate_totp_code_for_window( &self, secret: &str, time_window: Option<u64>, ) -> Result<String>

Generates a TOTP code for the given secret and optional time window.

When time_window is None, the current 30-second window is used.

pub async fn verify_totp_code(&self, user_id: &str, code: &str) -> Result<bool>

Verifies a TOTP code against the stored secret for user_id.

Applies a configurable clock-skew window (default: ±1 step).

Errors

Returns AuthError if no TOTP secret is registered for the user.

pub async fn check_ip_rate_limit(&self, ip: &str) -> Result<bool>

Checks whether the given IP address is within the configured rate limit.

Returns Ok(true) if the request is allowed, or an AuthError::RateLimit if the caller should be throttled.

pub async fn get_security_metrics(&self) -> Result<HashMap<String, u64>>

Return security metrics for monitoring dashboards.

Keys include active_sessions, total_tokens, failed_attempts, successful_attempts, and expired_tokens.

pub async fn register_phone_number( &self, user_id: &str, phone_number: &str, ) -> Result<()>

Registers a phone number for SMS-based MFA.

Errors

Returns AuthError if the phone number format is invalid.

pub async fn generate_backup_codes( &self, user_id: &str, count: usize, ) -> Result<Vec<String>>

Generate count one-time backup codes for the given user.

Codes are persisted server-side (hashed); plaintext codes are returned to the caller for display to the user.

pub async fn grant_permission( &self, user_id: &str, action: &str, resource: &str, ) -> Result<()>

Grants an authorization permission to a user.

Parameters

• user_id — the user receiving the permission.
• action — the action being allowed (e.g. "read", "write").
• resource — the resource scope (e.g. "documents", "users:*").

Errors

Returns AuthError if the user does not exist or storage fails.

pub async fn initiate_email_challenge(&self, user_id: &str) -> Result<String>

Initiates an email-based MFA challenge for user_id.

Sends a one-time code to the registered email address and returns a challenge ID.

Errors

Returns AuthError if no email is registered for the user or delivery fails.

pub fn storage(&self) -> Arc<dyn AuthStorage>

Returns a cloned handle to the storage backend.

Useful when you need to pass storage to another component or run direct queries outside the framework’s managed API.

pub fn config(&self) -> &AuthConfig

Returns a reference to the active framework configuration.

pub async fn reset_authorization_runtime(&self)

Reset runtime authorization state back to the default roles.

pub async fn register_user( &self, username: &str, email: &str, password: &str, ) -> Result<String>

Register a new user with username, email, and password.

The password is hashed with the configured algorithm (default: Argon2) before storage. Returns the generated user ID on success.

Errors

Returns AuthError if:

• The username or email is already taken
• The password does not meet the configured complexity requirements
• The storage backend is unavailable

Example

let user_id = auth.users().register("alice", "alice@example.com", "S3cur3P@ss!").await?;
println!("Created user: {user_id}");

pub async fn list_users( &self, limit: Option<usize>, offset: Option<usize>, active_only: bool, ) -> Result<Vec<UserInfo>>

👎Deprecated since 0.6.0:

use list_users_with_query(UserListQuery::new().limit(n).active_only()) instead

List users from the canonical user index with optional filtering and pagination.

This method provides paginated access to the user directory with optional filtering by active status.

Parameters

• limit: Maximum number of users to return (None for no limit)
• offset: Number of users to skip for pagination (None for start from beginning)
• active_only: If true, only return active users; if false, return all users

Returns

Returns a vector of UserInfo structs containing user details.

Example

// Get first 10 active users
let users = auth.list_users(Some(10), None, true).await?;
println!("Found {} active users", users.len());

// Get all users (active and inactive)
let all_users = auth.list_users(None, None, false).await?;

pub async fn list_users_with_query( &self, query: UserListQuery, ) -> Result<Vec<UserInfo>>

List users using a UserListQuery for better readability.

Prefer list_users_with_query with a UserListQuery for better readability when using pagination or filtering.

Example

let users = auth.list_users_with_query(
    UserListQuery::new()
        .limit(50)
        .active_only()
).await?;

pub async fn get_user_record(&self, user_id: &str) -> Result<UserInfo>

Get user information by canonical user ID.

pub async fn update_user_roles( &self, user_id: &str, roles: &[String], ) -> Result<()>

Update the roles assigned to a user.

pub async fn set_user_active(&self, user_id: &str, active: bool) -> Result<()>

Set a user’s active / deactivated status.

pub async fn update_user_email(&self, user_id: &str, email: &str) -> Result<()>

Update a user’s email address.

pub async fn verify_user_password( &self, user_id: &str, password: &str, ) -> Result<bool>

Verify a user’s password by user_id against the stored bcrypt hash.

pub async fn get_username_by_id(&self, user_id: &str) -> Result<String>

Look up a user’s username by their user_id.

pub async fn username_exists(&self, username: &str) -> Result<bool>

Check if a username exists.

pub async fn email_exists(&self, email: &str) -> Result<bool>

Check if an email exists.

pub async fn get_user_by_username( &self, username: &str, ) -> Result<HashMap<String, Value>>

Get user data by username.

pub async fn update_user_password( &self, username: &str, new_password: &str, ) -> Result<()>

Update user password.

pub async fn update_user_password_by_id( &self, user_id: &str, new_password: &str, ) -> Result<()>

Update user password by canonical user ID.

pub async fn delete_user(&self, username: &str) -> Result<()>

Delete a user by username.

pub async fn delete_user_by_id(&self, user_id: &str) -> Result<()>

Delete a user by canonical user ID.

pub async fn coordinate_distributed_sessions( &self, ) -> Result<SessionCoordinationStats>

Coordinate session state across distributed instances.

pub async fn synchronize_session(&self, session_id: &str) -> Result<()>

Synchronize a specific session with remote instances.

pub fn monitoring_manager(&self) -> Arc<MonitoringManager>

Returns the monitoring manager for metrics collection and health checks.

pub fn security_manager(&self) -> Option<Arc<SecurityManager>>

Returns the security manager for rate limiting, DoS protection, and IP blacklisting.

pub async fn get_performance_metrics(&self) -> HashMap<String, u64>

Return current performance metrics (token counts, latencies, etc.).

pub async fn health_check(&self) -> Result<HashMap<String, HealthCheckResult>>

Run a health check on all sub-systems (storage, token engine, etc.).

pub async fn export_prometheus_metrics(&self) -> String

Export all collected metrics in Prometheus text exposition format.

pub async fn create_role(&self, role: Role) -> Result<()>

Create a new role.

pub async fn list_roles(&self) -> Vec<Role>

Return all defined roles.

pub async fn get_role(&self, role_name: &str) -> Result<Role>

Fetch a role definition by name.

pub async fn add_role_permission( &self, role_name: &str, permission: Permission, ) -> Result<()>

Add a permission to an existing role.

pub async fn assign_role(&self, user_id: &str, role_name: &str) -> Result<()>

Assign a role to a user.

pub async fn remove_role(&self, user_id: &str, role_name: &str) -> Result<()>

Remove a role from a user.

pub async fn set_role_inheritance( &self, child_role: &str, parent_role: &str, ) -> Result<()>

Set role inheritance.

pub async fn revoke_permission( &self, user_id: &str, action: &str, resource: &str, ) -> Result<()>

Revoke permission from a user.

pub async fn user_has_role( &self, user_id: &str, role_name: &str, ) -> Result<bool>

Check if user has a role.

pub async fn list_user_roles(&self, user_id: &str) -> Result<Vec<String>>

List the currently assigned runtime roles for a user.

pub async fn get_effective_permissions( &self, user_id: &str, ) -> Result<Vec<String>>

Get effective permissions for a user.

pub async fn create_abac_policy( &self, name: &str, description: &str, ) -> Result<()>

Create ABAC policy.

pub async fn map_user_attribute( &self, user_id: &str, attribute: &str, value: &str, ) -> Result<()>

Set a user attribute value for ABAC (Attribute-Based Access Control) evaluation.

User attributes are key-value pairs associated with users that can be used in dynamic permission rules. This method stores or updates an attribute value.

Parameters

• user_id: The ID of the user to set the attribute for
• attribute: The name of the attribute to set
• value: The value to assign to the attribute

Example

// Set user attributes for policy evaluation
auth.map_user_attribute("example_user", "department", "engineering").await?;
auth.map_user_attribute("example_user", "clearance_level", "confidential").await?;

pub async fn get_user_attribute( &self, user_id: &str, attribute: &str, ) -> Result<Option<String>>

Get a user attribute value for ABAC (Attribute-Based Access Control) evaluation.

User attributes are key-value pairs associated with users that can be used in dynamic permission rules. Common attributes include department, clearance level, location, etc.

Parameters

• user_id: The ID of the user whose attribute to retrieve
• attribute: The name of the attribute to retrieve

Returns

Returns Some(value) if the attribute exists, None if it doesn’t exist.

Example

if let Some(dept) = auth.get_user_attribute("example_user", "department").await? {
    println!("User is in department: {}", dept);
}

pub async fn check_dynamic_permission( &self, user_id: &str, action: &str, resource: &str, context: HashMap<String, String>, ) -> Result<bool>

Check dynamic permission with context evaluation (ABAC - Attribute-Based Access Control).

This method evaluates permissions based on user attributes, resource attributes, and environmental context rather than just role assignments. It’s more flexible than simple role-based checks but requires more complex policy rules.

Parameters

• user_id: The ID of the user requesting access
• action: The action being requested (e.g., “read”, “write”, “delete”)
• resource: The resource being accessed (e.g., “documents”, “users”, “reports/123”)
• context: Additional context key-value pairs for policy evaluation

Returns

Returns true if the permission is granted based on the dynamic policy evaluation.

Example

let mut context = HashMap::new();
context.insert("time_of_day".to_string(), "business_hours".to_string());
context.insert("ip_location".to_string(), "office".to_string());

if auth.check_dynamic_permission("example_user", "read", "confidential_docs", context).await? {
    println!("Access granted based on dynamic policy");
}

pub async fn check_dynamic_permission_with_context( &self, user_id: &str, action: &str, resource: &str, context: PermissionContext, ) -> Result<bool>

Check dynamic permission using a structured context (preferred).

Prefer check_dynamic_permission_with_context with a PermissionContext for better type safety and readability.

Example

let context = PermissionContext::new()
    .with_attribute("time_of_day", "business_hours")
    .with_attribute("ip_location", "office");

if auth.check_dynamic_permission_with_context("example_user", "read", "confidential_docs", context).await? {
    println!("Access granted based on dynamic policy");
}

pub async fn create_resource(&self, resource: &str) -> Result<()>

Create resource for permission management.

pub async fn delegate_permission_with_request( &self, req: DelegationRequest, ) -> Result<()>

Delegate permission from one user to another using a DelegationRequest.

This is the preferred method for delegation as it avoids passing multiple parameters and makes the call site self-documenting.

Example

let req = DelegationRequest::new("admin_1", "user_2", "write", "reports")
    .duration(Duration::from_secs(3600));
auth.delegate_permission_with_request(req).await?;

pub async fn delegate_permission( &self, delegator_id: &str, delegatee_id: &str, action: &str, resource: &str, duration: Duration, ) -> Result<()>

Delegate permission from one user to another.

Prefer delegate_permission_with_request with a DelegationRequest for better readability when delegating permissions.

pub async fn get_active_delegations(&self, user_id: &str) -> Result<Vec<String>>

Get active delegations for a user.

pub async fn get_permission_audit_logs( &self, user_id: Option<&str>, action: Option<&str>, resource: Option<&str>, limit: Option<usize>, ) -> Result<Vec<String>>

Get permission audit logs with filtering.

pub async fn get_permission_audit_logs_with_query( &self, query: AuditLogQuery, ) -> Result<Vec<String>>

Get permission audit logs using an AuditLogQuery for better readability.

Prefer get_permission_audit_logs_with_query with an AuditLogQuery for better readability when using multiple filters.

Example

let logs = auth.get_permission_audit_logs_with_query(
    AuditLogQuery::new()
        .user("user_123")
        .action("read")
        .limit(50)
).await?;

pub async fn get_permission_metrics( &self, ) -> Result<HashMap<String, u64>, AuthError>

Get permission metrics for monitoring.

pub async fn get_security_audit_stats(&self) -> Result<SecurityAuditStats>

Collect comprehensive security audit statistics.

pub async fn get_user_profile(&self, user_id: &str) -> Result<ProviderProfile>

Get user profile information

impl AuthFramework

pub fn builder() -> AuthBuilder

Create a new builder for the authentication framework

pub fn quick_start() -> QuickStartBuilder

Quick start builder for common setups

pub fn for_use_case(use_case: UseCasePreset) -> AuthBuilder

Create a builder for a specific use case

pub fn preset(preset: SecurityPreset) -> AuthBuilder

Create an authentication framework with preset configuration