contextguard 0.1.8 → 0.2.1

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2025 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 { SecurityConfig } from "./types";
+/**
+ * Default security configuration values
+ */
+export declare const DEFAULT_CONFIG: Required<SecurityConfig>;
+/**
+ * Merges user configuration with defaults
+ * @param userConfig - User-provided configuration
+ * @returns Merged configuration with defaults
+ */
+export declare function mergeConfig(userConfig?: SecurityConfig): Required<SecurityConfig>;
+/**
+ * Validates configuration values
+ * @param config - Configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export declare function validateConfig(config: SecurityConfig): void;

package/dist/config.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Copyright (c) 2025 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.DEFAULT_CONFIG = void 0;
+exports.mergeConfig = mergeConfig;
+exports.validateConfig = validateConfig;
+/**
+ * Default security configuration values
+ */
+exports.DEFAULT_CONFIG = {
+    maxToolCallsPerMinute: 30,
+    blockedPatterns: [],
+    allowedFilePaths: [],
+    alertThreshold: 5,
+    enablePromptInjectionDetection: true,
+    enableSensitiveDataDetection: true,
+    logPath: "mcp_security.log",
+    enableProFeatures: false,
+    licenseFilePath: ".contextguard-license",
+    enableDatabaseReporting: false,
+    database: {
+        type: "json",
+        path: "contextguard_events.json",
+        batchSize: 100,
+        flushIntervalMs: 5000,
+    },
+};
+/**
+ * Merges user configuration with defaults
+ * @param userConfig - User-provided configuration
+ * @returns Merged configuration with defaults
+ */
+function mergeConfig(userConfig = {}) {
+    return {
+        ...exports.DEFAULT_CONFIG,
+        ...userConfig,
+    };
+}
+/**
+ * Validates configuration values
+ * @param config - Configuration to validate
+ * @throws Error if configuration is invalid
+ */
+function validateConfig(config) {
+    if (config.maxToolCallsPerMinute !== undefined && config.maxToolCallsPerMinute < 1) {
+        throw new Error("maxToolCallsPerMinute must be at least 1");
+    }
+    if (config.alertThreshold !== undefined && config.alertThreshold < 1) {
+        throw new Error("alertThreshold must be at least 1");
+    }
+}

