Crate authrs

Source

Expand description

§AuthRS

一个全面的 Rust 认证库。

§功能特性

密码哈希: 使用 Argon2、bcrypt、scrypt 进行安全的密码哈希
密码强度检查: 密码强度评估与验证
安全随机数: 密码学安全的随机数生成
JWT Token: JSON Web Token 的生成、验证和刷新
Session 管理: 安全的 Session 创建、验证和存储
Refresh Token: Token 轮换和重用检测
MFA: TOTP/HOTP 多因素认证
速率限制: 防止暴力破解攻击
CSRF 防护: 跨站请求伪造防护
OAuth 2.0: OAuth 客户端、PKCE、Token 内省
API Key 管理: 完整的 API Key 生命周期管理
账户安全: 账户锁定、登录追踪、递增延迟
WebAuthn / Passkeys: 无密码认证支持
RBAC: 角色权限管理、策略引擎
审计日志: 安全事件记录与查询
安全 Cookie: Cookie 签名、验证与安全属性管理
密钥派生: HKDF-SHA256/SHA512 密钥派生函数
Passwordless: Magic Link 与 OTP 支持
API Key 管理: API Key 生命周期管理与校验

§Features

本库使用 Cargo features 来允许用户选择性地启用功能：

argon2 - 启用 Argon2id 密码哈希支持（默认启用）
bcrypt - 启用 bcrypt 密码哈希支持
scrypt - 启用 scrypt 密码哈希支持
jwt - 启用 JWT 支持（默认启用）
mfa - 启用 TOTP/HOTP 多因素认证（默认启用）
oauth - 启用 OAuth 2.0 支持（PKCE、客户端管理、Token 内省）
rbac - 启用 RBAC 角色权限管理支持
webauthn - 启用 WebAuthn / Passkeys 支持
passwordless - 启用 Magic Link / OTP 无密码认证支持
crypto - 启用密码学工具（HKDF 等）
api-key - 启用 API Key 管理支持
full - 启用所有功能

默认启用的 features: argon2, jwt, mfa

§密码哈希示例

use authrs::password::{hash_password, verify_password};

// 哈希密码
let hash = hash_password("my_secure_password").unwrap();

// 验证密码
let is_valid = verify_password("my_secure_password", &hash).unwrap();
assert!(is_valid);

§密码强度检查

use authrs::password::{validate_password_strength, PasswordRequirements};

// 使用默认要求
let result = validate_password_strength("Str0ng_P@ssword!");
assert!(result.is_ok());

// 使用严格要求
let requirements = PasswordRequirements::strict();

§JWT Token 示例

use authrs::token::jwt::{JwtBuilder, JwtValidator};

// 创建 JWT
let secret = b"my-secret-key-at-least-32-bytes!";
let token = JwtBuilder::new()
    .subject("user123")
    .issuer("my-app")
    .expires_in_hours(24)
    .build_with_secret(secret)
    .unwrap();

// 验证 JWT
let validator = JwtValidator::new(secret);
let claims = validator.validate(&token).unwrap();

§Session 管理示例

use authrs::token::session::{SessionManager, SessionConfig};

// 创建 Session 管理器
let manager = SessionManager::new(SessionConfig::default());

// 创建 Session
let session = manager.create("user123").await.unwrap();

// 获取 Session
if let Some(s) = manager.get(&session.id).await {
    println!("User: {}", s.user_id);
}

§OAuth 2.0 示例

use authrs::oauth::{OAuthClient, ClientType, GrantType, PkceChallenge, PkceMethod};

// 创建 OAuth 客户端
let (client, secret) = OAuthClient::builder()
    .name("My Application")
    .client_type(ClientType::Confidential)
    .redirect_uri("https://example.com/callback")
    .grant_type(GrantType::AuthorizationCode)
    .scope("read")
    .build()
    .unwrap();

// 生成 PKCE challenge
let pkce = PkceChallenge::new(PkceMethod::S256).unwrap();
let (code_challenge, method) = pkce.authorization_params();

§API Key 管理示例

use authrs::api_key::{ApiKeyManager, ApiKeyConfig};

// 创建管理器
let mut manager = ApiKeyManager::with_default_config();

// 创建 API Key
let (key, plain_key) = manager.create_key("my-service")
    .with_prefix("sk_live")
    .with_scope("read")
    .with_expires_in_days(90)
    .build()
    .unwrap();

manager.add_key(key);

// 验证 API Key
if let Some(validated) = manager.validate(&plain_key) {
    println!("Key is valid, owner: {}", validated.owner);
}

§账户锁定示例

use authrs::security::account::{LoginAttemptTracker, AccountLockoutConfig, LoginCheckResult};

// 创建追踪器
let mut tracker = LoginAttemptTracker::with_default_config();

// 检查是否允许登录
match tracker.check_login_allowed("user123", None) {
    LoginCheckResult::Allowed => {
        // 允许登录尝试
        // 如果登录失败：
        tracker.record_failed_attempt("user123", None);
        // 如果登录成功：
        // tracker.record_successful_login("user123", None);
    }
    LoginCheckResult::Locked { reason, remaining } => {
        println!("账户已锁定: {:?}", reason);
    }
    LoginCheckResult::DelayRequired { wait_time } => {
        println!("请等待 {:?} 后重试", wait_time);
    }
    LoginCheckResult::IpBanned { ip } => {
        println!("IP {} 已被封禁", ip);
    }
}

