Genarrative/docs/technical/AUTH_REFRESH_ROTATION_DESIGN_2026-04-21.md

/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 成功响应

{
  "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。

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. 文档、任务清单与测试已同步更新。