@eduwork/dsh-oidc 0.1.0-alpha.11

package/docs/release-checklist.en.md

@@ -0,0 +1,60 @@
+# Public release checklist
+
+[简体中文](release-checklist.md) | **English**
+
+Record reviewer names, date, command output links, and exceptions in the release pull request. An unchecked item blocks public release unless a maintainer and security maintainer document why it is not applicable.
+
+## Authority and project metadata
+
+- [ ] Repository owner confirmed public release and the MIT license.
+- [ ] The `freedomkk-qfeng/dsh-oidc` remote is confirmed; npm package ownership is approved separately if npm publication is planned.
+- [ ] Maintainer, security, and release-manager rosters recorded with backups.
+- [ ] GitHub Private Vulnerability Reporting is enabled and its entry point has been checked without sensitive data.
+- [ ] ECNU/ChatECNU name, example text, colors, and trademark notice approved.
+
+## Source and protocol review
+
+- [ ] Two-person review completed for OIDC, Key Binding, model-gateway invariants, Profile validation, Provider credentials, and native boundary.
+- [ ] Enterprise Profile JSON Schema matches runtime behavior.
+- [ ] OpenAPI matches normative Key Binding prose and implementation.
+- [ ] OIDC standard references and limitations are current.
+- [ ] No unnecessary local reimplementation of a supported DSH capability.
+- [ ] Compatibility matrix and changelog updated.
+
+## Security and privacy
+
+- [ ] Threat model reviewed for actual topology.
+- [ ] Single-user versus multi-user Credential Provider boundary verified.
+- [ ] OIDC success and negative conformance suite passed against staging.
+- [ ] Cross-user/tenant Key Binding authorization tests passed.
+- [ ] API-key expiry, rotation, suspension, and remote revocation behavior tested.
+- [ ] Confirmed the WebServer listens only on `127.0.0.1` and no reverse proxy, port forward, or tunnel exposes the local session to other users.
+- [ ] Remote TLS, CSP, cookies, CSRF, egress, clock, logging, APM, and backups reviewed.
+- [ ] Privacy/legal review completed for identity and audit data.
+- [ ] Secret scans of both the current tree and publishable Git history found no production hosts, IDs, keys, logs, personal paths, or personal data.
+
+## Supply chain
+
+- [ ] Clean `npm ci` completed on Windows and Linux with Node 22.
+- [ ] `npm audit` and static analysis reviewed (not merely run).
+- [ ] Every direct/transitive license and exception reviewed.
+- [ ] npm install scripts reviewed; unexpected scripts denied.
+- [ ] Lockfile diff reviewed and dependency versions pinned as intended.
+- [ ] GitHub Actions pinned to immutable commits before public release.
+
+## Product acceptance
+
+- [ ] Plain Web DSH: login, callback, display name/sub fallback, provision, model call, refresh, check, logout.
+- [ ] Native desktop: current ChatECNU Work experience unchanged.
+- [ ] Native multimodal and text-only + image-transform routes tested.
+- [ ] Unsupported reasoning-effort model still runs with thinking enabled.
+- [ ] Failure UX tested: Discovery, token, UserInfo, bootstrap, policy denial, model key, expiry, network timeout.
+
+## Build and publish
+
+- [ ] `npm run check` passes from a clean checkout.
+- [ ] `npm pack --dry-run` and extracted tarball reviewed; only intended files included.
+- [ ] Source maps contain no private absolute paths or secrets.
+- [ ] Tag/release notes/checksums prepared.
+- [ ] npm trusted publishing/provenance configured; no long-lived local publish token.
+- [ ] Rollback/deprecation and vulnerability-notification plan confirmed.

package/docs/release-checklist.md

