[Ghost] 同域公开与鉴权端点无法分别控制凭证注入

[FIERsity]

问题

Ghost 的 network.secrets[].inject.hosts 当前按 hostname 匹配。若同一服务在同一 hostname 下同时提供公开端点和需要 API Key 的端点，manifest 无法表达“只对鉴权端点注入凭证”。

例如：

• https://example.com/mcp：公开、无需认证
• https://example.com/v1/convert：需要 Authorization: Bearer ...

以下声明会让两个端点都命中同一个 Secret：

{
  "network": {
    "hosts": ["example.com"],
    "secrets": [{
      "key": "api_key",
      "inject": {
        "header": "Authorization",
        "format": "Bearer {value}",
        "hosts": ["example.com"]
      }
    }]
  }
}

实际表现

在一个文件转换 Ghost 中，/mcp 原本是免登录接口，但因为可选 API Key 的 inject.hosts 命中了整个域名：

1. 未配置 Key 时，调用公开 /mcp 会在 Host 网络层直接失败，提示凭证未配置；
2. 删除未使用的 Secret/全域注入声明后，同一个 list_conversions 请求立即成功；
3. 实测 docx 查询成功返回 14 条转换路线。

插件当前可通过删除未使用的 Secret 规避，但如果后续同时启用同域的 /mcp 和 /v1/convert，插件侧没有安全、准确的表达方式。

期望

希望确认当前 host-only 行为是否为预期设计，并考虑为凭证注入增加更细粒度的显式 allowlist，例如：

• path 精确匹配或前缀匹配；
• 可选的 HTTP method 限定；
• 或 manifest 中独立的 endpoint/request profile。

安全语义建议：未匹配时不注入；重定向逐跳重新判断；不根据远端 401/403 自动重试并携带凭证。

需要考虑的兼容与安全项

• 旧 manifest 未声明新字段时保持当前行为；
• path 前缀边界（如 /api 不应误匹配 /api-public）；
• URL 编码、query 是否参与匹配；
• 同域和跨域重定向时重新匹配；
• 未匹配端点绝不携带 Secret；
• 权限展示、安装批准状态和插件升级行为；
• Secret 不进入日志、返回值、沙箱或会话历史。

这是 manifest/权限边界变更，建议先讨论 schema，再决定是否实现核心 PR。

[dash-s-cindy]

判断：值得处理。当前按 hostname 注入凭证是 Cindy 现有实现和契约中的预期行为，但它无法表达同一 hostname 下“公开端点不带凭证、鉴权端点才带凭证”的常见场景。Issue #1714 描述的是实际的可用性问题，也会造成凭证被发送到不需要它的同域端点；目前没有证据表明它会自动跨域泄露 Secret。

行动：建议先进行小范围 schema 设计，并以显式的 endpoint allowlist 作为第一版实现方向；暂不引入完整的 endpoint/request profile。旧 manifest 未声明新字段时保持当前 host-only 行为。设计确定后再提交核心网络层 PR，同时更新作者手册、权限展示和测试。

已确认的现状

• apps/desktop/src/shared/ghost.ts 当前只接受 network.secrets[].inject.hosts，并要求这些值逐字取自 network.hosts；省略 inject.hosts 表示全部白名单域名。当前 schema 没有 path 或 method 条件。
• apps/desktop/src/main/cindy-brain/networkSlot.ts 的 injectSecrets() 按 hostname 命中凭证，因此同一 hostname 下的 /mcp 与 /v1/convert 无法区分。未命中时不会注入；命中但凭证未配置时会快速失败，这与本 Issue 报告的现象相符。
• 重定向当前由主机手动逐跳跟随，并重新检查 HTTPS、端口和 hostname 白名单；跨 hostname 跳转会重新计算凭证。不过，同一 hostname 内目前不会按 path 重新判断，因此新增规则必须应用于每一跳。
• 当前不同凭证来源已有不同的 401 处理：OAuth/交换型凭证可能在 401 后刷新并重试一次；Connection JWT 仅 GET/HEAD/OPTIONS 可自动重试，非幂等请求只作废缓存而不重放。新增 endpoint 规则后，重定向和重试都必须复用同一个匹配器。
• 当前测试已覆盖凭证不会发送到未列入 inject.hosts 的 accounts.example.com，但尚未覆盖同域 path/method 区分、path 前缀边界或同域重定向后的重新匹配。
• docs/dev-rules/plugin-security-and-authoring.md 将 network 白名单、主机注入、凭证不回流沙箱以及作者手册同步列为安全契约。修改 manifest 校验时还必须满足存量插件升级无感的兼容要求。

推荐的第一版方向

可以考虑在现有 inject 下增加显式条件，例如：

{
  "network": {
    "hosts": ["example.com"],
    "secrets": [{
      "key": "api_key",
      "inject": {
        "header": "Authorization",
        "format": "Bearer {value}",
        "hosts": ["example.com"],
        "paths": ["/v1/convert"],
        "methods": ["POST"]
      }
    }]
  }
}

字段名称和最终形态仍应在 schema review 中确定。建议第一版优先支持 path 精确匹配；若支持前缀，必须按路径段边界匹配：/api 应命中 /api 和 /api/...，但不能命中 /api-public。query 默认不参与 path 匹配；method 未声明时不限制，显式声明时才限制。

