yggdrasil/api/

auth.rs

//! 认证相关的 Leptos server function 与辅助函数。
//!
//! 提供注册、登录、登出、获取当前用户等接口，
//! 通过 HttpOnly Cookie 维护会话，首个注册用户自动成为 admin。
//! 也可通过 `ADMIN_*` 环境变量在启动时创建/同步初始管理员（env 为凭据源，
//! 每次启动覆盖密码并确保 admin 角色），免去首次注册步骤——见 `sync_admin_from_env`。
//! 所有 server function 均在 `#[server(Name, "/api")]` 下注册，供客户端与服务端调用。
//! 仅在 `feature = "server"` 启用的服务端构建中执行数据库操作与 Cookie 写入。

#![allow(clippy::unused_unit, deprecated)]

use crate::api::error::ApiError;
#[cfg(feature = "server")]
use http::header::{HeaderValue, SET_COOKIE};
use leptos::prelude::*;

#[cfg(feature = "server")]
use crate::api::error::AppError;
#[cfg(feature = "server")]
use crate::auth::session::get_session_from_ctx;
#[cfg(feature = "server")]
use crate::auth::{password, session};
#[cfg(feature = "server")]
use crate::db::pool::get_conn;
use crate::models::user::PublicUser;
#[cfg(feature = "server")]
use crate::models::user::{SessionUser, UserRole};

#[cfg(feature = "server")]
fn validate_username(username: &str) -> Result<(), String> {
    let len = username.chars().count();
    if !(3..=50).contains(&len) {
        return Err("用户名长度必须在 3-50 字符之间".to_string());
    }
    if !username.chars().all(|c| c.is_alphanumeric() || c == '_') {
        return Err("用户名只能包含字母、数字和下划线".to_string());
    }
    Ok(())
}

#[cfg(feature = "server")]
pub(crate) fn validate_email(email: &str) -> Result<(), String> {
    if !crate::utils::server::EMAIL_REGEX.is_match(email) {
        return Err("邮箱格式不正确".to_string());
    }
    Ok(())
}

#[cfg(feature = "server")]
/// 密码长度上限（字节）：纵深防御，避免 Argon2 对超大输入做无意义的线性哈希扫描
/// （Argon2 本身的 memory_cost 才是主要开销，这里只是零成本兜底）。
const MAX_PASSWORD_BYTES: usize = 256;

