Files
sso/docs/upstream-core-changes.md
T
ssw f9c2324c47 refactor: 将 ipass-core 内核外置为 deps/ipass 子模块,本仓库仅保留 SSO
- 新增 git submodule deps/ipass(指向 ipass/ipass,pin 9c46e27),内核与通用能力插件统一收归子模块
- 删除仓库内 crates/ipass-core、vendor/ngx-rust、crates/plugin-domain
- source/rust/Cargo.toml 改为 members=[plugin-sso, gateway] + exclude=[../../deps/ipass],ngx/nginx-sys/ipass-core 改为 ../../deps/ipass/... 的 path 依赖
- gateway 移除 plugin-domain 装配:PLUGINS=[SsoPlugin, CorePlugin],去除 ipass_proxy 指令 / domain 开关 / set_flag_domain
- plugin-sso 新增 compat.rs 兼容层,重建被主线内核移除的 4 个 http 辅助函数(body_object/json_body/send_ct/redirect),scim/cas/portal/reset.rs 改走 crate::compat
- 删除 tests/domain-e2e.sh,run-local-e2e.sh 的域名测试调用一并移除(e2e 由 7 套降为 6 套)
- 更新 README/CLAUDE/docs 反映子模块结构;构建已验证:cargo build --release 通过,产出 libsso_gateway.dylib
2026-09-21 15:17:35 +08:00

129 lines
6.7 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 对照)
> **状态(2026-09-21)**:本仓库已不再内置内核,统一通过 `deps/ipass` git 子模块(`ipass/ipass`)消费上游内核;文中「我方 ipass-core」即指该子模块。本文保留为历史对照。
> 背景: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 节