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 设备认证) 完全不受影响

Cargo.toml

@@ -29,6 +29,7 @@ rust-version = "1.75"
 # Async runtime
 tokio = { version = "1", features = ["full"] }
 tokio-stream = "0.1"
+tokio-util = "0.7"
 futures = "0.3"
 async-stream = "0.3"
 
@@ -102,7 +103,7 @@ tempfile = "3"
 
 # SaaS dependencies
 axum = { version = "0.7", features = ["macros"] }
-axum-extra = { version = "0.9", features = ["typed-header"] }
+axum-extra = { version = "0.9", features = ["typed-header", "cookie"] }
 tower = { version = "0.4", features = ["util"] }
 tower-http = { version = "0.5", features = ["cors", "trace", "limit", "timeout"] }
 jsonwebtoken = "9"

admin-v2/src/services/request.ts

@@ -1,6 +1,9 @@
 // ============================================================
 // ZCLAW Admin V2 — Axios 实例 + JWT 拦截器
 // ============================================================
+//
+// 认证策略: 主路径使用 HttpOnly cookie（浏览器自动附加），
+// Authorization header 作为 fallback 保留用于 API 客户端。
 
 import axios from 'axios'
 import type { AxiosError, InternalAxiosRequestConfig } from 'axios'
@@ -26,9 +29,10 @@ const request = axios.create({
   baseURL: BASE_URL,
   timeout: TIMEOUT_MS,
   headers: { 'Content-Type': 'application/json' },
+  withCredentials: true, // 发送 HttpOnly cookies
 })
 
-// ── 请求拦截器：自动附加 JWT ──────────────────────────────
+// ── 请求拦截器：附加 Authorization header fallback ──────────
 
 request.interceptors.request.use((config: InternalAxiosRequestConfig) => {
   const token = useAuthStore.getState().token
@@ -77,9 +81,15 @@ request.interceptors.response.use(
       try {
         const res = await axios.post(`${BASE_URL}/auth/refresh`, null, {
           headers: { Authorization: `Bearer ${store.refreshToken}` },
+          withCredentials: true, // 发送 refresh cookie
         })
         const newToken = res.data.token as string
+        const newRefreshToken = res.data.refresh_token as string
+        // 更新内存中的 token（实际认证通过 HttpOnly cookie，浏览器已自动更新）
         store.setToken(newToken)
+        if (newRefreshToken) {
+          store.setRefreshToken(newRefreshToken)
+        }
         onTokenRefreshed(newToken)
         originalRequest.headers.Authorization = `Bearer ${newToken}`
         return request(originalRequest)

admin-v2/src/stores/authStore.ts

@@ -1,6 +1,10 @@
 // ============================================================
 // ZCLAW Admin V2 — Zustand 认证状态管理
 // ============================================================
+//
+// 安全策略: JWT token 通过 HttpOnly cookie 传递，前端 JS 无法读取。
+// account 信息（显示名/角色）仍存 localStorage 用于页面刷新后恢复 UI。
+// 内存中的 token/refreshToken 仅用于 Authorization header fallback（API 客户端兼容）。
 
 import { create } from 'zustand'
 import type { AccountPublic } from '@/types'
@@ -14,25 +18,22 @@ const ROLE_PERMISSIONS: Record<string, string[]> = {
   ],
   admin: [
     'account:read', 'account:admin', 'provider:manage', 'model:read',
-    'model:manage', 'relay:use', 'relay:admin', 'config:read',
+    'model:manage', 'relay:use', 'config:read',
     'config:write', 'prompt:read', 'prompt:write', 'prompt:publish',
   ],
   user: ['model:read', 'relay:use', 'config:read', 'prompt:read'],
 }
 
-const TOKEN_KEY = 'zclaw_admin_token'
-const REFRESH_KEY = 'zclaw_admin_refresh_token'
 const ACCOUNT_KEY = 'zclaw_admin_account'
 
-function loadFromStorage(): { token: string | null; refreshToken: string | null; account: AccountPublic | null } {
+/** 从 localStorage 恢复 account 信息（token 通过 HttpOnly cookie 管理） */
-  const token = localStorage.getItem(TOKEN_KEY)
+function loadFromStorage(): { account: AccountPublic | null } {
-  const refreshToken = localStorage.getItem(REFRESH_KEY)
   const raw = localStorage.getItem(ACCOUNT_KEY)
   let account: AccountPublic | null = null
   if (raw) {
     try { account = JSON.parse(raw) } catch { /* ignore */ }
   }
-  return { token, refreshToken, account }
+  return { account }
 }
 
 interface AuthState {
@@ -42,6 +43,7 @@ interface AuthState {
   permissions: string[]
 
   setToken: (token: string) => void
+  setRefreshToken: (refreshToken: string) => void
   login: (token: string, refreshToken: string, account: AccountPublic) => void
   logout: () => void
   hasPermission: (permission: string) => boolean
@@ -49,23 +51,28 @@ interface AuthState {
 
 export const useAuthStore = create<AuthState>((set, get) => {
   const stored = loadFromStorage()
-  const perms = stored.account ? (ROLE_PERMISSIONS[stored.account.role] ?? []) : []
+  const perms = stored.account?.role
+    ? (ROLE_PERMISSIONS[stored.account.role] ?? [])
+    : []
 
   return {
-    token: stored.token,
+    token: null,
-    refreshToken: stored.refreshToken,
+    refreshToken: null,
     account: stored.account,
     permissions: perms,
 
     setToken: (token: string) => {
-      localStorage.setItem(TOKEN_KEY, token)
       set({ token })
     },
 
+    setRefreshToken: (refreshToken: string) => {
+      set({ refreshToken })
+    },
+
     login: (token: string, refreshToken: string, account: AccountPublic) => {
-      localStorage.setItem(TOKEN_KEY, token)
+      // account 保留 localStorage（仅用于 UI 显示，非敏感）
-      localStorage.setItem(REFRESH_KEY, refreshToken)
       localStorage.setItem(ACCOUNT_KEY, JSON.stringify(account))
+      // token 仅存内存（实际认证通过 HttpOnly cookie）
       set({
         token,
         refreshToken,
@@ -75,10 +82,10 @@ export const useAuthStore = create<AuthState>((set, get) => {
     },
 
     logout: () => {
-      localStorage.removeItem(TOKEN_KEY)
-      localStorage.removeItem(REFRESH_KEY)
       localStorage.removeItem(ACCOUNT_KEY)
       set({ token: null, refreshToken: null, account: null, permissions: [] })
+      // 调用后端 logout 清除 HttpOnly cookies（fire-and-forget）
+      fetch('/api/v1/auth/logout', { method: 'POST', credentials: 'include' }).catch(() => {})
     },
 
     hasPermission: (permission: string) => {

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

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,8 +115,16 @@ pub async fn auth_middleware(
         .get(header::AUTHORIZATION)
         .and_then(|v| v.to_str().ok());
 
-    let result = if let Some(auth) = auth_header {
+    // 尝试从 Authorization header 提取 token
-        if let Some(token) = auth.strip_prefix("Bearer ") {
+    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
@@ -133,9 +142,6 @@ pub async fn auth_middleware(
         }
     } else {
         Err(SaasError::Unauthorized)
-        }
-    } else {
-        Err(SaasError::Unauthorized)
     };
 
     match result {
@@ -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))
 }
 
 /// 需要认证的路由

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))
+    // 配置 TCP keepalive + 短 SO_LINGER，防止 CLOSE_WAIT 累积
-        .await?;
+    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...");
-}