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

package/docs/architecture.en.md

@@ -2,124 +2,19 @@
 
 [简体中文](architecture.md) | **English**
 
-## Goals
+One Host account service composes identity, token lifecycle and the DSH model Provider. Servers own authorization; clients consume explicit contracts.
 
-`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.
+| Layer | Responsibility |
+| --- | --- |
+| Profile | Trusted public settings, full discovery URL, protocol opt-in and branding |
+| oidc.js / desktop-oidc.js | Shared identity validation, session writes, browser and loopback callback |
+| gateway-backend.js | Token resources, single-flight refresh, authorization isolation, logout and catalogs |
+| litellm-protocol.js / oidc-llm-protocol.js | Protocol-specific discovery, registration and response validation |
+| DSH Provider | Shared requests, JSON/SSE, attachments and reasoning |
+| Institution extensions | Optional own-account quota through shared Host transport |
 
-The design follows five rules:
+OIDC mode reuses the strict ID Token verifier. LiteLLM native validates its separate identity contract. Both model integrations use Access Tokens without a Key Binding fallback. Plain oidc configuration is identity-only.
 
-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.** Managed models require one accountable owner to jointly deliver OIDC, fixed Key Binding and the model gateway; identity-only mode requires only OIDC. 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.
+After browser Code + PKCE, the Host saves the authorization session and loads its catalog. Requests resolve the current Access Token and share refresh near expiry. Logout, reauthorization or account changes invalidate old calls. Secrets stay in Host credential storage, outside renderer configuration.
 
-## 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, managed-model mode needs all three groups, while identity-only mode omits the two model-resource groups. 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`: Shared Web/desktop OIDC implementation and the legacy native adapter.
-- `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 is a single institution-neutral reference:
-
-```text
-EDUWORK_API_KEY
-```
-
-Legacy automatic names normalize to `EDUWORK_API_KEY`; other explicit references remain unchanged. A credential fingerprint is stored alongside verified identity and the complete resource binding in the Host session. Network use and logout cleanup require the current key to belong to that session. The fingerprint is never projected into RPC, logs or conversation text. See the [Profile specification](enterprise-profile.en.md) for migration boundaries.
-
-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.
-
-## Desktop and legacy native boundary
-
-New desktop products use `backend: desktop`: a temporary loopback callback and official browser service share the OIDC/Key/model implementation across Wails and Electron. The host supplies credential storage. Legacy `backend: native` delegates to `enterpriseAccounts` only for existing bridges; see [desktop integration](desktop-host.en.md).
-
-The shared UI uses official `settings.models.footer`, onboarding, sidebar and general-settings slots. Institution configuration is read-only trusted data. Legacy bridge mutation methods are compatibility APIs, not a requirement or default UI for new institutions. `models-only` mounts the shared model-settings surface; `external` disables plugin UI. Quota and heartbeat remain in explicitly installed institution extensions.
-
-## 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.
+See [security](security-model.en.md), [Host integration](dsh-integration.en.md) and [gateway contracts](gateway-auth/README_EN.md).

package/docs/architecture.md

@@ -2,125 +2,19 @@
 
 **简体中文** | [English](architecture.en.md)
 
-## 目标
+客户端以一个 Host 账户服务组合身份、Token 生命周期和 DSH 模型 Provider。服务端负责授权，客户端只消费明确声明的协议。
 
-`dsh-oidc` 让机构无需 fork DSH，也无需依赖桌面外壳，就能把身份、授权、模型凭据、Provider 元数据和有边界的品牌能力接入普通 DSH Host。
+| 层次 | 职责 |
+| --- | --- |
+| Profile | 可信公开配置、完整发现地址、协议开关及品牌数据 |
+| oidc.js / desktop-oidc.js | 共用身份验证、会话写入、浏览器和本机回调 |
+| gateway-backend.js | Token 资源、并发刷新、授权隔离、退出及模型目录 |
+| litellm-protocol.js / oidc-llm-protocol.js | 各协议的发现、注册与响应校验 |
+| DSH Provider | 共用模型请求、JSON/SSE、附件和推理参数 |
+| 机构扩展 | 通过共享 Host 传输处理本人配额等可选能力 |
 
-设计遵循五条规则：
+OIDC 模式沿用严格 ID Token 验证器；LiteLLM native 的身份契约独立校验。两种模型接入均使用 Access Token，不存在 Key Binding 备用分支。oidc 配置只用于纯身份模式。
 
-1. **DSH 负责运行时。** 插件使用 DSH 官方服务和 `PiAiAdapter`，不另建对话或模型传输栈。
-2. **身份遵循标准。** 认证使用 OIDC Discovery、Authorization Code + PKCE、ID Token、UserInfo、刷新和可选撤销。
-3. **机构服务是一个完整交付边界。** 托管模型模式要求服务所有者共同交付 OIDC、固定 Key Binding 和模型网关；纯身份模式只需 OIDC。Profile 只能声明这些协议表面的公开地址与事实。
-4. **配置是数据，不是代码。** Profile 不能选择可执行 adapter、任意接口路径、脚本、样式表、工具或 Skill。
-5. **产品特有能力围绕核心组合。** 通用企业模型设置界面属于 `dsh-oidc`；桌面外壳、配额视图、模型转换或机构业务页面仍由独立插件或服务承担。
+浏览器完成 Code + PKCE 后，Host 保存授权会话并加载获授权目录。调用前解析有效 Access Token；临近到期合并刷新。退出、重新授权或账户切换使旧调用失效。秘密由 Host 凭据服务保存，不进入 renderer 配置。
 
-## 运行时组件
-
-| 组件 | 职责 | 信任级别 |
-| --- | --- | --- |
-| 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/desktop 共用 OIDC 实现及旧 native adapter。
-- `src/host/desktop-oidc.js`：临时 loopback 登录与取消。
-- `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 凭据引用。默认值统一为机构无关的公共引用：
-
-```text
-EDUWORK_API_KEY
-```
-
-旧自动引用按 Profile 规则兼容到 `EDUWORK_API_KEY`，其他显式引用保持不变。模型 Key 指纹与已验证身份及完整资源绑定一起保存在 Host 会话中；任何网络使用和登出清理都要求当前值仍归属于该会话。指纹不通过 RPC、日志或对话输出。迁移范围见 [Profile 规范](enterprise-profile.md)。
-
-Provider adapter 在请求时解析该引用。它不会读取环境中的 pi-ai 凭据存储，也不会把密钥放入 Enterprise Profile、UI payload、日志或 DSH 对话记录。Web 后端和 native 后端使用同一 Profile 规则；native `enterpriseAccounts` 只是宿主能力适配器，不拥有凭据命名策略，若返回不一致的引用会被拒绝。
-
-凭据存储安全性委托给当前 DSH Credential Provider。这是一项明确的宿主契约，并不意味着任意 DSH 部署都天然具备多用户安全性。
-
-## Provider 所有权与扩展
-
-托管资源 Profile 声明 Provider ID，以及本地模型或发现模式；纯身份 Profile 不声明 Provider。`dsh-oidc` 通过 DSH 官方 `PiAiAdapter` 和 `@earendil-works/pi-ai` 的 OpenAI Completions 实现拥有这些路由。
-
-可选功能插件可通过 Cordis 服务 `enterpriseTransforms` 注册转换。转换可以：
-
-- 为指定 Provider/模型声明聚合后的输入模态；
-- 重写即将发送给 Provider 的请求；
-- 检查模型的原生模态。
-
-转换不得修改持久对话记录，也不得为同一路由注册竞争 adapter。因此，原生多模态路由可绕过仅面向文本模型的图像理解回退，而纯文本路由可以选择接入该能力。
-
-## Desktop 与旧 native 边界
-
-新桌面使用 `backend: desktop`：临时 loopback 回调和官方浏览器服务在 Wails/Electron 间共享 OIDC/Key/模型实现，凭据存储仍由宿主提供。旧 `backend: native` 仅为已有桥接委托 `enterpriseAccounts`。见[桌面集成](desktop-host.md)。
-
-共用 UI 使用官方 `settings.models.footer`、onboarding、侧栏和通用设置插槽。机构配置是只读可信数据；旧桥的可变管理方法只是兼容 API，不是新机构的默认 UI 或必需接口。`models-only` 只挂共用模型设置，`external` 关闭插件 UI。配额和心跳由显式安装的机构扩展提供。
-
-## 明确排除
-
-- 任意 UserInfo endpoint 或 claim 路径映射；
-- 任意 Key Binding 路径或字段；
-- 远程模块、CSS、工具或 Skill；
-- 模型配额和机构目录协议；
-- 共享多用户 DSH Host 的服务端 Web 会话；
-- 动态 Provider adapter 选择。
-
-这些排除项减少协议歧义，并让可执行信任边界保持在本地、可审查范围内。
+详情：[安全模型](security-model.md)、[Host 集成](dsh-integration.md)、[网关协议](gateway-auth/README.md)。

