Files
ipass__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

131 lines
6.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 已经在自己的代码里铺好,无需内核再动。