feat(security): Auth Token HttpOnly Cookie — XSS 安全加固

后端: - axum-extra 启用 cookie feature - login/register/refresh 设置 HttpOnly + Secure + SameSite=Strict cookies - 新增 POST /api/v1/auth/logout 清除 cookies - auth_middleware 支持 cookie 提取路径（fallback from header） - CORS: 添加 allow_credentials(true) + COOKIE header 前端 (admin-v2): - authStore: token 仅存内存，不再写 localStorage（account 保留） - request.ts: 添加 withCredentials: true 发送 cookies - 修复 refresh token rotation bug（之前不更新 stored refreshToken） - logout 调用后端清除 cookie 端点向后兼容: API 客户端仍可用 Authorization: Bearer header Desktop (Ed25519 设备认证) 完全不受影响
2026-03-30 19:30:42 +08:00
parent e7b2d1c099
commit c2aff09811
6 changed files with 174 additions and 60 deletions
--- a/crates/zclaw-saas/src/auth/handlers.rs
+++ b/crates/zclaw-saas/src/auth/handlers.rs
@@ -1,6 +1,8 @@
 //! 认证 HTTP 处理器

-use axum::{extract::{State, ConnectInfo}, http::StatusCode, Json};
+use axum::{extract::{State, ConnectInfo}, Json};
+use axum_extra::extract::CookieJar;
+use axum_extra::extract::cookie::{Cookie, SameSite};
 use std::net::SocketAddr;
 use secrecy::ExposeSecret;
 use crate::state::AppState;
@@ -12,13 +14,49 @@ use super::{
    types::{AuthContext, LoginRequest, LoginResponse, RegisterRequest, ChangePasswordRequest, AccountPublic, RefreshRequest},
 };

