docs: design auth refresh session table
This commit is contained in:
@@ -4,6 +4,7 @@
|
||||
|
||||
## 文档列表
|
||||
|
||||
- [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)：`M2` 第三张会话表 `refresh_session` 的 cookie/hash 边界、轮换与吊销语义、索引与迁移规则。
|
||||
- [SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md)：`M2` 第二张身份表 `auth_identity` 的 provider 范围、唯一约束、手机号/微信身份写入规则与迁移策略。
|
||||
- [SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)：`M2` 第一张身份主表 `user_account` 的职责边界、字段、唯一约束、状态迁移、旧 `users` 映射与落地约束。
|
||||
- [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)：基于当前 Node 后端能力清单，设计用 `SpacetimeDB + Axum + 阿里云 OSS` 重写后端的目标架构、模块映射、数据分层、迁移顺序与验收标准。
|
||||
|
||||
@@ -314,6 +314,10 @@ server-rs/
|
||||
|
||||
- [SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md)
|
||||
|
||||
`refresh_session` 的 cookie/hash 边界、轮换与吊销语义，见：
|
||||
|
||||
- [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)
|
||||
|
||||
### B. 运行时主状态表
|
||||
|
||||
- `runtime_snapshot`
|
||||
|
||||
@@ -0,0 +1,388 @@
|
||||
# `refresh_session` 表设计
|
||||
|
||||
日期：`2026-04-21`
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份文档用于完成 `M2` 的第三条任务：`设计 refresh_session`。
|
||||
|
||||
目标是把以下几件事固定到可编码级别：
|
||||
|
||||
1. refresh cookie 与服务端 session 表的边界
|
||||
2. `refresh`、`logout`、`logout-all`、`sessions/:sessionId/revoke` 的失效语义
|
||||
3. `refresh_session` 与 `user_account.token_version` 的职责切分
|
||||
4. 会话列表、当前设备识别、轮换与吊销的数据结构
|
||||
|
||||
## 2. 当前基线
|
||||
|
||||
当前 Node 后端已经存在一张 `user_sessions` 表，并且 refresh cookie 主链已经完整可用：
|
||||
|
||||
1. 登录成功后创建随机 refresh token，并只把原始 token 放入 HttpOnly cookie
|
||||
2. 服务端只存 `sha256(refresh_token)` 结果
|
||||
3. `/api/auth/refresh` 会轮换 refresh token，同时更新过期时间与 `last_seen_at`
|
||||
4. `/api/auth/logout` 会吊销当前 refresh session，并提升 `token_version`
|
||||
5. `/api/auth/logout-all` 会吊销当前账号全部 refresh session，并提升 `token_version`
|
||||
6. `/api/auth/sessions` 依赖会话表列出当前设备与远端设备
|
||||
7. `/api/auth/sessions/:sessionId/revoke` 只吊销目标设备，不影响当前设备
|
||||
|
||||
当前 Node `user_sessions` 字段基线：
|
||||
|
||||
1. `id`
|
||||
2. `user_id`
|
||||
3. `refresh_token_hash`
|
||||
4. `client_type`
|
||||
5. `user_agent`
|
||||
6. `ip`
|
||||
7. `expires_at`
|
||||
8. `revoked_at`
|
||||
9. `created_at`
|
||||
10. `updated_at`
|
||||
11. `last_seen_at`
|
||||
|
||||
这说明：
|
||||
|
||||
1. refresh session 已经是现有系统的既有真相源。
|
||||
2. Rust 重写时不需要重新发明另一套“session cache + cookie state”双轨模型。
|
||||
3. 只需要把当前语义更明确地迁入 SpacetimeDB，并把与 `user_account` 的职责切开。
|
||||
|
||||
## 3. 边界定义
|
||||
|
||||
### 3.1 `refresh_session` 负责
|
||||
|
||||
1. 设备级 refresh token hash 真相
|
||||
2. 设备级过期时间
|
||||
3. 设备级吊销状态
|
||||
4. 设备级最后活跃时间
|
||||
5. 会话列表所需的客户端信息
|
||||
|
||||
### 3.2 它不负责
|
||||
|
||||
1. access token 签发
|
||||
2. access token 全局失效版本号
|
||||
3. 用户主状态
|
||||
4. provider 身份绑定
|
||||
5. 短信验证码与微信 OAuth
|
||||
|
||||
### 3.3 与 `user_account` 的职责切分
|
||||
|
||||
固定规则：
|
||||
|
||||
1. `refresh_session` 负责“哪台设备还能继续 refresh”
|
||||
2. `user_account.token_version` 负责“旧 access token 是否整体失效”
|
||||
|
||||
因此：
|
||||
|
||||
1. `logout` 必须同时改两层
|
||||
2. `logout-all` 必须同时改两层
|
||||
3. `sessions/:sessionId/revoke` 只改 `refresh_session`
|
||||
4. `/refresh` 只改 `refresh_session`，不改 `token_version`
|
||||
|
||||
## 4. cookie 与表的边界
|
||||
|
||||
### 4.1 cookie 只存原始 token
|
||||
|
||||
浏览器侧固定继续存：
|
||||
|
||||
1. cookie 名：`genarrative_refresh_session`
|
||||
2. 值：原始 refresh token
|
||||
3. `HttpOnly`
|
||||
4. `Path=/api/auth`
|
||||
5. 默认 `SameSite=Lax`
|
||||
6. 生产环境按配置决定 `Secure`
|
||||
|
||||
### 4.2 表里只存 hash
|
||||
|
||||
`refresh_session` 固定只存：
|
||||
|
||||
1. `sha256(refresh_token)`
|
||||
|
||||
禁止：
|
||||
|
||||
1. 把原始 refresh token 落库
|
||||
2. 把原始 refresh token 写日志
|
||||
3. 把 cookie 配置字段冗余进表结构
|
||||
|
||||
### 4.3 当前设备识别方式
|
||||
|
||||
`/api/auth/sessions` 的 `isCurrent` 固定按以下规则判断：
|
||||
|
||||
1. 从 cookie 读出原始 refresh token
|
||||
2. 计算 hash
|
||||
3. 与 `refresh_session.refresh_token_hash` 比较
|
||||
|
||||
## 5. 表访问级别
|
||||
|
||||
`refresh_session` 固定为 `private table`。
|
||||
|
||||
原因：
|
||||
|
||||
1. 包含 refresh token hash
|
||||
2. 包含客户端 UA 与 IP
|
||||
3. 包含设备级会话状态
|
||||
|
||||
前端不直接查询该表，只能通过 Axum / view 聚合后的 DTO 读取。
|
||||
|
||||
## 6. 字段设计
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `session_id` | `String` | 是 | 主键，建议继续沿用 `usess_*` 前缀。 |
|
||||
| `user_id` | `String` | 是 | 归属账号 ID，外键指向 `user_account.user_id`。 |
|
||||
| `refresh_token_hash` | `String` | 是 | 当前生效 refresh token 的哈希值。 |
|
||||
| `client_type` | `String` | 是 | 当前设备类型，当前阶段默认 `browser`。 |
|
||||
| `user_agent` | `Option<String>` | 否 | 请求头中的 `User-Agent` 原文。 |
|
||||
| `ip` | `Option<String>` | 否 | 会话创建时采集的客户端 IP。 |
|
||||
| `issued_by_provider` | `String` | 是 | 该会话是由哪种登录链路创建，枚举固定为 `password`、`phone`、`wechat`。 |
|
||||
| `expires_at` | `String` | 是 | 当前 refresh token 过期时间，UTC RFC3339。 |
|
||||
| `revoked_at` | `Option<String>` | 否 | 会话被吊销的时间。 |
|
||||
| `revoked_reason_code` | `Option<String>` | 否 | 吊销原因码，例如 `logout`、`logout_all`、`session_revoke`、`account_disabled`。 |
|
||||
| `created_at` | `String` | 是 | 会话首次创建时间。 |
|
||||
| `updated_at` | `String` | 是 | 最近一次会话状态变更时间。 |
|
||||
| `last_seen_at` | `String` | 是 | 最近一次 refresh 成功或创建时的活跃时间。 |
|
||||
|
||||
补充说明：
|
||||
|
||||
1. 当前阶段时间字段统一继续使用 UTC RFC3339 字符串。
|
||||
2. `session_id` 在 refresh 轮换时保持不变，不创建新会话行。
|
||||
3. `issued_by_provider` 不是为了做 provider 身份表，而是为了后续账号安全页和审计展示保留稳定字段。
|
||||
|
||||
## 7. 唯一约束与索引
|
||||
|
||||
### 7.1 必须具备的唯一约束
|
||||
|
||||
1. `session_id` 主键唯一
|
||||
2. `refresh_token_hash` 全局唯一
|
||||
|
||||
### 7.2 必须具备的查询索引
|
||||
|
||||
1. `(user_id, revoked_at, expires_at, last_seen_at DESC)`
|
||||
作用：列当前账号活跃会话
|
||||
2. `(user_id, session_id)`
|
||||
作用：按用户吊销指定会话
|
||||
3. `(expires_at, revoked_at)`
|
||||
作用：后续清理过期/已吊销会话
|
||||
4. `refresh_token_hash`
|
||||
作用：refresh、logout、current session 判断
|
||||
|
||||
## 8. 生命周期设计
|
||||
|
||||
### 8.1 创建
|
||||
|
||||
触发点：
|
||||
|
||||
1. 密码登录成功
|
||||
2. 手机号登录成功
|
||||
3. 微信登录成功
|
||||
4. 微信绑定手机号成功后签发正式会话
|
||||
|
||||
写入规则：
|
||||
|
||||
1. 生成原始 refresh token
|
||||
2. 计算 `refresh_token_hash`
|
||||
3. 创建一条新 `refresh_session`
|
||||
4. `last_seen_at = created_at`
|
||||
|
||||
### 8.2 刷新
|
||||
|
||||
触发点：
|
||||
|
||||
1. `POST /api/auth/refresh`
|
||||
|
||||
写入规则：
|
||||
|
||||
1. 先按 `refresh_token_hash` 找当前 session
|
||||
2. 校验 `revoked_at == null`
|
||||
3. 校验 `expires_at > now`
|
||||
4. 生成新的 refresh token
|
||||
5. 更新同一条 session 的 `refresh_token_hash`
|
||||
6. 更新 `expires_at`
|
||||
7. 更新 `last_seen_at`
|
||||
8. 更新 `updated_at`
|
||||
|
||||
关键约束：
|
||||
|
||||
1. refresh 是“同一会话轮换”，不是“新建第二条会话”。
|
||||
2. `session_id` 在轮换前后必须稳定，保证会话列表中的设备 ID 不跳变。
|
||||
|
||||
### 8.3 吊销当前会话
|
||||
|
||||
触发点：
|
||||
|
||||
1. `POST /api/auth/logout`
|
||||
|
||||
写入规则：
|
||||
|
||||
1. 按当前 cookie 找 session
|
||||
2. 写 `revoked_at = now`
|
||||
3. 写 `revoked_reason_code = logout`
|
||||
4. 同时提升 `user_account.token_version`
|
||||
|
||||
### 8.4 吊销全部会话
|
||||
|
||||
触发点：
|
||||
|
||||
1. `POST /api/auth/logout-all`
|
||||
|
||||
写入规则：
|
||||
|
||||
1. 按 `user_id` 批量吊销全部未吊销 session
|
||||
2. `revoked_reason_code = logout_all`
|
||||
3. 同时提升 `user_account.token_version`
|
||||
|
||||
### 8.5 吊销指定远端设备
|
||||
|
||||
触发点：
|
||||
|
||||
1. `POST /api/auth/sessions/:sessionId/revoke`
|
||||
|
||||
写入规则：
|
||||
|
||||
1. 只允许吊销同一 `user_id` 下的目标 session
|
||||
2. 当前设备不允许通过该接口吊销自己
|
||||
3. 只改目标 `refresh_session`
|
||||
4. `revoked_reason_code = session_revoke`
|
||||
5. 不提升 `token_version`
|
||||
|
||||
### 8.6 账号被禁用或并入
|
||||
|
||||
触发点：
|
||||
|
||||
1. `user_account.account_status = disabled`
|
||||
|
||||
写入规则：
|
||||
|
||||
1. 该账号下所有未吊销 session 都必须被批量吊销
|
||||
2. `revoked_reason_code = account_disabled`
|
||||
|
||||
## 9. 活跃态判断规则
|
||||
|
||||
一条 `refresh_session` 只有同时满足以下条件，才视为活跃：
|
||||
|
||||
1. `revoked_at = null`
|
||||
2. `expires_at > now`
|
||||
3. 所属 `user_account.account_status = active` 或允许 refresh 的待绑定状态
|
||||
|
||||
补充约束：
|
||||
|
||||
1. 当前阶段 `pending_bind_phone` 的微信壳账号允许 refresh，但只允许继续走绑定手机号相关接口。
|
||||
2. `disabled` 账号无论 session 本身是否过期，都不能继续 refresh。
|
||||
|
||||
## 10. 与现有接口的映射
|
||||
|
||||
### 10.1 `POST /api/auth/refresh`
|
||||
|
||||
依赖：
|
||||
|
||||
1. `refresh_session.refresh_token_hash`
|
||||
2. `refresh_session.expires_at`
|
||||
3. `refresh_session.revoked_at`
|
||||
4. `user_account.account_status`
|
||||
5. `user_account.token_version`
|
||||
|
||||
### 10.2 `GET /api/auth/sessions`
|
||||
|
||||
直接读取：
|
||||
|
||||
1. `session_id`
|
||||
2. `client_type`
|
||||
3. `user_agent`
|
||||
4. `ip`
|
||||
5. `created_at`
|
||||
6. `last_seen_at`
|
||||
7. `expires_at`
|
||||
|
||||
前端 DTO `clientLabel`、`ipMasked`、`isCurrent` 继续在 Axum 侧派生。
|
||||
|
||||
### 10.3 `POST /api/auth/logout`
|
||||
|
||||
依赖：
|
||||
|
||||
1. 当前 cookie 命中的 `refresh_session`
|
||||
2. `user_account.token_version`
|
||||
|
||||
### 10.4 `POST /api/auth/logout-all`
|
||||
|
||||
依赖：
|
||||
|
||||
1. 当前 `user_id` 下全部活跃 `refresh_session`
|
||||
2. `user_account.token_version`
|
||||
|
||||
## 11. 与当前 Node `user_sessions` 的映射关系
|
||||
|
||||
| Node `user_sessions` 列 | 新 `refresh_session` 字段 | 迁移规则 |
|
||||
| --- | --- | --- |
|
||||
| `id` | `session_id` | 原样迁移。 |
|
||||
| `user_id` | `user_id` | 原样迁移。 |
|
||||
| `refresh_token_hash` | `refresh_token_hash` | 原样迁移。 |
|
||||
| `client_type` | `client_type` | 原样迁移。 |
|
||||
| `user_agent` | `user_agent` | 原样迁移。 |
|
||||
| `ip` | `ip` | 原样迁移。 |
|
||||
| `expires_at` | `expires_at` | 原样迁移。 |
|
||||
| `revoked_at` | `revoked_at` | 原样迁移。 |
|
||||
| `created_at` | `created_at` | 原样迁移。 |
|
||||
| `updated_at` | `updated_at` | 原样迁移。 |
|
||||
| `last_seen_at` | `last_seen_at` | 原样迁移。 |
|
||||
|
||||
新增字段回填规则：
|
||||
|
||||
1. `issued_by_provider`
|
||||
初次迁移统一回填为 `password`
|
||||
说明：这是保守回填值，后续只影响展示，不影响鉴权正确性
|
||||
2. `revoked_reason_code`
|
||||
初次迁移统一回填为 `null`
|
||||
|
||||
## 12. reducer / service 落地约束
|
||||
|
||||
### 12.1 `module-auth` reducer 层
|
||||
|
||||
必须至少具备这些命令入口：
|
||||
|
||||
1. `create_refresh_session`
|
||||
2. `rotate_refresh_session`
|
||||
3. `revoke_refresh_session`
|
||||
4. `revoke_refresh_sessions_by_user`
|
||||
5. `revoke_refresh_session_by_user_and_session`
|
||||
6. `touch_refresh_session_last_seen`
|
||||
|
||||
### 12.2 Axum 应用层
|
||||
|
||||
固定负责：
|
||||
|
||||
1. 生成原始 refresh token
|
||||
2. 计算 hash
|
||||
3. 读写 HttpOnly cookie
|
||||
4. 决定当前调用是创建、轮换还是吊销
|
||||
5. 把 `revoked_reason_code` 映射到对应业务语义
|
||||
|
||||
## 13. 不允许的设计漂移
|
||||
|
||||
后续实现时禁止出现以下情况：
|
||||
|
||||
1. refresh 轮换时新建第二条 session，而不是更新原 session
|
||||
2. `sessions/:sessionId/revoke` 顺手提升 `token_version`，导致当前 access token 一起失效
|
||||
3. `logout-all` 只提升 `token_version`，却不吊销 refresh session
|
||||
4. 原始 refresh token 直接入库
|
||||
5. 会话表开始承担 `user_account` 状态职责
|
||||
|
||||
## 14. 本任务完成定义
|
||||
|
||||
当以下条件满足时，`设计 refresh_session` 视为完成：
|
||||
|
||||
1. refresh cookie 与服务端 session hash 的边界已经明确。
|
||||
2. 轮换、当前设备吊销、全部设备吊销三种语义已经切开。
|
||||
3. `refresh_session` 与 `user_account.token_version` 的职责已明确。
|
||||
4. 字段、唯一约束、索引与迁移规则已具体到可直接编码。
|
||||
|
||||
## 15. 依据文件
|
||||
|
||||
1. `server-node/src/routes/authRoutes.ts`
|
||||
2. `server-node/src/auth/authService.ts`
|
||||
3. `server-node/src/auth/refreshSessionCookie.ts`
|
||||
4. `server-node/src/repositories/userSessionRepository.ts`
|
||||
5. `server-node/src/config.ts`
|
||||
6. `server-node/src/db/migrations.ts`
|
||||
7. `server-node/src/app.test.ts`
|
||||
8. `docs/prd/ACCOUNT_SYSTEM_AND_LOGIN_ENTRY_PRD_2026-04-09.md`
|
||||
9. `docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md`
|
||||
10. `docs/technical/SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md`
|
||||
11. `docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md`
|
||||
Reference in New Issue
Block a user