Files
sso/docs/upstream-core-changes.md
T
ssw 81c8346ad6 docs: 致上游 ipass 内核修改建议(A 档 6 项 + B 档自解清单)
- A1 User 加 extra flatten 透传通道(插件字段通用解,替代逐字段硬编码)
- A2 split_value position→rposition(内嵌分隔符截断 bug)
- A3 iter_prefix_ex 带 exp 枚举原语
- A4 账号操作支持路径确认(插件经 store::update_users + sync_shm 自实现)
- A5 插件文件读写口径二选一
- A6 PASSWORD_MIN_LEN 6→8、COOKIE_NAME 由插件声明
- B 档全部本地自解,不阻塞内核原样收敛
2026-09-13 17:18:16 +08:00

127 lines
6.5 KiB
Markdown
Raw 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.
# 致 ipass 上游:内核修改建议(基于 ddd4172 对照)
> 背景:ssw/sso 正按「上游 ipass-core 为内核基准」收敛——内核原样复制,域名插件以上游为准,
> sso 作为纯插件并入。收敛过程中发现以下内核问题,**按影响分两档**:
> **A 档 = 请求上游修改**(不改则两侧合流后有实际损失);
> **B 档 = 供参考**(我方可自行解决,但上游统一改掉对两家都更干净)。
> 我方在等待期间一律先用本地标记补丁(`// PATCH(sso): 待上游采纳后撤销`)推进,不阻塞。
---
## A 档:请求上游修改
### A1. `models.rs` User 增加 `extra` 透传通道(最重要)
上游 User 目前硬编码了 LLM 配额字段(`slots` / `allowed_models` / `llm_rpm` / `llm_daily` /
`temp_grant_until`)。这些是 **plugin-llm 的语义**,放在内核模型里意味着:下一个插件要存
TOTP 密钥、邮箱、用户组、锁定状态……每个都得再来内核加一轮字段——插件用户不可能提供
覆盖所有场景的字段。
建议加一个内核「持有但不解释」的透传字段(我方已有生产实现,可直接抄):
```rust
/// 插件字段:内核持有、透传,不解释。
/// 读文件时未被上面字段认领的 key 自动进 `extra`;写回时展开回顶层。
/// 存量 users.json(含任何插件写入的字段)可原样接管,不会因内核不认识而丢数据。
#[serde(flatten)]
pub extra: BTreeMap<String, Value>,
```
两点说明:
- `flatten` 对上游现有字段**零影响**(已认领的字段优先),老 users.json 反序列化后原样写回。
- 若上游采纳,现有 LLM 字段可继续保留 typed(无冲突);也可顺势迁入 `extra` 让模型瘦身,
由上游定。
### A2. `state.rs` `split_value` 用 `position` 会截断内嵌分隔符的值(疑似 bug)
```rust
// 上游 ddd4172:取第一个分隔符
let sep = bytes.iter().position(|&b| b == VAL_SEP)?;
```
共享内存值格式为 `payload<SEP>exp`。当 payload 自身含 `VAL_SEP`(OAuth 授权码会话、
带逗号串的注入头 payload 都会),`position` 取到 payload 内部的分隔符,payload 被截断、
exp 解析失败。应改为 `rposition`(取最后一个——exp 里不可能再有分隔符):
```rust
let sep = bytes.iter().rposition(|&b| b == VAL_SEP)?;
```
我方生产已按 `rposition` 运行(这正是当初踩坑后改的)。
### A3. `state.rs` 缺带过期时间的枚举原语 `iter_prefix_ex`
上游只有 `iter_prefix`(丢掉 exp)。会话管理类插件(登录会话、OAuth 会话的 kick/清理/列表)
需要 `(key, payload, exp)` 三元组才能判断条目是否已过期。建议:
```rust
pub fn iter_prefix_ex(prefix: &[u8]) -> Vec<(String, String, i64)>;
```
(`iter_prefix` 可保留为兼容包装。)
### A4. `users.rs` 请确认「插件自实现账号操作」的支持路径
上游 `users` 模块有 `create/delete/set_display_name/set_password/grant_temp/...`,但身份类
插件还需要:`set_profile`(部门/用户组)、`set_role`、`batch_update`、`unlock`、
`record_login_failure`(登录失败计数与锁定)、`update_extra`。
我看到 `store::update_users<T,F>` 与 `users::sync_shm` 都是 `pub`,理论上插件可以自实现
这些函数并在写回后调 `sync_shm`——**若这是上游支持的路徑,确认即可,我们不再请求内核加函数**。
若上游认为这些属于通用账号能力,欢迎收进内核,签名可参照:
```rust
pub fn set_profile(username: &str, display_name: Option<&str>, department: Option<&str>,
add_groups: &[String], remove_groups: &[String]) -> Result<User, String>;
pub fn set_role(username: &str, role: &str) -> Result<User, String>;
pub fn batch_update(usernames: &[String], add_groups: &[String], remove_groups: &[String],
department: Option<&str>, role: Option<&str>, unlock: bool) -> Result<Vec<User>, String>;
pub fn unlock(username: &str) -> Result<User, String>;
pub fn record_login_failure(key: &str, now: i64) -> Result<(i64, i64), String>; // (失败次数, 锁定截止)
pub fn update_extra<T, F>(username: &str, f: F) -> Result<T, String>; // 配合 A1 的 extra 通道
```
### A5. `store.rs` 插件文件读写口径
上游公开的只有 `path_in_data(name)`。我方插件普遍使用「插件命名空间」口径
`plugin_path(name)`(`data/plugins/<name>.json`)+ `read_plugin/write_plugin/update_plugin`
泛型封装(含 `update_plugin<T,F>` 返回业务值)。建议上游二选一:
1. 收编 `plugin_path` 系(多插件并存时文件不易互相踩);
2. 或确认 `path_in_data` 是唯一口径、由插件自行拼子目录(我方按此自解)。
### A6. `config.rs` 两处小项
- `PASSWORD_MIN_LEN = 6`:建议提到 8(弱口令门槛;上游若有兼容顾虑可维持,我方在插件层
自行加校验)。
- `COOKIE_NAME = "ipass_admin_session"` 硬编码在内核:换内核/改内核会使存量会话全部失效。
建议会话 cookie 名改由插件声明(内核提供默认值即可)。
---
## B 档:我方本地自解(仅供上游参考,不改不阻塞)
| 项 | 我方处理 |
| --- | --- |
| `audit.rs`(审计日志,仅 sso 使用) | 移入 plugin-sso,内核保持上游原样 |
| 锁定/部门/用户组/临时授权等常量(`ACCOUNT_LOCK_*`、`DEPARTMENT_MAX_LEN`、`GROUPS_*`、`TEMP_GRANT_TTL`、`PASSWORD_MIN_LEN=8`) | 移入 plugin-sso 自己的常量模块 |
| `split_value` rposition(= A2) | 本地补丁,标记待上游采纳后撤销 |
| `iter_prefix_ex`(= A3) | 本地补丁,标记待上游采纳后撤销 |
| User `extra` flatten(= A1) | 本地补丁,标记待上游采纳后撤销 |
| `zone_ready` | 无使用者,直接删除 |
| `users::set_profile/batch_update/...`(= A4) | plugin-sso 内基于 `store::update_users` + `sync_shm` 自实现 |
---
## 已确认无需上游改动的部分
- `http.rs host_port`:上游 `rsplit_once` 实现比我方更简洁,语义等价,直接采纳。
- `store.rs` `write_json` 用紧凑 JSON(我方是 pretty):等价,采纳上游。
- `Plugin` trait(preconfig/postconfig/dispatch_api/zone_load/log_handler)、PLUGINS 装配、
`loc::Switch` 契约、`ctx_index` 注入:两侧已同构,**trait 层零适配可合流**。
## 对照基线
- 上游:`ssw/ipass` `ddd4172`(P0–P5 插件化收尾)
- 我方:`ssw/sso` `912c21a`
- 详细逐文件对照见 `docs/upstream-sync-2026-09-13.md` 第 6 节