autotel-devtools 7.0.0 → 8.1.0

package/README.md

@@ -149,12 +149,29 @@ process — point them at the bound port, or free the original.
 - ✅ Error aggregation and grouping
 - ✅ Service map visualization
 - ✅ Resources view (derived from telemetry)
+- ✅ GenAI run summaries + narrated walkthrough
 - ✅ Search with debounce (300ms)
 - ✅ Configurable telemetry limits (env vars)
 - ✅ Widget position persistence (localStorage)
 - ✅ Export traces as JSON
 - ✅ Custom element support (`<autotel-devtools>`)
 
+### GenAI: read an agent run at a glance
+
+When your app emits OpenTelemetry GenAI spans (Vercel AI SDK, Pydantic AI, OpenAI
+Agents, Anthropic, Google GenAI, LangChain, …), the **GenAI** tab gives two extras
+on top of the per-span detail:
+
+- A **run summary strip** sits above the detail for any multi-span run — total
+  cost (table-priced; a trailing `+` marks a lower bound when some calls are
+  unpriced), input→output tokens, reasoning tokens, model calls, tool
+  executions, sub-agents, duration and errors.
+- An **Explain run** button steps through the run in chronological order with
+  plain-language narration of each step. Auto-play or step manually with the
+  arrow keys / Space (Esc exits); clicking a span jumps the tour to that step.
+  Useful for showing a teammate or a client exactly what the agent did, which
+  tools it called, and where the cost went.
+
 ## Configuration
 
 ### Environment Variables
@@ -240,6 +257,26 @@ await expect
   .toBeGreaterThan(0);
 ```
 
+These read-back calls run from Node (no `Origin` header), so they are unaffected
+by the origin guard below.
+
+## Read-surface origin guard
+
+OTLP **ingestion** (`POST /v1/{traces,logs,metrics}`), `GET /widget.js` and
+`GET /healthz` are open to any origin — browser apps on arbitrary dev origins
+must be able to send telemetry and load the embeddable widget. The **read**
+surface is not: `GET /v1/traces`, `DELETE /v1/traces` and the `/ws` WebSocket are
+origin-checked so a web page you happen to be visiting can't `fetch()` or stream
+your locally captured prompts, responses and tokens.
+
+- A non-loopback `Origin` (a cross-origin browser read) is rejected with `403`.
+- When bound to a loopback host (the default), a non-loopback `Host` (DNS
+  rebinding) is also rejected. `--host 0.0.0.0` opts into network exposure and
+  applies only the `Origin` check.
+
+The embedded widget keeps working — it connects from a loopback origin
+(`http://localhost:<your-app-port>`). Server-side reads with no `Origin` pass.
+
 ## License
 
 MIT

package/dist/cli.cjs

@@ -353,6 +353,40 @@ function appendManyWithLimit(items, incoming, limit) {
   return next.length > limit ? next.slice(next.length - limit) : next;
 }
 
+// src/server/origin-guard.ts
+var LOOPBACK_IPV6 = /* @__PURE__ */ new Set(["::1", "0:0:0:0:0:0:0:1"]);
+function isLoopbackHostname(hostname) {
+  const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  return h === "localhost" || /^127\./.test(h) || LOOPBACK_IPV6.has(h);
+}
+function hostnameFromHostHeader(host) {
+  const h = host.trim();
+  if (h.startsWith("[")) {
+    const end = h.indexOf("]");
+    return end > 0 ? h.slice(1, end) : h;
+  }
+  const colon = h.indexOf(":");
+  return colon === -1 ? h : h.slice(0, colon);
+}
+function hostHeaderIsLoopback(host) {
+  return isLoopbackHostname(hostnameFromHostHeader(host));
+}
+function originIsLoopback(origin) {
+  try {
+    return isLoopbackHostname(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+function allowSensitiveRequest(headers, loopbackOnly) {
+  const { origin, host } = headers;
+  if (origin && origin.length > 0 && !originIsLoopback(origin)) return false;
+  if (loopbackOnly && host && host.length > 0 && !hostHeaderIsLoopback(host)) {
+    return false;
+  }
+  return true;
+}
+
 // src/server/server.ts
 var DevtoolsServer = class {
   wss;
@@ -372,7 +406,12 @@ var DevtoolsServer = class {
     this._port = options.port ?? 4318;
     this.onData = options.onData;
     this.httpServer = options.server ?? http.createServer();
-    this.wss = new ws.WebSocketServer({ server: this.httpServer, path: options.path ?? "/ws" });
+    const loopbackOnly = options.host == null || hostHeaderIsLoopback(options.host);
+    this.wss = new ws.WebSocketServer({
+      server: this.httpServer,
+      path: options.path ?? "/ws",
+      verifyClient: ({ origin, req }) => allowSensitiveRequest({ origin, host: req.headers.host }, loopbackOnly)
+    });
     this.wss.on("error", (err) => {
       if (this.httpServer.listening) throw err;
     });
@@ -1011,7 +1050,8 @@ function getWidgetJs() {
   }
   return cachedWidgetJs;
 }
-function attachDevtoolsRoutes(httpServer, devtools) {
+function attachDevtoolsRoutes(httpServer, devtools, options = {}) {
+  const loopbackOnly = options.loopbackOnly ?? true;
   httpServer.on("request", async (req, res) => {
     res.setHeader("Access-Control-Allow-Origin", "*");
     res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
@@ -1045,11 +1085,19 @@ function attachDevtoolsRoutes(httpServer, devtools) {
       return;
     }
     if (req.method === "GET" && url === "/v1/traces") {
+      if (!allowSensitiveRequest(req.headers, loopbackOnly)) {
+        sendJson(res, 403, { error: "Forbidden" });
+        return;
+      }
       const data = devtools.getCurrentData();
       sendJson(res, 200, { traces: data.traces, count: data.traces.length });
       return;
     }
     if (req.method === "DELETE" && url === "/v1/traces") {
+      if (!allowSensitiveRequest(req.headers, loopbackOnly)) {
+        sendJson(res, 403, { error: "Forbidden" });
+        return;
+      }
       devtools.clearData();
       sendJson(res, 200, { cleared: true });
       return;
@@ -1290,13 +1338,14 @@ async function main() {
     process.exit(0);
   }
   const httpServer = http.createServer();
-  const wsServer = new DevtoolsServer({ server: httpServer, verbose: true });
-  attachDevtoolsRoutes(httpServer, wsServer);
+  const loopbackOnly = hostHeaderIsLoopback(options.host);
+  const wsServer = new DevtoolsServer({ server: httpServer, host: options.host, verbose: true });
+  attachDevtoolsRoutes(httpServer, wsServer, { loopbackOnly });
   const listeners = listenLoopbackDualStack({
     primary: httpServer,
     port: options.port,
     host: options.host,
-    attachSecondary: (s) => attachDevtoolsRoutes(s, wsServer)
+    attachSecondary: (s) => attachDevtoolsRoutes(s, wsServer, { loopbackOnly })
   });
   const { addresses, warnings, port: boundPort } = await listeners.ready;
   if (boundPort !== options.port) {