@eduwork/dsh-oidc 0.1.0-alpha.11

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,53 @@
+# 第三方声明
+
+**简体中文** | [English](THIRD_PARTY_NOTICES.en.md)
+
+`dsh-oidc` 使用 MIT 许可证，并与以下直接声明的软件包互操作。精确版本记录在 `package-lock.json` 中；间接依赖的许可证文件保留在各自发布包内。
+
+## 运行时 Peer（源码未复制进本仓库）
+
+- DeepSeek Harness `0.1.2-alpha.2` 软件包和 `@deepseek-ai/cordis` `4.0.2`——MIT，Copyright (c) 2026 DeepSeek，<https://github.com/deepseek-ai/deepseek-harness>
+- `@earendil-works/pi-ai` `^0.84.2`（已审查源码 Runtime 中为 `0.84.4`）——MIT，<https://github.com/earendil-works/pi>
+- React `18.x`——MIT，Copyright (c) Facebook, Inc. and its affiliates，<https://github.com/facebook/react>
+
+本仓库使用这些软件包的公开 API，不 vendor 其源码。它们作为 peer dependency 出现，不表示其作者认可本项目。
+
+## 浏览器产物中包含的代码
+
+生成的 `lib/client.js` 打包了 Zod：
+
+### Zod 4.4.3
+
+以下许可证正文保持英文原文：
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+源码：<https://github.com/colinhacks/zod>
+
+## 仅开发使用的工具
+
+仓库还声明 tsdown（MIT）、TypeScript（Apache-2.0）、Ajv（MIT）、YAML（ISC）和 `@types/react`（MIT），用于构建与校验。它们不包含在 npm 包运行时文件中。发布前应根据 lockfile 审查其间接许可证和安装脚本。
+
+在 alpha.1 lockfile 中，npm 报告 `@google/genai`（无操作 preinstall）和 `protobufjs`（postinstall）包含安装脚本；二者均来自 `@earendil-works/pi-ai` peer 依赖树。准备安装期间，npm allow-scripts 策略未批准这些脚本。每次 lockfile 变化后，发布经理必须重新审查；`npm audit` 报告零已知漏洞不能替代该审查。
+
+准备好的 lockfile 含 255 个带许可证元数据的软件包条目：MIT 190 个、Apache-2.0 48 个、BSD-3-Clause 12 个、ISC 3 个、Python-2.0 1 个（`argparse`）和 0BSD 1 个。这只是清单结果，不构成法律意见；发布经理必须从最终 lockfile 重新生成并审查。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Default Web-first DSH bundle entry. Installing a local checkout with
+# `dsh plugin --profile web add .` appends this layer to the ordinary official
+# Web profile. Deployment facts remain outside the package source.
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE

package/docs/EDUWORK-MIGRATION.en.md

@@ -0,0 +1,23 @@
+# eduwork npm scope migration
+
+[简体中文](EDUWORK-MIGRATION.md) | **English**
+
+Starting with this version, the npm package is `@eduwork/dsh-oidc@0.1.0-alpha.11`, replacing `dsh-oidc`. The npm `eduwork` organization exists. The GitHub repository and checkout directory remain `dsh-oidc`. Consult the npm registry for current publication status.
+
+## Installation and migration
+
+```sh
+dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0-alpha.11
+```
+
+Back up an existing Profile's package.json and cordis.patch.yml, then update its dependency and dsh.profile.bundles entries. Update module name paths in custom patches too. Do not enable both package identities together; restart the Host after switching. These are separate npm packages, so updating the old package cannot migrate an installation automatically.
+
+## Data compatibility
+
+Keep `dsh-oidc/v1alpha1`, `oidcAccounts`, credential references, Provider identities and plugin row ids. Host and Client TYPERT package identities change together.
+
+Storage directories and user configuration content do not change. Product-managed Profiles migrate their owned dependencies through the product upgrader; community plugins remain unchanged.
+
+## Release scope
+
+This is an alpha package-identity migration retaining the declared DSH peer baseline. Build, tests, documentation, license and tarball checks cover this change. It adds no claims of real institutional sign-in, real email delivery or production acceptance. Stable releases still require the complete deployment checks. Keep previous versions installable and add a migration notice only after the new package passes installation validation.

package/docs/EDUWORK-MIGRATION.md

