agentgate-runtime-control 2.13.14 → 2.14.0

package/README.md

@@ -283,6 +283,48 @@ policies: {
 
 `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.
 
+## Closing the action-name evasion gap further (2.14)
+
+A follow-up adversarial test fed the policy engine action names it had never been designed to see: `delete\u0000all` (embedded NUL), `delete‮` (right-to-left override — makes the name *render* differently than it reads), `％ｅｘｐｏｒｔ` (fullwidth lookalikes of "export"), and `../delete` (path-traversal-shaped). None crashed anything, but all of them ALLOWed under the historical default, which is the real finding: a string-based classifier can always be fed a string it wasn't expecting.
+
+Three independent changes close this, and they compose with `unknownActionPolicy` above rather than replace it:
+
+**1. Unsafe action names are always rejected, unconditionally.** Control characters, bidi-override/zero-width characters, the fullwidth-forms block, and `../`-style path segments have no legitimate reason to appear in an action name, so this check is **not** an opt-in policy — it runs for every request, for every existing user, with no config needed:
+
+```text
+delete\u0000all   → BLOCK (winningRule: 'unsafe-action-name')
+delete‮      → BLOCK
+％ｅｘｐｏｒｔ        → BLOCK
+../delete         → BLOCK
+```
+
+**2. `policies.strictActionNames: true` (opt-in)** additionally requires every action name to match `^[a-z][a-z0-9_.:-]{0,63}$` — a plain lowercase identifier. This is off by default because it's a real behavior change for any system with mixed-case or unusually-shaped action names already in production; turn it on once you've audited your own action-name list.
+
+**3. Tool registration metadata is authoritative over the action name a caller sends.** The real fix for "call the dangerous tool under a name the policy engine doesn't recognize" isn't a better regex — it's not trusting the name at all for tools you control. `registerTool()` now accepts classification that lives with the tool, not with whatever the caller's request claims:
+
+```js
+gateway.registerTool({
+  name: 'remove_customer',
+  actionClass: 'destructive',      // or 'readOnly'
+  requiresApproval: true,
+  environments: ['development', 'staging'], // tool refuses to run outside these
+  handler: async (args) => { /* ... */ }
+});
+```
+
+A caller cannot edit another tool's registration, so `grant_admin` registered with `requiresApproval: true` still requires approval even if a request calls it with `action: 'totally_unrecognized_name'`. Metadata sits below your own explicit `blockActions`/`productionBlock`/amount/`approvalActions` rules (those still win) but above name-based classification and `unknownActionPolicy` — see `test/action-hardening-2.14.test.js` for the exact priority ordering.
+
+## Idempotent approval resolution (2.14)
+
+`POST /api/approvals/approve` and `POST /api/approvals/deny` accept an `Idempotency-Key` header. A retried request with the same key (same tenant, same path) gets back the **exact same response** instead of re-executing the handler or hitting an "already approved" error:
+
+```text
+POST /api/approvals/approve
+Idempotency-Key: approval_123:resolve:v1
+```
+
+Replayed responses carry an `Idempotency-Replayed: true` header. Keys are cached in memory per control-plane process for 24h by default (`idempotencyTtlMs` to override); a different key against the same approval is **not** treated as a replay and goes through normal single-use resolution. This matters for exactly the failure mode a retrying client hits in practice: a network blip after the first approve succeeded, followed by an automatic retry that must not double-execute a refund or a production change.
+
 ## Approval Flow
 
 Sensitive tool calls that evaluate to `ASK` enter a pending approval state and are never executed automatically in enforce mode.
@@ -496,6 +538,28 @@ AgentGate supports deterministic RBAC and ABAC authorization using agent/user id
 
 Runs, approvals, agents, and policy versions can be persisted locally through the built-in storage adapters. For production multi-tenant deployments, use the Postgres/Supabase adapters with tenant-scoped sessions and RLS; local JSON persistence is intended for development or single-process deployments. Storage is provider-neutral so a database adapter can be introduced without changing the policy API.
 
+### Persistence corruption is fail-closed, not silent (2.13.15+)
+
+An independent stress test of 2.13.14 found that writing garbage into `runs.json` or `approvals.json` and restarting made the server come up normally with an **empty collection** — no error, no alert. For `runs.json` that's a silently erased audit trail; for `approvals.json` it means a pending approval can vanish with no trace at all. That was a bug, not a resilience feature.
+
+As of 2.13.15, `PersistentCollectionStore` distinguishes three cases:
+
+- **File doesn't exist** (first run) — starts empty, as always. Not an error.
+- **File exists but isn't valid JSON, or isn't an array** — this is corruption. By default, the store throws `PersistenceCorruptionError` (`code: 'AGENTGATE_PERSISTENCE_CORRUPT'`) and refuses to start, so a corrupted security-relevant file is loud at startup instead of discovered later as a gap in the audit log.
+- **Any other read failure** (permission denied, disk I/O error) — also propagates as an error rather than being treated as "no data yet."
+
+Recovery is opt-in only, because silently discarding the operator's decision here is exactly the bug being fixed:
+
+```js
+createMCPGateway({
+  persistence: '.agentgate',
+  recoverFromCorruption: true,      // off by default — corruption throws unless you opt in
+  onPersistenceCorruption: (event) => { /* event.quarantinePath, event.filePath, ... */ }
+});
+```
+
+With `recoverFromCorruption: true`, the corrupt file is renamed to `<file>.corrupt.<timestamp>` (never deleted) so it can be inspected, the collection starts from an empty/seed state, and the event is logged loudly to stderr and handed to `onPersistenceCorruption` if provided — it is never silently absorbed. `gateway.persistenceHealth()` and the Control Plane's `GET /api/ready` (which now returns `503` with `{ ready: false, persistence: { degraded: true, corruptions: [...] } }` in this state) let you alert on it rather than assume health.
+
 ## Multi-Tenant Control Plane (v1.8)
 AgentGate v1.8 adds tenant isolation, scoped API keys, key rotation/revocation, and tenant-scoped webhook registrations.
 
@@ -543,8 +607,14 @@ For first-tenant bootstrap over HTTP, set `AGENTGATE_BOOTSTRAP_TOKEN` and send `
 - Deterministic authorization remains the security authority
 
 
+### Oversized request bodies no longer stall the next request (2.13.15+)
+
+A stress test found that a request body larger than `maxBodySize` correctly returned `413`, but the server stopped reading the body as soon as the limit was crossed without draining the rest of what the client was sending. On a keep-alive connection, those unread bytes were still arriving and got misread as the start of the *next* request, so a completely unrelated follow-up request (even an auth check with a fake key) could hang for the full request timeout instead of returning `401` quickly — a cheap way to tie up connections.
+
+2.13.15 fixes this by always fully draining the request body (even once it's known to be oversized — the rest is discarded, not buffered) before responding, and by sending `Connection: close` on `413`/`400` body-parsing errors so the client doesn't attempt to reuse a connection that was cut short either way. Regression tests in `test/oversized-body-recovery.test.js` repeat the exact sequence from the report (oversized request, then a fake-key request) and assert the follow-up never exceeds ~2s.
+
 ### Production Operations v2.1
-- `/api/health` and `/api/ready` health/readiness probes
+- `/api/health` and `/api/ready` health/readiness probes (`/api/ready` reports `503` and `persistence.degraded: true` if persistence was recovered from corruption — see Persistence above)
 - `/api/metrics` deterministic runtime counters and latency telemetry
 - `/api/events` Server-Sent Events stream for runtime events
 - Sliding-window HTTP rate limiting with 429 responses

package/docs/2.14-hardening-plan.md

@@ -0,0 +1,60 @@
+# 2.13.15 / 2.14 Hardening — Status and Remaining Infrastructure Plan
+
+This tracks the fix plan that came out of the independent 2.13.14 stress-test report. Items are split into what shipped as code in this repo (2.13.15 hotfix + 2.14 action-hardening) versus what requires real infrastructure or a third party and cannot be completed by changing source files alone.
+
+## Shipped as code
+
+| Item | Release | Where |
+|---|---|---|
+| Oversized request body no longer stalls the next request | 2.13.15 | `src/control-plane.js` (`readJsonBody`), `test/oversized-body-recovery.test.js` |
+| Persistence corruption fails closed by default (was silent data loss) | 2.13.15 | `src/persistent-store.js` (`PersistenceCorruptionError`), `test/persistence-corruption.test.js` |
+| `/api/ready` reports `503`/`degraded` on recovered corruption | 2.13.15 | `src/control-plane.js`, `src/mcp-gateway.js` (`persistenceHealth()`) |
+| Unsafe action names (control/bidi-override/fullwidth/path-traversal) blocked unconditionally | 2.14 | `src/policy-engine.js` (`UNSAFE_ACTION_NAME`) |
+| Opt-in strict action-name allowlist (`policies.strictActionNames`) | 2.14 | `src/policy-engine.js` (`STRICT_ACTION_NAME`) |
+| Tool registration metadata (`actionClass`, `requiresApproval`, `environments`) as the source of truth, overriding caller-supplied action names | 2.14 | `src/mcp-gateway.js` (`registerTool`), `src/policy-engine.js` |
+| Idempotency-Key support for `/api/approvals/approve` and `/deny` | 2.14 | `src/control-plane.js` |
+| `test/action-hardening-2.14.test.js`, `test/idempotency-approve-deny.test.js` | 2.14 | regression coverage for all of the above |
+
+`policies.unknownActionPolicy` (deny-by-default for action names the engine still doesn't recognize) and the Deep Attack Lab shipped in 2.13.14; this round only adds to it rather than replacing it. None of the above change default behavior in a way that breaks an existing deployment, except `strictActionNames`, which is opt-in.
+
+## Still requires real infrastructure or a third party
+
+These cannot be "sent as files" — they need an actual environment, actual load, or an actual outside reviewer. Two already have a runnable test pack in this repo; the other two are net new and described below.
+
+### Already have a test pack — just needs an environment to run it in
+
+- **PostgreSQL/Supabase + RLS acceptance test** — `docs/managed-postgres-acceptance-test.md`. Run against a real managed Postgres staging instance; records RPO/RTO and backup/restore verification.
+- **External security review** — `docs/external-security-review.md` and `docs/external-security-review-test-pack.md`. Needs an independent reviewer to actually execute and sign off; AgentGate's own team cannot self-certify this gate.
+
+### Net new — no existing doc, plan below
+
+**Disk-full test.** The 2.13.14 report deliberately avoided filling a real disk (`EACCES` via a read-only directory was used as a safe proxy, and it did surface a clear exception — see `src/persistent-store.js:save()`). A real disk-full test needs:
+1. A disposable staging host or container with a **quota-limited volume** (e.g. a small loop-mounted filesystem, or a container volume with a byte quota) — never the host's real root disk.
+2. Fill the quota while `PersistentCollectionStore.save()` is mid-write (temp-file + `renameSync`), and separately while idle, and confirm in both cases: the process surfaces a clear, loud error (not a silent swallow — this is the same class of bug 2.13.15 just fixed for corruption, so it needs its own explicit check); the `.tmp` file never replaces a good `filePath` via a partial `renameSync`; the control plane's `/api/ready` reflects the failure.
+3. Record: error surfaced, state of `filePath` vs `filePath.tmp` after the failure, and whether a subsequent write (after freeing space) recovers cleanly.
+
+**Multi-instance / concurrent-writer test.** Local JSON persistence (`PersistentCollectionStore`) is explicitly documented as single-process (see README "Persistence"); this test is about *proving* that boundary rather than discovering it in production:
+1. Point two separate `createMCPGateway({ persistence: sameDir })` processes at the same directory.
+2. Drive concurrent approvals/writes from both.
+3. Expected (and acceptable) outcome: last-writer-wins / lost updates — document this explicitly as the known limitation of local JSON mode, with the recommendation to use the PostgreSQL/Supabase adapter (which has real RLS and a real database handling concurrency) for any multi-instance deployment. The point of this test is a documented, demonstrated boundary — not a fix to local JSON mode itself, which isn't meant to be multi-writer-safe.
+
+## Acceptance criteria before using "enterprise-grade" language
+
+Carried over from the stress-test report, now with status:
+
+| Gate | Target | Status |
+|---|---:|---|
+| Oversized request followed by normal request | 0 timeouts | ✅ shipped 2.13.15, regression-tested |
+| Corrupted persistence startup | fail-closed or documented recovery | ✅ shipped 2.13.15, regression-tested |
+| Pending approvals lost silently | 0 | ✅ shipped 2.13.15 |
+| Unknown sensitive action allowed (name evasion) | 0 | ✅ shipped 2.13.14/2.14 (`unknownActionPolicy` + metadata + unsafe-name block) |
+| Pre-approval handler execution | 0 | ✅ already enforced, regression-tested pre-2.13 |
+| Duplicate approved execution | 0 | ✅ already enforced; 2.14 adds idempotent retries on top |
+| Cross-tenant leak | 0 | ✅ regression-tested (`test/approval-tenant-isolation.test.js`) |
+| Backup/restore | PASS | ⬜ needs a real Postgres staging run — see `docs/managed-postgres-acceptance-test.md` |
+| PostgreSQL RLS | PASS | ⬜ needs a real Postgres staging run — same doc |
+| Disk-full behavior | documented and tested | ⬜ plan above, needs a quota-limited environment |
+| Multi-instance/concurrent writer | documented and tested | ⬜ plan above, needs two real processes |
+| External review | completed or claim explicitly absent | ⬜ needs an actual independent reviewer |
+
+Until the ⬜ rows are run against real infrastructure, marketing/sales copy should keep saying what's actually true: the engine, policy, and single-process persistence layer are hardened and regression-tested; multi-instance/Postgres/external-review claims are not yet backed by an executed test run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgate-runtime-control",
-  "version": "2.13.14",
+  "version": "2.14.0",
   "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;
@@ -35,6 +67,25 @@ export function createControlPlane(options = {}) {
   const limiter = options.rateLimiter || new SlidingWindowLimiter({ limit: options.rateLimit || 120, windowMs: options.rateWindowMs || 60000 });
   const tenantLimiter = options.tenantRateLimiter || new SlidingWindowLimiter({ limit: options.tenantRateLimit || options.rateLimit || 120, windowMs: options.rateWindowMs || 60000 });
   const startedAt = Date.now();
+  // Idempotency: a client that retries POST /api/approvals/approve|deny
+  // (timeout, connection reset, at-least-once delivery) must not trigger a
+  // second side effect. Scoped by tenant + path + the client-supplied
+  // Idempotency-Key so a retry with the same key gets back the exact same
+  // response instead of re-executing (or hitting "already approved").
+  const idempotencyTtlMs = Number(options.idempotencyTtlMs || 24 * 60 * 60 * 1000);
+  const idempotencyCache = new Map(); // scopedKey -> { status, result, expiresAt }
+  const IDEMPOTENT_PATHS = new Set(['/api/approvals/approve', '/api/approvals/deny']);
+  function idempotencyGet(key) {
+    if (!key) return null;
+    const entry = idempotencyCache.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt < Date.now()) { idempotencyCache.delete(key); return null; }
+    return entry;
+  }
+  function idempotencyPut(key, status, result) {
+    if (!key) return;
+    idempotencyCache.set(key, { status, result, expiresAt: Date.now() + idempotencyTtlMs });
+  }
   const policyRegistry = options.policyRegistry || createPolicyRegistry({ filePath: options.policyPersistence || `${options.persistence || '.agentgate'}/policies.json` });
   const bundleRegistry = options.policyBundleRegistry || createPolicyBundleRegistry({ filePath: options.policyBundlePersistence || `${options.persistence || '.agentgate'}/policy-bundles.json` });
   const agents = agentStore || { items: [], add(a){ this.items.unshift(a); return a; }, list(filter){ const all=[...this.items]; return typeof filter==='function' ? all.filter(filter) : all; }, get(id){ return this.items.find(a=>a.id===id || a.name===id) || null; }, save(){} };
@@ -69,7 +120,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 +226,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));
@@ -202,9 +264,23 @@ export function createControlPlane(options = {}) {
           if (!tenantRate.allowed) { res.writeHead(429, {'content-type':'application/json','cache-control':'no-store','retry-after':String(Math.ceil((Date.parse(tenantRate.resetAt)-Date.now())/1000))}); res.end(JSON.stringify({error:'Tenant rate limit exceeded', ...tenantRate})); return; }
         }
       }
