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))
 }

 /// 需要认证的路由
--- a/crates/zclaw-saas/src/main.rs
+++ b/crates/zclaw-saas/src/main.rs
@@ -1,6 +1,7 @@
 //! ZCLAW SaaS 服务入口

 use axum::extract::State;
+use tokio_util::sync::CancellationToken;
 use tower_http::timeout::TimeoutLayer;
 use tracing::info;
 use zclaw_saas::{config::SaaSConfig, db::init_db, state::AppState};
@@ -35,7 +36,9 @@ async fn main() -> anyhow::Result<()> {
    dispatcher.register(UpdateLastUsedWorker);
    info!("Worker dispatcher initialized (5 workers registered)");

-    let state = AppState::new(db.clone(), config.clone(), dispatcher)?;
+    // 优雅停机令牌 — 取消后所有 SSE 流和长连接立即终止
+    let shutdown_token = CancellationToken::new();
+    let state = AppState::new(db.clone(), config.clone(), dispatcher, shutdown_token.clone())?;

    // 启动声明式 Scheduler（从 TOML 配置读取定时任务）
    let scheduler_config = &config.scheduler;
@@ -57,16 +60,55 @@ async fn main() -> anyhow::Result<()> {

    let app = build_router(state).await;

-    let listener = tokio::net::TcpListener::bind(format!("{}:{}", config.server.host, config.server.port))
-        .await?;
+    // 配置 TCP keepalive + 短 SO_LINGER，防止 CLOSE_WAIT 累积
+    let listener = create_listener(&config.server.host, config.server.port)?;
    info!("SaaS server listening on {}:{}", config.server.host, config.server.port);

+    // 优雅停机: Ctrl+C → 取消 CancellationToken → SSE 流终止 → 连接排空
+    let token = shutdown_token.clone();
    axum::serve(listener, app.into_make_service_with_connect_info::<std::net::SocketAddr>())
-        .with_graceful_shutdown(shutdown_signal())
+        .with_graceful_shutdown(async move {
+            tokio::signal::ctrl_c()
+                .await
+                .expect("Failed to install Ctrl+C handler");
+            info!("Received shutdown signal, cancelling SSE streams and draining connections...");
+            token.cancel();
+        })
        .await?;
    Ok(())
 }

+/// 创建带 TCP keepalive 和短 SO_LINGER 的 TcpListener，防止 CLOSE_WAIT 累积
+fn create_listener(host: &str, port: u16) -> anyhow::Result<tokio::net::TcpListener> {
+    let addr = format!("{}:{}", host, port);
+    let socket = socket2::Socket::new(
+        socket2::Domain::for_address(addr.parse::<std::net::SocketAddr>()?),
+        socket2::Type::STREAM,
+        Some(socket2::Protocol::TCP),
+    )?;
+
+    // SO_REUSEADDR: 允许快速重启时复用 TIME_WAIT 端口
+    socket.set_reuse_address(true)?;
+
+    // TCP keepalive: 60s 空闲后每 10s 探测，连续 3 次无响应则关闭
+    // 防止已断开但对端未发 FIN 的连接永远留在 CLOSE_WAIT
+    let keepalive = socket2::SockRef::from(&socket);
+    keepalive.set_tcp_keepalive(
+        &socket2::TcpKeepalive::new()
+            .with_time(std::time::Duration::from_secs(60))
+            .with_interval(std::time::Duration::from_secs(10)),
+    )?;
+
+    // 短 SO_LINGER (1s): 关闭时最多等 1 秒即 RST，避免大量 TIME_WAIT
+    socket.set_linger(Some(std::time::Duration::from_secs(1)))?;
+
+    socket.bind(&addr.parse::<std::net::SocketAddr>()?.into())?;
+    socket.listen(1024)?;
+    socket.set_nonblocking(true)?;
+
+    Ok(tokio::net::TcpListener::from_std(socket.into())?)
+}
+
 async fn health_handler(
    State(state): State<AppState>,
 ) -> (axum::http::StatusCode, axum::Json<serde_json::Value> ) {
@@ -133,6 +175,7 @@ async fn build_router(state: AppState) -> axum::Router {
                    .allow_origin(Any)
                    .allow_methods(Any)
                    .allow_headers(Any)
+                    .allow_credentials(true)
            } else {
                tracing::error!("生产环境必须配置 server.cors_origins，不能使用 allow_origin(Any)");
                panic!("生产环境必须配置 server.cors_origins 白名单。开发环境可设置 ZCLAW_SAAS_DEV=true 绕过。");
@@ -154,8 +197,10 @@ async fn build_router(state: AppState) -> axum::Router {
                .allow_headers([
                    axum::http::header::AUTHORIZATION,
                    axum::http::header::CONTENT_TYPE,
+                    axum::http::header::COOKIE,
                    axum::http::HeaderName::from_static("x-request-id"),
                ])
+                .allow_credentials(true)
        }
    };

@@ -205,11 +250,3 @@ async fn build_router(state: AppState) -> axum::Router {
        .layer(cors)
        .with_state(state)
 }
-
-/// 监听 Ctrl+C 信号，触发 graceful shutdown
-async fn shutdown_signal() {
-    tokio::signal::ctrl_c()
-        .await
-        .expect("Failed to install Ctrl+C handler");
-    info!("Received shutdown signal, draining connections...");
-}