feat(auth): 接入 /auth/refresh，不再把登录口令落盘

客户端此前把明文口令存进 EncryptedSharedPreferences，用于过期后的静默重登
（当时后端没有 refresh 端点）。后端现在有 /auth/refresh + /auth/logout 了，
本轮改为存 refresh token，口令在首次成功认证后即被抹掉。

关键约束：服务端的 refresh 是**单次使用 + 原子旋转 + 无宽限期**——同一个 token
第二次使用立刻 invalid_grant；而本端并发 401 是常态（管理概览页两个请求并发、
聊天页 REST 与 WS 同时起步）。因此：

- core/auth/TokenRefresher.kt：单飞刷新 + 代际守卫（等锁期间别人已换好令牌就直接
  复用，绝不用同一个 refresh token 打第二次）+ 终态记忆（被 invalid_grant 拒过的
  token 记下来，一次失效里只打一次注定失败的请求；Transient 不记忆以保留重试）
- 用应用层 Interceptor 而非 OkHttp Authenticator：后者对**任何** 401 都会被调用
  （含不带令牌的登录请求），且由 RetryAndFollowUp 内部循环驱动（上限 20 次跟进），
  持续 401 的令牌会打出刷新风暴。应用层拦截器只在「带了令牌仍 401」时介入，且严格
  重试一次
- 可恢复的 401 不再登出：Transient（网络/5xx）原样交回 401 并保留会话；只有
  Unrecoverable，或「换上刚签发的令牌仍 401」，才判终态
- WS 握手 401：先尝试一次续期再重连，终态才登出
- 登出补调 POST /auth/logout（此前从不调用，服务端 grant 会白活 30 天）
- 主动 skew（60s）刷新 + 兜底重试；刷新请求走不带令牌的客户端，不会递归回本路径

迁移对用户无感、绝不强制重登：启动时若「无 refresh token 但有旧口令」，用旧路径
静默登录一次换到 refresh token，随即 commit() 抹掉口令；离线失败就下次启动再试，
且不清会话。另外鉴权过期时也走一次续期——否则去掉口令会把会话砍到 24h，比改动前
更差。

HttpLoggingInterceptor 保持 BASIC 不动：/auth/refresh 与 /auth/logout 把 refresh
token 放在**请求体**里，再高一级就会把凭据打进 logcat。

测试：153 全绿（115 → +38）。含真实抓取响应体的 DTO 契约测试、TokenRefresher 的
并发/代际/终态单测、bootstrap 迁移单测，以及走真实 OkHttp + Retrofit + 回环
HttpServer 的端到端测试（证明只重试一次）。未新增任何依赖。

未验证项：主动/被动续期路径本身没能真机触发（唯一输入是加密存储里的 expires_at，
shell 写不进去；而 tokenTTL 是 24h 常量），仅由回环端到端测试覆盖。

app/src/main/kotlin/top/yeij/cyrene/app/AppContainer.kt

