npm - @agent-e/server - Versions diffs - 1.8.1 → 1.8.2 - Mend

@agent-e/server 1.8.1 → 1.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +54 -0
package/dist/AgentEServer-A7K6426K.mjs +7 -0
package/dist/{chunk-ALGME445.mjs → chunk-3HGNFK4A.mjs} +157 -52
package/dist/chunk-3HGNFK4A.mjs.map +1 -0
package/dist/cli.js +155 -50
package/dist/cli.js.map +1 -1
package/dist/cli.mjs +1 -1
package/dist/index.d.mts +2 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +165 -52
package/dist/index.js.map +1 -1
package/dist/index.mjs +2 -2
package/package.json +1 -1
package/dist/AgentEServer-KIQBHRUS.mjs +0 -7
package/dist/chunk-ALGME445.mjs.map +0 -1
/package/dist/{AgentEServer-KIQBHRUS.mjs.map → AgentEServer-A7K6426K.mjs.map} +0 -0

package/README.md CHANGED Viewed

@@ -232,6 +232,60 @@ Connect to the same port via WebSocket upgrade.
 Heartbeat: Server pings every 30 seconds.
+## Authentication
+Protect mutation routes and the dashboard with an API key:
+```ts
+const server = new AgentEServer({
+  apiKey: process.env.AGENTE_API_KEY,
+});
+```
+When `apiKey` is set:
+- **POST routes** (`/tick`, `/config`, `/approve`, `/reject`, `/diagnose`) require `Authorization: Bearer <key>`.
+- **Sensitive GET routes** (`/decisions`, `/metrics`, `/metrics/personas`, `/pending`) also require the header.
+- **Dashboard** (`GET /`) accepts either the `Authorization` header or a `?token=<key>` query parameter.
+- **WebSocket** accepts the key via `Authorization` header or `?token=<key>` on the upgrade request.
+- **Open routes** (`/health`, `/principles`) remain unauthenticated for health-check probes.
+All key comparisons use `crypto.timingSafeEqual()` to prevent timing side-channel attacks.
+## Security
+The server includes multiple layers of defense-in-depth:
+### Input Validation
+- **State validation** — all incoming economy state is validated before processing. Invalid state returns detailed errors with field paths.
+- **Event validation** — events are checked for required fields (`type`, `actor`, `timestamp`) and a valid `type` value before ingestion. Malformed events are silently dropped (HTTP) or return an error (WebSocket).
+- **Prototype pollution protection** — `__proto__`, `constructor`, and `prototype` keys are recursively stripped from all parsed JSON bodies.
+- **Body size limits** — HTTP request bodies are capped at 1 MB with a 30-second read timeout to mitigate slow-loris attacks.
+- **Array caps** — configuration arrays (lock/unlock/constrain) are capped at 1,000 entries.
+### Rate Limiting
+- **Per-connection** — each WebSocket connection is limited to one tick per 100 ms.
+- **Global** — a server-wide rate limiter caps ticks at 20/sec across all WebSocket connections to prevent CPU saturation.
+- **Connection limit** — maximum 50 concurrent WebSocket connections; excess connections are closed with code 1013.
+### Transport Security
+- **CORS** — configurable origin restriction via `corsOrigin` (default: `http://localhost:3100`). WebSocket connections from disallowed origins are closed with code 1008.
+- **HSTS** — `Strict-Transport-Security: max-age=31536000; includeSubDomains` header on all responses.
+- **Nonce-based CSP** — the dashboard uses a per-request cryptographic nonce for `script-src`, eliminating `'unsafe-inline'` scripts.
+- **SRI** — the CDN-loaded Chart.js library includes a `integrity` hash and `crossorigin="anonymous"` attribute.
+- **Security headers** — `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Cache-Control: no-cache, private` on all responses.
+### Concurrency
+- **Tick serialization** — `processTick()` uses a Promise-based mutex so concurrent HTTP + WebSocket ticks cannot corrupt shared adjustment queues.
+### Data Exposure
+- **metricsSnapshot stripping** — the `/decisions` endpoint strips full metrics snapshots from decision records to avoid leaking large internal state objects.
 ## State Validation
 All incoming state is validated before processing. Invalid state returns detailed errors with paths:

