@dinpd/ai-agent-guard 0.1.0

package/dist/index.js

@@ -0,0 +1,443 @@
+const DEFAULT_SENSITIVE_CLASSIFICATIONS = [
+    "pii",
+    "phi",
+    "payment",
+    "secret",
+    "regulated",
+    "customer_data",
+];
+const DEFAULT_SENSITIVE_DESTINATIONS = [
+    "external_email",
+    "webhook",
+    "third_party_saas",
+    "file_export",
+    "model_provider",
+    "browser_form",
+];
+export class AgentPassGuard {
+    policy;
+    now;
+    idGenerator;
+    usedIdempotencyKeys = new Set();
+    usageByJob = new Map();
+    constructor(options) {
+        this.policy = options.policy;
+        this.now = options.now || (() => new Date());
+        this.idGenerator = options.idGenerator || randomDecisionId;
+    }
+    check(input) {
+        const reasons = [];
+        const challengeFor = new Set();
+        const toolPolicy = this.policy.tools?.[input.tool];
+        if (!toolPolicy) {
+            reasons.push(`tool is not declared: ${input.tool}`);
+            return this.decision("deny", input, reasons);
+        }
+        this.evaluateToolPolicy(input, toolPolicy, reasons, challengeFor);
+        this.evaluateFlowPolicy(input, toolPolicy, reasons, challengeFor);
+        this.evaluateBudgetPolicy(input, reasons, challengeFor);
+        if (reasons.length > 0)
+            return this.decision("deny", input, reasons);
+        if (challengeFor.size > 0) {
+            return this.decision("challenge_required", input, ["approval is required"], challengeFor);
+        }
+        this.commit(input, toolPolicy);
+        return this.decision("allow", input, []);
+    }
+    reset() {
+        this.usedIdempotencyKeys.clear();
+        this.usageByJob.clear();
+    }
+    evaluateToolPolicy(input, policy, reasons, challengeFor) {
+        if (policy.action && policy.action !== input.action) {
+            reasons.push(`tool action mismatch: expected ${policy.action}, got ${input.action}`);
+        }
+        if (policy.maxAmountUsd !== undefined && input.amountUsd !== undefined && input.amountUsd > policy.maxAmountUsd) {
+            reasons.push(`amount exceeds maxAmountUsd ${policy.maxAmountUsd}`);
+        }
+        if (policy.requireIdempotencyKey && !input.idempotencyKey) {
+            reasons.push("idempotencyKey is required");
+        }
+        if (policy.singleUse && input.idempotencyKey && this.usedIdempotencyKeys.has(input.idempotencyKey)) {
+            reasons.push("idempotencyKey was already used");
+        }
+        if (policy.allowedDomains && input.externalDomain && !matchesAnyDomain(input.externalDomain, policy.allowedDomains)) {
+            reasons.push(`externalDomain is not allowed: ${input.externalDomain}`);
+        }
+        for (const field of presentBlockedFields(input.fieldSet, policy.blockedFields)) {
+            reasons.push(`field is blocked: ${field}`);
+        }
+        for (const field of absentAllowedFields(input.fieldSet, policy.allowedFields)) {
+            reasons.push(`field is not allowed: ${field}`);
+        }
+        if (policy.requiresApproval && !input.approvalId) {
+            challengeFor.add("tool");
+        }
+        if (policy.requiresApprovalIfPii && hasSensitiveData(input, this.policy) && !input.approvalId) {
+            challengeFor.add("pii");
+        }
+    }
+    evaluateFlowPolicy(input, toolPolicy, reasons, challengeFor) {
+        if (!input.dataFrom || !input.dataTo) {
+            if (hasSensitiveData(input, this.policy) && isSensitiveDestination(input, this.policy)) {
+                reasons.push("dataFrom and dataTo are required for sensitive data movement");
+            }
+            return;
+        }
+        const flow = this.policy.flows?.find((candidate) => matchesFlow(candidate, input));
+        if (flow) {
+            if (flow.decision === "deny")
+                reasons.push(`flow is denied: ${input.dataFrom} -> ${input.dataTo}`);
+            if (flow.maxRecords !== undefined && input.recordCount !== undefined && input.recordCount > flow.maxRecords) {
+                reasons.push(`recordCount exceeds maxRecords ${flow.maxRecords}`);
+            }
+            if (flow.allowedDomains && input.externalDomain && !matchesAnyDomain(input.externalDomain, flow.allowedDomains)) {
+                reasons.push(`externalDomain is not allowed for flow: ${input.externalDomain}`);
+            }
+            for (const field of presentBlockedFields(input.fieldSet, flow.blockedFields)) {
+                reasons.push(`field is blocked by flow: ${field}`);
+            }
+            for (const field of absentAllowedFields(input.fieldSet, flow.allowedFields)) {
+                reasons.push(`field is not allowed by flow: ${field}`);
+            }
+            if (flow.requiresApproval && !input.approvalId)
+                challengeFor.add("flow");
+            return;
+        }
+        if (hasSensitiveData(input, this.policy) && isSensitiveDestination(input, this.policy)) {
+            const defaultDecision = this.policy.defaultSensitiveDestinationDecision || "deny";
+            if (defaultDecision === "deny") {
+                reasons.push(`sensitive data movement has no allowed flow: ${input.dataFrom} -> ${input.dataTo}`);
+            }
+            else if (defaultDecision === "challenge_required" && !input.approvalId) {
+                challengeFor.add("pii");
+            }
+        }
+        if (toolPolicy.requiresApprovalIfPii && hasSensitiveData(input, this.policy) && !input.approvalId) {
+            challengeFor.add("pii");
+        }
+    }
+    evaluateBudgetPolicy(input, reasons, challengeFor) {
+        const budget = this.policy.budgets;
+        if (!budget || !input.jobId)
+            return;
+        const nowMs = this.now().getTime();
+        const usage = this.usageByJob.get(input.jobId) || newJobUsage(nowMs);
+        const nextToolCalls = usage.toolCalls + 1;
+        const nextSameToolCalls = (usage.toolCallsByName.get(input.tool) || 0) + 1;
+        const nextTokens = usage.tokens + (input.estimatedTokens || 0);
+        const nextCost = usage.estimatedCostUsd + (input.estimatedCostUsd || 0);
+        const nextRuntimeMs = nowMs - usage.startedAtMs;
+        const attemptKey = attemptKeyFor(input);
+        const attempts = (usage.toolAttempts.get(attemptKey) || 0) + 1;
+        if (!input.approvalId) {
+            if (budget.challengeAfterToolCallsPerJob !== undefined &&
+                nextToolCalls > budget.challengeAfterToolCallsPerJob) {
+                challengeFor.add("budget");
+            }
+            if (budget.challengeAfterTokensPerJob !== undefined && nextTokens > budget.challengeAfterTokensPerJob) {
+                challengeFor.add("budget");
+            }
+            if (budget.challengeAfterEstimatedCostUsdPerJob !== undefined &&
+                nextCost > budget.challengeAfterEstimatedCostUsdPerJob) {
+                challengeFor.add("budget");
+            }
+            if (budget.challengeAfterRuntimeMsPerJob !== undefined && nextRuntimeMs > budget.challengeAfterRuntimeMsPerJob) {
+                challengeFor.add("budget");
+            }
+        }
+        if (budget.maxToolCallsPerJob !== undefined && nextToolCalls > budget.maxToolCallsPerJob) {
+            reasons.push(`job exceeds maxToolCallsPerJob ${budget.maxToolCallsPerJob}`);
+        }
+        if (budget.maxSameToolCallsPerJob !== undefined && nextSameToolCalls > budget.maxSameToolCallsPerJob) {
+            reasons.push(`job exceeds maxSameToolCallsPerJob ${budget.maxSameToolCallsPerJob}`);
+        }
+        if (budget.maxIdenticalToolCallsPerJob !== undefined && attempts > budget.maxIdenticalToolCallsPerJob) {
+            reasons.push(`job exceeds maxIdenticalToolCallsPerJob ${budget.maxIdenticalToolCallsPerJob}`);
+        }
+        if (budget.maxTokensPerJob !== undefined && nextTokens > budget.maxTokensPerJob) {
+            reasons.push(`job exceeds maxTokensPerJob ${budget.maxTokensPerJob}`);
+        }
+        if (budget.maxEstimatedCostUsdPerJob !== undefined && nextCost > budget.maxEstimatedCostUsdPerJob) {
+            reasons.push(`job exceeds maxEstimatedCostUsdPerJob ${budget.maxEstimatedCostUsdPerJob}`);
+        }
+        if (budget.maxRuntimeMsPerJob !== undefined && nextRuntimeMs > budget.maxRuntimeMsPerJob) {
+            reasons.push(`job exceeds maxRuntimeMsPerJob ${budget.maxRuntimeMsPerJob}`);
+        }
+        if (budget.maxRetriesPerTool !== undefined && attempts > budget.maxRetriesPerTool + 1) {
+            reasons.push(`tool exceeds maxRetriesPerTool ${budget.maxRetriesPerTool}`);
+        }
+    }
+    commit(input, toolPolicy) {
+        if (toolPolicy.singleUse && input.idempotencyKey) {
+            this.usedIdempotencyKeys.add(input.idempotencyKey);
+        }
+        if (!input.jobId)
+            return;
+        const usage = this.usageByJob.get(input.jobId) || newJobUsage(this.now().getTime());
+        usage.toolCalls += 1;
+        usage.tokens += input.estimatedTokens || 0;
+        usage.estimatedCostUsd += input.estimatedCostUsd || 0;
+        const attemptKey = attemptKeyFor(input);
+        usage.toolAttempts.set(attemptKey, (usage.toolAttempts.get(attemptKey) || 0) + 1);
+        usage.toolCallsByName.set(input.tool, (usage.toolCallsByName.get(input.tool) || 0) + 1);
+        this.usageByJob.set(input.jobId, usage);
+    }
+    decision(type, input, reasons, challengeFor = new Set()) {
+        const uniqueReasons = [...new Set(reasons)];
+        const event = this.event(type, input, uniqueReasons);
+        return {
+            type,
+            allow: type === "allow",
+            challengeRequired: type === "challenge_required",
+            reasons: uniqueReasons,
+            challenge: type === "challenge_required"
+                ? {
+                    reason: uniqueReasons[0] || "approval is required",
+                    requiredApprovalFor: [...challengeFor],
+                    tool: input.tool,
+                    action: input.action,
+                    resource: input.resource,
+                    amountUsd: input.amountUsd,
+                    dataFrom: input.dataFrom,
+                    dataTo: input.dataTo,
+                    externalDomain: input.externalDomain,
+                }
+                : undefined,
+            event,
+        };
+    }
+    event(type, input, reasons) {
+        return {
+            decisionId: this.idGenerator(),
+            decision: type,
+            allowed: type === "allow",
+            reasons,
+            agentId: input.agentId,
+            tool: input.tool,
+            action: input.action,
+            jobId: input.jobId,
+            userId: input.userId,
+            resource: input.resource,
+            callFingerprint: input.callFingerprint,
+            amountUsd: input.amountUsd,
+            idempotencyKey: input.idempotencyKey,
+            approvalId: input.approvalId,
+            dataFrom: input.dataFrom,
+            dataTo: input.dataTo,
+            destinationType: input.destinationType,
+            externalDomain: input.externalDomain,
+            dataClassification: input.dataClassification || [],
+            fieldSet: input.fieldSet || [],
+            recordCount: input.recordCount,
+            estimatedTokens: input.estimatedTokens,
+            estimatedCostUsd: input.estimatedCostUsd,
+            issuedAt: this.now().toISOString(),
+        };
+    }
+}
+export function createGuard(options) {
+    return new AgentPassGuard(options);
+}
+export class AgentPassToolGate {
+    guard;
+    constructor(options) {
+        this.guard = "guard" in options ? options.guard : new AgentPassGuard(options);
+    }
+    check(input) {
+        return this.guard.check(input);
+    }
+    async run(input, execute) {
+        const decision = this.guard.check(input);
+        if (!decision.allow) {
+            return {
+                executed: false,
+                decision,
+            };
+        }
+        const result = await execute({ check: input, decision });
+        return {
+            executed: true,
+            decision,
+            result,
+        };
+    }
+    reset() {
+        this.guard.reset();
+    }
+}
+export function createToolGate(options) {
+    return new AgentPassToolGate(options);
+}
+export class AgentPassMcpToolGate {
+    gate;
+    mappings;
+    defaultAction;
+    constructor(options) {
+        this.gate = "guard" in options ? new AgentPassToolGate({ guard: options.guard }) : new AgentPassToolGate(options);
+        this.mappings = options.mappings || {};
+        this.defaultAction = options.defaultAction || "read";
+    }
+    check(callOrRequest, context) {
+        return this.gate.check(this.toGuardCheck(callOrRequest, context));
+    }
+    async run(callOrRequest, context, execute) {
+        const call = normalizeMcpToolCall(callOrRequest);
+        const check = this.toGuardCheck(call, context);
+        return this.gate.run(check, ({ decision }) => execute({
+            check,
+            decision,
+            call,
+            arguments: call.arguments || {},
+        }));
+    }
+    toGuardCheck(callOrRequest, context) {
+        return mcpToolCallToGuardCheck(callOrRequest, context, {
+            mappings: this.mappings,
+            defaultAction: this.defaultAction,
+        });
+    }
+    reset() {
+        this.gate.reset();
+    }
+}
+export function createMcpToolGate(options) {
+    return new AgentPassMcpToolGate(options);
+}
+export function mcpToolCallToGuardCheck(callOrRequest, context, options = {}) {
+    const call = normalizeMcpToolCall(callOrRequest);
+    const args = call.arguments || {};
+    const mapping = options.mappings?.[call.name] || {};
+    const action = readMcpMappedValue(mapping.action, args, call, context) || inferMcpAction(call.name, options.defaultAction);
+    return {
+        agentId: context.agentId,
+        jobId: context.jobId,
+        userId: context.userId,
+        approvalId: context.approvalId,
+        retryCount: context.retryCount,
+        tool: call.name,
+        action,
+        resource: readMcpMappedValue(mapping.resource, args, call, context),
+        callFingerprint: readMcpMappedValue(mapping.callFingerprint, args, call, context) || `${call.name}:${stableStringify(args)}`,
+        amountUsd: readMcpMappedValue(mapping.amountUsd, args, call, context),
+        idempotencyKey: readMcpMappedValue(mapping.idempotencyKey, args, call, context),
+        dataFrom: readMcpMappedValue(mapping.dataFrom, args, call, context),
+        dataTo: readMcpMappedValue(mapping.dataTo, args, call, context),
+        destinationType: readMcpMappedValue(mapping.destinationType, args, call, context),
+        externalDomain: readMcpMappedValue(mapping.externalDomain, args, call, context),
+        dataClassification: readMcpMappedValue(mapping.dataClassification, args, call, context),
+        fieldSet: readMcpMappedValue(mapping.fieldSet, args, call, context),
+        recordCount: readMcpMappedValue(mapping.recordCount, args, call, context),
+        estimatedTokens: readMcpMappedValue(mapping.estimatedTokens, args, call, context),
+        estimatedCostUsd: readMcpMappedValue(mapping.estimatedCostUsd, args, call, context),
+    };
+}
+function hasSensitiveData(input, policy) {
+    const sensitive = new Set((policy.sensitiveClassifications || DEFAULT_SENSITIVE_CLASSIFICATIONS).map(normalize));
+    return (input.dataClassification || []).some((classification) => sensitive.has(normalize(classification)));
+}
+function isSensitiveDestination(input, policy) {
+    const destinations = new Set((policy.sensitiveDestinationTypes || DEFAULT_SENSITIVE_DESTINATIONS).map(normalize));
+    return Boolean(input.destinationType && destinations.has(normalize(input.destinationType)));
+}
+function matchesFlow(flow, input) {
+    if (!matchesPattern(flow.from, input.dataFrom || ""))
+        return false;
+    if (!matchesPattern(flow.to, input.dataTo || ""))
+        return false;
+    if (flow.destinationType && !matchesPattern(flow.destinationType, input.destinationType || ""))
+        return false;
+    if (!flow.dataClassification || flow.dataClassification.length === 0)
+        return true;
+    const actual = new Set((input.dataClassification || []).map(normalize));
+    return flow.dataClassification.some((classification) => actual.has(normalize(classification)));
+}
+function matchesPattern(pattern, value) {
+    return pattern === "*" || normalize(pattern) === normalize(value);
+}
+function presentBlockedFields(fieldSet, blockedFields) {
+    if (!fieldSet || !blockedFields)
+        return [];
+    const blocked = new Set(blockedFields.map(normalize));
+    return fieldSet.filter((field) => blocked.has(normalize(field)));
+}
+function absentAllowedFields(fieldSet, allowedFields) {
+    if (!fieldSet || !allowedFields)
+        return [];
+    const allowed = new Set(allowedFields.map(normalize));
+    return fieldSet.filter((field) => !allowed.has(normalize(field)));
+}
+function matchesAnyDomain(domain, allowedDomains) {
+    const normalizedDomain = normalize(domain);
+    return allowedDomains.some((allowed) => {
+        const normalizedAllowed = normalize(allowed);
+        return normalizedDomain === normalizedAllowed || normalizedDomain.endsWith(`.${normalizedAllowed}`);
+    });
+}
+function attemptKeyFor(input) {
+    return [input.tool, input.action, input.callFingerprint || input.resource || "", input.idempotencyKey || ""].join("|");
+}
+function newJobUsage(startedAtMs) {
+    return {
+        startedAtMs,
+        toolCalls: 0,
+        tokens: 0,
+        estimatedCostUsd: 0,
+        toolAttempts: new Map(),
+        toolCallsByName: new Map(),
+    };
+}
+function normalize(value) {
+    return value.trim().toLowerCase();
+}
+function randomDecisionId() {
+    return `dec_${Math.random().toString(36).slice(2, 12)}`;
+}
+function normalizeMcpToolCall(callOrRequest) {
+    return "params" in callOrRequest ? callOrRequest.params : callOrRequest;
+}
+function readMcpMappedValue(value, args, call, context) {
+    if (typeof value === "function") {
+        const mapper = value;
+        return mapper(args, call, context);
+    }
+    return value;
+}
+function inferMcpAction(toolName, defaultAction = "read") {
+    const normalized = normalize(toolName);
+    if (containsAny(normalized, ["refund", "credit", "charge", "payment", "pay", "transfer"]))
+        return "pay";
+    if (containsAny(normalized, ["send", "email", "message", "notify", "post"]))
+        return "send";
+    if (containsAny(normalized, ["delete", "remove", "destroy"]))
+        return "delete";
+    if (containsAny(normalized, ["deploy", "rollback", "release"]))
+        return "deploy";
+    if (containsAny(normalized, ["export", "download", "dump"]))
+        return "export";
+    if (containsAny(normalized, ["admin", "permission", "role", "iam", "secret", "shell", "exec"]))
+        return "admin";
+    if (containsAny(normalized, ["update", "write", "create", "insert", "patch", "set"]))
+        return "write";
+    if (containsAny(normalized, ["read", "get", "list", "search", "find", "lookup", "query"]))
+        return "read";
+    return defaultAction;
+}
+function containsAny(value, needles) {
+    return needles.some((needle) => value.includes(needle));
+}
+function stableStringify(value) {
+    return JSON.stringify(stableValue(value));
+}
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (!value || typeof value !== "object")
+        return value;
+    const input = value;
+    const output = {};
+    for (const key of Object.keys(input).sort()) {
+        output[key] = stableValue(input[key]);
+    }
+    return output;
+}

