authrs 0.1.2

A comprehensive authentication library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

# AuthRS | Rust Authentication Toolkit

[中文版 README](README.zh-CN.md)

## Overview
AuthRS is a Rust 2024 authentication toolkit that consolidates password hashing, JWT/session tokens, MFA, passwordless (Magic Link / OTP), OAuth2 clients, RBAC, WebAuthn/Passkeys, CSRF, rate limiting, and secure randomness utilities so you can assemble robust auth flows without re-implementing primitives.

## Features
- Password hashing and strength validation (Argon2, bcrypt, scrypt, policy helpers)
- Secure random generators and constant-time comparison helpers
- JWT creation/validation plus refresh/session token management
- MFA (TOTP/HOTP) with recovery codes and otpauth helpers
- Passwordless (Magic Link / OTP) flows with in-memory stores
- API key lifecycle management and validation
- OAuth 2.0 clients with PKCE, scopes, and token introspection
- WebAuthn/Passkeys flows for passwordless registration/authentication
- RBAC policies and role utilities
- Account safety rails (lockout, login tracking, IP banning) and secure cookies
- CSRF protection, adaptive rate limiting, and audit logging
- HKDF-based crypto helpers (SHA-256/SHA-512)
- Cargo feature flags to tailor footprint (`argon2`, `bcrypt`, `scrypt`, `jwt`, `mfa`, `api-key`, `passwordless`, `crypto`, `oauth`, `rbac`, `webauthn`, `full`)

## Project Structure
```
src/
  lib.rs        # Library entry + public exports
  main.rs       # Minimal binary stub for manual experiments
  error.rs      # Shared Error/Result definitions
  password/     # Hashers + strength rules
  token/        # jwt.rs, refresh.rs, session.rs
  mfa/          # TOTP/HOTP + recovery modules
  passwordless/ # Magic Link & OTP helpers
  oauth/        # OAuth2 clients, PKCE, token handling
  rbac/         # Role/policy helpers
  webauthn/     # Passkey flows and validation
  crypto/       # HKDF key derivation helpers
  api_key/      # API key lifecycle management
  security/     # csrf.rs, rate_limit.rs, account.rs (lockout), cookie.rs
  random.rs     # Secure RNG helpers
  audit.rs      # Security event logging utilities
```

## Getting Started
```bash
cargo add authrs                # Add as a dependency
cargo build                     # Build with default features
cargo test --features full      # Run tests with all modules
```
Use `--no-default-features --features <list>` to mix modules precisely (e.g., `cargo build --no-default-features --features jwt,passwordless`).

## Example
```rust
use authrs::password::hash_password;
use authrs::token::jwt::{JwtBuilder, JwtValidator};

let hash = hash_password("Str0ng_P@ss")?;
let token = JwtBuilder::new()
    .subject("user123")
    .issuer("authrs-demo")
    .expires_in_hours(24)
    .build_with_secret(b"my-secret-key-at-least-32-bytes!")?;
let claims = JwtValidator::new(b"my-secret-key-at-least-32-bytes!").validate(&token)?;
println!("subject={}", claims.sub.unwrap_or_default());
```

## Feature Flags
- Defaults: `argon2`, `jwt`, `mfa`
- Optional: `bcrypt`, `scrypt`, `oauth`, `rbac`, `webauthn`, `passwordless`, `crypto`, `api-key`
- `full` turns on every optional module (including OAuth, RBAC, WebAuthn)
- Combine selectively via `cargo build --no-default-features --features jwt,scrypt`

## Development Workflow
```bash
cargo fmt                                  # Format with rustfmt
cargo clippy --all-targets --all-features  # Run static analysis
cargo test --features full                 # Execute full-feature test suite
cargo doc --open                           # Build API docs
```
Place unit tests alongside modules, and integration tests under `tests/` when composing flows. Prefer deterministic RNG (`StdRng::seed_from_u64`) for assertions; reserve `OsRng` for production randomness. Use feature-specific flags to validate gated paths (e.g., `--features oauth` or `--features webauthn`).

## Security Notes
- Never commit secrets or sample JWT keys—load them via ignored config or environment variables.
- Avoid relaxing Argon2/bcrypt parameters, CSRF TTLs, or rate-limit thresholds without design review and regression tests.
- Use constant-time helpers such as `constant_time_compare` from `random.rs` when comparing secrets.

## License
MIT License — see `LICENSE` for the full text.