Skip to content

World's first open-source enterprise world model.

14.7 KB
Raw Blame
//! 认证:argon2 密码哈希 + JWT(HttpOnly Cookie,同时接受 Bearer)。
//! Cookie 本身是会话 cookie,过期由 JWT 的 exp 控制(7 天)。

use argon2::password_hash::rand_core::OsRng;
use argon2::password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
use argon2::Argon2;
use axum::extract::FromRequestParts;
use axum::http::request::Parts;
use axum_extra::extract::cookie::{Cookie, CookieJar, SameSite};
use chrono::Utc;
use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
use serde::{Deserialize, Serialize};
use utopia_core::models::User;
use utopia_core::AppError;
use uuid::Uuid;

use crate::error::ApiErr;
use crate::state::AppState;

pub const COOKIE_NAME: &str = "utopia_token";
const TOKEN_TTL_DAYS: i64 = 7;

#[derive(Debug, Serialize, Deserialize)]
struct Claims {
    sub: Uuid,
    exp: i64,
}

pub fn hash_password(password: &str) -> Result<String, AppError> {
    let salt = SaltString::generate(&mut OsRng);
    Argon2::default()
        .hash_password(password.as_bytes(), &salt)
        .map(|h| h.to_string())
        .map_err(|e| AppError::Other(anyhow::anyhow!("Password hashing failed: {e}")))
}

pub fn verify_password(password: &str, hash: &str) -> bool {
    // 单点登录开的账号存的是 `!`,解析不了。照样跑一遍 argon2(对着 dummy),
    // 否则响应快得多,能据此分辨出哪些账号只走 SSO
    let Ok(parsed) = PasswordHash::new(hash) else {
        let dummy = PasswordHash::new(dummy_password_hash()).expect("the dummy parses");
        let _ = Argon2::default().verify_password(password.as_bytes(), &dummy);
        return false;
    };
    Argon2::default()
        .verify_password(password.as_bytes(), &parsed)
        .is_ok()
}

/// 「邮箱不存在」分支用的常量时间伙伴:一个用真实参数算出来的 argon2 哈希,明文是随机
/// 字节、算完即弃。要点只有一个——它必须能被 `PasswordHash::new` 解析并带着与
/// `hash_password` 相同的参数,这样那条分支和「邮箱存在、密码错」走的是同一段计算。
/// 它不匹配任何口令;结果本来就被丢弃。从 `hash_password` 派生而不是硬编码,是为了
/// 参数永不漂移:`Argon2::default()` 一变,这里跟着变,没有测试会静静过时。
pub fn dummy_password_hash() -> &'static str {
    static HASH: std::sync::OnceLock<String> = std::sync::OnceLock::new();
    HASH.get_or_init(|| {
        use argon2::password_hash::rand_core::RngCore;
        let mut bytes = [0u8; 32];
        OsRng.fill_bytes(&mut bytes);
        let plaintext: String = bytes.iter().map(|b| format!("{b:02x}")).collect();
        hash_password(&plaintext).expect("hashing random bytes cannot fail")
    })
}

pub fn issue_token(state: &AppState, user_id: Uuid) -> Result<String, AppError> {
    issue_session(state, user_id).map(|(token, _)| token)
}

/// 签发会话并给出它的过期时刻:要把过期时间告诉调用方的地方用这个,
/// 免得在别处再按 TTL 算一遍、和 JWT 里的 `exp` 对不上
pub fn issue_session(
    state: &AppState,
    user_id: Uuid,
) -> Result<(String, chrono::DateTime<Utc>), AppError> {
    let expires_at = Utc::now() + chrono::Duration::days(TOKEN_TTL_DAYS);
    let claims = Claims {
        sub: user_id,
        exp: expires_at.timestamp(),
    };
    let token = encode(
        &Header::default(),
        &claims,
        &EncodingKey::from_secret(state.jwt_secret.as_bytes()),
    )
    .map_err(|e| AppError::Other(anyhow::anyhow!("Token issuance failed: {e}")))?;
    Ok((token, expires_at))
}

