Files
ssw__ipass/docs/plugin/SSO_UPSTREAM_DECISIONS.md
admin ee05b27a36 refactor(core): 采纳 sso 上游化 4 条 —— A1/A2/A3 + A1 配套
按 sso/docs/upstream-core-changes.md 评估后的采纳清单:

A1(强采纳):User 增加 `extra` flatten 透传通道,让插件字段不再污染内核模型
A1 配套:新增 `users::update_extra<T,F>`,与 set_allowed_models 同源
A2(修真 bug):state::split_value `position` → `rposition`(payload 含 0x1f
     时被 position 截断;sso 已踩、rposition 取最后一个边界)
A3:state::iter_prefix_ex 返回 (key, payload, exp);iter_prefix 保留兼容包装

不采纳:A4(iPass 已具备大部分,plugin-sso 自实现)、A5(选选项 2 零代码)、
       A6-1(破坏测试边界用例,iPass 内核最小约束,由插件加策略)、
       A6-2(admin login 端点直接用 COOKIE_NAME)

262 项回归全绿(gateway 102 + llm 160)。

详见 docs/plugin/SSO_UPSTREAM_DECISIONS.md。
2026-09-13 17:43:13 +08:00

6.0 KiB
Raw Permalink Blame History

sso 上游化合流决策(2026-09-13,commit ddd4172 → 1.0.13)

sso 团队对照 iPass P5(commit ddd4172,1.0.12)提出 11 条内核修改建议, 分 A 档(请求上游改)与 B 档(自解)。本文件记录采纳与不采纳的依据。

采纳清单

A1 — User.extra flatten 透传通道 ✅

改动:ipass-core/src/models.rs::User 增加

#[serde(default, flatten)]
pub extra: BTreeMap<String, Value>,

为什么采纳:

  • 这是 plugin-sso 验证过的成熟方案("我方已有生产实现,可直接抄")
  • 解决"内核硬编码插件语义"的根本问题——allowed_models/llm_rpm/llm_daily/ temp_grant_until 都是 plugin-llm 的语义污染内核;未来插件要存 TOTP 密钥、 邮箱、用户组、锁定状态……再走内核加字段成本极高
  • serde(flatten) 对存量字段零影响——已认领字段优先,老 users.json 反序列化后原样写回
  • 给未来插件留通用扩展点

配套:同提交加 users::update_extra<T, F>, 让插件改 extra 走「读-改-写 + 写穿 shm」统一路径(与现有 users::set_allowed_models 同源)。

A1 配套 — users::update_extra ✅

ipass-core/src/users.rs 新增 pub fn update_extra<T, F>(username, f) where F: FnOnce(&mut User) -> Result<T, String>。走 store::update_users 路径自动 shm 同步。

A2 — split_value position → rposition ✅(修真 bug)

改动:ipass-core/src/state.rs::split_value 1 字符。

- let sep = bytes.iter().position(|&b| b == VAL_SEP)?;
+ let sep = bytes.iter().rposition(|&b| b == VAL_SEP)?;

为什么是真 bug:value 编码 <payload> \x1f <expires_at>,exp 必为 ASCII 数字(不可能含 VAL_SEP),所以最后一个 \x1f 才是真边界。 position 取第一个,payload 内部一旦含 0x1f(OAuth 授权码、注入头 payload 都可能)就会被截断、exp 解析失败。sso 上游化时已踩此坑。

iPass 现状未踩:sub: payload 是 host:port、ukey: payload 用 \n 分段, 都没内嵌 \x1f。但留此 bug 等下次踩代价太高,1 字符修复零风险。

A3 — state::iter_prefix_ex 返回 (key, payload, exp) ✅

改动:ipass-core/src/state.rs 新增 pub fn iter_prefix_ex(prefix) -> Vec<(String, String, i64)>。iter_prefix 保留为兼容包装(统计键 永不过期、不需要 exp)。

为什么采纳:会话 / OAuth kick / 过期扫描必须看见 exp 才能判定。 新增能力、零破坏。

不采纳清单

A4 — users 模块扩展 6 函数 ⏸️

sso 列了 set_profile / set_role / batch_update / unlock / record_login_failure / update_extra。其中:

  • update_extra —— 已采纳(见上)
  • unlock / record_login_failure —— iPass 已有等价:
    • users::clear_login_fail(ip) 当作 unlock
    • state::bump_login_fail(ip, now) -> i64 已用在 admin login 端点 (api.rs:224),配套 state::get_login_fail 判定 >= LOGIN_MAX_FAIL 锁定。iPass 不需要 lock_until 字段——只要次数 ≥ 10 就拒,与 sso 的 "N 次错误后锁定到 X 时刻" 业务模型不同
  • set_profile / set_role / batch_update —— iPass 没有部门/用户组 业务(纯 LLM + 域名)。留给 plugin-sso 自实现—— store::update_users<T, F> 是 pub,插件可以在闭包里读 &mut User 改任意字段然后调 users::sync_shm 写穿

A5 — store.rs 插件文件命名空间 ⏸️

iPass 选选项 2:path_in_data(name) 是唯一口径,由插件自行拼子目录。 plugin-sso 应直接用 store::path_in_data("oauth_codes.json") 等。 零代码改动。iPass 各插件都各管一份 JSON,无 namespace 冲突需求。

A6-1 — PASSWORD_MIN_LEN 6 → 8 ❌

为什么不采纳:测试夹具大量依赖 6/7 位密码做边界用例 (password 123 测拒绝、password alice123 测合法等)。iPass 整体 风格是「内核最小约束、插件层加业务策略」,弱口令门槛属于业务策略。 plugin-password-policy 类插件(未来)应在内核外校验后再调 users::create / set_password。

回退 PASSWORD_MIN_LEN = 6,回退 INIT_ADMIN_PASSWORD_DEFAULT = "123456"。

iPass 自己的 admin login 端点(CorePlugin)直接用 COOKIE_NAME, 迁移成本 > 收益。若 plugin-sso 想换 cookie 名:自实现 login 端点(替换 CorePlugin 的对应路由)或 fork 一份 CorePlugin。内核不动。

已确认无需上游改动

sso 列的三条确认项,iPass 已具备:

  • http::host_port —— 用 rsplit_once 实现,sso 更简洁、语义等价
  • store::write_json —— 紧凑 JSON,sso 是 pretty,等价
  • Plugin trait(preconfig / postconfig / dispatch_api / zone_load / log_handler)+ PLUGINS 装配 + loc::Switch + ctx_index 注入 —— 两侧已同构,trait 层零适配可合流

变更面

文件 改动
rust/crates/ipass-core/src/state.rs split_value rposition;新增 iter_prefix_ex
rust/crates/ipass-core/src/models.rs User.extra flatten
rust/crates/ipass-core/src/users.rs 新增 update_extra<T, F>;build_user 字面量补 extra: BTreeMap::new();引入 use std::collections::BTreeMap
rust/crates/ipass-core/src/config.rs (仅注释增改 — A6-1 回退后保留原值)

验收

  • cargo build —— 零 error 零 warning
  • bash tests/run.sh all —— 262 全绿(gateway 102 + llm 160)
  • 镜像 tag 计划:ipass-1.0.13(commit 1.0.12 → +1)

与 sso 的合流路径

sso 文档说「内核原样复制」——一旦 sso 仓库拉取 commit 1.0.13+,它 就能用上 User.extra / iter_prefix_ex / split_value 三个修正。其余 插件自实现路径(A4)sso 已经在自己的代码里铺好,无需内核再动。