@@ -0,0 +1,23 @@
+# eduwork npm 作用域迁移
+
+**简体中文** | [English](EDUWORK-MIGRATION.en.md)
+
+从本版本起，npm 包使用 `@eduwork/dsh-oidc@0.1.0-alpha.11`，替代旧的 `dsh-oidc`。npm `eduwork` 组织已创建；GitHub 仓库和本地 checkout 目录继续使用 `dsh-oidc`。包的当前发布状态以 npm registry 为准。
+
+## 安装与迁移
+
+```sh
+dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0-alpha.11
+```
+
+已有 Profile 先备份 package.json 与 cordis.patch.yml，再更新依赖和 dsh.profile.bundles；手写 patch 的模块路径 name 也需切换。不要同时启用新旧两份插件，切换后重启 Host。旧版本和新作用域版本是不同 npm 包，旧包的更新不会自动迁移安装。
+
+## 数据兼容
+
+保留 `dsh-oidc/v1alpha1`、`oidcAccounts`、凭据引用、Provider 标识和插件行 id；Host 与 Client 的 TYPERT 包归属一起更新。
+
+本次迁移不修改存储目录或用户配置内容。产品管理的 Profile 由产品升级逻辑迁移其受管依赖；社区插件保持原状。
+
+## 发布范围
+
+此版本为 alpha 包身份迁移，沿用声明的 DSH peer 基线。构建、测试、文档、开源和 tarball 检查针对本次变更执行；不新增真实学校登录、真实邮件发送或生产部署验收结论。稳定发布仍须完成公开发布检查表中的完整部署验收。旧包保持可安装，新包安装验证通过后添加迁移提示，不撤回旧版本。

package/docs/architecture.en.md

