HTTP In、Response、Request 與 API 安全

先畫清楚 HTTP 的四個邊界

Add-on 22.0.1 內嵌 Node-RED 5.0.2。HTTP In 建立伺服端路由，HTTP Response 結束同一次請求；HTTP Request 是用戶端；HA WebSocket 套件的 API node 又是另一條具有 Home Assistant 權限的路徑。它們都叫 API，但信任來源、credentials 與失敗語意不同。

Add-on 宣告 host_network: true，代表容器的本機網路可達面較廣；這是能力 grant，不代表任何 Flow 已經連線。對外 HTTP、WebSocket、TCP 與 UDP 都必須固定允許目的地。先用第 18 章的有限測試策略驗證純資料邏輯，再考慮任何整合測試。

HTTP In 與 Response 是不可拆開的同一次交換

Node-RED 5.0.2 的 HTTP In 在收到請求後送出一個 message。GET 的 msg.payload 是 query object；POST、PUT、PATCH、DELETE 的 payload 是解析後的 request body（若選擇略過解析則是原始資料）。同一則訊息還有 msg.req 與 msg.res。HTTP Response 依靠 msg.res 才能回覆原連線，沒有它就只會警告沒有 response。

HTTP In 編輯器提供 GET、POST、PUT、DELETE、PATCH。POST 可啟用檔案上傳；POST、PUT、PATCH、DELETE 可選擇略過 body parsing。上傳使用記憶體儲存，因此大小與檔案數必須在 route 之前受限。Node-RED 的 JSON 與 URL-encoded parser 使用 apiMaxLength，未另設時核心值為 5mb；這只是 parser 上限，不是業務 payload 的合理上限，也不涵蓋所有 proxy 或 multipart 限制。

CSV、HTML、JSON、XML、YAML parser nodes 只能處理語法；不能替你判定欄位授權、資源成本或內容可信。外部 body 應先限制 bytes 與 content type，再解析，再驗證 shape。一般 message model 可回看第 5 章。

六步完成離線設計，不啟動任何 route

1. 寫出單一路由契約。

   在文字中固定一個 method、一個相對 path、允許的 content type、最大 bytes、必要欄位、成功 status、拒絕 status 與 timeout。路徑只使用 /PLACEHOLDER_HTTP_PATH，不填真實 host 或秘密。

2. 畫出所有 terminal paths。

   從 HTTP In 追蹤正常、缺欄、錯型別、未授權、內部錯誤與逾時分支；每條都必須到一個 HTTP Response。禁止把 live msg.req／msg.res 放進 Delay、Context 或等待外部事件的無界路徑。

3. 離線讀取安全範例。

   本章練習只讀：開啟 12-http-endpoint.json，確認共 4 個 nodes、HTTP In 和 HTTP Response 都是 d:true，路徑是完整 placeholder，不 Import、不 Deploy、不啟用，也不發送測試請求。README 的隔離匯入程序是另一項獨立作業，絕不代表已獲准部署或連線。

4. 檢查暴露與認證層。

   分開記錄 Ingress 與 direct host port；若 route 可能走 direct /endpoint/，必須規劃 http_node.username/password 或受控反向代理。這組 Basic Auth 不等於細粒度 authorization。

5. 檢查 outbound 設計。

   離線讀取 13-outbound-http-request.json；確認 URL 是 PLACEHOLDER_HTTPS_URL、HTTP Request 為 d:true、沒有 auth、TLS 或 proxy config reference，Inject 也不會在啟動時執行。

6. 以表格完成失敗驗收。

   逐列寫出預期 status、最小 body、允許的 headers、外部 timeout 與停止條件。網路及 HA 節點仍須停用，值只用 placeholder；真正啟用須走本章之外的變更程序。

離線契約範本（不是可執行設定）
method: PLACEHOLDER_METHOD
path: /PLACEHOLDER_HTTP_PATH
request content type: PLACEHOLDER_MEDIA_TYPE
request max bytes: PLACEHOLDER_LIMIT
success: PLACEHOLDER_STATUS + 固定 shape
reject: PLACEHOLDER_STATUS + 不含內部細節
external I/O: 禁止執行

章末離線驗收

/endpoint、Ingress 與 direct port 是三個不同概念

Add-on wrapper 固定 Node-RED backend 為 127.0.0.1:46836，userDir=/config/、nodesDir=/config/nodes、flowFile=flows.json，並把 httpNodeRoot 設成 /endpoint。所以 HTTP In 內填 /PLACEHOLDER_HTTP_PATH 時，Add-on 路徑根是 /endpoint/PLACEHOLDER_HTTP_PATH。不要在節點 path 再重複填入 /endpoint。

http_node.username/password 設定存在 username 時，wrapper 用 bundled [email protected] 對 password 建 hash，交給 Node-RED httpNodeAuth。bcryptjs 是 wrapper 支援 library，不是 Palette node。Basic Auth 只回答「是否持有共同 credentials」；若不同使用者只能存取不同資源，Flow 還要使用可信身分來源做 authorization，且錯誤回應不可暴露判斷細節。

