agentgate-runtime-control 2.13.9 → 2.13.11

package/README.md

@@ -52,9 +52,20 @@ docker run --rm -p 8787:8787 agentgate
 
 ### Examples
 
+- `examples/protect-first-tool.mjs` — protect four real tools in one file (`read_customer` → ALLOW, `delete_customer` → ASK, `refund` → ASK/BLOCK by amount, `export_all` → BLOCK). Start here.
 - `examples/refund-agent.mjs` — protect a real side-effecting refund tool.
 - `examples/policy-bundle.mjs` — test and activate a versioned policy bundle.
 
+### Test your own tools against Attack Lab
+
+By default, `agentgate attack` runs the built-in attack scenarios against AgentGate's default policies. To test them against **your own** `agentgate.config.mjs` (the policies you actually ship with), pass `--config`:
+
+```bash
+agentgate attack --config ./agentgate.config.mjs
+```
+
+The config file must export an `agentgate` object created with `createAgentGate()` (exactly what `agentgate init` generates).
+
 ## Production readiness
 
 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.

package/examples/protect-first-tool.mjs

@@ -0,0 +1,83 @@
+// Protect your first real tool with AgentGate.
+//
+// The flow AgentGate sits in:
+//
+//   AI Agent  ─────▶  AgentGate  ─────▶  Tool / API  ─────▶  External system
+//                     (ALLOW/ASK/BLOCK
+//                      decided here,
+//                      BEFORE the tool
+//                      handler runs)
+//
+// This example wraps four tools an agent might call and shows the
+// decision each one gets under a simple, realistic policy:
+//
+//   read_customer   -> ALLOW  (read-only, no side effects)
+//   delete_customer -> ASK    (destructive, always needs a human to approve)
+//   refund          -> ASK below $5,000, BLOCK above $5,000
+//   export_all      -> BLOCK  (bulk data export, always blocked)
+//
+// Note that "destructive" tools (delete, refund, publish, export_all,
+// update_production, deploy) always require at least ASK — there is no
+// amount small enough to skip approval entirely for them. That is
+// deliberate: this policy engine treats "asks for approval" as the safe
+// default for anything with a side effect, not just anything expensive.
+//
+// Run it with:
+//   node examples/protect-first-tool.mjs
+
+import { createAgentGate } from 'agentgate-runtime-control';
+
+const gate = createAgentGate({
+  agent: 'SupportAgent',
+  mode: 'enforce',
+  policies: {
+    productionBlock: true,       // in production, destructive actions are blocked outright (not even ASK)
+    approvalAmount: 5000,        // refunds above this amount are always BLOCKed, no approval possible
+    blockActions: ['export_all'] // export_all is blocked regardless of amount/environment
+  }
+});
+
+// --- The real tool handlers your agent would otherwise call directly ---
+async function readCustomer({ customerId }) {
+  return { customerId, name: 'Jane Doe', plan: 'pro' };
+}
+async function deleteCustomer({ customerId }) {
+  return { deleted: customerId };
+}
+async function refund({ amount, customerId }) {
+  return { refunded: amount, customerId };
+}
+async function exportAll() {
+  return { exportedRows: 1_000_000 };
+}
+
+// --- Wrap each one with agentgate.protect() before the agent ever sees it ---
+const protectedReadCustomer = gate.protect(readCustomer, { tool: 'read_customer', action: 'read' });
+const protectedDeleteCustomer = gate.protect(deleteCustomer, { tool: 'delete_customer', action: 'delete' });
+const protectedRefund = gate.protect(refund, { tool: 'refund', action: 'refund' });
+const protectedExportAll = gate.protect(exportAll, { tool: 'export_all', action: 'export_all' });
+
+async function tryCall(label, fn, input) {
+  try {
+    const result = await fn(input, input);
+    console.log(`${label.padEnd(24)} -> ${result.status.toUpperCase()} (${result.agentgate.decision}) — ${result.agentgate.reason}`);
+  } catch (error) {
+    console.log(`${label.padEnd(24)} -> BLOCKED (${error.agentgate?.decision}) — ${error.agentgate?.reason}`);
+  }
+}
+
+// environment: 'development' lets the amount/action-based rules below decide
+// (ASK vs ALLOW vs BLOCK). In production, productionBlock:true would block
+// every destructive action outright — try changing this to 'production' and
+// re-running to see that stricter behavior.
+const env = 'development';
+
+console.log('AgentGate — protecting four real tools\n');
+await tryCall('read_customer', protectedReadCustomer, { customerId: 'cus_123', environment: env });
+await tryCall('delete_customer', protectedDeleteCustomer, { customerId: 'cus_123', environment: env });
+await tryCall('refund (small)', protectedRefund, { amount: 250, customerId: 'cus_123', environment: env });
+await tryCall('refund (large)', protectedRefund, { amount: 8000, customerId: 'cus_123', environment: env });
+await tryCall('export_all', protectedExportAll, { environment: env });
+
+console.log('\nNothing above BLOCK or pending ASK ever reached its real handler.');
+console.log('See gate.approvals() to review and approve pending ASK requests.');

