HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/RELEASE_NOTES_v0.2.0.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# BailingHub v0.2.0：工具清单访问保护与主动核验

`v0.2.0` 把 URL 工具清单的读取边界从隐含约定变成可配置、可验证的治理能力。管理员现在必须在“签名保护”和“允许公开”之间明确表达意图；中枢会把配置意图与实际探针结果分开显示，不再因为请求带了签名就假定接口已经受到保护。

本版本只治理“谁能下载工具清单”。工具调用继续使用既有签名、可信主体、路由白名单、风险审批、幂等和业务系统最终授权，ACC 与 Client API 均未变化。

## 用户可见结果

- 新建 URL 工具源默认选择“签名保护（推荐）”。只有管理员明确接受接口路径、参数、scope 和风险声明可被 URL 访问者查看时，才选择“允许公开”，保存时还会再次确认。
- 工具源列表同时显示“期望策略”和“实测结果”，并保留签名、未签名、错误签名三类 HTTP 状态证据。
- 受保护模式只有在正确签名返回 2xx，且未签名与错误签名分别返回 401、403 或 404 时才判定为 `protected`。
- 负向请求仍返回 2xx 时判定为 `public`；重定向、429、5xx、网络错误等不足以证明保护有效的结果判定为 `inconclusive`。两种情况都拒绝替换清单缓存，继续使用上一份可用清单。
- 公开模式只发送未签名请求，不会在失败时偷偷改用签名读取。

## 两种访问策略

| 策略 | 适用场景 | 中枢刷新行为 | 业务侧要求 |
|---|---|---|---|
| `signed_required` | 默认；清单不应匿名公开 | 正签读取，再执行未签名和错误签名负向探针 | 使用工具源同一密钥验签；负向请求返回 401/403/404；受保护响应禁止缓存 |
| `public_allowed` | 明确接受公开发现能力清单 | 只发送未签名请求 | 匿名 GET 可返回清单；工具调用仍须独立验签和授权 |

配置策略不代替业务授权。即使清单允许公开，真实工具请求仍必须按原协议校验 `X-Bailing-Signature`、`X-Bailing-On-Behalf-Of`、任务身份和业务权限。

## 主动探针与缓存安全

- 三类请求各自使用 10 秒上限；两个负向探针并发执行，最坏等待不叠加成 20 秒。
- 正向清单响应最多读取 5 MiB，并同时检查 `Content-Length` 与流式实际字节数。
- 正式策略不跟随重定向，避免探针在跳转后对错误目标形成结论。
- 访问泄露或结果无法判定时，探针证据与脱敏审计会被保存，但完整 `spec_url` 不进入告警通知。
- 只有策略验证和清单解析都通过后才替换缓存；失败始终保留旧缓存。

## 历史来源升级

新增迁移 `053_tool_spec_access_policy.sql`，为 `bz_tool_providers` 增加可空的访问策略和最近探针字段。升级顺序仍是：

```bash
npm run db:init
# 然后重启 BailingHub
```

升级前已有的 URL 工具源不会被系统猜成公开或已保护：

- 现有缓存保持不变，刷新继续沿用原来的签名读取方式；
- 控制台显示“待确认（历史配置）”，两个正式策略均不预选；
- 内部兼容标记 `legacy_unverified` 只用于读取历史记录，不属于公开 Schema，也不能作为 API 新建或更新值；
- 停用来源或修改说明、治理、检索等非清单字段不强迫选择策略；
- 修改清单 URL、密钥、自动刷新、重新启用等会改变清单读取面的操作，必须先选择正式策略；
- 最近探针已证明端点受保护时，控制台可一键采用“签名保护”，但仍由管理员明确确认。

管理员完成选择后，数据库只保存 `signed_required` 或 `public_allowed`。内部历史标记在后续正常保存或刷新时归一化为 `NULL`，无需额外数据清洗迁移。

## PHP / PHP7 SDK

PHP 与 PHP7 `SpecServer` 新增：

- `handlePublic()`：显式返回公开清单；
- `respondPublic()`：裸 PHP 显式公开响应；
- `responseHeaders()`：框架接入时取得推荐响应头；
- `respond($spec, $secret)`：传入密钥的受保护响应自动增加 `Cache-Control: private, no-store`。

旧的 `handle(..., null)` / `respond($spec, null)` 公开写法继续兼容，但新代码推荐使用带 `Public` 的显式入口，避免把公开意图隐藏在 `null` 中。

## 兼容性与边界

- 这是只增不改的 minor 升级；新增数据库字段均可空，旧代码会忽略它们。
- 不修改 ACC、Client API 版本、执行器协议、工具调用签名、审批语义、幂等规则或最终业务授权。
- 新建 URL 来源省略策略时安全默认 `signed_required`；显式提交内部历史标记会被拒绝。
- 自定义工具源仓储可继续使用既有 `upsert`；新的窄探针更新方法为可选扩展点。
- 回滚应用时应保留 053 新列和迁移账本。只有协调恢复旧应用与完整数据库快照时才回退数据库，不要单独删除账本或字段。

## 验证

```bash
npm run release:check
npm run e2e:console
```

重点覆盖：

- 两种正式策略的请求方式和失败关闭行为；
- 正签、未签名、错误签名状态分类；
- 超时、响应大小和重定向边界；
- 旧缓存保留、探针持久化与告警脱敏；
- 历史记录不被自动猜测、敏感修改前强制确认；
- 公开模式二次确认和已保护历史来源的一键采用；
- Schema、API、数据库仓储与 PHP / PHP7 SDK 兼容性。

## 相关文档

- [兼容性与升级](兼容性与升级.md#十url-工具清单访问策略升级)
- [公开运行时契约](CONTRACT.md)
- [第三方对接指南](第三方对接指南.md#63-发布接口清单--后台注册)
- [工具治理设计](TOOLS_DESIGN.md)
- [PHP SDK](../sdk/php/README.md)
- [PHP7 SDK](../sdk/php7/README.md)
- [English release notes](RELEASE_NOTES_v0.2.0.en.md)