03. Authentication & RBAC (foundry_auth)

foundry_core (基础类型) → foundry_auth (认证)
foundry_storage (数据访问) → foundry_auth (查询管理员)

foundry_auth
├── password.rs    # 密码哈希与验证（Argon2id）
├── jwt.rs         # JWT 令牌服务 + AdminClaims
├── rbac.rs        # 基于角色的访问控制
└── lib.rs         # 统一导出

use argon2::{
    Argon2,
    password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString, rand_core::OsRng},
};

pub fn hash_password(password: &str) -> AppResult<String> {
    let salt = SaltString::generate(&mut OsRng);  // ← 加密安全的随机盐
    let argon2 = Argon2::default();               // ← 使用默认参数
    let hash = argon2
        .hash_password(password.as_bytes(), &salt)
        .map_err(|e| AppError::Internal(format!("Password hashing failed: {}", e)))?
        .to_string();

    Ok(hash)
}

Argon2::default()

pub fn verify_password(password: &str, password_hash: &str) -> AppResult<bool> {
    let parsed_hash = PasswordHash::new(password_hash)
        .map_err(|e| AppError::Internal(format!("Invalid password hash format: {}", e)))?;

    let argon2 = Argon2::default();
    Ok(argon2
        .verify_password(password.as_bytes(), &parsed_hash)
        .is_ok())
}

#[test]
fn test_password_hash_and_verify() {
    let password = "admin123456";

    // 哈希密码
    let hash = hash_password(password).expect("Hashing should succeed");

    // 验证正确密码
    assert!(verify_password(password, &hash).expect("Verification should succeed"));

    // 验证错误密码
    assert!(!verify_password("wrong_password", &hash).expect("Verification should succeed"));
}

let hash1 = hash_password("admin123456").unwrap();
let hash2 = hash_password("admin123456").unwrap();
assert_ne!(hash1, hash2);  // ← 哈希值不同
assert!(verify_password("admin123456", &hash1).unwrap());  // ← 但都能验证
assert!(verify_password("admin123456", &hash2).unwrap());

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AdminClaims {
    pub sub: Uuid,                  // Subject：管理员 ID
    pub username: String,           // 用户名
    pub role: String,               // 角色：super_admin | admin | topic_admin
    pub allowed_systems: Vec<String>, // 允许访问的子系统列表
    pub exp: usize,                 // Expiration：过期时间戳
    pub iat: usize,                 // Issued At：签发时间戳
}

impl AdminClaims {
    pub fn is_super_admin(&self) -> bool {
        self.role == "super_admin"
    }

    pub fn is_general_admin(&self) -> bool {
        self.role == "admin"
    }

    pub fn is_topic_admin(&self) -> bool {
        self.role == "topic_admin"
    }

    /// 是否有平台级管理权限
    pub fn has_platform_manage_access(&self) -> bool {
        self.role == "super_admin"
            || self.role == "admin"
            || self.allowed_systems.iter().any(|s| s == "*")
    }

    /// 是否能管理管理员
    pub fn can_manage_admins(&self) -> bool {
        self.role == "super_admin"
    }

    /// 是否能查看平台统计
    pub fn can_view_platform_summary(&self) -> bool {
        self.role == "super_admin" || self.role == "admin"
    }
}

pub struct JwtService {
    secret: String,      // JWT 签名密钥
    expire_hours: i64,   // 令牌有效期（小时）
}

impl JwtService {
    pub fn new(secret: impl Into<String>, expire_hours: i64) -> Self {
        Self {
            secret: secret.into(),
            expire_hours,
        }
    }
}

pub fn generate_token(
    &self,
    admin_id: Uuid,
    username: &str,
    role: &str,
    allowed_systems: Vec<String>,
) -> AppResult<String> {
    let now = Utc::now();
    let exp = (now + Duration::hours(self.expire_hours)).timestamp() as usize;
    let iat = now.timestamp() as usize;

    let claims = AdminClaims {
        sub: admin_id,
        username: username.to_string(),
        role: role.to_string(),
        allowed_systems,
        exp,
        iat,
    };

    encode(
        &Header::default(),  // ← 使用默认 Header（HS256 算法）
        &claims,
        &EncodingKey::from_secret(self.secret.as_bytes()),
    )
    .map_err(|e| AppError::Internal(format!("Failed to generate JWT: {}", e)))
}

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZjY3...Uw.SflKxwRJ...MeJf36
|____________Header_____________|.|________Payload________|.|_Signature_|

HMAC-SHA256(
    base64UrlEncode(header) + "." + base64UrlEncode(payload),
    secret
)

