按 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。
131 lines
6.0 KiB
Markdown
131 lines
6.0 KiB
Markdown
# 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` 增加
|
||
```rust
|
||
#[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>`](upstream-core-changes.md#a1),
|
||
让插件改 `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 字符。
|
||
|
||
```diff
|
||
- 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"`。
|
||
|
||
### A6-2 — COOKIE_NAME 由插件声明 ❌
|
||
|
||
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 已经在自己的代码里铺好,无需内核再动。 |