# OIDC JWT Claims 设计

日期：`2026-04-21`

## 1. 文档目的

这份文档用于完成 `M2` 中的两条任务：

1. `设计 JWT claims`
2. `确认 iss/sub/sid/provider/roles 字段`

目标是把当前 Node 后端只包含 `sub + ver` 的轻量 JWT，升级为一份既兼容 Axum Bearer 鉴权、又可用于 `SpacetimeDB` 身份透传的 OIDC 风格 claims 设计，并固定：

1. 必须出现的标准字段与扩展字段
2. 哪些字段属于 access token，哪些不应该塞进 JWT
3. Axum、`platform-auth`、`module-auth`、`SpacetimeDB` 各自如何使用这些 claims
4. 与当前 Node token 口径的映射方式

## 2. 当前基线

当前 Node token 实现位于：

1. `server-node/src/auth/token.ts`
2. `server-node/src/middleware/auth.ts`
3. `server-node/src/types/express.d.ts`

当前 Node access token 口径：

1. Header：
   - `alg = HS256`
   - `typ = JWT`
2. 标准字段：
   - `sub = userId`
   - `iss = config.jwtIssuer`
   - `iat`
   - `exp`
3. 自定义字段：
   - `ver = tokenVersion`

当前主要问题：

1. claims 信息过薄，不足以直接支撑 `SpacetimeDB` 侧的身份上下文判断
2. `sid/provider/roles` 等字段尚未冻结，后续 `platform-auth` 与 `module-auth` 实现没有稳定目标
3. 当前 Express `request.auth` 里也只有 `userId` 与 `tokenVersion`

## 3. 设计目标

新的 access token 必须同时满足：

1. Axum 可直接做 Bearer 校验与最小授权判断
2. `SpacetimeDB` 可识别发行者与稳定主体身份
3. 后续 `module-auth` 可基于 `sid/provider/roles` 做会话与能力判定
4. 前端无需解析大量敏感信息
5. claims 尺寸保持克制，不把会话明细或风控状态塞进 JWT

## 4. token 分层

当前阶段固定只设计两类 token：

### 4.1 Access Token

用途：

1. `Authorization: Bearer <token>`
2. Axum 路由鉴权
3. `SpacetimeDB` 身份透传

特点：

1. 短期有效
2. 带完整最小 claims
3. 可在服务间透传

### 4.2 Refresh Session Cookie

用途：

1. 浏览器长期登录续期
2. 轮换 access token

特点：

1. 不走 JWT
2. 对应 `refresh_session` 表
3. 不通过 `SpacetimeDB` 透传

结论：

1. 只有 access token 需要本设计文档中的 claims
2. refresh cookie 不追加 JWT claims 设计复杂度

## 5. Claims 总体设计

当前阶段固定采用：

### 5.1 标准字段

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `iss` | 是 | 发行者，固定为 Axum 鉴权发行者。 |
| `sub` | 是 | 稳定用户 ID，对应 `user_account.user_id`。 |
| `aud` | 否 | 当前阶段可暂不强制；若启用，固定为 `genarrative-api`。 |
| `iat` | 是 | 签发时间。 |
| `exp` | 是 | 过期时间。 |
| `nbf` | 否 | 当前阶段不强制。 |
| `jti` | 否 | 当前阶段不强制；若后续需要细粒度吊销，再单独扩展。 |

### 5.2 扩展字段

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `sid` | 是 | 会话 ID，对应 `refresh_session.session_id` 或当前 access token 所属会话。 |
| `provider` | 是 | 登录来源，固定为 `password`、`phone`、`wechat`。 |
| `roles` | 是 | 角色列表；当前默认至少包含 `user`。 |
| `ver` | 是 | 用户 token 版本，对应 `user_account.token_version`。 |
| `phone_verified` | 是 | 是否已完成手机号验证。 |
| `binding_status` | 是 | 账号绑定状态，固定为 `active`、`pending_bind_phone`。 |
| `display_name` | 否 | 当前展示名快照，用于少量上游日志/观测；不是授权依据。 |

