GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

feat: add multi-device session identity

Browse Source
This commit is contained in:
kdletters
2026-04-21 16:25:45 +08:00
parent a83c64133d
commit fcaf7bdb38
13 changed files with 1445 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,184 @@
# `/api/auth/sessions` 会话列表与多端标识查询设计
日期：`2026-04-21`
## 1. 文档目的
这份文档用于指导 `M2` 中 `兼容 /api/auth/sessions` 的首版落地，冻结：
1. `GET /api/auth/sessions` 的请求与响应 contract
2. 当前设备识别方式与 `isCurrent` 语义
3. 多端登录识别字段如何从 `refresh_session` 派生到 DTO
4. Rust 首版在 Axum + 进程内 `module-auth` 下的最小实现边界
## 2. 当前基线
当前 Node `/api/auth/sessions` 已具备以下稳定行为：
1. 依赖 Bearer JWT 确认用户身份
2. 从 refresh cookie 识别当前设备
3. 返回当前账号全部未吊销活跃会话
4. 每条记录给出端侧标签、最近活跃时间、到期时间、IP 脱敏信息与是否当前设备
当前问题是：
1. 旧实现只能粗略给出“网页端浏览器 / 移动端浏览器”
2. 无法稳定区分同设备不同浏览器
3. 无法区分微信内 H5 与微信小程序、小程序平台来源
因此本次 `/api/auth/sessions` 首版落地必须直接承接多端会话身份模型。
## 3. 设计输入
本任务直接受以下文档约束：
1. [MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md](./MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md)
2. [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)
3. [AUTH_REFRESH_ROTATION_DESIGN_2026-04-21.md](./AUTH_REFRESH_ROTATION_DESIGN_2026-04-21.md)
4. [AUTH_LOGOUT_CURRENT_SESSION_DESIGN_2026-04-21.md](./AUTH_LOGOUT_CURRENT_SESSION_DESIGN_2026-04-21.md)
## 4. 首版落地范围
本阶段只落以下内容：
1. `module-auth` 提供按 `user_id` 读取活跃 refresh session 列表的能力
2. `api-server` 暴露 `GET /api/auth/sessions`
3. 登录创建 session 时落库结构化客户端身份字段
4. 会话列表返回多端识别所需字段，并兼容旧 `clientLabel`
本阶段明确不包含：
1. `/api/auth/sessions/:sessionId/revoke`
2. 前端完整消费全部新增字段
3. SpacetimeDB reducer / view 正式读表
## 5. 请求与响应 contract
### 5.1 请求
1. 方法：`GET`
2. 路径：`/api/auth/sessions`
3. 请求体：空
4. 鉴权：
- Bearer JWT 必填
- refresh cookie 选填但建议携带，用于判断 `isCurrent`
### 5.2 成功响应
```json
{
"sessions": [
{
"sessionId": "usess_xxx",
"clientType": "web_browser",
"clientRuntime": "chrome",
"clientPlatform": "windows",
"clientLabel": "Windows / Chrome",
"deviceDisplayName": "Windows / Chrome",
"miniProgramAppId": null,
"miniProgramEnv": null,
"userAgent": "Mozilla/5.0 ...",
"ipMasked": "203.0.*.*",
"isCurrent": true,
"createdAt": "2026-04-21T10:00:00Z",
"lastSeenAt": "2026-04-21T10:05:00Z",
"expiresAt": "2026-05-21T10:00:00Z"
}
]
}
```
字段说明：
1. `clientLabel` 当前阶段继续兼容旧前端字段，值固定与 `deviceDisplayName` 保持一致
2. `clientRuntime`、`clientPlatform`、`deviceDisplayName` 是多端识别首版最小新增字段
3. 小程序来源额外暴露 `miniProgramAppId`、`miniProgramEnv`
### 5.3 失败响应
以下情况返回 `401 UNAUTHORIZED`：
1. Bearer JWT 缺失或非法
2. Bearer JWT 对应用户不存在
仓储读取失败返回 `500 INTERNAL_SERVER_ERROR`。
## 6. 当前设备识别规则
`isCurrent` 固定按以下规则判断：
1. 从 refresh cookie 读取当前原始 refresh token
2. 在 Axum 侧计算 `sha256(refresh_token)`
3. 与会话列表中的 `refresh_token_hash` 比较
4. 命中则 `isCurrent = true`
说明：
1. 如果请求没有携带 refresh cookie，本接口仍可返回会话列表
2. 此时全部会话的 `isCurrent` 都为 `false`
## 7. 多端标识派生规则
### 7.1 后端入库字段
登录创建会话时，Axum 必须先解析并写入：
1. `client_type`
2. `client_runtime`
3. `client_platform`
4. `client_instance_id`
5. `device_fingerprint`
6. `device_display_name`
7. `mini_program_app_id`
8. `mini_program_env`
9. `user_agent`
10. `ip`
### 7.2 DTO 派生规则
会话列表返回时：
1. `clientType = client_type`
2. `clientRuntime = client_runtime`
3. `clientPlatform = client_platform`
4. `deviceDisplayName = device_display_name`
5. `clientLabel = device_display_name`
6. `miniProgramAppId = mini_program_app_id`
7. `miniProgramEnv = mini_program_env`
## 8. crate 边界
### 8.1 `module-auth`
负责：
1. 保存 refresh session 客户端身份快照
2. 按 `user_id` 返回活跃会话列表
3. 保持 refresh 轮换后 `session_id` 稳定、客户端身份字段不漂移
### 8.2 `api-server`
负责：
1. 读取 Bearer JWT 与 refresh cookie
2. 把活跃会话映射成旧接口兼容 DTO
3. 派生 `ipMasked` 与 `isCurrent`
## 9. 测试策略
至少覆盖：
1. 同一账号在同平台不同浏览器登录后，会话列表能返回两条不同运行时记录
2. 微信内 H5 登录后，会话列表返回 `wechat_h5 + wechat_embedded_browser`
3. 显式小程序头优先于 `User-Agent` 判断
4. 请求携带当前 refresh cookie 时，只有当前会话 `isCurrent = true`
## 10. 完成定义
满足以下条件时，本任务视为完成：
1. Rust 侧已提供 `GET /api/auth/sessions`
2. 会话列表可区分普通浏览器、微信内 H5、小程序来源
3. 同设备不同浏览器可在会话列表中清晰区分
4. `clientLabel` 与新增多端字段都已稳定返回
5. 文档、任务清单与测试已同步更新