+      const idempotencyHeader = req.headers['idempotency-key'];
+      const idempotencyKey = idempotencyHeader && IDEMPOTENT_PATHS.has(url.pathname)
+        ? `${authContext.tenantId || 'no-tenant'}:${url.pathname}:${idempotencyHeader}`
+        : null;
+      if (idempotencyKey) {
+        const cached = idempotencyGet(idempotencyKey);
+        if (cached) {
+          res.writeHead(cached.status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'idempotency-replayed': 'true' });
+          res.end(JSON.stringify(cached.result));
+          return;
+        }
+      }
       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);
+      if (idempotencyKey) idempotencyPut(idempotencyKey, status, result);
+      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 };
     }
   };
 
@@ -100,7 +111,17 @@ export function createMCPGateway(options = {}) {
       name: tool.name,
       description: tool.description || '',
       inputSchema: tool.inputSchema || { type: 'object' },
-      handler: tool.handler
+      handler: tool.handler,
+      // Optional classification recorded at registration time, i.e. by
+      // whoever controls the tool list — not by whatever action name a
+      // caller's request happens to send. This is what makes it trustworthy:
+      // a caller can rename "remove_customer" to "delete" or to a brand-new
+      // string the policy engine has never seen, but it cannot edit this
+      // tool's registered metadata. See policy-engine.js's handling of
+      // request.toolMetadata for how this takes priority over name matching.
+      actionClass: tool.actionClass || null, // 'destructive' | 'readOnly' | null
+      requiresApproval: tool.requiresApproval === true,
+      environments: Array.isArray(tool.environments) ? tool.environments : null
     });
     return api;
   }
