@eduwork/dsh-oidc 0.1.0-alpha.11

package/docs/key-binding-protocol.en.md

@@ -0,0 +1,227 @@
+# Worker User Center Key Binding Protocol v1
+
+[简体中文](key-binding-protocol.md) | **English**
+
+## 1. Status and terminology
+
+This document defines `worker-user-center-v1`, the enterprise management protocol used by `dsh-oidc` to bind an OIDC-authenticated subject to a model runtime API key. It is not part of OIDC.
+
+It is a required part of the [server API specification](server-integration-contract.en.md). An implementation must also provide the OIDC Provider and model gateway required by that specification; implementing only the API below is not a complete `dsh-oidc` server.
+
+The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and **OPTIONAL** are interpreted as described by RFC 2119 and RFC 8174.
+
+[`protocol/openapi.yaml`](../protocol/openapi.yaml) is the machine-readable companion contract. If prose and OpenAPI differ, this document controls security and lifecycle semantics; OpenAPI controls field spelling and basic shapes. Such a difference is a specification defect and must be reported.
+
+## 2. Design objectives
+
+The protocol separates three credentials:
+
+- the user's organization password, seen only by the OIDC Provider;
+- an OIDC access token, used only against the UserInfo and Key Binding services;
+- a model runtime API key, used only by the model Provider route.
+
+The API key is a replaceable, revocable runtime credential—not proof of the user's identity. The Key Binding server is the authorization authority for provisioning and resolving it.
+
+## 3. Base URL and fixed resources
+
+An Enterprise Profile supplies one HTTPS `keyBinding.baseURL`. It MUST NOT contain userinfo, query, or fragment and SHOULD contain a versioned path such as `/api/worker/v1`.
+
+The following paths are fixed relative to that base URL:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/bootstrap` | Read Provider, capabilities, entitlement, and credential state. |
+| POST | `/runtime-credential/provision` | Create/bind a credential when state is `missing`. |
+| POST | `/runtime-credential/resolve` | Return the active credential. |
+| POST | `/runtime-credential/renew` | Rotate an `expiring` or `expired` credential. |
+
+Profiles and users MUST NOT override paths, HTTP methods, field mappings, or credential-reference names.
+
+## 4. Authentication and authorization
+
+Every request MUST use TLS except explicit loopback development. The client sends:
+
+```http
+Authorization: Bearer <OIDC access token>
+Accept: application/json
+```
+
+The server MUST validate at least:
+
+- token signature or introspection result;
+- issuer;
+- audience intended for the Key Binding service;
+- expiry/not-before;
+- authenticated subject;
+- required operation scope;
+- organization membership, account state, and model entitlement.
+
+Recommended scopes are:
+
+| Operation | Scope |
+| --- | --- |
+| bootstrap | `worker.bootstrap.read` |
+| provision | `worker.credential.provision` |
+| resolve | `worker.credential.read` |
+| renew | `worker.credential.renew` |
+
+A deployment MAY use different scope names, but they remain OIDC authorization policy and are listed in the Enterprise Profile `oidc.scopes`; wire operations do not change.
+
+The server MUST derive the bound subject from the validated access token. It MUST NOT accept a caller-supplied subject ID in a request body.
+
+## 5. Bootstrap
+
+Request:
+
+```http
+GET /api/worker/v1/bootstrap HTTP/1.1
+Authorization: Bearer …
+Accept: application/json
+```
+
+Minimum successful response:
+
+```json
+{
+  "provider": { "id": "example-ai" },
+  "capabilities": ["worker.credential.provision"],
+  "runtime_credential": {
+    "status": "missing",
+    "provisioning": { "allowed": true }
+  }
+}
+```
+
+The returned `provider.id` is REQUIRED and MUST exactly equal the Enterprise Profile `provider.id`. A mismatch is a binding failure.
+
+Valid `runtime_credential.status` values are:
+
+- `missing`: no credential is bound;
+- `active`: an active credential can be resolved;
+- `expiring`: rotate if `api_key_id` exists, otherwise resolve according to server policy;
+- `expired`: rotate if `api_key_id` exists, otherwise resolve according to server policy;
+- `suspended`: entitlement/account disabled; local credential must not be treated as usable;
+- `unavailable`: service cannot currently provide a credential.
+
+`subject` MAY carry informational management-plane display data. The client MUST NOT use it to replace OIDC `sub` or `name`.
+
+`protocol_version`, if present, MUST be `worker-user-center/v1`. It is optional during v1 adoption; a future major protocol can require explicit negotiation.
+
+## 6. Provision
+
+The user MUST complete OIDC authentication before provisioning. `dsh-oidc` additionally requires an explicit UI action (`allowProvision: true`) so a callback alone does not silently create a model credential.
+
+```http
+POST /api/worker/v1/runtime-credential/provision HTTP/1.1
+Authorization: Bearer …
+Content-Type: application/json
+Idempotency-Key: <UUID>
+
+{ "provider_id": "example-ai" }
+```
+
+The server MUST:
+
+- verify `provider_id` is authorized for the subject;
+- enforce organization provisioning policy;
+- make the operation idempotent for the same authenticated subject, Provider, and Idempotency-Key;
+- return the same logical result for a replay during the server's idempotency retention window;
+- reject reuse of a key with a different payload as `409 Conflict`;
+- never log the returned API key.
+
+## 7. Resolve
+
+```http
+POST /api/worker/v1/runtime-credential/resolve HTTP/1.1
+Authorization: Bearer …
+Content-Type: application/json
+
+{
+  "provider_id": "example-ai",
+  "api_key_id": "optional-known-id"
+}
+```
+
+Resolve MUST NOT create a new entitlement. It returns the active credential already bound to the subject or a `404`/policy error. A server MAY rotate opaque secret material while preserving the same logical `api_key_id`, but it must not change Provider ownership.
+
+## 8. Renew
+
+```http
+POST /api/worker/v1/runtime-credential/renew HTTP/1.1
+Authorization: Bearer …
+Content-Type: application/json
+Idempotency-Key: <UUID>
+
+{
+  "provider_id": "example-ai",
+  "api_key_id": "key-123"
+}
+```
+
+Renew requires `api_key_id`, is idempotent, and rotates or replaces an expiring/expired credential. The server SHOULD invalidate superseded secret material as soon as operationally safe and MUST document any overlap window.
+
+## 9. Credential response
+
+All three successful POST operations return:
+
+```json
+{
+  "provider_id": "example-ai",
+  "api_key": "secret-runtime-value",
+  "api_key_id": "key-123",
+  "status": "active",
+  "expires_at": "2026-09-01T00:00:00Z"
+}
+```
+
+`provider_id`, `api_key`, and `status=active` are REQUIRED. The client refuses an absent/mismatched Provider or empty key.
+
+Credential responses MUST include `Cache-Control: no-store` and SHOULD include `Pragma: no-cache`. Servers, proxies, APM agents, and WAFs MUST redact Authorization headers and `api_key` response fields. The secret MUST NOT be placed in URLs, error details, analytics events, or audit logs.
+
+## 10. Errors
+
+Errors SHOULD use `application/problem+json` following RFC 9457 with a stable extension field `code`. At minimum:
+
+- `400`: malformed request/Provider ID;
+- `401`: missing, invalid, expired, or wrong-audience token;
+- `403`: scope, membership, entitlement, suspension, or provisioning policy denial;
+- `404`: no resolvable/renewable credential;
+- `409`: idempotency or lifecycle conflict;
+- `429`: rate limit, preferably with `Retry-After`;
+- `5xx`: server failure without secret material.
+
+Clients MUST NOT retry provisioning/renewal without preserving the same Idempotency-Key for the same logical operation. `dsh-oidc` currently performs one call; DSH model request retries are separate and never repeat Key Binding operations.
+
+## 11. Lifecycle and revocation
+
+The Key Binding service SHOULD revoke model credentials when:
+
+- organization membership or entitlement ends;
+- the OIDC subject is disabled;
+- a credential is rotated;
+- a security administrator revokes it;
+- its maximum lifetime expires.
+
+Local logout removes the cached model key but does not by itself prove remote revocation. Deployments requiring immediate remote revocation SHOULD add an authenticated management operation in a future protocol version rather than overloading OIDC token revocation.
+
+The model gateway MUST independently enforce API key status, Provider scope, expiration, and quota. Possession of an old key must not bypass the current enterprise policy indefinitely.
+
+## 12. Privacy and audit
+
+The server SHOULD minimize identity data in bootstrap. Audit records SHOULD contain event time, opaque subject reference, Provider ID, operation, outcome, policy reason, request correlation ID, and `api_key_id`—never the API key or OIDC token.
+
+Retention, access control, breach response, and cross-border processing are deployment responsibilities. The protocol does not grant permission to collect additional personal data.
+
+## 13. Conformance checklist
+
+A server is conformant when it:
+
+- implements all four fixed resources;
+- authenticates requests with the OIDC access token and never request-body subject data;
+- returns exact Provider binding;
+- enforces required scopes and organization entitlement;
+- implements provision/renew idempotency;
+- returns no-store credential responses;
+- never logs secrets;
+- exposes stable lifecycle states and problem codes;
+- passes the repository's OpenAPI contract tests plus organization-specific authorization tests.

package/docs/key-binding-protocol.md

@@ -0,0 +1,227 @@
+# Worker User Center Key Binding Protocol v1
+
+**简体中文** | [English](key-binding-protocol.en.md)
+
+## 1. 状态与术语
+
+本文定义 `worker-user-center-v1`：`dsh-oidc` 用它把经 OIDC 认证的 subject 与模型运行时 API Key 绑定。这是企业管理协议，不属于 OIDC 标准。
+
+它是[服务端接口规范](server-integration-contract.md)的必需组成部分。实现方必须同时提供该规范要求的 OIDC Provider 与模型网关；只实现以下 API 不构成完整的 `dsh-oidc` 服务端。
+
+关键词 **必须（MUST）**、**不得（MUST NOT）**、**必需（REQUIRED）**、**应该（SHOULD）**、**不应该（SHOULD NOT）**、**建议（RECOMMENDED）**、**不建议（NOT RECOMMENDED）**、**可以（MAY）** 和 **可选（OPTIONAL）** 按 RFC 2119 与 RFC 8174 解释。
+
+[`protocol/openapi.yaml`](../protocol/openapi.yaml) 是配套的机器可读契约。若正文与 OpenAPI 不一致，本文决定安全和生命周期语义，OpenAPI 决定字段拼写和基本结构。任何差异都属于规范缺陷，必须报告。
+
+## 2. 设计目标
+
+协议区分三类凭据：
+
+- 机构密码：只由 OIDC Provider 看见；
+- OIDC access token：只用于 UserInfo 和 Key Binding 服务；
+- 模型运行时 API Key：只用于模型 Provider 路由。
+
+API Key 是可替换、可撤销的运行凭据，不是用户身份证明。Key Binding 服务端是决定其创建和解析权限的授权权威。
+
+## 3. Base URL 与固定资源
+
+Enterprise Profile 提供一个 HTTPS `keyBinding.baseURL`。其中不得包含 userinfo、query 或 fragment，并且应该包含类似 `/api/worker/v1` 的版本路径。
+
+相对于该 base URL，以下路径固定不变：
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/bootstrap` | 读取 Provider、能力、授权资格和凭据状态。 |
+| POST | `/runtime-credential/provision` | 状态为 `missing` 时创建或绑定凭据。 |
+| POST | `/runtime-credential/resolve` | 返回活动凭据。 |
+| POST | `/runtime-credential/renew` | 轮换 `expiring` 或 `expired` 凭据。 |
+
+Profile 和用户不得覆盖路径、HTTP 方法、字段映射或凭据引用名。
+
+## 4. 认证与授权
+
+除显式 loopback 开发环境外，每个请求都必须使用 TLS。客户端发送：
+
+```http
+Authorization: Bearer <OIDC access token>
+Accept: application/json
+```
+
+服务端至少必须验证：
+
+- token 签名或 introspection 结果；
+- issuer；
+- 面向 Key Binding 服务的 audience；
+- 过期时间和 not-before；
+- 已认证 subject；
+- 操作所需 scope；
+- 机构成员资格、账号状态和模型授权。
+
+建议 scope：
+
+| 操作 | Scope |
+| --- | --- |
+| bootstrap | `worker.bootstrap.read` |
+| provision | `worker.credential.provision` |
+| resolve | `worker.credential.read` |
+| renew | `worker.credential.renew` |
+
+部署可以使用不同 scope 名称，但这些仍属于 OIDC 授权策略，并列在 Enterprise Profile `oidc.scopes` 中；网络操作本身不变。
+
+服务端必须从已验证 access token 派生绑定 subject，不得接受请求 body 中由调用方提供的 subject ID。
+
+## 5. Bootstrap
+
+请求：
+
+```http
+GET /api/worker/v1/bootstrap HTTP/1.1
+Authorization: Bearer …
+Accept: application/json
+```
+
+最小成功响应：
+
+```json
+{
+  "provider": { "id": "example-ai" },
+  "capabilities": ["worker.credential.provision"],
+  "runtime_credential": {
+    "status": "missing",
+    "provisioning": { "allowed": true }
+  }
+}
+```
+
+返回的 `provider.id` 是必需字段，必须与 Enterprise Profile `provider.id` 完全相等。不一致即视为绑定失败。
+
+有效的 `runtime_credential.status`：
+
+- `missing`：尚未绑定凭据；
+- `active`：可以解析活动凭据；
+- `expiring`：存在 `api_key_id` 时轮换，否则按服务端策略解析；
+- `expired`：存在 `api_key_id` 时轮换，否则按服务端策略解析；
+- `suspended`：授权或账号已停用；本地凭据不得继续视为可用；
+- `unavailable`：服务当前无法提供凭据。
+
+`subject` 可以携带仅供管理面显示的信息。客户端不得用它替换 OIDC `sub` 或 `name`。
+
+若返回 `protocol_version`，其值必须是 `worker-user-center/v1`。该字段在 v1 采用阶段可选；未来 major 协议可以要求显式协商。
+
+## 6. Provision
+
+用户必须先完成 OIDC 认证。`dsh-oidc` 还要求显式 UI 操作（`allowProvision: true`），因此仅完成 callback 不会静默创建模型凭据。
+
+```http
+POST /api/worker/v1/runtime-credential/provision HTTP/1.1
+Authorization: Bearer …
+Content-Type: application/json
+Idempotency-Key: <UUID>
+
+{ "provider_id": "example-ai" }
+```
+
+服务端必须：
+
+- 验证该 subject 获准使用 `provider_id`；
+- 执行机构凭据创建策略；
+- 对相同已认证 subject、Provider 和 Idempotency-Key 保证幂等；
+- 在服务端幂等保留窗口内，对重放请求返回相同逻辑结果；
+- 同一 key 与不同 payload 重用时返回 `409 Conflict`；
+- 绝不记录返回的 API Key。
+
+## 7. Resolve
+
+```http
+POST /api/worker/v1/runtime-credential/resolve HTTP/1.1
+Authorization: Bearer …
+Content-Type: application/json
+
+{
+  "provider_id": "example-ai",
+  "api_key_id": "optional-known-id"
+}
+```
+
+Resolve 不得创建新的授权资格。它返回已绑定到 subject 的活动凭据，或者返回 `404`/策略错误。服务端可以在保持同一逻辑 `api_key_id` 的情况下轮换不透明秘密材料，但不得改变 Provider 所有权。
+
+## 8. Renew
+
+```http
+POST /api/worker/v1/runtime-credential/renew HTTP/1.1
+Authorization: Bearer …
+Content-Type: application/json
+Idempotency-Key: <UUID>
+
+{
+  "provider_id": "example-ai",
+  "api_key_id": "key-123"
+}
+```
+
+Renew 要求提供 `api_key_id`，必须幂等，并轮换或替换即将过期/已过期凭据。服务端应该在操作安全允许后尽快使旧秘密材料失效，并且必须记录任何重叠有效窗口。
+
+## 9. 凭据响应
+
+三个 POST 操作成功时都返回：
+
+```json
+{
+  "provider_id": "example-ai",
+  "api_key": "secret-runtime-value",
+  "api_key_id": "key-123",
+  "status": "active",
+  "expires_at": "2026-09-01T00:00:00Z"
+}
+```
+
+`provider_id`、`api_key` 和 `status=active` 是必需字段。Provider 缺失、不匹配或 key 为空时，客户端会拒绝响应。
+
+凭据响应必须包含 `Cache-Control: no-store`，并且应该包含 `Pragma: no-cache`。服务端、代理、APM agent 和 WAF 必须脱敏 Authorization header 与 `api_key` 响应字段。不得把秘密写入 URL、错误详情、分析事件或审计日志。
+
+## 10. 错误
+
+错误应该遵循 RFC 9457，使用 `application/problem+json`，并提供稳定扩展字段 `code`。至少包含：
+
+- `400`：请求或 Provider ID 格式错误；
+- `401`：token 缺失、无效、过期或 audience 错误；
+- `403`：scope、成员资格、授权、停用或创建策略拒绝；
+- `404`：没有可解析或可更新的凭据；
+- `409`：幂等或生命周期冲突；
+- `429`：限流，最好包含 `Retry-After`；
+- `5xx`：不包含秘密材料的服务端失败。
+
+同一逻辑操作重试 provision/renew 时，客户端必须保留相同 Idempotency-Key。`dsh-oidc` 当前只发起一次调用；DSH 模型请求重试属于另一条链路，绝不会重复 Key Binding 操作。
+
+## 11. 生命周期与撤销
+
+以下情况发生时，Key Binding 服务应该撤销模型凭据：
+
+- 机构成员资格或授权终止；
+- OIDC subject 被停用；
+- 凭据被轮换；
+- 安全管理员撤销凭据；
+- 达到最大生命周期。
+
+本地退出会删除缓存模型 Key，但不能单独证明远程凭据已撤销。要求即时远程撤销的部署，应该在未来协议版本增加经过认证的管理操作，而不是复用 OIDC token revocation。
+
+模型网关必须独立执行 API Key 状态、Provider scope、过期和配额策略。持有旧 Key 不得无限期绕过当前企业策略。
+
+## 12. 隐私与审计
+
+服务端应该尽量减少 bootstrap 返回的身份数据。审计记录应该包含事件时间、不透明 subject 引用、Provider ID、操作、结果、策略原因、请求关联 ID 和 `api_key_id`，绝不能包含 API Key 或 OIDC token。
+
+数据保留、访问控制、泄露响应和跨境处理由部署方负责。该协议不授予收集更多个人数据的权限。
+
+## 13. 符合性检查
+
+服务端满足以下条件时符合本规范：
+
+- 实现全部四个固定资源；
+- 使用 OIDC access token 认证请求，绝不使用请求 body 中的 subject 数据；
+- 返回完全匹配的 Provider 绑定；
+- 执行所需 scope 和机构授权；
+- 实现 provision/renew 幂等；
+- 凭据响应使用 no-store；
+- 不记录秘密；
+- 提供稳定生命周期状态和问题代码；
+- 通过仓库 OpenAPI 契约测试和机构特有授权测试。

