contextguard 0.1.8 → 0.2.1

package/dist/init.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * contextguard init — automatically patch claude_desktop_config.json
+ * so that every MCP server is wrapped with ContextGuard.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// ── Config file detection ────────────────────────────────────────────────────
+function findConfigPath() {
+    const home = os.homedir();
+    let candidates = [];
+    switch (process.platform) {
+        case "darwin":
+            candidates = [
+                path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+            ];
+            break;
+        case "win32":
+            candidates = [
+                path.join(process.env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json"),
+            ];
+            break;
+        default: // Linux
+            candidates = [
+                path.join(home, ".config", "Claude", "claude_desktop_config.json"),
+                path.join(home, ".config", "claude", "claude_desktop_config.json"),
+            ];
+    }
+    return candidates.find((p) => fs.existsSync(p)) ?? null;
+}
+// ── Wrapping helpers ─────────────────────────────────────────────────────────
+function isAlreadyWrapped(server) {
+    if (server.command === "npx" && server.args?.[1] === "contextguard") {
+        return true;
+    }
+    if (server.command === "contextguard") {
+        return true;
+    }
+    return false;
+}
+/**
+ * Wrap an MCP server entry:
+ *   { command, args } → { command: "npx", args: ["-y", "contextguard", "--", <original command+args>] }
+ */
+function wrapServer(server, apiKey) {
+    const originalCmd = [server.command, ...(server.args ?? [])];
+    return {
+        command: "npx",
+        args: ["-y", "contextguard", "--", ...originalCmd],
+        env: {
+            ...server.env,
+            CONTEXTGUARD_API_KEY: apiKey,
+        },
+    };
+}
+function parseInitArgs(argv) {
+    let apiKey = "";
+    let configPath;
+    let dryRun = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if ((arg === "--api-key" || arg === "-k") && argv[i + 1]) {
+            apiKey = argv[++i];
+        }
+        else if ((arg === "--config" || arg === "-c") && argv[i + 1]) {
+            configPath = argv[++i];
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+    }
+    return { apiKey, configPath, dryRun };
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+function runInit(argv) {
+    const { apiKey, configPath: customPath, dryRun } = parseInitArgs(argv);
+    if (!apiKey) {
+        console.error("\n❌  Missing required argument: --api-key <key>\n" +
+            "    Get your key from the ContextGuard dashboard → Settings → API Keys\n");
+        process.exit(1);
+    }
+    // Locate config
+    const configPath = customPath ?? findConfigPath();
+    if (!configPath) {
+        console.error("\n❌  Could not find claude_desktop_config.json.\n" +
+            "    Is Claude Desktop installed? Or specify the path with --config <path>\n");
+        process.exit(1);
+    }
+    console.log(`\n🔍  Config found: ${configPath}`);
+    // Read and parse
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    }
+    catch (err) {
+        console.error(`\n❌  Failed to parse config: ${configPath}`);
+        console.error(`    Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const servers = { ...(config.mcpServers ?? {}) };
+    const names = Object.keys(servers);
+    if (names.length === 0) {
+        console.log("\n⚠️   No MCP servers found in config — nothing to wrap.\n");
+        process.exit(0);
+    }
+    console.log(`\n📋  Found ${names.length} MCP server(s):\n`);
+    let wrapped = 0;
+    let skipped = 0;
+    for (const [name, server] of Object.entries(servers)) {
+        if (isAlreadyWrapped(server)) {
+            console.log(`   ⏭   ${name}  (already wrapped, skipping)`);
+            skipped++;
+        }
+        else {
+            servers[name] = wrapServer(server, apiKey);
+            console.log(`   ✅  ${name}  → wrapped`);
+            wrapped++;
+        }
+    }
+    console.log(`\n📝  ${wrapped} wrapped, ${skipped} already configured.\n`);
+    if (wrapped === 0) {
+        console.log("✨  Nothing to do — all servers are already protected.\n");
+        process.exit(0);
+    }
+    const updated = { ...config, mcpServers: servers };
+    if (dryRun) {
+        console.log("⚠️   --dry-run: no changes written. Preview:\n");
+        console.log(JSON.stringify(updated, null, 2));
+        process.exit(0);
+    }
+    // Backup
+    const backupPath = configPath + ".bak";
+    fs.copyFileSync(configPath, backupPath);
+    console.log(`💾  Backup saved: ${backupPath}`);
+    // Write
+    fs.writeFileSync(configPath, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+    console.log(`✅  Config updated: ${configPath}`);
+    console.log("\n🚀  Done! Restart Claude Desktop to activate ContextGuard.\n" +
+        "    Dashboard: https://contextguard.dev/dashboard\n");
+}

package/dist/lib/supabase-client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { AgentPolicyRow, SecurityEventRow } from "../types/database.types";
+/**
+ * Supabase configuration
+ */
+export interface SupabaseConfig {
+    url: string;
+    serviceKey: string;
+    agentId?: string;
+}
+/**
+ * Supabase client for agent-dashboard communication
+ */
+export interface SupabaseClient {
+    reportEvent: (event: SecurityEventRow) => Promise<void>;
+    fetchPolicy: (agentId: string) => Promise<AgentPolicyRow | null>;
+    updateAgentStatus: (agentId: string, status: string) => Promise<void>;
+}
+/**
+ * Create a Supabase client
+ */
+export declare const createSupabaseClient: (config: SupabaseConfig) => SupabaseClient;

package/dist/lib/supabase-client.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSupabaseClient = void 0;
+const supabase_js_1 = require("@supabase/supabase-js");
+/**
+ * Create a Supabase client
+ */
+const createSupabaseClient = (config) => {
+    const { url, serviceKey } = config;
+    // Create Supabase client using the official SDK
+    const supabase = (0, supabase_js_1.createClient)(url, serviceKey, {
+        auth: {
+            persistSession: false,
+            autoRefreshToken: false,
+        },
+    });
+    return {
+        /**
+         * Report a security event to Supabase
+         */
+        reportEvent: async (event) => {
+            try {
+                const eventData = {
+                    agent_id: config.agentId || "unknown",
+                    event_type: event.event_type,
+                    severity: event.severity,
+                    details: event.details,
+                    session_id: event.session_id,
+                    timestamp: event.timestamp,
+                };
+                const { error } = await supabase
+                    .from("events")
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    .insert(eventData);
+                if (error) {
+                    console.error("Failed to report event to Supabase:", error);
+                }
+            }
+            catch (error) {
+                console.error("Failed to report event to Supabase:", error);
+                // Don't throw - we don't want to break the agent if reporting fails
+            }
+        },
+        /**
+         * Fetch policy configuration for an agent
+         */
+        fetchPolicy: async (agentId) => {
+            try {
+                const { data, error } = await supabase
+                    .from("policies")
+                    .select("*")
+                    .eq("agent_id", agentId)
+                    .single();
+                if (error) {
+                    console.error("Failed to fetch policy from Supabase:", error);
+                    return null;
+                }
+                return data || null;
+            }
+            catch (error) {
+                console.error("Failed to fetch policy from Supabase:", error);
+                return null;
+            }
+        },
+        /**
+         * Update agent status
+         */
+        updateAgentStatus: async (agentId, status) => {
+            try {
+                const statusData = {
+                    agent_id: agentId,
+                    status: status,
+                    last_heartbeat: new Date().toISOString(),
+                };
+                const { error } = await supabase
+                    .from("agents")
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    .upsert(statusData, {
+                    onConflict: "agent_id",
+                });
+                if (error) {
+                    console.error("Failed to update agent status:", error);
+                }
+            }
+            catch (error) {
+                console.error("Failed to update agent status:", error);
+            }
+        },
+    };
+};
+exports.createSupabaseClient = createSupabaseClient;

package/dist/logger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { SupabaseClient } from "./lib/supabase-client";
+import { SecurityEventRow, SecuritySeverity } from "./types/database.types";
+/**
+ * Security statistics interface
+ */
+export interface SecurityStatistics {
+    totalEvents: number;
+    eventsByType: Record<string, number>;
+    eventsBySeverity: Record<string, number>;
+    recentEvents: SecurityEventRow[];
+}
+/**
+ * Logger interface
+ */
+export interface Logger {
+    logEvent: (eventType: string, severity: SecuritySeverity, details: Record<string, unknown>, sessionId: string) => void;
+    getStatistics: () => SecurityStatistics;
+    clearEvents: () => void;
+    getAllEvents: () => SecurityEventRow[];
+}
+/**
+ * Create a security event logger
+ * @param logFile - Path to log file
+ * @param supabaseClient - Optional Supabase client for remote logging
+ * @param agentId - Agent identifier for event attribution
+ * @param alertWebhook - Optional webhook URL for HIGH/CRITICAL alerts
+ * @param alertOnSeverity - Severity levels that trigger webhook alerts
+ * @returns Logger functions
+ */
+export declare const createLogger: (logFile?: string, supabaseClient?: SupabaseClient, agentId?: string, alertWebhook?: string, alertOnSeverity?: string[]) => Logger;

package/dist/logger.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = void 0;
+const fs = __importStar(require("fs"));
+const MAX_STORED_EVENTS = 1000;
+/**
+ * Count events by a specific field
+ */
+const countByField = (events, field) => {
+    const counts = {};
+    for (const event of events) {
+        const value = String(event[field]);
+        counts[value] = (counts[value] || 0) + 1;
+    }
+    return counts;
+};
+const fireWebhookAlert = (webhookUrl, event) => {
+    fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            text: `[ContextGuard] ${event.severity} — ${event.event_type}`,
+            agent_id: event.agent_id,
+            session_id: event.session_id,
+            details: event.details,
+            timestamp: event.timestamp,
+        }),
+    }).catch((err) => {
+        console.error("Failed to fire webhook alert:", err);
+    });
+};
+/**
+ * Create a security event logger
+ * @param logFile - Path to log file
+ * @param supabaseClient - Optional Supabase client for remote logging
+ * @param agentId - Agent identifier for event attribution
+ * @param alertWebhook - Optional webhook URL for HIGH/CRITICAL alerts
+ * @param alertOnSeverity - Severity levels that trigger webhook alerts
+ * @returns Logger functions
+ */
+const createLogger = (logFile = "mcp_security.log", supabaseClient, agentId = "", alertWebhook, alertOnSeverity = ["HIGH", "CRITICAL"]) => {
+    let events = [];
+    return {
+        /**
+         * Log a security event
+         */
+        logEvent: (eventType, severity, details, sessionId) => {
+            const event = {
+                timestamp: new Date().toISOString(),
+                event_type: eventType,
+                severity,
+                details,
+                session_id: sessionId,
+                agent_id: agentId,
+                created_at: new Date().toISOString(),
+                id: "",
+            };
+            events.push(event);
+            // Keep only recent events in memory
+            if (events.length > MAX_STORED_EVENTS) {
+                events = events.slice(-MAX_STORED_EVENTS);
+            }
+            // Write to log file
+            try {
+                fs.appendFileSync(logFile, JSON.stringify(event) + "\n");
+            }
+            catch (error) {
+                console.error("Failed to write to log file:", error);
+            }
+            // Alert on high/critical severity
+            if (severity === "HIGH" || severity === "CRITICAL") {
+                console.error(`[SECURITY ALERT] ${eventType}: ${JSON.stringify(details)}`);
+            }
+            // Fire webhook alert if configured and severity matches
+            if (alertWebhook && alertOnSeverity.includes(severity)) {
+                fireWebhookAlert(alertWebhook, event);
+            }
+            // Report to Supabase if client is provided
+            if (supabaseClient) {
+                supabaseClient.reportEvent(event).catch((err) => {
+                    console.error("Failed to report event to Supabase:", err);
+                });
+            }
+        },
+        /**
+         * Get security statistics
+         */
+        getStatistics: () => ({
+            totalEvents: events.length,
+            eventsByType: countByField(events, "event_type"),
+            eventsBySeverity: countByField(events, "severity"),
+            recentEvents: events.slice(-10),
+        }),
+        /**
+         * Clear all logged events
+         */
+        clearEvents: () => {
+            events = [];
+        },
+        /**
+         * Get all events
+         */
+        getAllEvents: () => [...events],
+    };
+};
+exports.createLogger = createLogger;

package/dist/mcp-security-wrapper.d.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+interface SecurityConfig {
+    maxToolCallsPerMinute?: number;
+    enablePromptInjectionDetection?: boolean;
+    enableSensitiveDataDetection?: boolean;
+    enablePathTraversalPrevention?: boolean;
+    mode?: "monitor" | "block";
+    blockedPatterns?: string[];
+    allowedFilePaths?: string[];
+    alertThreshold?: number;
+    logPath?: string;
+    logLevel?: "debug" | "info" | "warn" | "error";
+    transport?: "stdio" | "sse" | "http";
+    port?: number;
+    targetUrl?: string;
+}
+interface SecurityEvent {
+    timestamp: string;
+    eventType: string;
+    severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+    details: Record<string, unknown>;
+    sessionId: string;
+}
+declare class SecurityPolicy {
+    private config;
+    private sensitiveDataPatterns;
+    private promptInjectionPatterns;
+    constructor(config: SecurityConfig);
+    get isBlockingMode(): boolean;
+    get rawConfig(): Required<SecurityConfig>;
+    checkPromptInjection(text: string): string[];
+    checkSensitiveData(text: string): string[];
+    checkFileAccess(filePath: string): string[];
+    checkRateLimit(timestamps: number[]): boolean;
+}
+declare class SecurityLogger {
+    private logFile;
+    private events;
+    constructor(logFile?: string);
+    logEvent(eventType: string, severity: SecurityEvent["severity"], details: Record<string, unknown>, sessionId: string): void;
+    getStatistics(): Record<string, unknown>;
+    private countByField;
+}
+declare class MCPSecurityWrapper {
+    private serverCommand;
+    private policy;
+    private logger;
+    private process;
+    private toolCallTimestamps;
+    private sessionId;
+    private clientMessageBuffer;
+    private serverMessageBuffer;
+    constructor(serverCommand: string[], policy: SecurityPolicy, logger: SecurityLogger);
+    start(): Promise<void>;
+    private handleClientInput;
+    private processClientMessage;
+    /** Returns violations + whether to block (block only if mode==="block") */
+    private inspectOutbound;
+    private handleServerOutput;
+}
+/**
+ * SSE proxy: listens on `port`, forwards every request to `targetUrl`,
+ * scanning both request body (outbound) and response body (inbound).
+ *
+ * Supports:
+ *   - Standard JSON-RPC over HTTP POST  (MCP HTTP transport)
+ *   - Server-Sent Events streams        (MCP SSE transport)
+ */
+declare class MCPSSEProxy {
+    private policy;
+    private logger;
+    private sessionId;
+    private toolCallTimestamps;
+    constructor(policy: SecurityPolicy, logger: SecurityLogger);
+    start(port: number, targetUrl: string): void;
+    private inspectOutbound;
+}
+export { MCPSecurityWrapper, MCPSSEProxy, SecurityPolicy, SecurityLogger };