309
docs/technical/MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md Normal file
View File

@@ -0,0 +1,309 @@
# 多端登录会话身份模型设计
日期：`2026-04-21`
## 1. 文档目的
这份文档用于补齐当前鉴权体系中“多端登录识别”能力的落地设计，目标是让后端能够稳定标识：
1. 不同设备上的浏览器登录
2. 同一设备上的不同浏览器登录
3. 微信小程序、支付宝小程序、抖音小程序等小程序来源
4. 微信内 H5 与普通浏览器 H5 的差异
同时冻结：
1. `refresh_session` 需要新增的客户端身份字段
2. 前端与网关需要补传的上下文
3. Axum 派生展示名与“当前设备”标识的规则
4. 与后续 `/api/auth/sessions`、`/api/auth/sessions/:sessionId/revoke` 的契约关系
## 2. 当前问题
当前项目里“设备类型”只有最小占位语义：
1. Node `buildAuthRequestContext(...)` 直接写死 `clientType = "browser"`
2. `clientLabel` 只是按 `User-Agent` 粗略显示“移动端浏览器 / 网页端浏览器”
3. `refresh_session` / `user_sessions` 里没有区分运行时、小程序来源、浏览器实例与设备实例的结构化字段
这会导致：
1. 无法区分“同一台电脑上的 Chrome 和 Edge”
2. 无法稳定标记“微信小程序登录”和“微信内 H5 登录”
3. 无法给会话列表生成稳定、可读的端侧标签
## 3. 设计目标
新的会话客户端身份模型必须满足：
1. 会话列表能区分“设备”与“客户端运行时”
2. 同设备不同浏览器被视为不同登录端
3. 小程序来源可稳定区分到平台级别
4. 前端不需要拿到真实设备名称，也能展示稳定友好标签
5. 浏览器拿不到真实设备名时，系统仍能自动生成展示名
## 4. 基本原则
### 4.1 不追求真实设备名
浏览器端通常无法拿到：
1. 系统设置里的设备名称
2. 手机自定义名称
3. 电脑主机名
因此本设计不依赖真实设备名称，而是生成“会话展示名”。
### 4.2 会话识别拆三层
当前阶段统一拆为：
1. `client_type`
大类，例如浏览器、小程序、桌面客户端
2. `client_runtime`
具体运行时，例如 Chrome、Safari、微信小程序
3. `client_instance_id`
客户端实例 ID，用于区分“同设备不同浏览器”以及“同浏览器不同安装/清缓存”
### 4.3 展示名由后端派生
`device_display_name` 不直接信任前端自由文本，而由后端基于结构化字段派生，必要时允许前端提供候选值。
## 5. 字段模型
`refresh_session` 建议新增以下字段：
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `client_type` | `String` | 是 | 大类，见 6.1 |
| `client_runtime` | `String` | 是 | 运行时，见 6.2 |
| `client_platform` | `String` | 否 | 平台，如 `windows`、`macos`、`ios`、`android` |
| `client_instance_id` | `String` | 否 | 客户端实例 ID，由前端持久化生成 |
| `device_fingerprint` | `String` | 否 | 后端派生指纹，用于聚合同设备近似会话 |
| `device_display_name` | `String` | 是 | 给用户展示的设备/端侧名称 |
| `mini_program_app_id` | `Option<String>` | 否 | 小程序 appid |
| `mini_program_env` | `Option<String>` | 否 | 小程序环境，如 `develop`、`trial`、`release` |
| `user_agent` | `Option<String>` | 否 | 原始 UA |
| `ip` | `Option<String>` | 否 | 登录 IP |
说明：
1. `client_type` 和 `client_runtime` 是强约束字段，必须稳定可枚举。
2. `client_instance_id` 用于区分“同一台设备上的不同浏览器/不同安装实例”。
3. `device_fingerprint` 不是鉴权凭据，只用于会话展示聚类。
4. `device_display_name` 是最终展示字段。
## 6. 枚举定义
### 6.1 `client_type`
固定枚举：
1. `web_browser`
2. `wechat_h5`
3. `mini_program`
4. `native_app`
5. `desktop_app`
6. `unknown`
### 6.2 `client_runtime`
当前阶段固定允许：
1. `chrome`
2. `edge`
3. `safari`
4. `firefox`
5. `wechat_embedded_browser`
6. `wechat_mini_program`
7. `alipay_mini_program`
8. `douyin_mini_program`
9. `unknown`
后续如扩展，不改已有语义，只追加枚举。
### 6.3 `client_platform`
当前阶段固定允许：
1. `windows`
2. `macos`
3. `linux`
4. `ios`
5. `android`
6. `unknown`
## 7. 前端采集输入
### 7.1 Web 浏览器
浏览器侧建议补传以下请求头：
1. `x-client-type`
2. `x-client-runtime`
3. `x-client-platform`
4. `x-client-instance-id`
其中：
1. `x-client-instance-id`
由前端首次启动时生成并持久化到本地存储
2. `x-client-runtime`
可由前端粗判，也允许后端根据 UA 覆盖修正
### 7.2 小程序
小程序侧额外补传：
1. `x-client-type=mini_program`
2. `x-client-runtime`
如 `wechat_mini_program`
3. `x-client-platform`
`ios` / `android`
4. `x-client-instance-id`
5. `x-mini-program-app-id`
6. `x-mini-program-env`
## 8. 后端判定规则
### 8.1 输入优先级
Axum 侧按以下顺序解析：
1. 显式请求头
2. `User-Agent` 自动识别
3. 回退默认值
### 8.2 默认回退
如果没有任何显式端侧头：
1. `client_type = web_browser`
2. `client_runtime` 由 UA 粗判，判不出则 `unknown`
3. `client_platform` 由 UA 粗判，判不出则 `unknown`
### 8.3 微信内 H5
如果 UA 命中 `MicroMessenger` 且不是小程序显式来源：
1. `client_type = wechat_h5`
2. `client_runtime = wechat_embedded_browser`
### 8.4 小程序来源优先于 UA
如果 `x-client-type=mini_program`：
1. 不再按普通 UA 逻辑覆盖成浏览器
2. `client_runtime` 必须优先保留小程序来源值
## 9. `client_instance_id` 规则
### 9.1 作用
它用于区分：
1. 同设备不同浏览器
2. 同浏览器不同安装实例
3. 小程序容器与普通 H5 容器
### 9.2 生成策略
前端首次启动时生成一个随机字符串并持久化：
1. Web：`localStorage` / `indexedDB`
2. 小程序：平台侧本地存储
说明：
1. 清浏览器数据后会变化，这是可接受的。
2. 它不是登录凭据，只是会话识别辅助字段。
## 10. `device_fingerprint` 规则
后端可基于以下字段做稳定哈希：
1. `client_type`
2. `client_runtime`
3. `client_platform`
4. `client_instance_id`
如果 `client_instance_id` 缺失，则回退：
1. `client_type`
2. `client_runtime`
3. `client_platform`
4. `normalized user_agent`
说明：
1. 这个指纹只用于显示和聚类，不作为鉴权依据。
2. 同一设备上的不同浏览器通常应产生不同指纹。
## 11. `device_display_name` 派生规则
后端固定按以下优先级派生：
1. 小程序：
- `微信小程序 / iPhone`
- `微信小程序 / Android`
- `支付宝小程序 / Android`
2. 微信内 H5：
- `微信内网页 / iPhone`
- `微信内网页 / Android`
3. 普通浏览器：
- `Windows / Chrome`
- `macOS / Safari`
- `iPhone / Safari`
- `Android / Chrome`
4. 无法识别时：
- `未知设备`
## 12. 与会话列表 DTO 的关系
当前 `AuthSessionSummary` 至少建议新增：
1. `clientRuntime`
2. `clientPlatform`
3. `deviceDisplayName`
4. `miniProgramAppId`
当前已有字段中的：
1. `clientType`
保留，但升级为新枚举
2. `clientLabel`
后续可由 `deviceDisplayName` 替代，或先兼容保留
## 13. 首版 Rust 落地范围
当前首版建议先完成：
1. Axum 从请求头 + UA 解析 `SessionClientContext`
2. `module-auth` 的 `refresh_session` 增加结构化客户端字段
3. 登录创建 session 时写入这些字段
4. 单元测试覆盖浏览器、小程序、微信 H5 的识别规则
本轮不强制一起完成：
1. `/api/auth/sessions`
2. 前端全面补传 `x-client-*` 头
3. 小程序端 SDK 对接
## 14. 不允许的设计漂移
后续实现时禁止：
1. 继续把所有终端都写成 `browser`
2. 用 `User-Agent` 文本直接充当最终设备名称
3. 用 IP 作为设备唯一标识
4. 把 `client_instance_id` 当成安全凭据
5. 前端任意上传自由文本设备名并直接持久化
## 15. 完成定义
满足以下条件时，这条能力设计视为完成：
1. 会话身份字段已能区分来源、运行时、平台、实例
2. 同设备不同浏览器与小程序来源都有明确建模
3. `device_display_name` 已有统一派生规则
4. 后续 `/api/auth/sessions` 已有稳定可用的数据基础