§WebAuthn / Passkeys 示例

use authrs::webauthn::{WebAuthnService, RegistrationManager, InMemoryCredentialStore};

// 创建 WebAuthn 服务
let service = WebAuthnService::new(
    "example.com",
    "https://example.com",
    "My Application",
).unwrap();

// 开始注册流程
let reg_manager = service.registration_manager();
let (challenge, state) = reg_manager.start_registration(
    "user123",
    "alice",
    "Alice",
    "My Passkey",
    None,
).unwrap();

// 将 challenge 发送给客户端进行处理...
// 客户端完成后，使用 finish_registration 完成注册

§RBAC 角色权限示例

use authrs::rbac::{Permission, Role, RoleBuilder, RoleManager, PolicyEngine, Policy, Subject, Resource, Action};

// 创建角色管理器
let manager = RoleManager::new();

// 创建角色
let viewer = RoleBuilder::new("viewer")
    .permission(Permission::new("posts", "read"))
    .build();

let editor = RoleBuilder::new("editor")
    .inherit("viewer")
    .permission(Permission::new("posts", "write"))
    .build();

manager.add_role(viewer).await;
manager.add_role(editor).await;

// 检查权限
assert!(
    manager
        .role_has_permission("editor", &Permission::new("posts", "read"))
        .await
);
assert!(
    manager
        .role_has_permission("editor", &Permission::new("posts", "write"))
        .await
);

// 使用策略引擎
let mut engine = PolicyEngine::new();
engine.add_policy(
    Policy::allow("editor-posts")
        .role("editor")
        .resource("posts")
        .actions(["read", "write"])
        .build()
);

let user = Subject::new("user1").with_role("editor");
assert!(engine.check_permission(&user, "posts", "read"));

Re-exports§

pub use error::Error;
pub use error::Result;
pub use password::Algorithm;
pub use password::PasswordHasher;
pub use password::hash_password;
pub use password::verify_password;
pub use random::constant_time_compare;
pub use random::constant_time_compare_str;
pub use random::generate_api_key;
pub use random::generate_csrf_token;
pub use random::generate_random_alphanumeric;
pub use random::generate_random_base64_url;
pub use random::generate_random_bytes;
pub use random::generate_random_hex;
pub use random::generate_recovery_codes;
pub use random::generate_reset_token;
pub use random::generate_session_token;
pub use token::jwt::Claims;
pub use token::jwt::JwtAlgorithm;
pub use token::jwt::JwtBuilder;
pub use token::jwt::JwtValidator;
pub use token::jwt::TokenPair;
pub use token::jwt::TokenPairGenerator;
pub use token::refresh::RefreshConfig;
pub use token::refresh::RefreshToken;
pub use token::refresh::RefreshTokenManager;
pub use token::refresh::RefreshTokenStore;
pub use token::refresh::TokenUseResult;
pub use token::session::CreateSessionOptions;
pub use token::session::InMemorySessionStore;
pub use token::session::Session;
pub use token::session::SessionConfig;
pub use token::session::SessionManager;
pub use token::session::SessionStore;
pub use mfa::hotp::HotpConfig;
pub use mfa::hotp::HotpGenerator;
pub use mfa::recovery::RecoveryCodeManager;
pub use mfa::recovery::RecoveryCodeSet;
pub use mfa::recovery::RecoveryConfig;
pub use mfa::totp::TotpConfig;
pub use mfa::totp::TotpManager;
pub use mfa::totp::TotpSecret;
pub use security::account::AccountLockStatus;
pub use security::account::AccountLockStore;
pub use security::account::AccountLockoutConfig;
pub use security::account::InMemoryAccountLockStore;
pub use security::account::LockReason;
pub use security::account::LoginAttempt;
pub use security::account::LoginAttemptTracker;
pub use security::account::LoginCheckResult;
pub use security::account::TrackerStats;
pub use security::cookie::SameSite;
pub use security::cookie::SecureCookie;
pub use security::cookie::delete_cookie_header;
pub use security::cookie::sign_cookie;
pub use security::cookie::verify_cookie;
pub use security::csrf::CsrfConfig;
pub use security::csrf::CsrfProtection;
pub use security::csrf::CsrfToken;
pub use security::rate_limit::RateLimitConfig;
pub use security::rate_limit::RateLimitInfo;
pub use security::rate_limit::RateLimiter;
pub use audit::AuditLogger;
pub use audit::AuditStats;
pub use audit::EventSeverity;
pub use audit::EventType;
pub use audit::InMemoryAuditLogger;
pub use audit::NoOpAuditLogger;
pub use audit::SecurityEvent;

Modules§

audit: 审计日志模块
error: 统一错误类型模块
mfa: 多因素认证 (MFA) 模块
password: 密码哈希模块
random: 安全随机数生成模块
security: 安全防护模块
token: Token 模块

Crate authrs

Crate authrs Copy item path

§AuthRS

§功能特性

§Features

§密码哈希示例

§密码强度检查

§JWT Token 示例

§Session 管理示例

§OAuth 2.0 示例

§API Key 管理示例

§账户锁定示例

§WebAuthn / Passkeys 示例

§RBAC 角色权限示例

Re-exports§

Modules§

Crate authrs