bugfix: error handlers, timeouts, global guards (audit Group D)

Five bug fixes in health-server.js from the comprehensive audit:

- D1 upstream.on('error'): every piped upstream IncomingMessage
(proxyRequest body + non-body paths, proxyDashboard non-rewrite path)
now has an error listener. An unhandled 'error' on a piped stream
throws and can crash the router — a backend socket reset mid-response
would take down every fronted service.
- D2 headersSent guards: the proxyRequest non-body error handler and
the proxyDashboard ClientRequest + upRes error handlers called
res.writeHead() unconditionally. If the response callback already
fired and is streaming, that throws ERR_HTTP_HEADERS_SENT inside the
error handler → unhandled exception. Now guarded; late errors call
res.destroy() instead.
- D3 upstream timeouts: 30s setTimeout on every proxied request
(proxyRequest body + non-body, proxyDashboard). A hung backend that
accepts the socket but never responds previously held the request +
upstream socket open indefinitely, exhausting FDs under load. Now
returns 504 + destroys the socket.
- D4 global guards: process.on('uncaughtException'/'unhandledRejection')
+ server.on('error') log and continue instead of crashing the router
on a single bad request. Last-resort backstop for any stream error
we missed an 'error' listener on.
- D5 referer routing comment: the refererIsDashboard routing is
client-controlled (Referer is spoofable), so document that it's a
functional routing hint, not a privilege boundary — the block calls
requireAuth() before proxying, so a spoofed Referer grants nothing.

health-server.js

@@ -436,12 +436,34 @@ function proxyRequest(
         (upstream) => {
           res.writeHead(upstream.statusCode || 502, upstream.headers);
           upstream.pipe(res);
+          // D1: handle mid-response backend socket errors without crashing.
+          upstream.on("error", () => {
+            if (!res.headersSent) {
+              try {
+                res.writeHead(502, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: "upstream_error" }));
+              } catch {}
+            } else {
+              try { res.destroy(); } catch {}
+            }
+          });
         },
       );
+      // D3: 30s timeout on the upstream request.
+      proxy.setTimeout(30000, () => {
+        if (!res.headersSent) {
+          res.writeHead(504, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "upstream_timeout" }));
+        }
+        try { proxy.destroy(new Error("upstream_timeout")); } catch {}
+      });
+      // D2: guard headersSent on the proxy error handler.
       proxy.on("error", (error) => {
         if (!res.headersSent) {
           res.writeHead(502, { "content-type": "application/json" });
           res.end(JSON.stringify({ error: "proxy_error", message: error.message }));
+        } else {
+          try { res.destroy(); } catch {}
         }
       });
       if (size > 0) proxy.write(Buffer.concat(chunks));
@@ -468,12 +490,42 @@ function proxyRequest(
     (upstream) => {
       res.writeHead(upstream.statusCode || 502, upstream.headers);
       upstream.pipe(res);
+      // D1: an unhandled 'error' on a piped IncomingMessage throws and can
+      // crash the router. If the backend socket resets mid-response, log +
+      // destroy the response cleanly instead of taking down every fronted
+      // service.
+      upstream.on("error", () => {
+        if (!res.headersSent) {
+          try {
+            res.writeHead(502, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "upstream_error" }));
+          } catch {}
+        } else {
+          try { res.destroy(); } catch {}
+        }
+      });
     },
   );
 
+  // D3: 30s timeout so a hung backend (accepts the socket but never
+  // responds) can't hold a request + upstream socket open forever.
+  proxy.setTimeout(30000, () => {
+    if (!res.headersSent) {
+      res.writeHead(504, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "upstream_timeout" }));
+    }
+    try { proxy.destroy(new Error("upstream_timeout")); } catch {}
+  });
+
+  // D2: guard headersSent so a late 'error' after headers were already
+  // written doesn't throw ERR_HTTP_HEADERS_SENT inside the error handler.
   proxy.on("error", (error) => {
-    res.writeHead(502, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: "proxy_error", message: error.message }));
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "proxy_error", message: error.message }));
+    } else {
+      try { res.destroy(); } catch {}
+    }
   });
 
   req.pipe(proxy);