pub fn verify_token(&self, token: &str) -> AppResult<AdminClaims> {
    let validation = Validation::default();  // ← 默认验证规则
    let token_data = decode::<AdminClaims>(
        token,
        &DecodingKey::from_secret(self.secret.as_bytes()),
        &validation,
    )
    .map_err(|e| AppError::Unauthorized(format!("Invalid or expired token: {}", e)))?;

    Ok(token_data.claims)
}

#[test]
fn test_jwt_generation_and_validation() {
    let jwt = JwtService::new("secret_test_key_1234567890", 24);
    let admin_id = Uuid::new_v4();

    // 生成令牌
    let token = jwt
        .generate_token(admin_id, "admin", "super_admin", vec!["*".to_string()])
        .unwrap();

    // 验证令牌
    let claims = jwt.verify_token(&token).unwrap();
    assert_eq!(claims.sub, admin_id);
    assert_eq!(claims.username, "admin");
    assert_eq!(claims.role, "super_admin");
    assert_eq!(claims.allowed_systems, vec!["*"]);
}

pub fn check_system_access(
    claims: &AdminClaims,
    target_system_slug: &str
) -> AppResult<()> {
    // 1. Super Admin 和 General Admin 有全局权限
    if claims.role == "super_admin" || claims.role == "admin" {
        return Ok(());
    }

    // 2. Topic Admin 检查白名单
    if claims
        .allowed_systems
        .iter()
        .any(|s| s == "*" || s == target_system_slug)
    {
        return Ok(());
    }

    // 3. 拒绝访问
    Err(AppError::Forbidden(format!(
        "Administrator '{}' is not authorized to manage sub-system '{}'",
        claims.username, target_system_slug
    )))
}

请求访问 system_slug
    ↓
┌────────────────────────────────────┐
│ claims.role == "super_admin"?      │ → ✅ 允许
└────────────────────────────────────┘
    ↓ 否
┌────────────────────────────────────┐
│ claims.role == "admin"?            │ → ✅ 允许
└────────────────────────────────────┘
    ↓ 否
┌────────────────────────────────────┐
│ "*" in allowed_systems?            │ → ✅ 允许
└────────────────────────────────────┘
    ↓ 否
┌────────────────────────────────────┐
│ target_slug in allowed_systems?    │ → ✅ 允许
└────────────────────────────────────┘
    ↓ 否
❌ Forbidden

async fn create_article(
    Extension(claims): Extension<AdminClaims>,
    Path(system_slug): Path<String>,
    Json(payload): Json<CreateArticleDto>,
) -> AppResult<Json<ApiResponse<Article>>> {
    // 1. 检查是否有权限访问此子系统
    check_system_access(&claims, &system_slug)?;

    // 2. 执行业务逻辑
    let article = ArticleService::create(&system_slug, payload).await?;

    Ok(Json(ApiResponse::success(article)))
}

async fn rbac_middleware(
    Extension(claims): Extension<AdminClaims>,
    Path(params): Path<HashMap<String, String>>,
    request: Request,
    next: Next,
) -> Result<Response, AppError> {
    // 从路径参数提取 system_slug
    if let Some(system_slug) = params.get("system_slug") {
        check_system_access(&claims, system_slug)?;
    }

    Ok(next.run(request).await)
}

#[test]
fn test_super_admin_access() {
    let claims = AdminClaims {
        sub: Uuid::new_v4(),
        username: "super_boss".to_string(),
        role: "super_admin".to_string(),
        allowed_systems: vec!["*".to_string()],
        exp: 9999999999,
        iat: 1000000000,
    };

    // Super Admin 可以访问任何系统
    assert!(check_system_access(&claims, "carnival_2026").is_ok());
    assert!(check_system_access(&claims, "vip_mall").is_ok());
    assert!(check_system_access(&claims, "any_system").is_ok());

    // 权限方法测试
    assert!(claims.is_super_admin());
    assert!(claims.can_manage_admins());
    assert!(claims.has_platform_manage_access());
    assert!(claims.can_view_platform_summary());
}

#[test]
fn test_general_admin_access() {
    let claims = AdminClaims {
        sub: Uuid::new_v4(),
        username: "general_op".to_string(),
        role: "admin".to_string(),
        allowed_systems: vec!["*".to_string()],
        exp: 9999999999,
        iat: 1000000000,
    };

    assert!(claims.is_general_admin());
    assert!(!claims.can_manage_admins());  // ← 不能管理管理员
    assert!(claims.has_platform_manage_access());
    assert!(claims.can_view_platform_summary());

    // 可以访问所有系统
    assert!(check_system_access(&claims, "carnival_2026").is_ok());
    assert!(check_system_access(&claims, "vip_mall").is_ok());
}