package/docs/oidc-interoperability.en.md

@@ -0,0 +1,100 @@
+# OIDC interoperability profile
+
+[简体中文](oidc-interoperability.md) | **English**
+
+OIDC is one part of the [server API specification](server-integration-contract.en.md). A conforming integration also requires the same accountable service owner to jointly deliver fixed Key Binding and the model gateway; implementing this document alone is not complete.
+
+## Standards
+
+The Web backend is a public OpenID Connect Relying Party based on:
+
+- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
+- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
+- [OAuth 2.0 Authorization Framework (RFC 6749)](https://www.rfc-editor.org/rfc/rfc6749)
+- [PKCE (RFC 7636)](https://www.rfc-editor.org/rfc/rfc7636)
+- [OAuth 2.0 for Native Apps (RFC 8252)](https://www.rfc-editor.org/rfc/rfc8252)
+- [OAuth 2.0 Token Revocation (RFC 7009)](https://www.rfc-editor.org/rfc/rfc7009)
+- [OAuth 2.0 Authorization Server Issuer Identification (RFC 9207)](https://www.rfc-editor.org/rfc/rfc9207)
+
+This document states the narrower interoperability choices made by `dsh-oidc`.
+
+## Required Provider behavior
+
+The Provider MUST:
+
+1. publish Discovery at `{issuer-without-trailing-slash}/.well-known/openid-configuration`;
+2. return an `issuer` exactly equal to the configured Issuer Identifier;
+3. publish `authorization_endpoint`, `token_endpoint`, `jwks_uri`, and `userinfo_endpoint`;
+4. advertise `S256` in `code_challenge_methods_supported`;
+5. issue RS256 ID Tokens with a non-empty `kid` and a unique matching RSA signing JWK;
+6. support Authorization Code flow for a public client without a client secret;
+7. return Bearer access tokens and an ID Token from the token endpoint;
+8. return JSON UserInfo containing non-empty `sub` equal to the ID Token `sub`.
+
+Discovery endpoints MAY use HTTPS origins different from the issuer, as the standard allows. Network HTTP is rejected. Loopback HTTP is accepted only when the profile explicitly enables development mode and both issuer/endpoint hosts are loopback.
+
+The current implementation supports RS256 only. Providers using ES256, PS256, encrypted ID Tokens, signed UserInfo JWTs, PAR, JAR, DPoP, or mTLS are not yet interoperable.
+
+## Authorization request
+
+The plugin generates cryptographically random:
+
+- 256-bit `state`;
+- 256-bit `nonce`;
+- 384-bit PKCE verifier and S256 challenge.
+
+Pending flows expire after ten minutes and are limited to 32 per plugin process. Existing query parameters on a discovered authorization endpoint are preserved; protocol parameters are set by the plugin.
+
+The redirect URI is always `http://127.0.0.1:<DSH-port>/oauth/callback`. Host and path are fixed, the port follows the DSH WebServer's actual listening port, and no request or proxy header is used to infer it.
+
+## Callback validation
+
+The callback:
+
+- accepts only the fixed path;
+- requires exactly one non-empty `state` and `code` for a successful response;
+- rejects duplicate `state`, `code`, `error`, or `iss` parameters;
+- consumes a pending state once, even on failure;
+- checks RFC 9207 `iss` when present;
+- exchanges the code with the original PKCE verifier.
+
+The post-callback `returnPath` must be a same-origin absolute path, preventing an open redirect.
+
+## ID Token validation
+
+The implementation verifies:
+
+- three-part JWS structure;
+- protected `alg=RS256` and non-empty `kid`;
+- exactly one RSA JWK matching `kid`, optional `use=sig`, and optional `alg=RS256`;
+- signature;
+- exact `iss`;
+- `aud` containing the client ID;
+- `azp` equal to the client ID when `aud` contains multiple values;
+- non-empty `sub`;
+- exact nonce;
+- finite required `iat` and `exp`, optional `nbf`, with 60 seconds of clock skew;
+- `at_hash` when the claim is present.
+
+TLS trust and DNS resolution remain responsibilities of the Node.js host and operating system.
+
+## UserInfo and display identity
+
+`userinfo_endpoint` is required by this interoperability profile even though its advertisement is not mandatory in every generic OIDC deployment.
+
+The response MUST contain `sub` and it MUST match the verified ID Token `sub`. The account display label is:
+
+1. trimmed standard UserInfo `name`, if non-empty;
+2. otherwise trimmed UserInfo `sub`.
+
+The plugin intentionally has no JSON path mapping or private profile endpoint. Organizations SHOULD fix their OIDC UserInfo response to supply the standard `name` claim when a human-readable label is desired.
+
+`affiliation` is currently accepted as an optional display extension; it does not affect authorization. A future stable profile may replace it with a namespaced claim or remove it.
+
+## Refresh and logout
+
+If the access token is within 90 seconds of expiry and a refresh token exists, the plugin refreshes it. On `invalid_grant`, the stored OIDC session and local model credential are removed and login is required. A rotated refresh token replaces the previous one. An expired session without a refresh token is handled the same way when an active session is next required.
+
+Logout attempts RFC 7009 revocation when Discovery publishes `revocation_endpoint`, then removes both the OIDC session record and the derived model credential locally. Remote revocation failure is logged without blocking local cleanup.
+
+The plugin does not implement RP-Initiated Logout or front/back-channel logout in this version.

package/docs/oidc-interoperability.md

@@ -0,0 +1,100 @@
+# OIDC 互操作规范
+
+**简体中文** | [English](oidc-interoperability.en.md)
+
+OIDC 是[服务端接口规范](server-integration-contract.md)的一部分。合格的机构接入还必须由同一服务所有者联合提供固定 Key Binding 和模型网关能力；只实现本文件并不构成完整接入。
+
+## 标准依据
+
+Web 后端是基于以下标准的 public OpenID Connect Relying Party：
+
+- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
+- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
+- [OAuth 2.0 Authorization Framework（RFC 6749）](https://www.rfc-editor.org/rfc/rfc6749)
+- [PKCE（RFC 7636）](https://www.rfc-editor.org/rfc/rfc7636)
+- [OAuth 2.0 for Native Apps（RFC 8252）](https://www.rfc-editor.org/rfc/rfc8252)
+- [OAuth 2.0 Token Revocation（RFC 7009）](https://www.rfc-editor.org/rfc/rfc7009)
+- [OAuth 2.0 Authorization Server Issuer Identification（RFC 9207）](https://www.rfc-editor.org/rfc/rfc9207)
+
+本文说明 `dsh-oidc` 在这些标准范围内采用的更严格互操作选择。
+
+## Provider 必需行为
+
+Provider 必须：
+
+1. 在 `{去掉末尾斜杠的 issuer}/.well-known/openid-configuration` 发布 Discovery；
+2. 返回与配置的 Issuer Identifier 完全一致的 `issuer`；
+3. 发布 `authorization_endpoint`、`token_endpoint`、`jwks_uri` 和 `userinfo_endpoint`；
+4. 在 `code_challenge_methods_supported` 中声明 `S256`；
+5. 签发带非空 `kid` 的 RS256 ID Token，并提供唯一匹配的 RSA 签名 JWK；
+6. 支持无 client secret 的 public client Authorization Code flow；
+7. 从 token endpoint 返回 Bearer access token 和 ID Token；
+8. 返回 JSON UserInfo，其中非空 `sub` 必须与 ID Token `sub` 相同。
+
+标准允许 Discovery endpoint 使用与 issuer 不同的 HTTPS origin。插件拒绝网络 HTTP；只有 Profile 显式启用开发模式，且 issuer/endpoint 主机都是 loopback 时才接受 HTTP。
+
+当前实现只支持 RS256。使用 ES256、PS256、加密 ID Token、签名 UserInfo JWT、PAR、JAR、DPoP 或 mTLS 的 Provider 暂不兼容。
+
+## Authorization 请求
+
+插件生成密码学安全随机值：
+
+- 256-bit `state`；
+- 256-bit `nonce`；
+- 384-bit PKCE verifier 和 S256 challenge。
+
+待完成流程十分钟后过期，每个插件进程最多保存 32 个。Discovery 返回的 authorization endpoint 上已有 query 参数会被保留，协议参数则由插件设置。
+
+Redirect URI 始终为 `http://127.0.0.1:<DSH端口>/oauth/callback`。host 和 path 固定，端口取 DSH WebServer 的实际监听端口；不从请求头或代理配置推断。
+
+## Callback 校验
+
+Callback：
+
+- 只接受固定路径；
+- 成功响应必须恰好包含一个非空 `state` 和一个非空 `code`；
+- 拒绝重复的 `state`、`code`、`error` 或 `iss` 参数；
+- 即使失败，也只允许一个待处理 state 被消费一次；
+- 如果存在 RFC 9207 `iss`，则对其进行校验；
+- 使用原始 PKCE verifier 交换 code。
+
+Callback 后的 `returnPath` 必须是同源绝对路径，以防止开放重定向。
+
+## ID Token 校验
+
+实现会校验：
+
+- 三段式 JWS 结构；
+- protected header 中 `alg=RS256` 且 `kid` 非空；
+- 恰好一个 RSA JWK 与 `kid` 匹配，可选 `use=sig` 和 `alg=RS256`；
+- 签名；
+- `iss` 完全一致；
+- `aud` 包含 client ID；
+- 当 `aud` 有多个值时，`azp` 等于 client ID；
+- 非空 `sub`；
+- nonce 完全一致；
+- 必需且有限的 `iat`、`exp`，以及可选 `nbf`，允许 60 秒时钟偏差；
+- 存在 `at_hash` 时校验它。
+
+TLS 信任和 DNS 解析仍由 Node.js 宿主和操作系统负责。
+
+## UserInfo 与显示身份
+
+虽然并非所有通用 OIDC 部署都强制发布 `userinfo_endpoint`，本互操作规范要求它存在。
+
+响应必须包含 `sub`，且必须与已验证 ID Token 的 `sub` 匹配。账号显示名称按以下顺序确定：
+
+1. 非空且去除首尾空白的标准 UserInfo `name`；
+2. 否则使用去除首尾空白的 UserInfo `sub`。
+
+插件有意不提供 JSON path 映射或私有人员信息 endpoint。希望显示人类可读姓名的机构，应该修正 OIDC UserInfo 响应并提供标准 `name` claim。
+
+当前接受 `affiliation` 作为可选显示扩展，但它不影响授权。未来稳定规范可能将其替换为带命名空间的 claim，或直接移除。
+
+## 刷新与退出
+
+当 access token 距离过期不足 90 秒且存在 refresh token 时，插件会刷新会话。若收到 `invalid_grant`，会删除已存 OIDC 会话和本地模型凭据，并要求重新登录。轮换后的 refresh token 会替换旧值。没有 refresh token 的过期会话在下次需要活动会话时按同样方式处理。
+
+退出登录时，如果 Discovery 发布 `revocation_endpoint`，插件会尝试按 RFC 7009 撤销 token；随后在本地删除 OIDC 会话记录和派生模型凭据。远程撤销失败会被记录，但不阻止本地清理。
+
+当前版本不实现 RP-Initiated Logout、front-channel logout 或 back-channel logout。