@dinpd/ai-agent-guard 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# @dinpd/ai-agent-guard
+
+Dependency-free runtime guard for AI agent tool calls.
+
+Use this package before an agent executes a tool, API call, browser action,
+message send, payment, refund, export, or production change.
+
+Install it from npm:
+
+```bash
+npm install @dinpd/ai-agent-guard
+```
+
+The first use case is simple: put a circuit breaker and approval gate in front
+of your agent's tools so loops, spend spikes, duplicate side effects, and PII
+egress are caught before execution.
+
+The guard returns one of three decisions:
+
+- `allow`: execute the tool call.
+- `challenge_required`: pause and ask for approval.
+- `deny`: block execution.
+
+## Five-Minute Path
+
+Install the package:
+
+```bash
+npm install @dinpd/ai-agent-guard
+```
+
+Run the local demos:
+
+```bash
+git clone https://github.com/dinpd/AgentPass.git
+cd AgentPass/packages/guard
+npm install
+npm run demo:quickstart
+npm run demo:mcp
+```
+
+The quickstart demo shows the intended first integration:
+
+1. A normal tool call executes.
+2. A repeated tool call is allowed once.
+3. The third identical call is denied.
+4. A PII email pauses for approval.
+
+Copy one of the starter policies and tighten it for your agent:
+
+- [`policies/tool-spend-cap.json`](policies/tool-spend-cap.json): cap tool calls,
+  retries, tokens, runtime, and estimated cost per job.
+- [`policies/pii-egress.json`](policies/pii-egress.json): restrict PII movement
+  to approved destinations and block high-risk fields.
+- [`policies/refund-payment.json`](policies/refund-payment.json): require
+  approval, amount caps, idempotency keys, and single-use execution.
+- [`policies/shell-browser-guard.json`](policies/shell-browser-guard.json):
+  challenge shell/file/browser actions and block secrets in external flows.
+- [`policies/mcp-tool-gateway.json`](policies/mcp-tool-gateway.json): start a
+  provider-style MCP tool policy with reads, writes, credits, email, and PII
+  flows.
+
+## Copy-Paste Wrapper
+
+```ts
+import { createToolGate } from "@dinpd/ai-agent-guard";
+
+const gate = createToolGate({
+  policy: {
+    tools: {
+      "web.search": { action: "read" }
+    },
+    budgets: {
+      maxIdenticalToolCallsPerJob: 2,
+      maxEstimatedCostUsdPerJob: 1
+    }
+  }
+});
+
+async function runAgentTool(toolCall) {
+  const execution = await gate.run(
+    {
+      agentId: "research-agent",
+      jobId: toolCall.jobId,
+      tool: toolCall.name,
+      action: "read",
+      resource: toolCall.query,
+      callFingerprint: `${toolCall.name}:${toolCall.query}`,
+      estimatedTokens: toolCall.estimatedTokens,
+      estimatedCostUsd: toolCall.estimatedCostUsd
+    },
+    () => executeTool(toolCall)
+  );
+
+  if (!execution.executed) {
+    return execution.decision;
+  }
+
+  return execution.result;
+}
+```
+
+## Tool Gate
+
+Use `createToolGate` when you want AgentPass to sit directly in front of tool
+execution:
+
+```ts
+import { createToolGate } from "@dinpd/ai-agent-guard";
+
+const gate = createToolGate({ policy });
+
+const execution = await gate.run(
+  {
+    agentId: "support-agent",
+    jobId: "case-1042",
+    tool: "stripe.refund",
+    action: "pay",
+    resource: "payment/pi_123",
+    amountUsd: 49,
+    idempotencyKey: "refund-case-1042-pi_123"
+  },
+  () => stripe.refunds.create({ payment_intent: "pi_123", amount: 4900 })
+);
+
+if (!execution.executed) {
+  return execution.decision;
+}
+
+return execution.result;
+```
+
+## MCP Tool-Call Gate
+
+Use `createMcpToolGate` when you want to guard MCP `tools/call` requests before
+forwarding them to a provider or internal MCP server:
+
+```ts
+import { createMcpToolGate } from "@dinpd/ai-agent-guard";
+
+const gate = createMcpToolGate({
+  policy,
+  mappings: {
+    "provider.billing.issue_credit": {
+      resource: (args) => `provider/customer/${String(args.customerId)}`,
+      amountUsd: (args) => Number(args.amountUsd),
+      idempotencyKey: (args) => String(args.idempotencyKey)
+    }
+  }
+});
+
+const execution = await gate.run(
+  {
+    params: {
+      name: "provider.billing.issue_credit",
+      arguments: {
+        customerId: "cus_123",
+        amountUsd: 49,
+        idempotencyKey: "credit-case-1042-cus_123"
+      }
+    }
+  },
+  {
+    agentId: "support-agent",
+    jobId: "case-1042",
+    userId: "user-17"
+  },
+  ({ call }) => forwardMcpToolCall(call)
+);
+
+if (!execution.executed) {
+  return execution.decision;
+}
+```
+
+The MCP adapter is dependency-free. It accepts a plain MCP-style `{ params:
+{ name, arguments } }` object, maps arguments into an AgentPass guard check, and
+uses the same `allow` / `deny` / `challenge_required` result as the local tool
+gate.
+
+## What It Checks
+
+- Closed-world tool declarations
+- Tool/action mismatches
+- Approval requirements
+- Amount caps
+- Idempotency keys and single-use actions
+- PII/sensitive-data movement to unsafe destinations
+- Field allowlists and blocked fields
+- Destination domain allowlists
+- Per-job tool-call, same-tool, identical-call, retry, token, cost, and runtime budgets
+- Soft budget thresholds that return `challenge_required` before hard denial
+- Optional `callFingerprint` values for detecting repeated tool calls without
+  storing full tool parameters
+
+This package is intentionally local and in-memory for the initial package.
+Persistent approvals, policy distribution, shared counters, and audit export
+belong in the runtime service layer.
+
+## Local Demo
+
+```bash
+npm install
+npm test
+npm run demo:quickstart
+npm run demo:mcp
+npm run demo
+npm run demo:circuit
+npm run demo:gate
+npm run demo:pii
+```
+
+The refund demo shows the initial runtime-guard story:
+
+1. A support agent proposes a refund.
+2. The guard returns `challenge_required`.
+3. The approved refund succeeds once.
+4. A retry with the same idempotency key is denied.
+5. A PII email to an unapproved destination is denied.
+
+The circuit-breaker demo shows tool-thrashing and spend controls:
+
+1. Repeated identical tool calls are denied.
+2. Soft token/cost thresholds pause for approval.
+3. Hard token/cost caps deny execution even after approval.
+
+The PII demo shows destination-specific data movement rules:
+
+1. CRM PII read into agent context is allowed.
+2. Customer email requires approval.
+3. Unknown webhook destinations are denied.
+4. Raw PII prompts to model providers are denied.
+5. Bulk file exports are capped by record count.
+6. High-risk fields are blocked for browser automation.

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+export type AgentAction = "read" | "write" | "send" | "delete" | "pay" | "deploy" | "export" | "admin" | string;
+export type DecisionType = "allow" | "deny" | "challenge_required";
+export type ToolPolicy = {
+    action?: AgentAction;
+    requiresApproval?: boolean;
+    requiresApprovalIfPii?: boolean;
+    maxAmountUsd?: number;
+    requireIdempotencyKey?: boolean;
+    singleUse?: boolean;
+    allowedDomains?: string[];
+    blockedFields?: string[];
+    allowedFields?: string[];
+};
+export type FlowPolicy = {
+    from: string;
+    to: string;
+    destinationType?: string;
+    decision?: "allow" | "deny";
+    requiresApproval?: boolean;
+    dataClassification?: string[];
+    allowedDomains?: string[];
+    blockedFields?: string[];
+    allowedFields?: string[];
+    maxRecords?: number;
+};
+export type BudgetPolicy = {
+    challengeAfterToolCallsPerJob?: number;
+    challengeAfterTokensPerJob?: number;
+    challengeAfterEstimatedCostUsdPerJob?: number;
+    challengeAfterRuntimeMsPerJob?: number;
+    maxToolCallsPerJob?: number;
+    maxSameToolCallsPerJob?: number;
+    maxIdenticalToolCallsPerJob?: number;
+    maxRetriesPerTool?: number;
+    maxTokensPerJob?: number;
+    maxEstimatedCostUsdPerJob?: number;
+    maxRuntimeMsPerJob?: number;
+};
+export type GuardPolicy = {
+    tools?: Record<string, ToolPolicy>;
+    flows?: FlowPolicy[];
+    budgets?: BudgetPolicy;
+    defaultSensitiveDestinationDecision?: "allow" | "deny" | "challenge_required";
+    sensitiveClassifications?: string[];
+    sensitiveDestinationTypes?: string[];
+};
+export type GuardCheck = {
+    agentId: string;
+    tool: string;
+    action: AgentAction;
+    jobId?: string;
+    userId?: string;
+    resource?: string;
+    callFingerprint?: string;
+    amountUsd?: number;
+    idempotencyKey?: string;
+    retryCount?: number;
+    approvalId?: string;
+    dataFrom?: string;
+    dataTo?: string;
+    destinationType?: string;
+    externalDomain?: string;
+    dataClassification?: string[];
+    fieldSet?: string[];
+    recordCount?: number;
+    estimatedTokens?: number;
+    estimatedCostUsd?: number;
+};
+export type GuardDecision = {
+    type: DecisionType;
+    allow: boolean;
+    challengeRequired: boolean;
+    reasons: string[];
+    challenge?: GuardChallenge;
+    event: GuardDecisionEvent;
+};
+export type GuardChallenge = {
+    reason: string;
+    requiredApprovalFor: Array<"tool" | "flow" | "pii" | "budget">;
+    tool: string;
+    action: AgentAction;
+    resource?: string;
+    amountUsd?: number;
+    dataFrom?: string;
+    dataTo?: string;
+    externalDomain?: string;
+};
+export type GuardDecisionEvent = {
+    decisionId: string;
+    decision: DecisionType;
+    allowed: boolean;
+    reasons: string[];
+    agentId: string;
+    tool: string;
+    action: AgentAction;
+    jobId?: string;
+    userId?: string;
+    resource?: string;
+    callFingerprint?: string;
+    amountUsd?: number;
+    idempotencyKey?: string;
+    approvalId?: string;
+    dataFrom?: string;
+    dataTo?: string;
+    destinationType?: string;
+    externalDomain?: string;
+    dataClassification: string[];
+    fieldSet: string[];
+    recordCount?: number;
+    estimatedTokens?: number;
+    estimatedCostUsd?: number;
+    issuedAt: string;
+};
+export type AgentPassGuardOptions = {
+    policy: GuardPolicy;
+    now?: () => Date;
+    idGenerator?: () => string;
+};
+export type ToolExecutionContext = {
+    check: GuardCheck;
+    decision: GuardDecision;
+};
+export type GuardedToolExecutor<TResult> = (context: ToolExecutionContext) => TResult | Promise<TResult>;
+export type GuardedToolExecutionResult<TResult> = {
+    executed: true;
+    decision: GuardDecision;
+    result: TResult;
+} | {
+    executed: false;
+    decision: GuardDecision;
+    result?: never;
+};
+export type AgentPassToolGateOptions = AgentPassGuardOptions | {
+    guard: AgentPassGuard;
+};
+export type McpToolCall = {
+    name: string;
+    arguments?: Record<string, unknown>;
+};
+export type McpToolsCallRequest = {
+    params: McpToolCall;
+};
+export type McpGuardContext = {
+    agentId: string;
+    jobId?: string;
+    userId?: string;
+    approvalId?: string;
+    retryCount?: number;
+};
+type McpMappedValue<T> = T | ((args: Record<string, unknown>, call: McpToolCall, context: McpGuardContext) => T | undefined);
+export type McpToolMapping = {
+    action?: McpMappedValue<AgentAction>;
+    resource?: McpMappedValue<string>;
+    callFingerprint?: McpMappedValue<string>;
+    amountUsd?: McpMappedValue<number>;
+    idempotencyKey?: McpMappedValue<string>;
+    dataFrom?: McpMappedValue<string>;
+    dataTo?: McpMappedValue<string>;
+    destinationType?: McpMappedValue<string>;
+    externalDomain?: McpMappedValue<string>;
+    dataClassification?: McpMappedValue<string[]>;
+    fieldSet?: McpMappedValue<string[]>;
+    recordCount?: McpMappedValue<number>;
+    estimatedTokens?: McpMappedValue<number>;
+    estimatedCostUsd?: McpMappedValue<number>;
+};
+export type McpToolCallAdapterOptions = {
+    mappings?: Record<string, McpToolMapping>;
+    defaultAction?: AgentAction;
+};
+export type AgentPassMcpToolGateOptions = AgentPassToolGateOptions & McpToolCallAdapterOptions;
+export type McpToolExecutionContext = ToolExecutionContext & {
+    call: McpToolCall;
+    arguments: Record<string, unknown>;
+};
+export type McpToolExecutor<TResult> = (context: McpToolExecutionContext) => TResult | Promise<TResult>;
+export declare class AgentPassGuard {
+    private policy;
+    private now;
+    private idGenerator;
+    private usedIdempotencyKeys;
+    private usageByJob;
+    constructor(options: AgentPassGuardOptions);
+    check(input: GuardCheck): GuardDecision;
+    reset(): void;
+    private evaluateToolPolicy;
+    private evaluateFlowPolicy;
+    private evaluateBudgetPolicy;
+    private commit;
+    private decision;
+    private event;
+}
+export declare function createGuard(options: AgentPassGuardOptions): AgentPassGuard;
+export declare class AgentPassToolGate {
+    readonly guard: AgentPassGuard;
+    constructor(options: AgentPassToolGateOptions);
+    check(input: GuardCheck): GuardDecision;
+    run<TResult>(input: GuardCheck, execute: GuardedToolExecutor<TResult>): Promise<GuardedToolExecutionResult<TResult>>;
+    reset(): void;
+}
+export declare function createToolGate(options: AgentPassToolGateOptions): AgentPassToolGate;
+export declare class AgentPassMcpToolGate {
+    readonly gate: AgentPassToolGate;
+    private mappings;
+    private defaultAction;
+    constructor(options: AgentPassMcpToolGateOptions);
+    check(callOrRequest: McpToolCall | McpToolsCallRequest, context: McpGuardContext): GuardDecision;
+    run<TResult>(callOrRequest: McpToolCall | McpToolsCallRequest, context: McpGuardContext, execute: McpToolExecutor<TResult>): Promise<GuardedToolExecutionResult<TResult>>;
+    toGuardCheck(callOrRequest: McpToolCall | McpToolsCallRequest, context: McpGuardContext): GuardCheck;
+    reset(): void;
+}
+export declare function createMcpToolGate(options: AgentPassMcpToolGateOptions): AgentPassMcpToolGate;
+export declare function mcpToolCallToGuardCheck(callOrRequest: McpToolCall | McpToolsCallRequest, context: McpGuardContext, options?: McpToolCallAdapterOptions): GuardCheck;
+export {};