@@ -0,0 +1,125 @@
+# Architecture and boundaries
+
+[简体中文](architecture.md) | **English**
+
+## Goals
+
+`dsh-oidc` lets an organization integrate identity, entitlement, model credentials, Provider metadata, and bounded branding into an ordinary DSH host without forking DSH or requiring a desktop shell.
+
+The design follows five rules:
+
+1. **DSH owns the runtime.** The plugin uses official DSH services and `PiAiAdapter`; it does not implement a parallel conversation or model transport stack.
+2. **Standards own identity.** Authentication uses OIDC Discovery, Authorization Code + PKCE, ID Tokens, UserInfo, refresh, and optional revocation.
+3. **The institutional service is one complete delivery boundary.** One accountable owner must jointly deliver OIDC, fixed Key Binding, and the model gateway; a Profile declares only their public endpoints and facts.
+4. **Configuration is data, not code.** A profile cannot select executable adapters, arbitrary endpoint paths, scripts, stylesheets, tools, or skills.
+5. **Product-specific capabilities compose around the core.** The common enterprise-model settings surface belongs to `dsh-oidc`; desktop shells, quota views, model transforms, or institutional pages remain separate plugins/services.
+
+## Runtime components
+
+| Component | Responsibility | Trust level |
+| --- | --- | --- |
+| DSH Host | Lifecycle, Cordis services, LLM registry, WebServer, credentials, attachments | Trusted executable host |
+| `dsh-oidc` Host face | Profile validation, OIDC client, Key Binding client, local Provider registration | Trusted local plugin |
+| `dsh-oidc` Client face | Account/onboarding surfaces, shared enterprise-model settings, and bounded branding | Trusted local plugin |
+| Enterprise Profile | Declarative integration facts | Trusted configuration, still validated fail-closed |
+| Institutional enterprise-model integration service | Joint OIDC identity, Key Binding authorization/credential lifecycle, and OpenAI-compatible model gateway | Remote identity, authorization, and data-processing authority |
+| Capability plugin | Optional request-bound transform such as image-to-text fallback | Separately trusted local plugin |
+
+## Control flow
+
+```mermaid
+sequenceDiagram
+  participant B as Browser/UI
+  participant D as dsh-oidc
+  participant O as OIDC Provider
+  participant K as Key Binding service
+  participant C as DSH Credential Provider
+  participant L as DSH LLM/PiAiAdapter
+  participant M as Model gateway
+
+  B->>D: begin(profileID)
+  D->>O: Discovery
+  D-->>B: Authorization URL (state, nonce, PKCE)
+  B->>O: User authentication and consent
+  O-->>D: http://127.0.0.1:port/oauth/callback?code&state
+  D->>O: Token request + code_verifier
+  D->>O: JWKS and UserInfo
+  D->>D: Verify ID Token and sub equality
+  D->>C: Store OIDC session
+  D->>K: GET /bootstrap with Bearer access token
+  B->>D: User confirms provisioning
+  D->>K: POST /runtime-credential/provision
+  K-->>D: api_key
+  D->>C: Store API key under the Profile credential reference
+  B->>L: Start model request
+  L->>C: Resolve runtime API key
+  L->>M: OpenAI-compatible streaming request
+```
+
+The OIDC Provider, Key Binding, and model gateway in the diagram are three interface groups in one [server API specification](server-integration-contract.en.md). They may route to different internal systems or origins, but an operator cannot choose only a subset. The Web callback always returns to local `127.0.0.1`, not a public institutional DSH address.
+
+## Code layout
+
+- `src/host/index.js`: DSH service entry and Typert remote methods.
+- `src/host/oidc.js`: Web and native account backends.
+- `src/host/profile.js`: validation, imports, public projection, Provider projection.
+- `src/host/provider/`: local DSH/PiAi Provider adapter and transform seam.
+- `src/client/`: DSH browser bundle, account surfaces, and remote descriptors.
+- `schema/`: machine-readable Enterprise Profile contract.
+- `protocol/openapi.yaml`: machine-readable Key Binding contract.
+- `docs/`: normative prose, threat model, and integration guidance.
+
+Host files remain readable native ESM and are copied to `lib/` during build. Client code is bundled into DSH's module-loader closure format. Published packages include built artifacts and the two machine-readable contracts.
+
+## Identity boundary
+
+OIDC is the only authentication and identity source in the Web backend, which starts only when the DSH WebServer listens exactly on `127.0.0.1`. The plugin binds three values:
+
+- configured issuer;
+- configured public client ID;
+- authenticated `sub` shared by the ID Token and UserInfo response.
+
+`userinfo.name` is display-only and falls back to `userinfo.sub`. Key Binding `bootstrap.subject`, if present, is informational and cannot overwrite identity. This prevents a private management API from silently becoming a second, incompatible identity protocol.
+
+## Credential boundary
+
+The Key Binding service returns the model API key exactly once per resolve/provision/renew response. `dsh-oidc` writes it under the normalized Enterprise Profile credential reference. The default remains deterministically derived from Provider ID:
+
+```text
+example-ai -> EXAMPLE_AI_API_KEY
+```
+
+Production and test may retain the same Provider ID and wire-level `provider_id` while explicitly using different `keyBinding.credentialRef` values in their respective trusted Profiles. This separates local secret namespaces without changing the server protocol.
+
+The Provider adapter resolves that reference at request time. It never reads an ambient pi-ai credential store and never places the key in the Enterprise Profile, UI payload, logs, or DSH transcript. Web and native backends follow the same Profile rule. Native `enterpriseAccounts` is only a host capability adapter; it does not own credential naming, and a conflicting reference is rejected.
+
+Credential storage security is delegated to the active DSH Credential Provider. That is an explicit host contract, not proof that every DSH deployment is multi-user safe.
+
+## Provider ownership and extension
+
+Each profile declares one Provider ID and one or more models. `dsh-oidc` owns those routes through DSH's official `PiAiAdapter` and `@earendil-works/pi-ai` OpenAI Completions implementation.
+
+Optional feature plugins register a transform through the Cordis service `enterpriseTransforms`. A transform may:
+
+- advertise an aggregate modality for a specific Provider/model;
+- rewrite the provider-bound request;
+- inspect the model's native modalities.
+
+It must not mutate the durable transcript or register a competing adapter for the same route. Native multimodal routes can therefore bypass a text-only image-understanding fallback, while text-only routes can opt into it.
+
+## Native desktop boundary
+
+`backend: native` delegates identity lifecycle and optional mutable enterprise-provider management to a host service named `enterpriseAccounts`. This exists for desktop products that require operating-system browser launch, loopback coordination, OS credential vaults, or locally persisted provider choices.
+
+Wails is not part of this repository or interface. A non-Wails desktop, mobile host, or another local shell can implement the same service. The same component registers one `settings.section` entry in both modes: Web presents trusted Enterprise Profiles read-only, while a native host may advertise add/switch/model-edit/restart capabilities. This official whole-page extension avoids depending on or patching the internals of DSH's Models page. `uiMode: models-only` lets a product reuse exactly that surface while retaining separate account, quota, update, or diagnostic surfaces; `external` disables all plugin UI.
+
+## Deliberate exclusions
+
+- arbitrary userinfo endpoint or claim-path mapping;
+- arbitrary Key Binding paths/fields;
+- remote modules, CSS, tools, or skills;
+- model quota and institution directory schemas;
+- server-side web sessions for a shared multi-user DSH host;
+- dynamic Provider adapter selection.
+
+These exclusions reduce protocol ambiguity and keep executable trust local and reviewable.

