agentgate-runtime-control 2.13.14 → 2.13.15

package/README.md

@@ -24,18 +24,6 @@ Useful control-plane endpoints include `/api/observability`, `/api/trace?runId=.
 
 **Observe → Attack → Enforce → Replay → Report → Govern**
 
-### Quickstart
-
-```bash
-npm install agentgate-runtime-control
-npx agentgate init          # writes agentgate.config.mjs — tells you to run doctor next
-npx agentgate doctor        # checks your config, warns loudly if you're still in observe mode,
-                             # then tells you to open examples/protect-first-tool.mjs next
-node examples/protect-first-tool.mjs   # see a real tool protected end-to-end
-npx agentgate attack --config ./agentgate.config.mjs   # attack-test YOUR policy, not the defaults
-```
-
-Each command prints what to run next, so you don't have to remember this sequence.
 
 ## Design Partner Edition
 
@@ -82,10 +70,6 @@ The config file must export an `agentgate` object created with `createAgentGate(
 
 See [`docs/production-readiness.md`](docs/production-readiness.md), [`docs/production-deployment.md`](docs/production-deployment.md), and [`docs/release-checklist.md`](docs/release-checklist.md) for deployment, operational, performance, and release gates.
 
-### About `npm test` on the installed package
-
-Running `npm test` inside an **installed** copy of `agentgate-runtime-control` (i.e. from `node_modules`) reports `0 tests` — that's expected, not a bug: the `test/` directory is intentionally not published to npm (see `files` in `package.json`), the same way most published packages don't ship their own test suite to consumers. The real suite (150+ cases, covering policy decisions, the approval lifecycle — including concurrent approve/deny and TTL expiry — attack-lab scenarios, egress guarding, multi-tenant isolation, and more) lives in and runs from the [source repository](https://github.com/walid-agentgate/agentgate) via `node --test`.
-
 ## Security
 
 See [`SECURITY.md`](SECURITY.md) for the security model and vulnerability-reporting guidance. AgentGate provides a deterministic control layer; it does not replace application-level identity, secret management, network isolation, or threat-model testing.
@@ -175,30 +159,11 @@ console.table(runAttackLab({ productionBlock: true }));
 
 The built-in lab covers prompt injection, privilege escalation, destructive actions, high-value refunds, and unsafe tool chaining. It is a testing aid, not a guarantee of security.
 
-### Deep Attack Lab — the unrecognized-action-name gap
-
-The 5 built-in cases above all use action names the policy engine already classifies (`export_all`, `update_production`, `delete`, `refund`, `publish`). A second, larger set specifically attacks action names it does **not** classify — the `unknownActionPolicy` gap described above — plus two "name evasion" cases (the same dangerous action called under a name that isn't in your `blockActions`/`approvalActions`):
-
-```bash
-agentgate attack --deep                       # against built-in default policies
-agentgate attack --deep --config ./agentgate.config.mjs   # against YOUR policy
-```
-
-or programmatically:
-
-```js
-import { runDeepAttackLab, DEEP_ATTACK_CASES } from 'agentgate-runtime-control';
-const results = await runDeepAttackLab(gateway);
-```
-
-Under the historical default (`unknownActionPolicy: 'allow'`), most of these legitimately ALLOW — that's the point, and CI should treat that as a finding rather than a passing baseline for anything reachable in production. Set `unknownActionPolicy: 'ask'` or `'block'` and re-run to confirm the gap is closed for your own policy.
-
 ## CLI
 
 ```bash
 agentgate test refund 1200
 agentgate attack
-agentgate attack --deep
 ```
 
 ## MCP Gateway
@@ -262,26 +227,6 @@ const nextPolicy = mergePolicies(currentPolicy, generated.policy);
 
 Policy generation is deterministic and reviewable. Generated suggestions do not automatically authorize or block traffic until the resulting policy is explicitly applied to a gateway.
 
-### `unknownActionPolicy` — what happens to action names AgentGate doesn't recognize
-
-The policy engine only classifies a small built-in set of action names as `destructive` (`delete`, `refund`, `publish`, `deploy`, `export_all`, `update_production`) or `readOnly` (`read`, `search`, `list`, `get`, `fetch`). **Any other action name — a typo, a new tool, a third-party integration using its own naming, or something that sounds obviously dangerous like `grant_admin` or `drop_database` — does not match any rule and falls through to `ALLOW` by default.** This is a real gap, not a corner case: it means adding a new tool with an unrecognized action name silently gets no protection at all unless you've explicitly listed it in `approvalActions`/`blockActions`.
-
-`policies.unknownActionPolicy` controls that fallback:
-
-```js
-policies: {
-  // 'allow' (default, kept for backward compatibility): unrecognized actions
-  //         pass through untouched, exactly as AgentGate has always done.
-  // 'ask':   unrecognized actions require human approval — the recommended
-  //          starting point; `agentgate init` sets this for new projects.
-  // 'block': unrecognized actions are refused outright — the strictest,
-  //          deny-by-default option, once every legitimate action name in
-  //          your system has been classified.
-  unknownActionPolicy: 'ask'
-}
-```
-
-`agentgate doctor` warns loudly whenever the effective setting is `'allow'`, so this is never a silent gap in a project that runs `doctor` as part of its setup. `examples/protect-first-tool.mjs` demonstrates the gap and the fix side by side with a `grant_admin` call.
 
 ## Approval Flow
 
@@ -313,26 +258,6 @@ Approval state is queryable through `gateway.approvals()` and JSON-RPC methods:
 
 The approval layer is intentionally separate from policy evaluation: policy decides `ALLOW`, `ASK`, or `BLOCK`; approval resolves only the `ASK` path.
 
-### Approval lifecycle — who, when, expiry, single-use, revocation
-
-- **Who approved / denied, and when**: every approval record carries `createdAt`, `resolvedAt`, and (for a deny) a `resolutionReason`. The run record (`gateway.replay(runId)`) links back to the approval via `approvalId` and stores the same `approval` block for audit export (`gateway.replay()` / `/api/audit/export`). AgentGate itself doesn't have a user identity system, so "who" is whatever identity your own auth layer attaches to the request that calls `approve()`/`deny()` — log that at your call site if you need a named approver.
-- **Expiry (TTL)**: a pending approval expires automatically after **15 minutes** by default (`DEFAULT_APPROVAL_TTL_MS` in `src/approval.js`). Pass `approvalTTLMs` to `createRuntime`/`createAgentGate`/`createMCPGateway` to change it, or `ttlMs: null` on a specific request to disable expiry. Once `expiresAt` passes, the approval flips to `status: 'expired'` the next time it's looked at (list/get/approve/deny), and the original tool call can never be executed late.
-- **Single-use guarantee**: `approve()`/`deny()` are synchronous up to the point where they flip `status` away from `pending` — there is no `await` in between the status check and the status write. Because Node runs JS on a single thread, two calls racing to resolve the same approval (concurrent HTTP requests, a double click, a retried request) can never both see `pending`: the second call always sees the already-resolved status and is rejected with `Approval is already <status>`. There is nothing else to configure for this — it's guaranteed by construction, not by a lock.
-- **Revocation**: there's no separate "revoke" verb — deny a still-pending approval with `gateway.deny(approvalId, reason)` (or `agentgate approval deny <id> <reason>` from the CLI) to take it off the table before anyone acts on it.
-- **Duplicate requests**: each call to a protected tool creates its own approval with its own id — AgentGate does not de-duplicate identical-looking requests. If your agent might retry the same call, treat that as your integration's concern (e.g. an idempotency key on your own tool handler).
-
-### Approval CLI
-
-Once a gateway or control plane is running (for example via `agentgate dev`), you can list and resolve approvals from the command line instead of writing HTTP calls by hand:
-
-```
-agentgate approval list [--status pending|approved|denied|expired] [--url <url>]
-agentgate approval approve <approvalId> [--url <url>] [--key <apiKey>]
-agentgate approval deny <approvalId> [reason] [--url <url>] [--key <apiKey>]
-```
-
-By default it talks to `http://localhost:8787` (what `agentgate dev` uses) and, if no `--key`/`AGENTGATE_API_KEY` is given, it automatically picks up the local dev session the same way opening the dashboard in a browser would — no extra setup needed for local testing. Point `--url` at a different host/port for a control plane running elsewhere, and pass `--key` (or set `AGENTGATE_API_KEY`) when auth is required outside local dev.
-
 ## v1.1 — Developer Integration
 
 AgentGate now exposes a single developer-facing runtime:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgate-runtime-control",
-  "version": "2.13.14",
+  "version": "2.13.15",
   "type": "module",
   "description": "Runtime control plane and SaaS governance layer for AI agent tool execution",
   "exports": {

package/src/control-plane.js

@@ -18,10 +18,42 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const PACKAGE_VERSION = require('../package.json').version;
 
+// Reads and parses a POST body with a hard size cap. Earlier versions bailed
+// out of the read loop as soon as the cap was exceeded without consuming the
+// rest of the incoming request — on a keep-alive connection, those unread
+// bytes are still in flight from the client and get misinterpreted as the
+// start of the next request, which is what caused an unrelated follow-up
+// request on the same socket to hang until timeout instead of failing fast.
+// Fix: once oversized, keep draining every chunk (so the socket/HTTP parser
+// ends this request cleanly) but stop buffering it into memory, then raise a
+// typed error with the right status for the caller to respond with.
+async function readJsonBody(req, maxBodySize) {
+  let raw = '';
+  let bytes = 0;
+  let oversized = false;
+  for await (const chunk of req) {
+    bytes += chunk.length;
+    if (bytes > maxBodySize) { oversized = true; continue; }
+    raw += chunk;
+  }
+  if (oversized) {
+    const error = new Error('Payload too large');
+    error.status = 413;
+    throw error;
+  }
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    const error = new Error('Invalid JSON');
+    error.status = 400;
+    throw error;
+  }
+}
+
 export function createControlPlane(options = {}) {
   const gateway = options.gateway || createMCPGateway(options);
   const staticHtml = options.html;
-  const agentStore = options.agentStore || (options.persistence ? createPersistentAgentStore({ filePath: options.agentPersistence || `${options.persistence}/agents.json` }) : null);
+  const agentStore = options.agentStore || (options.persistence ? createPersistentAgentStore({ filePath: options.agentPersistence || `${options.persistence}/agents.json`, recoverFromCorruption: options.recoverFromCorruption, onCorruption: options.onPersistenceCorruption }) : null);
   const tenantRegistry = options.tenantRegistry || new TenantRegistry({ filePath: `${options.persistence || '.agentgate'}/tenants.json`, keyPath: `${options.persistence || '.agentgate'}/api-keys.json` });
   const webhookRegistry = options.webhookRegistry || new WebhookRegistry({ filePath: `${options.persistence || '.agentgate'}/webhooks.json`, deliveryPath: `${options.persistence || '.agentgate'}/webhook-deliveries.json` });
   const authRequired = options.authRequired !== false;
@@ -69,7 +101,11 @@ export function createControlPlane(options = {}) {
     const scopedRuns = () => gateway.runs(tenantId);
     const scopedApprovals = (status) => gateway.approvals(status, tenantId);
     if (path === '/api/health') return { ok: true, mode: gateway.mode, version: gateway?.serverInfo?.version || PACKAGE_VERSION };
-    if (path === '/api/ready') return { ok: true, ready: true, mode: gateway.mode, uptimeSeconds: Math.floor((Date.now() - startedAt) / 1000) };
+    if (path === '/api/ready') {
+      const persistence = gateway.persistenceHealth?.() || { persistent: false, degraded: false, corruptions: [] };
+      const ready = !persistence.degraded;
+      return { ok: ready, ready, mode: gateway.mode, uptimeSeconds: Math.floor((Date.now() - startedAt) / 1000), persistence };
+    }
     if (path === '/api/kill-switch' && method === 'GET') return gateway.killStatus?.() || {killed:false};
     if (path === '/api/kill-switch' && method === 'POST') { if (body.enabled === false) return gateway.unkill?.(); return gateway.kill?.(body.reason); }
     if (path === '/api/metrics') return gateway.telemetry?.snapshot?.() || { uptimeSeconds: Math.floor((Date.now() - startedAt) / 1000), counters: {}, latency: {} };
@@ -171,11 +207,18 @@ export function createControlPlane(options = {}) {
     if (url.pathname.startsWith('/api/')) {
       let body = {};
       if (req.method === 'POST') {
-        let raw = '';
-        let bodyBytes = 0;
         const maxBodySize = Number(options.maxBodySize || 1024 * 1024);
-        for await (const chunk of req) { bodyBytes += chunk.length; if (bodyBytes > maxBodySize) { res.writeHead(413, {'content-type':'application/json'}); res.end(JSON.stringify({error:'Payload too large'})); return; } raw += chunk; }
-        try { body = raw ? JSON.parse(raw) : {}; } catch { res.writeHead(400, {'content-type':'application/json'}); res.end(JSON.stringify({error:'Invalid JSON'})); return; }
+        try {
+          body = await readJsonBody(req, maxBodySize);
+        } catch (error) {
+          // 'connection: close' on top of fully draining the body (above) is
+          // belt-and-suspenders: it tells the client itself not to reuse this
+          // socket, so even a client we haven't fully drained yet won't have
+          // its next request misread on this connection.
+          res.writeHead(error.status || 400, { 'content-type': 'application/json', 'cache-control': 'no-store', 'connection': 'close' });
+          res.end(JSON.stringify({ error: error.message }));
+          return;
+        }
       }
       const limitKey = req.headers['x-agentgate-key'] || req.socket.remoteAddress || 'anonymous';
       const rate = limiter.check(String(limitKey));
@@ -204,7 +247,8 @@ export function createControlPlane(options = {}) {
       }
       const result = await api(url.pathname, req.method, body, Object.fromEntries(url.searchParams.entries()), authContext);
       if (result._html) { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }); res.end(result.html); return; }
-      res.writeHead(result.error ? 404 : 200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      const status = result.error ? 404 : (url.pathname === '/api/ready' && result.ready === false ? 503 : 200);
+      res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
       res.end(JSON.stringify(result));
       return;
     }

package/src/mcp-gateway.js

@@ -32,9 +32,11 @@ export function createMCPGateway(options = {}) {
   const killReason = { value: options.killReason || 'Emergency security lock' };
   const maxRuns = Number(options.maxRuns || 25000);
   let retentionWarned = false;
-  const runStore = options.runStore || (options.persistence ? createPersistentRunStore({ filePath: options.runPersistence || `${options.persistence}/runs.json`, limit: maxRuns }) : null);
+  const recoverFromCorruption = Boolean(options.recoverFromCorruption);
+  const onPersistenceCorruption = options.onPersistenceCorruption;
+  const runStore = options.runStore || (options.persistence ? createPersistentRunStore({ filePath: options.runPersistence || `${options.persistence}/runs.json`, limit: maxRuns, recoverFromCorruption, onCorruption: onPersistenceCorruption }) : null);
   const runs = runStore ? null : [];
-  const approvals = createApprovalStore({ store: options.approvalStore || (options.persistence ? createPersistentApprovalStore({ filePath: options.approvalPersistence || `${options.persistence}/approvals.json`, limit: options.maxApprovals || maxRuns }) : undefined), limit: options.maxApprovals || maxRuns });
+  const approvals = createApprovalStore({ store: options.approvalStore || (options.persistence ? createPersistentApprovalStore({ filePath: options.approvalPersistence || `${options.persistence}/approvals.json`, limit: options.maxApprovals || maxRuns, recoverFromCorruption, onCorruption: onPersistenceCorruption }) : undefined), limit: options.maxApprovals || maxRuns });
   const eventBus = options.eventBus || createEventBus();
   const telemetry = options.telemetry || createTelemetry();
   const egressGuard = options.egressGuard || (options.egress ? createEgressGuard(options.egress === true ? {} : options.egress) : null);
@@ -73,6 +75,15 @@ export function createMCPGateway(options = {}) {
       const count = runStore ? runStore.list().length : runs.length;
       const nearLimit = count >= Math.max(1, Math.ceil(maxRuns * 0.9));
       return { count, limit: maxRuns, nearLimit, persistent: Boolean(runStore), truncated: count >= maxRuns };
+    },
+    // Reports whether persistence had to recover from corruption at startup
+    // (only possible when recoverFromCorruption: true was passed — otherwise
+    // corruption makes createMCPGateway() throw instead of starting up in a
+    // degraded state). Control planes/readiness probes should surface this
+    // rather than reporting healthy while sitting on recovered/lost data.
+    persistenceHealth: () => {
+      const corruptions = [runStore?.corruption, approvals?.corruption].filter(Boolean);
+      return { persistent: Boolean(runStore), degraded: corruptions.length > 0, corruptions };
     }
   };
 

package/src/persistent-store.js

@@ -1,11 +1,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+// Thrown when a persisted collection file exists but cannot be trusted:
+// invalid JSON, or valid JSON that isn't the array shape this store expects.
+// This is distinct from "file does not exist yet" (ENOENT), which is the
+// normal first-run case and is NOT an error.
+export class PersistenceCorruptionError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'PersistenceCorruptionError';
+    this.code = 'AGENTGATE_PERSISTENCE_CORRUPT';
+  }
+}
+
 export class PersistentCollectionStore {
-  constructor(filePath, { key = 'id', limit = 25000, seed = [] } = {}) {
+  constructor(filePath, { key = 'id', limit = 25000, seed = [], recoverFromCorruption = false, onCorruption } = {}) {
     this.filePath = path.resolve(filePath);
     this.key = key;
     this.limit = limit;
+    this.recoverFromCorruption = Boolean(recoverFromCorruption);
+    this.onCorruption = typeof onCorruption === 'function' ? onCorruption : null;
+    // Set only if a corruption event was handled (requires recoverFromCorruption:
+    // true). When this is non-null, the in-memory collection was reset and
+    // whatever was in the corrupt file was NOT recovered automatically.
+    this.corruption = null;
     this.items = this.#load(seed);
   }
 
@@ -35,22 +53,94 @@ export class PersistentCollectionStore {
     fs.writeFileSync(temp, JSON.stringify(this.items, null, 2), 'utf8');
     fs.renameSync(temp, this.filePath);
   }
+
   #load(seed) {
+    let text;
+    try {
+      text = fs.readFileSync(this.filePath, 'utf8');
+    } catch (err) {
+      // No file yet is the normal first-run case. Any other read failure
+      // (permission denied, I/O error, ...) is an operational failure, not
+      // "no data yet" — let it fail closed by propagating the error instead
+      // of silently returning an empty collection.
+      if (err.code === 'ENOENT') return Array.isArray(seed) ? seed.slice(0, this.limit) : [];
+      throw err;
+    }
+    let parsed;
     try {
-      if (!fs.existsSync(this.filePath)) return Array.isArray(seed) ? seed.slice(0, this.limit) : [];
-      const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf8'));
-      return Array.isArray(parsed) ? parsed.slice(0, this.limit) : [];
-    } catch { return Array.isArray(seed) ? seed.slice(0, this.limit) : []; }
+      parsed = JSON.parse(text);
+    } catch (err) {
+      return this.#handleCorruption(text, new PersistenceCorruptionError(
+        `Corrupt persistence file (invalid JSON): ${this.filePath}`,
+        { cause: err }
+      ), seed);
+    }
+    if (!Array.isArray(parsed)) {
+      return this.#handleCorruption(text, new PersistenceCorruptionError(
+        `Corrupt persistence file (expected an array, got ${parsed === null ? 'null' : typeof parsed}): ${this.filePath}`
+      ), seed);
+    }
+    return parsed.slice(0, this.limit);
   }
