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

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 形态

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