功能建议：支持为连接 Hub 的请求配置自定义 Header

[Shujakuinkuraudo]

背景

目前 HAPI 在自托管场景下，客户端 / runner 连接 Hub 时，主要依赖：

• CLI_API_TOKEN / Bearer Token 的 HTTP API 认证
• Socket.IO 连接时的 auth token

这在普通部署下没有问题，但如果 Hub 放在某些认证代理后面，就会比较难用。

比如以下场景：

• Cloudflare Access
• OAuth2 Proxy
• Google IAP
• 企业内网里的统一认证反代
• 其他要求固定 Header / Cookie 的反向代理

这些场景下，虽然 Hub 的 URL 可达，但 HAPI 客户端侧如果不能额外附带代理要求的 Header / Cookie，就无法正常连接。

---

希望支持的能力

希望 HAPI 能支持一个通用的“自定义请求头”配置，用于客户端 / runner 连接 Hub 时附加额外 Header，而不是做某个厂商特定的适配。

例如支持类似：

• 环境变量：HAPI_EXTRA_HEADERS_JSON
• 和/或 settings.json 中增加 extraHeaders

例如：

{
  "Cookie": "CF_Authorization=...",
  "CF-Access-Client-Id": "...",
  "CF-Access-Client-Secret": "..."
}

---

希望生效的范围

希望这个能力能统一应用到：

1. 连接 Hub 的 HTTP API 请求
2. Socket.IO / WebSocket / polling 连接

因为如果只支持 HTTP，不支持 socket，很多实时能力还是会受影响。

---

为什么建议做成通用 Header，而不是 Cloudflare 专项支持

因为这个需求不只是 Cloudflare Access 才会遇到，很多认证代理 / 反代场景都会有类似要求。

如果做成通用能力，可以同时覆盖：

• Cloudflare Access
• OAuth2 Proxy
• IAP 类网关
• 企业内网认证代理
• 其他自定义网关

这样对自托管部署会更灵活，也避免引入厂商特定逻辑。

---

设计上希望保持简单

我理解这个功能最好是：

• 可选能力，不影响现有用户
• 只有配置了才生效
• 作为高级 / 自托管场景能力提供
• 尽量只做“透传 Header”，不改变现有认证模型

---

想确认的问题

1. 维护者是否愿意接受这种“通用自定义 Header”能力？
2. 更推荐只做环境变量，还是同时支持 settings.json 配置？
3. 是否建议 HTTP 和 Socket.IO 一起支持，而不是只支持其中一部分？

如果这个方向可以，我可以再整理一个尽量聚焦的 PR。

[github-actions]

目前代码里没有找到“连接 Hub 时附加自定义 Header / Cookie”的现成能力。

已确认的现状：

• CLI/runner 发往 Hub 的 REST 请求目前固定只带 Authorization: Bearer <token> 和 Content-Type: application/json，见 cli/src/api/api.ts:25、cli/src/api/apiSession.ts:307、cli/src/runner/controlClient.ts:58。
• Socket.IO 连接目前只在握手 auth 中发送 token、clientType、sessionId / machineId，没有看到额外 header 配置，见 cli/src/api/apiSession.ts:109、cli/src/api/apiMachine.ts:223。
• Hub 侧 /cli/* HTTP 路由只校验 Authorization 头，见 hub/src/web/routes/cli.ts:74。
• Hub 侧 /cli Socket.IO namespace 只校验 socket.handshake.auth.token，见 hub/src/socket/server.ts:99。
• 当前 CLI 的可持久化设置字段只有 machineId、runnerAutoStartWhenRunningHappy、cliApiToken、apiUrl、serverUrl，未发现 extraHeaders 一类字段，见 cli/src/persistence.ts:13。
• 现有配置初始化模式是“环境变量优先，其次 ~/.hapi/settings.json”，CLI_API_TOKEN 和 HAPI_API_URL 都这样处理，见 cli/src/ui/tokenInit.ts:21、cli/src/ui/apiUrlInit.ts:17。

关于你提的 3 个问题，按当前代码能确认的是：

1. “是否接受这个功能”这一点代码里无法判断，需要维护者确认。
2. 从现有配置模式看，如果实现，环境变量和 settings.json 同时支持会更贴近当前 CLI 配置方式；目前已有配置就是 env 优先、settings 次之。
3. HTTP 和 Socket.IO 需要一起覆盖才完整。当前 REST 和 Socket.IO 是两套独立的连接路径；如果只改 HTTP，/cli 的实时连接仍然会继续只走 handshake.auth.token。

Relevant code:

• cli/src/api/api.ts:25 - 创建 session/machine 的 REST 请求头固定为 Authorization + Content-Type
• cli/src/api/apiSession.ts:109 - session Socket.IO 连接只配置 auth
• cli/src/api/apiMachine.ts:223 - machine Socket.IO 连接只配置 auth
• hub/src/web/routes/cli.ts:74 - Hub CLI HTTP 路由只读取 Authorization
• hub/src/socket/server.ts:99 - Hub CLI Socket.IO 只读取 handshake.auth.token
• cli/src/persistence.ts:13 - settings.json 字段列表，未见 extraHeaders
• cli/src/ui/tokenInit.ts:21 - token 初始化：env > settings.json > prompt
• cli/src/ui/apiUrlInit.ts:17 - API URL 初始化：env > settings.json > default

如果你要继续整理 PR，按现有代码结构，最小闭环至少会落在 CLI 配置读取、REST client、两个 Socket.IO client 这几处。

---

HAPI Bot

[Shujakuinkuraudo]

补充一下这个需求背后的安全动机。

从安全角度看，这样做的意义主要有几点：

1. 分层防护
   HAPI 自身已有应用层认证（例如 CLI_API_TOKEN），但如果服务直接暴露在公网，只有这一层通常还不够。
   在前面增加一层独立的鉴权网关，可以把“能到达服务”与“能调用服务”分开，形成更清晰的边界。

2. 降低公网暴露风险
   即使应用自身有 token，如果入口前面没有额外访问控制，仍然会直接暴露给公网扫描、探测、误访问或针对性攻击。
   额外的鉴权网关可以先把大多数未授权请求挡在外面。

3. 适配企业/团队已有安全体系
   很多自托管环境已经有统一接入层，比如：

   • Cloudflare Access
   • OAuth2 Proxy
   • Google IAP
   • 内部 SSO / API Gateway
   • 其他要求 header / cookie 的反向代理

   对这类部署来说，HAPI 如果完全不能附加额外请求头，就很难接入现有安全体系。

4. 更适合高风险环境的自托管
   有些场景下，用户希望：

   • 人工网页登录走交互式鉴权
   • 机器访问走 service token / gateway auth
   • 应用内部仍保留原有 token 校验

   这种“入口网关 + 应用自身认证”的双层设计，在实际部署里是有明确安全价值的。

目前的实际问题是：
CLI -> hub 既包含普通 HTTP 请求，也包含 Socket.IO 连接。如果没有一个统一的方式为这两类请求附加额外 header，那么把 HAPI 放在鉴权网关之后会比较困难。

所以这里更希望 upstream 提供的是一个通用能力，例如允许通过环境变量配置额外 outbound headers，而不是为某一个具体供应商写死专用逻辑。这样：

• 默认行为不变
• 不影响现有用户
• 但自托管用户可以把 HAPI 安全地放到额外的鉴权网关之后

如果希望先控制范围，我认为第一步只支持：

• env only
• outbound CLI -> hub only
• 同时覆盖 REST + Socket.IO

就已经可以覆盖大部分“增加一层鉴权网关”的安全需求了。