#[cfg(feature = "server")]
pub(crate) fn validate_password(password: &str) -> Result<(), String> {
    if password.len() < 8 {
        return Err("密码长度至少 8 位".to_string());
    }
    if password.len() > MAX_PASSWORD_BYTES {
        return Err("密码长度不能超过 256 位".to_string());
    }
    Ok(())
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
/// 认证接口统一响应结构。
pub struct AuthResponse {
    /// 操作是否成功。
    pub success: bool,
    /// 提示信息。
    pub message: String,
    /// 登录成功后的会话 token（已废弃，实际通过 Cookie 传递）。
    pub token: Option<String>,
}

/// 用户注册。
///
/// 校验用户名、邮箱、密码；仅在 `users` 表为空（站点未初始化）时允许注册，
/// 首个用户成为 admin。之后一律返回 "Registration is closed"，
/// 不随管理员角色变化（如被降级为 blocked）重新开放。
/// Leptos server function，注册在 `/api` 路径下。
#[server(Register, endpoint = "register", input = leptos::server_fn::codec::Json)]
pub async fn register(
    username: String,
    email: String,
    password: String,
) -> Result<AuthResponse, ApiError> {
    // 服务端构建时先进行严格限流检查。
    #[cfg(feature = "server")]
    {
        if let Some(headers) = crate::request_ctx::request_headers() {
            let ip = crate::api::rate_limit::get_client_ip(&headers).await;
            if let Err(msg) = crate::api::rate_limit::check_strict_limit(&ip) {
                return Ok(AuthResponse {
                    success: false,
                    message: msg,
                    token: None,
                });
            }
        }
    }

    if let Err(e) = validate_username(&username) {
        return Ok(AuthResponse {
            success: false,
            message: e,
            token: None,
        });
    }
    if let Err(e) = validate_email(&email) {
        return Ok(AuthResponse {
            success: false,
            message: e,
            token: None,
        });
    }
    if let Err(e) = validate_password(&password) {
        return Ok(AuthResponse {
            success: false,
            message: e,
            token: None,
        });
    }

    let client = get_conn().await.map_err(AppError::db_conn)?;

    // 先判注册是否已关闭再算哈希：站点初始化后每个公开注册 POST 都会走到这里，
    // 若无条件执行 Argon2（每次约 19 MiB 内存）就会白白占满内存与阻塞线程池。
    // 这里只是快速拒绝，并发首注册的竞争仍由下方 INSERT 的 NOT EXISTS 兜底。
    let has_users: bool = client
        .query_one("SELECT EXISTS (SELECT 1 FROM users)", &[])
        .await
        .map_err(AppError::query)?
        .get(0);
    if has_users {
        return Ok(registration_closed());
    }

    // Argon2 是 memory-hard 计算，必须在 spawn_blocking 中执行，避免阻塞 Tokio worker。
    let pw_for_hash = password.clone();
    let password_hash = tokio::task::spawn_blocking(move || password::hash_password(&pw_for_hash))
        .await
        .map_err(|_| AppError::Internal("密码处理任务失败"))?
        .map_err(|_| AppError::Internal("密码处理失败"))?;

    // 初始化完成的判据是「已有任何用户」，而非「存在 admin」：admin 被降级/封禁后
    // 部分唯一索引 `idx_one_admin` 不再生效，若只靠它判定，注册会重新开放并产生新 admin。
    // 并发首注册时两者都可能通过 NOT EXISTS，`idx_one_admin` 让后到者 DO NOTHING。
    let result = client
        .query_opt(
            "INSERT INTO users (username, email, password_hash, role)
             SELECT $1, $2, $3, 'admin'
             WHERE NOT EXISTS (SELECT 1 FROM users)
             ON CONFLICT DO NOTHING
             RETURNING id",
            &[&username, &email, &password_hash],
        )
        .await
        .map_err(AppError::query)?;

    // 插入失败只可能因为已有用户（含并发首注册的胜者），统一视为注册关闭。
    Ok(if result.is_some() {
        AuthResponse {
            success: true,
            message: "注册成功".to_string(),
            token: None,
        }
    } else {
        registration_closed()
    })
}

#[cfg(feature = "server")]
fn registration_closed() -> AuthResponse {
    AuthResponse {
        success: false,
        message: "Registration is closed".to_string(),
        token: None,
    }
}

/// 用户登录。
///
/// 验证用户名/邮箱与密码，生成会话并写入 HttpOnly Cookie；
/// 同一用户活跃会话数超过 `MAX_SESSIONS_PER_USER` 时删除最早会话。
/// Leptos server function，注册在 `/api` 路径下。
#[server(Login, endpoint = "login", input = leptos::server_fn::codec::Json)]
pub async fn login(username: String, password: String) -> Result<AuthResponse, ApiError> {
    // 服务端构建时先进行严格限流检查。
    #[cfg(feature = "server")]
    {
        if let Some(headers) = crate::request_ctx::request_headers() {
            let ip = crate::api::rate_limit::get_client_ip(&headers).await;
            if let Err(msg) = crate::api::rate_limit::check_strict_limit(&ip) {
                return Ok(AuthResponse {
                    success: false,
                    message: msg,
                    token: None,
                });
            }
        }
    }

    let mut client = get_conn().await.map_err(AppError::db_conn)?;

    let row = match client
        .query_opt(
            "SELECT id, username, email, password_hash, role, created_at FROM users WHERE username = $1 OR email = $1",
            &[&username],
        )
        .await
    {
        Ok(Some(row)) => row,
        Ok(None) => {
            // 用户不存在时也执行一次 Argon2 verify，抹平「用户不存在」与
            // 「密码错误」的响应时序差，防止通过响应时间枚举账号（L2）。
            // 用固定合法哈希做 verify（必然失败），耗时与真实校验一致。
            const DUMMY_HASH: &str =
                "$argon2id$v=19$m=19456,t=2,p=1$j3rNaAXzdExYaL94WBWtfg$n1S75LUQKaYJwaRl5bkFF/f/N1tLfRYR/7TuQxKP94c";
            let dummy_pw = password.clone();
            let _ = tokio::task::spawn_blocking(move || {
                crate::auth::password::verify_password(&dummy_pw, DUMMY_HASH)
            })
            .await;
            return Ok(AuthResponse {
                success: false,
                message: "Invalid credentials".to_string(),
                token: None,
            });
        }
        Err(e) => {
            return Err(AppError::query(e).into());
        }
    };

    let password_hash: String = row.get("password_hash");
    // Argon2 校验同样在 spawn_blocking 中执行。
    let pw_for_verify = password.clone();
    let hash_for_verify = password_hash.clone();
    let valid = tokio::task::spawn_blocking(move || {
        password::verify_password(&pw_for_verify, &hash_for_verify)
    })
    .await
    .map_err(|_| AppError::Internal("密码处理任务失败"))?
    .map_err(|_| AppError::Internal("密码处理失败"))?;

    if !valid {
        return Ok(AuthResponse {
            success: false,
            message: "Invalid credentials".to_string(),
            token: None,
        });
    }

    // blocked / 未知角色即使密码正确也不能建立会话；统一返回通用凭据错误，
    // 避免泄露账号当前状态。
    let role_str: String = row.get("role");
    if !matches!(UserRole::from_str(&role_str), Some(UserRole::Admin)) {
        return Ok(AuthResponse {
            success: false,
            message: "Invalid credentials".to_string(),
            token: None,
        });
    }

    let user_id: i32 = row.get("id");
    let token = session::generate_token();
    let token_hash = session::hash_token(&token);
    let expires_at = session::default_expiry();

    let max_sessions = crate::api::settings::runtime_security_settings()
        .await
        .max_sessions_per_user
        .max(1) as i64;

    // 用事务 + 对 users 行加 FOR UPDATE 锁，串行化同一用户的并发登录，
    // 避免 COUNT→DELETE→INSERT 之间的竞态导致超出上限（M1）。
    let tx = client.transaction().await.map_err(AppError::query)?;
    // 锁住该用户行，并发登录在此排队；同时复核凭据：校验密码到加锁之间若有
    // 改密/降级提交，已验证的旧哈希不得换取新世代会话。
    let still_valid = tx
        .query_opt(
            "SELECT 1 FROM users WHERE id = $1 AND password_hash = $2 AND role = 'admin' FOR UPDATE",
            &[&user_id, &password_hash],
        )
        .await
        .map_err(AppError::query)?
        .is_some();
    if !still_valid {
        return Ok(AuthResponse {
            success: false,
            message: "Invalid credentials".to_string(),
            token: None,
        });
    }

    // 只保留最新的 max_sessions - 1 个有效会话，为本次登录腾出一个名额。
    // 一次删掉所有超额会话，上限下调后下次登录即收敛到新上限，而不是每次只淘汰一条。
    tx.execute(
        "DELETE FROM sessions WHERE id IN (
            SELECT id FROM sessions
            WHERE user_id = $1 AND expires_at > NOW()
            ORDER BY created_at DESC, id DESC
            OFFSET $2
        )",
        &[&user_id, &(max_sessions - 1)],
    )
    .await
    .map_err(AppError::query)?;

    // 签发时快照当前世代号（users 行已被 FOR UPDATE 锁定，读到的即提交时的值）。
    tx.execute(
        "INSERT INTO sessions (user_id, token_hash, user_agent, expires_at, generation)
         SELECT id, $2, $3, $4, session_generation FROM users WHERE id = $1",
        &[&user_id, &token_hash, &None::<String>, &expires_at],
    )
    .await
    .map_err(AppError::query)?;

    tx.commit().await.map_err(AppError::query)?;

    let cookie = session::session_cookie(
        &token,
        session::SESSION_MAX_AGE_SECS,
        crate::api::settings::runtime_security_settings()
            .await
            .cookie_secure,
    );
    // 通过响应上下文设置 HttpOnly Cookie 响应头。
    if let Ok(value) = HeaderValue::try_from(cookie.as_str()) {
        crate::request_ctx::append_response_header(SET_COOKIE, value);
    }

    Ok(AuthResponse {
        success: true,
        message: "登录成功".to_string(),
        token: None,
    })
}