@@ -0,0 +1,60 @@
+# 公开发布检查表
+
+**简体中文** | [English](release-checklist.en.md)
+
+在发布 Pull Request 中记录审查人、日期、命令输出链接和例外说明。任何未勾选项目都会阻止公开发布，除非维护者和安全维护者书面说明其不适用原因。
+
+## 授权与项目元数据
+
+- [ ] 仓库所有者确认公开发布和 MIT 许可证。
+- [ ] `freedomkk-qfeng/dsh-oidc` 远程仓库位置已确认；如发布 npm，`dsh-oidc` 包所有权另行确认。
+- [ ] 维护者、安全维护者和发布经理名单及替补已记录。
+- [ ] GitHub Private Vulnerability Reporting 已启用并完成一次无敏感数据的入口检查。
+- [ ] ECNU/ChatECNU 名称、示例文字、颜色和商标声明获批。
+
+## 源码与协议审查
+
+- [ ] OIDC、Key Binding、模型网关一致性、Profile 校验、Provider 凭据和 native 边界已完成双人审查。
+- [ ] Enterprise Profile JSON Schema 与运行行为一致。
+- [ ] OpenAPI 与 Key Binding 规范正文和实现一致。
+- [ ] OIDC 标准引用和限制仍然有效。
+- [ ] 没有重复实现 DSH 已支持且适用的能力。
+- [ ] 兼容性矩阵和变更日志已更新。
+
+## 安全与隐私
+
+- [ ] 已按实际部署拓扑审查威胁模型。
+- [ ] 单用户/多用户 Credential Provider 边界已验证。
+- [ ] 已在预发布环境通过 OIDC 成功和反向符合性测试。
+- [ ] 已通过跨用户/跨 tenant Key Binding 授权测试。
+- [ ] 已测试 API Key 过期、轮换、停用和远程撤销行为。
+- [ ] 已确认 WebServer 仅监听 `127.0.0.1`，没有反向代理、端口转发或隧道把本地会话暴露给其他用户。
+- [ ] 已审查远端 TLS、CSP、Cookie、CSRF、出口、时钟、日志、APM 和备份。
+- [ ] 已完成身份和审计数据的隐私/法律审查。
+- [ ] 当前树与待公开 Git 历史的密钥扫描均未发现生产 host、ID、Key、日志、个人路径或个人数据。
+
+## 供应链
+
+- [ ] Windows 和 Linux 上使用 Node 22 完成干净 `npm ci`。
+- [ ] `npm audit` 和静态分析结果经过审查，而不只是执行。
+- [ ] 所有直接/间接许可证和例外已经审查。
+- [ ] npm 安装脚本已经审查，未预期脚本被拒绝。
+- [ ] Lockfile diff 已审查，依赖版本按预期锁定。
+- [ ] 公开发布前，GitHub Actions 已固定到不可变 commit。
+
+## 产品验收
+
+- [ ] 纯 Web DSH：登录、callback、显示 name/sub 降级、provision、模型调用、刷新、检查连接和退出。
+- [ ] Native 桌面：现有 ChatECNU Work 体验无回退。
+- [ ] 原生多模态和纯文本 + image-transform 路由均已测试。
+- [ ] 不支持 reasoning effort 的模型仍能启用 thinking 并正常运行。
+- [ ] 已测试失败 UX：Discovery、token、UserInfo、bootstrap、策略拒绝、模型 Key、过期和网络超时。
+
+## 构建与发布
+
+- [ ] 在干净 checkout 中通过 `npm run check`。
+- [ ] 已审查 `npm pack --dry-run` 和解压后的 tarball，且只包含预期文件。
+- [ ] Source map 不包含私有绝对路径或秘密。
+- [ ] Tag、发布说明和 checksum 已准备。
+- [ ] npm trusted publishing/provenance 已配置，不使用长期本地 publish token。
+- [ ] 已确认回滚、弃用和漏洞通知计划。

package/docs/security-model.en.md