package/docs/architecture.md

@@ -0,0 +1,125 @@
+# 架构与边界
+
+**简体中文** | [English](architecture.en.md)
+
+## 目标
+
+`dsh-oidc` 让机构无需 fork DSH，也无需依赖桌面外壳，就能把身份、授权、模型凭据、Provider 元数据和有边界的品牌能力接入普通 DSH Host。
+
+设计遵循五条规则：
+
+1. **DSH 负责运行时。** 插件使用 DSH 官方服务和 `PiAiAdapter`，不另建对话或模型传输栈。
+2. **身份遵循标准。** 认证使用 OIDC Discovery、Authorization Code + PKCE、ID Token、UserInfo、刷新和可选撤销。
+3. **机构服务是一个完整交付边界。** 同一服务所有者必须共同交付 OIDC、固定 Key Binding 和模型网关；Profile 只能声明这些协议表面的公开地址与事实。
+4. **配置是数据，不是代码。** Profile 不能选择可执行 adapter、任意接口路径、脚本、样式表、工具或 Skill。
+5. **产品特有能力围绕核心组合。** 通用企业模型设置界面属于 `dsh-oidc`；桌面外壳、配额视图、模型转换或机构业务页面仍由独立插件或服务承担。
+
+## 运行时组件
+
+| 组件 | 职责 | 信任级别 |
+| --- | --- | --- |
+| DSH Host | 生命周期、Cordis 服务、LLM 注册、WebServer、凭据和附件 | 受信任的可执行宿主 |
+| `dsh-oidc` Host 端 | Profile 校验、OIDC 客户端、Key Binding 客户端、本地 Provider 注册 | 受信任的本地插件 |
+| `dsh-oidc` Client 端 | 账号/引导界面、共用企业模型设置和有边界的品牌替换 | 受信任的本地插件 |
+| Enterprise Profile | 声明式集成事实 | 受信任配置，但仍以失败关闭方式校验 |
+| 机构企业模型集成服务 | 联合提供 OIDC 身份、Key Binding 授权/凭据生命周期和 OpenAI-compatible 模型网关 | 远程安全、授权和数据处理权威 |
+| 能力插件 | 可选的请求级转换，例如图像转文本回退 | 单独受信任的本地插件 |
+
+## 控制流
+
+```mermaid
+sequenceDiagram
+  participant B as 浏览器/UI
+  participant D as dsh-oidc
+  participant O as OIDC Provider
+  participant K as Key Binding 服务
+  participant C as DSH Credential Provider
+  participant L as DSH LLM/PiAiAdapter
+  participant M as 模型网关
+
+  B->>D: begin(profileID)
+  D->>O: Discovery
+  D-->>B: Authorization URL（state、nonce、PKCE）
+  B->>O: 用户认证与授权
+  O-->>D: http://127.0.0.1:port/oauth/callback?code&state
+  D->>O: Token 请求 + code_verifier
+  D->>O: JWKS 和 UserInfo
+  D->>D: 校验 ID Token 和 sub 一致性
+  D->>C: 保存 OIDC 会话
+  D->>K: 携带 Bearer access token 调用 GET /bootstrap
+  B->>D: 用户确认创建凭据
+  D->>K: POST /runtime-credential/provision
+  K-->>D: api_key
+  D->>C: 按 Profile 凭据引用保存 API Key
+  B->>L: 发起模型请求
+  L->>C: 解析运行时 API Key
+  L->>M: OpenAI-compatible 流式请求
+```
+
+图中 OIDC Provider、Key Binding 和模型网关是同一份[服务端接口规范](server-integration-contract.md)的三个接口组。它们可以在机构内部拆成不同系统或域名，但不能由部署方任选其一。Web 回调始终返回本机 `127.0.0.1`，不经过机构公网 DSH 地址。
+
+## 代码布局
+
+- `src/host/index.js`：DSH 服务入口和 Typert 远程方法。
+- `src/host/oidc.js`：Web 与 native 账号后端。
+- `src/host/profile.js`：校验、导入、公共投影和 Provider 投影。
+- `src/host/provider/`：本地 DSH/PiAi Provider adapter 和转换扩展点。
+- `src/client/`：DSH 浏览器 bundle、账号界面和远程描述符。
+- `schema/`：机器可读的 Enterprise Profile 契约。
+- `protocol/openapi.yaml`：机器可读的 Key Binding 契约。
+- `docs/`：规范正文、威胁模型和集成指南。
+
+Host 端文件保持为可读的原生 ESM，并在构建时复制到 `lib/`。Client 端代码被打包为 DSH module-loader 的闭包格式。发布包同时包含构建产物和两份机器可读契约。
+
+## 身份边界
+
+Web 后端只以 OIDC 作为认证和身份来源，并只在 DSH WebServer 精确监听 `127.0.0.1` 时启动。插件绑定三个值：
+
+- 配置的 issuer；
+- 配置的 public client ID；
+- 经认证且在 ID Token 与 UserInfo 中一致的 `sub`。
+
+`userinfo.name` 只用于显示，缺失时降级到 `userinfo.sub`。Key Binding `bootstrap.subject` 即使存在也只是信息字段，不能覆盖身份。这样可防止私有管理 API 悄悄变成第二套不兼容的身份协议。
+
+## 凭据边界
+
+Key Binding 服务在每次 resolve/provision/renew 响应中返回模型 API Key。`dsh-oidc` 将其写入 Enterprise Profile 解析后的 DSH 凭据引用。默认值仍由 Provider ID 确定性派生：
+
+```text
+example-ai -> EXAMPLE_AI_API_KEY
+```
+
+生产与测试可以保持相同的 Provider ID 和服务端 `provider_id`，同时在各自受信任的 Profile 中显式使用不同的 `keyBinding.credentialRef`。这只隔离本地秘密命名空间，不改变服务端协议。
+
+Provider adapter 在请求时解析该引用。它不会读取环境中的 pi-ai 凭据存储，也不会把密钥放入 Enterprise Profile、UI payload、日志或 DSH 对话记录。Web 后端和 native 后端使用同一 Profile 规则；native `enterpriseAccounts` 只是宿主能力适配器，不拥有凭据命名策略，若返回不一致的引用会被拒绝。
+
+凭据存储安全性委托给当前 DSH Credential Provider。这是一项明确的宿主契约，并不意味着任意 DSH 部署都天然具备多用户安全性。
+
+## Provider 所有权与扩展
+
+每个 Profile 声明一个 Provider ID 和一个或多个模型。`dsh-oidc` 通过 DSH 官方 `PiAiAdapter` 和 `@earendil-works/pi-ai` 的 OpenAI Completions 实现拥有这些路由。
+
+可选功能插件可通过 Cordis 服务 `enterpriseTransforms` 注册转换。转换可以：
+
+- 为指定 Provider/模型声明聚合后的输入模态；
+- 重写即将发送给 Provider 的请求；
+- 检查模型的原生模态。
+
+转换不得修改持久对话记录，也不得为同一路由注册竞争 adapter。因此，原生多模态路由可绕过仅面向文本模型的图像理解回退，而纯文本路由可以选择接入该能力。
+
+## Native 桌面边界
+
+`backend: native` 会把身份生命周期和可选的可变企业 Provider 管理委托给名为 `enterpriseAccounts` 的宿主服务。该模式适用于需要操作系统浏览器启动、回环协调、系统凭据保险库或本地 Provider 选择的桌面产品。
+
+Wails 不属于本仓库或接口。非 Wails 桌面端、移动宿主或其他本地外壳都可以实现同一服务。Web 与 native 模式由同一组件注册一个 `settings.section`：Web 只读展示受信任的 Enterprise Profile，native 宿主可声明新增、切换、模型编辑和重启能力。这个官方整页扩展点不依赖也不修改 DSH“模型”页面内部实现。`uiMode: models-only` 允许产品只复用该界面，同时保留独立账号、配额、更新或诊断界面；`external` 则关闭插件全部 UI。
+
+## 明确排除
+
+- 任意 UserInfo endpoint 或 claim 路径映射；
+- 任意 Key Binding 路径或字段；
+- 远程模块、CSS、工具或 Skill；
+- 模型配额和机构目录协议；
+- 共享多用户 DSH Host 的服务端 Web 会话；
+- 动态 Provider adapter 选择。
+
+这些排除项减少协议歧义，并让可执行信任边界保持在本地、可审查范围内。