/// 用户登出。
///
/// 清空客户端 session Cookie，并删除数据库中对应会话记录。
/// Leptos server function，注册在 `/api` 路径下。
#[server(Logout, endpoint = "logout", input = leptos::server_fn::codec::Json)]
pub async fn logout() -> Result<AuthResponse, ApiError> {
    let token = get_session_from_ctx();

    let client = get_conn().await.map_err(AppError::db_conn)?;

    // 设置过期时间为 0 的 Cookie，通知浏览器清除会话。
    let cookie = session::session_cookie(
        "",
        0,
        crate::api::settings::runtime_security_settings()
            .await
            .cookie_secure,
    );
    if let Ok(value) = HeaderValue::try_from(cookie.as_str()) {
        crate::request_ctx::append_response_header(SET_COOKIE, value);
    }

    if let Some(t) = token {
        let token_hash = session::hash_token(&t);
        crate::cache::invalidate_session_user(&token_hash).await;
        client
            .execute("DELETE FROM sessions WHERE token_hash = $1", &[&token_hash])
            .await
            .map_err(AppError::query)?;
    }

    Ok(AuthResponse {
        success: true,
        message: "登出成功".to_string(),
        token: None,
    })
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
/// 当前用户查询响应。
pub struct CurrentUserResponse {
    /// 当前已登录用户的公开信息；未登录时为 `None`。
    pub user: Option<PublicUser>,
}

#[cfg(feature = "server")]
/// 根据会话 token 查询对应用户（不含密码哈希，供会话缓存使用）。
///
/// 优先命中内存缓存，避免每次请求都执行完整用户查询；未命中时回查数据库并回填缓存。
/// 缓存命中与未命中两条路径都校验 `sessions.expires_at`、用户角色，以及
/// `sessions.generation`（签发快照）与 `users.session_generation`（当前值）是否一致，
/// 确保过期、撤销、改密或被封禁的会话不会继续有效。
pub async fn get_user_by_token(token: &str) -> Result<Option<SessionUser>, ApiError> {
    let token_hash = session::hash_token(token);

    if let Some(cached) = crate::cache::get_session_user(&token_hash).await {
        // 缓存命中后同时校验 session 是否存在/未过期、角色与世代号。
        let session_state: Option<(i32, String)> = get_conn()
            .await
            .map_err(AppError::db_conn)?
            .query_opt(
                "SELECT u.session_generation, u.role
                 FROM sessions s
                 JOIN users u ON s.user_id = u.id
                 WHERE s.token_hash = $1 AND s.expires_at > NOW()
                   AND s.generation = u.session_generation",
                &[&token_hash],
            )
            .await
            .map_err(AppError::query)?
            .map(|r| (r.get(0), r.get(1)));

        match session_state {
            Some((generation, role))
                if generation == cached.session_generation
                    && role == "admin"
                    && matches!(cached.role, UserRole::Admin) =>
            {
                return Ok(Some(cached));
            }
            _ => {
                // session 不存在/已过期、世代不匹配或角色已禁用：逐出缓存并视为未登录。
                crate::cache::invalidate_session_user(&token_hash).await;
                return Ok(None);
            }
        }
    }

    let client = get_conn().await.map_err(AppError::db_conn)?;

    let row = client
        .query_opt(
            "SELECT u.id, u.username, u.email, u.display_name, u.avatar_url, u.role, u.created_at, u.session_generation
             FROM sessions s
             JOIN users u ON s.user_id = u.id
             WHERE s.token_hash = $1 AND s.expires_at > NOW()
               AND s.generation = u.session_generation",
            &[&token_hash],
        )
        .await
        .map_err(AppError::query)?;

    let user = match row {
        Some(row) => {
            let role_str: String = row.get("role");
            let role = match UserRole::from_str(&role_str) {
                Some(UserRole::Admin) => UserRole::Admin,
                _ => return Ok(None),
            };
            Some(SessionUser {
                id: row.get("id"),
                username: row.get("username"),
                email: row.get("email"),
                display_name: row.get("display_name"),
                avatar_url: row.get("avatar_url"),
                role,
                created_at: row.get("created_at"),
                session_generation: row.get("session_generation"),
            })
        }
        None => None,
    };

    if let Some(ref u) = user {
        crate::cache::set_session_user(&token_hash, u.clone()).await;
    }

    Ok(user)
}

/// 获取当前登录用户的公开信息。
///
/// Leptos server function，注册在 `/api` 路径下。
#[server(GetCurrentUser, endpoint = "get_current_user", input = leptos::server_fn::codec::Json)]
pub async fn get_current_user() -> Result<CurrentUserResponse, ApiError> {
    let token = match get_session_from_ctx() {
        Some(t) => t,
        None => return Ok(CurrentUserResponse { user: None }),
    };

    let user = get_user_by_token(&token).await?.map(PublicUser::from);

    Ok(CurrentUserResponse { user })
}

#[cfg(feature = "server")]
/// 获取当前登录用户并要求其为 admin，否则返回 401/403。
///
/// 供其它服务端接口内部调用。
pub async fn get_current_admin_user() -> Result<SessionUser, ApiError> {
    let token = get_session_from_ctx().ok_or_else(|| ApiError::Unauthorized("未登录".into()))?;

    let session_user = get_user_by_token(&token)
        .await?
        .ok_or_else(|| ApiError::Unauthorized("会话已过期".into()))?;

    if session_user.role != UserRole::Admin {
        return Err(ApiError::Forbidden("权限不足".into()));
    }

    Ok(session_user)
}

/// 初始管理员配置（来自 `ADMIN_*` 环境变量）。
///
/// 不实现 `Debug`，避免日志意外泄露密码。
#[cfg(feature = "server")]
struct AdminEnvConfig {
    username: String,
    email: String,
    password: String,
}

/// 从环境变量读取初始管理员配置（`ADMIN_USERNAME` / `ADMIN_EMAIL` / `ADMIN_PASSWORD`）。
///
/// 三个变量任一缺失或为空 → 返回 `None`（特性关闭）。
/// 用户名/邮箱会 trim；密码原样保留（允许含空格）。
#[cfg(feature = "server")]
fn parse_admin_env() -> Option<AdminEnvConfig> {
    let username = std::env::var("ADMIN_USERNAME").ok()?;
    let username = username.trim().to_string();
    if username.is_empty() {
        return None;
    }
    let email = std::env::var("ADMIN_EMAIL").ok()?;
    let email = email.trim().to_string();
    if email.is_empty() {
        return None;
    }
    let password = std::env::var("ADMIN_PASSWORD").ok()?;
    if password.is_empty() {
        return None;
    }
    Some(AdminEnvConfig {
        username,
        email,
        password,
    })
}

/// `ADMIN_*` 初始管理员环境变量是否全部就位（即启动同步特性是否激活）。
///
/// 激活时每次启动都会用 env 覆盖邮箱与密码——个人信息页据此显示提示横幅。
#[cfg(feature = "server")]
pub(crate) fn admin_env_active() -> bool {
    parse_admin_env().is_some()
}

/// 启动时按 `ADMIN_*` 环境变量同步初始管理员（env 是超级管理员的凭据源）。
///
/// 语义（与 `BACKUP_*` 播种「仅首次生效」不同：这里**每次启动**都生效）：
/// 1. 三个变量任一缺失/为空 → 跳过（特性关闭，向后兼容）。
/// 2. 变量值非法（不过 `validate_*` 校验）→ warn + 跳过，不阻断启动。
/// 3. `ADMIN_USERNAME` 已存在 → 用 `ADMIN_PASSWORD` 覆盖其密码哈希
///    （密码一致时跳过重哈希，避免每次启动改写行；覆盖时 bump
///    `session_generation`，旧会话全部失效需重新登录）；
///    确保 role='admin'（恢复被降级/封禁的用户，触发 018 迁移的角色触发器）；
///    邮箱同步为 `ADMIN_EMAIL`（被其他用户占用时仅告警跳过邮箱）。
/// 4. `ADMIN_USERNAME` 不存在 → 尝试创建为 admin。库中已存在其他 admin 时
///    创建失败（`idx_one_admin` 部分唯一索引保证全库仅一个 admin），warn 提示。
///
/// 失败只告警不阻断启动（与 BACKUP_* 播种一致）。
#[cfg(feature = "server")]
pub(crate) async fn sync_admin_from_env(client: &tokio_postgres::Client) -> Result<(), AppError> {
    let Some(cfg) = parse_admin_env() else {
        return Ok(());
    };
    if let Err(e) = validate_username(&cfg.username) {
        tracing::warn!(
            "ADMIN_USERNAME={:?} 非法，跳过初始管理员同步: {e}",
            cfg.username
        );
        return Ok(());
    }
    if let Err(e) = validate_email(&cfg.email) {
        tracing::warn!("ADMIN_EMAIL={:?} 非法，跳过初始管理员同步: {e}", cfg.email);
        return Ok(());
    }
    if let Err(e) = validate_password(&cfg.password) {
        tracing::warn!("ADMIN_PASSWORD 不合法（{e}），跳过初始管理员同步");
        return Ok(());
    }

    // Argon2 是 memory-hard 计算，必须在 spawn_blocking 中执行（与注册路径一致）。
    let pw = cfg.password.clone();
    let password_hash = tokio::task::spawn_blocking(move || password::hash_password(&pw))
        .await
        .map_err(|_| AppError::Internal("初始管理员密码哈希任务失败"))?
        .map_err(|_| AppError::Internal("初始管理员密码哈希失败"))?;

    let row = client
        .query_opt(
            "SELECT id, email, role, password_hash FROM users WHERE username = $1",
            &[&cfg.username],
        )
        .await
        .map_err(AppError::query)?;

    let Some(row) = row else {
        // 用户名不存在：尝试创建为 admin（仅当库中尚无 admin 时成功）。
        let created = client
            .query_opt(
                "INSERT INTO users (username, email, password_hash, role)
                 VALUES ($1, $2, $3, 'admin')
                 ON CONFLICT DO NOTHING
                 RETURNING id",
                &[&cfg.username, &cfg.email, &password_hash],
            )
            .await
            .map_err(AppError::query)?;
        if created.is_some() {
            tracing::info!(
                "初始管理员已从环境变量创建: username={}（登录成功后可从 .env 移除 ADMIN_* 变量）",
                cfg.username
            );
        } else {
            tracing::warn!(
                "无法创建初始管理员 username={}（用户名/邮箱已被占用，或库中已存在其他 admin——全库仅允许一个 admin）。\
                 可将 ADMIN_USERNAME 改为现有 admin 的用户名以同步其凭据",
                cfg.username
            );
        }
        return Ok(());
    };

    // 用户名已存在：env 覆盖密码、确保 admin 角色、同步邮箱。
    let user_id: i32 = row.get("id");
    let stored_hash: String = row.get("password_hash");
    let stored_email: String = row.get("email");
    let role: String = row.get("role");

    // 密码与 env 一致时跳过重哈希（一次 Argon2 verify，代价可接受）。
    let pw_for_verify = cfg.password.clone();
    let same_password = tokio::task::spawn_blocking(move || {
        password::verify_password(&pw_for_verify, &stored_hash)
    })
    .await
    .map_err(|_| AppError::Internal("初始管理员密码校验任务失败"))?
    .unwrap_or(false);
    if !same_password {
        // 凭据变更 → bump session_generation；sessions.generation 快照不再匹配，
        // 旧会话（含缓存命中路径）立即失效，需用新密码重新登录。
        client
            .execute(
                "UPDATE users SET password_hash = $1, session_generation = session_generation + 1
                 WHERE id = $2",
                &[&password_hash, &user_id],
            )
            .await
            .map_err(AppError::query)?;
        tracing::info!("初始管理员密码已从环境变量覆盖: username={}", cfg.username);
    }

    if role != "admin" {
        // 018 迁移的角色变更触发器会在此 bump session_generation（降级期间的会话本已失效）。
        client
            .execute("UPDATE users SET role = 'admin' WHERE id = $1", &[&user_id])
            .await
            .map_err(AppError::query)?;
        tracing::info!("初始管理员角色已恢复为 admin: username={}", cfg.username);
    }

    if stored_email != cfg.email {
        let email_taken: bool = client
            .query_one(
                "SELECT EXISTS (SELECT 1 FROM users WHERE email = $1 AND id <> $2)",
                &[&cfg.email, &user_id],
            )
            .await
            .map_err(AppError::query)?
            .get(0);
        if email_taken {
            tracing::warn!(
                "ADMIN_EMAIL={:?} 已被其他用户占用，跳过邮箱同步（密码/角色不受影响）",
                cfg.email
            );
        } else {
            client
                .execute(
                    "UPDATE users SET email = $1 WHERE id = $2",
                    &[&cfg.email, &user_id],
                )
                .await
                .map_err(AppError::query)?;
        }
    }

    Ok(())
}

#[cfg(feature = "server")]
/// 原生 Axum 路由的 admin 前置校验：cookie → session → role。
///
/// 这些路由不经过 server fn 上下文，只能从请求头取 session。失败返回
/// `(状态码, 消息)`：无会话 cookie 为 401「未登录」，会话无效或查询失败为
/// 401「会话已过期」，非 admin 为 403「权限不足」。响应体格式由调用方决定。
pub(crate) async fn require_admin_from_headers(
    headers: &http::HeaderMap,
) -> Result<SessionUser, (http::StatusCode, &'static str)> {
    let cookie_header = headers
        .get(http::header::COOKIE)
        .and_then(|h| h.to_str().ok())
        .unwrap_or("");
    let token = session::parse_session_token(cookie_header)
        .ok_or((http::StatusCode::UNAUTHORIZED, "未登录"))?;
    let user = match get_user_by_token(token).await {
        Ok(Some(user)) => user,
        _ => return Err((http::StatusCode::UNAUTHORIZED, "会话已过期")),
    };
    if user.role != UserRole::Admin {
        return Err((http::StatusCode::FORBIDDEN, "权限不足"));
    }
    Ok(user)
}

#[cfg(all(test, feature = "server"))]
mod tests {
    use super::*;

    #[test]
    fn validate_username_valid() {
        assert!(validate_username("admin").is_ok());
        assert!(validate_username("user_123").is_ok());
        assert!(validate_username("abc").is_ok());
    }

    #[test]
    fn validate_username_too_short() {
        assert!(validate_username("ab").is_err());
    }

    #[test]
    fn validate_username_too_long() {
        assert!(validate_username(&"a".repeat(51)).is_err());
    }

    #[test]
    fn validate_username_max_length() {
        assert!(validate_username(&"a".repeat(50)).is_ok());
    }

    #[test]
    fn validate_username_special_chars() {
        assert!(validate_username("user name").is_err());
        assert!(validate_username("user@name").is_err());
        assert!(validate_username("user-name").is_err());
    }

    #[test]
    fn validate_username_unicode() {
        assert!(validate_username("用户名").is_ok());
    }

    #[test]
    fn validate_username_counts_chinese_chars_not_bytes() {
        // 20 个汉字 = 60 字节，按字符计在 50 以内应通过。
        assert!(validate_username(&"汉".repeat(20)).is_ok());
        assert!(validate_username(&"汉".repeat(50)).is_ok());
        assert!(validate_username(&"汉".repeat(51)).is_err());
        // 2 个汉字 = 6 字节，按字符计不足 3 应拒绝。
        assert!(validate_username("汉字").is_err());
    }

    #[test]
    fn validate_email_valid() {
        assert!(validate_email("user@example.com").is_ok());
        assert!(validate_email("a.b+c@domain.co").is_ok());
    }

    #[test]
    fn validate_email_invalid() {
        assert!(validate_email("notanemail").is_err());
        assert!(validate_email("@domain.com").is_err());
        assert!(validate_email("user@").is_err());
        assert!(validate_email("user@.com").is_err());
        assert!(validate_email("").is_err());
    }

    #[test]
    fn validate_password_valid() {
        assert!(validate_password("12345678").is_ok());
        assert!(validate_password("a very long password with spaces").is_ok());
    }

    #[test]
    fn validate_password_too_short() {
        assert!(validate_password("1234567").is_err());
    }

    #[test]
    fn validate_password_exactly_8() {
        assert!(validate_password("12345678").is_ok());
    }

    #[test]
    fn validate_password_empty() {
        assert!(validate_password("").is_err());
    }

    #[test]
    fn validate_password_too_long() {
        assert!(validate_password(&"a".repeat(257)).is_err());
        assert!(validate_password(&"a".repeat(256)).is_ok());
    }

    /// 在给定环境变量集下运行闭包，结束后恢复原值（env 是进程全局状态，需 serial 隔离）。
    fn with_env(vars: &[(&str, Option<&str>)], f: impl FnOnce()) {
        let saved: Vec<(String, Option<String>)> = vars
            .iter()
            .map(|(k, _)| (k.to_string(), std::env::var(k).ok()))
            .collect();
        for (k, v) in vars {
            match v {
                Some(v) => std::env::set_var(k, v),
                None => std::env::remove_var(k),
            }
        }
        f();
        for (k, v) in saved {
            match v {
                Some(v) => std::env::set_var(k, v),
                None => std::env::remove_var(k),
            }
        }
    }

    #[test]
    #[serial_test::serial]
    fn parse_admin_env_none_when_all_unset() {
        with_env(
            &[
                ("ADMIN_USERNAME", None),
                ("ADMIN_EMAIL", None),
                ("ADMIN_PASSWORD", None),
            ],
            || assert!(parse_admin_env().is_none()),
        );
    }

    #[test]
    #[serial_test::serial]
    fn parse_admin_env_none_when_any_missing() {
        // 只缺 ADMIN_PASSWORD。
        with_env(
            &[
                ("ADMIN_USERNAME", Some("admin")),
                ("ADMIN_EMAIL", Some("admin@example.com")),
                ("ADMIN_PASSWORD", None),
            ],
            || assert!(parse_admin_env().is_none()),
        );
        // 只缺 ADMIN_EMAIL。
        with_env(
            &[
                ("ADMIN_USERNAME", Some("admin")),
                ("ADMIN_EMAIL", None),
                ("ADMIN_PASSWORD", Some("strongpass123")),
            ],
            || assert!(parse_admin_env().is_none()),
        );
        // 只缺 ADMIN_USERNAME。
        with_env(
            &[
                ("ADMIN_USERNAME", None),
                ("ADMIN_EMAIL", Some("admin@example.com")),
                ("ADMIN_PASSWORD", Some("strongpass123")),
            ],
            || assert!(parse_admin_env().is_none()),
        );
    }

    #[test]
    #[serial_test::serial]
    fn parse_admin_env_none_on_empty_values() {
        with_env(
            &[
                ("ADMIN_USERNAME", Some("admin")),
                ("ADMIN_EMAIL", Some("admin@example.com")),
                ("ADMIN_PASSWORD", Some("")),
            ],
            || assert!(parse_admin_env().is_none()),
        );
        with_env(
            &[
                ("ADMIN_USERNAME", Some("   ")),
                ("ADMIN_EMAIL", Some("admin@example.com")),
                ("ADMIN_PASSWORD", Some("strongpass123")),
            ],
            || assert!(parse_admin_env().is_none()),
        );
    }

    #[test]
    #[serial_test::serial]
    fn parse_admin_env_some_when_all_set() {
        with_env(
            &[
                ("ADMIN_USERNAME", Some("  admin  ")),
                ("ADMIN_EMAIL", Some(" admin@example.com ")),
                ("ADMIN_PASSWORD", Some("  strong pass 123  ")),
            ],
            || {
                let cfg = parse_admin_env().expect("三个变量齐全应返回 Some");
                // 用户名/邮箱 trim，密码原样保留。
                assert_eq!(cfg.username, "admin");
                assert_eq!(cfg.email, "admin@example.com");
                assert_eq!(cfg.password, "  strong pass 123  ");
            },
        );
    }

    #[tokio::test]
    async fn require_admin_from_headers_rejects_missing_session_cookie() {
        let mut headers = http::HeaderMap::new();
        assert_eq!(
            require_admin_from_headers(&headers).await.unwrap_err(),
            (http::StatusCode::UNAUTHORIZED, "未登录")
        );

        headers.insert(http::header::COOKIE, HeaderValue::from_static("theme=dark"));
        assert_eq!(
            require_admin_from_headers(&headers).await.unwrap_err(),
            (http::StatusCode::UNAUTHORIZED, "未登录")
        );
    }
}