@@ -0,0 +1,138 @@
+# Security model and deployment requirements
+
+[简体中文](security-model.md) | **English**
+
+## Assets
+
+`dsh-oidc` handles:
+
+- OIDC authorization codes, access tokens, refresh tokens, and ID Tokens;
+- stable OIDC subject identifiers and optional display claims;
+- model runtime API keys;
+- organization/provider/model configuration;
+- account and capability state.
+
+The organization password is not an asset of this plugin and MUST be entered only into the OIDC Provider.
+
+## Trust boundaries
+
+1. Browser to DSH Host callback/UI.
+2. DSH Host to OIDC Provider.
+3. DSH Host to Key Binding service.
+4. DSH Host to model gateway.
+5. Plugin to DSH Credential Provider.
+6. Trusted local executable plugin code versus declarative Enterprise Profile data.
+
+The same institution may operate boundaries 2–4, but they remain separate protocol authorities and should use distinct audiences and credentials.
+
+## Security controls in this repository
+
+### OIDC
+
+- Authorization Code + PKCE S256 only.
+- Random state, nonce, and verifier.
+- Ten-minute pending-flow expiry and bounded flow count.
+- Fixed callback path and explicit public origin.
+- Duplicate security-parameter rejection.
+- RS256 signature/JWK/issuer/audience/azp/subject/nonce/time validation.
+- `at_hash` validation when supplied.
+- UserInfo `sub` equality with ID Token `sub`.
+- Same-origin-only callback return path.
+- HTTPS remote endpoints; explicit loopback-only HTTP development exception.
+- One MiB maximum for OIDC and Key Binding JSON responses.
+
+### Configuration
+
+- Unknown keys rejected.
+- 512 KiB profile bound.
+- No remote adapter/module/tool/skill selection.
+- Fixed Key Binding paths and fields.
+- HTTPS production URLs without embedded credentials/fragments.
+- PNG/WebP-only data logos; no SVG data URL.
+- Only bounded brand token overrides.
+
+### Secrets
+
+- Public OIDC client; no client secret.
+- Session and API key written only through DSH Credential Provider.
+- The model adapter resolves the normalized Profile credential reference at request time; deterministic Provider-ID derivation is only the default when none is configured.
+- Separate empty pi-ai auth store prevents ambient credentials shadowing the bound key.
+- Credential response requires exact Provider ID.
+- A native host's reported credential reference must match the Profile, preventing production/test cross-resolution.
+- Logout clears both local session and model key.
+
+## Host assumptions
+
+The plugin assumes:
+
+- Node.js TLS and DNS trust are correctly administered;
+- DSH plugins and profile files are writable only by trusted administrators;
+- the DSH WebServer listens exactly on `127.0.0.1` and exact `/oauth/callback` routing is not bypassed;
+- the active Credential Provider protects confidentiality and isolates intended users;
+- logs and crash reports do not dump credential values or request bodies;
+- no reverse proxy, port forward, or tunnel exposes the local WebServer to other users;
+- system time is reasonably synchronized.
+
+If any assumption fails, the plugin alone cannot restore the security boundary.
+
+## Single-user versus shared Web deployment
+
+The Web backend stores one logical OIDC session per profile credential reference. In a local DSH process with a file-backed credential store, that is a **single-user process model**. Multiple browsers reaching the same process could observe or replace the same account state through the shared Host services.
+
+The current Web backend therefore forces the DSH WebServer to listen on `127.0.0.1` and rejects both `publicBaseURL` and non-loopback hosts. It MUST NOT be exposed as a shared multi-user service.
+
+A shared deployment requires the host—not this plugin—to provide:
+
+- authenticated browser sessions;
+- per-user service/request context;
+- per-user Credential Provider namespaces;
+- encrypted storage with rotation and backup policy;
+- Secure, HttpOnly, SameSite cookies;
+- CSRF protection for non-OIDC state-changing actions;
+- tenant/subject isolation tests;
+- session termination and administrator revocation;
+- rate limiting and abuse monitoring.
+
+Those capabilities require a future, separate host backend; they are not a reason to relax the current Web backend's loopback check. Until DSH exposes and this project tests those contracts, the supported Web topology is one trusted user per process/profile.
+
+## SSRF and endpoint policy
+
+OIDC metadata is remote-controlled after the trusted issuer is configured. The standard permits cross-origin endpoints, so the plugin accepts them only over HTTPS. This prevents an arbitrary network-HTTP downgrade but does not stop a malicious or compromised issuer from naming private HTTPS endpoints.
+
+Operators SHOULD apply egress policy so the DSH process can reach only approved identity, Key Binding, and model origins. Cloud deployments SHOULD block metadata-service ranges and internal control planes at the network layer. DNS rebinding protections belong at the HTTP agent/egress proxy layer and are not implemented here.
+
+## Browser security
+
+The host SHOULD set a restrictive Content Security Policy. At minimum, review:
+
+- `connect-src` for DSH/WebSocket traffic;
+- `img-src` for HTTPS and approved `data:` images;
+- `frame-ancestors 'none'` unless embedding is explicitly intended;
+- `base-uri 'none'` and `object-src 'none'`;
+- `Referrer-Policy: no-referrer` or similarly restrictive policy.
+
+Remote brand images can reveal client IP/timing to their host even with no referrer. Package or proxy assets where that is unacceptable.
+
+## Known limitations
+
+- RS256 only; no algorithm agility yet.
+- No PAR/JAR/JARM, DPoP, mTLS, or encrypted tokens.
+- No RP-Initiated, front-channel, or back-channel logout.
+- In-memory pending login state is lost on restart and is not cluster-shared.
+- Discovery is cached for the process lifetime; emergency endpoint changes require restart.
+- Native backend security depends on the host `enterpriseAccounts` implementation.
+- Key Binding has no remote credential-revoke operation in v1.
+- Dependency integrity relies on npm lockfile and release controls; the repository does not vendor DSH/pi-ai source.
+
+## Security review checklist for deployments
+
+- [ ] Exact issuer, client ID, redirect URI, and audiences approved.
+- [ ] OIDC conformance and negative tests pass.
+- [ ] Key Binding scopes and entitlement checks tested for cross-user/cross-tenant access.
+- [ ] Provider/key mismatch and stale-key revocation tested.
+- [ ] Credential Provider topology matches single-user or isolated multi-user requirements.
+- [ ] Reverse proxy and CSP reviewed.
+- [ ] Secrets absent from application, proxy, APM, and crash logs.
+- [ ] Egress policy blocks unexpected private/metadata destinations.
+- [ ] Dependency lockfile, install scripts, and licenses reviewed.
+- [ ] Incident response contact and remote credential revocation procedure documented.

