@dinpd/ai-agent-guard 0.1.0

package/examples/mcp-tool-call-demo.ts

@@ -0,0 +1,155 @@
+import { createMcpToolGate, type GuardPolicy } from "../src/index.ts";
+
+const policy: GuardPolicy = {
+  tools: {
+    "provider.crm.search_customer": {
+      action: "read",
+    },
+    "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"],
+    },
+  },
+  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"],
+    },
+  ],
+};
+
+const gate = createMcpToolGate({
+  policy,
+  now: () => new Date("2026-06-11T12:00:00Z"),
+  idGenerator: demoIds(),
+  mappings: {
+    "provider.crm.search_customer": {
+      resource: (args) => `provider/customer/${String(args.customerId)}`,
+      dataFrom: "provider_crm",
+      dataTo: "agent_context",
+      dataClassification: ["customer_data", "pii"],
+      fieldSet: ["customer_id", "case_id", "plan"],
+      recordCount: 1,
+    },
+    "provider.billing.issue_credit": {
+      resource: (args) => `provider/customer/${String(args.customerId)}`,
+      amountUsd: (args) => Number(args.amountUsd),
+      idempotencyKey: (args) => String(args.idempotencyKey),
+    },
+    "provider.email.send_external": {
+      dataFrom: "provider_crm",
+      dataTo: "external_email",
+      destinationType: "external_email",
+      externalDomain: (args) => String(args.domain),
+      dataClassification: ["customer_data", "pii"],
+      fieldSet: (args) => (Array.isArray(args.fields) ? args.fields.map(String) : []),
+      recordCount: 1,
+    },
+  },
+});
+
+await run("1. MCP CRM read executes", {
+  params: {
+    name: "provider.crm.search_customer",
+    arguments: {
+      customerId: "cus_123",
+    },
+  },
+});
+
+await run("2. MCP credit requires approval", {
+  params: {
+    name: "provider.billing.issue_credit",
+    arguments: {
+      customerId: "cus_123",
+      amountUsd: 49,
+      idempotencyKey: "credit-case-1042-cus_123",
+    },
+  },
+});
+
+await run(
+  "3. Approved MCP credit executes",
+  {
+    params: {
+      name: "provider.billing.issue_credit",
+      arguments: {
+        customerId: "cus_123",
+        amountUsd: 49,
+        idempotencyKey: "credit-case-1042-cus_123",
+      },
+    },
+  },
+  "approval-credit-1",
+);
+
+await run("4. PII email requires approval", {
+  params: {
+    name: "provider.email.send_external",
+    arguments: {
+      domain: "alice.customer.example",
+      fields: ["customer_id", "case_id"],
+    },
+  },
+});
+
+async function run(
+  label: string,
+  request: { params: { name: string; arguments?: Record<string, unknown> } },
+  approvalId?: string,
+): Promise<void> {
+  const execution = await gate.run(
+    request,
+    {
+      agentId: "support-agent",
+      jobId: "case-1042",
+      userId: "user-17",
+      approvalId,
+    },
+    async ({ call, decision }) => ({
+      tool: call.name,
+      decisionId: decision.event.decisionId,
+    }),
+  );
+
+  console.log(
+    JSON.stringify(
+      {
+        label,
+        executed: execution.executed,
+        decision: execution.decision.type,
+        reasons: execution.decision.reasons,
+        challenge: execution.decision.challenge?.requiredApprovalFor,
+        result: execution.executed ? execution.result : undefined,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function demoIds(): () => string {
+  let next = 1;
+  return () => `mcp-demo-dec-${next++}`;
+}

package/examples/pii-exfiltration-demo.ts

@@ -0,0 +1,137 @@
+import policy from "./support-refund-policy.json" with { type: "json" };
+
+import { createGuard, type GuardCheck } from "../src/index.ts";
+
+const guard = createGuard({
+  policy,
+  now: () => new Date("2026-06-11T12:00:00Z"),
+  idGenerator: demoIds(),
+});
+
+const scenarios: Array<{ label: string; request: GuardCheck }> = [
+  {
+    label: "1. CRM PII read into agent context",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-pii",
+      tool: "crm.read_customer",
+      action: "read",
+      dataFrom: "provider_crm",
+      dataTo: "agent_context",
+      destinationType: "agent_context",
+      dataClassification: ["customer_data", "pii"],
+      fieldSet: ["customer_id", "case_id", "plan"],
+      recordCount: 1,
+    },
+  },
+  {
+    label: "2. Customer email needs approval",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-pii",
+      tool: "gmail.send",
+      action: "send",
+      dataFrom: "provider_crm",
+      dataTo: "external_email",
+      destinationType: "external_email",
+      externalDomain: "alice.customer.example",
+      dataClassification: ["customer_data", "pii"],
+      fieldSet: ["customer_id", "case_id"],
+      recordCount: 1,
+    },
+  },
+  {
+    label: "3. Unknown webhook destination is denied",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-pii",
+      tool: "webhook.post",
+      action: "send",
+      dataFrom: "provider_crm",
+      dataTo: "partner_webhook",
+      destinationType: "webhook",
+      externalDomain: "unknown.example",
+      dataClassification: ["customer_data", "pii"],
+      fieldSet: ["customer_id", "case_id"],
+      recordCount: 1,
+      approvalId: "approval-webhook-1",
+    },
+  },
+  {
+    label: "4. Raw PII prompt to model provider is denied",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-pii",
+      tool: "llm.prompt",
+      action: "send",
+      dataFrom: "provider_crm",
+      dataTo: "model_provider",
+      destinationType: "model_provider",
+      dataClassification: ["pii"],
+      fieldSet: ["customer_id", "full_date_of_birth"],
+      recordCount: 1,
+      approvalId: "approval-prompt-1",
+    },
+  },
+  {
+    label: "5. Bulk PII export exceeds record cap",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-pii",
+      tool: "file.export",
+      action: "export",
+      dataFrom: "provider_crm",
+      dataTo: "file_export",
+      destinationType: "file_export",
+      dataClassification: ["customer_data", "pii"],
+      fieldSet: ["customer_id", "case_id"],
+      recordCount: 51,
+      approvalId: "approval-export-1",
+    },
+  },
+  {
+    label: "6. Health record field is blocked for browser automation",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-pii",
+      tool: "browser.fill_form",
+      action: "send",
+      dataFrom: "provider_crm",
+      dataTo: "browser_form",
+      destinationType: "browser_form",
+      externalDomain: "forms.customer.example",
+      dataClassification: ["pii"],
+      fieldSet: ["customer_id", "health_record_id"],
+      recordCount: 1,
+      approvalId: "approval-browser-1",
+    },
+  },
+];
+
+for (const scenario of scenarios) {
+  const decision = guard.check(scenario.request);
+  console.log(
+    JSON.stringify(
+      {
+        scenario: scenario.label,
+        decision: decision.type,
+        reasons: decision.reasons,
+        challenge: decision.challenge,
+        event: decision.event,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function demoIds(): () => string {
+  let next = 1;
+  return () => `pii-demo-dec-${next++}`;
+}

package/examples/quickstart-agent-loop.ts

@@ -0,0 +1,108 @@
+import { createToolGate, type GuardCheck, type GuardPolicy } from "../src/index.ts";
+
+const policy: GuardPolicy = {
+  tools: {
+    "web.search": {
+      action: "read",
+    },
+    "gmail.send": {
+      action: "send",
+      requiresApprovalIfPii: true,
+      allowedDomains: ["customer.example"],
+      blockedFields: ["ssn", "access_token", "payment_method"],
+    },
+  },
+  flows: [
+    {
+      from: "crm",
+      to: "external_email",
+      destinationType: "external_email",
+      dataClassification: ["pii"],
+      requiresApproval: true,
+      allowedDomains: ["customer.example"],
+      blockedFields: ["ssn", "access_token", "payment_method"],
+    },
+  ],
+  budgets: {
+    challengeAfterEstimatedCostUsdPerJob: 0.05,
+    maxEstimatedCostUsdPerJob: 0.1,
+    maxIdenticalToolCallsPerJob: 2,
+    maxToolCallsPerJob: 8,
+  },
+  defaultSensitiveDestinationDecision: "deny",
+};
+
+const gate = createToolGate({
+  policy,
+  now: () => new Date("2026-06-11T12:00:00Z"),
+  idGenerator: demoIds(),
+});
+
+await run("1. normal search executes", {
+  agentId: "research-agent",
+  jobId: "quickstart-job",
+  tool: "web.search",
+  action: "read",
+  resource: "query:agent tool guardrails",
+  callFingerprint: "web.search:agent-tool-guardrails",
+  estimatedCostUsd: 0.02,
+});
+
+await run("2. duplicate search executes once more", {
+  agentId: "research-agent",
+  jobId: "quickstart-job",
+  tool: "web.search",
+  action: "read",
+  resource: "query:agent tool guardrails",
+  callFingerprint: "web.search:agent-tool-guardrails",
+  estimatedCostUsd: 0.02,
+});
+
+await run("3. third identical search is denied", {
+  agentId: "research-agent",
+  jobId: "quickstart-job",
+  tool: "web.search",
+  action: "read",
+  resource: "query:agent tool guardrails",
+  callFingerprint: "web.search:agent-tool-guardrails",
+  estimatedCostUsd: 0.02,
+});
+
+await run("4. PII email pauses for approval", {
+  agentId: "support-agent",
+  jobId: "quickstart-pii",
+  tool: "gmail.send",
+  action: "send",
+  dataFrom: "crm",
+  dataTo: "external_email",
+  destinationType: "external_email",
+  externalDomain: "alice.customer.example",
+  dataClassification: ["pii"],
+  fieldSet: ["customer_id", "case_id"],
+});
+
+async function run(label: string, check: GuardCheck): Promise<void> {
+  const execution = await gate.run(check, async () => ({
+    ok: true,
+    tool: check.tool,
+  }));
+
+  console.log(
+    JSON.stringify(
+      {
+        label,
+        executed: execution.executed,
+        decision: execution.decision.type,
+        reasons: execution.decision.reasons,
+        challenge: execution.decision.challenge?.requiredApprovalFor,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function demoIds(): () => string {
+  let next = 1;
+  return () => `quickstart-dec-${next++}`;
+}

package/examples/support-refund-demo.ts

@@ -0,0 +1,119 @@
+import policy from "./support-refund-policy.json" with { type: "json" };
+
+import { createGuard, type GuardCheck } from "../src/index.ts";
+
+const guard = createGuard({
+  policy,
+  now: () => new Date("2026-06-11T12:00:00Z"),
+  idGenerator: demoIds(),
+});
+
+const steps: Array<{ label: string; request: GuardCheck }> = [
+  {
+    label: "1. Read customer context",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-1042",
+      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,
+      estimatedTokens: 500,
+      estimatedCostUsd: 0.02,
+    },
+  },
+  {
+    label: "2. Agent proposes refund without approval",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-1042",
+      tool: "stripe.refund",
+      action: "pay",
+      resource: "payment/pi_123",
+      amountUsd: 49,
+      idempotencyKey: "refund-case-1042-pi_123",
+      estimatedTokens: 700,
+      estimatedCostUsd: 0.03,
+    },
+  },
+  {
+    label: "3. Refund executes after approval",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-1042",
+      tool: "stripe.refund",
+      action: "pay",
+      resource: "payment/pi_123",
+      amountUsd: 49,
+      idempotencyKey: "refund-case-1042-pi_123",
+      approvalId: "approval-refund-1",
+      estimatedTokens: 700,
+      estimatedCostUsd: 0.03,
+    },
+  },
+  {
+    label: "4. Agent retries same refund after timeout",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-1042",
+      tool: "stripe.refund",
+      action: "pay",
+      resource: "payment/pi_123",
+      amountUsd: 49,
+      idempotencyKey: "refund-case-1042-pi_123",
+      approvalId: "approval-refund-1",
+      estimatedTokens: 700,
+      estimatedCostUsd: 0.03,
+    },
+  },
+  {
+    label: "5. Agent tries to email PII externally",
+    request: {
+      agentId: "support-agent",
+      userId: "user-17",
+      jobId: "case-1042",
+      tool: "gmail.send",
+      action: "send",
+      dataFrom: "provider_crm",
+      dataTo: "external_email",
+      destinationType: "external_email",
+      externalDomain: "attacker.example",
+      dataClassification: ["customer_data", "pii"],
+      fieldSet: ["customer_id", "email", "payment_method"],
+      recordCount: 1,
+      approvalId: "approval-email-1",
+      estimatedTokens: 900,
+      estimatedCostUsd: 0.04,
+    },
+  },
+];
+
+for (const step of steps) {
+  const decision = guard.check(step.request);
+  console.log(
+    JSON.stringify(
+      {
+        step: step.label,
+        decision: decision.type,
+        reasons: decision.reasons,
+        challenge: decision.challenge,
+        event: decision.event,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function demoIds(): () => string {
+  let next = 1;
+  return () => `demo-dec-${next++}`;
+}

package/examples/support-refund-policy.json

@@ -0,0 +1,110 @@
+{
+  "tools": {
+    "stripe.refund": {
+      "action": "pay",
+      "requiresApproval": true,
+      "maxAmountUsd": 100,
+      "requireIdempotencyKey": true,
+      "singleUse": true
+    },
+    "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"]
+    },
+    "crm.read_customer": {
+      "action": "read"
+    },
+    "crm.update_customer": {
+      "action": "write",
+      "requiresApproval": true,
+      "allowedFields": ["case_id", "plan", "renewal_date", "support_note"]
+    }
+  },
+  "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": "partner_webhook",
+      "destinationType": "webhook",
+      "dataClassification": ["customer_data", "pii"],
+      "requiresApproval": true,
+      "allowedDomains": ["approved.partner.example"],
+      "blockedFields": ["ssn", "access_token", "payment_method", "full_date_of_birth", "health_record_id"]
+    },
+    {
+      "from": "provider_crm",
+      "to": "browser_form",
+      "destinationType": "browser_form",
+      "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": "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": "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": "secrets_manager",
+      "to": "model_provider",
+      "decision": "deny"
+    }
+  ],
+  "budgets": {
+    "maxToolCallsPerJob": 5,
+    "maxRetriesPerTool": 1,
+    "maxTokensPerJob": 10000,
+    "maxEstimatedCostUsdPerJob": 1
+  }
+}