package/docs/compatibility.en.md

@@ -2,48 +2,14 @@
 
 [简体中文](compatibility.md) | **English**
 
-## Runtime requirements
+Runtime and DSH compatibility follow package.json, dependency locks and measured results. Source tests are not a complete packaged desktop acceptance.
 
-The 0.2.x source targets DSH `0.1.5-rc.1`, Cordis `4.0.2` and pi-ai `0.85.1`. Use Node.js 22 or 24 and the checked-in lockfile for development. Align all DSH packages in the host; a retained peer range does not establish support for every deployment.
+The current source supports LiteLLM native contract 1, explicitly enabled experimental oidc-llm 0.1 and standard identity-only OIDC. oidc-llm remains a draft and is disabled by default.
 
-The older stable 0.1.0 package targets DSH 0.1.2-rc.1. Check the host before upgrading. See [development](development.en.md) for dependency and integration checks.
+This branch removes Key Binding model flows and backend: native account bridging; old profiles fail explicitly. New clients use Tokens while servers may retain legacy endpoints for released clients. This breaking change is unpublished. Choose an appropriate new package version and reviewed product locks before publication; never overwrite an existing npm version.
 
-## Contract versions
+## Validation
 
-- Enterprise Profile: `dsh-oidc/v1alpha1`
-- Key Binding Profile selector: `worker-user-center-v1` or `eduwork-resources-v1`; accepted Bootstrap wire aliases: `worker.user-center.v1`, `worker-user-center/v1`, `eduwork-resources/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`
+Package checks cover types, builds, shared identity/gateway regressions, schemas, documentation, secrets and packaging. Real OIDC/LiteLLM, desktop encryption, restart and UI require separately identified acceptance evidence.
 