## 6. 关键字段定义

### 6.1 `iss`

固定要求：

1. 必填
2. 必须可稳定配置
3. 必须作为 Axum 与 `SpacetimeDB` 共同信任的发行者标识

当前阶段建议：

1. 本地开发默认：`https://auth.genarrative.local`
2. 测试/生产环境由 `GENARRATIVE_JWT_ISSUER` 或等价配置显式提供

说明：

1. 不继续沿用 Node 当前的 `genarrative-server-node` 这种非 URL 风格字符串。
2. 既然目标是 OIDC 风格 claims，`iss` 应该升级为稳定 issuer 标识。

### 6.2 `sub`

固定要求：

1. 必填
2. 值为稳定用户 ID
3. 不能使用手机号、微信 openid 或用户名作为 `sub`

来源：

1. `user_account.user_id`

### 6.3 `sid`

固定要求：

1. 必填
2. 表示当前 access token 所属的会话 ID
3. 用于会话吊销、全端登出和会话列表关联

来源：

1. `refresh_session.session_id`

说明：

1. 即便当前 access token 是由 refresh cookie 刷新得到，`sid` 仍固定指向同一会话 ledger。
2. `sid` 是会话真相的索引，不是一次 access token 的唯一 ID。

### 6.4 `provider`

固定枚举：

1. `password`
2. `phone`
3. `wechat`

来源：

1. 优先来源于当前会话完成登录时的主 provider
2. 与 `auth_identity.provider`、`user_account.login_provider` 保持兼容

### 6.5 `roles`

固定要求：

1. 必填
2. 类型为字符串数组
3. 当前阶段至少包含 `user`

当前阶段角色基线：

1. `user`

说明：

1. 当前阶段不预支 `admin/moderator/devops` 等角色体系
2. 但字段必须现在就冻结，避免后续 breaking change

### 6.6 `ver`

固定要求：

1. 必填
2. 表示当前用户 token 版本
3. 用于全局登录失效控制

来源：

1. `user_account.token_version`

兼容说明：

1. 继续兼容当前 Node `ver` 设计
2. Axum 校验时必须比对数据库中的最新 `token_version`

### 6.7 `phone_verified`

固定要求：

1. 必填
2. `true` 表示账号已具备已验证手机号
3. `false` 表示例如微信待绑手机号场景

来源：

1. `user_account.phone_verified_at != null`

### 6.8 `binding_status`

固定枚举：

1. `active`
2. `pending_bind_phone`

来源：

1. `user_account.account_status` 的鉴权视图

说明：

1. 它不是完整账号状态枚举，只是鉴权流程需要的最小绑定状态快照
2. 禁止把大量内部状态枚举直接透传成 JWT claim

### 6.9 `display_name`

固定规则：

1. 可选
2. 仅作为展示快照
3. 不能用于授权或数据归属判断

说明：

1. 即使写入，也必须把它视为弱一致字段
2. 后续若变更显示名，不要求立即使所有 JWT 失效

## 7. 不进入 JWT 的字段

以下内容当前阶段禁止进入 access token：

1. 原始手机号
2. 手机号脱敏值
3. 微信 openid / unionid
4. refresh token hash
5. 风控状态、captcha 状态、封禁剩余时间
6. 完整用户资料对象
7. 审计日志、设备列表、IP、UA

原因：

1. 这些字段要么敏感，要么高频变动，要么不适合做 claims
2. 统一由数据库真相或接口读取承担

## 8. 推荐 payload 形态

```json
{
  "iss": "https://auth.genarrative.local",
  "sub": "usr_123",
  "sid": "sess_456",
  "provider": "wechat",
  "roles": ["user"],
  "ver": 3,
  "phone_verified": false,
  "binding_status": "pending_bind_phone",
  "display_name": "微信旅人",
  "iat": 1713657600,
  "exp": 1713664800
}
```

