Files
sso/docs/task-plan.md
T
ssw 8e9becaad7 docs: 插件化架构分析与迁移/任务文档,同步 CLAUDE.md 与路线图
新增
  docs/plugin-architecture-analysis.md  内核/插件边界分析、P 阶段拆分与装配契约
  docs/maxkey-migration-analysis.md     MaxKey 端点别名与 context-path 归一化对齐
  docs/task-plan.md                     阶段任务清单与验收口径

同步
  CLAUDE.md    crate 清单与目录地图:plugin-domain 标为「已迁入示例」,
               plugin-llm 明确「不迁入」(LLM 上游代理与配额计费属流量层,
               与本服务「身份层」的定位分界不变,半成品已从 workspace 移除);
               回归口径五套 → 六套;测试配置端口范围 18093-18099
  README.md    结构树补 plugin-domain,端口范围同步
  roadmap.md   P2 标记为已完成(部分)并写明 plugin-llm 不迁入的理由
2026-09-13 10:25:48 +08:00

56 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 任务计划:MaxKey 能力迁移落地(2026-09-12)✅ 已全部完成(2026-09-13)
> 依据:`docs/maxkey-migration-analysis.md`(P0×7)+ `docs/roadmap.md`(v2 + 用户管理界面)
> 保障手段:每项实现都带 e2e 断言;可借鉴的 MaxKey 测试用例逐项标注。
> 约束:零新增 crates.io 依赖(SHA-1、RSA、大数运算全部手写);存储沿用 users.json + 共享内存,不引入 DB。
## 执行顺序与验收
| # | 任务 | 落点 | 验收(e2e 断言) | 借鉴的 MaxKey 测试 |
| --- | --- | --- | --- | --- |
| ✅ 1 | 登录失败锁定(账号维度) | models/users/api/oauth/config | 连错 5 次锁定 600s;锁定期间密码正确也 423;到期自解锁;管理台可解锁 | mxk_history_login 失败计数语义 |
| ✅ 2 | 密码策略 | config/users | 短于 8 位拒;纯数字/纯字母拒;改密/建号/重置三入口一致 | mxk_cnf_password_policy 字段 |
| ✅ 3 | 审计日志 JSONL | 新模块 audit.rs + api | 登录成败/发令牌/管理操作都有行;管理台可查;>5MB 自动轮转 | mxk_history_login/event 三分表字段 |
| ✅ 4 | 在线会话查看/踢出 | state/api | sess:/sso: 均可列出(含过期过滤);按 token 或按用户踢;被踢会话立即 401 | SessionController 列表/踢出 |
| ✅ 5 | SVG 图形验证码 | 新模块 captcha.rs + oauth/api | 开关 `OAUTH_CAPTCHA=1` 时登录页出验证码、错码拒绝;缺省关(存量 e2e 不回归) | kaptcha 行为(不用其实现) |
| ✅ 6 | TOTP 双因子 | 新模块 otp.rs + users/api/oauth | RFC 4226/6238 标准向量通过;绑定→启用→登录必须带码;码错/缺失拒绝 | maxkey-starter-otp:HmacOTPTest / TimeBasedOTPTest(Base32 seed + 30s 步长 + 6 位截断) |
| ✅ 7 | RS256 + JWKS(roadmap v2) | 新模块 rsa.rs + oauth | JWKS 端点出 n/e(base64url);本地验签通过;alg=none / alg 混淆拒绝;HS256 存量可验;新 e2e 覆盖 | JWS/JWE 签发验签语义(maxkey-crypto) |
| ✅ 8 | 用户管理界面 | www/admin.html | 行内改角色/部门/组;筛选;批量加组;最后管理员禁用降级;组名逗号即时切分 | MaxKey 用户管理页交互 |
| ✅ 9 | 全量回归 + roadmap 更新 | tests/ + roadmap.md | 四套 e2e 全绿;roadmap 勾选 | — |
## 关键设计决定(偏离/补充说明)
- **验证码缺省关闭**(`OAUTH_CAPTCHA=1` 开启):验证码图形无法被 curl e2e 读取,
缺省开会让全部存量 e2e 失效;生产开启后,浏览器路径正常出码。
- **锁定是账号维度**(users.json 新字段 `failed_count`/`locked_until`),与既有
`fail:<ip>` IP 维度限速叠加;登录低频路径直接读文件,符合现有分层。
- **TOTP 的 HMAC-SHA1 手写**(sha2 crate 没有 SHA-1):RFC 6238 主流 authenticator
默认 SHA1/6 位/30s,必须兼容 Google Authenticator。
- **RSA 手写范围**:`modpow`(Knuth D 除法)+ Miller-Rabin 素性 + PKCS#1 v1.5 签名。
私钥存 `OAUTH_JWK_DIR/active.jwk.json`(分量的 base64url JSON,非 .pem——
手写 ASN.1/PEM 编解码收益低,roadmap 的 `.pem` 命名放宽,其余轮换语义照做)。
- **管理台密码策略例外**:种子管理员 `admin/123456` 不走 create 校验(历史行为),
但一旦重置即受新策略约束。
## 完成情况(2026-09-13 收尾)
- 9/9 全部完成;回归从「三套」扩为**五套**(`scripts/run-local-e2e.sh`,全绿 rc=0):
1. OAuth2/OIDC 基线;2. MaxKey 互通 + demo 接入;3. 管理接口·OAuth 接入方(31 项);
4. RS256 + JWKS 本地验签(14 项,含篡改 / alg=none / alg 混淆拒绝);
5. 管理接口·账号批量维护(39 项,新增)。
- RS256 内核为**手写零依赖 RSA-2048**(Miller-Rabin + 扩展欧几里得模逆 + Montgomery CIOS +
CRT + PKCS#1 v1.5),经独立二进制 × Python `pow()` 互证 3 轮随机密钥 roundtrip 全绿。
因 `cargo test` 链接 nginx 符号,单测走 `/tmp/*_standalone.rs` + rustc 方案。
- 批量维护新增 `POST /api/admin/users/batch`(单次文件锁内组合:加组/移组/设部门/改角色/解锁,
「至少保留一个管理员」红线在批量口径下同样生效)。
- 用户管理界面:筛选(关键字/角色/部门/组/已锁定)、勾选批量条、行内编辑
(角色下拉即改、部门/用户组点击就地编辑,Enter 保存 / Esc 取消 / 失焦提交)。
- 凭据治理:本地 e2e 口令与签名密钥统一进 `.env`(gitignore,模板 `.env.example`),
脚本经 `scripts/load-env.sh` 加载,命令行不再出现密钥。
### 遗留(不阻塞,属后续打磨)
- 用户组「标签输入」交互(当前为逗号分隔输入框,与 `check_groups` 分隔符约定一致,功能等价)。
- 统计卡点击下钻到筛选列表。
- 「最后一个管理员」在前端禁用降级选项(当前为 confirm + 后端红线兜底 + 失败回滚)。