#[test]
fn test_topic_admin_access() {
    let claims = AdminClaims {
        sub: Uuid::new_v4(),
        username: "carnival_manager".to_string(),
        role: "topic_admin".to_string(),
        allowed_systems: vec!["carnival_2026".to_string()],  // ← 只能访问这一个
        exp: 9999999999,
        iat: 1000000000,
    };

    assert!(claims.is_topic_admin());
    assert!(!claims.can_manage_admins());
    assert!(!claims.can_view_platform_summary());

    // 只能访问分配的系统
    assert!(check_system_access(&claims, "carnival_2026").is_ok());
    assert!(check_system_access(&claims, "vip_mall").is_err());  // ← 拒绝访问
}

async fn register_admin(
    pool: &DbPool,
    username: &str,
    password: &str,
    role: &str,
    allowed_systems: Vec<String>,
) -> AppResult<AdminEntity> {
    // 1. 哈希密码
    let password_hash = hash_password(password)?;

    // 2. 存储到数据库
    let admin = AdminStore::create(
        pool,
        username,
        None,  // email
        &password_hash,
        role,
        serde_json::to_value(allowed_systems).unwrap(),
    ).await?;

    Ok(admin)
}

async fn login(
    pool: &DbPool,
    jwt_service: &JwtService,
    username: &str,
    password: &str,
) -> AppResult<String> {
    // 1. 查询管理员
    let admin = AdminStore::get_by_username(pool, username).await?;

    // 2. 验证密码
    if !verify_password(password, &admin.password_hash)? {
        return Err(AppError::Unauthorized("Invalid credentials".into()));
    }

    // 3. 检查账户状态
    if admin.status != 1 {
        return Err(AppError::Forbidden("Account disabled".into()));
    }

    // 4. 解析 allowed_systems
    let allowed_systems: Vec<String> = serde_json::from_value(admin.allowed_systems)
        .unwrap_or_default();

    // 5. 生成 JWT
    let token = jwt_service.generate_token(
        admin.id,
        &admin.username,
        &admin.role,
        allowed_systems,
    )?;

    Ok(token)
}

// Axum 中间件
async fn auth_middleware(
    jwt_service: Extension<Arc<JwtService>>,
    mut request: Request,
    next: Next,
) -> Result<Response, AppError> {
    // 1. 提取 Authorization Header
    let auth_header = request
        .headers()
        .get(header::AUTHORIZATION)
        .and_then(|h| h.to_str().ok())
        .ok_or_else(|| AppError::Unauthorized("Missing Authorization header".into()))?;

    // 2. 提取 Token
    let token = auth_header
        .strip_prefix("Bearer ")
        .ok_or_else(|| AppError::Unauthorized("Invalid Authorization format".into()))?;

    // 3. 验证 Token
    let claims = jwt_service.verify_token(token)?;

    // 4. 注入到请求扩展
    request.extensions_mut().insert(claims);

    // 5. 继续处理请求
    Ok(next.run(request).await)
}

// Handler 中使用
async fn protected_handler(
    Extension(claims): Extension<AdminClaims>,
) -> impl IntoResponse {
    format!("Hello, {}! Role: {}", claims.username, claims.role)
}

fn validate_password_strength(password: &str) -> AppResult<()> {
    if password.len() < 8 {
        return Err(AppError::Validation("Password must be at least 8 characters".into()));
    }
    if !password.chars().any(|c| c.is_ascii_digit()) {
        return Err(AppError::Validation("Password must contain at least one digit".into()));
    }
    if !password.chars().any(|c| c.is_ascii_lowercase()) {
        return Err(AppError::Validation("Password must contain at least one lowercase letter".into()));
    }
    if !password.chars().any(|c| c.is_ascii_uppercase()) {
        return Err(AppError::Validation("Password must contain at least one uppercase letter".into()));
    }
    Ok(())
}

// 短期 Access Token + 长期 Refresh Token
pub struct TokenPair {
    pub access_token: String,   // 1小时过期
    pub refresh_token: String,  // 7天过期
}

impl JwtService {
    pub fn generate_token_pair(&self, admin: &AdminEntity) -> AppResult<TokenPair> {
        // Access Token：短期，包含完整权限
        let access_token = self.generate_token(
            admin.id,
            &admin.username,
            &admin.role,
            parse_allowed_systems(&admin.allowed_systems),
        )?;

        // Refresh Token：长期，仅包含用户 ID
        let refresh_token = self.generate_refresh_token(admin.id)?;

        Ok(TokenPair { access_token, refresh_token })
    }