@@ -37,8 +37,8 @@ class AppContainer(context: Context) {
             val created = ApiClientFactory.create(
                 baseUrl = baseUrl,
                 service = SessionsApi::class.java,
-                tokenProvider = { sessionStore.load().token },
-                onUnauthorized = { authManager.onSessionExpired() },
+                tokenProvider = authManager::currentToken,
+                unauthorizedPolicy = authManager.unauthorizedPolicy,
             )
             cachedBaseUrl = baseUrl
             cachedSessionsApi = created
@@ -61,8 +61,8 @@ class AppContainer(context: Context) {
             val created = ApiClientFactory.create(
                 baseUrl = baseUrl,
                 service = AdminApi::class.java,
-                tokenProvider = { sessionStore.load().token },
-                onUnauthorized = { authManager.onSessionExpired() },
+                tokenProvider = authManager::currentToken,
+                unauthorizedPolicy = authManager.unauthorizedPolicy,
             )
             cachedAdminBaseUrl = baseUrl
             cachedAdminApi = created
@@ -83,8 +83,8 @@ class AppContainer(context: Context) {
             val created = ApiClientFactory.create(
                 baseUrl = baseUrl,
                 service = MetaApi::class.java,
-                tokenProvider = { sessionStore.load().token },
-                onUnauthorized = { authManager.onSessionExpired() },
+                tokenProvider = authManager::currentToken,
+                unauthorizedPolicy = authManager.unauthorizedPolicy,
             )
             cachedMetaBaseUrl = baseUrl
             cachedMetaApi = created
@@ -95,7 +95,8 @@ class AppContainer(context: Context) {
 
     fun createChatSocket(): ChatSocket = ChatSocket(
         baseUrlProvider = { authManager.currentBaseUrl },
-        tokenProvider = { sessionStore.load().token },
-        onAuthFailed = { authManager.onSessionExpired() },
+        tokenProvider = authManager::currentToken,
+        onAuthRecover = authManager::recoverSocketAuth,
+        onAuthFailed = authManager::onSessionExpired,
     )
 }

app/src/main/kotlin/top/yeij/cyrene/app/CyreneApp.kt

@@ -4,6 +4,8 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.rememberCoroutineScope
+import kotlinx.coroutines.launch
 import top.yeij.cyrene.core.auth.SessionState
 import top.yeij.cyrene.ui.chat.ChatHomeScreen
 import top.yeij.cyrene.ui.common.LoadingScreen
@@ -12,6 +14,7 @@ import top.yeij.cyrene.ui.login.LoginScreen
 @Composable
 fun CyreneApp(container: AppContainer) {
     val state by container.authManager.state.collectAsState()
+    val scope = rememberCoroutineScope()
 
     LaunchedEffect(Unit) {
         container.authManager.bootstrap()
@@ -22,7 +25,8 @@ fun CyreneApp(container: AppContainer) {
         SessionState.LoggedOut -> LoginScreen(container)
         is SessionState.LoggedIn -> ChatHomeScreen(
             container = container,
-            onLogout = { container.authManager.logout() },
+            // 登出要先把服务端的 refresh 授权吊销掉，所以是挂起的；UI 不因为它在主线程等待。
+            onLogout = { scope.launch { container.authManager.logout() } },
         )
     }
 }

app/src/main/kotlin/top/yeij/cyrene/core/auth/AuthManager.kt

@@ -5,11 +5,16 @@ import top.yeij.cyrene.data.api.ApiClientFactory
 import top.yeij.cyrene.data.api.ApiErrorEnvelope
 import top.yeij.cyrene.data.api.CyreneApi
 import top.yeij.cyrene.data.api.dto.LoginRequest
+import top.yeij.cyrene.data.api.dto.LogoutRequest
+import top.yeij.cyrene.data.api.dto.RefreshRequest
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withContext
+import kotlinx.coroutines.withTimeoutOrNull
 import java.io.IOException
 import java.net.ConnectException
 import java.net.SocketTimeoutException
@@ -22,30 +27,88 @@ sealed interface SessionState {
     data class LoggedIn(val baseUrl: String, val role: String) : SessionState
 }
 
-class AuthManager(private val store: SessionStore) {
+/**
+ * 会话生命周期：登录、静默恢复、续期、登出。
+ *
+ * B2 起密码**不再落盘**：长期凭据是 refresh token，访问令牌过期时用它续期，
+ * 续期由 [TokenRefresher] 单飞协调（并发 401 只会真的刷一次——服务端轮换无宽限期）。
+ *
+ * @param apiFactory 认证接口的构造方式。默认走真实 Retrofit；单测注入假实现即可覆盖
+ *   登录 / 迁移 / 登出路径，既不需要网络也不需要新增依赖。
+ */
+class AuthManager(
+    private val store: SessionStorage,
+    private val apiFactory: (String) -> CyreneApi = { ApiClientFactory.create(baseUrl = it) },
+) {
 
     private val _state = MutableStateFlow<SessionState>(SessionState.Unknown)
     val state: StateFlow<SessionState> = _state.asStateFlow()
 
-    private var api: CyreneApi? = null
+    @Volatile
     var currentBaseUrl: String = ""
         private set
 
-    /** 启动时：有效 token 直接进入；过期则用已存凭据静默重登（D12）；否则回登录页。 */
+    private val refresher = TokenRefresher(store, ::refreshCall)
+
+    /** 不带令牌的认证客户端（登录 / 刷新 / 登出），按 baseUrl 缓存。可被 OkHttp 线程读到。 */
+    @Volatile
+    private var authApi: CyreneApi? = null
+
+    @Volatile
+    private var authApiBaseUrl: String? = null
+
+    /**
+     * 401 处置：能续期就用新令牌重试一次，明确被拒才判终态。
+     * 暂时性失败（网络 / 5xx）**绝不清会话**——见 B2 §6。
+     */
+    val unauthorizedPolicy: UnauthorizedPolicy = object : UnauthorizedPolicy {
+        override fun renew(usedToken: String): AuthRecovery = refresher.renew(usedToken)
+
+        override fun onSessionEnded() = onSessionExpired()
+    }
+
+    /** tokenProvider 与 WS 握手用：临近过期时阻塞地先换令牌。 */
+    fun currentToken(): String? = refresher.ensureToken()
+
+    /**
+     * WS 握手 401 的一次性恢复：换一次令牌让上层重连。
+     * 与 401 拦截器共用同一条单飞路径，因此 REST 与 WS 同时失效也只会打一次刷新。
+     */
+    fun recoverSocketAuth(): AuthRecovery = refresher.renew(store.load().token)
+
+    /**
+     * 启动时恢复会话（D12 + B2 迁移）。顺序即优先级：
+     *
+     * 1. **迁移**：没有 refresh token 却还留着旧版的明文密码 → 用旧凭据静默登录一次换 refresh token，
+     *    成功后立刻把它抹掉；失败（例如离线）保留原值、**不登出**，下次启动再试。
+     * 2. 已经有 refresh token → 任何残留的明文密码立刻抹掉。
+     * 3. 访问令牌过期 → 用 refresh token 续期。密码没了以后，这是唯一的静默恢复途径；
+     *    没有了它，隔一天再打开就要重新输密码（比旧版还差）。
+     * 4. 仍然拿不到有效令牌 → 回登录页（username 仍预填）。
+     */
     suspend fun bootstrap() = withContext(Dispatchers.IO) {
-        val stored = store.load()
-        currentBaseUrl = stored.baseUrl
-        when {
-            !stored.token.isNullOrBlank() && stored.expiresAt * 1000 > System.currentTimeMillis() -> {
-                _state.value = SessionState.LoggedIn(stored.baseUrl, stored.role.orEmpty())
-            }
+        var session = store.load()
+        currentBaseUrl = session.baseUrl
 
-            !stored.username.isNullOrBlank() && !stored.password.isNullOrBlank() -> {
-                val error = doLogin(stored.baseUrl, stored.username, stored.password)
-                if (error != null) _state.value = SessionState.LoggedOut
-            }
+        val legacyUser = session.username?.takeIf(String::isNotBlank)
+        val legacyPassword = session.password?.takeIf(String::isNotBlank)
+        if (session.refreshToken.isNullOrBlank() && legacyUser != null && legacyPassword != null) {
+            doLogin(session.baseUrl, legacyUser, legacyPassword)
+            session = store.load()
+        } else if (!session.password.isNullOrBlank()) {
+            store.purgePassword()
+            session = store.load()
+        }
 
-            else -> _state.value = SessionState.LoggedOut
+        if (!session.hasValidToken() && !session.refreshToken.isNullOrBlank()) {
+            refresher.renew(session.token)
+            session = store.load()
+        }
+
+        _state.value = if (session.hasValidToken()) {
+            SessionState.LoggedIn(session.baseUrl, session.role.orEmpty())
+        } else {
+            SessionState.LoggedOut
         }
     }
 
@@ -54,28 +117,45 @@ class AuthManager(private val store: SessionStore) {
             doLogin(ApiClientFactory.normalizeBaseUrl(rawBaseUrl), username, password)
         }
 
-    fun logout() {
+    /**
+     * 主动登出：先尽力吊销服务端的 refresh 授权（否则本地「登出」之后那条授权还能活 30 天），
+     * 再抹掉本地一切。吊销失败、超时、离线都不阻断本地清理，所以离线登出依然干净。
+     */
+    suspend fun logout() = withContext(Dispatchers.IO) {
+        val refreshToken = store.load().refreshToken?.takeIf(String::isNotBlank)
+        if (refreshToken != null) {
+            // 吊销请求不能拖住登出：给一个短上限，超时就当离线处理。
+            withTimeoutOrNull(REVOKE_TIMEOUT_MS) {
+                try {
+                    authApi(sessionBaseUrl()).logout(LogoutRequest(refreshToken))
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (_: Exception) {
+                    // 尽力而为：离线 / 服务端报错也必须把本地清干净。
+                }
+            }
+        }
         store.clearAll()
-        api = null
+        authApi = null
+        authApiBaseUrl = null
         _state.value = SessionState.LoggedOut
     }
 
-    /** 会话过期（401）：清 token、回登录页；凭据保留以便下次静默重登。 */
+    /** 会话终结（refresh 不可能或明确被拒）：清令牌回登录页；username 保留以便预填。 */
     fun onSessionExpired() {
         store.clearSession()
-        api = null
         _state.value = SessionState.LoggedOut
     }
 
     private suspend fun doLogin(url: String, username: String, password: String): CyreneError? {
-        val client = ApiClientFactory.create(baseUrl = url)
         return try {
-            val response = client.login(LoginRequest(username, password))
+            val response = authApi(url).login(LoginRequest(username, password))
             val data = response.body()?.data
             when {
                 response.isSuccessful && data != null -> {
-                    store.saveLogin(url, data.token, data.expiresAt, data.role, username, password)
-                    api = client
+                    store.saveLogin(url, data.token, data.expiresAt, data.role, username, data.refreshToken)
+                    // B2 红线：不再写明文密码。拿到长期凭据后，把历史遗留的那一份也一并抹掉。
+                    if (!data.refreshToken.isNullOrBlank()) store.purgePassword()
                     currentBaseUrl = url
                     _state.value = SessionState.LoggedIn(url, data.role)
                     null
@@ -85,7 +165,7 @@ class AuthManager(private val store: SessionStore) {
 
                 else -> {
                     val parsed = parseError(response.errorBody()?.string())
-                    if (response.code() == 401) {
+                    if (response.code() == HTTP_UNAUTHORIZED) {
                         CyreneError.Unauthorized(parsed?.code.orEmpty(), parsed?.message.orEmpty())
                     } else {
                         CyreneError.Server(
@@ -101,6 +181,52 @@ class AuthManager(private val store: SessionStore) {
         }
     }
 
+    /**
+     * [TokenRefresher] 注入的阻塞刷新调用。
+     *
+     * 它跑在 OkHttp 的调用线程上（拦截器 / tokenProvider），所以这里用 `runBlocking` 就地驱动
+     * Retrofit 的挂起接口——那正是此刻需要的语义：同步等结果。
+     *
+     * 客户端**不带令牌**，镜像 [doLogin]：既不会让过期令牌搭车，也不会把刷新的 401 送回
+     * 本类的过期处理路径（那两个客户端用的是 [NoUnauthorizedPolicy]）。
+     */
+    private fun refreshCall(refreshToken: String): RefreshCall {
+        val baseUrl = sessionBaseUrl()
+        if (baseUrl.isBlank()) return RefreshCall.Failed
+        return try {
+            val response = runBlocking { authApi(baseUrl).refresh(RefreshRequest(refreshToken)) }
+            val data = response.body()?.data
+            when {
+                response.isSuccessful && data != null ->
+                    RefreshCall.Ok(data.token, data.expiresAt, data.refreshToken)
+
+                // 200 但解不动：不拿会话去赌，当暂时性失败。
+                response.isSuccessful -> RefreshCall.Failed
+
+                // 该接口唯一的 401 就是 invalid_grant（未知 / 已吊销 / 已过期 / 已被用掉）。
+                response.code() == HTTP_UNAUTHORIZED -> RefreshCall.Rejected
+
+                else -> RefreshCall.Failed
+            }
+        } catch (_: Exception) {
+            RefreshCall.Failed
+        }
+    }
+
+    private fun authApi(baseUrl: String): CyreneApi {
+        val cached = authApi
+        if (cached != null && authApiBaseUrl == baseUrl) return cached
+        val created = apiFactory(baseUrl)
+        authApi = created
+        authApiBaseUrl = baseUrl
+        return created
+    }
+
+    private fun sessionBaseUrl(): String = currentBaseUrl.ifBlank { store.load().baseUrl }
+
+    private fun StoredSession.hasValidToken(): Boolean =
+        !token.isNullOrBlank() && expiresAt * 1000 > System.currentTimeMillis()
+
     private fun parseError(body: String?) = body
         ?.takeIf { it.isNotBlank() }
         ?.let {
@@ -118,4 +244,11 @@ class AuthManager(private val store: SessionStore) {
         is IOException -> CyreneError.Local(CyreneError.LocalKind.NoNetwork)
         else -> CyreneError.Local(CyreneError.LocalKind.Unknown)
     }
+
+    private companion object {
+        const val HTTP_UNAUTHORIZED = 401
+
+        /** 吊销授权的最长等待：到点就当离线，本地照样清干净。 */
+        const val REVOKE_TIMEOUT_MS = 3_000L
+    }
 }

app/src/main/kotlin/top/yeij/cyrene/core/auth/SessionStore.kt

@@ -11,11 +11,55 @@ data class StoredSession(
     val expiresAt: Long,
     val role: String?,
     val username: String?,
+    /** 长期凭据（B2）；B2 之前登录的安装没有这一项，因此可能为 null。 */
+    val refreshToken: String?,
+    /**
+     * **遗留字段**：B2 之前的版本把登录密码落在这里。
+     * 只读用于一次性迁移，绝不再写入；见 [SessionStorage.purgePassword]。
+     */
     val password: String?,
 )
 
-/** JWT 与登录凭据的加密存储（红线：不落明文、不打日志）。 */
-class SessionStore(context: Context) {
+/**
+ * 会话存储契约。[SessionStore] 是唯一的生产实现（EncryptedSharedPreferences）；
+ * 单元测试用内存假实现顶替，避免把 Android 的加密存储拖进 JVM 测试。
+ */
+interface SessionStorage {
+
+    fun load(): StoredSession
+
+    /** 登录成功：整份会话落盘。**不写密码**（B2 红线）。 */
+    fun saveLogin(
+        baseUrl: String,
+        token: String,
+        expiresAt: Long,
+        role: String,
+        username: String,
+        refreshToken: String?,
+    )
+
+    /**
+     * 只替换令牌三元组，保留 baseUrl / username / role。
+     * [refreshToken] 为 null 表示沿用原值——`AUTH_REFRESH_ROTATE_DISABLED=true` 时服务端不下发新的，
+     * 此时旧凭据仍然有效，绝不能丢掉。
+     */
+    fun updateTokens(token: String, expiresAt: Long, refreshToken: String?)
+
+    /**
+     * 确定性抹掉历史遗留的明文密码。
+     * 用 `commit()` 而不是 `apply()`：这是红线清除，必须在下一次读取之前就落到磁盘上。
+     */
+    fun purgePassword()
+
+    /** 会话失效：清 token 与 refresh token，保留 username 以便登录页预填。 */
+    fun clearSession()
+
+    /** 主动登出：整份清空。 */
+    fun clearAll()
+}
+
+/** JWT 与登录凭据的加密存储（红线：不落明文密码、不打日志）。 */
+class SessionStore(context: Context) : SessionStorage {
 
     private val prefs: SharedPreferences = EncryptedSharedPreferences.create(
         context,
@@ -25,44 +69,58 @@ class SessionStore(context: Context) {
         EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
     )
 
-    fun load(): StoredSession = StoredSession(
+    override fun load(): StoredSession = StoredSession(
         baseUrl = prefs.getString(KEY_BASE_URL, "").orEmpty(),
         token = prefs.getString(KEY_TOKEN, null),
         expiresAt = prefs.getLong(KEY_EXPIRES_AT, 0L),
         role = prefs.getString(KEY_ROLE, null),
         username = prefs.getString(KEY_USERNAME, null),
+        refreshToken = prefs.getString(KEY_REFRESH_TOKEN, null),
+        // 只读：迁移路径靠它判断「这是升级前的安装」，不再写入。
         password = prefs.getString(KEY_PASSWORD, null),
     )
 
-    fun saveLogin(
+    override fun saveLogin(
         baseUrl: String,
         token: String,
         expiresAt: Long,
         role: String,
         username: String,
-        password: String,
+        refreshToken: String?,
     ) {
-        prefs.edit()
+        val editor = prefs.edit()
             .putString(KEY_BASE_URL, baseUrl)
             .putString(KEY_TOKEN, token)
             .putLong(KEY_EXPIRES_AT, expiresAt)
             .putString(KEY_ROLE, role)
             .putString(KEY_USERNAME, username)
-            .putString(KEY_PASSWORD, password)
-            .apply()
+        if (!refreshToken.isNullOrBlank()) editor.putString(KEY_REFRESH_TOKEN, refreshToken)
+        editor.apply()
     }
 
-    /** 会话失效（401/过期）：清 token，但保留凭据以便静默重登（D12）。 */
-    fun clearSession() {
+    override fun updateTokens(token: String, expiresAt: Long, refreshToken: String?) {
+        val editor = prefs.edit()
+            .putString(KEY_TOKEN, token)
+            .putLong(KEY_EXPIRES_AT, expiresAt)
+        // 轮换关闭时服务端不下发新凭据，旧的那一份继续有效，必须保留。
+        if (!refreshToken.isNullOrBlank()) editor.putString(KEY_REFRESH_TOKEN, refreshToken)
+        editor.apply()
+    }
+
+    override fun purgePassword() {
+        prefs.edit().remove(KEY_PASSWORD).commit()
+    }
+
+    override fun clearSession() {
         prefs.edit()
             .remove(KEY_TOKEN)
             .remove(KEY_EXPIRES_AT)
             .remove(KEY_ROLE)
+            .remove(KEY_REFRESH_TOKEN)
             .apply()
     }
 
-    /** 主动登出：凭据一并清掉，避免下次启动被静默登回去。 */
-    fun clearAll() {
+    override fun clearAll() {
         prefs.edit().clear().apply()
     }
 
@@ -73,6 +131,7 @@ class SessionStore(context: Context) {
         const val KEY_EXPIRES_AT = "expires_at"
         const val KEY_ROLE = "role"
         const val KEY_USERNAME = "username"
+        const val KEY_REFRESH_TOKEN = "refresh_token"
         const val KEY_PASSWORD = "password"
     }
 }

app/src/main/kotlin/top/yeij/cyrene/core/auth/TokenRefresher.kt

@@ -0,0 +1,132 @@
+package top.yeij.cyrene.core.auth
+
+/** 一次令牌续期的结果。 */
+sealed interface AuthRecovery {
+
+    /** 已拿到可用的访问令牌：可能是刚签发的，也可能是别的线程刚换好的。 */
+    data class Renewed(val token: String) : AuthRecovery
+
+    /**
+     * 无法续期：本地没有 refresh token，或被服务端以 `invalid_grant` 拒绝
+     * （未知 / 已吊销 / 已过期 / 已被用掉，服务端把这四种情况折叠成一个码）。
+     * 这是终态——必须重新登录。
+     */
+    data object Unrecoverable : AuthRecovery
+
+    /** 暂时性失败：网络不通、5xx、响应解不动。会话可能仍然有效，稍后再试。 */
+    data object Transient : AuthRecovery
+}
+
+/**
+ * [TokenRefresher] 注入的刷新调用结果。
+ * 把 HTTP 细节挡在协调逻辑之外，单飞与代际守卫因此可以纯 JVM 单测。
+ */
+sealed interface RefreshCall {
+
+    /** 200：新的访问令牌；[refreshToken] 为 null 表示服务端关闭了轮换、旧凭据继续有效。 */
+    data class Ok(val token: String, val expiresAt: Long, val refreshToken: String?) : RefreshCall
+
+    /** `401 invalid_grant`。 */
+    data object Rejected : RefreshCall
+
+    /** 网络 / 5xx / 解析失败。 */
+    data object Failed : RefreshCall
+}
+
+/**
+ * 单飞（single-flight）刷新协调器。
+ *
+ * ## 为什么必须单飞
+ * 服务端 `RefreshStore.Rotate` 是**原子且无宽限期**的：同一个 refresh token 被第二次使用会立刻
+ * 拿到 `invalid_grant`（防重放）。而本端并发 401 是常态——管理概览页两个请求并发、聊天页 REST 与
+ * WS 同时起步。所以同一时刻只允许一个线程真正发刷新请求，其余线程在锁上等待后复用结果。
+ *
+ * ## 代际守卫
+ * 拿到锁之后**重新读一次存储**：如果已存的访问令牌既不是自己手里那份（[renew] 的 `staleToken`）、
+ * 又还没到过期点，说明等在锁上的这段时间里别的线程已经换好了令牌——直接复用，绝不刷第二次。
+ *
+ * ## 线程模型
+ * 全部逻辑跑在**调用方线程**上（OkHttp 的调用线程 / WS 重连协程），用 JVM 监视器锁串行化。
+ * 因此这里没有、也不能用协程 `Mutex`——调用点根本没有 suspend 上下文。
+ * 真实的刷新请求由调用方用**不带令牌**的客户端发出（见 `AuthManager.refreshCall`），
+ * 不会递归回本类。
+ *
+ * @param store 会话读写；实现必须让写入立刻对下一次 [SessionStorage.load] 可见。
+ * @param call 真正发刷新请求的阻塞调用。
+ * @param now 当前毫秒时间戳，可注入以便单测。
+ */
+class TokenRefresher(
+    private val store: SessionStorage,
+    private val call: (refreshToken: String) -> RefreshCall,
+    private val now: () -> Long = System::currentTimeMillis,
+) {
+
+    private val lock = Any()
+
+    /**
+     * 已经确定无效的那个 refresh token。`invalid_grant` 对该值而言是**永久**结论，
+     * 记下来可以让同一次失效里的其它并发 401 直接得到终态，不必各打一次注定失败的请求。
+     * 值本身随机且每次轮换都变，因此不需要额外失效逻辑。
+     */
+    private var rejectedRefreshToken: String? = null
+
+    /** 距过期不足 [SKEW_MS] 就算「该提前换令牌了」。 */
+    fun isNearExpiry(session: StoredSession): Boolean =
+        session.expiresAt * 1000 - now() <= SKEW_MS
+
+    /**
+     * 阻塞地给出一个当下可用的访问令牌；临近过期时先走一次单飞刷新。
+     * 供 OkHttp 的 tokenProvider 与 WS 握手使用（每次重连都会重新读）。
+     *
+     * 刷新失败时**仍然返回手里那份令牌**——它可能还没真的过期，401 交给兜底路径处理；
+     * 在这里返回 null 会让整条请求链断掉，比让服务端来裁决更糟。
+     */
+    fun ensureToken(): String? {
+        val session = store.load()
+        val token = session.token?.takeIf(String::isNotBlank) ?: return null
+        if (!isNearExpiry(session)) return token
+        return when (val recovery = renew(token)) {
+            is AuthRecovery.Renewed -> recovery.token
+            AuthRecovery.Unrecoverable, AuthRecovery.Transient -> token
+        }
+    }
+
+    /**
+     * 单飞刷新：同一时刻只有一个线程真正发请求，其余线程在锁上等待并复用结果。
+     *
+     * @param staleToken 触发续期的那次请求实际携带的令牌；null 表示只知道「手上没有可用的令牌」。
+     */
+    fun renew(staleToken: String?): AuthRecovery = synchronized(lock) {
+        val session = store.load()
+
+        // 代际守卫：等在锁上的这段时间里，别的线程已经换好了令牌 → 复用，绝不用同一个 refresh token 打第二次。
+        val current = session.token
+        if (!current.isNullOrBlank() && current != staleToken && !isNearExpiry(session)) {
+            return@synchronized AuthRecovery.Renewed(current)
+        }
+
+        val refreshToken = session.refreshToken?.takeIf(String::isNotBlank)
+            ?: return@synchronized AuthRecovery.Unrecoverable
+        if (refreshToken == rejectedRefreshToken) return@synchronized AuthRecovery.Unrecoverable
+
+        when (val result = call(refreshToken)) {
+            is RefreshCall.Ok -> {
+                rejectedRefreshToken = null
+                store.updateTokens(result.token, result.expiresAt, result.refreshToken)
+                AuthRecovery.Renewed(result.token)
+            }
+
+            RefreshCall.Rejected -> {
+                rejectedRefreshToken = refreshToken
+                AuthRecovery.Unrecoverable
+            }
+
+            RefreshCall.Failed -> AuthRecovery.Transient
+        }
+    }
+
+    private companion object {
+        /** 提前量：24h 的访问令牌留 60s 余量，避免踩着过期边界发请求。 */
+        const val SKEW_MS = 60_000L
+    }
+}

app/src/main/kotlin/top/yeij/cyrene/core/auth/UnauthorizedPolicy.kt

@@ -0,0 +1,29 @@
+package top.yeij.cyrene.core.auth
+
+/**
+ * 「带了令牌仍然 401」的处置策略。
+ *
+ * 由 `ApiClientFactory` 的拦截器在 **OkHttp 的调用线程上同步调用**，所以实现必须是
+ * 阻塞且线程安全的——那里没有 suspend 上下文，协程 `Mutex` 帮不上忙。
+ */
+interface UnauthorizedPolicy {
+
+    /**
+     * 尝试把被服务端拒绝的令牌换成可用的新令牌。
+     *
+     * @param usedToken 触发这次 401 的请求实际携带的访问令牌。
+     * @return [AuthRecovery.Renewed] 时调用方会用新令牌重试一次；另外两种都不重试。
+     */
+    fun renew(usedToken: String): AuthRecovery
+
+    /** 终态：续期不可能（没有 refresh token）或明确被拒（`invalid_grant`）——必须重新登录。 */
+    fun onSessionEnded()
+}
+
+/** 不带令牌的客户端（登录 / 刷新 / 登出）用：永不续期，也永不判终态。 */
+object NoUnauthorizedPolicy : UnauthorizedPolicy {
+
+    override fun renew(usedToken: String): AuthRecovery = AuthRecovery.Unrecoverable
+
+    override fun onSessionEnded() = Unit
+}

app/src/main/kotlin/top/yeij/cyrene/data/api/ApiClientFactory.kt

@@ -1,10 +1,14 @@
 package top.yeij.cyrene.data.api
 
 import top.yeij.cyrene.BuildConfig
+import top.yeij.cyrene.core.auth.AuthRecovery
+import top.yeij.cyrene.core.auth.NoUnauthorizedPolicy
+import top.yeij.cyrene.core.auth.UnauthorizedPolicy
 import kotlinx.serialization.json.Json
 import okhttp3.Interceptor
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.OkHttpClient
+import okhttp3.Request
 import okhttp3.Response
 import okhttp3.logging.HttpLoggingInterceptor
 import retrofit2.Retrofit
@@ -19,29 +23,31 @@ object ApiClientFactory {
         coerceInputValues = true
     }
 
-    /** 登录接口（不注入 token）。 */
+    /** 登录 / 刷新 / 登出接口（不注入 token、不参与续期）。 */
     fun create(
         baseUrl: String,
         tokenProvider: () -> String? = { null },
-        onUnauthorized: () -> Unit = {},
-    ): CyreneApi = create(baseUrl, CyreneApi::class.java, tokenProvider, onUnauthorized)
+        unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
+    ): CyreneApi = create(baseUrl, CyreneApi::class.java, tokenProvider, unauthorizedPolicy)
 
     /** 通用入口：按需构建任意 Retrofit service。 */
     fun <T : Any> create(
         baseUrl: String,
         service: Class<T>,
         tokenProvider: () -> String? = { null },
-        onUnauthorized: () -> Unit = {},
+        unauthorizedPolicy: UnauthorizedPolicy = NoUnauthorizedPolicy,
     ): T {
         val client = OkHttpClient.Builder()
             .connectTimeout(10, TimeUnit.SECONDS)
             .readTimeout(60, TimeUnit.SECONDS)
             .writeTimeout(60, TimeUnit.SECONDS)
-            .addInterceptor(HeaderInterceptor(tokenProvider, onUnauthorized))
+            .addInterceptor(AuthInterceptor(tokenProvider, unauthorizedPolicy))
             .apply {
                 if (BuildConfig.DEBUG) {
                     addInterceptor(
                         HttpLoggingInterceptor().apply {
+                            // BASIC 是上限：`/auth/refresh` 与 `/auth/logout` 把 refresh token 放在**请求体**里，
+                            // 再高一级就会把凭据打进 logcat。
                             level = HttpLoggingInterceptor.Level.BASIC
                             redactHeader("Authorization")
                         },
@@ -69,22 +75,48 @@ object ApiClientFactory {
         return url
     }
 
-    private class HeaderInterceptor(
+    /**
+     * 注入 `X-API-Version` 与 `Authorization`，并兜住「**带了令牌仍然** 401」：
+     * 先向策略要一次新令牌，拿到就用它**重试一次**；明确被拒才判终态。
+     *
+     * 为什么是应用层拦截器而不是 OkHttp `Authenticator`：
+     * `Authenticator` 对**任何** 401 都会被调用（包括不带令牌的登录请求），而且它由
+     * RetryAndFollowUp 在内部循环里驱动，重试次数（上限 20 次）不受本类控制——一个持续 401 的
+     * 令牌会打出一串刷新风暴。应用层拦截器只在带令牌时介入，且重试严格一次
+     * （OkHttp 允许应用层拦截器多次 `proceed()`，`calls != 1` 的检查只对网络拦截器生效）。
+     */
+    private class AuthInterceptor(
         private val tokenProvider: () -> String?,
-        private val onUnauthorized: () -> Unit,
+        private val unauthorizedPolicy: UnauthorizedPolicy,
     ) : Interceptor {
+
         override fun intercept(chain: Interceptor.Chain): Response {
             val token = tokenProvider()
-            val request = chain.request().newBuilder()
-                .header("X-API-Version", "1")
-                .apply { if (token != null) header("Authorization", "Bearer $token") }
-                .build()
-            val response = chain.proceed(request)
-            // 只有「带了 token 仍 401」才算会话过期；登录请求不带 token，不受影响。
-            if (response.code == 401 && token != null) {
-                onUnauthorized()
+            var response = chain.proceed(chain.request().withAuth(token))
+            // 只有「带了 token 仍 401」才算会话被拒；登录/刷新本身不带 token，不受影响。
+            if (response.code != HTTP_UNAUTHORIZED || token == null) return response
+
+            when (val recovery = unauthorizedPolicy.renew(token)) {
+                is AuthRecovery.Renewed -> {
+                    response.close()
+                    response = chain.proceed(chain.request().withAuth(recovery.token))
+                    // 换上刚签发的令牌仍然 401：服务端根本不接受这个账号，再刷也没有意义，判终态。
+                    if (response.code == HTTP_UNAUTHORIZED) unauthorizedPolicy.onSessionEnded()
+                }
+
+                AuthRecovery.Unrecoverable -> unauthorizedPolicy.onSessionEnded()
+
+                // 网络 / 5xx：会话可能还好着，原样把 401 交回去，绝不清会话。
+                AuthRecovery.Transient -> Unit
             }
             return response
         }
+
+        private fun Request.withAuth(token: String?): Request = newBuilder()
+            .header("X-API-Version", "1")
+            .apply { if (token != null) header("Authorization", "Bearer $token") }
+            .build()
     }
+
+    private const val HTTP_UNAUTHORIZED = 401
 }

app/src/main/kotlin/top/yeij/cyrene/data/api/CyreneApi.kt

@@ -2,6 +2,10 @@ package top.yeij.cyrene.data.api
 
 import top.yeij.cyrene.data.api.dto.LoginRequest
 import top.yeij.cyrene.data.api.dto.LoginResponse
+import top.yeij.cyrene.data.api.dto.LogoutRequest
+import top.yeij.cyrene.data.api.dto.LogoutResponse
+import top.yeij.cyrene.data.api.dto.RefreshRequest
+import top.yeij.cyrene.data.api.dto.RefreshResponse
 import retrofit2.Response
 import retrofit2.http.Body
 import retrofit2.http.POST
@@ -10,4 +14,10 @@ interface CyreneApi {
 
     @POST("api/v1/auth/login")
     suspend fun login(@Body body: LoginRequest): Response<ApiEnvelope<LoginResponse>>
+
+    @POST("api/v1/auth/refresh")
+    suspend fun refresh(@Body body: RefreshRequest): Response<ApiEnvelope<RefreshResponse>>
+
+    @POST("api/v1/auth/logout")
+    suspend fun logout(@Body body: LogoutRequest): Response<ApiEnvelope<LogoutResponse>>
 }

app/src/main/kotlin/top/yeij/cyrene/data/api/dto/LoginDto.kt

@@ -11,6 +11,49 @@ data class LoginRequest(
 @Serializable
 data class LoginResponse(
     val token: String,
+    /** **Unix 秒**（不是毫秒）：`time.Now().Add(24h).Unix()`。 */
     val expiresAt: Long,
     val role: String,
+    /** B2 的长期凭据；服务端没接线 refresh 存储时整个键缺失。 */
+    val refreshToken: String? = null,
+)
+
+/** `POST /api/v1/auth/refresh` 的请求体（公开接口，凭据就在请求体里）。 */
+@Serializable
+data class RefreshRequest(
+    val refreshToken: String,
+)
+
+/**
+ * `POST /api/v1/auth/refresh` 的成功载荷。
+ *
+ * - [refreshToken] 在默认（一次性轮换）模式下是**新的**凭据，旧的同一笔交易里作废；
+ *   `AUTH_REFRESH_ROTATE_DISABLED=true` 时服务端不下发，此时旧凭据继续有效——所以这里必须可空，
+ *   调用方也要在缺失时保留原值。
+ * - [role] 官方文档漏写，但实现一定会返回；给默认值以免文档形状的响应解不动。
+ */
+@Serializable
+data class RefreshResponse(
+    val token: String,
+    /** **Unix 秒**。 */
+    val expiresAt: Long,
+    val role: String = "",
+    val refreshToken: String? = null,
+)
+
+/** `POST /api/v1/auth/logout` 的请求体。 */
+@Serializable
+data class LogoutRequest(
+    val refreshToken: String,
+)
+
+/**
+ * `/auth/logout` 的响应体。文档与实现互相矛盾（`{"ok":true,"revokedCount":n}` / `{"revokedCount":n}`
+ * 对上真实信封里的 `{"revoked":bool}`），而本端**只看 HTTP 2xx**——所以每个字段都给默认值，
+ * 三种形状都能宽容解出，解不动也不影响登出。
+ */
+@Serializable
+data class LogoutResponse(
+    val revoked: Boolean = false,
+    val revokedCount: Int = 0,
 )

app/src/main/kotlin/top/yeij/cyrene/data/ws/ChatSocket.kt

@@ -1,5 +1,6 @@
 package top.yeij.cyrene.data.ws
 
+import top.yeij.cyrene.core.auth.AuthRecovery
 import top.yeij.cyrene.data.api.ApiClientFactory
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CompletableDeferred
@@ -49,19 +50,22 @@ import kotlin.random.Random
  * - OkHttp `pingInterval` 30s（服务端 ping 周期 54s / pong 等待 60s，客户端 30s 足够）。
  * - 服务端**没有 resume / 补发**：重连成功后由上层用新连接的 `history` 帧 + REST 补差去重。
  * - 退避 1s/2s/4s/8s/16s/30s（上限 30s，含抖动）。
- * - 握手返回 **HTTP 401** → [WsState.Offline]，触发 [onAuthFailed]，**不再重连**（需重新登录）。
+ * - 握手返回 **HTTP 401** → 先向 [onAuthRecover] 要一次续期（B2）：换到新令牌就**立刻重连一次**；
+ *   明确被拒或重连后仍 401 → [WsState.Offline] 并触发 [onAuthFailed]；暂时性失败走普通退避。
  *
  * ## 坏帧
  * 每帧解析都走 [WsEvent.parse]，非 JSON / 未知 `type` / 结构不匹配一律丢弃，不会中断连接。
  *
  * @param baseUrlProvider 服务器根地址（如 `http://host:8080`），每次重连时重新读取。
- * @param tokenProvider 当前 JWT，每次重连时重新读取（支持静默重登后复用同一实例）。
- * @param onAuthFailed 握手 401 回调；在协程内调用，注意切主线程。
+ * @param tokenProvider 当前 JWT，每次重连时重新读取（续期后无需重建实例）。
+ * @param onAuthRecover 握手 401 时的一次性兜底，见 [AuthRecovery]。
+ * @param onAuthFailed 终态回调（令牌被拒且无法续期）；在协程内调用，注意切主线程。
  * @param client 可注入自定义 OkHttpClient（会 `newBuilder` 派生，保留其拦截器）；缺省新建。
  */
 class ChatSocket(
     private val baseUrlProvider: () -> String?,
     private val tokenProvider: () -> String?,
+    private val onAuthRecover: () -> AuthRecovery = { AuthRecovery.Unrecoverable },
     private val onAuthFailed: () -> Unit = {},
     client: OkHttpClient? = null,
 ) {
@@ -104,6 +108,10 @@ class ChatSocket(
     @Volatile
     private var sessionJob: Job? = null
 
+    /** 本次 [connect] 是否已经用续期后的令牌重连过一次——避免握手 401 打成死循环。 */
+    @Volatile
+    private var authRetried: Boolean = false
+
     private var scope: CoroutineScope? = null
 
     /** 开始连接（幂等：已在连接 / 重连中时忽略）。 */
@@ -111,6 +119,7 @@ class ChatSocket(
         if (wantConnection) return
         wantConnection = true
         attempt = 0
+        authRetried = false
         sessionJob = ensureScope().launch { runConnectionLoop() }
     }
 
@@ -153,9 +162,7 @@ class ChatSocket(
                     }
 
                     SessionEnd.AuthFailed -> {
-                        wantConnection = false
-                        _state.value = WsState.Offline
-                        onAuthFailed()
+                        if (!recoverAuth()) break
                     }
 
                     SessionEnd.Closed -> {
@@ -171,6 +178,42 @@ class ChatSocket(
         }
     }
 
+    /**
+     * 握手被拒（HTTP 401）后的恢复（B2）：
+     * - [AuthRecovery.Renewed]：已换到新令牌，**立刻重连一次**（`tokenProvider` 每次重连都会重新读）；
+     * - [AuthRecovery.Unrecoverable]：令牌被服务端拒绝且无法续期 → 终态，触发 [onAuthFailed]；
+     * - [AuthRecovery.Transient]：暂时续不上（网络 / 5xx），会话保留，走普通退避重连。
+     *
+     * @return 连接循环是否继续。
+     */
+    private suspend fun recoverAuth(): Boolean {
+        if (authRetried) return endWithAuthFailure()
+        return when (onAuthRecover()) {
+            is AuthRecovery.Renewed -> {
+                authRetried = true
+                attempt = 0
+                _state.value = WsState.Reconnecting
+                true
+            }
+
+            AuthRecovery.Transient -> {
+                _state.value = WsState.Reconnecting
+                delay(backoffDelayMs(attempt))
+                attempt += 1
+                true
+            }
+
+            AuthRecovery.Unrecoverable -> endWithAuthFailure()
+        }
+    }
+
+    private fun endWithAuthFailure(): Boolean {
+        wantConnection = false
+        _state.value = WsState.Offline
+        onAuthFailed()
+        return false
+    }
+
     /** 建立一次连接并挂起，直到它关闭 / 失败 / 被取消。 */
     private suspend fun runSession(): SessionEnd {
         val url = buildUrl() ?: return SessionEnd.ConfigMissing