@agent-wall/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1297 @@
+import { z } from 'zod';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Agent Wall JSON-RPC Types
+ *
+ * Mirrors the MCP protocol's JSON-RPC 2.0 message format.
+ * We define our own types instead of depending on the MCP SDK
+ * so Agent Wall has zero coupling to any specific MCP version.
+ */
+
+declare const JsonRpcRequestSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}, {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}>;
+declare const JsonRpcNotificationSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}, {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}>;
+declare const JsonRpcResponseSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}, {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}>;
+declare const JsonRpcMessageSchema: z.ZodUnion<[z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}, {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}>, z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}, {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}>, z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}, {
+    jsonrpc: "2.0";
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}>]>;
+type JsonRpcRequest = z.infer<typeof JsonRpcRequestSchema>;
+type JsonRpcNotification = z.infer<typeof JsonRpcNotificationSchema>;
+type JsonRpcResponse = z.infer<typeof JsonRpcResponseSchema>;
+type JsonRpcMessage = z.infer<typeof JsonRpcMessageSchema>;
+/** MCP tools/call request params */
+interface ToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/** MCP tools/list result */
+interface ToolListResult {
+    tools: Array<{
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+        annotations?: Record<string, unknown>;
+    }>;
+    nextCursor?: string;
+}
+/** MCP response content block (text, image, resource) */
+interface McpContentBlock {
+    type: string;
+    text?: string;
+    data?: string;
+    mimeType?: string;
+    [key: string]: unknown;
+}
+declare function isRequest(msg: JsonRpcMessage): msg is JsonRpcRequest;
+declare function isNotification(msg: JsonRpcMessage): msg is JsonRpcNotification;
+declare function isResponse(msg: JsonRpcMessage): msg is JsonRpcResponse;
+declare function isToolCall(msg: JsonRpcMessage): boolean;
+declare function isToolList(msg: JsonRpcMessage): boolean;
+declare function getToolCallParams(msg: JsonRpcRequest): ToolCallParams | null;
+/**
+ * Create a JSON-RPC error response for a denied tool call.
+ */
+declare function createDenyResponse(id: string | number, message: string): JsonRpcResponse;
+/**
+ * Create a JSON-RPC error response for a tool call requiring approval.
+ */
+declare function createPromptResponse(id: string | number, message: string): JsonRpcResponse;
+
+/**
+ * Agent Wall Read Buffer
+ *
+ * Accumulates raw bytes from a stream and extracts
+ * newline-delimited JSON-RPC messages one at a time.
+ *
+ * Directly mirrors the MCP SDK's ReadBuffer pattern:
+ *   - Append raw chunks
+ *   - Scan for '\n' delimiter
+ *   - Extract line, strip '\r', JSON.parse, validate
+ *
+ * Security: Enforces maximum buffer size to prevent DOS
+ * via unbounded memory growth from a single large message.
+ */
+
+declare class ReadBuffer {
+    private buffer;
+    private maxBufferSize;
+    constructor(maxBufferSize?: number);
+    /**
+     * Append raw bytes from a stream chunk.
+     * Throws if the buffer exceeds the configured maximum size.
+     */
+    append(chunk: Buffer): void;
+    /**
+     * Try to extract the next complete JSON-RPC message.
+     * Returns null if no complete message is available yet.
+     * Automatically skips empty lines.
+     */
+    readMessage(): JsonRpcMessage | null;
+    /**
+     * Extract ALL available messages from the buffer.
+     */
+    readAllMessages(): JsonRpcMessage[];
+    /**
+     * Clear the buffer.
+     */
+    clear(): void;
+    /**
+     * Check if there's any pending data in the buffer.
+     */
+    get hasPendingData(): boolean;
+    /**
+     * Get current buffer size in bytes.
+     */
+    get currentSize(): number;
+}
+/**
+ * Error thrown when buffer exceeds maximum size.
+ */
+declare class BufferOverflowError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a single line of text into a validated JSON-RPC message.
+ */
+declare function deserializeMessage(line: string): JsonRpcMessage;
+/**
+ * Serialize a JSON-RPC message to a newline-delimited string.
+ */
+declare function serializeMessage(message: JsonRpcMessage): string;
+
+/**
+ * Agent Wall Prompt Injection Detector
+ *
+ * Detects prompt injection attacks in tool call arguments.
+ * This is the #1 attack vector for AI agents — an attacker embeds
+ * instructions in data (emails, documents, web pages) that trick
+ * the AI into executing malicious actions.
+ *
+ * Detection layers:
+ *   1. Known injection phrases (e.g., "ignore previous instructions")
+ *   2. Role/system prompt markers (e.g., "<|im_start|>system")
+ *   3. Instruction override patterns (e.g., "IMPORTANT: new instructions")
+ *   4. Encoded injection (base64-encoded injection strings)
+ *   5. Unicode obfuscation (homoglyphs, zero-width chars)
+ */
+
+interface InjectionDetectorConfig {
+    /** Enable injection detection (default: true) */
+    enabled?: boolean;
+    /** Sensitivity: "low" (fewer false positives), "medium", "high" (catches more) */
+    sensitivity?: "low" | "medium" | "high";
+    /** Custom patterns to add (regex strings) */
+    customPatterns?: string[];
+    /** Tool names to exclude from injection scanning */
+    excludeTools?: string[];
+}
+interface InjectionScanResult {
+    /** Whether injection was detected */
+    detected: boolean;
+    /** Confidence: "low", "medium", "high" */
+    confidence: "low" | "medium" | "high";
+    /** All matches found */
+    matches: InjectionMatch[];
+    /** Human-readable summary */
+    summary: string;
+}
+interface InjectionMatch {
+    /** Which pattern category matched */
+    category: string;
+    /** The matched text (truncated for safety) */
+    matched: string;
+    /** Which argument key contained the match */
+    argumentKey: string;
+    /** Confidence level for this specific match */
+    confidence: "low" | "medium" | "high";
+}
+declare class InjectionDetector {
+    private config;
+    private customRegexes;
+    constructor(config?: InjectionDetectorConfig);
+    /**
+     * Scan a tool call's arguments for prompt injection.
+     */
+    scan(toolCall: ToolCallParams): InjectionScanResult;
+    /**
+     * Extract a string from an argument value (handles nested objects).
+     */
+    private extractString;
+}
+
+/**
+ * Agent Wall Egress Control (URL/SSRF Protection)
+ *
+ * Inspects tool call arguments for URLs and blocks requests to:
+ *   - Private/internal IPs (RFC1918: 10.x, 172.16-31.x, 192.168.x)
+ *   - Loopback addresses (127.x, ::1, localhost)
+ *   - Link-local addresses (169.254.x — AWS/cloud metadata endpoint)
+ *   - Cloud metadata endpoints (169.254.169.254)
+ *   - Blocked domains (configurable)
+ *
+ * Supports allowlist mode: only explicitly allowed domains pass.
+ */
+
+interface EgressControlConfig {
+    /** Enable egress control (default: true when configured) */
+    enabled?: boolean;
+    /** Allowed domains (if set, ONLY these domains pass — allowlist mode) */
+    allowedDomains?: string[];
+    /** Blocked domains (blocklist mode, used when allowedDomains is not set) */
+    blockedDomains?: string[];
+    /** Block private/internal IPs (default: true) */
+    blockPrivateIPs?: boolean;
+    /** Block cloud metadata endpoints (default: true) */
+    blockMetadataEndpoints?: boolean;
+    /** Tool names to exclude from egress scanning */
+    excludeTools?: string[];
+}
+interface EgressCheckResult {
+    /** Whether the call is safe to proceed */
+    allowed: boolean;
+    /** URLs found in arguments */
+    urlsFound: EgressUrlInfo[];
+    /** URLs that were blocked */
+    blocked: EgressUrlInfo[];
+    /** Human-readable summary */
+    summary: string;
+}
+interface EgressUrlInfo {
+    /** The original URL string */
+    url: string;
+    /** Parsed hostname */
+    hostname: string;
+    /** Why it was blocked (if blocked) */
+    reason?: string;
+    /** Which argument key contained this URL */
+    argumentKey: string;
+}
+declare class EgressControl {
+    private config;
+    constructor(config?: EgressControlConfig);
+    /**
+     * Check a tool call's arguments for blocked URLs.
+     */
+    check(toolCall: ToolCallParams): EgressCheckResult;
+    /**
+     * Check a single hostname/URL against all rules.
+     * Returns the block reason, or null if allowed.
+     *
+     * Check order matters: more specific checks (obfuscated, metadata) run
+     * before generic private IP, so the reason message is precise.
+     */
+    private checkUrl;
+}
+
+/**
+ * Agent Wall Kill Switch
+ *
+ * Emergency "deny all" mechanism for instantly shutting down
+ * all tool call forwarding. Three activation methods:
+ *
+ *   1. File-based: touch .agent-wall-kill in cwd or home dir
+ *   2. Programmatic: killSwitch.activate() / killSwitch.deactivate()
+ *   3. Signal-based: SIGUSR2 toggles the kill switch (Unix only)
+ *
+ * When active, ALL tool calls are denied immediately with a clear message.
+ * The kill switch is checked FIRST in the proxy pipeline — before policy
+ * engine, injection detection, or any other check.
+ */
+interface KillSwitchConfig {
+    /** Enable kill switch checking (default: true) */
+    enabled?: boolean;
+    /** Check for kill file on filesystem (default: true) */
+    checkFile?: boolean;
+    /** File names to check (default: [".agent-wall-kill"]) */
+    killFileNames?: string[];
+    /** Directories to check for kill files (default: [cwd, home]) */
+    checkDirs?: string[];
+    /** How often to check the kill file in ms (default: 1000) */
+    pollIntervalMs?: number;
+    /** Register SIGUSR2 signal handler to toggle (default: true on Unix) */
+    registerSignal?: boolean;
+}
+interface KillSwitchStatus {
+    /** Whether the kill switch is currently active */
+    active: boolean;
+    /** How it was activated */
+    reason: string;
+    /** When it was activated */
+    activatedAt: string | null;
+}
+declare class KillSwitch {
+    private config;
+    private manuallyActive;
+    private fileActive;
+    private activeReason;
+    private activatedAt;
+    private pollTimer;
+    constructor(config?: KillSwitchConfig);
+    /**
+     * Check if the kill switch is currently active.
+     * This should be called at the TOP of the proxy pipeline.
+     */
+    isActive(): boolean;
+    /**
+     * Get the current kill switch status.
+     */
+    getStatus(): KillSwitchStatus;
+    /**
+     * Programmatically activate the kill switch.
+     */
+    activate(reason?: string): void;
+    /**
+     * Programmatically deactivate the kill switch.
+     * Note: file-based kill switch must be deactivated by removing the file.
+     */
+    deactivate(): void;
+    /**
+     * Start polling for kill files.
+     */
+    private startPolling;
+    /**
+     * Check if any kill file exists.
+     */
+    private checkKillFiles;
+    /**
+     * Register SIGUSR2 signal handler to toggle kill switch.
+     * SIGUSR2 is used (not SIGUSR1) because some tools use SIGUSR1.
+     */
+    private registerSignalHandler;
+    /**
+     * Stop the kill switch (cleanup timers and signal handlers).
+     */
+    dispose(): void;
+}
+
+/**
+ * Agent Wall Tool Call Chain Detector
+ *
+ * Detects suspicious sequences of tool calls that indicate
+ * multi-step attacks. Individual calls may look innocent,
+ * but the CHAIN reveals the attack:
+ *
+ *   read_file(.env) → write_file(tmp.txt) → bash(curl)  = EXFILTRATION
+ *   list_directory(/) → read_file(passwd) → read_file(shadow) = RECON
+ *   write_file(script.sh) → bash(chmod +x) → bash(./script.sh) = DROPPER
+ *
+ * The detector maintains a sliding window of recent tool calls
+ * and matches against known attack chain patterns.
+ */
+
+interface ChainDetectorConfig {
+    /** Enable chain detection (default: true) */
+    enabled?: boolean;
+    /** Sliding window size (number of recent calls to track) */
+    windowSize?: number;
+    /** Time window in ms (calls older than this are dropped) */
+    windowMs?: number;
+    /** Custom chain patterns to add */
+    customChains?: ChainPattern[];
+}
+interface ChainPattern {
+    /** Unique name for this chain pattern */
+    name: string;
+    /** Ordered sequence of tool name glob patterns */
+    sequence: string[];
+    /** Severity: "low", "medium", "high", "critical" */
+    severity: "low" | "medium" | "high" | "critical";
+    /** Human-readable description */
+    message: string;
+    /** Whether argument values must match across steps (e.g., same file read then sent) */
+    trackArguments?: boolean;
+}
+interface ChainDetectionResult {
+    /** Whether a suspicious chain was detected */
+    detected: boolean;
+    /** Matched chain patterns */
+    matches: ChainMatchInfo[];
+    /** Human-readable summary */
+    summary: string;
+}
+interface ChainMatchInfo {
+    /** Name of the matched chain pattern */
+    chain: string;
+    /** Severity level */
+    severity: "low" | "medium" | "high" | "critical";
+    /** The tool calls that formed the chain */
+    calls: string[];
+    /** Description */
+    message: string;
+}
+declare class ChainDetector {
+    private config;
+    private history;
+    private allChains;
+    constructor(config?: ChainDetectorConfig);
+    /**
+     * Record a tool call and check for suspicious chains.
+     * Call this AFTER the policy engine allows the call.
+     */
+    record(toolCall: ToolCallParams): ChainDetectionResult;
+    /**
+     * Check if the current history matches a chain pattern.
+     * Looks for the sequence appearing in order (not necessarily consecutive).
+     */
+    private matchesChain;
+    /**
+     * Match a tool name against a pipe-separated glob-like pattern.
+     */
+    private matchesToolPattern;
+    /**
+     * Remove entries outside the time window or exceeding window size.
+     */
+    private pruneHistory;
+    /**
+     * Clear the call history (e.g., on session reset).
+     */
+    reset(): void;
+    /**
+     * Get the current call history length.
+     */
+    getHistoryLength(): number;
+}
+
+/**
+ * Agent Wall Policy Engine
+ *
+ * Evaluates tool calls against YAML-defined rules.
+ * Rules are matched in order — first match wins.
+ * If no rule matches, the default action applies.
+ *
+ * Security hardening:
+ *   - Path normalization (resolves ../ before matching)
+ *   - Unicode NFC normalization (prevents homoglyph bypass)
+ *   - Zero-trust "strict" mode (default deny, only explicit allows pass)
+ *   - Safe regex construction (prevents ReDoS in argument matching)
+ *   - Deep argument scanning across all string values
+ */
+
+type RuleAction = "allow" | "deny" | "prompt";
+/** Policy mode: "standard" (backward-compatible) or "strict" (zero-trust) */
+type PolicyMode = "standard" | "strict";
+interface RuleMatch {
+    /** Glob patterns matched against string values in arguments */
+    arguments?: Record<string, string>;
+}
+interface RateLimitConfig {
+    maxCalls: number;
+    windowSeconds: number;
+}
+interface PolicyRule {
+    name: string;
+    /** Glob pattern for tool name(s). Use "|" to separate multiple patterns. */
+    tool: string;
+    /** Optional argument matching */
+    match?: RuleMatch;
+    /** What to do when this rule matches */
+    action: RuleAction;
+    /** Human-readable message shown when rule triggers */
+    message?: string;
+    /** Rate limiting for this rule's scope */
+    rateLimit?: RateLimitConfig;
+}
+/** Security modules configuration. */
+interface SecurityConfig {
+    /** Prompt injection detection */
+    injectionDetection?: InjectionDetectorConfig;
+    /** URL/SSRF egress control */
+    egressControl?: EgressControlConfig;
+    /** Emergency kill switch */
+    killSwitch?: KillSwitchConfig;
+    /** Tool call chain/sequence detection */
+    chainDetection?: ChainDetectorConfig;
+    /** Enable HMAC-SHA256 audit log signing */
+    signing?: boolean;
+    /** Signing key (auto-generated per session if not provided) */
+    signingKey?: string;
+}
+interface PolicyConfig {
+    version: number;
+    /** Policy mode: "standard" (default) or "strict" (zero-trust deny-by-default) */
+    mode?: PolicyMode;
+    /** Default action when no rule matches (overridden to "deny" in strict mode) */
+    defaultAction?: RuleAction;
+    /** Global rate limit across all tools */
+    globalRateLimit?: RateLimitConfig;
+    /** Response scanning configuration */
+    responseScanning?: ResponseScannerPolicyConfig;
+    /** Security modules (injection detection, egress control, kill switch, chain detection) */
+    security?: SecurityConfig;
+    /** Ordered list of rules — first match wins */
+    rules: PolicyRule[];
+}
+/** Response scanning section in the YAML policy. */
+interface ResponseScannerPolicyConfig {
+    enabled?: boolean;
+    maxResponseSize?: number;
+    oversizeAction?: "block" | "redact";
+    detectSecrets?: boolean;
+    detectPII?: boolean;
+    /** Action for base64 blob detection: "pass" (default), "redact", or "block" */
+    base64Action?: "pass" | "redact" | "block";
+    /** Maximum number of custom patterns allowed (default: 100) */
+    maxPatterns?: number;
+    patterns?: Array<{
+        name: string;
+        pattern: string;
+        flags?: string;
+        action: "pass" | "redact" | "block";
+        message?: string;
+        category?: string;
+    }>;
+}
+interface PolicyVerdict {
+    action: RuleAction;
+    rule: string | null;
+    message: string;
+}
+declare class PolicyEngine {
+    private config;
+    private rateLimiter;
+    constructor(config: PolicyConfig);
+    /**
+     * Update the policy configuration (e.g., after file reload).
+     */
+    updateConfig(config: PolicyConfig): void;
+    /**
+     * Evaluate a tool call against the policy rules.
+     * Returns the verdict: allow, deny, or prompt.
+     */
+    evaluate(toolCall: ToolCallParams): PolicyVerdict;
+    /**
+     * Check if a rule matches a tool call.
+     */
+    private matchesRule;
+    /**
+     * Match a tool name against a pattern.
+     * Pattern can contain "|" for multiple alternatives.
+     */
+    private matchToolName;
+    /**
+     * Match rule argument patterns against actual tool arguments.
+     * Each key in ruleArgs is an argument name, value is a glob pattern.
+     * ALL specified argument patterns must match for the rule to match.
+     *
+     * Security: normalizes paths and unicode before matching.
+     * Security: checks key aliases (path → file, filepath, etc.)
+     */
+    private matchArguments;
+    /**
+     * Get the current policy config.
+     */
+    getConfig(): PolicyConfig;
+    /**
+     * Get all rule names.
+     */
+    getRuleNames(): string[];
+}
+
+/**
+ * Agent Wall Policy Loader
+ *
+ * Loads and validates policy configuration from YAML files.
+ * Supports loading from a specific path or auto-discovering
+ * agent-wall.yaml in the current directory or parent directories.
+ */
+
+/**
+ * Load a policy config from a specific file path.
+ */
+declare function loadPolicyFile(filePath: string): PolicyConfig;
+/**
+ * Parse a YAML string into a validated PolicyConfig.
+ */
+declare function parsePolicyYaml(yamlContent: string): PolicyConfig;
+/**
+ * Auto-discover the nearest agent-wall.yaml by walking up
+ * from the given directory (defaults to cwd).
+ * Returns the file path if found, null otherwise.
+ */
+declare function discoverPolicyFile(startDir?: string): string | null;
+/**
+ * Load the policy config by auto-discovering the config file.
+ * Falls back to default policy if no config file found.
+ */
+declare function loadPolicy(configPath?: string): {
+    config: PolicyConfig;
+    filePath: string | null;
+};
+/**
+ * Get the default policy config.
+ * Ships with Agent Wall — provides reasonable security out of the box.
+ */
+declare function getDefaultPolicy(): PolicyConfig;
+/**
+ * Generate the default agent-wall.yaml content for `agent-wall init`.
+ */
+declare function generateDefaultConfigYaml(): string;
+
+/**
+ * Agent Wall Response Scanner
+ *
+ * Inspects MCP server responses BEFORE they reach the AI agent.
+ * This is the second half of the firewall:
+ *   - Policy Engine controls what goes IN  (tool calls)
+ *   - Response Scanner controls what comes OUT (tool results)
+ *
+ * Detects:
+ *   1. Secret leaks (API keys, tokens, passwords in response text)
+ *   2. Data exfiltration markers (base64 blobs, large hex dumps)
+ *   3. Sensitive file content (private keys, certificates, AWS creds)
+ *   4. Oversized responses (context window stuffing)
+ *   5. Custom patterns (user-defined via YAML config)
+ *
+ * Security:
+ *   - ReDoS-safe pattern validation (rejects dangerous regex)
+ *   - Max pattern count enforcement
+ *   - Configurable base64 blob action
+ *   - Generic redaction markers (no pattern name leak)
+ */
+type ResponseAction = "pass" | "redact" | "block";
+/** A single pattern to match against response content. */
+interface ResponsePattern {
+    /** Unique name for this pattern */
+    name: string;
+    /** Regex pattern to match against response text */
+    pattern: string;
+    /** Flags for the regex (default: "gi") */
+    flags?: string;
+    /** What to do when the pattern matches */
+    action: ResponseAction;
+    /** Human-readable description */
+    message?: string;
+    /** Category for grouping in audit logs */
+    category?: string;
+}
+/** Configuration for response scanning. */
+interface ResponseScannerConfig {
+    /** Enable/disable the response scanner (default: true) */
+    enabled?: boolean;
+    /** Maximum response size in bytes before blocking (0 = no limit) */
+    maxResponseSize?: number;
+    /** Action when response exceeds maxResponseSize: "block" or "redact" (truncate) */
+    oversizeAction?: "block" | "redact";
+    /** Built-in secret detection (default: true) */
+    detectSecrets?: boolean;
+    /** Built-in PII detection (default: false — opt-in) */
+    detectPII?: boolean;
+    /** Action for base64 blob detection: "pass" (default), "redact", or "block" */
+    base64Action?: ResponseAction;
+    /** Maximum number of custom patterns allowed (default: 100) */
+    maxPatterns?: number;
+    /** Custom patterns to match against response content */
+    patterns?: ResponsePattern[];
+}
+/** Result of scanning a response. */
+interface ScanResult {
+    /** Whether the response is clean */
+    clean: boolean;
+    /** The final action to take */
+    action: ResponseAction;
+    /** All findings */
+    findings: ScanFinding[];
+    /** If action is "redact", the redacted response text */
+    redactedText?: string;
+    /** Original size in bytes */
+    originalSize: number;
+}
+/** A single finding from the scanner. */
+interface ScanFinding {
+    /** Name of the pattern that matched */
+    pattern: string;
+    /** Category */
+    category: string;
+    /** The action this pattern requests */
+    action: ResponseAction;
+    /** Human-readable message */
+    message: string;
+    /** Number of matches found */
+    matchCount: number;
+    /** Preview of matched content (redacted) */
+    preview?: string;
+}
+/**
+ * Validate a regex pattern is safe from ReDoS attacks.
+ * Returns true if the pattern is safe, false if potentially dangerous.
+ */
+declare function isRegexSafe(pattern: string): boolean;
+declare class ResponseScanner {
+    private config;
+    private compiledPatterns;
+    private rejectedPatterns;
+    constructor(config?: ResponseScannerConfig);
+    /**
+     * Compile all regex patterns upfront for performance.
+     * Validates each pattern for ReDoS safety before compilation.
+     */
+    private compilePatterns;
+    /**
+     * Safely compile a pattern. For user patterns, validate ReDoS safety first.
+     */
+    private safeCompile;
+    /**
+     * Scan a response text for sensitive content.
+     */
+    scan(text: string): ScanResult;
+    /**
+     * Scan the content array from an MCP tools/call response.
+     * MCP responses have the shape: { content: [{ type: "text", text: "..." }, ...] }
+     */
+    scanMcpResponse(result: unknown): ScanResult;
+    /**
+     * Extract all text content from an MCP response result.
+     */
+    private extractText;
+    /**
+     * Resolve the highest-severity action from all findings.
+     * Priority: block > redact > pass
+     */
+    private resolveAction;
+    /**
+     * Redact matched patterns from the text.
+     * Uses generic [REDACTED] marker — never leaks pattern names.
+     */
+    private redactText;
+    /**
+     * Create a safe preview of matched content (first 4 chars + last 4).
+     */
+    private createPreview;
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): ResponseScannerConfig;
+    /**
+     * Get the number of compiled patterns.
+     */
+    getPatternCount(): number;
+    /**
+     * Get list of patterns that were rejected during compilation.
+     */
+    getRejectedPatterns(): string[];
+    /**
+     * Update configuration (e.g., after policy file reload).
+     */
+    updateConfig(config: ResponseScannerConfig): void;
+}
+/**
+ * Create a scanner with sensible defaults (secrets ON, PII OFF).
+ */
+declare function createDefaultScanner(): ResponseScanner;
+
+/**
+ * Agent Wall Audit Logger
+ *
+ * Structured logging of every tool call and its policy verdict.
+ * Logs to stderr (JSON) and optionally to a file.
+ * This is the audit trail — proof of what the agent did and what was blocked.
+ *
+ * Security:
+ *   - HMAC-SHA256 chain signing (tamper-evident log entries)
+ *   - Log rotation (max file size with automatic rotation)
+ *   - File permission checks on policy files
+ */
+
+interface AuditEntry {
+    timestamp: string;
+    sessionId: string;
+    direction: "request" | "response";
+    method: string;
+    tool?: string;
+    arguments?: Record<string, unknown>;
+    verdict?: {
+        action: RuleAction;
+        rule: string | null;
+        message: string;
+    };
+    responsePreview?: string;
+    latencyMs?: number;
+    error?: string;
+}
+/** Signed audit entry — includes HMAC chain for tamper evidence. */
+interface SignedAuditEntry extends AuditEntry {
+    /** HMAC-SHA256 of this entry + previous hash (chain) */
+    _sig?: string;
+    /** Sequence number in the chain */
+    _seq?: number;
+}
+interface AuditLoggerOptions {
+    /** Log to stdout as JSON lines (default: true) */
+    stdout?: boolean;
+    /** Log to a file (JSON lines) */
+    filePath?: string;
+    /** Redact sensitive values in arguments (default: true) */
+    redact?: boolean;
+    /** Maximum argument value length before truncation */
+    maxArgLength?: number;
+    /** Silent mode — no output */
+    silent?: boolean;
+    /** Enable HMAC-SHA256 chain signing */
+    signing?: boolean;
+    /** HMAC signing key (auto-generated per session if not provided) */
+    signingKey?: string;
+    /** Max log file size in bytes before rotation (default: 50MB, 0 = no limit) */
+    maxFileSize?: number;
+    /** Number of rotated log files to keep (default: 5) */
+    maxFiles?: number;
+    /** Callback fired after every log entry (for dashboard streaming) */
+    onEntry?: (entry: AuditEntry) => void;
+}
+declare class AuditLogger {
+    private options;
+    private fileFd;
+    private entries;
+    private prevHash;
+    private seqCounter;
+    private currentFileSize;
+    constructor(options?: AuditLoggerOptions);
+    /**
+     * Open or reopen the log file using synchronous fd (reliable on Windows).
+     */
+    private openLogFile;
+    /**
+     * Log a tool call with its policy verdict.
+     */
+    log(entry: AuditEntry): void;
+    /**
+     * Compute HMAC-SHA256 for a log entry in the chain.
+     * Chain: HMAC(entry_json + prev_hash)
+     */
+    private computeHmac;
+    /**
+     * Rotate log files: current → .1, .1 → .2, etc.
+     * Oldest file beyond maxFiles is deleted.
+     */
+    private rotateLogFile;
+    /**
+     * Log a denied tool call (convenience method).
+     */
+    logDeny(sessionId: string, tool: string, args: Record<string, unknown>, ruleName: string | null, message: string): void;
+    /**
+     * Log an allowed tool call (convenience method).
+     */
+    logAllow(sessionId: string, tool: string, args: Record<string, unknown>, ruleName: string | null, message: string): void;
+    /**
+     * Get all logged entries (for the audit command).
+     */
+    getEntries(): AuditEntry[];
+    /**
+     * Get summary statistics.
+     */
+    getStats(): {
+        total: number;
+        allowed: number;
+        denied: number;
+        prompted: number;
+    };
+    /**
+     * Redact sensitive argument values.
+     */
+    private redactEntry;
+    /**
+     * Verify the HMAC chain integrity of a log file.
+     * Returns { valid: boolean, entries: number, firstBroken: number | null }
+     */
+    static verifyChain(logFilePath: string, signingKey: string): {
+        valid: boolean;
+        entries: number;
+        firstBroken: number | null;
+    };
+    /**
+     * Set or replace the onEntry callback (for dashboard streaming).
+     */
+    setOnEntry(callback: ((entry: AuditEntry) => void) | undefined): void;
+    /**
+     * Close the logger (flush file stream).
+     */
+    close(): void;
+}
+interface FilePermissionCheckResult {
+    safe: boolean;
+    warnings: string[];
+}
+/**
+ * Check if a policy file has safe permissions.
+ * Warns if world-writable, group-writable, or owned by different user.
+ * On Windows this is best-effort (no Unix permission model).
+ */
+declare function checkFilePermissions(filePath: string): FilePermissionCheckResult;
+
+/**
+ * Agent Wall Stdio Proxy
+ *
+ * The core of Agent Wall. Sits between an MCP client and server,
+ * intercepting every JSON-RPC message over stdio (stdin/stdout).
+ *
+ * Architecture:
+ *   MCP Client (e.g. Claude Code)
+ *       ↕ stdin/stdout
+ *   Agent Wall Proxy (this file)
+ *       ↕ stdin/stdout (child process)
+ *   MCP Server (e.g. filesystem server)
+ *
+ * The proxy:
+ *   1. Spawns the real MCP server as a child process
+ *   2. Reads JSON-RPC from its own stdin (from the MCP client)
+ *   3. For tools/call requests: evaluates against the policy engine
+ *   4. If allowed: forwards to child's stdin
+ *   5. If denied: returns a JSON-RPC error without forwarding
+ *   6. Pipes child's stdout back to its own stdout (to the MCP client)
+ */
+
+interface ProxyOptions {
+    /** The command to spawn (e.g. "npx") */
+    command: string;
+    /** Arguments for the command (e.g. ["@modelcontextprotocol/server-filesystem", "/path"]) */
+    args?: string[];
+    /** Environment variables for the child process */
+    env?: Record<string, string>;
+    /** Working directory for the child process */
+    cwd?: string;
+    /** The policy engine instance */
+    policyEngine: PolicyEngine;
+    /** The response scanner instance (optional — if not provided, responses pass through) */
+    responseScanner?: ResponseScanner;
+    /** The audit logger instance */
+    logger: AuditLogger;
+    /** Session ID for audit logging */
+    sessionId?: string;
+    /** Callback for prompt actions — return true to allow, false to deny */
+    onPrompt?: (tool: string, args: Record<string, unknown>, message: string) => Promise<boolean>;
+    /** Called when the proxy is ready (child process spawned) */
+    onReady?: () => void;
+    /** Called when the proxy exits */
+    onExit?: (code: number | null) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Maximum buffer size in bytes (default: 10MB) */
+    maxBufferSize?: number;
+    /** TTL for pending tool calls in ms (default: 30000) — prevents memory leaks */
+    pendingCallTtlMs?: number;
+    /** Prompt injection detector (optional) */
+    injectionDetector?: InjectionDetector;
+    /** Egress/SSRF control (optional) */
+    egressControl?: EgressControl;
+    /** Emergency kill switch (optional) */
+    killSwitch?: KillSwitch;
+    /** Tool call chain detector (optional) */
+    chainDetector?: ChainDetector;
+}
+interface ProxyEvents {
+    ready: [];
+    exit: [code: number | null];
+    error: [error: Error];
+    denied: [tool: string, message: string];
+    allowed: [tool: string];
+    prompted: [tool: string, message: string];
+    responseBlocked: [tool: string, findings: string];
+    responseRedacted: [tool: string, findings: string];
+    injectionDetected: [tool: string, summary: string];
+    egressBlocked: [tool: string, summary: string];
+    killSwitchActive: [tool: string];
+    chainDetected: [tool: string, summary: string];
+}
+declare class StdioProxy extends EventEmitter {
+    private child;
+    private clientBuffer;
+    private serverBuffer;
+    private options;
+    private sessionId;
+    private running;
+    private stats;
+    /** Track pending tools/call requests by JSON-RPC id, so we can correlate responses */
+    private pendingToolCalls;
+    /** Cleanup timer for expired pending calls */
+    private pendingCleanupTimer;
+    private pendingCallTtlMs;
+    constructor(options: ProxyOptions);
+    /**
+     * Start the proxy — spawn the child MCP server and begin intercepting.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the proxy — gracefully shut down the child process.
+     * Follows the MCP SDK pattern: stdin.end() → SIGTERM → SIGKILL
+     */
+    stop(): Promise<void>;
+    /**
+     * Get proxy statistics.
+     */
+    getStats(): {
+        forwarded: number;
+        denied: number;
+        prompted: number;
+        total: number;
+        scanned: number;
+        responseBlocked: number;
+        responseRedacted: number;
+    };
+    /**
+     * Wire up the stdin/stdout pipelines with interception.
+     */
+    private setupPipelines;
+    /**
+     * Start periodic cleanup of expired pending tool calls.
+     */
+    private startPendingCallCleanup;
+    /**
+     * Stop the pending call cleanup timer.
+     */
+    private stopPendingCallCleanup;
+    /**
+     * Process buffered messages from the MCP client.
+     * This is where policy enforcement happens.
+     */
+    private processClientMessages;
+    /**
+     * Process buffered messages from the MCP server.
+     * Applies response scanning before forwarding to the client.
+     */
+    private processServerMessages;
+    /**
+     * Handle a single message from the MCP server.
+     * If it's a response to a tools/call we tracked, scan it.
+     */
+    private handleServerMessage;
+    /**
+     * Build a redacted MCP response by replacing text content.
+     */
+    private buildRedactedResponse;
+    /**
+     * Handle a single message from the MCP client.
+     *
+     * Security check order (defense in depth):
+     *   1. Kill switch — if active, deny ALL calls immediately
+     *   2. Injection detection — scan arguments for prompt injection
+     *   3. Egress control — check for blocked URLs/IPs
+     *   4. Policy engine — evaluate rules (existing behavior)
+     *   5. Chain detection — record call and check for suspicious sequences
+     */
+    private handleClientMessage;
+    /**
+     * Handle an allowed tool call — forward to server.
+     */
+    private handleAllow;
+    /**
+     * Handle a denied tool call — return error to client, never forward.
+     */
+    private handleDeny;
+    /**
+     * Handle a prompt tool call — ask for human approval.
+     */
+    private handlePrompt;
+    /**
+     * Extract scannable text from a JSON-RPC error response.
+     */
+    private extractErrorText;
+    /**
+     * Write a JSON-RPC message to the MCP server (child's stdin).
+     */
+    private writeToServer;
+    /**
+     * Write a JSON-RPC message to the MCP client (our stdout).
+     */
+    private writeToClient;
+}
+/**
+ * Create a terminal-based prompt handler.
+ *
+ * IMPORTANT: stdin/stdout are reserved for MCP JSON-RPC protocol.
+ * We open /dev/tty (Unix) or CON (Windows) directly to read from
+ * the controlling terminal. This prevents conflicts with the
+ * MCP message stream on stdin.
+ *
+ * Output goes to stderr (safe — MCP only uses stdout).
+ */
+declare function createTerminalPromptHandler(): (tool: string, args: Record<string, unknown>, message: string) => Promise<boolean>;
+
+/**
+ * Agent Wall Dashboard Server
+ *
+ * HTTP + WebSocket server that bridges proxy events to a browser-based
+ * security dashboard. Serves the built React SPA and streams real-time
+ * events over WebSocket.
+ *
+ * Usage:
+ *   const dashboard = new DashboardServer({ port: 61100, proxy, killSwitch });
+ *   await dashboard.start();
+ */
+
+type WsMessageType = "event" | "stats" | "audit" | "killSwitch" | "ruleHits" | "config" | "welcome";
+interface WsMessage<T = unknown> {
+    type: WsMessageType;
+    ts: string;
+    payload: T;
+}
+interface ProxyEventPayload {
+    event: string;
+    tool: string;
+    detail: string;
+    severity: "info" | "warn" | "critical";
+}
+interface StatsPayload {
+    forwarded: number;
+    denied: number;
+    prompted: number;
+    total: number;
+    scanned: number;
+    responseBlocked: number;
+    responseRedacted: number;
+    uptime: number;
+    killSwitchActive: boolean;
+}
+interface RuleHitsPayload {
+    rules: Array<{
+        name: string;
+        action: string;
+        hits: number;
+    }>;
+}
+interface ConfigPayload {
+    defaultAction: string;
+    ruleCount: number;
+    mode: string;
+    security: {
+        injection: boolean;
+        egress: boolean;
+        killSwitch: boolean;
+        chain: boolean;
+        signing: boolean;
+    };
+}
+type ClientWsMessage = {
+    type: "toggleKillSwitch";
+} | {
+    type: "getStats";
+} | {
+    type: "getConfig";
+} | {
+    type: "getAuditLog";
+    limit?: number;
+    filter?: string;
+};
+interface DashboardServerOptions {
+    /** Port to listen on */
+    port: number;
+    /** The proxy instance to observe */
+    proxy: StdioProxy;
+    /** Kill switch instance (for toggle control) */
+    killSwitch?: KillSwitch;
+    /** Policy engine (for config summary) */
+    policyEngine?: PolicyEngine;
+    /** Audit logger (for log queries) */
+    logger?: AuditLogger;
+    /** Directory containing the built React SPA */
+    staticDir?: string;
+    /** Stats broadcast interval in ms (default: 2000) */
+    statsIntervalMs?: number;
+}
+declare class DashboardServer {
+    private httpServer;
+    private wss;
+    private statsTimer;
+    private ruleHitCounts;
+    private startTime;
+    private options;
+    constructor(options: DashboardServerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Get the actual port (useful when port 0 is used for testing) */
+    getPort(): number;
+    private wireProxyEvents;
+    /** Called by the audit logger's onEntry callback */
+    handleAuditEntry(entry: AuditEntry): void;
+    private handleClientMessage;
+    private broadcast;
+    private sendTo;
+    private broadcastStats;
+    private sendStats;
+    private buildStats;
+    private sendConfig;
+    private sendRuleHits;
+    private handleHttpRequest;
+}
+
+export { type AuditEntry, AuditLogger, type AuditLoggerOptions, BufferOverflowError, type ChainDetectionResult, ChainDetector, type ChainDetectorConfig, type ChainMatchInfo, type ChainPattern, type ClientWsMessage, type ConfigPayload, DashboardServer, type DashboardServerOptions, type EgressCheckResult, EgressControl, type EgressControlConfig, type EgressUrlInfo, type FilePermissionCheckResult, InjectionDetector, type InjectionDetectorConfig, type InjectionMatch, type InjectionScanResult, type JsonRpcMessage, JsonRpcMessageSchema, type JsonRpcNotification, JsonRpcNotificationSchema, type JsonRpcRequest, JsonRpcRequestSchema, type JsonRpcResponse, JsonRpcResponseSchema, KillSwitch, type KillSwitchConfig, type KillSwitchStatus, type McpContentBlock, type PolicyConfig, PolicyEngine, type PolicyMode, type PolicyRule, type PolicyVerdict, type ProxyEventPayload, type ProxyEvents, type ProxyOptions, type RateLimitConfig, ReadBuffer, type ResponseAction, type ResponsePattern, ResponseScanner, type ResponseScannerConfig, type ResponseScannerPolicyConfig, type RuleAction, type RuleHitsPayload, type RuleMatch, type ScanFinding, type ScanResult, type SecurityConfig, type SignedAuditEntry, type StatsPayload, StdioProxy, type ToolCallParams, type ToolListResult, type WsMessage, type WsMessageType, checkFilePermissions, createDefaultScanner, createDenyResponse, createPromptResponse, createTerminalPromptHandler, deserializeMessage, discoverPolicyFile, generateDefaultConfigYaml, getDefaultPolicy, getToolCallParams, isNotification, isRegexSafe, isRequest, isResponse, isToolCall, isToolList, loadPolicy, loadPolicyFile, parsePolicyYaml, serializeMessage };