/// 外层是否在跑 TLS。反代都会带 `X-Forwarded-Proto`;没有这个头(本地直连、
/// 开发环境)就当明文,Secure 不打,登录照常工作。
///
/// 不需要「信任的代理」名单:伪造这个头只会让攻击者自己的 cookie 变成 Secure,
/// 更严格而不是更宽松,没有攻击价值。`UTOPIA_COOKIE_SECURE=true` 可强制打开,
/// 给那些不发这个头的代理兜底。
pub fn behind_tls(headers: &axum::http::HeaderMap, forced: bool) -> bool {
    forced
        || headers
            .get("x-forwarded-proto")
            .and_then(|v| v.to_str().ok())
            // 经过多层代理时这个头是逗号分隔的链,最左边是最初那一跳
            .and_then(|v| v.split(',').next())
            .is_some_and(|p| p.trim().eq_ignore_ascii_case("https"))
}

/// 会话 cookie。`secure` 由 [`behind_tls`] 判定——HTTPS 下打上 Secure,
/// 浏览器就不会再把它经明文链路发出去。
pub fn auth_cookie(token: String, secure: bool) -> Cookie<'static> {
    Cookie::build((COOKIE_NAME, token))
        .path("/")
        .http_only(true)
        .secure(secure)
        .same_site(SameSite::Lax)
        .build()
}

/// 注销用的删除指令。**属性必须和签发时一致**:浏览器按 name + domain + path
/// 匹配才认得出要删哪一条,只给名字的话 path 会退化成当前请求路径
/// (`/api/v1/auth`),和签发时的 `/` 对不上——cookie 留在浏览器里,人以为
/// 自己登出了。
pub fn clear_auth_cookie(secure: bool) -> Cookie<'static> {
    Cookie::build((COOKIE_NAME, ""))
        .path("/")
        .http_only(true)
        .secure(secure)
        .same_site(SameSite::Lax)
        .build()
}

pub(crate) fn decode_user_id(state: &AppState, token: &str) -> Result<Uuid, AppError> {
    let data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(state.jwt_secret.as_bytes()),
        &Validation::default(),
    )
    .map_err(|_| AppError::Unauthorized)?;
    Ok(data.claims.sub)
}

/// 请求带来的凭据:Cookie `utopia_token` 优先,其次 `Authorization: Bearer`。
fn presented_credential(parts: &Parts) -> Result<String, AppError> {
    CookieJar::from_headers(&parts.headers)
        .get(COOKIE_NAME)
        .map(|c| c.value().to_string())
        .or_else(|| {
            parts
                .headers
                .get(axum::http::header::AUTHORIZATION)
                .and_then(|v| v.to_str().ok())
                .and_then(|v| v.strip_prefix("Bearer "))
                .map(|v| v.to_string())
        })
        .ok_or(AppError::Unauthorized)
}

/// 已登录用户提取器:Cookie `utopia_token` 或 `Authorization: Bearer`。
pub struct AuthUser(pub User);

impl FromRequestParts<AppState> for AuthUser {
    type Rejection = ApiErr;

    async fn from_request_parts(
        parts: &mut Parts,
        state: &AppState,
    ) -> Result<Self, Self::Rejection> {
        let token = presented_credential(parts)?;
        let user_id = decode_user_id(state, &token)?;
        let user = utopia_store::accounts::find_user_by_id(&state.pool, user_id)
            .await?
            .ok_or(AppError::Unauthorized)?;
        Ok(AuthUser(user))
    }
}

