feat: add refresh token rotation flow

docs/technical/AUTH_REFRESH_ROTATION_DESIGN_2026-04-21.md

@@ -0,0 +1,205 @@
+# `/api/auth/refresh` 轮换落地设计
+
+日期：`2026-04-21`
+
+## 1. 文档目的
+
+这份文档用于指导 `M2` 中 `实现 refresh token 轮换` 任务的首版落地，冻结：
+
+1. `POST /api/auth/refresh` 的请求与响应 contract。
+2. refresh cookie、服务端 refresh session 与 access token 三者的职责边界。
+3. “会话 ID 稳定、refresh token 可轮换”的固定语义。
+4. Rust 首版在未切入 SpacetimeDB 前的临时进程内实现方式。
+
+## 2. 当前基线
+
+当前 Node `/api/auth/refresh` 已具备以下稳定语义：
+
+1. 从 HttpOnly cookie 中读取原始 refresh token。
+2. 服务端只按 `refresh_token_hash` 查找当前活跃会话。
+3. refresh 成功后，不新建第二条会话，而是在原会话上轮换 refresh token。
+4. 轮换时会更新 `expires_at` 与 `last_seen_at`。
+5. 成功后返回新的 access token，并写回新的 refresh cookie。
+6. 失败时会主动清空 refresh cookie，要求前端重新登录。
+
+Rust 首版必须保留以上语义。
+
+## 3. 当前阶段范围
+
+本阶段只落以下内容：
+
+1. `module-auth` 增加进程内 refresh session 真相与轮换服务。
+2. `api-server` 暴露 `POST /api/auth/refresh`。
+3. 登录成功时创建 refresh session。
+4. refresh 成功时在原 session 上轮换 refresh token。
+5. access token 的 `sid` 固定改为稳定 `session_id`，不再直接复用 refresh token。
+
+本阶段不包含：
+
+1. `/api/auth/logout`
+2. `/api/auth/logout-all`
+3. `/api/auth/sessions`
+4. `/api/auth/sessions/:sessionId/revoke`
+5. SpacetimeDB reducer 真正写表
+
+## 4. contract
+
+### 4.1 请求
+
+1. 方法：`POST`
+2. 路径：`/api/auth/refresh`
+3. 请求体：空
+4. 鉴权来源：refresh cookie
+
+### 4.2 成功响应
+
+```json
+{
+  "token": "<access-token>"
+}
+```
+
+同时响应头必须写回新的 refresh cookie。
+
+### 4.3 失败响应
+
+当 refresh token 缺失、会话不存在、会话已过期或用户不存在时：
+
+1. 返回 `401 UNAUTHORIZED`
+2. 同时清理 refresh cookie
+
+## 5. 固定语义
+
+### 5.1 session_id 与 refresh token 必须拆开
+
+从本任务开始固定以下规则：
+
+1. `session_id` 是稳定会话主键。
+2. refresh token 是可轮换的会话凭证。
+3. access token 的 `sid` 必须写入 `session_id`。
+4. refresh 轮换只更新 refresh token，不更改 `session_id`。
+
+禁止继续把 refresh token 直接塞进 JWT `sid`。
+
+### 5.2 refresh 是“原会话轮换”
+
+refresh 成功后：
+
+1. 保留原 `session_id`
+2. 生成新的原始 refresh token
+3. 用新的 `refresh_token_hash` 覆盖旧值
+4. 更新 `expires_at`
+5. 更新 `last_seen_at`
+
+不允许新建第二条 session。
+
+## 6. crate 边界
+
+### 6.1 `module-auth`
+
+负责：
+
+1. 管理 refresh session 进程内真相。
+2. 提供创建 refresh session 与轮换 refresh session 的用例。
+3. 提供按 `user_id` 查询用户快照的能力，供 refresh 成功后重新签发 access token。
+
+不负责：
+
+1. 生成原始 refresh token。
+2. 读写 cookie。
+3. 签发 JWT。
+
+### 6.2 `platform-auth`
+
+负责：
+
+1. 生成原始 refresh token。
+2. 对 refresh token 做哈希。
+3. 构造 refresh cookie 的 `Set-Cookie` 头。
+4. 从 cookie header 中读取 refresh token。
+
+### 6.3 `api-server`
+
+负责：
+
+1. 从请求 cookie 中提取 refresh token。
+2. 调用 `module-auth` 执行 refresh session 轮换。
+3. 根据用户快照与稳定 `session_id` 重新签发 access token。
+4. refresh 失败时清理 cookie。
+
+## 7. 进程内存储模型
+
+当前阶段 `module-auth` 继续使用进程内内存仓储承接 refresh session，字段至少包括：
+
+1. `session_id`
+2. `user_id`
+3. `refresh_token_hash`
+4. `issued_by_provider`
+5. `expires_at`
+6. `created_at`
+7. `updated_at`
+8. `last_seen_at`
+9. `revoked_at`
+
+说明：
+
+1. 这只是 SpacetimeDB 正式落地前的阶段性实现。
+2. 字段命名与语义继续对齐 [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)。
+
+## 8. 流程
+
+### 8.1 登录创建 session
+
+密码登录成功后：
+
+1. `api-server` 生成原始 refresh token。
+2. `api-server` 计算 `refresh_token_hash`。
+3. `module-auth` 创建一条新 session，并返回稳定 `session_id`。
+4. `api-server` 用该 `session_id` 写入 access token 的 `sid`。
+5. `api-server` 把原始 refresh token 写回 cookie。
+
+### 8.2 refresh 轮换 session
+
+当请求 `POST /api/auth/refresh` 时：
+
+1. 从 cookie 中读取原始 refresh token。
+2. 计算 `refresh_token_hash`。
+3. `module-auth` 查找当前活跃 session。
+4. 校验 `expires_at > now` 且 `revoked_at == null`。
+5. 读取该 session 对应用户。
+6. 生成新的原始 refresh token。
+7. 用新 hash 更新同一条 session。
+8. 返回新的 access token 与新的 refresh cookie。
+
+## 9. 错误语义
+
+以下情况统一返回 `401`：
+
+1. 缺少 refresh cookie
+2. refresh token 命中不到 session
+3. refresh session 已过期
+4. refresh session 已吊销
+5. session 对应用户不存在
+
+错误文案统一保持中文，并沿用“当前登录态已失效，请重新登录”这类恢复导向语义。
+
+## 10. 测试策略
+
+至少覆盖：
+
+1. 登录成功后可用 cookie 调用 `/api/auth/refresh`
+2. refresh 成功会写回新的 cookie
+3. refresh 成功返回新的 access token
+4. refresh 后旧 refresh token 立即失效
+5. 缺少 cookie 时返回 `401`
+6. 无效 refresh token 时返回 `401` 且清理 cookie
+
+## 11. 完成定义
+
+满足以下条件时，本任务视为完成：
+
+1. Rust 侧已提供 `POST /api/auth/refresh`。
+2. access token `sid` 已改为稳定 `session_id`。
+3. refresh token 轮换成功时不创建新会话。
+4. refresh 失败时会清理 cookie。
+5. 文档、任务清单与测试已同步更新。