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

4.9 KiB
Raw Permalink Blame History

任务计划: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 项);
    2. RS256 + JWKS 本地验签(14 项,含篡改 / alg=none / alg 混淆拒绝);
    3. 管理接口·账号批量维护(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 + 后端红线兜底 + 失败回滚)。