ai-agent-guardrails 0.0.1

package/README.md

@@ -0,0 +1,155 @@
+# ai-agent-guardrails
+
+[![npm version](https://img.shields.io/npm/v/ai-agent-guardrails.svg)](https://www.npmjs.com/package/ai-agent-guardrails)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Security middleware for AI SDK that adds production-grade controls to agent tool calling.
+
+## Features
+
+- Policy Enforcement: Allowlists, denylists, and risk-based tool classification
+- Human Approval Gates: Require user confirmation for high-risk operations
+- Budget Controls: Max tool calls, time limits, per-tool timeouts
+- Audit Logging: Structured events compatible with OpenTelemetry
+- Secret Redaction: Automatic PII/secret removal from logs
+- MCP Integration: Works with Model Context Protocol tools
+
+## Installation
+
+```bash
+npm install ai-agent-guardrails ai zod
+# or
+pnpm add ai-agent-guardrails ai zod
+```
+
+## Quick Start
+
+```typescript
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { guardTools, createSimplePolicy, ConsoleAuditSink } from 'ai-agent-guardrails';
+
+// Define policy
+const policy = createSimplePolicy({
+  denylist: ['delete_database'], // Block dangerous tools
+  requireApprovalForRisk: ['write', 'admin'], // Require approval for these
+});
+
+// Wrap tools with guardrails
+const tools = guardTools(myTools, {
+  policy,
+  audit: new ConsoleAuditSink(),
+  timeoutMs: 10_000,
+});
+
+// Use in AI SDK
+const result = streamText({
+  model: openai('gpt-4o-mini'),
+  messages,
+  tools, // ← Guarded tools
+});
+```
+
+## With MCP Tools
+
+```typescript
+import { createMCPClient } from '@ai-sdk/mcp';
+import { guardTools, createSimplePolicy } from 'ai-agent-guardrails';
+
+// Connect to MCP server
+const mcp = await createMCPClient({ transport: ... });
+const mcpTools = await mcp.tools();
+
+// Apply guardrails
+const policy = createSimplePolicy({
+  requireApprovalForRisk: ['write', 'admin'],
+});
+
+const tools = guardTools(mcpTools, { policy });
+```
+
+## Approval Flow (React)
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export default function Chat() {
+  const { messages, addToolApprovalResponse } = useChat();
+
+  return (
+    <>
+      {messages.map(m =>
+        m.parts?.map(part => {
+          if (part.state === 'approval-requested') {
+            return (
+              <div>
+                <p>Tool requires approval: {part.type}</p>
+                <button onClick={() => addToolApprovalResponse({ id: part.approval.id, approved: true })}>
+                  Approve
+                </button>
+                <button onClick={() => addToolApprovalResponse({ id: part.approval.id, approved: false })}>
+                  Deny
+                </button>
+              </div>
+            );
+          }
+        })
+      )}
+    </>
+  );
+}
+```
+
+## Budget Controls
+
+```typescript
+import { createDefaultContext } from 'ai-agent-guardrails';
+
+const ctx = createDefaultContext();
+ctx.maxToolCalls = 5; // Limit to 5 tool calls
+ctx.maxDurationMs = 30_000; // 30 second timeout
+
+const tools = guardTools(myTools, { policy, ctx });
+```
+
+## Audit Logging
+
+```typescript
+import { InMemoryAuditSink, ConsoleAuditSink, FileAuditSink } from 'ai-agent-guardrails';
+
+// Console (dev)
+const audit = new ConsoleAuditSink();
+
+// Memory (testing)
+const audit = new InMemoryAuditSink();
+const events = audit.getEvents();
+
+// File (production)
+const audit = new FileAuditSink('./audit.jsonl');
+```
+
+## Redaction
+
+```typescript
+import { createDefaultRedactor, createFieldRedactor } from 'ai-agent-guardrails';
+
+// Automatic pattern-based redaction
+const redactor = createDefaultRedactor();
+
+// Field-based redaction
+const redactor = createFieldRedactor(['password', 'apiKey', 'secret']);
+
+const tools = guardTools(myTools, { policy, redactor });
+```
+
+## Documentation
+
+- [Full Documentation](https://github.com/yourusername/agent-guardrails-mcp)
+- [Threat Model](https://github.com/yourusername/agent-guardrails-mcp/blob/main/docs/THREAT_MODEL.md)
+- [Demo App](https://agent-guardrails-demo.vercel.app)
+
+## License
+
+MIT © Krish Gupta

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Risk classification for tools
+ */
+type Risk = 'read' | 'write' | 'admin';
+/**
+ * Decision outcome from policy evaluation
+ */
+type GuardDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+} | {
+    allow: true;
+    needsApproval: true;
+    reason: string;
+};
+/**
+ * Context passed through guard execution
+ */
+type GuardContext = {
+    requestId: string;
+    toolCalls: number;
+    maxToolCalls: number;
+    startTime: number;
+    maxDurationMs?: number;
+};
+/**
+ * Tool-like interface that matches AI SDK tool structure
+ */
+type ToolLike = {
+    description?: string;
+    inputSchema?: unknown;
+    parameters?: unknown;
+    needsApproval?: boolean | ((input: any) => boolean | Promise<boolean>);
+    execute?: (input: any) => Promise<any>;
+};
+/**
+ * Policy interface for classification and decision making
+ */
+type GuardPolicy = {
+    /**
+     * Classify a tool call by risk level
+     */
+    classify: (toolName: string, input: unknown) => Promise<{
+        risk: Risk;
+        reason?: string;
+    }> | {
+        risk: Risk;
+        reason?: string;
+    };
+    /**
+     * Decide whether to allow, block, or require approval
+     */
+    decide: (args: {
+        toolName: string;
+        input: unknown;
+        ctx: GuardContext;
+        risk: Risk;
+        reason?: string;
+    }) => Promise<GuardDecision> | GuardDecision;
+};
+/**
+ * Audit event types
+ */
+type AuditEvent = {
+    type: 'tool_call_attempted';
+    toolName: string;
+    input: unknown;
+    requestId: string;
+    timestamp: number;
+} | {
+    type: 'tool_call_blocked';
+    toolName: string;
+    reason: string;
+    requestId: string;
+    timestamp: number;
+} | {
+    type: 'tool_call_needs_approval';
+    toolName: string;
+    reason: string;
+    requestId: string;
+    timestamp: number;
+} | {
+    type: 'tool_call_executed';
+    toolName: string;
+    durationMs: number;
+    requestId: string;
+    timestamp: number;
+} | {
+    type: 'tool_call_timeout';
+    toolName: string;
+    timeoutMs: number;
+    requestId: string;
+    timestamp: number;
+} | {
+    type: 'budget_exceeded';
+    reason: string;
+    requestId: string;
+    timestamp: number;
+};
+/**
+ * Audit sink interface for logging events
+ */
+type AuditSink = {
+    emit: (event: AuditEvent) => void | Promise<void>;
+};
+/**
+ * Options for guardTools wrapper
+ */
+type GuardToolsOptions = {
+    policy: GuardPolicy;
+    ctx?: GuardContext;
+    audit?: AuditSink;
+    timeoutMs?: number;
+    redactor?: Redactor;
+};
+/**
+ * Redactor interface for PII/secret removal
+ */
+type Redactor = {
+    redact: (value: unknown) => unknown;
+};
+
+/**
+ * Wrap a toolset with guardrails enforcement
+ *
+ * This is the main entry point for the guardrails package. It wraps AI SDK tools
+ * with policy enforcement, budget checks, timeouts, and audit logging.
+ *
+ * @example
+ * ```ts
+ * const tools = guardTools(mcpTools, {
+ *   policy: createSimplePolicy({ requireApprovalForRisk: ['write', 'admin'] }),
+ *   audit: new ConsoleAuditSink(),
+ *   timeoutMs: 10_000,
+ * });
+ * ```
+ */
+declare function guardTools<T extends Record<string, ToolLike>>(tools: T, opts: GuardToolsOptions): T;
+
+/**
+ * Create a default guard context with budget limits
+ */
+declare function createDefaultContext(requestId?: string): GuardContext;
+/**
+ * Wrap a promise with a timeout
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+
+/**
+ * Create a simple policy with allowlist/denylist
+ */
+declare function createSimplePolicy(options: {
+    allowlist?: string[];
+    denylist?: string[];
+    requireApprovalForRisk?: Risk[];
+}): GuardPolicy;
+/**
+ * Create a composable policy builder
+ */
+declare class PolicyBuilder {
+    private classifiers;
+    private rules;
+    /**
+     * Add a classifier function
+     */
+    addClassifier(classifier: (toolName: string, input: unknown) => {
+        risk: Risk;
+        reason?: string;
+    } | null): this;
+    /**
+     * Add a decision rule
+     */
+    addRule(rule: (args: {
+        toolName: string;
+        input: unknown;
+        ctx: GuardContext;
+        risk: Risk;
+        reason?: string;
+    }) => GuardDecision | null): this;
+    /**
+     * Build the final policy
+     */
+    build(): GuardPolicy;
+}
+
+/**
+ * In-memory audit sink that stores events in an array
+ */
+declare class InMemoryAuditSink implements AuditSink {
+    private events;
+    emit(event: AuditEvent): void;
+    /**
+     * Get all stored events
+     */
+    getEvents(): ReadonlyArray<AuditEvent>;
+    /**
+     * Clear all stored events
+     */
+    clear(): void;
+    /**
+     * Get events for a specific request
+     */
+    getEventsForRequest(requestId: string): AuditEvent[];
+}
+/**
+ * Console audit sink that logs events to console
+ */
+declare class ConsoleAuditSink implements AuditSink {
+    private prefix;
+    constructor(prefix?: string);
+    emit(event: AuditEvent): void;
+}
+/**
+ * File audit sink that writes events to a JSONL file
+ * Note: This is for Node.js environments only
+ */
+declare class FileAuditSink implements AuditSink {
+    private writeStream;
+    constructor(filePath: string);
+    emit(event: AuditEvent): void;
+    /**
+     * Close the file stream
+     */
+    close(): void;
+}
+
+/**
+ * Create a regex-based redactor
+ */
+declare function createRegexRedactor(patterns: RegExp[], replacement?: string): Redactor;
+/**
+ * Create a default redactor with common secret and PII patterns
+ */
+declare function createDefaultRedactor(): Redactor;
+/**
+ * Field-based redactor that redacts specific fields
+ */
+declare function createFieldRedactor(fieldsToRedact: string[], replacement?: string): Redactor;
+/**
+ * Composite redactor that chains multiple redactors
+ */
+declare function composeRedactors(...redactors: Redactor[]): Redactor;
+
+export { type AuditEvent, type AuditSink, ConsoleAuditSink, FileAuditSink, type GuardContext, type GuardDecision, type GuardPolicy, type GuardToolsOptions, InMemoryAuditSink, PolicyBuilder, type Redactor, type Risk, type ToolLike, composeRedactors, createDefaultContext, createDefaultRedactor, createFieldRedactor, createRegexRedactor, createSimplePolicy, guardTools, withTimeout };