-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;
-- independent technical review, CI/focused regression evidence, and a recorded maintainer decision for authentication, credential, build, or release workflow changes; add independent human approval after a second maintainer joins.
-
-See [the public release checklist](release-checklist.en.md) for the operator checklist.
+See [migration](key-binding-protocol.en.md) and [development](development.en.md). Source changes, npm publication, application assembly and production deployment remain separate operations.

package/docs/compatibility.md

@@ -2,48 +2,14 @@
 
 **简体中文** | [English](compatibility.en.md)
 
-## 运行环境
+运行环境和 DSH 兼容范围以 package.json、依赖锁及对应实测为准，不能把源码测试等同于整包发行验收。
 
-0.2.x 源码面向 DSH `0.1.5-rc.1`、Cordis `4.0.2` 和 pi-ai `0.85.1`。开发使用 Node.js 22 或 24 及本模块的依赖锁。宿主中的 DSH 包必须保持一致；保留的 peer 范围不代表任意部署组合均受支持。
+当前源码支持 LiteLLM native contract 1、显式启用的 oidc-llm 0.1 实验模型接入，以及不附带模型资源的标准 OIDC 身份登录。oidc-llm 尚未定稿，默认关闭。
 
-旧稳定包 0.1.0 对应 DSH 0.1.2-rc.1，升级前先检查宿主。依赖和接入检查见[开发说明](development.md)。
+本分支已删除旧 Key Binding 模型流程和 backend: native 账户桥，旧配置会报错。新客户端使用 Token；服务端可保留旧接口兼容已经发布的老客户端。此次破坏性变更尚未发布，发布前需选择合适的新包版本并同步已审查的产品锁，不能覆盖旧 npm 版本。
 
-## 契约版本
+## 验证要求
 
-- Enterprise Profile：`dsh-oidc/v1alpha1`
-- Key Binding Profile 配置名称：`worker-user-center-v1` 或 `eduwork-resources-v1`；Bootstrap wire 兼容名称：`worker.user-center.v1`、`worker-user-center/v1`、`eduwork-resources/v1`
-- Typert 包/命名空间：`@eduwork/dsh-oidc` / `oidcAccounts`
-- 浏览器管理投影：`dsh-oidc/management/v1alpha1`
-- 回调路径：`/oauth/callback`
-- Provider 转换服务：`enterpriseTransforms`
-- 兼容旧版的 Provider 设置命名空间：`provider-enterprise`
+包级检查包含类型、构建、共享身份与网关回归、Schema、文档、秘密扫描和打包。真实 OIDC/LiteLLM、桌面加密存储、重启和界面分别验收，报告必须区分实际覆盖。
 
