@eduwork/dsh-oidc 0.1.0-alpha.11

package/docs/dsh-integration.en.md

@@ -0,0 +1,171 @@
+# DSH integration and extension seams
+
+[简体中文](dsh-integration.md) | **English**
+
+## Supported host baseline
+
+The current compatibility baseline is DeepSeek Harness `0.1.2-alpha.2`, upstream commit `0a53fb55bea101816fa226bb964ae2bed71c343b`. Peer versions are exact while DSH remains prerelease software.
+
+The plugin uses public package exports rather than copied DSH source:
+
+| DSH service/package | Use |
+| --- | --- |
+| `dsh-typert-protocol` | Host/client RPC descriptors. |
+| `dsh-host-webserver` | Exact `/oauth/callback` route. |
+| `dsh-credentials` | Session and runtime API-key storage. |
+| `dsh-llm` | Adapter registry, credentials, retry policy, stable errors. |
+| `dsh-llm-pi-ai` | Official `PiAiAdapter`. |
+| `dsh-settings` | Provider directory/readiness facts. |
+| `dsh-launch-environment` | Credential fallback when no Credential Provider service is present. |
+| client runtime/remotes/slots/theme | Browser bundle and bounded UI/brand surfaces. |
+
+The OpenAI-compatible wire implementation comes from `@earendil-works/pi-ai`, which is already the basis of DSH's official Pi adapter.
+
+## Why the Provider adapter is inside this package
+
+OIDC authentication alone does not yield a callable enterprise model. A closed-loop integration also needs a stable Provider route whose credential reference matches Key Binding output. Publishing a second organization-specific Provider package would recreate the coupling this repository is meant to remove.
+
+The adapter is therefore an internal module of `dsh-oidc`, but its behavior is constrained:
+
+- one audited `openai-compatible` implementation;
+- declarative Provider/model facts only;
+- official DSH LLM registry and Pi adapter;
+- no second HTTP stack;
+- no ambient pi-ai credential discovery;
+- DSH-owned retry policy and attachment resolution.
+
+It remains exported as `@eduwork/dsh-oidc/provider` for tests and advanced local composition, but Enterprise Profiles cannot replace it.
+
+## Cordis service entry
+
+The default export is `OidcAccountService`, a `TypertRemoteService` named `oidcAccounts`. Remote methods are:
+
+| Method | Result |
+| --- | --- |
+| `configuration()` | Public profiles with secrets and endpoint bases removed. |
+| `status(profileID)` | Local session/credential state. |
+| `begin(profileID)` | Redirect URL for Web, completed status for native. |
+| `reconcile(profileID, {allowProvision})` | Bootstrap and resolve/provision/renew. |
+| `logout(profileID)` | Local cleanup and best-effort OIDC revocation. |
+| `management()` | Capability-aware projection consumed by the shared enterprise-model settings UI. |
+| `activate/configure/addCustom/updateCustom/removeProfile/configureModels/restart` | Optional native management operations; Web profiles reject mutation. |
+
+The client descriptor uses strict Zod codecs. Configuration sent to the browser excludes issuer, client ID, Key Binding base, model base URL, tokens, and keys.
+
+## Web composition
+
+### Direct installation
+
+`dsh-oidc` declares its own default Web-first Bundle patch. Install it directly from npm into the official Web profile without authoring a wrapper Bundle:
+
+```bash
+dsh plugin --profile web add @eduwork/dsh-oidc@0.1.0-alpha.11
+```
+
+For auditing, development, or validating unpublished changes, install a reviewed 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 install links the checkout into the Profile, so the source directory must remain available. It does not scan the current workspace. Team deployments should prefer a reviewed, exact npm version; `@eduwork/dsh-oidc@alpha` is only for deployments that intentionally follow prerelease updates.
+
+The shipped patch mounts exactly one `enterprise-oidc` instance using `DSH_OIDC_ENTERPRISE_PROFILE`. The Web backend requires the DSH WebServer to listen exactly on `127.0.0.1` and builds the fixed `/oauth/callback` from its actual port; no public callback-origin setting is accepted. It deliberately does not set `agent-default-model`, because Provider and model IDs belong to the deployment's Enterprise Profile and users can select an available enterprise model in DSH.
+
+### Product-owned Bundle
+
+```yaml
+- id: agent-default-model
+  config:
+    provider: example-ai
+    model: example-max
+
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+        web:
+          returnPath: /
+```
+
+The containing DSH profile/bundle must also include the ordinary Web app, credentials, LLM/Pi adapter dependencies, settings, attachment services, and client surfaces. `dsh-oidc` is not a complete DSH distribution.
+
+See the [getting-started guide](getting-started.en.md) for OIDC registration, Key Binding implementation, environment variables, acceptance, and troubleshooting.
+
+## Desktop/native composition
+
+```yaml
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        backend: native
+        uiMode: models-only
+        profilePathEnv: PRODUCT_ENTERPRISE_PROFILE
+```
+
+The host supplies Cordis service `enterpriseAccounts`. Any product-owned institution catalog MUST first be converted by the host or assembly layer into a standard Enterprise Profile; `dsh-oidc` does not read or interpret product catalogs:
+
+```ts
+interface EnterpriseAccounts {
+  status(institutionID: string): Promise<NativeStatus>
+  login(institutionID: string, options: { allowProvision: false }): Promise<NativeStatus>
+  reconcile(institutionID: string, options: { allowProvision: boolean }): Promise<NativeStatus>
+  logout(institutionID: string): Promise<NativeStatus>
+  configuration(): Promise<NativeManagement>
+  activate(institutionID: string): Promise<NativeManagement>
+  configure(institutionID: string): Promise<NativeManagement>
+  addCustom(baseURL: string): Promise<NativeManagement>
+  updateCustom(institutionID: string, baseURL: string): Promise<NativeManagement>
+  removeInstitution(institutionID: string): Promise<NativeManagement>
+  configureCustomModels(institutionID: string, mode: 'discovery' | 'manual', models: RuntimeModel[]): Promise<NativeManagement>
+  restart(): Promise<{restarting: true}>
+}
+```
+
+`NativeStatus` may include `displayName`, `organization`, `state`, `userName`, `affiliation`, `accessExpiresAt`, `runtimeCredentialRef`, `credentialReady`, `credentialState`, and `capabilities`. `runtimeCredentialRef` is only a host status assertion; when present, it MUST equal the normalized Enterprise Profile `keyBinding.credentialRef`. Credential naming belongs to the Profile, not to Wails, Electron, or any other host implementation.
+
+Only the first four lifecycle operations are required for a native identity backend. Management operations are capability-detected: when absent, the same UI remains a read-only profile/model viewer. This is a host adapter, not part of OIDC or Key Binding wire standards. It can be implemented by Wails, Electron, Tauri, a mobile bridge, or another local host.
+
+The public browser projection is versioned as `dsh-oidc/management/v1alpha1`. It deliberately excludes tokens and credentials. Web Enterprise Profiles set all mutation capabilities to false; a native adapter may set `manageProfiles`, `manageModels`, and `restart` according to the methods it actually provides.
+
+## Model capability transforms
+
+The plugin exposes a Cordis service named `enterpriseTransforms`:
+
+```js
+const dispose = ctx.enterpriseTransforms.register({
+  provider: 'example-ai',
+  model: 'example-max',
+  inputModalities: ['image'],
+  when: ({ inputModalities }) => !inputModalities.includes('image'),
+  transform: async (request, nativeModelInfo) => {
+    // Return a provider-bound request. Do not mutate request/transcript in place.
+    return request
+  },
+})
+```
+
+Route-wide and model-specific transforms run in that order. Duplicate registrations at the same scope are rejected. Registration changes emit `llm/adapters-updated`.
+
+Transforms are executable local plugins and must be reviewed separately. They are never loaded from an Enterprise Profile.
+
+## DSH upgrade procedure
+
+For every DSH release candidate or stable upgrade:
+
+1. update exact peer versions in a branch;
+2. diff the public exports and relevant types used above;
+3. run unit and package tests;
+4. launch a plain Web DSH profile and complete login, provisioning, model call, refresh, logout;
+5. launch the desktop/native composition and compare user-visible behavior;
+6. verify client loader format and slot names;
+7. review whether official DSH capability supersedes any local adapter code;
+8. record results in `docs/compatibility.en.md` before release.
+
+No semver range should silently opt this security-sensitive plugin into an untested DSH release while DSH remains pre-1.0.