@@ -541,6 +593,18 @@ function proxyDashboard(req, res) {
       if (!shouldRewrite) {
         res.writeHead(upRes.statusCode || 502, upRes.headers);
         upRes.pipe(res);
+        // D1: handle mid-response backend socket errors on the non-rewrite
+        // path (the rewrite path has its own upRes.on('error') below).
+        upRes.on("error", () => {
+          if (!res.headersSent) {
+            try {
+              res.writeHead(502, { "content-type": "application/json" });
+              res.end(JSON.stringify({ error: "upstream_error" }));
+            } catch {}
+          } else {
+            try { res.destroy(); } catch {}
+          }
+        });
         return;
       }
 
@@ -581,17 +645,40 @@ function proxyDashboard(req, res) {
         res.end(buf);
       });
       upRes.on("error", () => {
-        try {
-          res.writeHead(502);
-          res.end();
-        } catch {}
+        // D2: guard headersSent — in the rewrite path, res.writeHead may
+        // already have fired (it fires in the 'end' handler). The old code
+        // called writeHead unconditionally → ERR_HTTP_HEADERS_SENT.
+        if (!res.headersSent) {
+          try {
+            res.writeHead(502);
+            res.end();
+          } catch {}
+        } else {
+          try { res.destroy(); } catch {}
+        }
       });
     },
   );
 
+  // D3: 30s timeout on the dashboard upstream request.
+  upstream.setTimeout(30000, () => {
+    if (!res.headersSent) {
+      res.writeHead(504, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "upstream_timeout" }));
+    }
+    try { upstream.destroy(new Error("upstream_timeout")); } catch {}
+  });
+
+  // D2: guard headersSent on the ClientRequest error handler. The old code
+  // called writeHead unconditionally, which throws if the response callback
+  // already fired and is streaming.
   upstream.on("error", (error) => {
-    res.writeHead(502, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: "proxy_error", message: error.message }));
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "proxy_error", message: error.message }));
+    } else {
+      try { res.destroy(); } catch {}
+    }
   });
 
   // Buffer body before forwarding — same chunked-encoding fix as proxyRequest.
@@ -1228,6 +1315,11 @@ except Exception:
   })();
   const refererIsDashboard = refererPath.startsWith(`${HM_PREFIX}/app`);
 
+  // NOTE: Referer is client-controlled, so a caller who sets Referer: /hm/app
+  // can route requests that would otherwise go to WebUI (e.g. /api/*) to the
+  // dashboard. This is functional routing, not a privilege boundary — the
+  // block below calls requireAuth() before proxying to the dashboard, so a
+  // spoofed Referer doesn't grant any access the caller didn't already have.
   if (refererIsDashboard) {
     // Anything with a Referer from the dashboard goes to the dashboard,
     // *except* requests that explicitly start with /webui (escape hatch).
@@ -1306,6 +1398,20 @@ server.listen(PORT, "0.0.0.0", () => {
   console.log(`HuggingMes + Hermes WebUI router listening on 0.0.0.0:${PORT}`);
 });
 
+// D4: last-resort guards so one bad request/response can't crash the
+// router and take down every fronted service. An unhandled stream error
+// (e.g. a backend socket reset on a response we forgot to attach an
+// 'error' listener to) would otherwise throw and terminate the process.
+process.on("uncaughtException", (err) => {
+  console.error("uncaughtException in router (continuing):", err && err.stack ? err.stack : err);
+});
+process.on("unhandledRejection", (err) => {
+  console.error("unhandledRejection in router (continuing):", err);
+});
+server.on("error", (err) => {
+  console.error("router server error:", err && err.stack ? err.stack : err);
+});
+
 /* ── WebSocket upgrade handling ─────────────────────────────────────
  *
  * Both the Hermes dashboard and hermes-webui can open WebSocket