-修改上述任一项都必须进行兼容性分析；涉及网络可见契约时，必须发布新的契约版本。
-
-## 项目语义化版本
-
-在 `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 授权测试；
-- 文档、版本和变更日志更新；
-- 对认证、凭据、构建或发布流程变更完成独立技术复核、CI/专项回归并记录维护者决定；增加第二位维护者后再加入独立人工批准。
-
-操作检查项见[公开发布检查表](release-checklist.md)。
+迁移见[旧方案说明](key-binding-protocol.md)，构建见[开发指南](development.md)。源码、npm 发布、客户端装配和生产部署分别执行。

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

@@ -14,7 +14,7 @@ The original product implementation coupled OIDC account behavior, institution c
 Publish one project/package named `dsh-oidc` containing:
 
 - standard OIDC Web client and a host-neutral native adapter contract;
-- the fixed Key Binding client;
+- shared token authorization and lifecycle;
 - 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;
@@ -23,7 +23,7 @@ Publish one project/package named `dsh-oidc` containing:
 
 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.
+Enterprise Profiles are data and cannot select executable adapters or override discovered authorization boundaries.
 
 ## Consequences
 

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

@@ -14,7 +14,7 @@
 发布一个名为 `dsh-oidc` 的项目和软件包，包含：
 
 - 标准 OIDC Web 客户端和宿主中立的 native adapter 契约；
-- 固定 Key Binding 客户端；
+- 共享 Token 授权和生命周期；
 - 一个本地、经过审查的 OpenAI-compatible DSH Provider adapter；
 - 声明式 Provider/模型配置和有边界的品牌配置；
 - 标准账号 UI，以及 Web/native 宿主共用、可感知宿主能力的企业模型设置界面；
@@ -23,7 +23,7 @@
 
 桌面外壳、配额、机构业务 API、搜索、图像理解实现、Skill、打包和更新继续留在本仓库之外。
 
-Enterprise Profile 只是数据，不能选择可执行 adapter，也不能自定义 Key Binding 网络字段。
+Enterprise Profile 只是数据，不能选择可执行 adapter，也不能改写已发现的授权边界。
 
 ## 影响
 

package/docs/desktop-host.en.md

@@ -2,7 +2,7 @@
 
 [简体中文](desktop-host.md)
 
-`backend: desktop` uses a temporary loopback callback for desktop sign-in. OIDC validation, host credentials, Key Binding, model discovery and `authorizedFetch()` reuse the Web implementation; existing `web` and legacy native bridge modes remain supported.
+`backend: desktop` uses a temporary loopback callback for desktop sign-in. OIDC validation, host credentials, token refresh, model discovery and authorizedFetch reuse shared code. Web and desktop are supported; the legacy native account bridge is removed.
 
 ```yaml
 - id: enterprise-oidc