package/dist/database.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright (c) 2025 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 { SecurityEvent } from "./types";
+/**
+ * Database configuration options
+ */
+export interface DatabaseConfig {
+    /** Database type */
+    type: "sqlite" | "json" | "postgresql" | "mysql";
+    /** Connection string or file path */
+    connectionString?: string;
+    /** Database file path (for SQLite/JSON) */
+    dbPath?: string;
+    /** Enable database reporting */
+    enabled: boolean;
+    /** Batch size for bulk inserts */
+    batchSize?: number;
+    /** Flush interval in milliseconds */
+    flushIntervalMs?: number;
+}
+/**
+ * Event record for database storage
+ */
+export interface EventRecord {
+    id?: number;
+    timestamp: string;
+    sessionId: string;
+    eventType: string;
+    severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+    method?: string;
+    toolName?: string;
+    userId?: string;
+    violations?: string[];
+    blocked: boolean;
+    details: string;
+    createdAt?: string;
+}
+/**
+ * Database reporter interface
+ */
+export interface IDatabaseReporter {
+    reportEvent(event: SecurityEvent, additionalData?: Record<string, unknown>): Promise<void>;
+    reportToolCall(sessionId: string, toolName: string, params: Record<string, unknown>, violations: string[], blocked: boolean): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getRecentEvents(limit?: number): Promise<EventRecord[]>;
+    getEventsBySession(sessionId: string): Promise<EventRecord[]>;
+    getEventsBySeverity(severity: string): Promise<EventRecord[]>;
+}
+/**
+ * JSON file-based database reporter
+ * Simple implementation for development and small deployments
+ */
+export declare class JSONDatabaseReporter implements IDatabaseReporter {
+    private dbPath;
+    private eventBuffer;
+    private batchSize;
+    private flushInterval;
+    private eventIdCounter;
+    constructor(config: DatabaseConfig);
+    private initializeDatabase;
+    private loadEventCounter;
+    reportEvent(event: SecurityEvent, additionalData?: Record<string, unknown>): Promise<void>;
+    reportToolCall(sessionId: string, toolName: string, params: Record<string, unknown>, violations: string[], blocked: boolean): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getRecentEvents(limit?: number): Promise<EventRecord[]>;
+    getEventsBySession(sessionId: string): Promise<EventRecord[]>;
+    getEventsBySeverity(severity: string): Promise<EventRecord[]>;
+}
+/**
+ * SQLite database reporter
+ * For production deployments with better performance
+ */
+export declare class SQLiteDatabaseReporter implements IDatabaseReporter {
+    private dbPath;
+    private eventBuffer;
+    private batchSize;
+    private flushInterval;
+    constructor(config: DatabaseConfig);
+    reportEvent(_event: SecurityEvent, _additionalData?: Record<string, unknown>): Promise<void>;
+    reportToolCall(_sessionId: string, _toolName: string, _params: Record<string, unknown>, _violations: string[], _blocked: boolean): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getRecentEvents(_limit?: number): Promise<EventRecord[]>;
+    getEventsBySession(_sessionId: string): Promise<EventRecord[]>;
+    getEventsBySeverity(_severity: string): Promise<EventRecord[]>;
+}
+/**
+ * PostgreSQL database reporter
+ * For enterprise deployments with high volume
+ */
+export declare class PostgreSQLDatabaseReporter implements IDatabaseReporter {
+    private connectionString;
+    private eventBuffer;
+    private batchSize;
+    constructor(config: DatabaseConfig);
+    reportEvent(_event: SecurityEvent, _additionalData?: Record<string, unknown>): Promise<void>;
+    reportToolCall(_sessionId: string, _toolName: string, _params: Record<string, unknown>, _violations: string[], _blocked: boolean): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getRecentEvents(_limit?: number): Promise<EventRecord[]>;
+    getEventsBySession(_sessionId: string): Promise<EventRecord[]>;
+    getEventsBySeverity(_severity: string): Promise<EventRecord[]>;
+}
+/**
+ * Database reporter factory
+ * Creates appropriate reporter based on configuration
+ */
+export declare class DatabaseReporterFactory {
+    static create(config: DatabaseConfig): IDatabaseReporter;
+}

