[fengzai6]

Summary

工作流新增 External API 触发器，让外部系统可以通过独立端点和节点专属 key 投递 JSON 来启动运行。实现覆盖凭据的创建、读取、轮换与退役，以及入站鉴权、输入契约校验、幂等、审计和编辑器管理入口。

触发器保存时把节点声明的 inputSchema 投影为冻结的 workflow inputs，使入站校验与下游 {{input.*}} 使用同一份契约。请求只接受符合声明的 JSON 对象；Idempotency-Key 可选，携带时按 activation 隔离并并发安全地去重。端点退役、节点移除或工作流删除后，旧 key 立即失效且密文不会继续保留。

Related

Closes #2137

Changes

• 新增 trigger.external 节点、实例内唯一的 slug 与节点级 key，以及独立的匿名运行端点。
• 支持 Authorization: Bearer、X-Api-Key 和查询参数三种 key 形态，统一做定时安全摘要比较。
• 对声明支持的 JSON Schema 子集执行严格入站校验，包括 required、properties、additionalProperties: false、enum、maxLength、数组 items、整数语义与类型联合。
• 支持可选 Idempotency-Key，按 trigger activation 隔离，缺失时不自动按 body 去重。
• 新增受 workflows.write 门控的 key reveal、rotate、rename 管理接口，以及供检查器读取 live slug 的公开元数据接口。
• 工作流保存时同步触发器存储；节点移除、替换或工作流删除会软删触发行并清空 key 密文，保留 digest 审计信息。
• 编辑器新增 External API 配置、输入字段编辑、并发确认的 key 轮换/端点改名、规范化端点展示与受控 reveal。
• 将外部端点接入既有匿名 ingress 限流，分区为 slug|remoteIp。
• 补充校验器对 type: [...] 联合类型的支持，并让空类型约束返回可定位的错误。

Risk / Impact

• 匿名 ingress 的实际授权边界是节点 key；持有 workflows.write 的团队成员可以读取该团队外部触发器的明文 key。
• slug 在实例内唯一；显式改名会使旧 URL 立即失效。config.slug 只是草稿，保存工作流不会隐式改名。
• key 轮换没有宽限期，旧 key 立即失效。
• 退役触发行保留 digest、slug 与审计字段，但清空 key_ciphertext。
• 入站 JSON Schema 校验只覆盖当前声明的关键词子集；工作流引擎自身仍不统一执行 input schema 校验。

Test plan

自动化

• External trigger payload validator 单测通过：26 通过，0 失败。
• External trigger HTTP E2E 测试通过：32 通过，0 失败。
• External trigger 管理集成测试通过：36 通过，0 失败。
• External trigger ingress 集成测试覆盖错误或缺失 key、非法 payload、不可用端点、受理拒绝、幂等重投和并发去重。
• 前端检查器测试覆盖线上端点发现、key reveal 与轮换确认、端点改名、复制行为、非法草稿 slug 和管理错误态。

手工验证

• 真实企业微信 webhook 调用到达下游 HTTP Request 节点，并在 Terminal 完成，返回 errcode: 0。
• 浏览器验证 External API 触发器的字符串、对象、数组、null、布尔和数值字段都能传到下游节点。

[ppXD]

感謝這個 PR 的細緻工作。key 的處理、tenancy、資料庫層的冪等保證和測試深度都很扎實；重用 IRunStarter / RunSourceEnvelope / ActivationAuthoritySnapshot 也是正確的選擇。

這次標成 Request changes，原因有兩個：

• 有幾項屬於對外公開的契約。一旦有外部呼叫方接入，就再也收不回來。
• 匿名入口有幾處防線比現有的 webhook 和 callback 路徑弱。

合併前：對外契約（現在改成本低，之後改不了）

• ?key= 查詢參數形式的憑證
  • 位置：ExternalTriggersController.cs:32,40；編輯器範例在 external-trigger-inspector.tsx:47。
  • 問題：#2113 的日誌遮罩只涵蓋名為 token 的路徑參數，?key= 不在範圍內。任何一行帶 ?key= 的 access log，都等於一個長期有效的觸發能力。
  • 修法：只接受 Authorization: Bearer 與 X-Api-Key，curl 範例也一併改掉。
• endpoint 身分
  • 問題：目前是人工命名、全域唯一、可改名的 slug，加上單一 key 欄位。實際後果：
    • 跨 team 建立同名 slug 會回 409，形成存在性 oracle；
    • 401 與 404 的差異讓 endpoint 可被列舉；
    • 改名會讓既有呼叫方立即失效；
    • rotate 沒有重疊期。
  • 修法：URL 改用不可猜的 opaque public id，並在路由加上長度限制；名稱降為可自由修改的 label。憑證改成 current/previous 兩個 slot，並帶到期時間。