@@ -20,7 +20,6 @@ The host supplies a Cordis `desktopServices` service with `openExternal(url: str
 
 When the distribution provides `configFile: {path, examplesPath}`, organization settings stay read-only and are loaded again on restart. The optional Host method `openConfiguration(target: 'config' | 'examples'): Promise<void>` enables configuration-file and example-folder buttons. The RPC accepts these two fixed targets only; the host resolves its own paths, and the renderer cannot send a path or command. `configuration().configFile.canOpen` reports availability. Web hosts without this capability show the configuration-file location instead. Personal models and configured organization sign-in remain available.
 
-Resource binding accepts the original `worker.user-center.v1`, the transitional `worker-user-center/v1`, and `eduwork-resources/v1`. Unknown versions and mismatched Provider IDs are rejected before creating a model credential. Completed identity sign-in is retained, with an error identifying the separate resource/configuration problem.
 
 The host must implement `credentials.resolve/set/unset`, backed by its operating-system vault. The plugin has no plaintext credential file or fallback on storage failure. OAuth tokens remain Host-only. Personal API keys remain independent of the organization's managed credential. The public `oidcAccounts.authorizedFetch()` capability remains Host-only.
 
@@ -36,11 +35,11 @@ Shared Host/Client RPC additions:
 
 Sign-in, sidebar and organization settings share one account snapshot. Credential Providers should emit the official `credentials/reference-updated` event after set/unset. The client listens to that forwarded Remote event and `connection/reset`; it does not depend on a custom account event that the official Remote transport does not forward.
 
-Explicit sign-in with a connected key, or confirmed key provisioning, selects the first resolvable enterprise model. A default is saved even when no session exists. For a current main session, the client also uses the official `modelDirectories.directoryFor(sessionID).select()` API; addressed subagents are left alone. Load the official `agentDefaultModel` and writable `settings` services. Older hosts without this capability show a message asking the user to choose from the model menu.
+Explicit sign-in with a connected model service selects the first resolvable enterprise model. A default is saved even when no session exists. For a current main session, the client also uses the official `modelDirectories.directoryFor(sessionID).select()` API; addressed subagents are left alone. Load the official `agentDefaultModel` and writable `settings` services. Older hosts without this capability show a message asking the user to choose from the model menu.
 
 Initial upgrade recovery uses `onlyIfMissing:true`: it preserves an existing resolvable default and repairs only an absent or unavailable one. A valid personal selection in the current session is also preserved. Credential events, connection checks and subsequent status refreshes never select a model. Personal credentials and unrelated settings remain unchanged.
 
-For desktop acceptance run `node scripts/serve-desktop-oidc-fixture.mjs --config <new test configuration file>`. It binds a random loopback port, serves synthetic HTTP PKCE/Key/models/quota and writes a public JSONC profile. The file must not exist; user configuration is never overwritten. Use isolated data directories for each shell and Ctrl+C to stop. No real accounts or model credits are used.
+For desktop acceptance run `node scripts/serve-desktop-oidc-fixture.mjs --config <new test configuration file>`. It binds a random loopback port, serves synthetic HTTP PKCE/Token/models/quota and writes a public JSONC profile. The file must not exist; user configuration is never overwritten. Use isolated data directories for each shell and Ctrl+C to stop. No real accounts or model credits are used.
 
 The independent random login handle is not OAuth state. Results never carry an authorization URL, code, nonce, verifier or token. The client polls once per second, displays browser completion instructions and a cancel button, and cancels on unmount. Sign-in expires within ten minutes. Closing a system browser cannot reliably be detected across platforms; the app cancel action and expiry bound the listener lifetime.
 
@@ -48,7 +47,7 @@ An empty Profile list is valid: no listener or organization login is needed. Ide
 
 Run `node --test test/desktop.test.js test/desktop-host.test.js`. To test a frozen installation, set `DSH_OIDC_PACKAGE_ROOT` to its package directory and `DSH_OIDC_EXPECT_DSH=0.1.5-rc.1`. The latter test uses the installed package's actual Host dependencies without WebServer, optional browser-service lifecycle and HTTP PKCE. All credentials and identities are synthetic. Shell vault, window and system-browser integration still require product acceptance.
 
-The `.20260910.6` public avatar menu provides account refresh and sign-out; quota UI requires an institution extension. A portal supports narrow sidebars; arrows, Home/End, Escape and outside click/focus are supported. Logout clears this profile's local identity, managed key and cached model metadata, serializes vault writes and rejects late writes. Personal keys remain untouched.
+The `.20260910.6` public avatar menu provides account refresh and sign-out; quota UI requires an institution extension. A portal supports narrow sidebars; arrows, Home/End, Escape and outside click/focus are supported. Logout clears this profile's local identity, Tokens and cached model metadata, serializes vault writes and rejects late writes. Personal keys remain untouched.
 
 The temporary HTTP callback page reads `brand.productName/organizationName/logoURL/mark/primaryColor` from this attempt's Profile and chooses Chinese or English from Accept-Language. It has no external fonts, scripts or raw error reflection and directs the user back to the app. Ordinary Web validation still redirects into its local app; model keys never enter the browser.
 

package/docs/desktop-host.md

@@ -2,7 +2,7 @@
 
 [English](desktop-host.en.md)
 
-`backend: desktop` 通过临时 loopback 回调接入桌面登录，复用 Web 后端的 OIDC 校验、Host credentials、Key Binding 和模型发现协议。既有 `web` 和 Go 桥 `native` 配置继续可用。
+`backend: desktop` 通过临时 loopback 回调接入桌面登录，复用 Web 后端的 OIDC 校验、Host credentials、Token 刷新和模型发现。支持 web 和 desktop；旧 native 账户桥已移除。
 
 ```yaml
 - id: enterprise-oidc