2
docs/technical/README.md
View File

@@ -5,7 +5,9 @@
## 文档列表
- [AUTH_ME_QUERY_DESIGN_2026-04-21.md](./AUTH_ME_QUERY_DESIGN_2026-04-21.md)：`/api/auth/me` 首版查询设计，冻结 Bearer JWT 衔接、`user + availableLoginMethods` 返回 contract，以及用户不存在时的 `401` 语义。
- [AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md](./AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md)：`/api/auth/sessions` 会话列表设计，冻结当前设备识别、多端登录字段映射、`clientLabel` 兼容策略与 Rust 首版接口边界。
- [PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md](./PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md)：密码登录与自动建号落地设计，冻结 `/api/auth/entry`、幂等兼容策略、模块边界以及与 JWT / refresh cookie 的衔接方式。
- [MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md](./MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md)：多端登录会话身份模型设计，冻结浏览器、小程序、微信内 H5 的客户端身份字段、请求头约定与展示名派生规则。
- [PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md](./PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md)：`platform-auth` refresh cookie 适配设计，冻结 cookie 配置结构、读取规则与 `api-server` 最小读取链路。
- [PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md](./PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md)：`platform-auth` 首版 JWT 适配设计，冻结 `JwtConfig`、claims 结构、`HS256` 签发/校验、`api-server` Bearer 中间件与内部验收路由边界。
- [OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](./OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)：面向 Axum、`platform-auth` 与 `SpacetimeDB` 身份透传的 OIDC 风格 JWT claims 设计，冻结 `iss/sub/sid/provider/roles` 等关键字段。