package/dist/database.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Copyright (c) 2025 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.DatabaseReporterFactory = exports.PostgreSQLDatabaseReporter = exports.SQLiteDatabaseReporter = exports.JSONDatabaseReporter = void 0;
+const fs = __importStar(require("fs"));
+/**
+ * JSON file-based database reporter
+ * Simple implementation for development and small deployments
+ */
+class JSONDatabaseReporter {
+    constructor(config) {
+        this.eventBuffer = [];
+        this.flushInterval = null;
+        this.eventIdCounter = 0;
+        this.dbPath = config.dbPath || "contextguard_events.json";
+        this.batchSize = config.batchSize || 100;
+        // Initialize database file if it doesn't exist
+        this.initializeDatabase();
+        // Load existing event count for ID generation
+        this.loadEventCounter();
+        // Set up auto-flush
+        if (config.flushIntervalMs) {
+            this.flushInterval = setInterval(() => {
+                this.flush().catch(err => console.error("Auto-flush error:", err));
+            }, config.flushIntervalMs);
+        }
+    }
+    initializeDatabase() {
+        if (!fs.existsSync(this.dbPath)) {
+            fs.writeFileSync(this.dbPath, JSON.stringify({ events: [] }, null, 2));
+        }
+    }
+    loadEventCounter() {
+        try {
+            const data = JSON.parse(fs.readFileSync(this.dbPath, "utf-8"));
+            this.eventIdCounter = data.events?.length || 0;
+        }
+        catch (error) {
+            console.error("Failed to load event counter:", error);
+            this.eventIdCounter = 0;
+        }
+    }
+    async reportEvent(event, additionalData) {
+        const record = {
+            id: ++this.eventIdCounter,
+            timestamp: event.timestamp,
+            sessionId: event.sessionId,
+            eventType: event.eventType,
+            severity: event.severity,
+            blocked: false,
+            details: JSON.stringify({ ...event.details, ...additionalData }),
+            createdAt: new Date().toISOString(),
+        };
+        this.eventBuffer.push(record);
+        // Auto-flush if buffer is full
+        if (this.eventBuffer.length >= this.batchSize) {
+            await this.flush();
+        }
+    }
+    async reportToolCall(sessionId, toolName, params, violations, blocked) {
+        const record = {
+            id: ++this.eventIdCounter,
+            timestamp: new Date().toISOString(),
+            sessionId,
+            eventType: "TOOL_CALL",
+            severity: violations.length > 0 ? "HIGH" : "LOW",
+            toolName,
+            violations,
+            blocked,
+            details: JSON.stringify({ params, violations }),
+            createdAt: new Date().toISOString(),
+        };
+        this.eventBuffer.push(record);
+        if (this.eventBuffer.length >= this.batchSize) {
+            await this.flush();
+        }
+    }
+    async flush() {
+        if (this.eventBuffer.length === 0)
+            return;
+        try {
+            // Read existing data
+            const data = JSON.parse(fs.readFileSync(this.dbPath, "utf-8"));
+            // Append new events
+            data.events = data.events || [];
+            data.events.push(...this.eventBuffer);
+            // Write back to file
+            fs.writeFileSync(this.dbPath, JSON.stringify(data, null, 2));
+            // Clear buffer
+            this.eventBuffer = [];
+        }
+        catch (error) {
+            console.error("Failed to flush events to database:", error);
+            throw error;
+        }
+    }
+    async close() {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+            this.flushInterval = null;
+        }
+        await this.flush();
+    }
+    async getRecentEvents(limit = 100) {
+        try {
+            const data = JSON.parse(fs.readFileSync(this.dbPath, "utf-8"));
+            const events = data.events || [];
+            return events.slice(-limit).reverse();
+        }
+        catch (error) {
+            console.error("Failed to read events:", error);
+            return [];
+        }
+    }
+    async getEventsBySession(sessionId) {
+        try {
+            const data = JSON.parse(fs.readFileSync(this.dbPath, "utf-8"));
+            const events = data.events || [];
+            return events.filter((e) => e.sessionId === sessionId);
+        }
+        catch (error) {
+            console.error("Failed to read events:", error);
+            return [];
+        }
+    }
+    async getEventsBySeverity(severity) {
+        try {
+            const data = JSON.parse(fs.readFileSync(this.dbPath, "utf-8"));
+            const events = data.events || [];
+            return events.filter((e) => e.severity === severity);
+        }
+        catch (error) {
+            console.error("Failed to read events:", error);
+            return [];
+        }
+    }
+}
+exports.JSONDatabaseReporter = JSONDatabaseReporter;
+/**
+ * SQLite database reporter
+ * For production deployments with better performance
+ */
+class SQLiteDatabaseReporter {
+    constructor(config) {
+        this.eventBuffer = [];
+        this.flushInterval = null;
+        this.dbPath = config.dbPath || "contextguard_events.db";
+        this.batchSize = config.batchSize || 100;
+        console.warn("SQLite reporter requires 'better-sqlite3' package. " +
+            "Install with: npm install better-sqlite3");
+        // Note: Actual SQLite implementation would require better-sqlite3
+        // This is a placeholder that falls back to JSON
+        console.warn("Falling back to JSON reporter. Install better-sqlite3 for SQLite support.");
+    }
+    async reportEvent(_event, _additionalData) {
+        // Placeholder - would use SQLite in production
+        console.log("SQLite reporter not implemented, use JSONDatabaseReporter");
+    }
+    async reportToolCall(_sessionId, _toolName, _params, _violations, _blocked) {
+        // Placeholder
+        console.log("SQLite reporter not implemented, use JSONDatabaseReporter");
+    }
+    async flush() {
+        // Placeholder
+    }
+    async close() {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+        }
+    }
+    async getRecentEvents(_limit) {
+        return [];
+    }
+    async getEventsBySession(_sessionId) {
+        return [];
+    }
+    async getEventsBySeverity(_severity) {
+        return [];
+    }
+}
+exports.SQLiteDatabaseReporter = SQLiteDatabaseReporter;
+/**
+ * PostgreSQL database reporter
+ * For enterprise deployments with high volume
+ */
+class PostgreSQLDatabaseReporter {
+    constructor(config) {
+        this.eventBuffer = [];
+        this.connectionString = config.connectionString || "";
+        this.batchSize = config.batchSize || 1000;
+        console.warn("PostgreSQL reporter requires 'pg' package. " +
+            "Install with: npm install pg");
+    }
+    async reportEvent(_event, _additionalData) {
+        // Placeholder - would use pg library in production
+        console.log("PostgreSQL reporter not implemented, use JSONDatabaseReporter");
+    }
+    async reportToolCall(_sessionId, _toolName, _params, _violations, _blocked) {
+        // Placeholder
+        console.log("PostgreSQL reporter not implemented, use JSONDatabaseReporter");
+    }
+    async flush() {
+        // Placeholder
+    }
+    async close() {
+        // Placeholder
+    }
+    async getRecentEvents(_limit) {
+        return [];
+    }
+    async getEventsBySession(_sessionId) {
+        return [];
+    }
+    async getEventsBySeverity(_severity) {
+        return [];
+    }
+}
+exports.PostgreSQLDatabaseReporter = PostgreSQLDatabaseReporter;
+/**
+ * Database reporter factory
+ * Creates appropriate reporter based on configuration
+ */
+class DatabaseReporterFactory {
+    static create(config) {
+        if (!config.enabled) {
+            return new NullDatabaseReporter();
+        }
+        switch (config.type) {
+            case "json":
+                return new JSONDatabaseReporter(config);
+            case "sqlite":
+                return new SQLiteDatabaseReporter(config);
+            case "postgresql":
+                return new PostgreSQLDatabaseReporter(config);
+            default:
+                console.warn(`Unknown database type: ${config.type}, using JSON`);
+                return new JSONDatabaseReporter(config);
+        }
+    }
+}
+exports.DatabaseReporterFactory = DatabaseReporterFactory;
+/**
+ * Null reporter for when database is disabled
+ */
+class NullDatabaseReporter {
+    async reportEvent() { }
+    async reportToolCall() { }
+    async flush() { }
+    async close() { }
+    async getRecentEvents() { return []; }
+    async getEventsBySession() { return []; }
+    async getEventsBySeverity() { return []; }
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export { createAgent } from "./agent";
+export type { Agent } from "./agent";
+export type { MCPMessage } from "./types/mcp";
+export { createPolicyChecker, DEFAULT_POLICY } from "./policy";
+export type { PolicyChecker } from "./policy";
+export { createLogger } from "./logger";
+export type { Logger, SecurityStatistics } from "./logger";
+export { createSupabaseClient } from "./lib/supabase-client";
+export type { SupabaseConfig } from "./lib/supabase-client";
+export type { AgentPolicyRow, AgentPolicyInsert, AgentPolicyUpdate, SecurityEventRow, SecurityEventInsert, SecurityEventUpdate, AgentStatusRow, AgentStatusInsert, AgentStatusUpdate, EventStatisticsRow, SecuritySeverity, AgentStatus, } from "./types/database.types";

package/dist/index.js

@@ -0,0 +1,18 @@
+"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 = exports.createLogger = exports.DEFAULT_POLICY = exports.createPolicyChecker = exports.createAgent = void 0;
+var agent_1 = require("./agent");
+Object.defineProperty(exports, "createAgent", { enumerable: true, get: function () { return agent_1.createAgent; } });
+var policy_1 = require("./policy");
+Object.defineProperty(exports, "createPolicyChecker", { enumerable: true, get: function () { return policy_1.createPolicyChecker; } });
+Object.defineProperty(exports, "DEFAULT_POLICY", { enumerable: true, get: function () { return policy_1.DEFAULT_POLICY; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "createLogger", { enumerable: true, get: function () { return logger_1.createLogger; } });
+var supabase_client_1 = require("./lib/supabase-client");
+Object.defineProperty(exports, "createSupabaseClient", { enumerable: true, get: function () { return supabase_client_1.createSupabaseClient; } });

package/dist/init.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * contextguard init — automatically patch claude_desktop_config.json
+ * so that every MCP server is wrapped with ContextGuard.
+ */
+export declare function runInit(argv: string[]): void;