package/examples/circuit-breaker-demo.ts

@@ -0,0 +1,138 @@
+import { createToolGate, type GuardCheck, type GuardPolicy } from "../src/index.ts";
+
+const repeatedCallGate = createToolGate({
+  policy: {
+    tools: {
+      "web.search": {
+        action: "read",
+      },
+    },
+    budgets: {
+      maxIdenticalToolCallsPerJob: 2,
+    },
+  },
+  now: () => new Date("2026-06-11T12:00:00Z"),
+  idGenerator: demoIds("repeat"),
+});
+
+const spendGate = createToolGate({
+  policy: spendPolicy(),
+  now: () => new Date("2026-06-11T12:00:00Z"),
+  idGenerator: demoIds("spend"),
+});
+
+await runSearch(repeatedCallGate, "1. Search executes", {
+  agentId: "research-agent",
+  jobId: "repeat-loop",
+  tool: "web.search",
+  action: "read",
+  resource: "query:best refund workflow",
+  callFingerprint: "web.search:best-refund-workflow",
+});
+
+await runSearch(repeatedCallGate, "2. Same search executes once more", {
+  agentId: "research-agent",
+  jobId: "repeat-loop",
+  tool: "web.search",
+  action: "read",
+  resource: "query:best refund workflow",
+  callFingerprint: "web.search:best-refund-workflow",
+});
+
+await runSearch(repeatedCallGate, "3. Third identical search is denied", {
+  agentId: "research-agent",
+  jobId: "repeat-loop",
+  tool: "web.search",
+  action: "read",
+  resource: "query:best refund workflow",
+  callFingerprint: "web.search:best-refund-workflow",
+});
+
+await runSearch(spendGate, "4. First expensive search executes", {
+  agentId: "research-agent",
+  jobId: "spend-loop",
+  tool: "web.search",
+  action: "read",
+  resource: "query:agent framework survey",
+  estimatedTokens: 500,
+  estimatedCostUsd: 0.04,
+});
+
+await runSearch(spendGate, "5. Soft token threshold requires approval", {
+  agentId: "research-agent",
+  jobId: "spend-loop",
+  tool: "web.search",
+  action: "read",
+  resource: "query:agent framework survey details",
+  estimatedTokens: 400,
+  estimatedCostUsd: 0.03,
+});
+
+await runSearch(spendGate, "6. Approved search executes", {
+  agentId: "research-agent",
+  jobId: "spend-loop",
+  tool: "web.search",
+  action: "read",
+  resource: "query:agent framework survey details",
+  estimatedTokens: 400,
+  estimatedCostUsd: 0.03,
+  approvalId: "approval-budget-1",
+});
+
+await runSearch(spendGate, "7. Hard token and cost caps deny execution", {
+  agentId: "research-agent",
+  jobId: "spend-loop",
+  tool: "web.search",
+  action: "read",
+  resource: "query:agent framework survey more",
+  estimatedTokens: 400,
+  estimatedCostUsd: 0.04,
+  approvalId: "approval-budget-1",
+});
+
+async function runSearch(
+  gate: ReturnType<typeof createToolGate>,
+  label: string,
+  check: GuardCheck,
+): Promise<void> {
+  const execution = await gate.run(check, async () => ({
+    results: [`result for ${check.resource || check.tool}`],
+  }));
+
+  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 spendPolicy(): GuardPolicy {
+  return {
+    tools: {
+      "web.search": {
+        action: "read",
+      },
+    },
+    budgets: {
+      challengeAfterTokensPerJob: 800,
+      challengeAfterEstimatedCostUsdPerJob: 0.08,
+      maxTokensPerJob: 1200,
+      maxEstimatedCostUsdPerJob: 0.1,
+      maxSameToolCallsPerJob: 10,
+    },
+  };
+}
+
+function demoIds(prefix: string): () => string {
+  let next = 1;
+  return () => `${prefix}-demo-dec-${next++}`;
+}