@eduwork/dsh-oidc 0.1.0-alpha.11

package/CHANGELOG.en.md

@@ -0,0 +1,120 @@
+# Changelog
+
+[简体中文](CHANGELOG.md) | **English**
+
+All notable changes are documented here. The format follows Keep a Changelog principles and the project uses Semantic Versioning with pre-1.0 qualifications described in `docs/compatibility.en.md`.
+
+## [Unreleased]
+
+## [0.1.0-alpha.11] - 2026-09-05
+
+- Move the npm identity to `@eduwork/dsh-oidc`; update installation/module paths and Client registration together.
+- Keep `dsh-oidc/v1alpha1`, `oidcAccounts`, credential references, Provider identities and plugin row ids. Host and Client TYPERT package identities change together.
+- Keep the previous unscoped version installable and document Profile migration.
+
+
+## [0.1.0-alpha.10] - 2026-08-31
+
+### Changed
+
+- Updated the compatibility baseline to DeepSeek Harness `0.1.2-alpha.2` (`0a53fb55…`) and `@deepseek-ai/cordis` `4.0.2`.
+- Migrated Provider settings integration to alpha.2's official `SettingsProvider.installSection()` API and removed reliance on the retired top-level `installSettingsSection` and `settingsNamespace` exports.
+- Completed build, unit, protocol, documentation, secret, and publish-content checks against both the npm and locked source release-pack DSH Runtimes.
+
+## [0.1.0-alpha.9] - 2026-08-31
+
+### Changed
+
+- Removed `catalogPathEnv`, `activeInstitutionEnv`, and all product institution-catalog conversion code. Both Web and native backends now accept only standard Enterprise Profiles; product-owned catalogs must be converted by the product assembly layer first.
+- Native `enterpriseAccounts` remains an optional generic host capability interface with no Wails, Electron, or product-data-format dependency.
+
+## [0.1.0-alpha.8] - 2026-08-31
+
+### Added
+
+- Added a bilingual [server API specification](docs/server-integration-contract.en.md) that documents OIDC + PKCE, Key Binding, and the model gateway as one jointly required institutional delivery in API-reference form.
+- Completed open-source cleanup of Chinese-default/English documentation, public repository links, maintainers, and the private security-reporting entry point.
+
+### Changed
+
+- Fixed the Web callback to `http://127.0.0.1:<DSH-port>/oauth/callback`; public `publicBaseURL` and DSH WebServer hosts other than `127.0.0.1` are rejected.
+- Added optional Enterprise Profile `keyBinding.credentialRef`, allowing production and test to isolate local DSH credentials while retaining one Provider ID and server protocol. Omission preserves Provider-ID derivation, so existing profiles require no migration.
+- Host-provided credential references must now enter the same generic Profile field instead of letting a host and Provider independently determine lookup locations.
+- Examples and tests now use reserved documentation addresses, and the public main branch does not inherit internal development history.
+
+### Security
+
+- Native hosts now fail closed when their reported credential reference conflicts with the Enterprise Profile, preventing production/test API-key cross-resolution.
+
+## [0.1.0-alpha.7] - 2026-08-30
+
+### Added
+
+- Development-only network HTTP deployments may explicitly allowlist one exact `insecureDevelopmentOrigin`; HTTPS remains mandatory by default and loopback development behavior is unchanged.
+
+## [0.1.0-alpha.6] - 2026-08-29
+
+### Changed
+
+- Updated the compatibility baseline to DeepSeek Harness `0.1.2-alpha.1` and replaced the removed client runtime peer with the public renderer/session-era packages.
+- Enterprise model management now extends the upstream Models page through the official `settings.models.footer` slot; the product no longer needs a fork of the complete model settings page.
+- Reviewed pi-ai `0.84.4` through the source release-pack Runtime while retaining a compatible `^0.84.2` peer range.
+
+## [0.1.0-alpha.5] - 2026-08-26
+
+### Changed
+
+- Installation documentation now starts from a reviewed local Git checkout and uses a placeholder GitHub organization until repository ownership is decided.
+- Clarified that local-path installation links the checkout into the DSH Profile, does not scan the current workspace, and requires the checkout to remain available.
+- Registry installation is documented only as a future path after a reviewed npm publication.
+
+## [0.1.0-alpha.4] - 2026-08-26
+
+### Added
+
+- Direct DSH Bundle installation through `dsh plugin --profile web add dsh-oidc`, backed by a package-owned Web-first `cordis.patch.yml`.
+- Complete English and Chinese third-party integration guides covering OIDC registration, Key Binding implementation, Enterprise Profile authoring, Web/native composition, production acceptance, and troubleshooting.
+
+### Changed
+
+- Publishable npm tarballs now include the protocol and deployment documentation needed to operate the plugin without a repository checkout.
+
+## [0.1.0-alpha.3] - 2026-08-25
+
+### Added
+
+- A single capability-aware enterprise provider/model settings component for Web and native DSH compositions, registered through DSH's official `settings.section` extension point.
+- Versioned `dsh-oidc/management/v1alpha1` browser projection and optional native add/switch/model-edit/restart operations.
+- `models-only` UI mode so desktop products can inherit the shared model settings while retaining separate account, quota, update, and diagnostic surfaces.
+
+### Changed
+
+- Plain Web now presents its trusted Enterprise Profile through the same provider/model UI as Desktop, with mutation actions hidden.
+- Authenticated accounts that still need a runtime credential receive an explicit confirm-and-connect action instead of repeating OIDC login.
+
+## [0.1.0-alpha.2] - 2026-08-25
+
+### Changed
+
+- Account surfaces now display the standard OIDC UserInfo `name`, falling back to `sub`, while retaining organization branding as secondary context.
+- Native desktop adapters are expected to project the same `userName` identity contract as the Web backend; private management-plane bootstrap data must not replace OIDC identity.
+
+## [0.1.0-alpha.1] - 2026-08-25
+
+### Added
+
+- Standalone `dsh-oidc` package with no ChatECNU private-package dependency.
+- OIDC Authorization Code + PKCE Web backend and native account adapter.
+- Standard UserInfo identity (`name`, fallback `sub`) with subject binding.
+- Fixed `worker-user-center-v1` Key Binding client and OpenAPI contract.
+- Declarative Enterprise Profile JSON Schema, branding, Provider/model catalog, and ECNU placeholder example.
+- Local DSH/PiAi OpenAI-compatible Provider adapter and `enterpriseTransforms` extension seam.
+- Chinese/English account UI fallbacks.
+- Security, governance, contribution, compatibility, release, and third-party documentation.
+
+### Security
+
+- Exact callback/public-origin handling, same-origin return path, duplicate callback-parameter rejection.
+- Multi-audience `azp`, JWK metadata/uniqueness, required time claims, optional `at_hash`, and UserInfo subject validation.
+- HTTPS cross-origin Discovery endpoint support with loopback-only HTTP development exception.
+- Bounded profile and network response sizes, strict unknown-key rejection, and SVG data-logo rejection.

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# 变更日志
+
+**简体中文** | [English](CHANGELOG.en.md)
+
+所有重要变更均记录于此。格式遵循 Keep a Changelog 原则；项目使用语义化版本，并遵循[兼容性与发布策略](docs/compatibility.md)中对 1.0 之前版本的说明。
+
+## [未发布]
+
+## [0.1.0-alpha.11] - 2026-09-05
+
+- npm 包身份改为 `@eduwork/dsh-oidc`，同步安装路径、组合模块路径与客户端注册。
+- 保留 `dsh-oidc/v1alpha1`、`oidcAccounts`、凭据引用、Provider 标识和插件行 id；Host 与 Client 的 TYPERT 包归属一起更新。
+- 旧无作用域版本保留可安装，并提供 Profile 迁移说明。
+
+
+## [0.1.0-alpha.10] - 2026-08-31
+
+### 变更
+
+- 兼容基线更新至 DeepSeek Harness `0.1.2-alpha.2`（`0a53fb55…`）与 `@deepseek-ai/cordis` `4.0.2`。
+- Provider 设置接入迁移到 alpha.2 官方 `SettingsProvider.installSection()`；不再依赖已删除的 `installSettingsSection` 与 `settingsNamespace` 顶层导出。
+- npm 与锁定源码 release-pack 两种 DSH Runtime 均完成构建、单元测试、协议/文档/敏感信息和发布内容检查。
+
+## [0.1.0-alpha.9] - 2026-08-31
+
+### 变更
+
+- 删除 `catalogPathEnv`、`activeInstitutionEnv` 和产品机构目录转换代码。Web 与 native 后端现在都只接受标准 Enterprise Profile；任何产品自有目录必须由产品装配层先转换。
+- Native `enterpriseAccounts` 继续作为可选的通用宿主能力接口，不依赖 Wails、Electron 或任何产品数据格式。
+
+## [0.1.0-alpha.8] - 2026-08-31
+
+### 新增
+
+- 增加中英文[服务端接口规范](docs/server-integration-contract.md)，按接口说明形式定义 OIDC + PKCE、Key Binding 和模型网关这一完整机构服务必须共同交付的能力。
+- 中英文文档默认入口、公开仓库地址、维护者和私密安全报告入口完成开源化整理。
+
+### 变更
+
+- Web 回调固定为 `http://127.0.0.1:<DSH端口>/oauth/callback`，不再接受公网 `publicBaseURL` 或非 `127.0.0.1` 的 DSH WebServer。
+- Enterprise Profile 新增可选 `keyBinding.credentialRef`，让生产与测试在保持同一 Provider ID/服务端协议的同时隔离本地 DSH 凭据；省略时继续按 Provider ID 派生，旧配置无需迁移。
+- 宿主提供的凭据引用现在必须进入同一通用 Profile 字段，不再允许宿主与 Provider 分别决定读取位置。
+- 示例与测试只使用保留文档地址，公开主分支不继承内部开发提交历史。
+
+### 安全
+
+- Native 宿主若报告与 Enterprise Profile 不一致的凭据引用，插件会失败关闭，避免生产/测试环境交叉读取 API Key。
+
+## [0.1.0-alpha.7] - 2026-08-30
+
+### 新增
+
+- 仅限开发环境的网络 HTTP 部署可以显式允许一个精确 `insecureDevelopmentOrigin`；默认仍强制 HTTPS，loopback 开发行为不变。
+
+## [0.1.0-alpha.6] - 2026-08-29
+
+### 变更
+
+- 兼容基线更新至 DeepSeek Harness `0.1.2-alpha.1`，并用公开 renderer/session 时代软件包替换已移除的 Client runtime peer。
+- 企业模型管理现在通过官方 `settings.models.footer` 扩展上游“模型”页面；产品不再需要 fork 完整模型设置页。
+- 通过源码 release-pack Runtime 审查 pi-ai `0.84.4`，同时保留兼容的 `^0.84.2` peer 范围。
+
+## [0.1.0-alpha.5] - 2026-08-26
+
+### 变更
+
+- 在仓库所有权确定前，安装文档改为从经过审查的本地 Git checkout 开始，并使用 GitHub 组织占位符。
+- 明确本地路径安装会把 checkout 链接进 DSH Profile，不会扫描当前工作区，并要求 checkout 持续存在。
+- Registry 安装只作为 npm 版本经过审查并发布后的未来路径。
+
+## [0.1.0-alpha.4] - 2026-08-26
+
+### 新增
+
+- 通过包自带的 Web-first `cordis.patch.yml`，支持 `dsh plugin --profile web add dsh-oidc` 直接安装 DSH Bundle。
+- 完整中英文第三方接入指南，覆盖 OIDC 注册、Key Binding 实现、Enterprise Profile、Web/native 组合、生产验收和排障。
+
+### 变更
+
+- 可发布 npm tarball 现在包含无需仓库 checkout 即可部署插件所需的协议和部署文档。
+
+## [0.1.0-alpha.3] - 2026-08-25
+
+### 新增
+
+- Web 与 native DSH 组合共用、可感知能力的企业 Provider/模型设置组件，通过 DSH 官方 `settings.section` 扩展点注册。
+- 版本化 `dsh-oidc/management/v1alpha1` 浏览器投影，以及可选 native 新增、切换、模型编辑和重启操作。
+- `models-only` UI 模式，使桌面产品在保留独立账号、配额、更新和诊断界面的同时继承共用模型设置。
+
+### 变更
+
+- 纯 Web 现在通过与 Desktop 相同的 Provider/模型 UI 展示受信任 Enterprise Profile，并隐藏修改操作。
+- 已认证但仍缺少运行凭据的账号会显示明确“确认并连接”操作，而不是重复 OIDC 登录。
+
+## [0.1.0-alpha.2] - 2026-08-25
+
+### 变更
+
+- 账号界面显示标准 OIDC UserInfo `name`，缺失时降级到 `sub`；机构品牌仍作为次要上下文。
+- Native desktop adapter 应提供与 Web 后端相同的 `userName` 身份契约；私有管理面 bootstrap 数据不得替换 OIDC 身份。
+
+## [0.1.0-alpha.1] - 2026-08-25
+
+### 新增
+
+- 独立 `dsh-oidc` 软件包，不依赖 ChatECNU 私有包。
+- OIDC Authorization Code + PKCE Web 后端和 native 账号 adapter。
+- 标准 UserInfo 身份（`name`，降级 `sub`）和 subject 绑定。
+- 固定 `worker-user-center-v1` Key Binding 客户端和 OpenAPI 契约。
+- 声明式 Enterprise Profile JSON Schema、品牌替换、Provider/模型目录和 ECNU 占位示例。
+- 本地 DSH/PiAi OpenAI-compatible Provider adapter 和 `enterpriseTransforms` 扩展点。
+- 中英文账号 UI 降级文案。
+- 安全、治理、贡献、兼容、发布和第三方文档。
+
+### 安全
+
+- 精确 callback/public-origin 处理、同源 return path 和重复 callback 参数拒绝。
+- 多 audience `azp`、JWK 元数据/唯一性、必需时间 claim、可选 `at_hash` 和 UserInfo subject 校验。
+- 支持跨 origin HTTPS Discovery endpoint；HTTP 仅限 loopback 开发环境。
+- 限制 Profile 和网络响应大小，严格拒绝未知字段和 SVG data logo。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-oidc contributors
+
+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.

