diff --git a/.workbuddy/skills/ipass-core-add-plugin/SKILL.md b/.workbuddy/skills/ipass-core-add-plugin/SKILL.md index 055a5d3..0f5536e 100644 --- a/.workbuddy/skills/ipass-core-add-plugin/SKILL.md +++ b/.workbuddy/skills/ipass-core-add-plugin/SKILL.md @@ -184,6 +184,8 @@ CARGO_NET_OFFLINE=true cargo build --release - `proxy_pass http://$module_var;` 在变量为空时会报 500 `no host in upstream`。 **不要用 `if ($var = "")` 兜底** —— `if` 在 rewrite 阶段求值,而变量是 access 阶段才写的, 合法请求会被一起误判。用 `error_page 500 502 503 = @fallback;` + `location @fallback { return 404 "MARKER"; }`。 +- **新模块若读环境变量(`std::env::var`),必须在 conf 的 main 上下文加 `env XXX;` 白名单**, + 否则 worker 里恒读空(**`nginx.conf` 与 `nginx.test.conf` 两处都要加**)。 ### 7. 写 e2e 并注册进回归 @@ -198,23 +200,6 @@ CARGO_NET_OFFLINE=true cargo build --release ### 0. 基准约定(2026-09-13 起生效,先读这条) -**内核(ipass-core)以上游 refs/ipass 为基准,本地零业务补丁**: -- 内核源码与 `refs/ipass/rust/crates/ipass-core/src` 逐字节一致;需要内核改的 - 先提建议(`docs/upstream-core-changes.md` 模式:A 档请上游改 / B 档插件自解), - 上游采纳后 `git -C refs/ipass pull` 再同步 `src/*.rs`。 -- 插件个性代码一律放**插件 crate 本地模块**(参照 plugin-sso 的 accounts.rs/ - storex.rs/utilx.rs/audit.rs 四件套),身份扩展字段存 `User.extra`(flatten - 透传),经 `UserExt` 强类型读写;账号操作走 `store::update_users` + `users::sync_shm`。 -- 插件文件用 `store::path_in_data`(上游唯一口径);`iter_prefix_ex`/`update_extra` - 等上游已提供,不要再造。 -- gateway 装配要点:`[SsoPlugin, CorePlugin, DomainPlugin]`(sso 先认领身份端点)、 - `CoreExt::reclaim_on_delete`(删账号回收域名)、dispatch 兜底 JSON 信封、 - 指令 `ipass_state/ipass_data_dir/ipass_api/ipass_proxy` + `sso_iap`(sso 特有)。 -- Cargo.toml 元数据(crate 名 sso-gateway 等)保留我方:产物名 libsso_gateway.dylib - 是 nginx conf / 部署脚本依赖,勿改。 - -## 0. 基准约定(2026-09-13 起生效,先读这条) - **内核(ipass-core)以上游 refs/ipass 为基准,本地零业务补丁**: - 内核源码与 `refs/ipass/rust/crates/ipass-core/src` 逐字节一致;需要内核改的 先提建议(`docs/upstream-core-changes.md` 模式:A 档请上游改 / B 档插件自解), @@ -271,6 +256,43 @@ cd refs/ipass && git fetch origin && git merge --ff-only origin/main (`email`/`groups`/`failed_count`/`locked_until` …),**由上游改写会抹掉它们**。 两侧不要互写同一份 `users.json`;同理,`gen_id` 形状不同 ⇒ 两侧记录 id 不能互相校验。 +## 协议扩展端点族(SCIM / CAS / 同步 / 密码重置 / 归属地) + +把「一类协议端点」做成 plugin-sso 内的**独立模块**(`scim.rs` / `cas.rs` / `sync.rs` / `reset.rs` / `geo.rs`), +而不是往主路由表里逐条塞路径。分发靠 `api.rs` 的 `route()` **兜底段**: + +```rust +_ => { + if let Some(e) = crate::scim::route(method, uri) { return Some(e); } + if let Some(e) = crate::cas::route(method, uri) { return Some(e); } + if let Some(e) = crate::reset::route(method, uri) { return Some(e); } + if let Some(e) = crate::sync::route(method, uri) { return Some(e); } + None +} +``` + +各模块自持 `route(method, uri) -> Option<(Guard, Handler)>`(前缀/精确匹配自定、鉴权级别自定), +`Guard`/`Handler` 用 `pub(crate)` 暴露。新增同类能力**照此扩展**,不要往主表里逐条塞。 + +**零新增 crate 是硬约束**(禁 crates.io/git 依赖):LDAP 不能用 `ldap3`(async/tokio 冲突)—— +改为**手工 BER/ASN.1** 编码做 Simple Bind(`ldap.rs`);HTTP 拉取用标准库 `TcpStream`(`sync.rs`)。 + +三个必踩点(本仓 2026-09-14 实测): + +1. **新模块读 env 必须进白名单**。nginx 默认剥离全部 env,worker 里 `std::env::var` 恒空。 + 用了 `SYNC_*` / `PASSWORD_RESET_*` / `LDAP_*` 的模块,必须在 `nginx.conf` **和** `nginx.test.conf` + 的 main 上下文显式 `env XXX;`(未设置时按缺省兜底,不报错)。 +2. **302 的 body 不能为空**。`http::redirect` 若用空串,`pool.create_buffer_from_str("")` 返回 `None` + → `send_with` 返回 `NGX_ERROR` → 302 根本不发出(curl 拿不到 `Location`,CAS `?ticket=` 全空)。 + 给一个单空格 body 即可。 +3. **重置/改密类 e2e 不得动 admin 种子口令**。种子口令(如 `123456`)过不了插件 8 位策略, + 重置接口无法还原它 → 一旦改成强口令,后续套件用旧口令登录会反复失败 → 触发账号锁定(**423,600s**), + 整轮回归崩掉。正确做法:**一次性账号**闭环(admin 会话 `users/create` → forgot → reset → 新口令登录 → + `users/delete`),并在 `trap ... EXIT` 里兜底清理;admin 全程不动。已锁时用 + `bash scripts/seed-data.sh --force` 复原 users.json(同时清掉账号锁)。 + +--- + ## 高价值排错(症状 → 根因) | 症状 | 根因 | 修法 | @@ -285,10 +307,13 @@ cd refs/ipass && git fetch origin && git merge --ff-only origin/main | e2e 里新接口全部 401 | location 没开 `sso_ on;`,或鉴权走错通道(Admin 用 Cookie / User 用 `X-API-Key`) | 先手工 curl 确认 `sso_` 生效,再核对凭据类型 | | shell 报 `X:: unbound variable` | `$VAR` 后紧跟全角字符(`$SUB)`)被吞进变量名 | 写 `${SUB})`(本项目高频坑,e2e 里成片出现) | | Edit 工具报成功,但 cargo 仍报同一错误 | 该工具在部分机器上「报告成功但磁盘未落盘」 | 改完 `bash grep` 复核真实磁盘;确定性整段替换**优先用 python 脚本** | +| 新模块读不到 `SYNC_*` / `PASSWORD_RESET_*` 等 env | nginx 剥离全部 env;未在 main 上下文 `env XXX;` | `nginx.conf` 与 `nginx.test.conf` 都加 `env XXX;` | +| CAS `/cas/login` 302 无 `Location` / 无 `?ticket=` | `http::redirect` 传了**空 body** → 零长 buffer 分配失败 → `NGX_ERROR` | redirect 的 body 给单空格 | +| e2e 跑到一半后续套件全 401、日志见 `423 账号已锁定` | 重置类用例改了 admin 种子口令且无法还原,反复登录失败触发账号锁 | 改一次性账号闭环;已锁时 `seed-data.sh --force` 复原 | ## 交付物约定 - 插件新增后,同步更新三处文档:`CLAUDE.md`(crate 清单 + 目录地图 + e2e 套数)、 `README.md`(结构树 + 端口范围)、`docs/roadmap.md`(把「待迁入」改成已完成)。 - 「不做」的决定也要写进文档(例如明确不迁入某插件、以及理由),否则下一个人会再问一遍。 -- 收尾跑全量回归并给出 `rc`:`bash scripts/run-local-e2e.sh`,五套/六套全 `rc=0` 才算绿。 +- 收尾跑全量回归并给出 `rc`:`bash scripts/run-local-e2e.sh`,七套全 `rc=0` 才算绿(第 7 套 `tests/maxkey-p1p2-e2e.sh`:SCIM/CAS/密码重置/同步/LDAP 禁用回归)。