@dinpd/ai-agent-guard 0.1.0

package/examples/tool-gate-demo.ts

@@ -0,0 +1,95 @@
+import policy from "./support-refund-policy.json" with { type: "json" };
+
+import { createToolGate, type GuardCheck } from "../src/index.ts";
+
+const gate = createToolGate({
+  policy,
+  now: () => new Date("2026-06-11T12:00:00Z"),
+  idGenerator: demoIds(),
+});
+
+const tools = {
+  "crm.read_customer": async (input: { customerId: string }) => ({
+    customerId: input.customerId,
+    caseId: "case-1042",
+    plan: "pro",
+  }),
+  "stripe.refund": async (input: { paymentId: string; amountUsd: number }) => ({
+    refundId: "re_123",
+    paymentId: input.paymentId,
+    amountUsd: input.amountUsd,
+  }),
+};
+
+await runTool(
+  "Allowed CRM read",
+  {
+    agentId: "support-agent",
+    userId: "user-17",
+    jobId: "case-gate",
+    tool: "crm.read_customer",
+    action: "read",
+    resource: "customer/cus_123",
+    dataFrom: "provider_crm",
+    dataTo: "agent_context",
+    dataClassification: ["customer_data"],
+    fieldSet: ["customer_id", "case_id", "plan"],
+    recordCount: 1,
+  },
+  () => tools["crm.read_customer"]({ customerId: "cus_123" }),
+);
+
+await runTool(
+  "Refund pauses for approval",
+  {
+    agentId: "support-agent",
+    userId: "user-17",
+    jobId: "case-gate",
+    tool: "stripe.refund",
+    action: "pay",
+    resource: "payment/pi_123",
+    amountUsd: 49,
+    idempotencyKey: "refund-case-gate-pi_123",
+  },
+  () => tools["stripe.refund"]({ paymentId: "pi_123", amountUsd: 49 }),
+);
+
+await runTool(
+  "Unknown tool is blocked",
+  {
+    agentId: "support-agent",
+    userId: "user-17",
+    jobId: "case-gate",
+    tool: "shell.exec",
+    action: "admin",
+    resource: "prod-host",
+  },
+  async () => ({ output: "this callback is never invoked" }),
+);
+
+async function runTool<TResult>(
+  label: string,
+  check: GuardCheck,
+  execute: () => Promise<TResult>,
+): Promise<void> {
+  const execution = await gate.run(check, execute);
+  console.log(
+    JSON.stringify(
+      {
+        label,
+        executed: execution.executed,
+        decision: execution.decision.type,
+        reasons: execution.decision.reasons,
+        challenge: execution.decision.challenge,
+        result: execution.executed ? execution.result : undefined,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function demoIds(): () => string {
+  let next = 1;
+  return () => `gate-demo-dec-${next++}`;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@dinpd/ai-agent-guard",
+  "version": "0.1.0",
+  "description": "Runtime authorization guard for AI agent tool calls.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "policies",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dinpd/AgentPass.git",
+    "directory": "packages/guard"
+  },
+  "bugs": {
+    "url": "https://github.com/dinpd/AgentPass/issues"
+  },
+  "homepage": "https://github.com/dinpd/AgentPass/tree/main/packages/guard#readme",
+  "keywords": [
+    "ai-agents",
+    "agent",
+    "guardrails",
+    "tool-calling",
+    "mcp",
+    "authorization",
+    "policy",
+    "pii",
+    "circuit-breaker"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test && npm run build",
+    "demo:quickstart": "node --import tsx examples/quickstart-agent-loop.ts",
+    "demo:circuit": "node --import tsx examples/circuit-breaker-demo.ts",
+    "demo:mcp": "node --import tsx examples/mcp-tool-call-demo.ts",
+    "demo": "node --import tsx examples/support-refund-demo.ts",
+    "demo:gate": "node --import tsx examples/tool-gate-demo.ts",
+    "demo:pii": "node --import tsx examples/pii-exfiltration-demo.ts",
+    "test": "node --test --import tsx tests/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}

package/policies/mcp-tool-gateway.json

@@ -0,0 +1,50 @@
+{
+  "tools": {
+    "provider.crm.search_customer": {
+      "action": "read"
+    },
+    "provider.crm.update_customer": {
+      "action": "write",
+      "requiresApproval": true,
+      "allowedFields": ["customer_id", "case_id", "support_note", "plan"]
+    },
+    "provider.billing.issue_credit": {
+      "action": "pay",
+      "requiresApproval": true,
+      "maxAmountUsd": 100,
+      "requireIdempotencyKey": true,
+      "singleUse": true
+    },
+    "provider.email.send_external": {
+      "action": "send",
+      "requiresApprovalIfPii": true,
+      "allowedDomains": ["customer.example"],
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth"]
+    }
+  },
+  "flows": [
+    {
+      "from": "provider_crm",
+      "to": "agent_context",
+      "dataClassification": ["customer_data", "pii"],
+      "allowedFields": ["customer_id", "case_id", "plan"],
+      "maxRecords": 10
+    },
+    {
+      "from": "provider_crm",
+      "to": "external_email",
+      "destinationType": "external_email",
+      "dataClassification": ["customer_data", "pii"],
+      "requiresApproval": true,
+      "allowedDomains": ["customer.example"],
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth"]
+    }
+  ],
+  "budgets": {
+    "maxToolCallsPerJob": 15,
+    "maxSameToolCallsPerJob": 6,
+    "maxIdenticalToolCallsPerJob": 2,
+    "maxEstimatedCostUsdPerJob": 1
+  },
+  "defaultSensitiveDestinationDecision": "deny"
+}

package/policies/pii-egress.json

@@ -0,0 +1,75 @@
+{
+  "tools": {
+    "crm.read_customer": {
+      "action": "read"
+    },
+    "gmail.send": {
+      "action": "send",
+      "requiresApprovalIfPii": true,
+      "allowedDomains": ["customer.example"],
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    "webhook.post": {
+      "action": "send",
+      "requiresApprovalIfPii": true,
+      "allowedDomains": ["approved.partner.example"],
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    "llm.prompt": {
+      "action": "send",
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    "file.export": {
+      "action": "export",
+      "requiresApprovalIfPii": true,
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    "browser.fill_form": {
+      "action": "send",
+      "requiresApprovalIfPii": true,
+      "allowedDomains": ["customer.example"],
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    }
+  },
+  "flows": [
+    {
+      "from": "provider_crm",
+      "to": "agent_context",
+      "dataClassification": ["customer_data", "pii"],
+      "allowedFields": ["customer_id", "case_id", "plan", "renewal_date"],
+      "maxRecords": 10
+    },
+    {
+      "from": "provider_crm",
+      "to": "external_email",
+      "destinationType": "external_email",
+      "dataClassification": ["customer_data", "pii"],
+      "requiresApproval": true,
+      "allowedDomains": ["customer.example"],
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    {
+      "from": "provider_crm",
+      "to": "model_provider",
+      "destinationType": "model_provider",
+      "dataClassification": ["pii"],
+      "decision": "deny",
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    {
+      "from": "provider_crm",
+      "to": "file_export",
+      "destinationType": "file_export",
+      "dataClassification": ["customer_data", "pii"],
+      "requiresApproval": true,
+      "maxRecords": 50,
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    {
+      "from": "secrets_manager",
+      "to": "model_provider",
+      "decision": "deny"
+    }
+  ],
+  "defaultSensitiveDestinationDecision": "deny"
+}

package/policies/refund-payment.json

@@ -0,0 +1,26 @@
+{
+  "tools": {
+    "stripe.refund": {
+      "action": "pay",
+      "requiresApproval": true,
+      "maxAmountUsd": 100,
+      "requireIdempotencyKey": true,
+      "singleUse": true
+    },
+    "crm.read_customer": {
+      "action": "read"
+    },
+    "crm.update_customer": {
+      "action": "write",
+      "requiresApproval": true,
+      "allowedFields": ["case_id", "plan", "renewal_date", "support_note"]
+    }
+  },
+  "budgets": {
+    "maxToolCallsPerJob": 10,
+    "maxSameToolCallsPerJob": 4,
+    "maxIdenticalToolCallsPerJob": 2,
+    "maxRetriesPerTool": 1,
+    "maxEstimatedCostUsdPerJob": 1
+  }
+}

package/policies/shell-browser-guard.json

@@ -0,0 +1,55 @@
+{
+  "tools": {
+    "browser.open": {
+      "action": "read",
+      "allowedDomains": ["docs.example", "github.com"]
+    },
+    "browser.fill_form": {
+      "action": "send",
+      "requiresApprovalIfPii": true,
+      "allowedDomains": ["customer.example"],
+      "blockedFields": ["password", "access_token", "api_key", "ssn", "payment_method"]
+    },
+    "shell.exec": {
+      "action": "admin",
+      "requiresApproval": true,
+      "blockedFields": ["api_key", "access_token", "password", "private_key"]
+    },
+    "file.write": {
+      "action": "write",
+      "requiresApproval": true,
+      "blockedFields": ["api_key", "access_token", "password", "private_key"]
+    }
+  },
+  "flows": [
+    {
+      "from": "secrets_manager",
+      "to": "model_provider",
+      "decision": "deny"
+    },
+    {
+      "from": "local_files",
+      "to": "external_email",
+      "destinationType": "external_email",
+      "dataClassification": ["secret", "regulated"],
+      "decision": "deny"
+    },
+    {
+      "from": "local_files",
+      "to": "browser_form",
+      "destinationType": "browser_form",
+      "dataClassification": ["pii", "secret"],
+      "requiresApproval": true,
+      "allowedDomains": ["customer.example"],
+      "blockedFields": ["password", "access_token", "api_key", "ssn", "payment_method"]
+    }
+  ],
+  "budgets": {
+    "challengeAfterRuntimeMsPerJob": 120000,
+    "maxRuntimeMsPerJob": 300000,
+    "maxToolCallsPerJob": 20,
+    "maxSameToolCallsPerJob": 8,
+    "maxIdenticalToolCallsPerJob": 2
+  },
+  "defaultSensitiveDestinationDecision": "deny"
+}

package/policies/tool-spend-cap.json

@@ -0,0 +1,24 @@
+{
+  "tools": {
+    "web.search": {
+      "action": "read"
+    },
+    "llm.complete": {
+      "action": "send"
+    },
+    "browser.open": {
+      "action": "read"
+    }
+  },
+  "budgets": {
+    "challengeAfterToolCallsPerJob": 8,
+    "challengeAfterTokensPerJob": 12000,
+    "challengeAfterEstimatedCostUsdPerJob": 0.75,
+    "maxToolCallsPerJob": 15,
+    "maxSameToolCallsPerJob": 6,
+    "maxIdenticalToolCallsPerJob": 2,
+    "maxRetriesPerTool": 2,
+    "maxTokensPerJob": 20000,
+    "maxEstimatedCostUsdPerJob": 1
+  }
+}