+
+  // Corruption means the file exists but its contents cannot be trusted —
+  // tampering, a crash mid-write on an older version, disk corruption, etc.
+  // The previous behavior here was to swallow the error and silently return
+  // an empty array, which quietly erases audit history and, worse, makes
+  // pending approvals vanish with no trace. We now fail closed by default:
+  // the store refuses to come up at all, so the operator finds out at
+  // startup instead of discovering a gap in the audit trail later.
+  //
+  // Recovery is opt-in only (recoverFromCorruption: true): the corrupt file
+  // is quarantined (renamed, never deleted) and the collection starts from
+  // `seed` (normally empty) — but this is explicitly NOT the same as
+  // recovering the lost data, and is logged loudly as such.
+  #handleCorruption(rawText, error, seed) {
+    if (!this.recoverFromCorruption) throw error;
+    const quarantinePath = `${this.filePath}.corrupt.${Date.now()}`;
+    try {
+      fs.renameSync(this.filePath, quarantinePath);
+    } catch {
+      try { fs.writeFileSync(quarantinePath, rawText ?? '', 'utf8'); } catch { /* best effort */ }
+    }
+    this.corruption = {
+      filePath: this.filePath,
+      quarantinePath,
+      message: error.message,
+      recoveredAt: new Date().toISOString(),
+      recoveredCount: Array.isArray(seed) ? seed.length : 0
+    };
+    console.error(
+      `\n🚨 AgentGate: persistence corruption recovered for ${this.filePath}\n` +
+      `   Corrupt file quarantined to: ${quarantinePath}\n` +
+      `   Started with ${this.corruption.recoveredCount} seed record(s) — the original contents were NOT recovered.\n` +
+      `   Investigate the quarantined file before trusting this collection again.\n`
+    );
+    this.onCorruption?.(this.corruption);
+    return Array.isArray(seed) ? seed.slice(0, this.limit) : [];
+  }
+
   #trim() { if (this.items.length > this.limit) this.items.splice(this.limit); }
 }
 
 export function createPersistentRunStore(options = {}) {
-  return new PersistentCollectionStore(options.filePath || '.agentgate/runs.json', { limit: options.limit || 25000 });
+  return new PersistentCollectionStore(options.filePath || '.agentgate/runs.json', {
+    limit: options.limit || 25000,
+    recoverFromCorruption: options.recoverFromCorruption,
+    onCorruption: options.onCorruption
+  });
 }
 export function createPersistentApprovalStore(options = {}) {
-  return new PersistentCollectionStore(options.filePath || '.agentgate/approvals.json', { limit: options.limit || 25000 });
+  return new PersistentCollectionStore(options.filePath || '.agentgate/approvals.json', {
+    limit: options.limit || 25000,
+    recoverFromCorruption: options.recoverFromCorruption,
+    onCorruption: options.onCorruption
+  });
 }
 export function createPersistentAgentStore(options = {}) {
-  return new PersistentCollectionStore(options.filePath || '.agentgate/agents.json', { limit: options.limit || 1000 });
+  return new PersistentCollectionStore(options.filePath || '.agentgate/agents.json', {
+    limit: options.limit || 1000,
+    recoverFromCorruption: options.recoverFromCorruption,
+    onCorruption: options.onCorruption
+  });
 }