@eduwork/dsh-oidc 0.2.3 → 0.3.0-dev.1

package/docs/security-model.en.md

@@ -1,138 +1,16 @@
-# Security model and deployment requirements
+# Security boundaries
 
 [简体中文](security-model.md) | **English**
 
-## Assets
+Profiles are explicitly configured trusted data. Discovery and token responses cannot select executable modules, inject branding scripts or choose arbitrary request destinations.
 
-`dsh-oidc` handles:
+- Code + PKCE, one-use state and applicable nonce bind sign-in; desktop callbacks listen only on 127.0.0.1.
+- OIDC validates signature, issuer, aud/azp, time, nonce, at_hash and UserInfo subject. ID Tokens returned during refresh are checked against the original identity.
+- Validated discovery supplies model API endpoints. Host requests restrict destinations and redirects; extension reads accept bounded relative paths, GET and bounded bodies.
+- Tokens stay in Host credential storage, never RPC, configuration, diagnostics or model metadata. Personal keys remain separate.
+- Requests bind to authorization context. Logout or reauthorization cancels old calls; late responses cannot restore sessions or leak into another account. Refresh within the same authorization does not cancel valid calls.
+- Local logout precedes best-effort Refresh Token revocation. Remote failure cannot restore local access. Servers determine issued Access Tokens' remaining lifetime.
 
-- 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 client no longer creates, reads or migrates organization model API keys. Old profiles are explicitly rejected and migration requires sign-in, without URL/token-shape guessing. Old keys are not bulk-deleted because independent configurations may still use them.
 
-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.
+See [Profiles](enterprise-profile.en.md) and [protocols](gateway-auth/README_EN.md). Local Web is not a multi-user service.

package/docs/security-model.md

@@ -1,138 +1,16 @@
-# 安全模型与部署要求
+# 安全边界
 
 **简体中文** | [English](security-model.en.md)
 
-## 资产
+Profile 由发行方或本机用户明确配置，限制为数据。发现与 Token 响应不允许改写执行模块、品牌脚本或任意请求目的地。
 
-`dsh-oidc` 会处理：
+- Code + PKCE、一次性 state 和适用的 nonce 绑定登录；桌面回调只监听 127.0.0.1。
+- OIDC 校验签名、issuer、aud/azp、时间、nonce、at_hash 和 UserInfo sub；刷新返回 ID Token 时验证原身份。
+- 模型 API 地址来自已校验的发现。Host 限制目的地址和重定向，机构资源读取只接受有界相对路径、GET 和有界正文。
+- Token 由 Host 凭据服务保存，不通过 RPC、配置、诊断或模型元数据暴露。个人 Key 与机构 Token 分开。
+- 请求绑定登录上下文；退出和重新授权取消旧请求，迟到响应不能恢复旧登录或流入新账户。相同授权的 Token 刷新不应误伤在途调用。
+- 客户端先本地退出，再尽力撤销 Refresh Token；远程失败不恢复本地授权。已签发 Access Token 的剩余有效期由服务端控制。
 
-- OIDC authorization code、access token、refresh token 和 ID Token；
-- 稳定 OIDC subject 标识符和可选显示 claim；
-- 模型运行时 API Key；
-- 机构、Provider 和模型配置；
-- 账号与能力状态。
+客户端不再创建、读取或迁移机构模型 API Key。遇到旧配置明确拒绝，迁移需重新登录；不会凭 URL 或 Token 外观猜测兼容方式。旧 Key 不会被批量删除，以免影响其他独立配置。
 
-机构密码不属于本插件资产，必须只输入 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、安装脚本和许可证已审查。
-- [ ] 事故响应联系人和远程凭据撤销流程已记录。
+仅身份模式、Token 模型模式及两种网关的配置边界见[Profile](enterprise-profile.md)与[协议说明](gateway-auth/README.md)。本机 Web 不可作为多人共享服务。