@@ -28,9 +28,8 @@ OIDC 从受信 Profile 对应的 Discovery 构造 HTTP(S) 授权 URL。此 URL
 
 发行方提供 `configFile: {path, examplesPath}` 时，企业服务保持只读，由用户编辑文件后重启应用。若宿主提供 `openConfiguration`，设置显示“打开配置文件”和“查看示例”；RPC 只接收 `config` / `examples`，由宿主解析固定路径，不允许 renderer 传路径或命令。`configuration().configFile.canOpen` 声明是否可直接打开；Web 或未提供该能力的宿主显示配置文件位置作为备用。个人 API Key 设置和已配置企业的身份登录继续可用。
 
-资源绑定兼容既有 `worker.user-center.v1`、过渡写法 `worker-user-center/v1` 与 `eduwork-resources/v1`。未知版本或不匹配的 Provider ID 在创建模型凭据前拒绝，保留已完成的身份登录，并提示检查模型资源服务或企业配置；它们不是身份验证失败。
 
-宿主必须提供 `credentials.resolve/set/unset`。本插件没有明文凭据文件或存储失败后的备用路径；桌面发行方负责接入操作系统保险库。模型调用仍使用独立运行 Key，OAuth token 不经 RPC 返回 renderer。`oidcAccounts.authorizedFetch()` 仍是 Host-only 公共授权请求入口。
+宿主必须提供 `credentials.resolve/set/unset`。本插件没有明文凭据文件或存储失败后的备用路径；桌面发行方负责接入操作系统保险库。模型调用使用当前 Access Token，OAuth token 不经 RPC 返回 renderer。`oidcAccounts.authorizedFetch()` 仍是 Host-only 公共授权请求入口。
 
 只有用户点击登录时才监听 `127.0.0.1`。默认随机端口，回调为 `http://127.0.0.1:<port>/oauth/callback`；需在身份提供方注册支持动态 loopback 端口的公共 PKCE 客户端。若身份提供方只接受精确回调端口，可在受信配置固定 `callbackPort`（端口占用时明确失败，不改用未注册端口）。不支持配置其他监听地址。取消、失效、成功、合法回调失败、服务卸载和 Host 退出均清理监听。错误路径、Host、Origin、state 或 HTTP 方法不会消费合法的待登录状态。
 
@@ -38,7 +37,7 @@ RPC 扩展（共用 Host/Client Typert schema）：
 
 | 方法 | 返回 |
 | --- | --- |
-| `begin(profileID)` | 桌面返回 `{mode:'external', loginID, expiresAt}`；Web 仍返回 `redirect`，旧 native 仍可返回 `completed`。 |
+| `begin(profileID)` | 桌面返回 `{mode:'external', loginID, expiresAt}`；Web 仍返回 `redirect`。 |
 | `loginStatus(loginID)` | `{loginID, profileID, state, expiresAt, status?, errorCode?}`。state 为 pending/completed/cancelled/expired/failed。 |
 | `cancelLogin(loginID)` | 同上；等待正在写入的登录撤回，避免取消后重新出现凭据。 |
 | `openConfiguration(target)` | 文件管理模式下返回 `{opened:true}`；目标仅为 `config` / `examples`。系统打开失败时返回简短提示。 |
@@ -46,21 +45,21 @@ RPC 扩展（共用 Host/Client Typert schema）：
 
 客户端账号快照由登录页、侧栏和企业设置共享。宿主凭据 Provider 应在 set/unset 后按官方契约发出 `credentials/reference-updated`；客户端监听该标准 Remote 事件及 `connection/reset`，不依赖不会由官方 Remote 转发的自定义账号事件。
 
