agentgate-runtime-control 2.13.11 → 2.13.13

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.
@@ -258,6 +274,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:

package/bin/agentgate.js

@@ -35,6 +35,7 @@ Usage:
   agentgate egress <response.json> [--strict]
   agentgate policy <create|list|test|activate|rollback|diff> <name> ...
   agentgate tenant <create|list|key|revoke|rotate> ...
+  agentgate approval <list|approve|deny> [id] [reason] [--url <url>] [--key <apiKey>]
   agentgate --help
   agentgate doctor
   agentgate simulate
@@ -108,9 +109,22 @@ export { pack };
 } else if (cmd === 'doctor') {
   const configPath = path.resolve(process.cwd(), 'agentgate.config.mjs');
   let config = { mode: 'enforce', policies: { productionBlock: true, autoApproveAmount: 500, approvalAmount: 5000 }, authRequired: true };
-  try { const mod = await import(`file://${configPath}?doctor=${Date.now()}`); const gate = mod.agentgate || {}; config = { ...config, ...(mod.config || {}), ...(gate.config || {}), ...(gate.mode ? { mode: gate.mode } : {}), ...(gate.policies ? { policies: gate.policies } : {}) }; } catch {}
+  let foundConfig = false;
+  try { const mod = await import(`file://${configPath}?doctor=${Date.now()}`); const gate = mod.agentgate || {}; config = { ...config, ...(mod.config || {}), ...(gate.config || {}), ...(gate.mode ? { mode: gate.mode } : {}), ...(gate.policies ? { policies: gate.policies } : {}) }; foundConfig = true; } catch {}
   const report = runDoctorChecks({ config });
-  console.log(JSON.stringify(report, null, 2)); process.exitCode = report.ok ? 0 : 2;
+  console.log(JSON.stringify(report, null, 2));
+  if (!foundConfig) {
+    console.error('\nNo agentgate.config.mjs found here — checked built-in defaults instead. Run `agentgate init` first to create one for your own policies.');
+  }
+  if (config.mode === 'observe') {
+    console.error('\n⚠️  WARNING: mode is "observe". Decisions are being recorded but NOTHING is actually blocked or held for approval yet — destructive tools will still execute. Set mode: \'enforce\' in agentgate.config.mjs once you are ready to protect real tools.');
+  }
+  if (report.ok) {
+    console.error('\nNext: protect your first tool — see examples/protect-first-tool.mjs for a worked example (read/delete/refund/export), or run `agentgate attack --config agentgate.config.mjs` to test your policy against the built-in attack scenarios.');
+  } else {
+    console.error('\nFix the failing checks above, then run `agentgate doctor` again.');
+  }
+  process.exitCode = report.ok ? 0 : 2;
 } else if (cmd === 'simulate') {
   const policy = { productionBlock: true, autoApproveAmount: 500, approvalAmount: 5000 };
   console.log(JSON.stringify(simulatePolicyMatrix({ policies: policy }), null, 2));
@@ -287,7 +301,85 @@ export { pack };
       ? `import { createAgentGate, getPolicyPack } from 'agentgate-runtime-control';\n\nconst pack = getPolicyPack('${pack.id}');\n\nexport const agentgate = createAgentGate({\n  agent: 'SupportAgent',\n  mode: 'observe',\n  policies: pack.policies\n});\n\nexport { pack };\n`
       : `import { createAgentGate } from 'agentgate-runtime-control';\n\nexport const agentgate = createAgentGate({\n  agent: 'MyAgent',\n  mode: 'enforce',\n  policies: {\n    productionBlock: true,\n    autoApproveAmount: 500,\n    approvalAmount: 5000\n  }\n});\n`;
     try { await fs.access(file); console.error('agentgate.config.mjs already exists'); process.exitCode = 1; }
-    catch { await fs.writeFile(file, content, 'utf8'); console.log(`Created ${file}${pack ? ` from ${pack.name} (enforce mode)` : ''}`); }
+    catch {
+      await fs.writeFile(file, content, 'utf8');
+      console.log(`Created ${file}${pack ? ` from ${pack.name} (enforce mode)` : ''}`);
+      console.log('\nNext: run `agentgate doctor` to check this config, then see examples/protect-first-tool.mjs to protect your first tool.');
+    }
+  }
+} else if (cmd === 'approval') {
+  const sub = process.argv[3];
+  const urlIndex = process.argv.indexOf('--url');
+  const baseUrl = (urlIndex >= 0 ? process.argv[urlIndex + 1] : (process.env.AGENTGATE_URL || 'http://localhost:8787')).replace(/\/$/, '');
+  const keyIndex = process.argv.indexOf('--key');
+  const apiKey = keyIndex >= 0 ? process.argv[keyIndex + 1] : (process.env.AGENTGATE_API_KEY || null);
+
+  async function authHeaders() {
+    if (apiKey) return { 'x-agentgate-key': apiKey, 'content-type': 'application/json' };
+    // No API key given — try to pick up the local session cookie that `agentgate dev`
+    // hands out on GET '/', so this CLI can talk to a locally running dev server
+    // without any extra setup.
+    try {
+      const res = await fetch(`${baseUrl}/`);
+      const cookie = res.headers.get('set-cookie');
+      const match = cookie && cookie.match(/agentgate_local_session=[^;]+/);
+      if (match) return { cookie: match[0], 'content-type': 'application/json' };
+    } catch {}
+    return { 'content-type': 'application/json' };
+  }
+
+  async function call(apiPath, method = 'GET', body) {
+    let headers;
+    try { headers = await authHeaders(); }
+    catch (err) { return { status: 0, json: { error: `Could not reach ${baseUrl}: ${err.message}` } }; }
+    try {
+      const res = await fetch(`${baseUrl}${apiPath}`, { method, headers, body: body ? JSON.stringify(body) : undefined });
+      let json;
+      try { json = await res.json(); } catch { json = { error: `Non-JSON response (status ${res.status})` }; }
+      return { status: res.status, json };
+    } catch (err) {
+      return { status: 0, json: { error: `Could not reach ${baseUrl}: ${err.message}` } };
+    }
+  }
+
+  const unreachable = (result) => {
+    console.error(`Could not reach AgentGate at ${baseUrl}${result.status ? ` (HTTP ${result.status})` : ''}: ${result.json.error || 'unknown error'}`);
+    console.error('Is `agentgate dev` running? Point at it with --url <http://host:port>, or pass --key <apiKey> if auth is required.');
+    process.exitCode = 1;
+  };
+
+  if (sub === 'list') {
+    const statusIndex = process.argv.indexOf('--status');
+    const status = statusIndex >= 0 ? process.argv[statusIndex + 1] : undefined;
+    const result = await call(`/api/approvals${status ? `?status=${encodeURIComponent(status)}` : ''}`);
+    if (result.status !== 200) unreachable(result);
+    else {
+      const approvals = result.json.approvals || [];
+      if (!approvals.length) console.log('No approvals found.');
+      else console.table(approvals.map(a => ({ id: a.id, status: a.status, action: a.metadata?.action || a.request?.action || '', createdAt: a.createdAt, expiresAt: a.expiresAt || 'never' })));
+    }
+  } else if (sub === 'approve' || sub === 'deny') {
+    const id = process.argv[4];
+    if (!id) { console.error(`Usage: agentgate approval ${sub} <approvalId>${sub === 'deny' ? ' [reason]' : ''} [--url <url>] [--key <apiKey>]`); process.exitCode = 1; }
+    else {
+      const reason = sub === 'deny' ? process.argv[5] : undefined;
+      const apiPath = sub === 'approve' ? '/api/approvals/approve' : '/api/approvals/deny';
+      const result = await call(apiPath, 'POST', sub === 'approve' ? { approvalId: id } : { approvalId: id, reason });
+      if (result.status !== 200 || result.json.ok === false) {
+        if (result.status === 0 || result.status === 401 || result.status === 403) unreachable(result);
+        else { console.error(`Could not ${sub} ${id}: ${result.json.error || `HTTP ${result.status}`}`); process.exitCode = 1; }
+      } else {
+        console.log(JSON.stringify(result.json, null, 2));
+      }
+    }
+  } else {
+    console.error(`Usage: agentgate approval <list|approve|deny> ...
+  agentgate approval list [--status pending|approved|denied|expired] [--url <url>] [--key <apiKey>]
+  agentgate approval approve <approvalId> [--url <url>] [--key <apiKey>]
+  agentgate approval deny <approvalId> [reason] [--url <url>] [--key <apiKey>]
+
+By default this talks to a locally running \`agentgate dev\` server at http://localhost:8787.`);
+    process.exitCode = 1;
   }
 } else if (cmd === 'dev') {
   const htmlPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../standalone.html');

package/package.json

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

package/src/mcp-gateway.js

@@ -2,7 +2,7 @@ import http from 'node:http';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { evaluate } from './policy-engine.js';
-import { createApprovalStore, createApprovalRequest, APPROVAL_STATUS } from './approval.js';
+import { createApprovalStore, createApprovalRequest, APPROVAL_STATUS, isApprovalExpired } from './approval.js';
 import { createPersistentRunStore, createPersistentApprovalStore } from './persistent-store.js';
 import { createEventBus } from './event-bus.js';
 import { createTelemetry } from './telemetry.js';
@@ -52,8 +52,12 @@ export function createMCPGateway(options = {}) {
     tools: () => [...tools.keys()],
     runs: (tenantId) => { const all = runStore ? runStore.list() : [...runs]; return tenantId ? all.filter(run => run.tenantId === tenantId) : all; },
     replay: (runId, tenantId) => { const run = runStore ? runStore.get(runId) : (runs.find((item) => item.id === runId) || null); return !tenantId || run?.tenantId === tenantId ? run : null; },
-    approvals: (status, tenantId) => { const all = approvals.list(status); return tenantId ? all.filter(item => item.tenantId === tenantId) : all; },
-    getApproval: (approvalId, tenantId) => { const item = approvals.get(approvalId); return !tenantId || item?.tenantId === tenantId ? item : null; },
+    approvals: (status, tenantId) => {
+      approvals.list(APPROVAL_STATUS.PENDING).forEach(expireIfStale);
+      const all = approvals.list(status);
+      return tenantId ? all.filter(item => item.tenantId === tenantId) : all;
+    },
+    getApproval: (approvalId, tenantId) => { const item = expireIfStale(approvals.get(approvalId)); return !tenantId || item?.tenantId === tenantId ? item : null; },
     approve: (approvalId, tenantId) => resolveApproval(approvalId, true, undefined, tenantId),
     deny: (approvalId, reason, tenantId) => resolveApproval(approvalId, false, reason, tenantId),
     events: eventBus,
@@ -74,6 +78,20 @@ export function createMCPGateway(options = {}) {
 
   for (const tool of options.tools || []) registerTool(tool);
 
+  // Lazily flips a PENDING-but-past-TTL approval to EXPIRED the next time it's
+  // looked at (list/get/approve/deny), so it can never be actioned late.
+  function expireIfStale(approval) {
+    if (!approval || approval.status !== APPROVAL_STATUS.PENDING) return approval;
+    if (!isApprovalExpired(approval)) return approval;
+    approval.status = APPROVAL_STATUS.EXPIRED;
+    approval.resolvedAt = new Date().toISOString();
+    const run = runStore ? runStore.get(approval.runId) : runs.find(item => item.id === approval.runId);
+    if (run) { run.status = 'expired'; run.approval = { status: approval.status, resolvedAt: approval.resolvedAt }; }
+    approvals.save?.();
+    runStore?.save?.();
+    return approval;
+  }
+
   function registerTool(tool) {
     if (!tool?.name || typeof tool.handler !== 'function') {
       throw new TypeError('registerTool() expects { name, handler, description?, inputSchema? }');
@@ -183,6 +201,7 @@ export function createMCPGateway(options = {}) {
         decision: decision.decision,
         risk: decision.risk,
         reason: decision.reason,
+        ttlMs: options.approvalTTLMs,
         metadata: { tool: name, rpcRequestId: id, arguments: clone(input) }
       }, approvals);
       run.status = 'pending_approval';
@@ -245,7 +264,7 @@ export function createMCPGateway(options = {}) {
 
 
   async function resolveApproval(approvalId, approved, denialReason, tenantId) {
-    const approval = approvals.get(approvalId);
+    const approval = expireIfStale(approvals.get(approvalId));
     if (tenantId && approval?.tenantId !== tenantId) return { ok: false, error: 'Approval not found' };
     if (!approval) return { ok: false, error: 'Approval not found' };
     if (approval.status !== APPROVAL_STATUS.PENDING) return { ok: false, error: `Approval is already ${approval.status}`, approval };