World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 认证: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()));
}
}