@@ -146,7 +167,12 @@ export function createMCPGateway(options = {}) {
       model: params.model || params.context?.model || input.model,
       usage: params.usage || params.context?.usage || input.usage,
       estimatedCost: params.estimatedCost ?? params.context?.estimatedCost ?? input.estimatedCost,
-      context: params.context || {}
+      context: params.context || {},
+      // The tool's own registered metadata (never caller-suppliable) — see
+      // registerTool() above and policy-engine.js's toolMetadata handling.
+      toolMetadata: (tool.actionClass || tool.requiresApproval || tool.environments)
+        ? { actionClass: tool.actionClass, requiresApproval: tool.requiresApproval, environments: tool.environments }
+        : null
     };
     if (killSwitch && mode === 'enforce') {
       const run = { id: randomUUID(), createdAt:new Date().toISOString(), tenantId:request.tenantId, request, decision:'BLOCK', risk:100, reason:killReason.value, mode, killed:true };

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
+  });
 }

package/src/policy-engine.js

@@ -5,11 +5,38 @@ export const DECISIONS = Object.freeze({ ALLOW: 'ALLOW', ASK: 'ASK', BLOCK: 'BLO
 const destructive = new Set(['delete','refund','publish','deploy','export_all','update_production']);
 const readOnly = new Set(['read','search','list','get','fetch']);
 
+// Characters that have no legitimate reason to appear in an action name and
+// exist only to confuse logs/matching or to smuggle a control sequence past
+// string-equality checks: NUL and other control bytes, zero-width/bidi
+// override characters (can make "delete" *look* like something else when
+// rendered, or hide characters entirely), the fullwidth-forms block (an
+// adversarial test used "％ｅｘｐｏｒｔ" — fullwidth lookalikes of ASCII — to
+// probe whether it matched "export"), and "../"-style path segments. This
+// check is unconditional and always on (not an opt-in policy) because no
+// real tool/action name is ever affected by it — unlike a strict allowlist
+// regex, which IS opt-in below to avoid breaking existing naming schemes.
+const UNSAFE_ACTION_NAME = new RegExp(
+  '[\\x00-\\x1F\\x7F\\u200B-\\u200F\\u202A-\\u202E\\u2066-\\u2069\\uFEFF\\uFF00-\\uFFEF]|\\.\\.[\\/\\\\]'
+);
+// Opt-in, stricter allowlist for teams that control every action name they
+// register: policies.strictActionNames: true requires lowercase
+// ascii-identifier-shaped names. Off by default so existing naming schemes
+// (mixed case, spaces, unicode brand/customer names, etc.) don't suddenly
+// start failing on upgrade.
+const STRICT_ACTION_NAME = /^[a-z][a-z0-9_.:-]{0,63}$/;
+
 export function evaluate(input = {}, policies = {}) {
   const auth = authorize(input, policies.authorization);
   const trace = [{ id: 'authorization', matched: auth.decision === 'BLOCK', decision: auth.decision, reason: auth.reason, matchedRule: auth.matchedRule || null }];
   if (auth.decision === 'BLOCK') return decision('BLOCK', auth.reason, 96, { authorization: auth, ruleTrace: trace, winningRule: auth.matchedRule || 'authorization' });
-  const action = String(input.action || '').toLowerCase();
+  const rawAction = String(input.action || '');
+  if (UNSAFE_ACTION_NAME.test(rawAction)) {
+    return decision('BLOCK', 'Action name contains unsafe characters (control, bidi-override, fullwidth-form, or path-traversal)', 99, { ruleTrace: [...trace, { id: 'unsafe-action-name', matched: true, decision: 'BLOCK', reason: 'Action name contains unsafe characters' }], winningRule: 'unsafe-action-name' });
+  }
+  const action = rawAction.toLowerCase();
+  if (policies.strictActionNames && !STRICT_ACTION_NAME.test(action)) {
+    return decision('BLOCK', 'Action name does not match the required format under strictActionNames', 97, { ruleTrace: [...trace, { id: 'strict-action-name', matched: true, decision: 'BLOCK', reason: 'Action name does not match the required format under strictActionNames' }], winningRule: 'strict-action-name' });
+  }
   const hasAmount = Object.prototype.hasOwnProperty.call(input, 'amount') && input.amount !== undefined && input.amount !== null;
   if (hasAmount && (typeof input.amount !== 'number' || !Number.isFinite(input.amount) || input.amount < 0)) {
     return decision('BLOCK', 'Amount must be a finite non-negative number', 98, { ruleTrace: [...trace, { id: 'invalid-amount', matched: true, decision: 'BLOCK', reason: 'Amount must be a finite non-negative number' }], winningRule: 'invalid-amount' });
@@ -29,6 +56,30 @@ export function evaluate(input = {}, policies = {}) {
   if (policies.approvalActions?.includes(action)) {
     return decision('ASK', 'Approval required for sensitive action', 70, { ruleTrace: [...trace, { id: 'approval-action', matched: true, decision: 'ASK', reason: 'Approval required for sensitive action' }], winningRule: 'approval-action' });
   }
+  // A tool's own registered metadata (set by whoever controls the tool list,
+  // via registerTool({ actionClass, requiresApproval, environments })) is a
+  // more trustworthy signal than the action *name* a caller's request
+  // happens to send, because a caller can pick any action string it wants
+  // but cannot edit another tool's registration. It sits below the admin's
+  // own explicit blockActions/productionBlock/amount/approvalActions rules
+  // above (those still win), but above name-based classification and
+  // unknownActionPolicy below — this is what closes the "call the dangerous
+  // tool under an action name the policy engine doesn't recognize" evasion.
+  const toolMeta = input.toolMetadata;
+  if (toolMeta) {
+    if (Array.isArray(toolMeta.environments) && toolMeta.environments.length && !toolMeta.environments.includes(env)) {
+      return decision('BLOCK', 'Tool is not permitted in this environment per its registered metadata', 93, { ruleTrace: [...trace, { id: 'tool-metadata-environment', matched: true, decision: 'BLOCK', reason: 'Tool is not permitted in this environment per its registered metadata' }], winningRule: 'tool-metadata-environment' });
+    }
+    if (toolMeta.actionClass === 'destructive' && policies.productionBlock && env === 'production') {
+      return decision('BLOCK', 'Destructive production action is blocked (per tool registration metadata)', 90, { ruleTrace: [...trace, { id: 'tool-metadata-production-block', matched: true, decision: 'BLOCK', reason: 'Destructive production action is blocked (per tool registration metadata)' }], winningRule: 'tool-metadata-production-block' });
+    }
+    if (toolMeta.requiresApproval) {
+      return decision('ASK', 'Approval required per tool registration metadata', 74, { ruleTrace: [...trace, { id: 'tool-metadata-approval', matched: true, decision: 'ASK', reason: 'Approval required per tool registration metadata' }], winningRule: 'tool-metadata-approval' });
+    }
+    if (toolMeta.actionClass === 'readOnly') {
+      return decision('ALLOW', 'Read-only per tool registration metadata', 5, { ruleTrace: [...trace, { id: 'tool-metadata-readonly', matched: true, decision: 'ALLOW', reason: 'Read-only per tool registration metadata' }], winningRule: 'tool-metadata-readonly' });
+    }
+  }
   if (amount > 0 && amount > (policies.autoApproveAmount ?? 500)) {
     return decision('ASK', 'Amount exceeds the automatic approval threshold', 65, { ruleTrace: [...trace, { id: 'auto-approval-threshold', matched: true, decision: 'ASK', reason: 'Amount exceeds the automatic approval threshold' }], winningRule: 'auto-approval-threshold' });
   }