package/docs/security-model.md

@@ -0,0 +1,138 @@
+# 安全模型与部署要求
+
+**简体中文** | [English](security-model.en.md)
+
+## 资产
+
+`dsh-oidc` 会处理：
+
+- OIDC authorization code、access token、refresh token 和 ID Token；
+- 稳定 OIDC subject 标识符和可选显示 claim；
+- 模型运行时 API Key；
+- 机构、Provider 和模型配置；
+- 账号与能力状态。
+
+机构密码不属于本插件资产，必须只输入 OIDC Provider。
+
+## 信任边界
+
+1. 浏览器到 DSH Host callback/UI。
+2. DSH Host 到 OIDC Provider。
+3. DSH Host 到 Key Binding 服务。
+4. DSH Host 到模型网关。
+5. 插件到 DSH Credential Provider。
+6. 受信任的本地可执行插件代码与声明式 Enterprise Profile 数据之间。
+
+同一机构可以运营第 2–4 项边界，但它们仍是彼此独立的协议权威，应该使用不同 audience 和凭据。
+
+## 本仓库实现的安全控制
+
+### OIDC
+
+- 仅使用 Authorization Code + PKCE S256。
+- 随机 state、nonce 和 verifier。
+- 待处理流程十分钟过期，且数量受限。
+- 固定 callback 路径和显式 public origin。
+- 拒绝重复安全参数。
+- 校验 RS256 签名、JWK、issuer、audience、azp、subject、nonce 和时间。
+- 存在 `at_hash` 时校验它。
+- UserInfo `sub` 必须等于 ID Token `sub`。
+- Callback return path 只能同源。
+- 远程 endpoint 必须 HTTPS；只有显式 loopback 开发环境可以使用 HTTP。
+- OIDC 与 Key Binding JSON 响应最大 1 MiB。
+
+### 配置
+
+- 拒绝未知字段。
+- Profile 最大 512 KiB。
+- 不允许远程选择 adapter、module、tool 或 Skill。
+- Key Binding 路径和字段固定。
+- 生产 URL 使用 HTTPS，且不得包含凭据或 fragment。
+- Data logo 只允许 PNG/WebP，不允许 SVG。
+- 只覆盖有边界的品牌 token。
+
+### 秘密
+
+- 使用 OIDC public client，不使用 client secret。
+- Session 和 API Key 只通过 DSH Credential Provider 写入。
+- 模型 adapter 在请求时解析 Profile 规范化后的凭据引用；未配置时才按 Provider ID 确定性派生。
+- 独立空 pi-ai auth store 防止环境凭据遮蔽已绑定 Key。
+- 凭据响应必须精确匹配 Provider ID。
+- Native 宿主报告的凭据引用必须与 Profile 一致，防止生产/测试环境交叉取 Key。
+- 退出登录会清除本地会话和模型 Key。
+
+## 宿主假设
+
+插件假设：
+
+- Node.js TLS 和 DNS 信任得到正确管理；
+- DSH 插件和 Profile 文件只能由受信任管理员写入；
+- DSH WebServer 精确监听 `127.0.0.1`，且 `/oauth/callback` 路由注册不会被绕过；
+- 当前 Credential Provider 能保护机密性，并隔离目标用户；
+- 日志和崩溃报告不会转储凭据值或请求 body；
+- 没有反向代理、端口转发或隧道把本地 WebServer 暴露给其他用户；
+- 系统时间基本同步。
+
+任何假设失效时，插件无法独自恢复安全边界。
+
+## 单用户与共享 Web 部署
+
+Web 后端会按 Profile 凭据引用保存一个逻辑 OIDC 会话。在使用文件型凭据存储的本地 DSH 进程中，这属于**单用户进程模型**。访问同一进程的多个浏览器可能通过共用 Host 服务看到或替换同一账号状态。
+
+因此，当前 Web backend 强制 DSH WebServer 监听 `127.0.0.1`，并拒绝 `publicBaseURL` 或非 loopback host。它不得作为共享多用户服务公开。
+
+共享部署要求宿主而不是本插件提供：
+
+- 已认证的浏览器 session；
+- 每用户服务/请求上下文；
+- 每用户 Credential Provider 命名空间；
+- 带轮换和备份策略的加密存储；
+- Secure、HttpOnly、SameSite Cookie；
+- 对非 OIDC 状态变更操作的 CSRF 防护；
+- tenant/subject 隔离测试；
+- session 终止和管理员撤销；
+- 限流和滥用监控。
+
+上述能力需要由未来新的宿主 backend 实现；它们不是放宽当前 Web backend loopback 检查的理由。在 DSH 暴露并且本项目验证这些契约前，支持的 Web 拓扑是每个进程/Profile 仅供一名受信任用户使用。
+
+## SSRF 与 endpoint 策略
+
+配置受信任 issuer 后，OIDC 元数据仍由远端控制。标准允许跨 origin endpoint，因此插件仅在 HTTPS 下接受它们。这样可阻止任意网络 HTTP 降级，但不能阻止恶意或已被攻陷的 issuer 指向私有 HTTPS endpoint。
+
+运维方应该实施出口策略，使 DSH 进程只能访问已批准的身份、Key Binding 和模型 origin。云部署应该在网络层阻断 metadata-service 地址段和内部控制面。DNS rebinding 防护属于 HTTP agent/出口代理职责，本插件尚未实现。
+
+## 浏览器安全
+
+宿主应该设置严格 Content Security Policy，至少审查：
+
+- `connect-src`：DSH/WebSocket 流量；
+- `img-src`：HTTPS 和批准的 `data:` 图片；
+- `frame-ancestors 'none'`：除非明确需要嵌入；
+- `base-uri 'none'` 和 `object-src 'none'`；
+- `Referrer-Policy: no-referrer` 或同等严格策略。
+
+即便没有 referrer，远程品牌图片仍可能向其宿主暴露客户端 IP 和访问时间。无法接受时，应打包资产或通过受控代理提供。
+
+## 已知限制
+
+- 只支持 RS256，尚无算法敏捷性。
+- 不支持 PAR/JAR/JARM、DPoP、mTLS 或加密 token。
+- 不支持 RP-Initiated、front-channel 或 back-channel logout。
+- 进程重启会丢失内存中的待登录状态，且该状态不跨集群共享。
+- Discovery 在进程生命周期内缓存；紧急 endpoint 变更需要重启。
+- Native 后端安全性取决于宿主 `enterpriseAccounts` 实现。
+- Key Binding v1 没有远程凭据撤销操作。
+- 依赖完整性依靠 npm lockfile 和发布控制；仓库不 vendor DSH/pi-ai 源码。
+
+## 部署安全审查清单
+
+- [ ] 精确 issuer、client ID、redirect URI 和 audience 已获批准。
+- [ ] OIDC 符合性和反向测试通过。
+- [ ] Key Binding scope 和授权已测试跨用户/跨 tenant 访问。
+- [ ] Provider/Key 不匹配和旧 Key 撤销已测试。
+- [ ] Credential Provider 拓扑符合单用户或隔离多用户要求。
+- [ ] 反向代理和 CSP 已审查。
+- [ ] 应用、代理、APM 和崩溃日志中没有秘密。
+- [ ] 出口策略会阻断意外的私有/metadata 目标。
+- [ ] 依赖 lockfile、安装脚本和许可证已审查。
+- [ ] 事故响应联系人和远程凭据撤销流程已记录。