OIDC 准入网关 Senti100/dsh-oidc

@senti100/dsh-oidc

为 DeepSeek Harness（DSH）Web 配置档提供与具体服务商无关的 OpenID Connect 准入。它通过 openid-client 走 Authorization Code + PKCE 流程，验证成功后把浏览器交给 DSH 原生 Connection 插件，该插件不做任何改动。

安全架构

本包是仅运行在 Host 侧的 Cordis 插件。它注册 /auth/login、/auth/callback、/auth/check、/auth/signin、/auth/logout，不会替换或复制 @deepseek-ai/dsh-client-connection。校验 ID token 与准入策略之后，它创建一个短时效的不透明内存会话，并通过 ctx.connection.authenticatedUrl(publicOrigin) 重定向，由 DSH 自己签发原生浏览器 cookie。

反向代理是安全边界中不可缺少的一环。它必须只把 /auth/login、/auth/callback、/auth/check、/auth/signin、/auth/logout 直接转发给 DSH，拒绝其余未匹配的 /auth/*，并用 forward_auth /auth/check 保护其他所有路径（根路径、静态资源、/api、上传、SSE/流、WebSocket 升级）。只在 auth-check 子请求上剥离 Connection 和 Upgrade，保留应用代理的 WebSocket 升级。转发之前，Caddy 会剥离浏览器提供的 authorization、proxy-authorization、身份别名以及 X-Dsh-Oidc-Client-Ip，然后用它自己观测到的连接来源 {remote_host} 设置这个专用请求头。只有当 socket 对端是 loopback 时，插件才信任该请求头中唯一一个合法 IP。直接来自 loopback 的调用方可以设置它，这是显式受信任的本地恢复手段，绝不是一条局域网信任路径。OIDC 会话被移除后，残留的原生 DSH cookie 不足以通过校验。DSH 必须保持只监听 loopback。如果要求源站严格只用 HTTPS，就不要在该地址上暴露 HTTP 80 端口；在第一次 HTTP 请求发生之前，自动重定向或 HSTS 都无法保护已经存进浏览器的非 Secure 原生 cookie。代理示例还会把新签发的原生 cookie 标记为 Secure，但无法修复浏览器里已经存下的 cookie。参见部署指南。

DSH 0.2.0-rc.2 只有一个进程级的 operator peer。所有获准进入的用户共享同一个 DSH home、会话、工作区、凭据、工具、审批和事件流。分组只控制准入，不会创建内部角色或隔离。需要隔离时，请为每个用户运行独立的 DSH home/进程。

兼容性

这个兼容性候选版本刻意锁定到公开的 DSH 0.2.0-rc.2 包接口。本版本（0.2.1-alpha.0）已在 DSH 0.2.0-rc.2 上测试：完整配置档验收（真实 Web 配置档、Caddy 2.10.2、合成 OIDC、原生 cookie、WebSocket、上传）、单独的公开安装门禁，以及 Caddy 2.11.3 背后的真实 HTTPS 部署。DSH API 尚未稳定；在放宽这些精确的 peer 版本之前，请先测试并发布单独的适配器/版本。上游后续版本属于未来的兼容通道，不代表已支持。
请参阅上游 seam 审计与干净的升级/回滚流程。本候选版本不支持 0.1.x/0.2.x 混合版本图。

配置

| 字段 | 含义 |
| issuer | 用于发现和 token 校验的精确 HTTPS 签发者标识符。 |
| clientId | 精确的 OIDC 客户端标识符。 |
| clientSecretRef | 可选的 DSH 凭据引用名。每次登录/回调/登出操作都会解析密钥值，密钥值永远不作为配置。公开客户端请省略此项。 |
| publicOrigin | 固定的 HTTPS 源，路径为 /；绝不从 Host 或转发头推导。 |
| allowedSubjects | 精确的 { issuer, subject } 元组。 |
| allowedEmails | 精确的邮箱值，作为额外的策略类别，绝不作为身份；准入还要求字面布尔值 email_verified: true。 |
| allowedGroups | 来自 groupsClaim 的精确值，区分大小写。 |
| groupMode | 对配置的允许组取 any 或 all。 |
| requiredClaims | 每个必需声明的精确允许值；各类别之间取 AND。 |
| sessionMaxAgeSeconds | 本地 OIDC 会话的绝对生命周期（默认 8 小时）。 |
| sessionIdleTimeoutSeconds | 空闲过期时间（默认 30 分钟）。在这些限制生效前，服务商策略变更不会使已签发的会话失效。 |
至少需要一个 allow 类别。每个配置的类别之间是 AND 关系；subject、email 和 any 组类别内部的值是 OR 关系。匹配比较按字节精确进行，不做大小写折叠，也不做子串匹配。显式空策略列表无效。组声明必须是非空有界数组，元素为唯一非空有界字符串；标量组一律拒绝。自定义 required 声明可以是单个有界非空字符串，也可以是同样的有界唯一字符串数组形式。

参见分步部署与回滚指南、examples/cordis.patch.yml、examples/Caddyfile 和 .env.example。登录之前，裸根路径对 API 客户端应返回 401；浏览器导航会重定向到内置登录页 /auth/signin，页面上的 Sign-in 按钮会在 /auth/login 启动 OIDC。重定向只在 sec-fetch-mode: navigate 时触发（或者该请求头缺失时，仅限 HTML 的 Accept）；fetch/XHR/WebSocket 子请求仍然返回普通 401，因为 Caddy 的 forward_auth 子请求不会复制这类导航信号。该页面是自包含的内联 HTML，带严格 CSP，不加载任何外部资源。当前分发路径就是这个 checkout 及其本地 tarball；不假定包已发布到 npm。补丁里的配置值由环境变量提供；client secret 的值留在 ctx.credentials 后面，插件配置里只出现它的引用名。

协议行为

- 通过 HTTPS 进行 OpenID Connect 发现，拒绝重定向，并设有有界请求超时。
- 仅使用 Authorization Code，PKCE S256，state/nonce/verifier/transaction/session/CSRF 各自独立随机生成。
- 一次性五分钟 transaction，绑定 Secure; HttpOnly; SameSite=Lax; Path=/ cookie。
- 由 openid-client/oauth4webapi 校验 ID-token 的签名、issuer、audience、过期时间、nonce 以及可选的 auth_time，随后只要 azp 存在就精确检查 azp === clientId，audience 为多值时 azp 必填。
- HEAD /auth/login 是无状态就绪响应：不创建 transaction、cookie，也不向服务商发请求。
- 服务端会话不透明且经过哈希；cookie 或日志中不保留 access token、refresh token、原始 ID token、claims、secret、code、state 或 nonce。
- GET logout 只渲染确认表单。POST 要求 Origin 精确匹配并通过会话 CSRF 校验，之后才做本地删除。RP 发起的 logout 是可选项，由服务商声明支持。
- 重启会使所有 transaction 和 OIDC 会话失效。

本地开发

需要 Node 22 系列中的 22.19 或更新版本。

npm ci
npm run check
npm run check 会跑格式化、lint、严格 TypeScript、带覆盖率门槛的测试、构建、包内容检查，以及本地密钥模式扫描。npm run test:acceptance:full-profile 是另一道一次性发布门禁：它要求通过 DSH_OIDC_CADDY_BIN 指定精确的 Caddy v2.10.2，还需要 Corepack 和锁定版本的 Playwright 浏览器。这道门禁会打包本仓库，用公开的 dsh plugin --profile web add --save-exact 命令安装该 tarball，启动已发布的 DSH 0.2.0-rc.2 Web 配置档，并用真实的前端、API、上传、原生 cookie Secure 标志和 WebSocket 归属方，跑一遍合成 OIDC/TLS 以及随包发布的 Caddy 示例。npm run test:public-install 则单独从 Web 模板初始化 web-oidc，用精确的 0.2.0-rc.2 peer overrides 安装本地 tarball，在进程环境里用合成 OIDC 设置启动，验证未认证的 /auth/check 返回 401，检查没有打印 bootstrap bearer URL，然后拆除它的临时 home。CI 会跑这两项。在 0.2.0-rc.2 里，/events 只是一个预留的、无归属方的准入探针；它并不算作 DSH SSE 覆盖。两套测试装置都不使用真实服务商、生产 DSH home、代理、DNS 或凭据。

非目标

本包不改变 DSH RPC 方法、权限、模型凭据、工作区授权、按用户归属或事件投递。它不会让非回环地址的 DSH 绑定变得安全。它不部署也不配置身份服务商、代理、DNS 或 DSH 实例。