agentgate-runtime-control 2.13.15 → 2.14.0

package/README.md

@@ -24,6 +24,18 @@ 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
 
@@ -70,6 +82,10 @@ 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.
@@ -159,11 +175,30 @@ 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
@@ -227,6 +262,68 @@ 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.
+
+## 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
 
@@ -258,6 +355,26 @@ 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:
@@ -421,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.
 
@@ -468,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.15",
+  "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

@@ -67,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(){} };
@@ -245,9 +264,22 @@ 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; }
       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

@@ -111,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;
   }
@@ -157,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/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' });
   }