    pub fn refresh_access_token(
        &self,
        refresh_token: &str,
        pool: &DbPool,
    ) -> AppResult<String> {
        // 1. 验证 Refresh Token
        let claims = self.verify_token(refresh_token)?;

        // 2. 重新查询管理员信息（防止权限变更）
        let admin = AdminStore::get_by_id(pool, claims.sub).await?;

        // 3. 生成新的 Access Token
        self.generate_token(
            admin.id,
            &admin.username,
            &admin.role,
            parse_allowed_systems(&admin.allowed_systems),
        )
    }
}

use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

pub struct RateLimiter {
    attempts: Arc<Mutex<HashMap<String, Vec<Instant>>>>,
    max_attempts: usize,
    window: Duration,
}

impl RateLimiter {
    pub fn new(max_attempts: usize, window_secs: u64) -> Self {
        Self {
            attempts: Arc::new(Mutex::new(HashMap::new())),
            max_attempts,
            window: Duration::from_secs(window_secs),
        }
    }

    pub fn check_rate_limit(&self, username: &str) -> AppResult<()> {
        let mut attempts = self.attempts.lock().unwrap();
        let now = Instant::now();

        let entry = attempts.entry(username.to_string()).or_insert_with(Vec::new);

        // 清理过期记录
        entry.retain(|&t| now.duration_since(t) < self.window);

        // 检查限流
        if entry.len() >= self.max_attempts {
            return Err(AppError::Forbidden(format!(
                "Too many login attempts. Try again in {} seconds",
                self.window.as_secs()
            )));
        }

        // 记录本次尝试
        entry.push(now);
        Ok(())
    }
}

// 使用示例：
// 5 分钟内最多 5 次登录尝试
let rate_limiter = RateLimiter::new(5, 300);

async fn login_with_rate_limit(
    rate_limiter: &RateLimiter,
    username: &str,
    password: &str,
) -> AppResult<String> {
    // 检查限流
    rate_limiter.check_rate_limit(username)?;

    // 执行登录
    login(pool, jwt_service, username, password).await
}

// Axum 中间件强制 HTTPS
async fn force_https_middleware(
    request: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    if request.uri().scheme_str() != Some("https") {
        return Err(StatusCode::FORBIDDEN);
    }
    Ok(next.run(request).await)
}

服务器存储 Session
  ↓
需要 Redis/Memcached
  ↓
水平扩展困难

Token 自包含所有信息
  ↓
服务器无状态
  ↓
易于水平扩展

// ❌ 不好：所有管理员都是全局权限
if claims.role == "admin" {
    // 允许访问任何系统
}

// ✅ 更好：细粒度权限控制
if claims.role == "super_admin" || claims.role == "admin" {
    // 全局权限
} else if claims.allowed_systems.contains(target_slug) {
    // 限定权限
} else {
    // 拒绝
}

// ❌ 不好：不加盐
hash = SHA256(password)

// ✅ 更好：随机盐
salt = random_bytes(16)
hash = Argon2id(password, salt)

foundry_auth
    ↓ 被使用
┌───────────────────────────────────────┐
│ foundry_engine (middleware)           │
│   - 使用 JwtService 验证令牌          │
│   - 使用 check_system_access 鉴权     │
├───────────────────────────────────────┤
│ foundry_engine (handlers/auth.rs)     │
│   - 使用 hash_password 注册           │
│   - 使用 verify_password 登录         │
│   - 使用 JwtService::generate_token   │
├───────────────────────────────────────┤
│ foundry (app.rs)                      │
│   - 初始化 JwtService                 │
└───────────────────────────────────────┘

#[tokio::test]
async fn test_full_auth_flow() {
    let pool = setup_test_db().await;
    let jwt = JwtService::new("test_secret", 24);

    // 1. 注册
    let password_hash = hash_password("admin123").unwrap();
    let admin = AdminStore::create(
        &pool,
        "testuser",
        None,
        &password_hash,
        "admin",
        json!([]),
    ).await.unwrap();

    // 2. 登录
    assert!(verify_password("admin123", &admin.password_hash).unwrap());

    // 3. 生成令牌
    let token = jwt.generate_token(
        admin.id,
        &admin.username,
        &admin.role,
        vec![],
    ).unwrap();

    // 4. 验证令牌
    let claims = jwt.verify_token(&token).unwrap();
    assert_eq!(claims.sub, admin.id);
}

use foundry_auth::{hash_password, verify_password, JwtService, check_system_access};

// 密码哈希
let hash = hash_password("password123")?;
let is_valid = verify_password("password123", &hash)?;

// JWT 服务
let jwt = JwtService::new("your-secret-key", 24);
let token = jwt.generate_token(admin_id, "admin", "super_admin", vec![])?;
let claims = jwt.verify_token(&token)?;

// 权限检查
check_system_access(&claims, "blog")?;