206 lines
5.6 KiB
Markdown
206 lines
5.6 KiB
Markdown
# `/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. 文档、任务清单与测试已同步更新。
|