-明确登录并连接 Key 或确认创建 Key 后，自动选择企业目录中第一个可解析模型。还没有会话时也会保存未来会话的默认值；存在主会话时通过官方 `modelDirectories.directoryFor(sessionID).select()` 同步当前选择，不改子代理。宿主应加载官方 `agentDefaultModel` 和可写 `settings` 服务。旧宿主缺少此能力时明确提示从模型菜单选择。
+明确登录并连接模型后，自动选择企业目录中第一个可解析模型。还没有会话时也会保存未来会话的默认值；存在主会话时通过官方 `modelDirectories.directoryFor(sessionID).select()` 同步当前选择，不改子代理。宿主应加载官方 `agentDefaultModel` 和可写 `settings` 服务。旧宿主缺少此能力时明确提示从模型菜单选择。
 
 升级后的首次加载使用 `onlyIfMissing:true`：已有有效默认值则保留，缺失或已不能解析才修复；当前会话中可用的个人选择也保留。凭据事件、检查连接和后续状态刷新不会切模型，个人 Key 与其他设置不受影响。
 
-双桌面联调可运行 `node scripts/serve-desktop-oidc-fixture.mjs --config <新的测试配置文件>`。脚本只绑定本机随机端口，生成合成身份、完整 HTTP PKCE/Key/模型/配额服务及公开 JSONC 配置；配置文件必须不存在，不覆盖用户配置。每套外壳使用独立测试数据目录；用 Ctrl+C 关闭服务。服务不接触真实账号，也不消耗模型额度。
+双桌面联调可运行 `node scripts/serve-desktop-oidc-fixture.mjs --config <新的测试配置文件>`。脚本只绑定本机随机端口，生成合成身份、完整 HTTP PKCE/Token/模型/配额服务及公开 JSONC 配置；配置文件必须不存在，不覆盖用户配置。每套外壳使用独立测试数据目录；用 Ctrl+C 关闭服务。服务不接触真实账号，也不消耗模型额度。
 
 `loginID` 是独立随机句柄，不是 OAuth state。响应不包含授权 URL、code、nonce、PKCE verifier 或 token。前端以一秒间隔轮询，显示在浏览器中完成登录与取消按钮；登录最长十分钟，页面卸载取消尚未完成的尝试。关闭外部浏览器无法被跨平台可靠检测，用户可在应用中取消，或等待短时监听过期。
 
-空 Profile 是有效配置，不会监听端口，也不要求机构登录。纯身份 Profile 不要求资源端点；登出仅移除该机构的身份/托管 Key，个人 API Key 保留。身份登录成功后资源接口暂不可用时保留已登录身份，后续可以重试资源连接。
+空 Profile 是有效配置，不会监听端口，也不要求机构登录。纯身份 Profile 不要求资源端点；登出仅移除该机构的身份/Token，个人 API Key 保留。身份登录成功后资源接口暂不可用时保留已登录身份，后续可以重试资源连接。
 
 验证入口：`node --test test/desktop.test.js test/desktop-host.test.js`。后者可通过 `DSH_OIDC_PACKAGE_ROOT` 指向安装的冻结包目录，并设置 `DSH_OIDC_EXPECT_DSH=0.1.5-rc.1`，使用该安装目录的真实 DSH 依赖运行无 WebServer 的 Host、可选浏览器服务和 loopback PKCE 验证。所有凭据与用户均为测试合成值；产品主进程保险库、窗口和操作系统浏览器行为仍由发行方联合验收。
 
-`.20260910.6` 的公共侧栏头像显示账户刷新和注销；配额内容由可选机构扩展提供。菜单通过 portal 支持收窄侧栏；支持方向键、Home/End、Escape、外部点击/失焦关闭。注销清理该机构本地身份、模型 Key、模型元数据缓存，序列化保险库写操作并拒绝旧请求写回；个人 Key 不受影响。
+`.20260910.6` 的公共侧栏头像显示账户刷新和注销；配额内容由可选机构扩展提供。菜单通过 portal 支持收窄侧栏；支持方向键、Home/End、Escape、外部点击/失焦关闭。注销清理该机构本地身份、Token、模型元数据缓存，序列化保险库写操作并拒绝旧请求写回；个人 Key 不受影响。
 