package/docs/compatibility.en.md

@@ -0,0 +1,61 @@
+# Compatibility and release policy
+
+[简体中文](compatibility.md) | **English**
+
+## Tested matrix
+
+| dsh-oidc | Node.js | DSH | pi-ai | Status |
+| --- | --- | --- | --- | --- |
+| `0.1.0-alpha.11` | 22, 24 | Declared baseline remains `0.1.2-alpha.2`; separate mainline `0.1.2-rc.1` configuration RPC probe | `^0.84.2` | npm scope migration with persistent contracts retained; the rc.1 probe is not full compatibility acceptance. |
+| `0.1.0-alpha.10` | 22, 24 | `0.1.2-alpha.2` / `0a53fb55…` | `^0.84.2` (`0.84.4` in npm/source Runtimes) | Migrated to `SettingsProvider.installSection()`; full checks pass through both npm and source release-pack paths. |
+| `0.1.0-alpha.9` | 22, 24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2` (`0.84.4` in the reviewed source Runtime) | Web and native consume only standard Enterprise Profiles; product institution-catalog conversion is completely outside the plugin. |
+| `0.1.0-alpha.8` | 22, 24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2` (`0.84.4` in the reviewed source Runtime) | Shared Web/native Profile credential-reference rule, production/test local-key isolation, and fail-closed native mismatch handling. |
+| `0.1.0-alpha.7` | 22, 24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2` (`0.84.4` in the reviewed source Runtime) | An exact network HTTP origin may be allowed for development; production remains HTTPS-only. |
+| `0.1.0-alpha.6` | 22, 24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2` (`0.84.4` in the reviewed source Runtime) | Uses the upstream Models page and official `settings.models.footer`; validate through a source release-pack until matching npm packages are published. |
+| `0.1.0-alpha.5` | 22, 24 (development) | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | Local-checkout-first installation documentation; runtime behavior is unchanged from alpha.4. |
+| `0.1.0-alpha.4` | 22, 24 (development) | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | Direct DSH Web Bundle installation and complete third-party deployment documentation; product/Web acceptance completed in the ECNU reference composition. |
+| `0.1.0-alpha.3` | 22, 24 (development) | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | Shared Web/native enterprise-model settings and native capability adapter; end-to-end product acceptance pending. |
+| `0.1.0-alpha.2` | 22, 24 (development) | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | Standard UserInfo name presentation unified across Web and native adapters; real deployment acceptance pending. |
+| `0.1.0-alpha.1` | 22, 24 (development) | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | Unit/build/package baseline; real deployment acceptance still required. |
+
+Only exact DSH peer versions in `package.json` are supported. Other versions may install only after explicit peer override and are untested.
+
+## Contract versions
+
+- Enterprise Profile: `dsh-oidc/v1alpha1`
+- Key Binding: `worker-user-center-v1`
+- Typert package/namespace: `@eduwork/dsh-oidc` / `oidcAccounts`
+- Browser management projection: `dsh-oidc/management/v1alpha1`
+- Callback path: `/oauth/callback`
+- Provider transform service: `enterpriseTransforms`
+- Legacy-compatible Provider settings namespace: `provider-enterprise`
+
+Changing any item above requires compatibility analysis and, where wire-visible, a new contract version.
+
+## Project semver
+
+Before `1.0.0`, minor versions may contain incompatible alpha contract changes, but release notes and migration instructions are required. Patch versions must be backward compatible within the same documented contract version.
+
+After `1.0.0`:
+
+- additive optional profile fields and error codes may be minor releases;
+- removing/renaming fields, changing fixed paths, callback path, default credential derivation, or identity rules requires a major release or a separately versioned contract;
+- security hardening that rejects previously accepted unsafe input may ship in a minor or patch release with prominent notice.
+
+## Release gates
+
+No public tag/npm publish until all of the following pass:
+
+- `npm ci` from a clean checkout;
+- `npm run check` on Windows and Linux;
+- CodeQL or equivalent static analysis;
+- dependency/license and install-script review;
+- secret/production-endpoint scan;
+- npm tarball content review;
+- plain Web end-to-end acceptance;
+- native desktop no-regression acceptance;
+- OIDC negative tests and Key Binding authorization tests;
+- documentation/version/changelog update;
+- two-person review for authentication, credential, build, or release workflow changes.
+
+See [the public release checklist](release-checklist.en.md) for the operator checklist.