• 拒絕語意
  • 問題：authority 被拒與 completion admission 被拒都回 202 {runId:null}。稽核的 DedupKey 是 rejected:{slug}:{idempotencyKey}：不帶 Idempotency-Key 時只留一筆就失明，帶了則每次投遞都新增一筆、無上限。
  • 修法：對已通過驗證的呼叫方回傳穩定的非 2xx 錯誤碼。稽核列改用 (endpoint, reason, day) 為鍵，與 PullRequestTriggerAdmission 的做法一致。
• 冪等範圍
  • 問題：範圍綁在 activation.Id，而 ReplaceActivationsAsync 每次存檔都會重建 activation。所以「投遞、存檔、再投遞同一個 key」會產生第二個 run。
  • 修法：改以 trigger 列 id 為範圍，並存 body hash；同一個 key 搭配不同 body 時回 422。
• 路由遮蔽
  • 問題：新增的 GET /api/workflows/external-triggers 會遮蔽 slug 剛好為 external-triggers 的既有 workflow，而這個名稱不在 ReservedSlugs（WorkflowService.cs:2236）裡。
  • 修法：改成以 id 為鍵的子路由；或者把它加入保留字，並為既有資料重新產生 slug。

合併前：匿名入口加固

• 先讀 body 才驗證
  • 問題：controller 在查 slug、驗 key 之前，就先讀入最多 25 MiB 的 body（MaxDeliveryBodyBytes，ExternalTriggersController.cs:34）。實測對不存在的 slug 送一個 24 MiB、未帶憑證的 POST，配置了約 177–341 MiB。對照之下，不存在的 webhook id 會先回 404，配置不到 1 MiB。
  • 修法：先解析 slug、驗證 key，再用每個 trigger 自己的小上限讀 body。
• 比對 key 前做了太多工作
  • 問題：ExternalTriggerIngress.cs:36-63 在比對 key 之前，先做了 3 次查詢並反序列化整份 definition。
  • 修法：查到 slug 列後立即比對 digest；不存在的 slug 與錯誤的 key 回應要一致。input schema 存到 trigger 列上，不要每次請求都解析整份定義。
• 限流
  • 問題：{slug} 沒有長度限制，partition key 的大小由攻擊者決定。失敗的認證也會消耗合法呼叫方的額度：打 2000 次錯 key 之後，真 key 會拿到 429。
  • 修法：失敗只計入位址桶；429 回應補上 Retry-After。
• 輸入校驗器沒有上限
  • 問題：ExternalTriggerPayloadValidator 不設上限。3.8 MiB 的 1, 會產生約 200 萬筆錯誤、配置約 0.8 GiB；超長的整數指數會走進 BigInteger.Parse，耗掉數秒 CPU。另外 pattern、minimum、oneOf、$ref，甚至拼錯的 type，目前都被靜默接受。
  • 修法：錯誤數設上限（約 20 筆），不回顯原值；拒絕超長的數字 token；存檔時拒絕不支援的 schema 關鍵字。
• jsonb 存不下的合法 JSON 會回 500
  • 問題：\u0000、孤立 surrogate、1e200000 都能通過解析，但存進 jsonb 時失敗，回 500。
  • 修法：在入口直接回 400。
• 沒有 per-trigger 的 run 速率或併發上限
  • 問題：一把外洩的 key，每分鐘可以用發布者的 authority 起約 2000 個 run。
  • 修法：在 RunStarter 之前加一個 admission 步驟，使用 committed 預設值。

後續 PR

• 分層與規範：Rule 16/18.1：Reveal 與 List handler 直接注入 CodeSpaceDbContext；Core 的 outcome 型別重複了 Messages 的 DTO，還需要一個 mapper。Rule 3/4：拆分 ReceiveAsync（約 90 行）。Rule 1：建構子參數過多。
• reveal、rotate、rename：reveal 改成 POST，並加 Cache-Control: private, no-store。rotate、rename 要寫稽核 log，並加上並行控制。
• 三份真相：node、前端派生的 activation、trigger 列三者各自存在。透過 API 建立、卻沒有 activation 列的 workflow 會永遠 404。改用 node-save hook，也能解除 WorkflowService 對 trigger.external 的耦合。
• payload 的信任邊界：發送端的 payload 原樣存入，Viewer 可讀。可考慮對選定欄位 seal、設定 SourceInstanceId / ExternalEventId，並在 goal template 中把這些內容標記為不受信任。
• 測試：補上 payload → run → engine 的端到端覆蓋，以及真 HTTP 的並行同 key、投遞／存檔／再投遞、/api/ext 的 429 情境。本機 mutation 測試中，E2E 層 15 個 mutant 一個都沒殺掉。

長期方向

改成以 registry 為基礎的 inbound endpoint：authenticator、body decoder、admission、responder 各自是 sibling interface，做法與既有的 webhook verifier/normalizer registry 相同。這樣 HMAC 發送端和其他 body 形式就能直接接入，不用改 controller。這部分可以等上面的契約定案後再做。