每條分支都回應，而且只回應一次

Switch 的每個 output、Catch 的每個有限錯誤分支、驗證失敗與正常分支都要到 HTTP Response。若分支丟棄訊息，caller 會一直等待到 upstream proxy 或 client timeout；若兩條分支都回覆同一個 msg.res，則會造成重複送出。安全結構是先建立固定 error envelope，再在單一回應匯合點設定受控 msg.statusCode 與 headers。

// 純資料示意；不得接到已啟用 HTTP In
// 前提：上游仍保留原本 live msg.res
const value = msg.payload && msg.payload.value;
if (typeof value !== "string" || value.length < 1 || value.length > 64) {
    msg.statusCode = 400;
    msg.payload = { code: "INVALID_INPUT" };
    return msg;
}
msg.statusCode = 200;
msg.payload = { accepted: true };
return msg;

這段只示範 shape guard，不處理身分或實際 route。HTTP Response 若節點本身固定 status，固定值優先；否則讀 msg.statusCode，最後才是 200。非 Buffer 的 object payload 一律呼叫 Express res.jsonp(msg.payload)，因此 query 中的 JSONP callback 可能改變 response envelope。若契約要求不變的 JSON，必須把 callback query name 保留給安全檢查並拒絕 caller 提供該參數；另一做法是先序列化可信 JSON，再設定固定 JSON content type，避免走 object 的 JSONP 語意。

HTTP Request：固定 HTTPS 目的地，不讓 message 決定網路

HTTP Request 5.0.2 的編輯欄位包含 Method（GET、POST、PUT、DELETE、HEAD 或由 msg.method 指定）、URL、GET payload 處理方式、TLS config、Basic／Digest／Bearer 三種 credentials、keep-alive、HTTP proxy config、錯誤輸出、insecure HTTP parser、回傳型別與 headers。節點 URL 若包含 Mustache 標記，runtime 會以整則 message render；所以看似寫在節點內也不代表固定。範例只使用完整、沒有 {{...}} 的 non-templated placeholder URL，正式目的地則必須另經核准。

除了 node 設定，runtime 還會消費 msg.headers、msg.cookies、msg.followRedirects，以及 method、URL、timeout 控制 msg.method、msg.url、msg.requestTimeout；未選 TLS config 時還會消費 msg.rejectUnauthorized。因此緊接節點前要建立只含核准 payload、必要 header 與固定控制值的全新 allowlisted message，不能把 HTTP In、Dashboard 或 MQTT message 原樣傳入，也不能只刪一兩個已知欄位。

核心 runtime 的 HTTP Request timeout 未另設 httpRequestTimeout 時為 120000 ms，也可由正數 msg.requestTimeout 覆寫；程式另設最多 21 次 redirects。這些是 5.0.2 行為，不是所有服務都適合的政策。對每個目的地應設定更窄且有理由的 timeout，並在上游限制重試次數與總期限。Redirect 應停用，或由 egress proxy／upstream 同時執行目的 host allowlist 與 response-size 上限；不要用無限重試補救 timeout。

核心會先把完整 response buffer 放入記憶體；選 parsed JSON 時，還會先執行 JSON.parse，之後才輸出 message。HTTP Request 本身沒有每次 response-byte limit 或 redirect-host allowlist，所以節點後才檢查 msg.responseUrl、content type 或 body 大小，無法阻止已發生的 SSRF、跨 host redirect 或記憶體耗盡。成功輸出仍應白名單處理 msg.statusCode、msg.headers、msg.responseUrl、msg.payload、msg.redirectList 與可能的 msg.responseCookies，但這只保護下游資料使用；不要把 headers/cookies 原樣接回 HTTP Response，也不要完整 Debug。

method、path、body、headers 要分層驗證

「HTTP In 已選 POST」只完成 router 層 method 比對。完整驗證至少有傳輸層、語法層、shape 層、授權層與業務層；任何一層失敗都回傳有限、穩定的錯誤，不附 stack、token、內部 host 或原始 body。

CORS 不是 authentication。Node-RED 可透過全域 httpNodeCors 設定為 HTTP nodes 增加 CORS middleware，並對 OPTIONS 設定處理；HTTP In 節點 dialog 沒有逐 route CORS 欄位。只允許明確 origin、method 與 headers，不使用寬鬆 wildcard 搭配 credentials。瀏覽器同源政策也不會阻止非瀏覽器 client。

反向代理要限制 request body、header bytes、連線數與 upstream timeout，並只信任代理自己覆寫的 forwarding headers。TLS 終止在哪一層、proxy 到 backend 是否仍受保護、client IP 如何取得都要記錄。Add-on direct TLS 只涵蓋 direct listener；Ingress 與外部 proxy 是不同 TLS session。