/// 会话或个人令牌,二者都落到同一个 `User` 上(0014 决定 6,#1243)。
///
/// **不替换 `AuthUser`。** `AuthUser` 把每个 Bearer 都当 JWT 解,令牌在那几百条
/// 路由上一律是 401——那是有意的:哪条路由准令牌进来,要在 0014 里说出理由。
/// 用这个提取器的只有文档原件(0052)、「把一个库搭起来」那几条和读图那几条:搜实体、
/// 实体详情、认知历史、事实证据、图总览、邻域(决定 7)。
///
/// 令牌只收窄:`pat` 在的时候,路由先问 [`Self::require_write`] 或
/// [`Self::reaches`],角色照旧由 `require_kb` 与工作区角色判。
pub struct SessionOrToken {
    pub user: User,
    /// None = 网页会话,不收窄任何东西
    pub pat: Option<utopia_store::tokens::Authenticated>,
}

impl FromRequestParts<AppState> for SessionOrToken {
    type Rejection = ApiErr;

    async fn from_request_parts(
        parts: &mut Parts,
        state: &AppState,
    ) -> Result<Self, Self::Rejection> {
        let raw = presented_credential(parts)?;
        // 过期与撤销在 `authenticate` 的 SQL 里判;停用的人 `find_user_by_id` 挡住
        let (user_id, pat) = if raw.starts_with(utopia_store::tokens::PREFIX) {
            let pat = utopia_store::tokens::authenticate(&state.pool, raw.trim()).await?;
            (pat.user_id, Some(pat))
        } else {
            (decode_user_id(state, &raw)?, None)
        };
        let user = utopia_store::accounts::find_user_by_id(&state.pool, user_id)
            .await?
            .ok_or(AppError::Unauthorized)?;
        Ok(Self { user, pat })
    }
}

impl SessionOrToken {
    /// 代人行事的那枚令牌;会话是 None。审计行靠它分得出是哪一枚(0014 决定 6)
    pub fn token_id(&self) -> Option<Uuid> {
        self.pat.as_ref().map(|pat| pat.token_id)
    }

    /// 令牌有没有把这个库排除掉。会话什么都不排除;这不是权限,权限归角色
    pub fn reaches(&self, kb_id: Uuid) -> bool {
        self.pat.as_ref().is_none_or(|pat| pat.covers(kb_id))
    }

    /// 令牌准不准往这个库里写。`None` 是一个还不存在的库:限定过 `kb_ids` 的令牌
    /// 列表里不可能有它,所以建库只给不限库的令牌。
    ///
    /// 两种拒绝各带 code:它们都是「换一枚令牌就行」,与角色不够的 403 不是一回事
    pub fn require_write(&self, kb_id: Option<Uuid>) -> Result<(), AppError> {
        let Some(pat) = &self.pat else {
            return Ok(());
        };
        if !pat.can_write() {
            return Err(AppError::CodedForbidden {
                code: "token_read_only",
                message: "This token is read-only; issue one with the write scope".into(),
            });
        }
        let in_scope = match kb_id {
            Some(kb_id) => pat.covers(kb_id),
            None => pat.kb_ids.is_none(),
        };
        if !in_scope {
            return Err(AppError::CodedForbidden {
                code: "token_kb_out_of_scope",
                message: "This token reaches only the knowledge bases it lists".into(),
            });
        }
        Ok(())
    }
}