-临时 HTTP 回调页读取本次 Profile 的 `brand.productName/organizationName/logoURL/mark/primaryColor`，按浏览器 Accept-Language 选择中英文。没有外部字体、脚本或原始错误回显，清楚提示返回应用。普通 Web 验证仍跳回本地应用；不会把生产模型 Key 交给浏览器。
+临时 HTTP 回调页读取本次 Profile 的 `brand.productName/organizationName/logoURL/mark/primaryColor`，按浏览器 Accept-Language 选择中英文。没有外部字体、脚本或原始错误回显，清楚提示返回应用。普通 Web 验证仍跳回本地应用；不会把Token 交给浏览器。
 
 在与目标 DSH 完全一致的隔离依赖树运行 `npm run check`，不要从旧版本根依赖构建后标为新基线。可再运行 `npm run check:browser`：使用该 Runtime 的 `playwright-core` 和本机 Edge 无头浏览器（可用 `DSH_OIDC_BROWSER_CHANNEL` 指定 Chrome），直接加载编译客户端，验证菜单/多个组件共享状态/注销，并生成品牌回调截图。本检查不替代主进程保险库与真实操作系统浏览器联验。
 

package/docs/development.en.md

@@ -24,7 +24,7 @@ The complete check covers TypeScript, the dependency lock and official contracts
 | Path | Responsibility |
 | --- | --- |
 | `src/host/profile.js` | Trusted Profile, bounded branding/models and common credential reference |
-| `src/host/oidc.js` | PKCE, Token/UserInfo, Key Binding, sessions and credential ownership |
+| `src/host/oidc.js` | PKCE, Token/UserInfo, identity sessions and credential writes |
 | `src/host/desktop-oidc.js` | Temporary loopback login shared by both desktop shells |
 | `src/host/resources.js` | Conservative model-catalog normalization |
 | `src/host/provider/` | Official PiAi Provider and explicit image-transform boundary |
@@ -37,7 +37,7 @@ The complete check covers TypeScript, the dependency lock and official contracts
 
 ## Extensions and publication
 
-The public package owns identity, managed keys, model discovery/inference and their account UI. Quota, heartbeat, campus search and speech business services belong in institution/product plugins. [Account extensions](account-extensions.en.md) are Host transport and slot contracts, not hidden institution-feature switches. Examples contain placeholder domains, public client IDs and no secrets.
+The public package owns identity, token authorization, model discovery/inference and their account UI. Quota, heartbeat, campus search and speech business services belong in institution/product plugins. [Account extensions](account-extensions.en.md) are Host transport and slot contracts, not hidden institution-feature switches. Examples contain placeholder domains, public client IDs and no secrets.
 
 Module checks and publication use the [shared EduWork workflow](https://github.com/ecnu/EduWork/blob/main/docs/PACKAGES_EN.md). Validate deployment-specific sign-in separately; published npm versions are immutable.
 

package/docs/development.md

@@ -24,7 +24,7 @@ npm run check
 | 路径 | 职责 |
 | --- | --- |
 | `src/host/profile.js` | 可信 Profile、受限品牌/模型配置、统一凭据引用 |
-| `src/host/oidc.js` | PKCE、Token/UserInfo、Key Binding、会话与凭据归属 |
+| `src/host/oidc.js` | PKCE、Token/UserInfo、身份会话与凭据写入 |
 | `src/host/desktop-oidc.js` | 两种桌面外壳共用的临时 loopback 登录 |
 | `src/host/resources.js` | 模型目录的保守归一化 |
 | `src/host/provider/` | 官方 PiAi Provider 和显式图像转换边界 |
@@ -39,6 +39,6 @@ Host ESM 由 `scripts/build-host.mjs` 复制至 `lib`，Client 由 tsdown 打包
 
 ## 扩展与发布
 
-公共包只拥有身份、托管 Key、模型目录/调用及对应账号 UI。配额、心跳、校内检索和语音业务由机构/产品插件负责；[账户扩展](account-extensions.md)是 Host 运输与插槽边界，不是暗中启用机构功能的开关。所有示例均使用占位域名、Public Client ID 与无秘密配置。
+公共包只拥有身份、Token 授权、模型目录/调用及对应账号 UI。配额、心跳、校内检索和语音业务由机构/产品插件负责；[账户扩展](account-extensions.md)是 Host 运输与插槽边界，不是暗中启用机构功能的开关。所有示例均使用占位域名、Public Client ID 与无秘密配置。
 
 模块通过 EduWork 的统一工作流检查和发布，参见[包维护说明](https://github.com/ecnu/EduWork/blob/main/docs/PACKAGES.md)。依赖锁、合成测试与实际部署登录分别验证；发布包使用新版本，不覆盖已有 npm 版本。