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

6.7 KiB
Raw Blame History

致 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 密钥、邮箱、用户组、锁定状态……每个都得再来内核加一轮字段——插件用户不可能提供 覆盖所有场景的字段。

建议加一个内核「持有但不解释」的透传字段(我方已有生产实现,可直接抄):

/// 插件字段:内核持有、透传,不解释。
/// 读文件时未被上面字段认领的 key 自动进 `extra`;写回时展开回顶层。
/// 存量 users.json(含任何插件写入的字段)可原样接管,不会因内核不认识而丢数据。
#[serde(flatten)]
pub extra: BTreeMap<String, Value>,

两点说明:

  • flatten 对上游现有字段零影响(已认领的字段优先),老 users.json 反序列化后原样写回。
  • 若上游采纳,现有 LLM 字段可继续保留 typed(无冲突);也可顺势迁入 extra 让模型瘦身, 由上游定。

A2. state.rs split_value 用 position 会截断内嵌分隔符的值(疑似 bug)

// 上游 ddd4172:取第一个分隔符
let sep = bytes.iter().position(|&b| b == VAL_SEP)?;

共享内存值格式为 payload<SEP>exp。当 payload 自身含 VAL_SEP(OAuth 授权码会话、 带逗号串的注入头 payload 都会),position 取到 payload 内部的分隔符,payload 被截断、 exp 解析失败。应改为 rposition(取最后一个——exp 里不可能再有分隔符):

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

我方生产已按 rposition 运行(这正是当初踩坑后改的)。

A3. state.rs 缺带过期时间的枚举原语 iter_prefix_ex

上游只有 iter_prefix(丢掉 exp)。会话管理类插件(登录会话、OAuth 会话的 kick/清理/列表) 需要 (key, payload, exp) 三元组才能判断条目是否已过期。建议:

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——若这是上游支持的路徑,确认即可,我们不再请求内核加函数。 若上游认为这些属于通用账号能力,欢迎收进内核,签名可参照:

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 节