package/docs/compatibility.md

@@ -0,0 +1,61 @@
+# 兼容性与发布策略
+
+**简体中文** | [English](compatibility.en.md)
+
+## 已测试矩阵
+
+| dsh-oidc | Node.js | DSH | pi-ai | 状态 |
+| --- | --- | --- | --- | --- |
+| `0.1.0-alpha.11` | 22、24 | 声明基线仍为 `0.1.2-alpha.2`；另有主线 `0.1.2-rc.1` 隔离配置 RPC 探针 | `^0.84.2` | npm 作用域迁移；保留数据协议；不将 rc.1 探针视为完整版本兼容验收。 |
+| `0.1.0-alpha.10` | 22、24 | `0.1.2-alpha.2` / `0a53fb55…` | `^0.84.2`（npm/源码 Runtime 中为 `0.84.4`） | 迁移到 `SettingsProvider.installSection()`；npm 与源码 release-pack 双路径通过完整检查。 |
+| `0.1.0-alpha.9` | 22、24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2`（已审查源码 Runtime 中为 `0.84.4`） | Web/native 只消费标准 Enterprise Profile；产品机构目录转换彻底移出插件。 |
+| `0.1.0-alpha.8` | 22、24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2`（已审查源码 Runtime 中为 `0.84.4`） | Web/native 共用 Profile 凭据引用规则；支持生产/测试本地 Key 隔离，并对 native 引用错配失败关闭。 |
+| `0.1.0-alpha.7` | 22、24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2`（已审查源码 Runtime 中为 `0.84.4`） | 开发环境可显式允许一个精确的网络 HTTP origin；生产仍强制 HTTPS。 |
+| `0.1.0-alpha.6` | 22、24 | `0.1.2-alpha.1` / `cd5ef814…` | `^0.84.2`（已审查源码 Runtime 中为 `0.84.4`） | 使用上游“模型”页面和官方 `settings.models.footer`；匹配的 npm 包发布前，应通过源码 release-pack 验证。 |
+| `0.1.0-alpha.5` | 22、24（开发） | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | 文档改为优先从本地 checkout 安装；运行行为与 alpha.4 相同。 |
+| `0.1.0-alpha.4` | 22、24（开发） | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | 支持直接安装 DSH Web Bundle，并提供完整第三方部署文档；ECNU 参考组合已完成产品/Web 验收。 |
+| `0.1.0-alpha.3` | 22、24（开发） | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | Web/native 共用企业模型设置和 native 能力 adapter；尚待端到端产品验收。 |
+| `0.1.0-alpha.2` | 22、24（开发） | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | Web 与 native adapter 统一使用标准 UserInfo 姓名显示；尚待真实部署验收。 |
+| `0.1.0-alpha.1` | 22、24（开发） | `0.1.1-rc.2` / `b150a551…` | `0.82.1` | 单元测试、构建和打包基线；仍需真实部署验收。 |
+
+仅支持 `package.json` 中声明的精确 DSH peer 版本。其他版本即使通过显式 peer override 安装，也属于未经测试的组合。
+
+## 契约版本
+
+- Enterprise Profile：`dsh-oidc/v1alpha1`
+- Key Binding：`worker-user-center-v1`
+- Typert 包/命名空间：`@eduwork/dsh-oidc` / `oidcAccounts`
+- 浏览器管理投影：`dsh-oidc/management/v1alpha1`
+- 回调路径：`/oauth/callback`
+- Provider 转换服务：`enterpriseTransforms`
+- 兼容旧版的 Provider 设置命名空间：`provider-enterprise`
+
+修改上述任一项都必须进行兼容性分析；涉及网络可见契约时，必须发布新的契约版本。
+
+## 项目语义化版本
+
+在 `1.0.0` 之前，minor 版本可以包含不兼容的 alpha 契约变更，但必须提供发布说明和迁移指引。同一已记录契约版本中的 patch 版本必须向后兼容。
+
+在 `1.0.0` 之后：
+
+- 新增可选 Profile 字段和错误码可以作为 minor 版本发布；
+- 删除或重命名字段、修改固定路径、回调路径、默认凭据派生或身份规则，需要 major 版本或单独版本化的契约；
+- 因安全加固而拒绝此前接受的不安全输入，可以在醒目说明后作为 minor 或 patch 版本发布。
+
+## 发布门槛
+
+以下项目全部通过前，不得创建公开 tag 或发布 npm 包：
+
+- 在干净 checkout 中执行 `npm ci`；
+- Windows 和 Linux 上执行 `npm run check`；
+- CodeQL 或等效静态分析；
+- 依赖、许可证和安装脚本审查；
+- 密钥与生产地址扫描；
+- npm tarball 内容审查；
+- 纯 Web 端到端验收；
+- native 桌面无回退验收；
+- OIDC 反向测试和 Key Binding 授权测试；
+- 文档、版本和变更日志更新；
+- 对认证、凭据、构建或发布流程变更进行双人审查。
+
+操作检查项见[公开发布检查表](release-checklist.md)。

package/docs/decisions/0001-one-plugin-composition-boundary.en.md

@@ -0,0 +1,34 @@
+# ADR 0001: One plugin for the enterprise integration loop
+
+[简体中文](0001-one-plugin-composition-boundary.md) | **English**
+
+- Status: Accepted for alpha
+- Date: 2026-08-25
+
+## Context
+
+The original product implementation coupled OIDC account behavior, institution catalog, a private Provider package, desktop bridges, and product features. Publishing only the login portion would leave users unable to call a model; publishing every desktop concern would bind the standard to Wails and one institution.
+
+## Decision
+
+Publish one project/package named `dsh-oidc` containing:
+
+- standard OIDC Web client and a host-neutral native adapter contract;
+- the fixed Key Binding client;
+- one local audited OpenAI-compatible DSH Provider adapter;
+- declarative Provider/model and bounded brand configuration;
+- standard account UI and one capability-aware enterprise-model settings surface shared by Web/native hosts;
+- `models-only` and external UI composition modes;
+- a stable local model-transform service.
+
+Keep desktop shells, quotas, institutional business APIs, search, vision implementations, skills, packaging, and updates outside this repository.
+
+Enterprise Profiles are data and cannot select executable adapters or customize Key Binding wire fields.
+
+## Consequences
+
+- A plain Web DSH can complete enterprise login-to-model flow with one plugin plus a profile.
+- Desktop products preserve richer native operations behind host services while inheriting the same provider/model UI.
+- The former private Provider package is internalized, eliminating an unpublished dependency.
+- The plugin carries more responsibility than a generic OIDC login widget, so its security and compatibility review must cover credentials and model transport integration.
+- Additional Provider protocol families require reviewed local code and an architectural decision; they cannot be enabled by remote profile data.

package/docs/decisions/0001-one-plugin-composition-boundary.md

@@ -0,0 +1,34 @@
+# ADR 0001：企业集成闭环采用单插件组合边界
+
+**简体中文** | [English](0001-one-plugin-composition-boundary.en.md)
+
+- 状态：Alpha 阶段已接受
+- 日期：2026-08-25
+
+## 背景
+
+原产品实现把 OIDC 账号行为、机构目录、私有 Provider 包、桌面桥接和产品功能耦合在一起。若只发布登录部分，用户无法真正调用模型；若发布所有桌面相关内容，又会把标准绑定到 Wails 和单一机构。
+
+## 决策
+
+发布一个名为 `dsh-oidc` 的项目和软件包，包含：
+
+- 标准 OIDC Web 客户端和宿主中立的 native adapter 契约；
+- 固定 Key Binding 客户端；
+- 一个本地、经过审查的 OpenAI-compatible DSH Provider adapter；
+- 声明式 Provider/模型配置和有边界的品牌配置；
+- 标准账号 UI，以及 Web/native 宿主共用、可感知宿主能力的企业模型设置界面；
+- `models-only` 和 external UI 组合模式；
+- 稳定的本地模型转换服务。
+
+桌面外壳、配额、机构业务 API、搜索、图像理解实现、Skill、打包和更新继续留在本仓库之外。
+
+Enterprise Profile 只是数据，不能选择可执行 adapter，也不能自定义 Key Binding 网络字段。
+
+## 影响
+
+- 普通 Web DSH 只需一个插件和一个 Profile，就能完成从企业登录到模型调用的闭环。
+- 桌面产品可在宿主服务后保留更丰富的 native 操作，同时继承相同的 Provider/模型 UI。
+- 原私有 Provider 包被内化，消除了未公开依赖。
+- 插件职责大于通用 OIDC 登录控件，因此安全和兼容审查必须覆盖凭据及模型传输集成。
+- 新增其他 Provider 协议族需要经过审查的本地代码和架构决策，不能由远程 Profile 数据启用。