旧 manifest 未声明新字段时应保持 host-only 语义，不能让已安装插件突然失效或要求重新配置凭证。

必须先固定的安全语义

1. 统一使用解析后的 HTTPS URL pathname 匹配，并明确 percent-encoding、重复斜杠、./..、大小写和 Unicode 主机名的规范化规则。对有歧义的编码路径应拒绝或采用保守的 fail-closed 规则。
2. 初始请求、每次重定向、每次凭证刷新/重试都重新匹配。未匹配时先清除由主机管理的凭证头，不能让上一跳注入的头或插件自带的 Authorization 继续发送。
3. 不允许根据远端 401/403 动态扩大凭证范围。现有 OAuth/交换型 401 重试机制仍可保留，但重试必须再次遵守 endpoint allowlist；Connection JWT 的现有幂等方法限制也不能被绕过。
4. 权限展示、安装批准和更新 diff 应能够清楚表达凭证注入的 host/path/method 范围。新增或修改注入目标是否构成权限扩张，需要与现有 permission baseline 一并定案，不能只修改运行时而不更新批准语义。
5. Secret 继续只存在于 Host 保险库和出站请求头，不进入日志、响应、沙箱、会话历史或错误诊断。

方案取舍

• 推荐：现有 inject 增加 path/method allowlist。 改动面较小，能直接解决本 Issue，旧 manifest 兼容性也最好。
• 次选：独立 endpoint/request profile。 表达力更强，适合未来不同端点拥有不同 header、请求体或认证流程，但会显著扩大 schema、权限 UI、批准状态和运行时复杂度，不建议作为本 Issue 的第一步。
• 不建议：根据 401/403 决定是否注入。 这会把凭证边界交给不可信远端，并带来不可预测的重试和泄露风险。

建议验收标准

• 旧 host-only manifest 的行为保持不变。
• 精确 path 只在声明路径注入；公开的 /mcp 不携带凭证。
• 若支持 prefix，/api 不命中 /api-public，但命中 /api/convert。
• method 限定正确区分 POST 与 GET；未声明 methods 时保持不限制。
• query、编码路径、尾斜杠和大小写规则都有固定测试。
• 同域和跨域重定向逐跳重新匹配：从受保护 path 跳到公开 path 时移除凭证，反向跳转时只有目标规则命中才注入。
• 未配置但未命中的 Secret 不应导致公开请求失败；命中但未配置仍保持现有 fail-closed 语义。
• OAuth/交换型 401 重试和 Connection JWT 的幂等方法限制不能绕过 path/method 规则。
• 插件自带 headers 和上一跳残留都不能重新带出主机凭证。
• 已安装、已批准、已启用的旧插件升级后无需重新配置；若新增权限投影字段，补充旧状态升级 fixture。

结论

建议接受 #1714，先进入 schema/design review，并以“host + path（第一版先精确匹配）”作为推荐实现方向。实现 PR 至少应同步修改 manifest 校验、作者手册、网络层匹配/重定向/重试逻辑、权限展示和专项测试；在这些兼容与批准语义未确定前，不建议直接改变运行时行为。

[FIERsity]

跟进状态更新(2026-08-06):两个配套 PR 已从 Draft 转出,等待 review。

现状

• feat(plugin-protocol): scope secret injection by endpoint cindy-protocol#30(协议定义:inject.paths / inject.methods,可选字段,省略时保持 host-only)→ 已解除 Draft,已 rebase 到最新 main,含 hosts 排序归一化(权限 diff 稳定),协议仓测试全过。
• feat(ghost): 按 endpoint 收窄凭证注入 #1719(Desktop 运行时:初始请求 / 401 重试 / 每跳重定向按 host+path+method 重新匹配,未命中剥除宿主管理凭证头)→ 已解除 Draft,已 rebase 到最新 main,并按 Copilot review 修了 3 处(401 重试不再重放降级后的副作用请求、逐跳注释、hosts 排序)。

已按本 issue 上 bot 分析收敛的设计

• 第一版只加 path/method allowlist,不做完整 endpoint profile ✓(与 bot 推荐方向一致)
• path 精确匹配、method 显式声明才限制、旧 manifest 未声明新字段保持 host-only ✓
• 路径规范化与歧义编码 fail-closed、重定向逐跳重新匹配、401 重试不得绕过 endpoint 规则 ✓
• 权限展示:仅在作者显式声明 endpoint 范围时新增 detail,旧 host-only manifest 的权限 baseline 不变 ✓

需要维护者拍板的一个点

旧 schema-v2 客户端会静默丢弃 paths/methods 字段,把收窄凭证退化为整域注入(fail-open)。两个 PR 已把退化后的行为限定为等于现状 host-only(不劣于今天),残余风险仅是「作者以为收窄了但旧客户端未生效」,不构成新的凭证泄露面;已在 PR 描述与作者手册中明确。若按协议仓 precedent(如 #39 revert 所示)要求「协议 main 不先于客户端 rollout 声明能力」,则合并顺序应为:先合 cindy#1719(Desktop 运行时,自带完整校验),再合 cindy-protocol#30(此时协议 main 的信号与实际客户端能力一致)。请确认该顺序或给出其他安排。