@dotsetlabs/bellwether 0.10.0

package/dist/security/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Security testing types for deterministic vulnerability detection.
+ *
+ * This module defines types for the security baseline feature, which runs
+ * deterministic security tests in check mode without requiring LLM.
+ */
+/**
+ * Categories of security vulnerabilities tested.
+ * Each category maps to a specific class of attack vectors.
+ */
+export type SecurityCategory = 'sql_injection' | 'xss' | 'path_traversal' | 'command_injection' | 'ssrf' | 'error_disclosure';
+/**
+ * Risk level classification for security findings.
+ * Based on potential impact and exploitability.
+ */
+export type RiskLevel = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/**
+ * A security test payload used to probe for vulnerabilities.
+ */
+export interface SecurityPayload {
+    /** Category of vulnerability being tested */
+    category: SecurityCategory;
+    /** The actual payload string */
+    payload: string;
+    /** Human-readable description of the test */
+    description: string;
+    /** Expected tool behavior when receiving this payload */
+    expectedBehavior: 'reject' | 'sanitize' | 'accept';
+}
+/**
+ * Result of a single security test execution.
+ */
+export interface SecurityTestResult {
+    /** Category of vulnerability tested */
+    category: SecurityCategory;
+    /** Payload that was tested */
+    payload: string;
+    /** Parameter that was tested */
+    parameter: string;
+    /** Whether the test passed (tool behaved safely) */
+    passed: boolean;
+    /** Risk level if a finding was discovered */
+    riskLevel: RiskLevel;
+    /** Finding details if a vulnerability was detected */
+    finding?: SecurityFinding;
+    /** Response behavior observed */
+    behavior: 'rejected' | 'sanitized' | 'accepted' | 'error';
+}
+/**
+ * A security finding discovered during testing.
+ */
+export interface SecurityFinding {
+    /** Category of vulnerability */
+    category: SecurityCategory;
+    /** Risk level assessment */
+    riskLevel: RiskLevel;
+    /** Short title for the finding */
+    title: string;
+    /** Detailed description of the issue */
+    description: string;
+    /** Evidence supporting the finding */
+    evidence: string;
+    /** Suggested remediation steps */
+    remediation: string;
+    /** Common Weakness Enumeration ID (e.g., "CWE-89") */
+    cweId: string;
+    /** Parameter where the vulnerability was found */
+    parameter: string;
+    /** Tool where the vulnerability was found */
+    tool: string;
+}
+/**
+ * Security fingerprint for a tool, stored in the baseline.
+ * Captures the security testing state and findings for comparison.
+ */
+export interface SecurityFingerprint {
+    /** Whether security testing was performed */
+    tested: boolean;
+    /** Categories that were tested */
+    categoriesTested: SecurityCategory[];
+    /** Findings discovered during testing */
+    findings: SecurityFinding[];
+    /** Overall risk score (0-100, higher = more risk) */
+    riskScore: number;
+    /** When security testing was last run */
+    testedAt: string;
+    /** Hash of findings for quick comparison */
+    findingsHash: string;
+}
+/**
+ * Security baseline comparison result.
+ * Shows how security posture changed between baselines.
+ */
+export interface SecurityDiff {
+    /** New findings that didn't exist in the previous baseline */
+    newFindings: SecurityFinding[];
+    /** Findings that were resolved (existed before, not now) */
+    resolvedFindings: SecurityFinding[];
+    /** Previous risk score */
+    previousRiskScore: number;
+    /** Current risk score */
+    currentRiskScore: number;
+    /** Risk score change (positive = worse, negative = better) */
+    riskScoreChange: number;
+    /** Whether security posture degraded */
+    degraded: boolean;
+    /** Summary of security changes */
+    summary: string;
+}
+/**
+ * Options for running security tests.
+ */
+export interface SecurityTestOptions {
+    /** Categories to test (default: all) */
+    categories?: SecurityCategory[];
+    /** Maximum payloads per category (default from constants) */
+    maxPayloadsPerCategory?: number;
+    /** Timeout per test in ms (default from constants) */
+    timeout?: number;
+    /** Whether to test for error disclosure */
+    testErrorDisclosure?: boolean;
+}
+/**
+ * Context required to run security tests on a tool.
+ */
+export interface SecurityTestContext {
+    /** The tool being tested */
+    toolName: string;
+    /** Tool description */
+    toolDescription: string;
+    /** Tool input schema */
+    inputSchema?: Record<string, unknown>;
+    /** Function to call the tool with arguments */
+    callTool: (args: Record<string, unknown>) => Promise<SecurityToolCallResult>;
+}
+/**
+ * Result from calling a tool during security testing.
+ */
+export interface SecurityToolCallResult {
+    /** Whether the call resulted in an error */
+    isError: boolean;
+    /** Text content of the response */
+    content: string;
+    /** Raw error message if isError is true */
+    errorMessage?: string;
+}
+/**
+ * Aggregate security results for an entire server.
+ */
+export interface SecurityReport {
+    /** When the security test was run */
+    testedAt: string;
+    /** Total tools tested */
+    toolsTested: number;
+    /** Total findings across all tools */
+    totalFindings: number;
+    /** Findings by risk level */
+    findingsByRiskLevel: Record<RiskLevel, number>;
+    /** Findings by category */
+    findingsByCategory: Record<SecurityCategory, number>;
+    /** Overall server risk score (0-100) */
+    overallRiskScore: number;
+    /** Per-tool security fingerprints */
+    toolFingerprints: Map<string, SecurityFingerprint>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/security/types.js

@@ -0,0 +1,8 @@
+/**
+ * Security testing types for deterministic vulnerability detection.
+ *
+ * This module defines types for the security baseline feature, which runs
+ * deterministic security tests in check mode without requiring LLM.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/transport/base-transport.d.ts

@@ -0,0 +1,59 @@
+import { EventEmitter } from 'events';
+import type { JSONRPCMessage } from './types.js';
+import { type Logger } from '../logging/logger.js';
+/**
+ * Base configuration for all transports.
+ */
+export interface BaseTransportConfig {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Events emitted by transports.
+ */
+export interface TransportEvents {
+    message: (msg: JSONRPCMessage) => void;
+    error: (error: Error) => void;
+    close: () => void;
+}
+/**
+ * Abstract base class for MCP transports.
+ *
+ * Transports handle the low-level communication with MCP servers,
+ * including message framing and connection management.
+ *
+ * All transports emit:
+ * - 'message': When a JSON-RPC message is received
+ * - 'error': When an error occurs
+ * - 'close': When the connection is closed
+ */
+export declare abstract class BaseTransport extends EventEmitter {
+    protected debug: boolean;
+    protected logger: Logger;
+    constructor(config?: BaseTransportConfig);
+    /**
+     * Send a JSON-RPC message to the server.
+     */
+    abstract send(message: JSONRPCMessage): void;
+    /**
+     * Close the transport connection.
+     */
+    abstract close(): void;
+    /**
+     * Check if the transport is connected.
+     */
+    abstract isConnected(): boolean;
+    /**
+     * Log a debug message if debug mode is enabled.
+     */
+    protected log(message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof TransportEvents>(event: K, listener: TransportEvents[K]): this;
+    emit<K extends keyof TransportEvents>(event: K, ...args: Parameters<TransportEvents[K]>): boolean;
+}
+/**
+ * Transport type identifier.
+ */
+export type TransportType = 'stdio' | 'sse' | 'streamable-http';
+//# sourceMappingURL=base-transport.d.ts.map

package/dist/transport/base-transport.js

@@ -0,0 +1,38 @@
+import { EventEmitter } from 'events';
+import { getLogger } from '../logging/logger.js';
+/**
+ * Abstract base class for MCP transports.
+ *
+ * Transports handle the low-level communication with MCP servers,
+ * including message framing and connection management.
+ *
+ * All transports emit:
+ * - 'message': When a JSON-RPC message is received
+ * - 'error': When an error occurs
+ * - 'close': When the connection is closed
+ */
+export class BaseTransport extends EventEmitter {
+    debug;
+    logger;
+    constructor(config) {
+        super();
+        this.debug = config?.debug ?? false;
+        this.logger = getLogger('transport');
+    }
+    /**
+     * Log a debug message if debug mode is enabled.
+     */
+    log(message, data) {
+        if (this.debug) {
+            this.logger.debug(data ?? {}, message);
+        }
+    }
+    // Type-safe event methods
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+}
+//# sourceMappingURL=base-transport.js.map

package/dist/transport/http-transport.d.ts

@@ -0,0 +1,67 @@
+import type { JSONRPCMessage, JSONRPCResponse } from './types.js';
+import { BaseTransport, type BaseTransportConfig } from './base-transport.js';
+/**
+ * Configuration for HTTP Transport.
+ */
+export interface HTTPTransportConfig extends BaseTransportConfig {
+    /** Base URL of the MCP server (e.g., https://api.example.com/mcp) */
+    baseUrl: string;
+    /** Optional session ID for authenticated connections */
+    sessionId?: string;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * HTTPTransport connects to MCP servers over HTTP using POST requests.
+ *
+ * This transport is used for remote MCP servers that expose a simple
+ * HTTP endpoint. Each request is sent as a POST and the response is
+ * returned directly.
+ *
+ * This is a request-response pattern, unlike SSE which supports
+ * server-initiated messages.
+ *
+ * Expected server endpoint:
+ * - POST {baseUrl} - JSON-RPC endpoint
+ */
+export declare class HTTPTransport extends BaseTransport {
+    private connected;
+    private abortController;
+    private readonly baseUrl;
+    private readonly sessionId?;
+    private readonly headers;
+    private readonly timeout;
+    constructor(config: HTTPTransportConfig);
+    /**
+     * Initialize the HTTP transport.
+     * For HTTP, there's no persistent connection, so this just validates the URL.
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a JSON-RPC message to the server via HTTP POST.
+     *
+     * Unlike SSE transport, this method handles the response synchronously
+     * and emits a 'message' event with the response.
+     */
+    send(message: JSONRPCMessage): void;
+    /**
+     * Send a JSON-RPC message and wait for the response.
+     */
+    sendAsync(message: JSONRPCMessage): Promise<JSONRPCResponse | null>;
+    /**
+     * Handle a streaming HTTP response (text/event-stream).
+     * Includes timeout handling to prevent indefinite hangs.
+     */
+    private handleStreamingResponse;
+    /**
+     * Close the HTTP transport.
+     */
+    close(): void;
+    /**
+     * Check if the transport is connected.
+     */
+    isConnected(): boolean;
+}
+//# sourceMappingURL=http-transport.d.ts.map

package/dist/transport/http-transport.js

@@ -0,0 +1,238 @@
+import { BaseTransport } from './base-transport.js';
+import { TIMEOUTS, DISPLAY_LIMITS } from '../constants.js';
+/**
+ * HTTPTransport connects to MCP servers over HTTP using POST requests.
+ *
+ * This transport is used for remote MCP servers that expose a simple
+ * HTTP endpoint. Each request is sent as a POST and the response is
+ * returned directly.
+ *
+ * This is a request-response pattern, unlike SSE which supports
+ * server-initiated messages.
+ *
+ * Expected server endpoint:
+ * - POST {baseUrl} - JSON-RPC endpoint
+ */
+export class HTTPTransport extends BaseTransport {
+    connected = false;
+    abortController = null;
+    baseUrl;
+    sessionId;
+    headers;
+    timeout;
+    constructor(config) {
+        super(config);
+        this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.sessionId = config.sessionId;
+        this.headers = config.headers ?? {};
+        this.timeout = config.timeout ?? TIMEOUTS.DEFAULT;
+        // Add session ID to headers if provided
+        if (this.sessionId) {
+            this.headers['X-Session-Id'] = this.sessionId;
+        }
+    }
+    /**
+     * Initialize the HTTP transport.
+     * For HTTP, there's no persistent connection, so this just validates the URL.
+     */
+    async connect() {
+        this.log('Initializing HTTP transport', { baseUrl: this.baseUrl });
+        // Optionally, we could do a health check here
+        // For now, just mark as connected
+        this.connected = true;
+    }
+    /**
+     * Send a JSON-RPC message to the server via HTTP POST.
+     *
+     * Unlike SSE transport, this method handles the response synchronously
+     * and emits a 'message' event with the response.
+     */
+    send(message) {
+        if (!this.connected) {
+            this.emit('error', new Error('Transport not connected'));
+            return;
+        }
+        this.sendAsync(message).catch((error) => {
+            this.emit('error', error);
+        });
+    }
+    /**
+     * Send a JSON-RPC message and wait for the response.
+     */
+    async sendAsync(message) {
+        this.log('Sending message', { message });
+        this.abortController = new AbortController();
+        const timeoutId = setTimeout(() => {
+            this.abortController?.abort();
+        }, this.timeout);
+        try {
+            const response = await fetch(this.baseUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    ...this.headers,
+                },
+                body: JSON.stringify(message),
+                signal: this.abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => 'Unknown error');
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            const contentType = response.headers.get('content-type');
+            // Handle streaming response (for streamable HTTP)
+            if (contentType?.includes('text/event-stream')) {
+                await this.handleStreamingResponse(response);
+                return null;
+            }
+            // Handle JSON response
+            if (contentType?.includes('application/json')) {
+                const responseData = (await response.json());
+                this.emit('message', responseData);
+                return responseData;
+            }
+            // No content or unexpected content type
+            return null;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') {
+                throw new Error('Request timeout');
+            }
+            throw error;
+        }
+    }
+    /**
+     * Handle a streaming HTTP response (text/event-stream).
+     * Includes timeout handling to prevent indefinite hangs.
+     */
+    async handleStreamingResponse(response) {
+        const reader = response.body?.getReader();
+        if (!reader) {
+            return;
+        }
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let readerLocked = true;
+        /**
+         * Read with timeout to prevent indefinite hangs.
+         * Returns the read result or throws on timeout.
+         */
+        const readWithTimeout = async () => {
+            return new Promise((resolve, reject) => {
+                const timeoutId = setTimeout(() => {
+                    reject(new Error('Streaming read timeout'));
+                }, this.timeout);
+                reader.read().then((result) => {
+                    clearTimeout(timeoutId);
+                    resolve(result);
+                }, (error) => {
+                    clearTimeout(timeoutId);
+                    reject(error);
+                });
+            });
+        };
+        try {
+            let done = false;
+            while (!done) {
+                // Use timeout-wrapped read to prevent indefinite blocking
+                const result = await readWithTimeout();
+                done = result.done;
+                if (done) {
+                    break;
+                }
+                const value = result.value;
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete lines
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmedLine = line.trim();
+                    // Skip empty lines and comments
+                    if (!trimmedLine || trimmedLine.startsWith(':')) {
+                        continue;
+                    }
+                    // Parse SSE format: "data: {...}"
+                    if (trimmedLine.startsWith('data:')) {
+                        const data = trimmedLine.substring(5).trim();
+                        try {
+                            const message = JSON.parse(data);
+                            this.emit('message', message);
+                        }
+                        catch (error) {
+                            // Log streaming parse errors for visibility
+                            const preview = data.length > DISPLAY_LIMITS.TRANSPORT_DATA_PREVIEW ? data.substring(0, DISPLAY_LIMITS.TRANSPORT_DATA_PREVIEW) + '...' : data;
+                            this.logger.warn({ preview, error: error instanceof Error ? error.message : String(error) }, 'Failed to parse SSE message');
+                        }
+                    }
+                    else {
+                        // Try to parse as direct JSON
+                        try {
+                            const message = JSON.parse(trimmedLine);
+                            this.emit('message', message);
+                        }
+                        catch {
+                            // Not JSON - this is common for non-JSON lines in streams, log only in debug
+                            this.log('Skipping non-JSON line', { preview: trimmedLine.substring(0, DISPLAY_LIMITS.RESPONSE_DATA_PREVIEW) });
+                        }
+                    }
+                }
+            }
+            // Process any remaining data in buffer
+            if (buffer.trim()) {
+                try {
+                    const message = JSON.parse(buffer.trim());
+                    this.emit('message', message);
+                }
+                catch {
+                    // Ignore incomplete data
+                }
+            }
+        }
+        catch (error) {
+            // On timeout or other errors, cancel the reader to release the lock
+            if (readerLocked) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // Ignore cancel errors - reader may already be closed
+                }
+            }
+            throw error;
+        }
+        finally {
+            // Release the lock if still held
+            if (readerLocked) {
+                try {
+                    reader.releaseLock();
+                    readerLocked = false;
+                }
+                catch {
+                    // Ignore releaseLock errors - lock may already be released by cancel
+                }
+            }
+        }
+    }
+    /**
+     * Close the HTTP transport.
+     */
+    close() {
+        this.log('Closing HTTP transport');
+        this.connected = false;
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+        this.emit('close');
+    }
+    /**
+     * Check if the transport is connected.
+     */
+    isConnected() {
+        return this.connected;
+    }
+}
+//# sourceMappingURL=http-transport.js.map