package/dist/AgentEServer-A7K6426K.mjs ADDED Viewed

@@ -0,0 +1,7 @@
+import {
+  AgentEServer
+} from "./chunk-3HGNFK4A.mjs";
+export {
+  AgentEServer
+};
+//# sourceMappingURL=AgentEServer-A7K6426K.mjs.map

package/dist/{chunk-ALGME445.mjs → chunk-3HGNFK4A.mjs} RENAMED Viewed

@@ -9,11 +9,12 @@ import {
 } from "@agent-e/core";
 // src/routes.ts
-import { timingSafeEqual } from "crypto";
+import { timingSafeEqual, randomBytes } from "crypto";
 import { validateEconomyState } from "@agent-e/core";
 // src/dashboard.ts
-function getDashboardHtml() {
+function getDashboardHtml(nonce) {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -23,7 +24,7 @@ function getDashboardHtml() {
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,400;14..32,500;14..32,600;14..32,700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
-<script src="https://cdn.jsdelivr.net/npm/chart.js@4.5.1/dist/chart.umd.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.5.1/dist/chart.umd.min.js" integrity="sha384-jb8JQMbMoBUzgWatfe6COACi2ljcDdZQ2OxczGA3bGNeWe+6DChMTBJemed7ZnvJ" crossorigin="anonymous"` + nonceAttr + `></script>
 <style>
   *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
@@ -844,7 +845,7 @@ function getDashboardHtml() {
 </main>
-<script>
+<script` + nonceAttr + `>
 (function() {
   'use strict';
@@ -891,6 +892,9 @@ function getDashboardHtml() {
   var $dashboardRoot = document.getElementById('dashboard-root');
   // -- Helpers --
+  // SECURITY-CRITICAL: esc() prevents XSS by escaping all HTML-significant characters.
+  // Every user-derived or WebSocket-derived value rendered via innerHTML MUST pass through esc().
+  // If adding new terminal renderers or DOM builders, always use esc() on dynamic data.
   function esc(s) { return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;').replace(/'/g,'&#39;').replace(/\\\\/g,'&#92;'); }
   function pad(n, w) { return String(n).padStart(w || 4, ' '); }
   function fmt(n) { return typeof n === 'number' ? n.toFixed(3) : '\\u2014'; }
@@ -1295,14 +1299,25 @@ function getDashboardHtml() {
   }
   // -- API calls --
+  // Read token from URL query param \u2014 never embed the API key in the HTML body.
+  var _authKey = new URLSearchParams(location.search).get('token');
+  function authHeaders() {
+    var h = {};
+    if (_authKey) h['Authorization'] = 'Bearer ' + _authKey;
+    return h;
+  }
   function fetchJSON(path) {
-    return fetch(path).then(function(r) { return r.json(); });
+    return fetch(path, { headers: authHeaders() }).then(function(r) { return r.json(); });
   }
   function postJSON(path, body) {
+    var h = authHeaders();
+    h['Content-Type'] = 'application/json';
     return fetch(path, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: h,
       body: JSON.stringify(body),
     }).then(function(r) { return r.json(); });
   }
@@ -1364,7 +1379,9 @@ function getDashboardHtml() {
   // -- WebSocket --
   function connectWS() {
     var proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
-    ws = new WebSocket(proto + '//' + location.host);
+    var wsUrl = proto + '//' + location.host;
+    if (_authKey) wsUrl += '?token=' + encodeURIComponent(_authKey);
+    ws = new WebSocket(wsUrl);
     ws.onopen = function() {
       reconnectDelay = 1000;
@@ -1514,11 +1531,30 @@ function getDashboardHtml() {
 </html>`;
 }
+// src/validation.ts
+var VALID_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "trade",
+  "mint",
+  "burn",
+  "transfer",
+  "produce",
+  "consume",
+  "role_change",
+  "enter",
+  "churn"
+]);
+function validateEvent(e) {
+  if (!e || typeof e !== "object") return false;
+  const ev = e;
+  return typeof ev["type"] === "string" && VALID_EVENT_TYPES.has(ev["type"]) && typeof ev["timestamp"] === "number" && typeof ev["actor"] === "string";
+}
 // src/routes.ts
 function setSecurityHeaders(res) {
   res.setHeader("X-Content-Type-Options", "nosniff");
   res.setHeader("X-Frame-Options", "DENY");
   res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+  res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
 }
 function setCorsHeaders(res, allowedOrigin, requestOrigin) {
   setSecurityHeaders(res);
@@ -1560,21 +1596,34 @@ function json(res, status, data, origin, reqOrigin) {
   res.end(JSON.stringify(data));
 }
 var MAX_BODY_BYTES = 1048576;
+var READ_BODY_TIMEOUT_MS = 3e4;
+var MAX_CONFIG_ARRAY = 1e3;
 function readBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
     let totalBytes = 0;
+    const timeout = setTimeout(() => {
+      req.destroy();
+      reject(new Error("Request body read timeout"));
+    }, READ_BODY_TIMEOUT_MS);
     req.on("data", (chunk) => {
       totalBytes += chunk.length;
       if (totalBytes > MAX_BODY_BYTES) {
+        clearTimeout(timeout);
         req.destroy();
         reject(new Error("Request body too large"));
         return;
       }
       chunks.push(chunk);
     });
-    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
-    req.on("error", reject);
+    req.on("end", () => {
+      clearTimeout(timeout);
+      resolve(Buffer.concat(chunks).toString("utf-8"));
+    });
+    req.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
   });
 }
 function createRouteHandler(server) {
@@ -1621,9 +1670,10 @@ function createRouteHandler(server) {
           });
           return;
         }
+        const validEvents = Array.isArray(events) ? events.filter(validateEvent) : void 0;
         const result = await server.processTick(
           state,
-          Array.isArray(events) ? events : void 0
+          validEvents
         );
         const warnings = validation?.warnings ?? [];
         respond(200, {
@@ -1653,6 +1703,10 @@ function createRouteHandler(server) {
         return;
       }
       if (path === "/decisions" && method === "GET") {
+        if (!checkAuth(req, apiKey)) {
+          respond(401, { error: "Unauthorized" });
+          return;
+        }
         const rawLimit = parseInt(url.searchParams.get("limit") ?? "100", 10);
         const limit = Math.min(Math.max(Number.isNaN(rawLimit) ? 100 : rawLimit, 1), 1e3);
         const sinceParam = url.searchParams.get("since");
@@ -1668,7 +1722,11 @@ function createRouteHandler(server) {
         } else {
           decisions = agentE.log.latest(limit);
         }
-        respond(200, { decisions });
+        const sanitized = decisions.map((d) => {
+          const { metricsSnapshot: _, ...rest } = d;
+          return rest;
+        });
+        respond(200, { decisions: sanitized });
         return;
       }
       if (path === "/config" && method === "POST") {
@@ -1686,18 +1744,18 @@ function createRouteHandler(server) {
         }
         const config = parsed;
         if (Array.isArray(config["lock"])) {
-          for (const param of config["lock"]) {
+          for (const param of config["lock"].slice(0, MAX_CONFIG_ARRAY)) {
             if (typeof param === "string") server.lock(param);
           }
         }
         if (Array.isArray(config["unlock"])) {
-          for (const param of config["unlock"]) {
+          for (const param of config["unlock"].slice(0, MAX_CONFIG_ARRAY)) {
             if (typeof param === "string") server.unlock(param);
           }
         }
         if (Array.isArray(config["constrain"])) {
           const validated = [];
-          for (const c of config["constrain"]) {
+          for (const c of config["constrain"].slice(0, MAX_CONFIG_ARRAY)) {
             if (c && typeof c === "object" && typeof c["param"] === "string" && typeof c["min"] === "number" && typeof c["max"] === "number") {
               const constraint = c;
               if (!Number.isFinite(constraint.min) || !Number.isFinite(constraint.max)) {
@@ -1770,14 +1828,28 @@ function createRouteHandler(server) {
         return;
       }
       if (path === "/" && method === "GET" && server.serveDashboard) {
+        if (apiKey) {
+          const dashToken = url.searchParams.get("token") ?? "";
+          const hasBearer = checkAuth(req, apiKey);
+          const hasQueryToken = dashToken.length === apiKey.length && timingSafeEqual(Buffer.from(dashToken), Buffer.from(apiKey));
+          if (!hasBearer && !hasQueryToken) {
+            respond(401, { error: "Unauthorized \u2014 use ?token=<apiKey> or Authorization header" });
+            return;
+          }
+        }
         setCorsHeaders(res, cors, reqOrigin);
-        res.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com; connect-src 'self' ws: wss:; img-src 'self' data:");
-        res.setHeader("Cache-Control", "public, max-age=60");
+        const nonce = randomBytes(16).toString("base64");
+        res.setHeader("Content-Security-Policy", `default-src 'self'; script-src 'nonce-${nonce}' https://cdn.jsdelivr.net; style-src 'unsafe-inline' https://fonts.googleapis.com; font-src https://fonts.gstatic.com; connect-src 'self' ws: wss:; img-src 'self' data:`);
+        res.setHeader("Cache-Control", "no-cache, private");
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-        res.end(getDashboardHtml());
+        res.end(getDashboardHtml(nonce));
         return;
       }
       if (path === "/metrics" && method === "GET") {
+        if (!checkAuth(req, apiKey)) {
+          respond(401, { error: "Unauthorized" });
+          return;
+        }
         const agentE = server.getAgentE();
         const latest = agentE.store.latest();
         const history = agentE.store.recentHistory(100);
@@ -1785,6 +1857,10 @@ function createRouteHandler(server) {
         return;
       }
       if (path === "/metrics/personas" && method === "GET") {
+        if (!checkAuth(req, apiKey)) {
+          respond(401, { error: "Unauthorized" });
+          return;
+        }
         const agentE = server.getAgentE();
         const latest = agentE.store.latest();
         const dist = latest.personaDistribution || {};
@@ -1875,6 +1951,10 @@ function createRouteHandler(server) {
         return;
       }
       if (path === "/pending" && method === "GET") {
+        if (!checkAuth(req, apiKey)) {
+          respond(401, { error: "Unauthorized" });
+          return;
+        }
         const agentE = server.getAgentE();
         const pending = agentE.log.query({ result: "skipped_override" });
         respond(200, {
@@ -1904,6 +1984,7 @@ function send(ws, data) {
 var MAX_WS_PAYLOAD = 1048576;
 var MAX_WS_CONNECTIONS = 100;
 var MIN_TICK_INTERVAL_MS = 100;
+var GLOBAL_MIN_TICK_INTERVAL_MS = 50;
 function sanitizeJson2(obj) {
   if (obj === null || typeof obj !== "object") return obj;
   if (Array.isArray(obj)) return obj.map(sanitizeJson2);
@@ -1916,6 +1997,7 @@ function sanitizeJson2(obj) {
 }
 function createWebSocketHandler(httpServer, server) {
   const wss = new WebSocketServer({ server: httpServer, maxPayload: MAX_WS_PAYLOAD });
+  let globalLastTickTime = 0;
   const aliveMap = /* @__PURE__ */ new WeakMap();
   const heartbeatInterval = setInterval(() => {
     for (const ws of wss.clients) {
@@ -1943,7 +2025,8 @@ function createWebSocketHandler(httpServer, server) {
     }
     if (server.apiKey) {
       const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
-      const token = url.searchParams.get("token") ?? req.headers["authorization"]?.replace("Bearer ", "");
+      const authHeader = req.headers["authorization"];
+      const token = (authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : void 0) ?? url.searchParams.get("token");
       if (!token || token.length !== server.apiKey.length || !timingSafeEqual2(Buffer.from(token), Buffer.from(server.apiKey))) {
         ws.close(1008, "Unauthorized");
         return;
@@ -1977,7 +2060,12 @@ function createWebSocketHandler(httpServer, server) {
             send(ws, { type: "error", message: "Rate limited \u2014 min 100ms between ticks" });
             break;
           }
+          if (now - globalLastTickTime < GLOBAL_MIN_TICK_INTERVAL_MS) {
+            send(ws, { type: "error", message: "Rate limited \u2014 server tick capacity exceeded" });
+            break;
+          }
           lastTickTime = now;
+          globalLastTickTime = now;
           const state = msg["state"];
           const events = msg["events"];
           if (server.validateState) {
@@ -1991,9 +2079,10 @@ function createWebSocketHandler(httpServer, server) {
             }
           }
           try {
+            const validEvents = Array.isArray(events) ? events.filter(validateEvent) : void 0;
             const result = await server.processTick(
               state,
-              Array.isArray(events) ? events : void 0
+              validEvents
             );
             send(ws, {
               type: "tick_result",
@@ -2013,13 +2102,17 @@ function createWebSocketHandler(httpServer, server) {
           break;
         }
         case "event": {
-          const event = msg["event"];
-          if (event) {
-            server.getAgentE().ingest(event);
-            send(ws, { type: "event_ack" });
-          } else {
+          const rawEvent = msg["event"];
+          if (!rawEvent) {
             send(ws, { type: "error", message: 'Missing "event" field' });
+            break;
           }
+          if (!validateEvent(rawEvent)) {
+            send(ws, { type: "error", message: "Invalid event \u2014 requires type (valid event type), timestamp (number), and actor (string)" });
+            break;
+          }
+          server.getAgentE().ingest(rawEvent);
+          send(ws, { type: "event_ack" });
           break;
         }
         case "health": {
@@ -2084,6 +2177,8 @@ var AgentEServer = class {
     this.lastState = null;
     this.adjustmentQueue = [];
     this.alerts = [];
+    /** Serialization lock for processTick — prevents concurrent ticks from corrupting shared state. */
+    this.tickLock = Promise.resolve();
     this.startedAt = Date.now();
     this.wsHandle = null;
     this.port = config.port ?? 3100;
@@ -2220,36 +2315,46 @@ var AgentEServer = class {
    * 6. Return response
    */
   async processTick(state, events) {
-    this.adjustmentQueue = [];
-    this.alerts = [];
-    this.lastState = state;
-    if (events) {
-      for (const event of events) {
-        this.agentE.ingest(event);
+    const prev = this.tickLock;
+    let unlock;
+    this.tickLock = new Promise((resolve) => {
+      unlock = resolve;
+    });
+    await prev;
+    try {
+      this.adjustmentQueue = [];
+      this.alerts = [];
+      this.lastState = state;
+      if (events) {
+        for (const event of events) {
+          this.agentE.ingest(event);
+        }
       }
-    }
-    await this.agentE.tick(state);
-    const rawAdj = [...this.adjustmentQueue];
-    this.adjustmentQueue = [];
-    const decisions = this.agentE.getDecisions({ since: state.tick, until: state.tick });
-    const adjustments = rawAdj.map((adj) => {
-      const decision = decisions.find(
-        (d) => d.plan.parameter === adj.key && d.result === "applied"
-      );
+      await this.agentE.tick(state);
+      const rawAdj = [...this.adjustmentQueue];
+      this.adjustmentQueue = [];
+      const decisions = this.agentE.getDecisions({ since: state.tick, until: state.tick });
+      const adjustments = rawAdj.map((adj) => {
+        const decision = decisions.find(
+          (d) => d.plan.parameter === adj.key && d.result === "applied"
+        );
+        return {
+          parameter: adj.key,
+          value: adj.value,
+          ...adj.scope ? { scope: adj.scope } : {},
+          reasoning: decision?.diagnosis.violation.suggestedAction.reasoning ?? ""
+        };
+      });
       return {
-        parameter: adj.key,
-        value: adj.value,
-        ...adj.scope ? { scope: adj.scope } : {},
-        reasoning: decision?.diagnosis.violation.suggestedAction.reasoning ?? ""
+        adjustments,
+        alerts: [...this.alerts],
+        health: this.agentE.getHealth(),
+        tick: state.tick,
+        decisions
       };
-    });
-    return {
-      adjustments,
-      alerts: [...this.alerts],
-      health: this.agentE.getHealth(),
-      tick: state.tick,
-      decisions
-    };
+    } finally {
+      unlock();
+    }
   }
   /**
    * Run Observer + Diagnoser on the given state without side effects (no execution).
@@ -2291,4 +2396,4 @@ var AgentEServer = class {
 export {
   AgentEServer
 };
-//# sourceMappingURL=chunk-ALGME445.mjs.map
+//# sourceMappingURL=chunk-3HGNFK4A.mjs.map