From 9bce430e911b5d8a12f4a9ac266c068b03645e56 Mon Sep 17 00:00:00 2001 From: chichuan Date: Mon, 26 Oct 2026 10:51:48 +0800 Subject: [PATCH] docs: seal v1.0.66-beta.2 release notes --- .../779-installer-skills-fail-closed.md | 0 .../1.0.66-beta.2}/auth-oidc-diagnostics.md | 0 .../auth-oidc-provider-hooks.md | 0 .../auth-oidc-split-exchange.md | 0 .../gitee-repair-openharmony-assets.md | 0 CHANGELOG.md | 117 ++++++++++++++++++ 6 files changed, 117 insertions(+) rename .changes/{ => released/1.0.66-beta.2}/779-installer-skills-fail-closed.md (100%) rename .changes/{ => released/1.0.66-beta.2}/auth-oidc-diagnostics.md (100%) rename .changes/{ => released/1.0.66-beta.2}/auth-oidc-provider-hooks.md (100%) rename .changes/{ => released/1.0.66-beta.2}/auth-oidc-split-exchange.md (100%) rename .changes/{ => released/1.0.66-beta.2}/gitee-repair-openharmony-assets.md (100%) diff --git a/.changes/779-installer-skills-fail-closed.md b/.changes/released/1.0.66-beta.2/779-installer-skills-fail-closed.md similarity index 100% rename from .changes/779-installer-skills-fail-closed.md rename to .changes/released/1.0.66-beta.2/779-installer-skills-fail-closed.md diff --git a/.changes/auth-oidc-diagnostics.md b/.changes/released/1.0.66-beta.2/auth-oidc-diagnostics.md similarity index 100% rename from .changes/auth-oidc-diagnostics.md rename to .changes/released/1.0.66-beta.2/auth-oidc-diagnostics.md diff --git a/.changes/auth-oidc-provider-hooks.md b/.changes/released/1.0.66-beta.2/auth-oidc-provider-hooks.md similarity index 100% rename from .changes/auth-oidc-provider-hooks.md rename to .changes/released/1.0.66-beta.2/auth-oidc-provider-hooks.md diff --git a/.changes/auth-oidc-split-exchange.md b/.changes/released/1.0.66-beta.2/auth-oidc-split-exchange.md similarity index 100% rename from .changes/auth-oidc-split-exchange.md rename to .changes/released/1.0.66-beta.2/auth-oidc-split-exchange.md diff --git a/.changes/gitee-repair-openharmony-assets.md b/.changes/released/1.0.66-beta.2/gitee-repair-openharmony-assets.md similarity index 100% rename from .changes/gitee-repair-openharmony-assets.md rename to .changes/released/1.0.66-beta.2/gitee-repair-openharmony-assets.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 56b4f8461..6b3820f0f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,123 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th ## [Unreleased] +## [1.0.66-beta.2] - 2026-10-26 + +### Added + +- OIDC 登录错误诊断：`auth provider-login `、`auth exchange-prepare` 和 `auth token-exchange` +保留 Portal 的公开错误码和 trace ID，并将已定义错误码转换为可读说明。 +覆盖配置、事务/state、授权码、身份校验、限流、上游调用和 DWS 会话签发错误。 +三个命令均为第三方 IdP 集成入口，不出现在 `dws auth --help` 与 shell 补全中，可显式执行。 + +- 从 `error.code`、`error.action`、`trace_id` 解析公开诊断；响应体缺失或无效时， + 使用合法的 `X-Dws-Trace-Id`。后端日志专用 `reason` 不进入客户端输出。 +- 人类可读错误显示 `Trace ID` 和 `Server Code`。JSON 复用现有字段： + 传统输出为 `error.server_error_code`，统一输出为 `error.upstream_code`， + 两者均提供 `error.trace_id` 和 `error.details.action/http_status/provider`。 +- `stop` 提示检查参数/配置或联系管理员；`restart_login` 提示重新登录或重新 + `exchange-prepare` 取码。保持单次请求，不自动重试旧 code/state。 +- 保留现有错误分类、退出码和 token 响应格式。只保留 Portal 已定义的固定公开 + message，不回显任意异常正文、内部 reason 或请求凭证；诊断标识限制长度和字符。 + +验证包含真实本地 HTTP 错误响应、三条命令的 JSON/人类输出、无效响应的 trace 回退、 +配置停止与重新登录提示、取消/超时分类、凭证反射过滤及不重试行为。 + +- OIDC Provider 通过 `edition.Hooks.OIDCProviders` 注册。核心 Hook 已实现；dws-ant 的真实 SDK 适配和注册留待后续接入。 + +`auth provider-login ` 从 `edition.Hooks.OIDCProviders` 选择授权实现。 +该命令为第三方 IdP 集成入口，不出现在 `dws auth --help` 与 shell 补全中，可显式执行。 +必填位置参数 `` 同时传给 transactions 和 exchange 接口。换票请求包含 +`provider`、`code`、`state`；显式指定 DWS 应用凭据时再加入 `client_id`、`client_secret`。 +核心通过注册项选择授权实现，具体 SDK 由 overlay 提供。 +服务地址使用系统统一的 MCP 配置（`mcp_url` 文件或默认地址），登录不修改端点配置。 + +#### Overlay 接入 + +公共类型位于 `pkg/edition`，overlay 不需要也不得导入核心的 `internal/auth`。 +在已有 `NewHooks()` 中注册名称及授权回调，再沿用启动入口的 `edition.Override(h)`： + +```go +h.OIDCProviders = func() []edition.OIDCProvider { + return []edition.OIDCProvider{ + { + Name: "ant", + Authorize: authorizeWithAntSDK, + }, + } +} +``` + +`authorizeWithAntSDK` 的函数签名为： + +```go +func(context.Context, edition.OIDCAuthorizationRequest) (edition.OIDCAuthorizationResult, error) +``` + +蚂蚁适配负责调用自己的 SDK，并把 SDK 实际返回的 `code/state` 转为公共结果类型。 +若已有 `AuthorizeOIDC` 使用业务侧 DTO，只在这个回调中转换类型；不用复制核心事务、 +换票或保存凭证代码。SDK 初始化与认证发生在回调执行时，注册函数只返回声明。 +名称可由 overlay 自定义，但必须满足 `[a-z][a-z0-9_-]{0,63}`，并与 Portal 已配置的 +provider 一致。重复名称、空回调、非法名称均为注册错误。 + +#### 执行边界 + +1. 核心校验 CLI 参数并选择已注册的回调。 +2. 核心向 Portal 创建事务，校验服务端 provider、授权参数与有效期。 +3. 核心向回调传入 `authorization_endpoint`、独立的参数 map 及受事务期限约束的 context。 +4. SDK 尊重取消与超时，原样使用服务端授权参数并返回实际取得的 `code/state`。 +5. 核心验证授权码及原事务 state，再换票、补全身份、保存 DWS profile。 + +SDK 会话、密码、DWS 换票用的 client secret 和 PKCE verifier 不属于这个回调的输入输出。 +错误中不得包含认证材料；核心也不记录 SDK 原始错误文本。授权失败、取消、超时或 +state 不匹配不会触发其他 SDK 或 Mock 兜底，也不会换票或保存凭证。 + +没有注册对应实现时，核心仍先检查 Portal 配置；服务端接受 provider 后返回 +`OIDC_SDK_UNAVAILABLE`。Help 和 dry-run 不枚举注册项、不初始化 SDK、不访问网络。 +普通 OAuth/PAT 登录和分步 `exchange-prepare` / `token-exchange` 入口保持独立。 + +#### 联调与依赖更新 + +核心的 Hook API 提交并推送后，overlay 需要把远程核心依赖更新到包含该 API 的提交， +再编译上述注册代码。只修改另一 Go 包里的同名文件不会替换核心实现。 + +回归验证覆盖自定义名称和 ant 注册、真实命令入口及凭证保存、非法/重复/缺失注册、 +后端拒绝、SDK 错误脱敏、取消/超时、state 篡改、空授权码和 help/dry-run 无副作用。 + +```bash +DWS_PACKAGE_VERSION=0.0.0-test CGO_ENABLED=0 go test ./pkg/edition ./internal/auth ./internal/app +``` + +已验证：上述三个包的完整测试、Hook 定向 race 测试、`go vet ./...`、`make build`， +以及构建后二进制的 provider-login help / dry-run。未执行真实蚂蚁网关登录。 + +- 支持业务分步完成第三方登录：先执行 `dws auth exchange-prepare --provider ant` 获取服务端授权参数，再由业务调用 IdP/SDK 取码，最后执行 `dws auth token-exchange --provider ant --code --state ` 换取 DWS Token。 + +支持 `--code-stdin`、可选且必须成对的 `--client-id/--client-secret`，默认返回现有 TokenData；显式 `--save` 后在线核验完整身份并保存，保留已有默认账号。两个命令均支持 `--dry-run`，服务地址使用系统统一的 MCP 配置（`mcp_url` 文件或默认地址），不修改全局配置；保存 Token 时记录其刷新所用的 Portal 地址。PKCE verifier 始终由服务端保存，换票失败不会自动重试一次性 code/state。 + +命令沿用统一结果输出。作为第三方 IdP 集成入口，两个命令以 Cobra Hidden 隐藏，不出现在 `dws auth --help` 与 shell 补全中，仍可显式执行；不进入 Agent Schema（Hidden 且无 Contract.Identity），也不再占用 reviewed Schema 排除列表。 + +macOS 终端按实际文件描述符识别，使用 `select` 等待输入，不依赖 `/dev/tty` 或 `/dev/stdin` 文件名，覆盖 `< /dev/tty` 重定向；以 50ms 周期检查取消，不改变终端模式、不关闭借用句柄。高编号输入使用低编号描述符副本等待，完成后只关闭副本；低编号描述符耗尽时明确报错。 + +`--code-stdin` 的等待输入和后续换票共享一分钟超时，并响应调用方的取消或更短截止时间。取消、超时错误保留原有身份，不归类为参数错误，也不会继续换票。Unix 标准输入使用可取消的轮询读取，取消后保留原文件描述符；Windows 控制台保留原输入模式，通过原生 API 取消读取，重定向管道则通过关闭来中断。宿主通过 `SetIn` 注入的自定义阻塞输入须支持 `Close` 中断读取（取消时会关闭，正常完成时保留）。无 `Close` 的自定义 Reader 须为非阻塞或自行响应 context。 + +OIDC 换票响应增加实际 DWS `clientId`（与 IdP 的 `client_id` 不同）。`provider-login` 和 `token-exchange --save` 均保存该应用绑定和原 Portal 地址。默认应用继续由 Portal 托管密钥；显式指定的自定义应用将原始密钥保存到现有安全凭证槽，并与 Token/Profile 写入一起回滚。刷新自定义应用时从该槽读取密钥，发送给原 Portal 的 `/oauth2/refreshToken`，不回退到全局应用、不跟随重定向、不在结果或 app.json 中暴露密钥。未使用 `--save` 的分步换票不写入本地凭证。 + +需要同步部署 Portal：默认 OIDC 响应返回实际 `clientId`，刷新接口接受可选 `clientSecret`。旧版默认响应缺少应用绑定时，新 CLI 会明确要求更新 Portal；旧的缺失绑定记录需要重新登录。 + +OIDC 登录持久化时记录 `oidc_provider`，刷新成功继续保留；该本地元数据不加入未保存的 token-exchange 返回值。所有 OIDC 分支只通过该字段识别，不再从 Portal 地址或密钥模式推断登录来源。此前未记录该字段的开发测试凭证不做兼容迁移，需重新登录。 + +OIDC 刷新前校验原应用、Portal 和登录来源绑定，缺失时直接报错，不使用全局应用或默认端点兜底。刷新失败不读取组织镜像或历史全局凭证，即使同用户、同组织也不能切换应用。被拒绝或失效时提示重新执行 provider-login 或原分步登录流程，自定义应用需沿用原 client-id/client-secret；网络、取消、超时、限流和 5xx 保留原凭证，不强制重新登录。普通 OAuth 既有恢复策略保持不变。 + +已确认的 `invalidParameter.authCode.notFound` 仍保留脱敏后的错误类型和规范化业务码供分类使用；错误识别不再意味着允许 OIDC 凭证恢复。服务端原始错误文本不进入输出、日志或错误链。 + +### Fixed + +- **Installer skill failures** (#779) — fail explicitly without an installation-success banner when a release archive has no usable skills and no local source is available; also fail when the PowerShell local mono skill directory is missing. + +- 修复 Gitee 补同步入口遗漏 OpenHarmony 附件的问题，使已发布稳定版本的完整九项制品能够通过附件清单校验。 + + ## [1.0.66-beta.1] - 2026-10-21 ### Fixed