package/docs/dsh-integration.md

@@ -0,0 +1,171 @@
+# DSH 集成与扩展边界
+
+**简体中文** | [English](dsh-integration.en.md)
+
+## 支持的宿主基线
+
+当前兼容基线为 DeepSeek Harness `0.1.2-alpha.2`，上游 commit `0a53fb55bea101816fa226bb964ae2bed71c343b`。DSH 仍处于预发布阶段，因此 peer version 使用精确版本。
+
+插件只使用公开 package export，不复制 DSH 源码：
+
+| DSH 服务/软件包 | 用途 |
+| --- | --- |
+| `dsh-typert-protocol` | Host/Client RPC 描述符。 |
+| `dsh-host-webserver` | 精确 `/oauth/callback` 路由。 |
+| `dsh-credentials` | Session 和运行时 API Key 存储。 |
+| `dsh-llm` | Adapter 注册、凭据、重试策略和稳定错误。 |
+| `dsh-llm-pi-ai` | 官方 `PiAiAdapter`。 |
+| `dsh-settings` | Provider 目录和就绪状态。 |
+| `dsh-launch-environment` | Credential Provider 服务不存在时的凭据降级。 |
+| Client runtime/remotes/slots/theme | 浏览器 bundle 和有边界的 UI/品牌表面。 |
+
+OpenAI-compatible 网络实现来自 `@earendil-works/pi-ai`，它也是 DSH 官方 Pi adapter 的基础。
+
+## 为什么 Provider adapter 位于本包内
+
+只有 OIDC 认证还不能获得可调用的企业模型。闭环集成还需要稳定 Provider 路由，并确保其凭据引用与 Key Binding 输出一致。再发布一个机构特有 Provider 包，会重新制造本仓库要消除的耦合。
+
+因此 adapter 是 `dsh-oidc` 内部模块，但其行为受到严格约束：
+
+- 只有一个经过审查的 `openai-compatible` 实现；
+- 只接受声明式 Provider/模型事实；
+- 使用 DSH 官方 LLM 注册和 Pi adapter；
+- 不维护第二套 HTTP 栈；
+- 不自动发现环境中的 pi-ai 凭据；
+- 重试策略和附件解析由 DSH 负责。
+
+它仍以 `@eduwork/dsh-oidc/provider` 导出，供测试和高级本地组合使用，但 Enterprise Profile 无法替换它。
+
+## Cordis 服务入口
+
+默认导出为 `OidcAccountService`，这是名为 `oidcAccounts` 的 `TypertRemoteService`。远程方法包括：
+
+| 方法 | 结果 |
+| --- | --- |
+| `configuration()` | 删除秘密和 endpoint 基址后的公开 Profile。 |
+| `status(profileID)` | 本地 session/凭据状态。 |
+| `begin(profileID)` | Web 返回重定向 URL，native 返回完成状态。 |
+| `reconcile(profileID, {allowProvision})` | 执行 bootstrap 和 resolve/provision/renew。 |
+| `logout(profileID)` | 本地清理，并尽力执行 OIDC 撤销。 |
+| `management()` | 共用企业模型设置 UI 使用的宿主能力投影。 |
+| `activate/configure/addCustom/updateCustom/removeProfile/configureModels/restart` | 可选 native 管理操作；Web Profile 拒绝修改。 |
+
+Client 描述符使用严格 Zod codec。发送给浏览器的配置不包含 issuer、client ID、Key Binding base、模型 base URL、Token 或 Key。
+
+## Web 组合
+
+### 直接安装
+
+`dsh-oidc` 自带默认的 Web-first Bundle patch，可以直接从 npm 安装到官方 Web Profile，无需再编写 wrapper Bundle：
+
+```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 链接到 Profile，因此源码目录必须持续存在。它不会扫描当前工作区。团队部署应优先固定经过复核的 npm 精确版本；`@eduwork/dsh-oidc@alpha` 只适合明确希望跟随预发布更新的场景。
+
+随包 patch 使用 `DSH_OIDC_ENTERPRISE_PROFILE` 挂载且只挂载一个 `enterprise-oidc` 实例。Web backend 要求 DSH WebServer 精确监听 `127.0.0.1`，并从实际端口构造固定 `/oauth/callback`；不接受公网回调源配置。它有意不设置 `agent-default-model`，因为 Provider 和模型 ID 属于部署方 Enterprise Profile，用户可在 DSH 中选择可用企业模型。
+
+### 产品自有 Bundle
+
+```yaml
+- id: agent-default-model
+  config:
+    provider: example-ai
+    model: example-max
+
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        profilePathEnv: DSH_OIDC_ENTERPRISE_PROFILE
+        web:
+          returnPath: /
+```
+
+所属 DSH Profile/Bundle 还必须包含普通 Web 应用、credentials、LLM/Pi adapter 依赖、settings、attachment 服务和 Client 界面。`dsh-oidc` 不是完整 DSH 发行版。
+
+OIDC 注册、Key Binding 实现、环境变量、验收和排障见[接入指南](getting-started.md)。
+
+## Desktop/native 组合
+
+```yaml
+- insert:
+    - id: enterprise-oidc
+      name: '@eduwork/dsh-oidc'
+      config:
+        backend: native
+        uiMode: models-only
+        profilePathEnv: PRODUCT_ENTERPRISE_PROFILE
+```
+
+宿主提供 Cordis 服务 `enterpriseAccounts`。产品自有机构目录必须由宿主或装配层先转换为标准 Enterprise Profile；`dsh-oidc` 不读取或解释产品目录：
+
+```ts
+interface EnterpriseAccounts {
+  status(institutionID: string): Promise<NativeStatus>
+  login(institutionID: string, options: { allowProvision: false }): Promise<NativeStatus>
+  reconcile(institutionID: string, options: { allowProvision: boolean }): Promise<NativeStatus>
+  logout(institutionID: string): Promise<NativeStatus>
+  configuration(): Promise<NativeManagement>
+  activate(institutionID: string): Promise<NativeManagement>
+  configure(institutionID: string): Promise<NativeManagement>
+  addCustom(baseURL: string): Promise<NativeManagement>
+  updateCustom(institutionID: string, baseURL: string): Promise<NativeManagement>
+  removeInstitution(institutionID: string): Promise<NativeManagement>
+  configureCustomModels(institutionID: string, mode: 'discovery' | 'manual', models: RuntimeModel[]): Promise<NativeManagement>
+  restart(): Promise<{restarting: true}>
+}
+```
+
+`NativeStatus` 可以包含 `displayName`、`organization`、`state`、`userName`、`affiliation`、`accessExpiresAt`、`runtimeCredentialRef`、`credentialReady`、`credentialState` 和 `capabilities`。`runtimeCredentialRef` 只是宿主状态回报；若提供，必须等于 Enterprise Profile 规范化后的 `keyBinding.credentialRef`。凭据命名策略属于 Profile，不属于 Wails、Electron 或其他宿主实现。
+
+Native 身份后端只必须实现前四项生命周期操作。管理操作通过能力探测：缺少这些方法时，同一 UI 会保持为只读 Profile/模型查看器。这是宿主 adapter，不属于 OIDC 或 Key Binding 网络标准；Wails、Electron、Tauri、移动桥接或其他本地宿主均可实现。
+
+浏览器公共投影版本为 `dsh-oidc/management/v1alpha1`，有意排除 Token 和凭据。Web Enterprise Profile 的所有修改能力为 false；native adapter 可以根据实际方法声明 `manageProfiles`、`manageModels` 和 `restart`。
+
+## 模型能力转换
+
+插件提供名为 `enterpriseTransforms` 的 Cordis 服务：
+
+```js
+const dispose = ctx.enterpriseTransforms.register({
+  provider: 'example-ai',
+  model: 'example-max',
+  inputModalities: ['image'],
+  when: ({ inputModalities }) => !inputModalities.includes('image'),
+  transform: async (request, nativeModelInfo) => {
+    // 返回将要发送给 Provider 的请求，不要原地修改 request/transcript。
+    return request
+  },
+})
+```
+
+路由级转换先执行，模型级转换后执行。同一 scope 的重复注册会被拒绝。注册变化触发 `llm/adapters-updated`。
+
+转换是可执行本地插件，必须单独审查，绝不会从 Enterprise Profile 加载。
+
+## DSH 升级流程
+
+每次升级 DSH release candidate 或 stable 版本时：
+
+1. 在分支中更新精确 peer version；
+2. 对比上述公开 export 和相关类型；
+3. 运行单元测试和打包测试；
+4. 启动纯 Web DSH Profile，完成登录、provision、模型调用、刷新和退出；
+5. 启动 Desktop/native 组合并比较用户可见行为；
+6. 验证 Client loader 格式和 slot 名称；
+7. 审查 DSH 官方能力是否已替代任何本地 adapter 代码；
+8. 发布前在 `docs/compatibility.md` 记录结果。
+
+DSH 仍处于 1.0 之前时，不应使用 semver 范围让该安全敏感插件静默升级到未经测试的 DSH 版本。

package/docs/ecnu-reference.en.md

@@ -0,0 +1,66 @@
+# ECNU reference composition
+
+[简体中文](ecnu-reference.md) | **English**
+
+This repository uses East China Normal University / ChatECNU only as a concrete reference for the generic standard. The public example contains placeholders and no production endpoint, OIDC client identifier, API key, token, personal data, or logo asset.
+
+The reference file is [`examples/ecnu.enterprise-profile.example.json`](../examples/ecnu.enterprise-profile.example.json).
+
+## Intended composition
+
+The existing ChatECNU Work product can be expressed as a composition rather than a monolith:
+
+```text
+DeepSeek Harness
+  + dsh-oidc
+      - standard OIDC identity
+      - worker-user-center-v1 Key Binding
+      - ECNU Enterprise Profile
+      - declarative ChatECNU Provider/models
+      - bounded brand/account UI and shared enterprise-model settings UI
+  + ECNU product plugins
+      - image-understanding fallback for text-only ecnu-max
+      - enterprise search route and official DSH result rendering
+      - product presets/skills/resources
+      - native desktop account adapter and OS credential vault
+      - quota or institution-specific business UI
+  + desktop shell/packaging/updater
+```
+
+Pure Web DSH uses the Web backend and a host-appropriate Credential Provider. ChatECNU Work desktop uses the native backend and keeps its existing Wails implementation behind `enterpriseAccounts`. Both render the enterprise-model section through `dsh-oidc`; the desktop adapter merely advertises additional mutation/restart capabilities. Neither mode changes OIDC or Key Binding server contracts.
+
+## Identity expectation
+
+The OIDC Provider should return standard UserInfo:
+
+```json
+{
+  "sub": "opaque-stable-subject",
+  "name": "Display Name"
+}
+```
+
+If `name` is absent, UI falls back to `sub`. The plugin does not call an ECNU-private profile endpoint and does not map `data.attributes.XM` or similar paths. This is deliberate: the organization OIDC service should expose the standard claim.
+
+## Model example
+
+The placeholder shows two common facts:
+
+- `ecnu-max`: text-only, large context, selectable reasoning efforts;
+- `ecnu-plus`: native text/image input, thinking enabled but no selectable reasoning-effort parameter.
+
+For `ecnu-plus`, `supportsReasoningEffort: false` removes the unsupported effort while preserving thinking behavior. For `ecnu-max`, a separate ECNU image-understanding plugin can register `enterpriseTransforms` to add an aggregate image capability without altering the profile or replacing the Provider route.
+
+## Before any public release
+
+ECNU maintainers must separately approve:
+
+- the GitHub organization and repository visibility;
+- copyright holder wording;
+- use of university/ChatECNU names and brand values;
+- public support and security contact addresses;
+- publication of the npm package name;
+- removal of every internal endpoint, identifier, log, archive, and credential;
+- the production deployment's privacy/security review.
+
+The existence of this reference document is not authorization to publish institutional infrastructure details or brand assets.

package/docs/ecnu-reference.md

@@ -0,0 +1,66 @@
+# 华东师范大学参考组合
+
+**简体中文** | [English](ecnu-reference.en.md)
+
+本仓库仅以华东师范大学 / ChatECNU 作为通用标准的一项具体参考实现。公开示例全部使用占位符，不包含生产 endpoint、OIDC Client ID、API Key、Token、个人数据或 Logo 资产。
+
+参考文件为 [`examples/ecnu.enterprise-profile.example.json`](../examples/ecnu.enterprise-profile.example.json)。
+
+## 预期组合
+
+现有 ChatECNU Work 产品可以表达为组合结构，而不是单体实现：
+
+```text
+DeepSeek Harness
+  + dsh-oidc
+      - 标准 OIDC 身份
+      - worker-user-center-v1 Key Binding
+      - ECNU Enterprise Profile
+      - 声明式 ChatECNU Provider/模型
+      - 有边界的品牌/账号 UI 和共用企业模型设置 UI
+  + ECNU 产品插件
+      - 面向纯文本 ecnu-max 的图像理解回退
+      - 企业搜索通路和 DSH 官方结果渲染
+      - 产品预设、Skill 和资源
+      - native 桌面账号 adapter 与操作系统凭据保险库
+      - 配额或机构特有业务 UI
+  + 桌面外壳、打包与更新器
+```
+
+纯 Web DSH 使用 Web 后端和适合宿主的 Credential Provider。ChatECNU Work 桌面端使用 native 后端，并把现有 Wails 实现保留在 `enterpriseAccounts` 后面。两者都通过 `dsh-oidc` 渲染企业模型区域；桌面 adapter 只额外声明可变配置和重启能力。两种模式都不改变 OIDC 或 Key Binding 服务端契约。
+
+## 身份预期
+
+OIDC Provider 应返回标准 UserInfo：
+
+```json
+{
+  "sub": "opaque-stable-subject",
+  "name": "Display Name"
+}
+```
+
+如果没有 `name`，UI 会降级显示 `sub`。插件不会调用 ECNU 私有人员信息接口，也不会映射 `data.attributes.XM` 等路径。这是有意设计：机构 OIDC 服务应提供标准 claim。
+
+## 模型示例
+
+占位示例展示了两类常见模型事实：
+
+- `ecnu-max`：纯文本、大上下文、支持选择 reasoning effort；
+- `ecnu-plus`：原生文本/图片输入，支持 thinking，但不支持选择 reasoning-effort 参数。
+
+对 `ecnu-plus` 设置 `supportsReasoningEffort: false`，会移除不支持的 effort 参数但保留 thinking。对 `ecnu-max`，独立的 ECNU 图像理解插件可注册 `enterpriseTransforms`，在不修改 Profile、不替换 Provider 路由的情况下增加聚合图像能力。
+
+## 任何公开发布之前
+
+ECNU 维护者必须另行批准：
+
+- GitHub 组织和仓库可见性；
+- 版权主体表述；
+- 校名、ChatECNU 名称和品牌值的使用；
+- 公开支持和安全联系地址；
+- npm 包名发布；
+- 清除全部内部 endpoint、标识符、日志、归档和凭据；
+- 生产部署的隐私与安全审查。
+
+存在这份参考文档不代表已获准发布任何机构基础设施细节或品牌资产。

package/docs/enterprise-profile.en.md

@@ -0,0 +1,159 @@
+# Enterprise Profile specification (`dsh-oidc/v1alpha1`)
+
+[简体中文](enterprise-profile.md) | **English**
+
+## Status and conformance
+
+This document specifies the data contract consumed by `dsh-oidc` `0.1.x`. The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, and **MAY** are interpreted as described by RFC 2119 and RFC 8174.
+
+The canonical machine-readable schema is [`schema/enterprise-profile.v1alpha1.schema.json`](../schema/enterprise-profile.v1alpha1.schema.json). Runtime validation is intentionally stricter in several security-sensitive URL cases. A conforming profile MUST pass both JSON Schema validation and `normalizeEnterpriseProfile()`.
+
+## Trust model
+
+Profiles are trusted deployment configuration, not user input. Nevertheless, the parser is fail-closed:
+
+- unknown keys are rejected at the root and at every executable-relevant nested object;
+- total serialized profile size is limited to 512 KiB;
+- production URLs require HTTPS;
+- development HTTP is accepted only for explicit loopback hosts;
+- URL credentials, fragments, and endpoint-base query strings are rejected;
+- only the built-in `openai-compatible` adapter can be selected;
+- Key Binding accepts only its protocol base and an optional local DSH credential reference; network paths and fields remain fixed;
+- logo data URLs accept PNG/WebP only, not SVG.
+
+A remote administration system MAY distribute profile JSON only if the host authenticates the source, verifies integrity, and stages changes through review. Downloaded JSON does not become safe merely because it contains no JavaScript.
+
+## Root object
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `schemaVersion` | yes | Exact string `dsh-oidc/v1alpha1`. |
+| `id` | yes | Profile ID matching `^[a-z][a-z0-9-]{0,63}$`. |
+| `displayName` | yes | Human-readable integration name. |
+| `organization` | no | Organization label; defaults to `displayName`. |
+| `nativeInstitutionID` | no | Identifier passed only to a native backend; defaults to `id`. |
+| `allowInsecureDevelopment` | no | Enables loopback HTTP for local development. Network HTTP additionally requires `insecureDevelopmentOrigin`. |
+| `insecureDevelopmentOrigin` | no | Exact non-TLS development origin. It is accepted only together with `allowInsecureDevelopment: true`, and every HTTP OIDC/key-binding/provider endpoint must use this exact origin. Never ship it in a production profile. |
+| `brand` | yes | Bounded presentational values. |
+| `oidc` | yes | OIDC public-client facts. |
+| `keyBinding` | yes | Key Binding base URL and optional local DSH credential reference. |
+| `provider` | yes | One local OpenAI-compatible Provider route and model list. |
+
+## Branding
+
+Branding changes only approved presentation surfaces. It does not alter authentication or executable behavior.
+
+| Field | Limit / behavior |
+| --- | --- |
+| `productName` | 80 characters; document/sidebar label. |
+| `organizationName` | 120 characters. |
+| `mark` | 1–4 characters used when no logo is supplied. |
+| `logoURL` | HTTPS URL or base64 PNG/WebP, at most 128 KiB as text. Remote images use `referrerPolicy=no-referrer`. |
+| `primaryColor` | Six-digit hex color. Only a bounded DSH token set is overridden. |
+| `loginTitle` | 120 characters. |
+| `loginDescription` | 500 characters. |
+| `supportURL` | Absolute HTTPS URL opened with `noopener noreferrer`. |
+
+Profiles MUST NOT include logos or names without permission from the rights holder. Operators concerned about remote-image tracking SHOULD package a base64 PNG/WebP or host the asset on a controlled origin with a restrictive CSP.
+
+## OIDC object
+
+```json
+{
+  "issuer": "https://id.example.edu/oidc",
+  "clientId": "dsh-web-public-client",
+  "scopes": ["openid", "profile", "offline_access"]
+}
+```
+
+- `issuer` is an OIDC Issuer Identifier. Paths are supported; query and fragment are not. Exact string equality with Discovery metadata is required.
+- `clientId` identifies a public client. No client secret belongs in a profile or this plugin.
+- `scopes` MUST contain `openid` and `profile`, contain no whitespace within an item, and contain no duplicates.
+- `offline_access` SHOULD be requested when the Provider issues refresh tokens and policy allows it.
+- Key Binding authorization scopes are deployment-specific but SHOULD use the names in the reference example.
+
+The Web redirect URI is fixed to `http://127.0.0.1:<DSH-port>/oauth/callback`. The host and path are not configurable; the port follows the DSH WebServer's actual listening port.
+
+## Key Binding object
+
+```json
+{
+  "baseURL": "https://ai.example.edu/api/worker/v1",
+  "credentialRef": "EXAMPLE_AI_TEST_API_KEY"
+}
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `baseURL` | yes | Base URL of the `worker-user-center-v1` Key Binding interface group. |
+| `credentialRef` | no | Local DSH Credential Provider name under which the bound model API key is stored. It must match `^[A-Za-z_][A-Za-z0-9_]*$` and is limited to 128 characters. |
+
+The protocol type is fixed to `worker-user-center-v1`, and the Provider ID sent on the wire is always `provider.id`. When `credentialRef` is omitted, the parser preserves the backward-compatible default: uppercase the Provider ID, replace non-alphanumerics with `_`, and append `_API_KEY`. For example, `example-ai` defaults to `EXAMPLE_AI_API_KEY`.
+
+`credentialRef` is only the name of a local secret-store entry. It is not an API key and is never sent to OIDC, Key Binding, or the model service. A normal single-environment deployment SHOULD omit it. Deployments that reuse one Provider ID across production and test MUST configure distinct references, for example `EXAMPLE_AI_API_KEY` and `EXAMPLE_AI_TEST_API_KEY`, so one environment cannot resolve another environment's key.
+
+Endpoint paths, request/response fields, and Provider ID semantics are protocol facts and MUST NOT be customized by profiles. If a native host returns `runtimeCredentialRef`, it MUST equal the normalized profile value or the plugin fails closed.
+
+## Provider object
+
+The Provider object is data interpreted by a local audited adapter.
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | DSH route ID and source of the default credential reference. Must be unique across loaded profiles. |
+| `displayName` | no | User-facing Provider name. |
+| `adapter` | yes | Exact string `openai-compatible`. |
+| `baseURL` | yes | HTTPS OpenAI-compatible API base. |
+| `reasoning` | no | Default DSH/pi-ai reasoning level, default `high`. |
+| `defaultContextWindow` | no | Positive safe integer, default 262144. |
+| `defaultMaxTokens` | no | Positive safe integer, default 32768. |
+| `maxRequestImageBytes` | no | Accumulated native-image request budget. |
+| `requestImagePixelBudget` | no | Image normalization pixel budget. |
+| `requestImageMaxBytes` | no | Per-normalized-image byte budget. |
+| `streamIdleTimeoutMs` | no | Positive idle timeout, default 300000. |
+| `retryPolicy` | no | DSH provider-owned retry policy; default normal/2 retries. |
+| `compat` | no | Bounded pi-ai OpenAI compatibility facts. |
+| `models` | yes | 1–128 unique model entries. |
+
+`retryPolicy.mode` is `normal` or `always`. `always` can retry indefinitely until success, cancellation, or disposal and SHOULD NOT be enabled without an explicit product decision. The policy is validated again by DSH.
+
+`compat` accepts only the keys enumerated in the JSON Schema. Operators MUST describe provider facts accurately; a compatibility override can change request semantics, though it cannot execute code.
+
+## Model entries
+
+Each model has:
+
+- required `id`;
+- optional display `name`;
+- `input` containing `text`, `image`, or both (default `text`);
+- optional positive `contextWindow` and `maxTokens`;
+- optional `reasoning` boolean;
+- optional `reasoningEfforts` object, or `false`;
+- optional bounded `compat` overrides.
+
+If a model supports thinking but not selectable reasoning effort, set:
+
+```json
+{
+  "compat": { "supportsReasoningEffort": false }
+}
+```
+
+The adapter then enables the profile's thinking behavior while removing an unsupported user-selected effort before validation and transport. The request is not rejected merely because the provider lacks an effort parameter.
+
+## Secret prohibition
+
+Profiles MUST NOT contain:
+
+- OIDC client secrets;
+- access, refresh, or ID tokens;
+- model API keys;
+- private signing keys;
+- session cookies;
+- personal identity data.
+
+The OIDC client is public. Runtime secrets are created after login and stored only by the active DSH Credential Provider.
+
+## Versioning
+
+Unknown `schemaVersion` values are rejected. During alpha, any field may change between `v1alphaN` versions. A stable `v1` will use additive optional fields for minor releases and a new schema version for incompatible changes. See [Compatibility](compatibility.en.md).