说明：

1. 示例只表达字段形态，不锁死具体编码库细节
2. `iat/exp` 由签发库按标准时间戳表达

## 9. Axum / platform-auth / module-auth / SpacetimeDB 的使用边界

### 9.1 `platform-auth`

负责：

1. 签发 access token
2. 校验 `iss/exp/sub/sid/provider/roles/ver`
3. 解析 claims 为统一 Rust 结构

### 9.2 `module-auth`

负责：

1. 提供 claims 所依赖的用户、会话、绑定状态真相
2. 定义 `provider`、`binding_status`、`token_version` 的领域语义

### 9.3 `api-server`

负责：

1. 从 Bearer token 中提取 claims
2. 做路由级鉴权与用户状态校验
3. 把最小身份上下文透传给 `SpacetimeDB client`

### 9.4 `SpacetimeDB`

负责：

1. 基于受信任 issuer 识别主体身份
2. 在 reducer / view 上下文中读取稳定主体身份

当前阶段约束：

1. `SpacetimeDB` 身份判定以 `iss + sub` 为核心
2. `sid/provider/roles` 主要服务于应用层与后续模块授权，不要求第一版在 reducer 中过度使用

## 10. 与当前 Node token 的映射关系

| 当前 Node | 新 claims | 迁移规则 |
| --- | --- | --- |
| `sub = userId` | `sub` | 原样保留，但语义冻结为稳定用户 ID。 |
| `iss = jwtIssuer` | `iss` | 继续保留，但升级为 OIDC 风格 issuer 标识。 |
| `ver = tokenVersion` | `ver` | 原样保留。 |
| 无 | `sid` | 新增，绑定会话主键。 |
| 无 | `provider` | 新增，绑定本次登录 provider。 |
| 无 | `roles` | 新增，当前至少固定为 `["user"]`。 |
| 无 | `phone_verified` | 新增，表达手机号验证状态。 |
| 无 | `binding_status` | 新增，表达待绑手机/已激活状态。 |
| 无 | `display_name` | 可选新增。 |

## 11. Express / Axum 请求上下文映射

当前 Node `Express.Request.auth` 只有：

1. `userId`
2. `tokenVersion`

Rust 侧建议升级为统一 claims 结构，例如：

1. `user_id`
2. `session_id`
3. `provider`
4. `roles`
5. `token_version`
6. `phone_verified`
7. `binding_status`

说明：

1. `api-server` 不再只传 `userId`
2. 但 handler 仍应优先依赖最小必要字段，避免所有路由都耦合完整 claims

## 12. 不允许的设计漂移

后续实现时禁止出现以下情况：

1. 继续只保留 `sub + ver`，却声称已完成 `SpacetimeDB` 身份透传设计
2. 把手机号、openid、unionid 等敏感信息直接塞进 JWT
3. 把 `sid` 设计成一次 access token 的随机 ID，而不是会话 ID
4. 把 `roles` 省略，等未来再补，导致后续 claims 结构 breaking change
5. 在 `SpacetimeDB` 场景里信任客户端传入的 user id，而不是受信任 JWT 的 `sub`

## 13. 本任务完成定义

当以下条件满足时，JWT claims 设计任务视为完成：

1. `iss/sub/sid/provider/roles` 已明确冻结
2. access token 与 refresh session 的职责边界已切开
3. Axum、`platform-auth`、`module-auth`、`SpacetimeDB` 的使用边界已明确
4. 后续可以直接按这份文档实现签发、校验与身份透传

## 14. 依据文件

1. `server-node/src/auth/token.ts`
2. `server-node/src/middleware/auth.ts`
3. `server-node/src/auth/refreshSessionCookie.ts`
4. `server-node/src/config.ts`
5. `server-node/src/types/express.d.ts`
6. `packages/shared/src/contracts/auth.ts`
7. `docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md`
8. `docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md`
9. `docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md`