package/package.json

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

package/src/approval.js

@@ -12,10 +12,18 @@ export class ApprovalStore {
 
 export function createApprovalStore(options = {}) { return options.store || new ApprovalStore(options.limit || 500); }
 
+// Default: a pending approval expires after 15 minutes if nobody acts on it.
+// Pass ttlMs: null (or 0) to disable expiry for a given request.
+export const DEFAULT_APPROVAL_TTL_MS = 15 * 60 * 1000;
+
 export function createApprovalRequest(data = {}, store = new ApprovalStore()) {
+  const createdAt = new Date();
+  const ttlMs = data.ttlMs === undefined ? DEFAULT_APPROVAL_TTL_MS : data.ttlMs;
+  const expiresAt = ttlMs ? new Date(createdAt.getTime() + ttlMs).toISOString() : null;
   return store.add({
     id: data.id || `approval_${randomUUID()}`,
-    createdAt: new Date().toISOString(),
+    createdAt: createdAt.toISOString(),
+    expiresAt,
     status: APPROVAL_STATUS.PENDING,
     runId: data.runId,
     tenantId: data.tenantId || data.request?.tenantId || null,
@@ -27,4 +35,13 @@ export function createApprovalRequest(data = {}, store = new ApprovalStore()) {
   });
 }
 
+// A pending approval is expired once `expiresAt` has passed. Every approval
+// is single-use by construction: approve()/deny() flip `status` away from
+// PENDING synchronously (before any await), so a second call — concurrent
+// or not — always sees a non-pending status and is rejected. There is no
+// separate "already used" flag to track.
+export function isApprovalExpired(approval, now = Date.now()) {
+  return Boolean(approval?.expiresAt) && new Date(approval.expiresAt).getTime() <= now;
+}
+
 function clone(value) { try { return structuredClone(value); } catch { return JSON.parse(JSON.stringify(value)); } }

package/src/runtime.js

@@ -1,6 +1,6 @@
 import { evaluate } from './policy-engine.js';
 import { createPersistentRunStore, createPersistentApprovalStore } from './persistent-store.js';
-import { createApprovalStore, createApprovalRequest, APPROVAL_STATUS } from './approval.js';
+import { createApprovalStore, createApprovalRequest, APPROVAL_STATUS, isApprovalExpired } from './approval.js';
 
 export class RunStore {
   constructor(limit = 25000) { this.limit = limit; this.runs = []; }
@@ -45,6 +45,7 @@ export function createRuntime(options = {}) {
           decision: event.decision,
           risk: event.risk,
           reason: event.reason,
+          ttlMs: options.approvalTTLMs,
           metadata: { action: request.action || request.tool || null }
         }, approvalStore);
         event.status = 'pending_approval';
@@ -65,11 +66,28 @@ export function createRuntime(options = {}) {
     return { status: 'executed', value, agentgate: event };
   }
 
-  function approvals(status) { return approvalStore.list(status); }
-  function getApproval(id) { return approvalStore.get(id); }
+  // Lazily flips a PENDING-but-expired approval to EXPIRED and drops its
+  // pending execution, so a stale approval 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 item = pending.get(approval.id);
+    if (item) { item.event.status = 'expired'; item.event.approval = { status: approval.status, resolvedAt: approval.resolvedAt }; }
+    pending.delete(approval.id);
+    approvalStore.save?.();
+    return approval;
+  }
+
+  function approvals(status) {
+    approvalStore.list(APPROVAL_STATUS.PENDING).forEach(expireIfStale);
+    return approvalStore.list(status);
+  }
+  function getApproval(id) { return expireIfStale(approvalStore.get(id)); }
 
   async function approve(approvalId) {
-    const approval = approvalStore.get(approvalId);
+    const approval = expireIfStale(approvalStore.get(approvalId));
     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 };
     const item = pending.get(approvalId);
@@ -99,7 +117,7 @@ export function createRuntime(options = {}) {
   }
 
   function deny(approvalId, reason = 'Denied by approver') {
-    const approval = approvalStore.get(approvalId);
+    const approval = expireIfStale(approvalStore.get(approvalId));
     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 };
     const item = pending.get(approvalId);