# 🔐 AVL Auth
**The World's Most Advanced Identity and Access Management System**
[](https://crates.io/crates/avl-auth)
[](https://docs.rs/avl-auth)
[](https://avila.cloud)
[](LICENSE)
---
## 🎯 Why AVL Auth?
AVL Auth is not just another authentication library. It's a **complete identity platform** designed for the next generation of applications:
- ⚡ **Blazing Fast**: Sub-10ms authentication in Brazil, optimized for LATAM
- 🛡️ **Military-Grade Security**: Multiple encryption layers, zero-trust architecture
- 🌐 **Global Scale**: Built on AvilaDB for worldwide distribution
- 🤖 **AI-Powered**: ML-based anomaly detection and risk assessment
- 📊 **LGPD/GDPR Compliant**: Built-in compliance and audit trails
- 🔧 **Developer First**: Simple API, comprehensive docs, batteries included
## ✨ Features
### 🔐 Authentication & Authorization
- **Advanced JWT**: Multi-algorithm support (RS256, ES256, HS256) with automatic key rotation
- **OAuth2/OIDC**: Complete flows for Google, GitHub, Microsoft, Apple
- **Multi-Factor Authentication**:
- TOTP (Time-based One-Time Password)
- WebAuthn/FIDO2 for passwordless auth
- Biometric authentication support
- SMS/Email verification
- Backup codes
- **Passwordless Auth**: Magic links, WebAuthn, biometrics
- **Session Management**: Distributed sessions with device binding
- **API Keys**: Scoped keys with rate limiting and auto-rotation
### 🛡️ Security Features
- **Password Security**:
- Argon2id hashing with configurable cost
- Password strength validation
- Breach detection
- Password history
- Complexity requirements
- **Risk-Based Authentication**:
- Real-time risk scoring
- Anomaly detection
- Geo-velocity checks (impossible travel)
- Device fingerprinting
- IP reputation analysis
- **Zero Trust**: Continuous authentication and verification
- **Rate Limiting**: Token bucket algorithm with distributed state
- **Account Protection**: Lockout policies, suspicious activity detection
### 👥 Access Control
- **RBAC**: Hierarchical roles with permission inheritance
- **ABAC**: Attribute-based policies with conditions:
- IP range restrictions
- Time-based access windows
- User attribute matching
- Risk score thresholds
- **Dynamic Policies**: Real-time policy evaluation
- **Fine-Grained Permissions**: Resource-level access control
### 📊 Observability & Compliance
- **Comprehensive Audit Logs**: Every action tracked
- **User Activity Reports**: Behavioral analytics
- **LGPD/GDPR Compliance**: Built-in data export and deletion
- **Security Events**: Real-time alerting
- **Performance Metrics**: Detailed timing and diagnostics
### 🔧 Developer Experience
- **Simple API**: Intuitive, well-documented
- **Type Safety**: Full Rust type system
- **Async/Await**: Modern async Rust
- **Error Handling**: Descriptive, actionable errors
- **Testing**: Comprehensive test suite
- **Benchmarks**: Performance tracking
## 🚀 Quick Start
Add to your `Cargo.toml`:
```toml
[dependencies]
avl-auth = "0.1"
tokio = { version = "1", features = ["full"] }
# Optional: Full AVL Platform integration
avl-auth = { version = "0.1", features = ["full"] }
# Enables: AvilaDB, AVX Telemetry, Avila Compress, Analytics
```
### Integration with AVL Platform
AVL Auth is designed to work seamlessly with other Avila libraries:
- **AvilaDB**: Distributed user storage with 4MB documents and vector search
- **AVX Telemetry**: Structured logging, metrics, and distributed tracing
- **Avila Compress**: Efficient token and session compression
- **Avila Telemetry**: Time series analysis for behavioral patterns and risk scoring
```toml
[dependencies]
avl-auth = { version = "0.1", features = ["database", "telemetry", "analytics"] }
aviladb = "0.1"
avx-telemetry = "0.1"
```
### Basic Example
```rust
use avl_auth::{AuthClient, Config, Credentials};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Initialize client
let config = Config::default();
let auth = AuthClient::new(config).await?;
// Register user
let user_id = auth.register(
"user@example.com".to_string(),
"SecureP@ss123!".to_string()
).await?;
// Login
let session = auth.login(Credentials {
email: "user@example.com".to_string(),
password: "SecureP@ss123!".to_string(),
device_id: Some("device_123".to_string()),
ip_address: Some("191.36.8.1".parse()?),
}).await?;
// Verify token
let claims = auth.verify_token(&session.access_token).await?;
println!("Authenticated as: {}", claims.email);
Ok(())
}
```
### Advanced Example
```rust
use avl_auth::prelude::*;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let auth = AuthClient::new(Config::default()).await?;
// Setup MFA
let totp_config = auth.mfa_manager()
.generate_totp_config("user@example.com", None);
// Generate API key
let (api_key, metadata) = auth.api_key_manager()
.generate_api_key(
user_id,
"Production API".to_string(),
None,
vec!["read".to_string(), "write".to_string()],
Some(1000), // Rate limit
Some(chrono::Duration::days(90)),
).await?;
// Risk assessment
let risk = auth.risk_engine()
.assess_risk(&user, ip, device_id, user_agent)
.await?;
if risk.level >= RiskLevel::High {
// Require additional verification
}
Ok(())
}
```
## 📖 Documentation
### Core Concepts
#### JWT Tokens
AVL Auth uses JWTs for stateless authentication with automatic key rotation:
```rust
// Keys are rotated automatically based on configuration
auth.jwt_manager().rotate_keys(&new_private, &new_public).await?;
// Get public keys for verification (JWKS endpoint)
let jwks = auth.jwt_manager().get_jwks().await?;
```
#### Session Management
Sessions are distributed and can be bound to devices/IPs:
```rust
// Sessions automatically enforced
let session = auth.session_manager()
.validate_session(&session_id, Some(ip), Some(device_id))
.await?;
// Cleanup expired sessions
auth.session_manager().cleanup_expired_sessions().await?;
```
#### Risk Assessment
Real-time risk scoring based on multiple factors:
```rust
let assessment = auth.risk_engine()
.assess_risk(&user, ip, device_id, user_agent)
.await?;
match assessment.recommended_action {
RiskAction::Allow => { /* Proceed */ },
RiskAction::RequireMfa => { /* Challenge with MFA */ },
RiskAction::Deny => { /* Block */ },
_ => {}
}
```
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────┐
│ Application │
└─────────────────────┬───────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ AVL Auth Client │
├─────────────────────────────────────────────────────┤
│ JWT Manager │ OAuth2 │ MFA │ Permissions │
│ Sessions │ API Keys │ Risk │ Audit │
└─────────────────────┬───────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌────────────────┐
│ AvilaDB │ │AVX Telem.│ │ Avila Telemetry│
│ (Users, Keys)│ │(Logs) │ │ (Time Series) │
└──────────────┘ └──────────┘ └────────────────┘
```
### AVL Platform Integration
AVL Auth leverages the full Avila ecosystem:
| **AvilaDB** | User & session storage | 4MB documents, vector search, <10ms latency in Brazil |
| **AVX Telemetry** | Structured logging | Distributed tracing, metrics aggregation |
| **Avila Compress** | Data compression | Efficient token storage, reduced bandwidth |
| **Avila Telemetry** | Time series analysis | ARIMA forecasting, anomaly detection for risk scoring |
## ⚡ Performance
Benchmarks on AVL Cloud (São Paulo region):
| JWT Create | 0.5ms | 1.2ms | 50,000/s |
| JWT Verify | 0.3ms | 0.8ms | 80,000/s |
| Password Hash | 45ms | 65ms | 1,000/s |
| Password Verify | 45ms | 65ms | 1,000/s |
| Full Login | 8ms | 15ms | 5,000/s |
| API Key Verify | 0.4ms | 1.0ms | 60,000/s |
Run benchmarks:
```bash
cargo bench
```
## 🧪 Testing
```bash
# Run all tests
cargo test
# Run integration tests
cargo test --test integration_tests
# Run with coverage
cargo tarpaulin --out Html
```
## 📝 Configuration
```rust
use avl_auth::Config;
use std::time::Duration;
let config = Config {
database_url: "http://localhost:8000".to_string(),
database_name: "auth".to_string(),
jwt: JwtConfig {
algorithm: "RS256".to_string(),
access_token_ttl: Duration::from_secs(900), // 15 min
refresh_token_ttl: Duration::from_secs(604800), // 7 days
auto_rotate_keys: true,
rotation_interval: Duration::from_secs(7776000), // 90 days
..Default::default()
},
password: PasswordConfig {
min_length: 12,
require_uppercase: true,
require_lowercase: true,
require_numbers: true,
require_special: true,
argon2_memory_cost: 65536, // 64 MB
argon2_time_cost: 3,
..Default::default()
},
risk: RiskConfig {
enabled: true,
mfa_threshold: 60,
block_threshold: 90,
anomaly_detection: true,
geo_velocity_check: true,
..Default::default()
},
..Default::default()
};
```
## 🌍 OAuth2 Providers
Configure external identity providers:
```rust
use avl_auth::models::OAuth2Provider;
let google_provider = OAuth2Provider {
name: "google".to_string(),
client_id: "your-client-id".to_string(),
client_secret: "your-client-secret".to_string(),
auth_url: "https://accounts.google.com/o/oauth2/v2/auth".to_string(),
token_url: "https://oauth2.googleapis.com/token".to_string(),
redirect_url: "https://your-app.com/auth/callback".to_string(),
scopes: vec!["openid".to_string(), "email".to_string(), "profile".to_string()],
};
auth.oauth2_manager().register_provider(google_provider).await?;
```
## 🔒 Security Best Practices
1. **Always use HTTPS in production**
2. **Rotate JWT keys regularly** (auto-rotation enabled by default)
3. **Enable MFA for sensitive operations**
4. **Monitor audit logs** for suspicious activity
5. **Set appropriate rate limits**
6. **Use strong password policies**
7. **Implement CORS properly**
8. **Keep dependencies updated**
## 📊 Comparison
| **Open Source** | ✅ | ❌ | ❌ | ❌ |
| **Self-Hosted** | ✅ | ❌ | ❌ | ❌ |
| **Brazil Latency** | 5-10ms | 80-120ms | 60-100ms | 70-110ms |
| **JWT Rotation** | ✅ Auto | ⚠️ Manual | ⚠️ Manual | ❌ |
| **Risk Engine** | ✅ Built-in | ✅ Paid | ⚠️ Limited | ❌ |
| **ABAC Policies** | ✅ | ✅ Paid | ⚠️ Limited | ❌ |
| **Audit Logs** | ✅ Free | ✅ Paid | ✅ | ⚠️ Limited |
| **WebAuthn** | ✅ | ✅ | ✅ | ❌ |
| **Pricing** | Free/OSS | $$$$ | $$$ | $$ |
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
## 📄 License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.
## 🏛️ Built by Avila
Part of the **AVL Cloud Platform** - The cloud platform genuinely built for Brazil and LATAM.
### Related Projects
- **[AvilaDB](../aviladb/)** - NoSQL database with 4MB documents and vector search
- **[AVX Telemetry](../avx-telemetry/)** - Observability and distributed tracing
- **[Avila Telemetry](../avila-telemetry/)** - Time series and forecasting
- **[Avila Compress](../avila-compress/)** - Native compression (LZ4, Zstd)
- **[AVL Queue](../avl-queue/)** - Message queue and event streaming
- **[AVL Secrets](../avl-secrets/)** - Secrets management
### Links
- 🌐 Website: [avila.cloud](https://avila.cloud)
- 📖 Docs: [docs.avila.cloud](https://docs.avila.cloud)
- 💬 Discord: [discord.gg/avilacloud](https://discord.gg/avilacloud)
- 🐦 Twitter: [@avilacloud](https://twitter.com/avilacloud)
- 📦 Crates.io: [crates.io/crates/avl-auth](https://crates.io/crates/avl-auth)
---
**🔐 Secure your applications with AVL Auth - The most advanced authentication system in the world.**