53
docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md
View File

@@ -13,6 +13,11 @@
3. `refresh_session` 与 `user_account.token_version` 的职责切分
4. 会话列表、当前设备识别、轮换与吊销的数据结构
补充约束：
1. 多端登录识别字段以 [MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md](./MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md) 为准。
2. 本文负责把这些字段正式并入 `refresh_session` 结构、迁移规则与接口读模型。
## 2. 当前基线
当前 Node 后端已经存在一张 `user_sessions` 表，并且 refresh cookie 主链已经完整可用：
@@ -44,6 +49,7 @@
1. refresh session 已经是现有系统的既有真相源。
2. Rust 重写时不需要重新发明另一套“session cache + cookie state”双轨模型。
3. 只需要把当前语义更明确地迁入 SpacetimeDB，并把与 `user_account` 的职责切开。
4. 旧 Node 基线只有最小 `client_type + user_agent + ip` 粒度，本轮需要升级为结构化客户端身份模型。
## 3. 边界定义
@@ -129,7 +135,14 @@
| `session_id` | `String` | 是 | 主键，建议继续沿用 `usess_*` 前缀。 |
| `user_id` | `String` | 是 | 归属账号 ID，外键指向 `user_account.user_id`。 |
| `refresh_token_hash` | `String` | 是 | 当前生效 refresh token 的哈希值。 |
| `client_type` | `String` | 是 | 当前设备类型，当前阶段默认 `browser`。 |
| `client_type` | `String` | 是 | 终端大类，固定枚举见多端会话身份设计。 |
| `client_runtime` | `String` | 是 | 具体运行时，例如 `chrome`、`wechat_mini_program`。 |
| `client_platform` | `String` | 是 | 平台类型，例如 `windows`、`ios`、`android`。 |
| `client_instance_id` | `Option<String>` | 否 | 客户端实例 ID，用于区分同设备不同浏览器或同浏览器不同安装实例。 |
| `device_fingerprint` | `Option<String>` | 否 | 服务端派生的设备聚类指纹，不作为安全凭据。 |
| `device_display_name` | `String` | 是 | 用于会话列表展示的统一端侧名称。 |
| `mini_program_app_id` | `Option<String>` | 否 | 小程序 appid。 |
| `mini_program_env` | `Option<String>` | 否 | 小程序环境，例如 `develop`、`trial`、`release`。 |
| `user_agent` | `Option<String>` | 否 | 请求头中的 `User-Agent` 原文。 |
| `ip` | `Option<String>` | 否 | 会话创建时采集的客户端 IP。 |
| `issued_by_provider` | `String` | 是 | 该会话是由哪种登录链路创建，枚举固定为 `password`、`phone`、`wechat`。 |
@@ -145,6 +158,8 @@
1. 当前阶段时间字段统一继续使用 UTC RFC3339 字符串。
2. `session_id` 在 refresh 轮换时保持不变，不创建新会话行。
3. `issued_by_provider` 不是为了做 provider 身份表，而是为了后续账号安全页和审计展示保留稳定字段。
4. `device_display_name` 由 Axum 应用层基于结构化字段派生，不直接信任前端自由文本。
5. `client_type`、`client_runtime`、`client_platform` 的具体枚举口径固定受多端会话身份设计文档约束。
## 7. 唯一约束与索引
@@ -285,13 +300,21 @@
1. `session_id`
2. `client_type`
3. `user_agent`
4. `ip`
5. `created_at`
6. `last_seen_at`
7. `expires_at`
3. `client_runtime`
4. `client_platform`
5. `device_display_name`
6. `mini_program_app_id`
7. `mini_program_env`
8. `user_agent`
9. `ip`
10. `created_at`
11. `last_seen_at`
12. `expires_at`
前端 DTO `clientLabel`、`ipMasked`、`isCurrent` 继续在 Axum 侧派生。
前端 DTO 侧：
1. `clientLabel` 当前阶段继续兼容保留，但固定与 `deviceDisplayName` 对齐。
2. `ipMasked`、`isCurrent` 继续在 Axum 侧派生。
### 10.3 `POST /api/auth/logout`
@@ -314,7 +337,7 @@
| `id` | `session_id` | 原样迁移。 |
| `user_id` | `user_id` | 原样迁移。 |
| `refresh_token_hash` | `refresh_token_hash` | 原样迁移。 |
| `client_type` | `client_type` | 原样迁移。 |
| `client_type` | `client_type` | `browser` 在迁移后统一归一为 `web_browser`。 |
| `user_agent` | `user_agent` | 原样迁移。 |
| `ip` | `ip` | 原样迁移。 |
| `expires_at` | `expires_at` | 原样迁移。 |
@@ -330,6 +353,20 @@
说明：这是保守回填值，后续只影响展示，不影响鉴权正确性
2. `revoked_reason_code`
初次迁移统一回填为 `null`
3. `client_runtime`
初次迁移按 `User-Agent` 粗判，无法识别时回填 `unknown`
4. `client_platform`
初次迁移按 `User-Agent` 粗判，无法识别时回填 `unknown`
5. `client_instance_id`
初次迁移统一回填为 `null`
6. `device_fingerprint`
初次迁移按 `client_type + client_runtime + client_platform + normalized_user_agent` 派生
7. `device_display_name`
初次迁移由后端按多端会话身份规则派生
8. `mini_program_app_id`
初次迁移统一回填为 `null`
9. `mini_program_env`
初次迁移统一回填为 `null`
## 12. reducer / service 落地约束