+/// Cookie 配置常量
+const ACCESS_TOKEN_COOKIE: &str = "zclaw_access_token";
+const REFRESH_TOKEN_COOKIE: &str = "zclaw_refresh_token";
+
+/// 构建 auth cookies 并附加到 CookieJar
+fn set_auth_cookies(jar: CookieJar, token: &str, refresh_token: &str) -> CookieJar {
+    let access_max_age = std::time::Duration::from_secs(2 * 3600); // 2h
+    let refresh_max_age = std::time::Duration::from_secs(7 * 86400); // 7d
+
+    // cookie crate 需要 time::Duration，从 std 转换
+    let access = Cookie::build((ACCESS_TOKEN_COOKIE, token.to_string()))
+        .http_only(true)
+        .secure(true)
+        .same_site(SameSite::Strict)
+        .path("/api")
+        .max_age(access_max_age.try_into().unwrap_or_else(|_| std::time::Duration::from_secs(3600).try_into().unwrap()))
+        .build();
+
+    let refresh = Cookie::build((REFRESH_TOKEN_COOKIE, refresh_token.to_string()))
+        .http_only(true)
+        .secure(true)
+        .same_site(SameSite::Strict)
+        .path("/api/v1/auth")
+        .max_age(refresh_max_age.try_into().unwrap_or_else(|_| std::time::Duration::from_secs(86400).try_into().unwrap()))
+        .build();
+
+    jar.add(access).add(refresh)
+}
+
+/// 清除 auth cookies
+fn clear_auth_cookies(jar: CookieJar) -> CookieJar {
+    jar.remove(Cookie::build(ACCESS_TOKEN_COOKIE).path("/api"))
+      .remove(Cookie::build(REFRESH_TOKEN_COOKIE).path("/api/v1/auth"))
+}
+
 /// POST /api/v1/auth/register
 /// 注册成功后自动签发 JWT，返回与 login 一致的 LoginResponse
 pub async fn register(
    State(state): State<AppState>,
    ConnectInfo(addr): ConnectInfo<SocketAddr>,
+    jar: CookieJar,
    Json(req): Json<RegisterRequest>,
-) -> SaasResult<(StatusCode, Json<LoginResponse>)> {
+) -> SaasResult<(CookieJar, Json<LoginResponse>)> {
    if req.username.len() < 3 {
        return Err(SaasError::InvalidInput("用户名至少 3 个字符".into()));
    }
@@ -100,9 +138,9 @@ pub async fn register(
        state.jwt_secret.expose_secret(), 168,
    ).await?;

-    Ok((StatusCode::CREATED, Json(LoginResponse {
+    let resp = LoginResponse {
        token,
-        refresh_token,
+        refresh_token: refresh_token.clone(),
        account: AccountPublic {
            id: account_id,
            username: req.username,
@@ -113,15 +151,18 @@ pub async fn register(
            totp_enabled: false,
            created_at: now,
        },
-    })))
+    };
+    let jar = set_auth_cookies(jar, &resp.token, &refresh_token);
+    Ok((jar, Json(resp)))
 }

 /// POST /api/v1/auth/login
 pub async fn login(
    State(state): State<AppState>,
    ConnectInfo(addr): ConnectInfo<SocketAddr>,
+    jar: CookieJar,
    Json(req): Json<LoginRequest>,
-) -> SaasResult<Json<LoginResponse>> {
+) -> SaasResult<(CookieJar, Json<LoginResponse>)> {
    // 一次查询获取用户信息 + password_hash + totp_secret（合并原来的 3 次查询）
    let row: Option<AccountLoginRow> =
        sqlx::query_as(
@@ -189,14 +230,16 @@ pub async fn login(
        state.jwt_secret.expose_secret(), 168,
    ).await?;

-    Ok(Json(LoginResponse {
+    let resp = LoginResponse {
        token,
-        refresh_token,
+        refresh_token: refresh_token.clone(),
        account: AccountPublic {
            id: r.id, username: r.username, email: r.email, display_name: r.display_name,
            role: r.role, status: r.status, totp_enabled: r.totp_enabled, created_at: r.created_at,
        },
-    }))
+    };
+    let jar = set_auth_cookies(jar, &resp.token, &refresh_token);
+    Ok((jar, Json(resp)))
 }

 /// POST /api/v1/auth/refresh
@@ -204,8 +247,9 @@ pub async fn login(
 /// refresh_token 一次性使用，使用后立即失效
 pub async fn refresh(
    State(state): State<AppState>,
+    jar: CookieJar,
    Json(req): Json<RefreshRequest>,
-) -> SaasResult<Json<serde_json::Value>> {
+) -> SaasResult<(CookieJar, Json<serde_json::Value>)> {
    // 1. 验证 refresh token 签名 (跳过过期检查，但有 7 天窗口限制)
    let claims = verify_token_skip_expiry(&req.refresh_token, state.jwt_secret.expose_secret())?;

@@ -282,10 +326,11 @@ pub async fn refresh(
    // 9. 清理过期/已使用的 refresh tokens 已迁移到 Scheduler 定期执行
    // 不再在每次 refresh 时阻塞请求

-    Ok(Json(serde_json::json!({
+    let jar = set_auth_cookies(jar, &new_access, &new_refresh);
+    Ok((jar, Json(serde_json::json!({
        "token": new_access,
        "refresh_token": new_refresh,
-    })))
+    }))))
 }

 /// GET /api/v1/auth/me — 返回当前认证用户的公开信息
@@ -456,3 +501,10 @@ fn sha256_hex(input: &str) -> String {
    use sha2::{Sha256, Digest};
    hex::encode(Sha256::digest(input.as_bytes()))
 }
+
+/// POST /api/v1/auth/logout — 清除 auth cookies
+pub async fn logout(
+    jar: CookieJar,
+) -> (CookieJar, axum::http::StatusCode) {
+    (clear_auth_cookies(jar), axum::http::StatusCode::NO_CONTENT)
+}
--- a/crates/zclaw-saas/src/auth/mod.rs
+++ b/crates/zclaw-saas/src/auth/mod.rs
@@ -103,9 +103,10 @@ fn extract_client_ip(req: &Request) -> Option<String> {
        .map(|s| s.to_string())
 }

-/// 认证中间件: 从 JWT 或 API Token 提取身份
+/// 认证中间件: 从 JWT Cookie / Authorization Header / API Token 提取身份
 pub async fn auth_middleware(
    State(state): State<AppState>,
+    jar: axum_extra::extract::cookie::CookieJar,
    mut req: Request,
    next: Next,
 ) -> Response {
@@ -114,25 +115,30 @@ pub async fn auth_middleware(
        .get(header::AUTHORIZATION)
        .and_then(|v| v.to_str().ok());

-    let result = if let Some(auth) = auth_header {
-        if let Some(token) = auth.strip_prefix("Bearer ") {
-            if token.starts_with("zclaw_") {
-                // API Token 路径
-                verify_api_token(&state, token, client_ip.clone()).await
-            } else {
-                // JWT 路径
-                let verify_result = jwt::verify_token(token, state.jwt_secret.expose_secret());
-                verify_result
-                    .map(|claims| AuthContext {
-                        account_id: claims.sub,
-                        role: claims.role,
-                        permissions: claims.permissions,
-                        client_ip,
-                    })
-                    .map_err(|_| SaasError::Unauthorized)
-            }
+    // 尝试从 Authorization header 提取 token
+    let header_token = auth_header.and_then(|auth| auth.strip_prefix("Bearer "));
+
+    // 尝试从 HttpOnly cookie 提取 token (仅当 header 不存在时)
+    let cookie_token = jar.get("zclaw_access_token").map(|c| c.value().to_string());
+
+    let token = header_token
+        .or(cookie_token.as_deref());
+
+    let result = if let Some(token) = token {
+        if token.starts_with("zclaw_") {
+            // API Token 路径
+            verify_api_token(&state, token, client_ip.clone()).await
        } else {
-            Err(SaasError::Unauthorized)
+            // JWT 路径
+            let verify_result = jwt::verify_token(token, state.jwt_secret.expose_secret());
+            verify_result
+                .map(|claims| AuthContext {
+                    account_id: claims.sub,
+                    role: claims.role,
+                    permissions: claims.permissions,
+                    client_ip,
+                })
+                .map_err(|_| SaasError::Unauthorized)
        }
    } else {
        Err(SaasError::Unauthorized)
@@ -155,6 +161,7 @@ pub fn routes() -> axum::Router<AppState> {
        .route("/api/v1/auth/register", post(handlers::register))
        .route("/api/v1/auth/login", post(handlers::login))
        .route("/api/v1/auth/refresh", post(handlers::refresh))
+        .route("/api/v1/auth/logout", post(handlers::logout))
 }

 /// 需要认证的路由