# 路线图 / 待执行任务 > 状态标记:`[ ]` 待开工 · `[~]` 进行中 · `[x]` 已完成 > 每项都在「为什么 / 做什么 / 验收 / 注意」四段内自洽,可直接开工。 --- ## v1(已完成) - [x] 从内部网关项目剥离出独立 SSO 服务(去掉动态域名转发 / LLM 上游代理 / 用量计费) - [x] 目录重组:`docs/` `source/` `tests/` `scripts/` - [x] 自包含 IdP:四种 grant + PKCE + discovery + introspect + userinfo - [x] IAP 身份注入:`X-Auth-*` 五头,客户端伪造同名头被覆盖 - [x] MaxKey 端点别名与 context-path 归一化 - [x] 管理台:账号管理 + OAuth 接入方管理 + 接入指南 - [x] 三套端到端回归(协议基线 14 · 互通/接入 24 · 管理接口 31) --- ## [ ] v2:升级 RS256 签名 + `/oauth/jwks`,让第三方本地验签 ### 为什么 当前 access_token / id_token 用 **HS256(对称密钥)** 签名,密钥即 `OAUTH_SIGNING_SECRET`。 对称密钥的根本问题是**不能给第三方**——给了就等于把签发能力也给了。所以现状是: - 第三方拿到令牌后**无法本地验签**,只能每请求回源 `POST /oauth/introspect`; - 每个业务系统都要经一次网络往返 + 本服务的可用性依赖,横向扩展时自省成为热点; - OIDC 生态里的标准库(各类 `jwks` 缓存实现)**用不上**——它们默认 RS256 + JWKS。 `GET /oauth/jwks` 与 `/.well-known/jwks.json` 路由**已在 v1 占位**,当前行为是 「显式 404 + 说明原因」(不返回空 `{"keys":[]}`,避免客户端静默失败)。 ### 做什么 1. **密钥对与轮换模型** - 配置:`OAUTH_JWK_DIR`(默认 `$data_dir/jwks`)下放 `active.pem` + 可选的历史公钥。 - 启动时(`state_zone_init`,fork 前)载入私钥;缺私钥则**首次启动自动生成** 2048-bit RSA (`openssl` 命令行不可用,需纯 Rust 生成——见「注意」)。 - 支持 `kid`:每把密钥一个稳定 `kid`(如公钥 SHA-256 前 16 位 hex),签发时写进 JWT header。 - 轮换:把新密钥设为 active,旧私钥移出签名集但**公钥保留在 JWKS**,直到最后一批旧令牌过期 (≥ `OAUTH_REFRESH_TTL` = 30 天)。 2. **签名算法抽象** - 在 `oauth.rs` 抽出 `mint` / `verify` 的算法分支:`HS256`(兼容旧密钥)| `RS256`(默认)。 - `jwt_verify` 按 JWT header 的 `alg` 选择验签方式;**必须白名单校验 `alg`**, 禁止 `none`,禁止拿公钥当 HMAC 密钥(`alg` 混淆攻击)。 - `alg` 决策走配置(`OAUTH_JWT_ALG`,默认 `RS256`),便于灰度:新旧并行期内 用 HS256 签发的存量令牌仍可验签通过。 3. **JWKS 端点** - 输出标准 JWK:`{"keys":[{"kty":"RSA","use":"sig","alg":"RS256","kid":...,"n":...,"e":...}]}`。 - `n`/`e` 用 **base64url 无填充**(不是标准 base64)。 - 加 `Cache-Control`(如 `public, max-age=3600`),并保证轮换后客户端能及时刷新。 - discovery 的 `jwks_uri` 指向 `/.well-known/jwks.json`,`id_token_signing_alg_values_supported` 改为 `["RS256","HS256"]`。 4. **依赖与体积** - RSA 需要大数运算。优先评估 **手写**(`modpow` + 已有的 `sha2`)还是引入 `rsa` / `ring` / `num-bigint`——v1 的硬约定是「零新增依赖 / vendor 离线可编译」, 引入前先确认能否 vendor 进 `source/rust/vendor/`。 - 若用手写:`rsa` crate 的 PKCS#1 v1.5 + SHA-256 + RSASSA-PKCS1-v1_5 编码是固定长度填充, 实现量可控;签名的 `DigestInfo` DER 前缀是常量,可直接内联。 ### 验收 - [ ] `GET /.well-known/jwks.json` 返回可用 JWKS,`n`/`e` 为 base64url; - [ ] 用 JWKS 公钥在**不访问本服务**的前提下,本地验签通过 access_token 与 id_token; - [ ] `alg` 传 `none` / 传 HS256 但用公钥当密钥 → 一律拒绝; - [ ] 轮换后:新令牌带新 `kid`,旧令牌仍能验签直到过期; - [ ] 现有三套 e2e 全绿(HS256 存量路径不回归); - [ ] 新增一套 e2e:抓 JWKS → 本地验签 → 断言 `iss`/`aud`/`exp`。 ### 注意 - **`iss` 一致性**是历史上最容易踩的坑:`OAUTH_ISSUER` 必须与浏览器实际访问的 host 一致。 第三方本地验签会把 `iss` 与 discovery 的 `issuer` 逐字符比对,不一致直接失败。 - 私钥**绝对不进版本库**(`.gitignore` 放行规则要写对,别把 `jwks/` 加进白名单)。 - 不要返回空 JWKS:客户端会缓存住「无密钥」状态,问题排查时表现为「一直验签失败、日志无异常」。 --- ## [ ] 用户管理界面:角色 / 部门 / 用户组的可视化维护 ### 为什么 管理台的「账号管理」现在只能建账号、改显示名、重置口令/密钥、删除, **角色 / 部门 / 用户组三个字段是只读展示**(表格里注明「接口已可用,界面待做」)。 但这三个字段恰恰是 IAP 的实际价值所在:后端收到 `X-Auth-Groups` 后要据此做本地鉴权, 若只能改 `users.json` 文件(还不热生效,必须重启),等于「有分组机制但没法运营」。 **后端接口在 v1 已经就绪且已测**: | 接口 | 作用 | 校验 | | --- | --- | --- | | `POST /api/admin/users/role` | 改角色 | 不允许降级最后一个管理员 | | `POST /api/admin/users/profile` | 改部门 / 用户组 | 均禁控制字符;部门长度 ≤ `DEPARTMENT_MAX_LEN`;组数 ≤ `GROUPS_MAX`,单组名 ≤ `GROUP_NAME_MAX_LEN` | | `GET /api/admin/users` | 列表 | 已回显 `departments` / `groups` 取值集合(供前端做候选提示) | 所以本项**纯前端 + 少量交互打磨**,不需要动 Rust。 ### 做什么 1. **账号表行内编辑**(或在侧滑面板里): - `role`:下拉(`admin` / `user`);目标账号是最后一个管理员时**禁用降级**并给出原因, 与后端校验保持一致的文案,避免「点了才报错」。 - `department`:单值,带已有部门的下拉候选 + 允许新建(datalist)。 - `groups`:多值标签输入(逗号或回车确认、可删),候选来自列表接口回显的集合。 2. **列表里的筛选与批量** - 按角色 / 部门 / 用户组筛选; - 批量加组 / 移组(按行多选 → 一次提交多条 `users/profile`)。 3. **一致性** - 提交后立即用返回值刷新本地行数据(不做乐观更新后不回读,避免与「最后一个管理员」这类 服务端裁决不一致); - 错误提示直接透出后端 `msg`(校验文案已经写得很具体,不要再包一层泛化提示)。 4. **顺手补齐**(同一批改动内,成本很低) - 统计卡已有「部门 / 用户组」两个数字,点击应能下钻筛选到对应列表。 ### 验收 - [ ] 能给账号改角色、部门、用户组,刷新页面后仍在; - [ ] 最后一个管理员无法被降级(前端禁用 + 后端兜底都生效); - [ ] 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确; - [ ] 按角色 / 部门 / 用户组能筛出正确结果; - [ ] 改完用户组后,经 IAP 访问后端拿到的 `X-Auth-Groups` 同步变化 (端到端验证:改组 → 带会话请求 demo 系统的 `/api/echo` → 断言头部); - [ ] `admin.html` 内无内联 `onclick`,无未清理的全局状态(沿用 v1 的写法约定)。 ### 注意 - 前端**不能**把 `salt` / `pwd_hash` 带到任何请求或日志里:列表接口刻意不返回它们。 - 用户组名会进 HTTP 头(`X-Auth-Groups`)。后端 `check_groups` 把 `,` `、` `;` 换行/制表/空格**当分隔符切开**(而不是报错),所以组名里永远不可能含逗号—— 前端的标签输入要与之一致:用户敲 `a,b` 应得到两个标签「a」「b」,不是一个标签「a,b」; 否则「界面显示一个组、实际存了两个」会很难查。 - 改角色 / 部门 / 组都是**写穿共享内存 + 写文件**,写完即生效(无需重启); 若发现「改完不生效」,先查是不是漏了 `sync_shm` 而不是去重启。 --- ## 备注:不建议做的事 - **不要为分组引入树形 / 多级组织架构**。当前模型是「部门(单值)+ 用户组(多值平铺)」, 足以支撑 IAP 的 header 注入与后端本地鉴权;升级成组织树会同时放大前端、校验与同步三处复杂度, 且与本服务「身份层」的定位不符。确有需要时,让下游业务系统用 `X-Auth-Groups` 自己做映射。 - **不要把 OIDC 的 scope / claim 自定义能力做成界面配置**。claim 形状是第三方客户端的契约, 改动需要双方同步,属于「按需改代码」而不是「运营自助」。