有限錯誤模型

400 INVALID_INPUT    欄位或型別不合契約
401 AUTH_REQUIRED    缺少或無效 authentication
403 NOT_ALLOWED      身分有效但沒有該資源權限
404 NOT_FOUND        不揭露不存在或不可見資源細節
413 BODY_TOO_LARGE   在解析前拒絕超過上限
415 MEDIA_TYPE       不支援的 Content-Type
429 RATE_LIMITED     有界速率限制；不含內部計數細節
500 INTERNAL_ERROR   固定最小 body；詳細原因只進受控 log
504 UPSTREAM_TIMEOUT outbound 期限已到；不無限重試

HA API node 是進階權限入口，不是一般 HTTP 捷徑

HA WebSocket 0.80.3 註冊的 persisted type 是 ha-api。它可選 WebSocket 或 HTTP；HTTP method 為 GET、POST、PUT、DELETE，path 會移除開頭的 /api/ 再交給既有 HA server config。WebSocket data 必須包含 type。Data 可用 JSON／JSONata；輸出位置與型別也可自訂。這些動態能力讓一個 node 能跨越多種 HA API，不等於呼叫都只讀。

若已有明確用途的 Current State、Get Entities 或 Action node，優先使用語意更窄的節點；Action 的 target 與 data 邊界見第 11 章。API node 只適合沒有專用 node 且已確定 HA API 契約的進階案例。本章不提供可執行 HA API flow、method、path 或 data，也不指示啟用任何 node。

ha-webhook 是 HA 事件入口，不是 Node-RED HTTP In 的別名。Webhook URL／ID 是敏感入口值，不得出現在截圖、flow export 或一般 log；外部來源、重放、payload 大小與後續副作用仍要限制。其他 WebSocket、TCP、UDP nodes 有各自的 config 與 framing 語意，不能套用 HTTP Response 配對模型。

更完整的 credentials、proxy、TLS、host network 與 least privilege 維運界線見第 21 章。發生 timeout、記憶體或連線問題時，依第 22 章收集有限資料，不要先打開完整 Debug。

故障排除

• HTTP In 有訊息，但 caller 一直等待：逐條追蹤 Switch、驗證拒絕、Catch 與正常路徑是否都保留原 msg.res 並抵達 HTTP Response。不要以 Delay 拉長等待；先保持 route 停用，在純資料副本驗證 terminal path。
• HTTP Response 顯示沒有 response：這則 msg 不是來自同一次 HTTP In，或途中重建 message 遺失 msg.res。不要自己仿造 msg.res；改為保留原 message，只覆寫受控欄位。
• Ingress 可開啟，direct endpoint 卻是 401／不可達：兩者是不同 listener 與認證邊界。檢查 host port 是否映射、direct TLS 與 http_node 設定；不要為排錯啟用 leave_front_door_open。
• endpoint 可達但沒有要求 editor 登入：direct NGINX 對 /endpoint/ 本來就不走 editor 的 Supervisor auth。設定 endpoint 專用認證與 authorization，不要把網路位置當成存取控制。
• HTTP Request timeout 或反覆 redirect：保持節點停用，檢查 placeholder 是否尚未替換、DNS、proxy、TLS chain、最終 host、有限 request timeout 與 redirect policy。不要關閉 certificate validation 或設無限重試。
• parsed JSON 看似成功但後續出錯：JSON parser 只保證語法。增加必要欄位、型別、範圍、深度、array 長度與未知欄位拒絕；錯誤路徑仍要回應。
• CORS 錯誤只在瀏覽器出現：確認 origin、preflight method/headers 與 proxy 回應；不要用 wildcard 加 credentials，也不要把通過 CORS 當成已 authentication。
• HA API node 顯示 requires path/type：這是進階 node 的輸入契約錯誤。不要從外部 payload 臨時補值；保持停用，回到固定 HTTP path 或 WebSocket type 的白名單設計。

固定版本來源與官方文件

本章以 exact commits 判定 Add-on 路由與 Node-RED／HA nodes 行為；rolling 文件只作一般使用說明。固定來源沒有證明的 proxy 或環境政策，本章不作推論。

• Home Assistant Community App: Node-RED 22.0.1 固定提交：/endpoint、direct／Ingress NGINX、host port、http_node、http_static 與 bundled bcryptjs。
• Node-RED 5.0.2 固定提交：HTTP In／Response／Request、HTTP Proxy、TLS、parser nodes、live objects、CORS 與其他 network nodes。
• HA WebSocket nodes 0.80.3 固定提交：ha-api 與 ha-webhook 的註冊及輸入契約。
• Node-RED 官方文件：Core nodes。
• Node-RED 官方文件：Messages。
• Node-RED 官方文件：Securing Node-RED。
• Add-on 官方文件（固定提交）。
• 本站停用範例：12-http-endpoint.json 與 13-outbound-http-request.json；請先讀安全範例說明。

常見問題