diff --git a/CLAUDE.md b/CLAUDE.md index d5f13f6..1dcc358 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,18 +5,28 @@ ## 一句话定位 -**统一认证服务(SSO)**:nginx 动态模块(`ngx-rust`)+ Rust,单进程,无数据库 / Redis / MQ。 +**iPass 统一网关**的身份能力:nginx 动态模块(`ngx-rust`)+ Rust,单进程,无数据库 / Redis / MQ。 +代码形态是**内核 + 插件**(编译期装配,产出**单个** `.so`): -- **IdP**:OAuth2.0 / OIDC 授权服务器 —— 发 token、登录、introspect、discovery。 -- **IAP**:nginx `access` 阶段门禁,把身份以 `X-Auth-*` 注入后端,业务系统零改造。 -- **协议对齐 MaxKey**:端点别名 + 扁平响应,照抄 MaxKey 文档的应用可直接对接。 +| crate | 职责 | +| --- | --- | +| `ipass-core` | **内核**:共享内存状态、`users.json` 与 API Key 的**唯一读写者**、账号模型、插件契约 | +| `plugin-sso` | **身份插件**:OAuth2.0 / OIDC 授权服务器 + IAP 身份注入 | +| `plugin-domain` | **域名插件**(已迁入):企业域名「子域名 → 后端」转发 + 申请/审核。**同时是「在 `ipass-core` 之上新增一个能力插件」的完整示例** | +| ~~`plugin-llm`~~ | **不迁入**:LLM 上游代理与配额计费属于流量层,与本服务“身份层”的定位分界不变(见文末) | +| `gateway` | **装配层**:module 壳 + 插件注册表 → `libsso_gateway.so` | + +判据:**去掉 SSO,网关还能不能转域名、还能不能代理 LLM?** 能 → 那它就不是内核。 +所以内核是 `ipass-core`,身份只是插件之一。 状态 = `data/` 下两个 JSON(`users.json` / `oauth_clients.json`); **客户端注册表与会话常驻共享内存,热路径零文件 I/O**。 -> **定位差异(不要越界)**:本项目**不做**动态域名转发、LLM 上游代理、用量计费。 -> 代码由内部网关项目剥离而来(`refs/ipass`,仅本地参考、不入库)。 -> 因此这里没有 `$proxy_backend_addr` 这类动态上游变量,`proxy_pass` 由 nginx 配置写死。 +> **为什么是单 .so,而不是「nginx 本来支持的多模块」** +> nginx 动态模块没有稳定 ABI,Rust 侧更没有(每个 cdylib 各链一份 `std`,跨模块传 +> `String` 就是双重 free)。拆开必撞两个坑:① 共享内存 zone 的 tag 不同 → 启动即 +> EMERG;② 同名变量(`auth_user` 等)被后加载者覆盖 get_handler → 行为取决于 +> `load_module` 顺序。源码级论证见 `docs/plugin-architecture-analysis.md`。 --- @@ -57,14 +67,14 @@ cargo build --release 冷编译约 40 秒,增量 1~2 秒。 -> `source/rust/build.rs` **不可删**:macOS 必须 `-undefined dynamic_lookup`——动态模块引用的 +> `source/rust/gateway/build.rs` **不可删**:macOS 必须 `-undefined dynamic_lookup`——动态模块引用的 > nginx 运行时符号由主程序在 `load_module` 时提供,链接时必然未定义。 > `ngx` crate 的 build.rs 也设了,但 `rustc-link-arg` **只对设置它的 crate 生效**、不传给依赖方。 ### 跑测试 ```bash -bash scripts/run-local-e2e.sh # 三套 e2e 全跑(自动起停 nginx + demo 系统) +bash scripts/run-local-e2e.sh # 六套 e2e 全跑(自动起停 nginx + demo 系统) bash scripts/run-local-e2e.sh --keep # 保留进程手工排查 ``` @@ -72,27 +82,25 @@ bash scripts/run-local-e2e.sh --keep # 保留进程手工排查 ## 目录地图(改代码前先看这里) +`source/rust/` 是 Cargo workspace(`cargo build` 在**根**跑,产物 `target/release/libsso_gateway.dylib`): + | 路径 | 职责 | | --- | --- | -| `source/rust/src/lib.rs` | **模块入口**:指令解析、共享内存建表(`state_zone_init`,fork 前一次)、变量注册、两个阶段处理器(IAP access / API content)、`init_process` 播种 admin | -| `source/rust/src/api.rs` | **API 统一分发器**:路由表(精确匹配)+ 鉴权分流(`Guard::Public/User/Admin`)+ 全部 handler | -| `source/rust/src/oauth.rs` | **OAuth2 AS 全部逻辑**:client/code/token 模型、HS256 JWT 签名/验签、PKCE、端点 handler、IAP 身份解析 | -| `source/rust/src/oauth_clients.rs` | 接入方注册表(`reload_shm` / `get` / `all` / `upsert` / `delete` / `view`) | -| `source/rust/src/users.rs` | 账号:播种 admin、创建、改密、重置 Key、角色、部门/用户组校验 | -| `source/rust/src/session.rs` | 管理员登录会话(`sess:` 键 + HttpOnly Cookie,滑动续期) | -| `source/rust/src/state.rs` | 共享内存:根结构、键值编解码(栈上拼 key)、业务包装函数 | -| `source/rust/src/store.rs` | JSON 原子读写(`.tmp` + `rename`)+ 跨 worker 文件锁 + data 目录 | -| `source/rust/src/http.rs` | 请求辅助:参数合并、**两段式请求体读取**、JSON 响应输出 | -| `source/rust/src/util.rs` | 随机数、SHA-256、口令哈希、常量时间比较、时间格式化、日志 | -| `source/rust/src/config.rs` | **全部策略常量**:TTL、长度上限、共享内存键前缀、cookie 名 | -| `source/rust/src/models.rs` | `User` / `OAuthClient` 结构;`groups` 用宽容反序列化(同时接受 `["a"]` 与 `"a,b"`) | +| `gateway/src/lib.rs` | **装配层**:指令解析、共享内存建表(`state_zone_init`,fork 前一次)、`PLUGINS` 数组、API 的 content 阶段处理器与插件分发、`init_process` 播种 admin | +| `crates/ipass-core/src/*` | **内核**:`state`(通用共享内存原语)/ `store`(JSON 原子读写)/ `users`(账号与 Key 的唯一写入口)/ `models`(仅共性字段 + `extra` 透传)/ `config`(仅共性策略常量与键前缀)/ `session`(管理员会话)/ `audit` / `http` / `util` / `plugin`(契约)/ `loc`(location 开关)。**不含** OAuth / TOTP 等个性代码 | +| `crates/plugin-sso/src/*` | **身份插件**:`oauth`(OAuth2/OIDC 全部逻辑 + IAP 身份解析)/ `api`(路由表 + handler)/ `oauth_clients` / `oauth_keys`(OAuth/IAP 协议常量与共享内存键前缀,原属内核 `config`)/ `oauth_state`(OAuthClient 模型 + 注册表/授权码/会话状态,原属内核 `state`/`store`)/ `rsa`(手写 RS256)/ `captcha` / `otp`(TOTP 算法 + 账号侧 TOTP,数据存 `User.extra`) | +| `crates/plugin-domain/src/*` | **域名插件**:`keys`(`sub:` 前缀、企业域名 zone、子域名形状与 TTL 常量)/ `models`(`DomainEntry`)/ `domains`(校验、申请/审核/删除、写穿共享内存)/ `resolve`(access 阶段解析 Host → `$proxy_backend_addr`)/ `api`(8 条管理态 + 账号态路由)/ `lib`(`DomainPlugin` 装配) | + +> `models.rs` 的 `User` 只含**共性字段**(凭据 / 身份声明 / 锁定);iPass 等插件的个性字段 +> (`llm_*` / TOTP 种子等)一律走 `User.extra`(内核透传、不解释),因此内核不认识也能 +> 直接接管任一边的存量 `users.json`,且插件加字段**不必改内核**。 其余: | 路径 | 职责 | | --- | --- | | `source/conf/nginx.conf` | 生产模板:IdP + 管理台 443、IAP 子域、80→443、含 `auth_sub` 的日志格式 | -| `source/conf/nginx.test.conf` | 本机/CI 验证配置(明文 18095-18099),`scripts/run-local-e2e.sh` 会渲染它 | +| `source/conf/nginx.test.conf` | 本机/CI 验证配置(明文 18093-18099:18093/18094 为域名转发回显与转发口),`scripts/run-local-e2e.sh` 会渲染它 | | `source/conf/tls/README.md` | 证书约定、acme.sh 签发、公钥比对校验(**ECC 不能用 `openssl rsa -modulus`**) | | `source/www/admin.html` | 管理台单页(三个 tab:账号 / 接入方 / 接入指南),纯静态 + fetch | | `source/data-seed/` | 种子模板(进版本库):`oauth_clients.json` + `users.json.example` | @@ -240,7 +248,8 @@ curl -s -b 'sso_sid=<值>' http://127.0.0.1:18098/api/v1/me ## 边界:不要做的事 - **不要**引入数据库、Redis、消息队列或额外常驻进程 —— 本项目的价值就是单进程、零依赖。 -- **不要**把流量层能力搬回来(动态域名转发、LLM 上游代理、用量计费)。这是与来源项目的**定位分界**。 +- **LLM 上游代理与用量计费不搬回来**:那是流量层与计费层的职责,与本服务“身份层”的定位分界不变。 + (动态域名转发已作为 `plugin-domain` **示例插件**引入:它侧重“如何在内核之上新增一个能力插件”,而非做量。) - **不要**在 `source/data/` 里手工改文件后期待热生效 —— **共享内存才是运行期真源**,改文件需重启。 - **不要**把 `source/data/` 提交进版本库,也不要在 `refs/` 里提交参考项目。 - **不要**重写整个 `nginx.conf` —— 它很短,**逐点修改**。 @@ -248,3 +257,28 @@ curl -s -b 'sso_sid=<值>' http://127.0.0.1:18098/api/v1/me - **不要**为了「顺手」把 HS256 换成 RS256(或反之):签名算法是给第三方的契约, 切换要走 `docs/roadmap.md` 里的 v2 计划(新旧并行 + `kid` 轮换)。 - 测试不要复用生产 data 目录:用 `source/data/` + 非特权端口(18095-18099),不要占用 80/443。 + +--- + +## 新增一个插件(checklist) + +1. 建 crate:`crates/plugin-xxx`,`Cargo.toml` 里写 `ipass-core.workspace = true`, + 并在根 `Cargo.toml` 的 `members` 里登记。 +2. 实现 `ipass_core::plugin::Plugin`: + - `preconfig` —— 注册 nginx 变量(**两步缺一不可**:`ngx_http_add_variable` 登记 + 名字与 handler,`ngx_http_get_variable_index` 取写入槽位) + - `postconfig` —— 注册阶段处理器(`ngx::http::add_phase_handler::`) + - `dispatch_api` —— 管理接口;**不归自己处理的路由必须返回 `None`**,否则会抢掉别人的接口 + - `zone_load` —— fork 前的共享内存预装载(返回条数,仅用于日志) +3. 在 `gateway/src/lib.rs` 的 `PLUGINS` 数组里加一项——**数组顺序就是 handler 执行顺序**。 +4. location 开关:在 `ipass_core::loc::Switch` 加枚举项,再改 gateway 的 `loc_switch` + 与 `NGX_HTTP_SSO_COMMANDS`。 + ⚠️ 配置指令**只能手工列在 gateway**:`ngx_module_t.commands` 是 null-terminated + 连续数组,不同 crate 的 static 数组无法自动拼接。 +5. 需要给账号加字段 → 在 `ipass-core/src/models.rs` 加 `#[serde(default)]` 字段。 + +**纪律**(违反即失去「共用一份身份」的意义): + +* 插件**不得**直接写 `data/users.json`,一律经 `ipass_core::users`; +* 插件不得自己实现口令校验 / Key 校验 / 锁定——那是内核的事; +* 插件之间不互相依赖,共享信息一律经内核状态表或 nginx 变量。 diff --git a/README.md b/README.md index c99b484..6325c39 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,15 @@ -# SSO —— 统一认证服务(nginx 动态模块 + Rust) +# iPass 统一网关 —— 身份插件(nginx 动态模块 + Rust) + +> 本仓库是 **iPass 统一网关**的代码库,形态是**内核 + 插件**(编译期装配,产出单个 `.so`): +> +> | crate | 职责 | +> | --- | --- | +> | `ipass-core` | 内核:共享内存状态、`users.json` 与 API Key 的**唯一读写者** | +> | `plugin-sso` | 身份插件(本 README 的主体):OAuth2/OIDC + IAP | +> | `plugin-domain` | 域名插件:企业域名「子域名 → 后端」转发(新增能力插件的完整示例) | +> +> 判据:去掉 SSO,网关仍能转域名、仍能代理 LLM → 所以内核不是身份,**身份只是插件之一**。 +> 架构论证见 `docs/plugin-architecture-analysis.md`。 自包含的 **OAuth2.0 / OIDC 身份提供者(IdP)** 与 **身份感知代理(IAP)**, 以 nginx 动态模块形式运行:加载进 nginx,不引入数据库、Redis、消息队列或任何额外常驻进程。 @@ -10,8 +21,9 @@ - **协议兼容 MaxKey**:提供 `/oauth/v20/*`、`/oauth2.0/*` 端点别名与 context-path 归一化, 照抄 MaxKey 文档的第三方应用不用改一行代码。 -> **定位**:身份层,不是流量层。本服务**不做**动态域名转发、LLM 上游代理、用量计费。 -> 代码由内部网关项目剥离而来(来源存档见 `refs/ipass`,不入版本库)。 +> **身份与流量分离**:`plugin-sso` 只回答「你是谁」与「把这个身份告诉后端」。 +> 动态域名转发、LLM 上游代理、用量计费属于**其它插件**(来源存档见 `refs/ipass`), +> 与身份插件共用同一份 `users.json`、同一把 API Key——由 `ipass-core` 统一读写。 --- @@ -74,9 +86,13 @@ sso/ │ └── screenshots/ 管理台与登录页截图 ├── source/ 可部署产物(代码 + 配置 + 静态页) │ ├── rust/ 动态模块源码(Cargo workspace,vendor 了 ngx-rust) +│ │ ├── crates/ipass-core/ 内核:状态 / 账号 / Key 的唯一读写者 / 插件契约 +│ │ ├── crates/plugin-sso/ 身份插件:OAuth2 / OIDC + IAP +│ ├── crates/plugin-domain/ 域名插件:企业域名子域名转发(插件示例) +│ │ └── gateway/ 装配层:module 壳 + 插件注册表 → libsso_gateway.so │ ├── conf/ │ │ ├── nginx.conf 生产模板(TLS、IAP 子域、日志字段) -│ │ ├── nginx.test.conf 本机/CI 验证配置(明文端口 18095-18099) +│ │ ├── nginx.test.conf 本机/CI 验证配置(明文端口 18093-18099) │ │ └── tls/README.md 证书约定、acme.sh 签发与校验 │ ├── www/admin.html 管理台单页(纯静态 + fetch) │ ├── data-seed/ 种子模板(进版本库) diff --git a/docs/maxkey-migration-analysis.md b/docs/maxkey-migration-analysis.md new file mode 100644 index 0000000..24755a2 --- /dev/null +++ b/docs/maxkey-migration-analysis.md @@ -0,0 +1,132 @@ +# MaxKey 能力迁移分析(refs/maxkey → 本项目) + +> 分析日期:2026-09-12 +> 参照物:`refs/maxkey/`(dromara MaxKey,Java/Gradle,44 张表的完整 IAM/IDaas) +> 本体:本项目(nginx 动态模块 + Rust,OAuth2/OIDC IdP + IAP,文件+共享内存存储,零外部依赖约定) + +## 结论(先看这里) + +MaxKey 值得抄的不是"大而全",而是三类东西:**纯算法与协议语义**(直接可移植)、**域模型设计**(表结构即最佳实践文档)、**安全运营闭环**(锁定/审计/策略,本项目完全缺失)。按本项目的硬约束(无 DB、无 Redis、零新增依赖、"身份层不做流量层"),能力分四档: + +| 档位 | 数量 | 判断标准 | +| --- | --- | --- | +| P0 建议迁移 | 7 项 | 纯逻辑可 Rust 重写,且补齐 IAP 安全短板 | +| P1 视需求迁移 | 5 项 | 有外部依赖或体积成本,先评估再动 | +| P2 低优先 | 5 项 | 有价值但当前定位用不上 | +| 不建议迁移 | 6 项 | 重度绑定 Java 生态,或与"身份层"定位冲突 | + +--- + +## P0:建议迁移(纯逻辑,直接补短板) + +1. **RS256 + JWKS 签发/验签** — 已在 roadmap v2 规划。 + MaxKey 实证:`maxkey-commons/maxkey-crypto/`(JWS/JWE 签发验签、X509/keystore)。 + 抄它的点:JWKS 输出格式、`kid` 轮换语义(旧公钥保留至最后一批旧令牌过期)。 + +2. **登录失败锁定** — 本项目目前**无任何防爆破机制**,这是 IAP 场景最大安全缺口。 + MaxKey 实证:`mxk_history_login` + 登录失败计数策略。移植成本极低:`users.json` 里加 + `failed_count / locked_until` 字段,共享内存同步,无需新表。 + +3. **登录历史 / 审计日志** — MaxKey 用 `mxk_history_login` / `mxk_history_login_apps` / + `mxk_history_event` 三张分表。本项目可落成 append-only JSONL 文件(`data/audit/`), + 记录:时间、用户、IP、UA、grant 类型、成功/失败。管理台加一个只读列表即可。 + 这是"真实流量看板"问题的 SSO 侧基础设施。 + +4. **密码策略** — MaxKey:`mxk_cnf_password_policy`(长度/复杂度/有效期/历史密码)。 + 本项目最小集:长度 ≥ 8 + 重置时强制改密 + 可选复杂度,配置进现有 `config.rs`。 + 纯校验逻辑,半天工作量。 + +5. **TOTP 双因子** — MaxKey:`maxkey-starter-otp/`(HOTP/TOTP 算法族)。 + 纯算法(RFC 6238,HMAC-SHA1 + 30s 步长),Rust 用已有 `sha2`+手写 HMAC 即可, + 不新增依赖。用户侧字段:`totp_secret` + `totp_enabled`。注意配套要做**绑定流程** + (otpauth:// URI 展示)与登录时的第二因子校验分支。 + +6. **图形验证码** — MaxKey 用魔改 kaptcha(Java 生态绑定,不抄实现)。 + 本项目直接生成 **SVG 验证码**(数字/字母干扰线),零依赖可做, + 挂在 `/oauth/authorize` 登录页与找回密码入口。 + +7. **在线会话管理 / 踢出** — MaxKey:`SessionController`(在线会话查看/踢出)。 + 本项目 session 已在共享内存(`session.rs`),天然支持:管理台列出活跃会话 + + 单条踢出 + 全端下线。改动量小,运维价值高。 + +--- + +## P1:视需求迁移(先评估成本) + +8. **SCIM 2.0 身份供给** — MaxKey:`maxkey-web-apis/maxkey-web-api-scim/` + (User/Group/EnterpriseUser/ServiceProviderConfig 完整资源模型)。 + 价值:外部系统(HR、上游 IdP)可用标准协议推送用户进来。资源模型清晰, + 就是 CRUD,落 `users.json`/`groups` 现有模型可行;工作量主要在过滤语义 + (`userName eq "..."`)与分页。**若确定有上游系统对接需求再做。** + +9. **CAS 协议端点(v2/v3 validate)** — 延续 v1"照抄 MaxKey 文档接入方零改造"的思路, + 补 `/cas/sso/validate`、`/p3/proxyValidate` 等端点,让 CAS 客户端也能直连。 + 票据校验是纯逻辑;但 CAS 生态在国内老系统里存量不小,值得排期。 + +10. **LDAP / AD 认证源** — MaxKey:`realm/ldap`(OpenLDAP/AD)。企业场景刚需,但 + Rust 侧需要 LDAP 客户端库(`ldap3` 依赖体积不小,且需 vendor)。 + 替代路径:先用 P1-8 的 SCIM 或 P2-13 的同步连接器"拉取"而非"直连"。 + +11. **身份同步连接器(钉钉 / 企微 / 飞书 / AD)** — MaxKey: + `maxkey-synchronizers/maxkey-synchronizer-/`。钉钉/企微/飞书三个就是 + HTTP API 调用(分页拉用户+组织),交互协议可直接照抄;AD/LDAP 需 LDAP 库。 + 适合做成定时任务(本项目无后台进程,可用 nginx timer 或外部 cron curl 管理端点触发)。 + +12. **自助密码重置(邮箱/短信找回)** — MaxKey:`mxk_register` + 邮件/短信 provider + (阿里云/腾讯云/网易云信,`maxkey-starter-sms/`)。依赖外部发信通道;若做, + 建议 provider 抽象成配置驱动的 HTTP 调用(与 AIMALL GenericHTTPTool 同思路)。 + +--- + +## P2:低优先(有价值,当前定位用不上) + +13. **WebAuthn / Passkey** — MaxKey:`maxkey-starter/maxkey-starter-passkey/` + (含 `mxk_user_passkeys` 表)。方向正确但 Rust 零依赖下验签链很重 + (COSE/CTAP2/attestation),且 RSA 大数运算本来就在 v2 才引入。等 v2 落地后再评估。 + +14. **社交登录 / 扫码登录** — MaxKey 基于 JustAuth + 自研 WeLink/飞书/企微 request。 + 本项目作为**企业内部身份层**,社交登录价值有限;若 souyi.net.cn C 端要用,另起服务。 + +15. **SAML 2.0** — MaxKey 重度绑定 OpenSAML。XML-DSig 签名在 Rust 零依赖下工作量 + 数倍于整个现有 oauth.rs。除非有明确 SAML SP 客户,否则不排期。 + +16. **FormBased / TokenBased / ExtendApi 协议** — 老式企业代填/票据协议。 + TokenBased 的"票据换会话"语义可作为 IAP 票据机制参考;FormBased 代填不建议。 + +17. **ip2location 归属地解析** — MaxKey 内置登录 IP 归属地。审计日志做精致了再加。 + +--- + +## 不建议迁移(明确不做) + +| 能力 | 理由 | +| --- | --- | +| Kerberos/SPNEGO、Ws-Federation | 重度绑定 JAAS/GSSAPI;IAP 场景可用 nginx 层方案替代 | +| Spring Cloud Gateway 网关(maxkey-gataway) | 本项目定位就是"身份层不做流量层",直接冲突 | +| 多租户(mxk_institutions) | 放大全链路复杂度,当前单租户足够 | +| 树形组织架构 | roadmap 已有明确"不做"决定,维持 | +| MyBatis/JPA 持久层、44 张表整体照搬 | 只抄域模型设计思路,不抄存储形态(本项目文件+共享内存) | +| kaptcha、管理台前端(maxkey-web-frontend) | Java/前端技术栈绑定,重写无参考价值 | + +--- + +## 域模型参考(照抄设计而非表) + +MaxKey 的 44 张表里,对本项目最有参考价值的三组设计: + +- **应用-协议明细分离**:`mxk_apps` + `mxk_apps_oauth_client_details`/`saml_v20_details`/ + `cas_details`/…。本项目现有 `oauth_clients.rs` 已是同构;未来若补 CAS/SCIM, + 沿用"应用主表 + 协议明细"的形状,不要往应用主表里塞协议字段。 +- **审计三分表**:登录历史 / 应用登录历史 / 事件,按时间append。对应 P0-3。 +- **配置表与业务表分离**:`mxk_cnf_*`(密码策略、短信、邮件、LDAP 上下文)独立成表。 + 本项目对应物是 `config.rs`,未来配置项变多时按此分组,不要混进业务数据。 + +## MaxKey 源码证据索引 + +- 认证方式总入口:`maxkey-authentications/maxkey-authentication-provider/…/authn/provider/impl/` +- OAuth2/OIDC 端点:`maxkey-protocols/maxkey-protocol-oauth-2.0/…/endpoint/`(discovery 在 `wellknown/`) +- SCIM:`maxkey-web-apis/maxkey-web-api-scim/` +- 会话管理:`maxkey-webs/maxkey-web-mgt/…/web/access/controller/SessionController` +- 同步连接器:`maxkey-synchronizers/maxkey-synchronizer-{ad,ldap,jdbc,dingtalk,workwechat,feishu}/` +- OTP 算法:`maxkey-starter/maxkey-starter-otp/` +- 全量表结构:`sql/v4.2.0/maxkey.sql` diff --git a/docs/plugin-architecture-analysis.md b/docs/plugin-architecture-analysis.md new file mode 100644 index 0000000..3b1dba7 --- /dev/null +++ b/docs/plugin-architecture-analysis.md @@ -0,0 +1,187 @@ +# 插件化架构:iPass 统一网关(core + 插件) + +> 问题:iPass 有「动态域名 + LLM 路由」,SSO 有「身份 / Key / OAuth」, +> nginx 本来就支持多模块——能不能做成插件模式,共用一个用户基础认证与 Key,其它由插件来做? +> +> **定稿(2026-09-13)**: +> 1. 内核是 **`ipass-core`(网关内核)**,**SSO 是其中一个插件**,与 `domain`、`llm` 平级。 +> 身份不是内核——内核只回答「请求是谁、状态存哪、配置怎么装配」。 +> 2. **`users.json` 全局共用一份,由 `ipass-core` 独占读写**,插件只读不写。 +> 3. 插件是 **Rust crate 级(编译期装配,产出单个 `.so`)**,不是运行时加载多个动态模块。 + +--- + +## 一、为什么是 ipass-core,而不是 sso-core + +内核的职责应该是「所有插件都要用、且只有一份才有意义」的东西: + +| 能力 | 归属 | 理由 | +| --- | --- | --- | +| 共享内存状态表 / 文件写锁 | core | 只能有一个 zone;多份就失去「热路径零文件 I/O」的意义 | +| `users.json` 读写与 Key 索引 | core | 一处吊销处处生效;插件各写一份就等于没共用 | +| 账号模型 `User` | core | 身份是全局概念,域名审批与 LLM 配额都要挂在同一个账号上 | +| 会话 / 登录失败锁定 / 审计 | core | 与账号强绑定,跨插件共享 | +| OAuth2 / OIDC 签发与校验 | plugin-sso | 一种认证协议,不是网关必需品 | +| IAP 身份注入 | plugin-sso | 同上 | +| 动态域名映射与审批 | plugin-domain | 独立业务 | +| LLM 路由 / 配额 / 计费 | plugin-llm | 独立业务 | + +一句话判据:**去掉 SSO,网关还能不能转域名、还能不能代理 LLM?** 能 → 那它就不是内核。 + +## 二、「nginx 支持多模块」≠ 插件 ABI + +三个硬约束决定了多 `.so` 只能算「同源编译的多个 C 模块」,不是插件生态: + +1. **模块必须与 nginx 二进制同源**。动态模块的 `ngx_module_t` 带 `version` / + `signature`(含 `NGX_MODULE_SIGNATURE` 一长串编译期特性位),不匹配直接拒绝加载。 +2. **Rust 没有稳定 ABI**。每个 cdylib 静态链进自己的一份 `std`。跨 `.so` 传递 + `Box` / `String` / `Vec` 意味着「A 的分配器分配、B 的分配器释放」→ 双重 free。 +3. **加载顺序影响行为**(下一节有源码级证据)。 + +## 三、如果硬上多 .so,会踩的三个坑(已在 nginx 1.30.4 源码核对) + +### 坑 1:共享内存 zone 的 tag 必须相同,否则启动即失败 + +`src/core/ngx_cycle.c`: + +```c +if (tag != shm_zone[i].tag) { + ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, + "the shared memory zone \"%V\" is " + "already declared for a different use", &shm_zone[i].shm.name); + return NULL; // ← 直接启动失败 +} +``` + +而两边现在传的都是**自己模块的 `ngx_module_t` 地址**: + +```rust +// source/rust/src/lib.rs:451 +ngx_shared_memory_add(cf, &raw mut name, size, (&raw mut ngx_http_sso_module).cast()) +// refs/ipass/rust/src/lib.rs:824 +ngx_shared_memory_add(cf, &raw mut name, size, (&raw mut ngx_http_ipass_module).cast()) +``` + +**现在一行不改,同进程加载必然冲突。** 想共用就得把 tag 改成约定值(例如都传 `NULL`), +且 `size` 必须一致(或后者传 0 表示不校验)。 + +### 坑 2:同名变量会被后加载者「劫持」getter + +两边注册了**完全相同的五个变量**: + +```rust +static AUTH_VAR_NAMES: [&str; 5] = ["auth_user","auth_email","auth_groups","auth_sub","auth_token"]; +``` + +`src/http/ngx_http_variables.c`:同名 + `NGX_HTTP_VAR_CHANGEABLE` 时 +`ngx_http_add_variable` **返回已存在的那个 `v`**(不报错、不新建)。而两边注册后都做: + +```rust +unsafe { (*var).get_handler = Some(auth_var_get); } // 覆盖 +``` + +`ngx_http_get_variable_index` 对同名又返回**同一个 slot**。结果是: + +> `$auth_user` 取哪个模块的 handler、以及 access 阶段谁最后写入该 slot, +> **完全取决于 `load_module` 的先后顺序**。 + +这类 bug 不报错,只会「某些部署下身份对、某些部署下身份错」。 + +### 坑 3:跨 .so 复用 Rust 结构是 UB + +`ShmRoot { map: RwLock>, file_lock: RwLock<()> }` 是 Rust 布局。 +两个 `.so` 各自编译,只要 rustc 版本 / 优化级别 / 结构定义有任一差异, +字段偏移或 `RwLock` 内部表示就可能对不上 → 静默内存损坏。 +要跨模块共享只能换成 `#[repr(C)]` + `magic` + `version` + `size` 三重校验的桥接头。 + +## 四、定稿结构 + +``` +source/rust/ +├── Cargo.toml # [workspace] members = crates/* + gateway +├── vendor/ngx-rust/ # 保持(path 依赖,不可走 crates.io / git) +├── crates/ +│ ├── ipass-core/ # 网关内核:唯一读写 users.json 的地方 +│ │ └── src/{config,models,users,store,state,session,util,http,audit,plugin}.rs +│ ├── plugin-sso/ # 身份插件:OAuth2/OIDC + IAP 注入 +│ │ └── src/{oauth,oauth_clients,rsa,otp,captcha,api}.rs +│ ├── plugin-domain/ # 动态域名(后续迁入) +│ └── plugin-llm/ # LLM 路由 / 配额(后续迁入) +└── gateway/ # 装配层:模块壳 + 插件注册表 → 单个 .so + └── src/lib.rs +``` + +### 插件契约 + +```rust +pub trait Plugin { + fn name(&self) -> &'static str; + fn commands(&self) -> &[ngx_command_t]; // 配置指令(sso_api / ipass_proxy / ipass_llm ...) + fn preconfig(&self, cf) -> bool; // 注册 nginx 变量 + fn postconfig(&self, cf) -> bool; // 注册 phase handler + fn api_routes(&self) -> &[Route]; // 管理接口 + fn access(&self, r) -> Option; // access 阶段(可选) +} +``` + +装配层按声明顺序依次调用 → **handler 顺序显式可控**(这正是多 .so 方案里最难保证的一点)。 + +### 共享内存键前缀(现状已天然不冲突,直接沿用) + +| 归属 | 前缀 | +| --- | --- | +| core | `sess:` `fail:` `ukey:` | +| plugin-sso | `sso:` `oac:` `ocl:` | +| plugin-domain | `sub:` | +| plugin-llm | `up:` `rl:` `st:` `ust:` `ums:` | + +> `ukey:`(API Key → 身份索引)归 core:Key 由 core 签发与吊销,索引就必须由 core 维护, +> 否则会出现「Key 已重置但旧索引还在」的窗口。 + +## 五、`users.json`:共用一份,core 独占读写 + +- **物理上只有一份** `data/users.json`;插件**只读**,写入一律经 `ipass_core::users` +- **Schema 取并集**,所有新增字段 `#[serde(default)]`,存量文件可直接接管: + + | 来源 | 字段 | + | --- | --- | + | 共用 | `username` `display_name` `role` `salt` `pwd_hash` `api_key` `email` `department` `groups` `created_at` | + | SSO | `failed_count` `locked_until` `totp_secret` `totp_enabled` | + | 域名 | `temp_grant_until` | + | LLM | `allowed_models` `llm_rpm` `llm_daily` | + +- `groups` 用**宽容反序列化**(接受 `["rd","eng"]` 与 `"rd,eng"`): + 只认数组会让外部目录导出的 `users.json` 整体反序列化失败,表现为「账号全部消失」 +- Schema 版本与迁移逻辑由 core 负责;插件不得自行扩展 `User` 字段, + 需要扩展时在 core 里加 `#[serde(default)]` 字段 + +## 六、落地路径 + +| 阶段 | 内容 | 验收 | +| --- | --- | --- | +| **P0** | 建 workspace;config/models/store/state/session/users/audit 迁入 core;User 取并集 | `run-local-e2e.sh` 五套全绿 | +| **P1** | 插件 trait + 路由注册表;sso 完成插件化;handler 顺序显式化 | 仅编 `--features sso` 与全量都能跑通 | +| **P2** | 迁入 plugin-domain(从 `refs/ipass` 移植,去掉其重复的 oauth/users) | 域名 e2e 全绿 | +| ~~P2'~~ | ~~迁入 plugin-llm~~ —— **已决定不迁入**:LLM 上游代理与配额计费属流量层,与本服务定位分界不变(已从 workspace 移除) | — | +| P3 | (可选)确需独立发版时才做 C ABI bridge,按第三节三条纪律执行 | — | + +## 七、遗留待定 + +- 仓库归属:当前在 `ssw/sso` 仓库内改造,产品名已变为「iPass 统一网关」, + 是否新建 `ssw/ipass` 仓库并迁移,由你定。 +- `refs/ipass` 目前是带本地 `.git` 的存档副本(无 remote、不入本仓库版本控制), + P2 移植时按「新代码为准、旧实现仅作参考」处理。 + +--- + +## 附:本次查证用到的源码位置 + +| 论断 | 位置 | +| --- | --- | +| zone tag 不同 → EMERG 启动失败 | `src/core/ngx_cycle.c` → `ngx_shared_memory_add` | +| 同名 + CHANGEABLE → 返回已有变量而非新建 | `src/http/ngx_http_variables.c` → `ngx_http_add_variable` | +| sso 的 zone tag = `&ngx_http_sso_module` | `source/rust/src/lib.rs:451` | +| ipass 的 zone tag = `&ngx_http_ipass_module` | `refs/ipass/rust/src/lib.rs:824` | +| 两边注册同名 `$auth_*` 且覆盖 get_handler | `source/rust/src/lib.rs:254-262`、`refs/ipass/rust/src/lib.rs:89` | +| 键前缀全景 | `refs/ipass/rust/src/config.rs:66-101` | +| 代码重复量(oauth 425 / users 525 / models 234 / state 150 行差异) | 两仓库同名文件 diff | diff --git a/docs/roadmap.md b/docs/roadmap.md index 2ae27d4..bd8213d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -17,7 +17,7 @@ --- -## [ ] v2:升级 RS256 签名 + `/oauth/jwks`,让第三方本地验签 +## [x] v2:升级 RS256 签名 + `/oauth/jwks`,让第三方本地验签(2026-09-13 完成) ### 为什么 @@ -64,23 +64,26 @@ ### 验收 -- [ ] `GET /.well-known/jwks.json` 返回可用 JWKS,`n`/`e` 为 base64url; -- [ ] 用 JWKS 公钥在**不访问本服务**的前提下,本地验签通过 access_token 与 id_token; -- [ ] `alg` 传 `none` / 传 HS256 但用公钥当密钥 → 一律拒绝; -- [ ] 轮换后:新令牌带新 `kid`,旧令牌仍能验签直到过期; -- [ ] 现有三套 e2e 全绿(HS256 存量路径不回归); -- [ ] 新增一套 e2e:抓 JWKS → 本地验签 → 断言 `iss`/`aud`/`exp`。 +- [x] `GET /.well-known/jwks.json` 返回可用 JWKS,`n`/`e` 为 base64url; +- [x] 用 JWKS 公钥在**不访问本服务**的前提下,本地验签通过 access_token 与 id_token(e2e 内嵌纯 Python `pow()` 验签); +- [x] `alg` 传 `none` / 传 HS256 但用公钥当密钥 → 一律拒绝; +- [x] 轮换模型落地(`kid` = 公钥 SHA-256 前 16 位 hex;`from_jwk` 容忍缺私钥分量,历史公钥仍可验); +- [x] 现有三套 e2e 全绿(HS256 存量路径不回归); +- [x] 新增一套 e2e(`tests/rs256-jwks-e2e.sh`:discovery→JWKS→签发→本地验签→篡改/伪造拒绝→introspect)。 ### 注意 - **`iss` 一致性**是历史上最容易踩的坑:`OAUTH_ISSUER` 必须与浏览器实际访问的 host 一致。 第三方本地验签会把 `iss` 与 discovery 的 `issuer` 逐字符比对,不一致直接失败。 +- **实现落点(2026-09-13)**:RSA 全手写(`src/rsa.rs`:Miller-Rabin、扩展欧几里得模逆、 + Montgomery CIOS、CRT、PKCS#1 v1.5 EMSA),零新增 crates 依赖;私钥存 + `OAUTH_JWK_DIR/active.jwk.json`(JWK 分量 JSON,非 PEM)。 - 私钥**绝对不进版本库**(`.gitignore` 放行规则要写对,别把 `jwks/` 加进白名单)。 - 不要返回空 JWKS:客户端会缓存住「无密钥」状态,问题排查时表现为「一直验签失败、日志无异常」。 --- -## [ ] 用户管理界面:角色 / 部门 / 用户组的可视化维护 +## [x] 用户管理界面:角色 / 部门 / 用户组的可视化维护(2026-09-13 完成) ### 为什么 @@ -102,6 +105,10 @@ ### 做什么 +0. **批量维护接口**(实现时新增):`POST /api/admin/users/batch`, + `usernames` + `add_groups` / `remove_groups` / `department` / `role` / `unlock` 任意组合, + 单次文件锁内原子生效;批量降级同样受「至少保留一个管理员」红线约束; + 不存在的账号只跳过(`skipped` 回显)不中断整批。 1. **账号表行内编辑**(或在侧滑面板里): - `role`:下拉(`admin` / `user`);目标账号是最后一个管理员时**禁用降级**并给出原因, 与后端校验保持一致的文案,避免「点了才报错」。 @@ -119,13 +126,14 @@ ### 验收 -- [ ] 能给账号改角色、部门、用户组,刷新页面后仍在; -- [ ] 最后一个管理员无法被降级(前端禁用 + 后端兜底都生效); -- [ ] 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确; -- [ ] 按角色 / 部门 / 用户组能筛出正确结果; -- [ ] 改完用户组后,经 IAP 访问后端拿到的 `X-Auth-Groups` 同步变化 - (端到端验证:改组 → 带会话请求 demo 系统的 `/api/echo` → 断言头部); -- [ ] `admin.html` 内无内联 `onclick`,无未清理的全局状态(沿用 v1 的写法约定)。 +- [x] 能给账号改角色、部门、用户组,刷新页面后仍在(角色下拉即改;部门/组点击就地编辑,Enter 保存); +- [x] 最后一个管理员无法被降级(前端 confirm + 失败回滚,后端红线兜底;含批量降级红线,e2e 断言); +- [x] 非法输入(含控制字符 / 超长部门名 / 超组数上限)被拒且提示明确(e2e 断言参数校验); +- [x] 按角色 / 部门 / 用户组(+ 关键字 / 只看已锁定)能筛出正确结果,头部提示「筛选出 n / m 个」; +- [x] 改组后新签令牌经 IAP 注入的 `X-Auth-Groups` 立即反映新组(e2e 断言);并固化语义: + **Bearer 注入是令牌签发时刻的 claims 快照**——改组不影响已签发的旧令牌(到期前), + 下游要即时生效就让用户重登/重取令牌,或走 SSO 会话(cookie)路径(e2e 断言双口径); +- [x] `admin.html` 内无内联 `onclick`,无未清理的全局状态(沿用 v1 的写法约定)。 ### 注意 @@ -146,3 +154,26 @@ 且与本服务「身份层」的定位不符。确有需要时,让下游业务系统用 `X-Auth-Groups` 自己做映射。 - **不要把 OIDC 的 scope / claim 自定义能力做成界面配置**。claim 形状是第三方客户端的契约, 改动需要双方同步,属于「按需改代码」而不是「运营自助」。 + +--- + +## 插件化改造(2026-09-13) + +架构定稿:内核是 **`ipass-core`**,**SSO 是插件之一**(与 `plugin-domain` / `plugin-llm` 平级); +`users.json` **全局共用一份,由内核独占读写**,插件只读不写。 + +- [x] workspace 拆分:`crates/ipass-core` + `crates/plugin-sso` + `gateway`,产出**单个** `.so` +- [x] 内核收口:`config`(仅共性)/ `models`(仅共性 + `extra` 透传)/ `store` / `state`(仅通用原语)/ `session` / `users` / `audit` / `http` / `util`(个性能力 TOTP 归 `plugin-sso` 的 `otp.rs`;OAuth 协议常量/键前缀归 `oauth_keys.rs`、OAuthClient 模型与注册表/授权码/会话状态归 `oauth_state.rs`,均原属内核 `config`/`state`/`store`) +- [x] `User` 共性字段 + `extra` 透传:iPass 等插件的个性字段(`llm_*` / `temp_grant_until` / TOTP 种子等) + 经 `extra` 落盘,全部 `#[serde(default)]`;已验证 iPass 存量 `users.json` **无字段丢失** +- [x] 插件契约 `Plugin::{preconfig, postconfig, dispatch_api, zone_load}`; + 装配顺序 = `gateway` 里 `PLUGINS` 数组的顺序,**显式可控** +- [x] 五套 e2e 全绿(rc=0),行为与重构前完全等价 +- [x] 六套 e2e 全绿(rc=0),新增 `tests/domain-e2e.sh`(域名插件:鉴权 / 转发 / 申请审核 / 写穿生效) +- [x] P2(部分):迁入 `plugin-domain`(域名插件)作为“新增能力插件”的完整示例:crate + `sso_domain` 开关 + 编译装配 + 用例(`tests/domain-e2e.sh`,43 项)。 + **`plugin-llm` 明确不迁入**:LLM 上游代理与配额计费属流量层,与本服务定位分界不变(已从 workspace 移除)。 +- [ ] 仓库归属:是否新建 `ssw/ipass` 仓库(当前仍在 `ssw/sso`) + +> 顺带的收益:iPass 与 SSO 原先各有一份 `oauth.rs`(差异 425 行)、`users.rs`(525 行)、 +> `models.rs`(234 行),内核化后只保留一份。 +> 架构论证(为什么不拆多 .so)见 `docs/plugin-architecture-analysis.md`。 diff --git a/docs/task-plan.md b/docs/task-plan.md new file mode 100644 index 0000000..ae10fca --- /dev/null +++ b/docs/task-plan.md @@ -0,0 +1,55 @@ +# 任务计划:MaxKey 能力迁移落地(2026-09-12)✅ 已全部完成(2026-09-13) + +> 依据:`docs/maxkey-migration-analysis.md`(P0×7)+ `docs/roadmap.md`(v2 + 用户管理界面) +> 保障手段:每项实现都带 e2e 断言;可借鉴的 MaxKey 测试用例逐项标注。 +> 约束:零新增 crates.io 依赖(SHA-1、RSA、大数运算全部手写);存储沿用 users.json + 共享内存,不引入 DB。 + +## 执行顺序与验收 + +| # | 任务 | 落点 | 验收(e2e 断言) | 借鉴的 MaxKey 测试 | +| --- | --- | --- | --- | --- | +| ✅ 1 | 登录失败锁定(账号维度) | models/users/api/oauth/config | 连错 5 次锁定 600s;锁定期间密码正确也 423;到期自解锁;管理台可解锁 | mxk_history_login 失败计数语义 | +| ✅ 2 | 密码策略 | config/users | 短于 8 位拒;纯数字/纯字母拒;改密/建号/重置三入口一致 | mxk_cnf_password_policy 字段 | +| ✅ 3 | 审计日志 JSONL | 新模块 audit.rs + api | 登录成败/发令牌/管理操作都有行;管理台可查;>5MB 自动轮转 | mxk_history_login/event 三分表字段 | +| ✅ 4 | 在线会话查看/踢出 | state/api | sess:/sso: 均可列出(含过期过滤);按 token 或按用户踢;被踢会话立即 401 | SessionController 列表/踢出 | +| ✅ 5 | SVG 图形验证码 | 新模块 captcha.rs + oauth/api | 开关 `OAUTH_CAPTCHA=1` 时登录页出验证码、错码拒绝;缺省关(存量 e2e 不回归) | kaptcha 行为(不用其实现) | +| ✅ 6 | TOTP 双因子 | 新模块 otp.rs + users/api/oauth | RFC 4226/6238 标准向量通过;绑定→启用→登录必须带码;码错/缺失拒绝 | maxkey-starter-otp:HmacOTPTest / TimeBasedOTPTest(Base32 seed + 30s 步长 + 6 位截断) | +| ✅ 7 | RS256 + JWKS(roadmap v2) | 新模块 rsa.rs + oauth | JWKS 端点出 n/e(base64url);本地验签通过;alg=none / alg 混淆拒绝;HS256 存量可验;新 e2e 覆盖 | JWS/JWE 签发验签语义(maxkey-crypto) | +| ✅ 8 | 用户管理界面 | www/admin.html | 行内改角色/部门/组;筛选;批量加组;最后管理员禁用降级;组名逗号即时切分 | MaxKey 用户管理页交互 | +| ✅ 9 | 全量回归 + roadmap 更新 | tests/ + roadmap.md | 四套 e2e 全绿;roadmap 勾选 | — | + +## 关键设计决定(偏离/补充说明) + +- **验证码缺省关闭**(`OAUTH_CAPTCHA=1` 开启):验证码图形无法被 curl e2e 读取, + 缺省开会让全部存量 e2e 失效;生产开启后,浏览器路径正常出码。 +- **锁定是账号维度**(users.json 新字段 `failed_count`/`locked_until`),与既有 + `fail:` IP 维度限速叠加;登录低频路径直接读文件,符合现有分层。 +- **TOTP 的 HMAC-SHA1 手写**(sha2 crate 没有 SHA-1):RFC 6238 主流 authenticator + 默认 SHA1/6 位/30s,必须兼容 Google Authenticator。 +- **RSA 手写范围**:`modpow`(Knuth D 除法)+ Miller-Rabin 素性 + PKCS#1 v1.5 签名。 + 私钥存 `OAUTH_JWK_DIR/active.jwk.json`(分量的 base64url JSON,非 .pem—— + 手写 ASN.1/PEM 编解码收益低,roadmap 的 `.pem` 命名放宽,其余轮换语义照做)。 +- **管理台密码策略例外**:种子管理员 `admin/123456` 不走 create 校验(历史行为), + 但一旦重置即受新策略约束。 + +## 完成情况(2026-09-13 收尾) + +- 9/9 全部完成;回归从「三套」扩为**五套**(`scripts/run-local-e2e.sh`,全绿 rc=0): + 1. OAuth2/OIDC 基线;2. MaxKey 互通 + demo 接入;3. 管理接口·OAuth 接入方(31 项); + 4. RS256 + JWKS 本地验签(14 项,含篡改 / alg=none / alg 混淆拒绝); + 5. 管理接口·账号批量维护(39 项,新增)。 +- RS256 内核为**手写零依赖 RSA-2048**(Miller-Rabin + 扩展欧几里得模逆 + Montgomery CIOS + + CRT + PKCS#1 v1.5),经独立二进制 × Python `pow()` 互证 3 轮随机密钥 roundtrip 全绿。 + 因 `cargo test` 链接 nginx 符号,单测走 `/tmp/*_standalone.rs` + rustc 方案。 +- 批量维护新增 `POST /api/admin/users/batch`(单次文件锁内组合:加组/移组/设部门/改角色/解锁, + 「至少保留一个管理员」红线在批量口径下同样生效)。 +- 用户管理界面:筛选(关键字/角色/部门/组/已锁定)、勾选批量条、行内编辑 + (角色下拉即改、部门/用户组点击就地编辑,Enter 保存 / Esc 取消 / 失焦提交)。 +- 凭据治理:本地 e2e 口令与签名密钥统一进 `.env`(gitignore,模板 `.env.example`), + 脚本经 `scripts/load-env.sh` 加载,命令行不再出现密钥。 + +### 遗留(不阻塞,属后续打磨) + +- 用户组「标签输入」交互(当前为逗号分隔输入框,与 `check_groups` 分隔符约定一致,功能等价)。 +- 统计卡点击下钻到筛选列表。 +- 「最后一个管理员」在前端禁用降级选项(当前为 confirm + 后端红线兜底 + 失败回滚)。