package/README.en.md

@@ -0,0 +1,184 @@
+# dsh-oidc
+
+> npm package: `@eduwork/dsh-oidc@0.1.0-alpha.11`. The previous unscoped package remains available during migration. See [migration and data compatibility](docs/EDUWORK-MIGRATION.en.md).
+
+[简体中文](README.md) | **English**
+
+Standards-based enterprise identity and model integration for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+`dsh-oidc` composes four concerns behind one reviewed, declarative Enterprise Profile:
+
+1. OpenID Connect Authorization Code flow with PKCE for a public client;
+2. a fixed enterprise **Key Binding** protocol that exchanges the authenticated OIDC access token for a revocable model runtime credential;
+3. an audited local OpenAI-compatible DSH Provider adapter; and
+4. bounded product branding plus a shared account and enterprise-model settings UI.
+
+The plugin is Web-first and has no Wails dependency. A desktop product can select the native account backend without changing the profile, Provider routes, UI contract, or Key Binding semantics.
+
+> **Status: alpha.** The code is usable for integration testing against DSH `0.1.2-alpha.2` through both the official npm Runtime and the locked source release-pack Runtime. The Enterprise Profile and Key Binding contracts are `v1alpha1`/`v1`. The Web backend is local single-user only; security review and compatibility tests remain required before production use.
+
+Integrating your own organization? Read the **[server API specification](docs/server-integration-contract.en.md)** first, then follow the **[getting-started guide](docs/getting-started.en.md)**. The first defines, with requests, responses, fields, and errors, the OIDC + PKCE, Key Binding, and model-gateway capabilities one institutional service must jointly deliver; the second covers configuration, installation, acceptance, and troubleshooting.
+
+## Why this boundary
+
+An organization should be able to integrate DSH without forking DSH, shipping executable configuration, or binding its identity layer to one desktop shell. The organization supplies data and standards-compliant endpoints; the plugin owns the executable adapter and validates that data before use.
+
+```mermaid
+flowchart LR
+  subgraph Local[Trusted local machine]
+    U[Browser] <-->|127.0.0.1 callback| D[DSH + dsh-oidc]
+    C[DSH Credential Provider]
+    P[Local OpenAI-compatible adapter]
+    D --> C --> P
+  end
+  subgraph Service[One institutional integration service]
+    O[OIDC Provider]
+    K[Key Binding]
+    M[Model gateway]
+  end
+  D <--> O
+  D --> K
+  K -->|runtime API key| C
+  P --> M
+  E[Enterprise Profile JSON] --> D
+  X[Optional capability plugin] -->|enterpriseTransforms| P
+```
+
+The Enterprise Profile is data only. It cannot name JavaScript modules, inject CSS, install tools or skills, or redefine Key Binding paths and wire fields.
+
+## What is included
+
+- fixed loopback callback `http://127.0.0.1:<DSH-port>/oauth/callback`;
+- OIDC Discovery, PKCE S256, state, nonce, RS256 ID Token validation, UserInfo subject binding, refresh, and optional revocation;
+- `userinfo.name` for display, falling back only to the required `userinfo.sub`;
+- fixed `worker-user-center-v1` endpoints for bootstrap, provision, resolve, and renew;
+- DSH Credential Provider storage for OIDC session material and the runtime API key;
+- declarative provider/model catalog and bounded brand tokens;
+- one capability-aware enterprise-service settings section shared by Web and native hosts through DSH's official `settings.section` extension point;
+- a native backend adapter boundary for desktop products;
+- a stable `enterpriseTransforms` service for capabilities such as a text-model image fallback without forking the Provider route.
+
+Not included: an OIDC Provider, a Key Binding server, multi-user session storage, an organization directory, quota UI, a desktop shell, or remote executable plugins.
+
+## Branding scope
+
+`dsh-oidc` already includes bounded product branding. An Enterprise Profile may declare:
+
+- `productName`, `organizationName`, and a one-to-four-character `mark`;
+- an HTTPS or base64 PNG/WebP `logoURL`;
+- a six-digit hexadecimal `primaryColor`;
+- `loginTitle`, `loginDescription`, and an HTTPS `supportURL`.
+
+These values affect the document title, sidebar brand, conversation hero mark, login/confirmation surfaces, and a bounded set of DSH theme tokens. They cannot inject arbitrary CSS, SVG, scripts, or components, and they do not replace a desktop shell, updater, quota UI, or institution-specific business pages. See the [Enterprise Profile specification](docs/enterprise-profile.en.md#branding) for limits and security rules.
+
+## Requirements
+
+- Node.js 22 or newer;
+- DeepSeek Harness `0.1.2-alpha.2` packages listed as peers;
+- an OIDC Public Client without a Client Secret that registers `http://127.0.0.1:3080/oauth/callback` exactly;
+- Discovery metadata with PKCE S256, RS256 ID Tokens, and `userinfo_endpoint`;
+- one institutional integration service implementing the complete [server contract](docs/server-integration-contract.en.md), including Key Binding and the model gateway;
+- a DSH Credential Provider appropriate for the deployment.
+
+The current Web backend is intentionally limited to a trusted, single-user DSH process bound to `127.0.0.1`. It is not a shared public-Web session solution. See [Security model](docs/security-model.en.md).
+
+## Install
+
+Install the reviewed, exact version from npm:
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0-alpha.11
+```
+
+For auditing, development, or testing unpublished changes, install from a local checkout instead:
+
+```bash
+git clone https://github.com/freedomkk-qfeng/dsh-oidc.git
+cd dsh-oidc
+npm ci
+npm run check
+dsh plugin --profile web add .
+```
+
+The local-path form links the checkout into the DSH `web` Profile, so keep the source directory in place. Team deployments should prefer a reviewed, exact npm version; use `@eduwork/dsh-oidc@alpha` only when intentionally following alpha updates.
+
+Advanced products may instead add it explicitly to their own DSH bundle patch:
+
+```yaml
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+```
+
+Set `DSH_OIDC_ENTERPRISE_PROFILE` to a trusted local JSON file. Start from [`examples/enterprise-profile.example.json`](examples/enterprise-profile.example.json) and validate it with [`schema/enterprise-profile.v1alpha1.schema.json`](schema/enterprise-profile.v1alpha1.schema.json).
+
+Start DSH on the fixed IPv4 loopback host. The public OIDC client must register exactly:
+
+```text
+http://127.0.0.1:3080/oauth/callback
+```
+
+The callback host and path are not configurable. The port follows the actual DSH WebServer port; if the operator changes `3080`, the OIDC registration must use the same port.
+
+## Configuration surfaces
+
+| Plugin config | Purpose |
+| --- | --- |
+| `profile` | One inline Enterprise Profile object. |
+| `profiles` | An array of inline Enterprise Profiles. Provider IDs must also be unique. |
+| `profilePathEnv` | Name of an environment variable containing the trusted JSON profile path. |
+| `backend` | `web` (default) or `native`. Native delegates account lifecycle to the host's `enterpriseAccounts` service. |
+| `uiMode` | `standard` (shared model settings plus account/onboarding/branding), `models-only` (shared model settings only), or `external` (no plugin UI). |
+| `web.returnPath` | Same-origin absolute path after callback; defaults to `/`. |
+| `allowEmptyProfiles` | Allows the plugin service to start with no profile, mainly for composition tests. |
+
+See [Enterprise Profile](docs/enterprise-profile.en.md) for every data field and trust rule.
+
+## Protocol summary
+
+OIDC remains standard OIDC. The plugin does not support custom “userinfo field mapping”: `name` is the standard display claim and `sub` is the guaranteed stable fallback. OIDC, Key Binding, and the model gateway form one required institutional server contract; they are not optional alternatives. See the [complete server integration contract](docs/server-integration-contract.en.md).
+
+Given `keyBinding.baseURL = https://ai.example.edu/api/worker/v1`, the only valid operations are:
+
+- `GET /bootstrap`
+- `POST /runtime-credential/provision`
+- `POST /runtime-credential/resolve`
+- `POST /runtime-credential/renew`
+
+The profile cannot change these paths or their fields. [`protocol/openapi.yaml`](protocol/openapi.yaml) is the machine-readable contract; [Key Binding protocol](docs/key-binding-protocol.en.md) defines normative behavior, authorization, idempotency, logging, and lifecycle semantics.
+
+Provider ID determines the runtime route and, by default, derives the local credential reference (for example, `example-ai` becomes `EXAMPLE_AI_API_KEY`). Production and test deployments that reuse one Provider ID may explicitly isolate their local secret entries with `keyBinding.credentialRef`; this does not change the server API.
+
+## Development
+
+```bash
+npm ci
+npm run check
+```
+
+`npm run check` rebuilds both plugin faces, runs unit/security-contract tests, validates examples and OpenAPI structure, scans publishable sources for common secrets, personal paths, non-example addresses, and ECNU service endpoints, and inspects the npm tarball.
+
+The repository intentionally keeps Host code as native ESM under `src/host`; `scripts/build-host.mjs` copies it to `lib`. The DSH browser client is bundled as the loader-compatible `lib/client.js`.
+
+## Documentation
+
+- [Architecture and boundaries](docs/architecture.en.md)
+- [Complete institutional server integration contract](docs/server-integration-contract.en.md)
+- [Third-party getting-started guide](docs/getting-started.en.md)
+- [Enterprise Profile specification](docs/enterprise-profile.en.md)
+- [OIDC interoperability profile](docs/oidc-interoperability.en.md)
+- [Key Binding protocol](docs/key-binding-protocol.en.md)
+- [Security model and deployment requirements](docs/security-model.en.md)
+- [DSH integration and extension seams](docs/dsh-integration.en.md)
+- [ECNU reference composition](docs/ecnu-reference.en.md)
+- [Compatibility and release policy](docs/compatibility.en.md)
+- [Public release checklist](docs/release-checklist.en.md)
+- [Contribution guide](CONTRIBUTING.en.md), [security policy](SECURITY.en.md), and [governance](GOVERNANCE.en.md)
+
+## License and trademarks
+
+Code and original documentation are licensed under MIT. Dependency notices are in [THIRD_PARTY_NOTICES.en.md](THIRD_PARTY_NOTICES.en.md).
+
+DeepSeek Harness and DeepSeek are names of their respective owners. “华东师范大学”, “ECNU”, “ChatECNU”, and associated marks remain the property of their respective rights holders. The ECNU file in `examples/` is a placeholder reference configuration, contains no production endpoint or client identifier, and does not grant trademark rights.

package/README.md

@@ -0,0 +1,143 @@
+# dsh-oidc
+
+> npm 包：`@eduwork/dsh-oidc@0.1.0-alpha.11`。旧无作用域包保留供迁移；安装切换与数据兼容见 [迁移说明](docs/EDUWORK-MIGRATION.md)。
+
+**简体中文** | [English](README.en.md)
+
+`dsh-oidc` 是面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的企业身份与模型闭环集成插件。
+
+它不是“只做登录”的 OIDC 按钮，而是把四项能力按清晰边界组合起来：
+
+1. 标准 OIDC Authorization Code + PKCE 公共客户端登录；
+2. 固定的企业 **Key Binding** 协议，用 OIDC Access Token 申请、解析或轮换可撤销的模型运行凭据；
+3. 本地、经过审计的 OpenAI-compatible DSH Provider 适配器；
+4. 有边界的品牌替换，以及 Web / Desktop 共用的账号与企业模型设置 UI。
+
+插件 Web 优先，不依赖 Wails。桌面产品可以切换到 native account backend，但 Enterprise Profile、Provider 路由、前端账号契约和 Key Binding 语义不变。
+
+> **当前状态：alpha。** 当前源码已适配 DSH `0.1.2-alpha.2`（提交 `0a53fb55…`），并在官方 npm Runtime 与锁定源码 release-pack Runtime 中完成构建和集成检查；Enterprise Profile 仍为 `v1alpha1`。正式生产前仍必须完成真实 OIDC/Key Binding 联调、宿主凭据隔离审计和 DSH 升级兼容性测试。
+
+准备接入自己的机构？先读 **[服务端接口规范](docs/server-integration-contract.md)**，再按 **[完整中文接入指南](docs/getting-started.md)** 部署。前者以请求、响应、字段和错误码形式定义一个机构服务必须共同实现的 OIDC + PKCE、Key Binding 和模型网关能力；后者覆盖配置、安装、验收和排障。
+
+## 为什么叫 `dsh-oidc`
+
+这个名字足够准确，也没有把 ECNU、Wails、某个模型网关或某种客户端形态绑进公共能力。仓库名仍为 `dsh-oidc`，npm 包使用 `@eduwork/dsh-oidc`；[旧 npm 包](https://www.npmjs.com/package/dsh-oidc)保留供迁移。
+
+它的边界不是“登录结束”，而是“一套能闭环的企业模型接入标准”：
+
+- OIDC 负责确认用户是谁；
+- Key Binding 负责确认该用户能否获得哪个 Provider 的运行凭据；
+- Enterprise Profile 负责声明品牌、OIDC 公共客户端、Key Binding 基址和模型事实；
+- 本地 Provider 适配器把凭据和模型事实接入 DSH；
+- 具体桌面外壳、配额展示、学校业务页、更新器等仍由产品实现方扩展。
+
+远程配置只能是数据，不能指定 JS 模块、脚本、CSS、工具、Skill 或自定义 Provider adapter，也不能修改 Key Binding 的路径和字段。这是开源后的核心安全边界。
+
+## 能力与非目标
+
+已包含：
+
+- 固定 loopback 回调 `http://127.0.0.1:<DSH端口>/oauth/callback`；
+- OIDC Discovery、PKCE S256、state、nonce、RS256 ID Token 校验、UserInfo subject 绑定、刷新和可选撤销；
+- 只读取标准 `userinfo.name`，缺失时降级到必需字段 `userinfo.sub`；
+- 固定 `worker-user-center-v1` 的 bootstrap / provision / resolve / renew；
+- 使用 DSH Credential Provider 保存 OIDC 会话和模型 API Key；
+- 声明式 Provider/模型目录和有边界的品牌 token；
+- Web 与 native 宿主共用、按宿主能力自动显隐操作的企业服务设置页；该页面通过 DSH 官方 `settings.section` 扩展点注册；
+- 桌面原生账号后端适配边界；
+- 稳定的 `enterpriseTransforms` 扩展服务，图像理解等插件可以增强某条模型路由，但不会再注册一套重复 Provider。
+
+明确不包含：OIDC 服务端、Key Binding 服务端、多用户会话数据库、学校人员目录、配额 UI、Wails 外壳、客户端更新器和远程可执行插件。
+
+## 品牌替换范围
+
+`dsh-oidc` 当前已经包含品牌替换。部署方可以在 Enterprise Profile 的 `brand` 中声明：
+
+- `productName`、`organizationName` 和 1–4 字符的 `mark`；
+- HTTPS 或 base64 PNG/WebP `logoURL`；
+- 六位十六进制 `primaryColor`；
+- `loginTitle`、`loginDescription` 和 HTTPS `supportURL`。
+
+这些字段会作用于页面标题、侧栏品牌、对话开场标记、登录/确认界面和一组受限 DSH 主题 token。它们不能注入任意 CSS、SVG、脚本或组件，也不会替换桌面外壳、更新器、配额界面和机构业务页面。完整字段、大小限制与安全规则见 [Enterprise Profile 规范](docs/enterprise-profile.md#品牌替换)。
+
+## 最小接入步骤
+
+1. 按[服务端接口规范](docs/server-integration-contract.md)联合提供 OIDC、Key Binding 和模型网关。
+2. 为无 Client Secret 的 Public Client 精确登记 `http://127.0.0.1:3080/oauth/callback`。
+3. 从 [`examples/enterprise-profile.example.json`](examples/enterprise-profile.example.json) 复制一份可信本地配置。
+4. 从 npm 安装经过复核的精确版本：
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0-alpha.11
+```
+
+需要审计、开发或测试尚未发布的改动时，也可以从本地 checkout 安装：
+
+```bash
+git clone https://github.com/freedomkk-qfeng/dsh-oidc.git
+cd dsh-oidc
+npm ci
+npm run check
+dsh plugin --profile web add .
+```
+
+本地路径安装会把当前 checkout 以依赖链接到 DSH `web` Profile；安装后不要移动或删除源码目录。团队部署应优先固定经过复核的 npm 精确版本；需要主动跟随 alpha 更新时可以使用 `@eduwork/dsh-oidc@alpha`。
+
+高级产品也可以在自己的 DSH bundle 中显式引入 `dsh-oidc`：
+
+```yaml
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+```
+
+5. 用环境变量传入配置文件路径，并让 DSH WebServer 监听 `127.0.0.1`：
+
+```text
+DSH_OIDC_ENTERPRISE_PROFILE=/etc/dsh/enterprise-profile.json
+dsh --profile web --host 127.0.0.1 --port 3080
+```
+
+回调 host 与 path 不可配置。端口取 DSH WebServer 实际端口；如修改 `3080`，OIDC 注册值也必须同步修改。
+
+## 最重要的部署约束
+
+当前 Web backend 只支持“可信单用户机器上的一个本地 DSH 进程”，并强制 DSH WebServer 绑定 `127.0.0.1`。它不支持共享公网 Web，也不应通过反向代理暴露为多人站点。需要共享部署时，应由另一个具备每用户会话、凭据隔离、Cookie/CSRF 和存储安全的宿主实现新的 backend，而不是放宽本插件的 loopback 限制。详见 [`docs/security-model.md`](docs/security-model.md)。
+
+## 协议原则
+
+OIDC 部分坚持标准化，不增加机构私有的 UserInfo 映射语法：
+
+- Discovery 的 `issuer` 必须与配置完全一致；
+- OIDC endpoint 可以按标准位于不同 HTTPS origin；
+- UserInfo 的 `sub` 必须等于 ID Token 的 `sub`；
+- 展示名取 `name`，缺失时才取 `sub`；
+- bootstrap 中即使返回姓名，也不得覆盖 OIDC 身份。
+
+OIDC、Key Binding 和模型网关共同构成一个完整的机构服务端交付，不能任选。Key Binding 是本项目定义的企业协议：Profile 通过 `baseURL` 指定接口组，其余路径、请求字段和响应字段全部固定。Provider ID 决定运行路由，并默认派生凭据引用（例如 `example-ai` 对应 `EXAMPLE_AI_API_KEY`）；生产/测试复用同一 Provider ID 时，可以用本地 `keyBinding.credentialRef` 明确隔离，且不会改变服务端接口。完整接口见[服务端接口规范](docs/server-integration-contract.md)。
+
+## 开发与复核
+
+```bash
+npm ci
+npm run check
+```
+
+完整检查包括 Host/Client 构建、单元测试、OIDC 安全边界测试、JSON Schema 示例校验、OpenAPI 结构检查、敏感信息扫描和 npm tarball 预检。
+
+详细材料：
+
+- [`docs/architecture.md`](docs/architecture.md)：组合架构与代码边界
+- [`docs/server-integration-contract.md`](docs/server-integration-contract.md)：机构服务端必须共同实现的完整接口规范
+- [`docs/getting-started.md`](docs/getting-started.md)：第三方从零接入、部署、验收与排障
+- [`docs/enterprise-profile.md`](docs/enterprise-profile.md)：Enterprise Profile 字段和信任规则
+- [`docs/oidc-interoperability.md`](docs/oidc-interoperability.md)：OIDC 兼容性要求
+- [`docs/key-binding-protocol.md`](docs/key-binding-protocol.md)：Key Binding 规范
+- [`docs/security-model.md`](docs/security-model.md)：威胁模型和部署要求
+- [`docs/dsh-integration.md`](docs/dsh-integration.md)：DSH 服务依赖和扩展点
+- [`docs/ecnu-reference.md`](docs/ecnu-reference.md)：华东师范大学参考组合（仅占位配置）
+- [`docs/compatibility.md`](docs/compatibility.md)：版本与发布策略
+
+代码和原创文档使用 MIT 许可证。ECNU/ChatECNU 示例不包含真实地址、Client ID 或密钥，也不授予任何校名、商标和品牌资产使用权。

package/THIRD_PARTY_NOTICES.en.md

@@ -0,0 +1,51 @@
+# Third-party notices
+
+[简体中文](THIRD_PARTY_NOTICES.md) | **English**
+
+`dsh-oidc` is MIT-licensed and interoperates with the following directly declared packages. Exact versions are recorded in `package-lock.json`; transitive dependency license files remain in their distributed packages.
+
+## Runtime peers (not copied into this repository)
+
+- DeepSeek Harness packages `0.1.2-alpha.2` and `@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` (`0.84.4` in the reviewed source Runtime) — MIT, <https://github.com/earendil-works/pi>
+- React `18.x` — MIT, Copyright (c) Facebook, Inc. and its affiliates, <https://github.com/facebook/react>
+
+This repository uses public package APIs and does not vendor their source. Their presence as peer dependencies does not imply endorsement of this project.
+
+## Code embedded in the browser artifact
+
+The generated `lib/client.js` bundles 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.
+
+Source: <https://github.com/colinhacks/zod>
+
+## Development-only tools
+
+The repository also declares tsdown (MIT), TypeScript (Apache-2.0), Ajv (MIT), YAML (ISC), and `@types/react` (MIT) for build and validation. They are not included in the npm package's runtime files. Review their transitive licenses and install scripts from the lockfile before release.
+
+At the alpha.1 lockfile, npm reports install scripts on `@google/genai` (a no-op preinstall) and `protobufjs` (postinstall), both reached through the `@earendil-works/pi-ai` peer tree. npm's allow-scripts policy left them unapproved during the preparation install. Release managers must re-review this fact whenever the lockfile changes; `npm audit` reporting zero known vulnerabilities does not replace that review.
+
+The prepared lockfile contains 255 package entries with declared license metadata: MIT (190), Apache-2.0 (48), BSD-3-Clause (12), ISC (3), Python-2.0 (1, `argparse`), and 0BSD (1). This is an inventory result, not legal advice; the release manager must regenerate and review it from the final lockfile.