新增
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 不迁入的理由
56 lines
4.9 KiB
Markdown
56 lines
4.9 KiB
Markdown
# 任务计划: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 + 后端红线兜底 + 失败回滚)。
|