/// 生成一条 JWT 签名密钥:32 字节 CSPRNG,hex 编码成 64 个字符。
///
/// 长度取 32 字节是因为 HS256 的 HMAC 块就是 32 字节——再长会被先哈希一遍,
/// 并不增加强度。hex 而非 base64:这个值会出现在日志、环境变量和运维的复制粘贴里,
/// 不带 +/= 省去一整类转义问题。
pub fn generate_jwt_secret() -> String {
    use argon2::password_hash::rand_core::RngCore;
    let mut buf = [0u8; 32];
    OsRng.fill_bytes(&mut buf);
    buf.iter().map(|b| format!("{b:02x}")).collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn claims_in(days: i64) -> Claims {
        Claims {
            sub: Uuid::now_v7(),
            exp: (Utc::now() + chrono::Duration::days(days)).timestamp(),
        }
    }

    /// JWT 校验的护栏:默认配置必须认自家签发的 HS256,且拒绝换密钥与过期。
    /// 加于 jsonwebtoken 9 → 10 升级时(CVE-2026-25537:<10.3.0 的类型混淆可绕过授权)——
    /// 库的默认校验语义是编译器看不见的那部分,回归靠这里兜。
    #[test]
    fn default_validation_accepts_own_token_and_rejects_the_rest() {
        let secret = b"test-secret-not-a-real-key";
        let claims = claims_in(7);
        let token = encode(
            &Header::default(),
            &claims,
            &EncodingKey::from_secret(secret),
        )
        .expect("issuing must succeed");

        let decoded = decode::<Claims>(
            &token,
            &DecodingKey::from_secret(secret),
            &Validation::default(),
        )
        .expect("own token must verify under default validation");
        assert_eq!(decoded.claims.sub, claims.sub, "sub must survive the trip");

        assert!(
            decode::<Claims>(
                &token,
                &DecodingKey::from_secret(b"a-different-secret"),
                &Validation::default(),
            )
            .is_err(),
            "a token signed with another key must not verify"
        );

        let expired = encode(
            &Header::default(),
            &claims_in(-1),
            &EncodingKey::from_secret(secret),
        )
        .expect("issuing must succeed");
        assert!(
            decode::<Claims>(
                &expired,
                &DecodingKey::from_secret(secret),
                &Validation::default(),
            )
            .is_err(),
            "exp must be enforced by default"
        );
    }

    fn headers_with(proto: Option<&str>) -> axum::http::HeaderMap {
        let mut h = axum::http::HeaderMap::new();
        if let Some(p) = proto {
            h.insert("x-forwarded-proto", p.parse().unwrap());
        }
        h
    }

    /// Secure 的判定必须只在确认走了 TLS 时为真:判错成 true,明文部署的用户
    /// 登录后浏览器直接丢掉 cookie,症状是「点了登录又回到登录页」,且不报错。
    #[test]
    fn secure_only_when_tls_is_actually_in_front() {
        // 没有代理:本地直连、cargo run —— 不能打 Secure,否则 HTTP 下登不上
        assert!(!behind_tls(&headers_with(None), false));
        assert!(!behind_tls(&headers_with(Some("http")), false));

        assert!(behind_tls(&headers_with(Some("https")), false));
        // 头的大小写由代理决定,不能假设
        assert!(behind_tls(&headers_with(Some("HTTPS")), false));

        // 多层代理时这个头是逗号分隔的链,最左边是最初那一跳——
        // 取错一端会把「用户走 HTTPS 到边缘、边缘走 HTTP 回源」判成明文
        assert!(behind_tls(&headers_with(Some("https, http")), false));
        assert!(!behind_tls(&headers_with(Some("http, https")), false));

        // 配置强制打开:给不发这个头的代理兜底
        assert!(behind_tls(&headers_with(None), true));
    }

    /// 「邮箱不存在」分支用的 dummy 哈希:唯一要紧的属性是它和真实哈希用同一套参数,
    /// 这样两条分支跑的是同一段 argon2 计算。明文是什么无关紧要——`verify_password`
    /// 解析成功后就完整跑一遍,匹配与否都花同样的时间
    #[test]
    fn the_dummy_hash_costs_the_same_as_a_real_one() {
        let dummy = PasswordHash::new(dummy_password_hash()).expect("the dummy parses");
        let real_str = hash_password("anything").unwrap();
        let real = PasswordHash::new(&real_str).unwrap();
        assert_eq!(dummy.algorithm, real.algorithm);
        assert_eq!(
            dummy.params, real.params,
            "the dummy must cost what a real verify costs"
        );
        assert_eq!(
            dummy.salt.map(|s| s.len()),
            real.salt.map(|s| s.len()),
            "same salt length as a real hash"
        );
        assert!(!verify_password("anything", dummy_password_hash()));
    }
}