@dotsetlabs/bellwether 0.10.0

package/dist/utils/network.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Network utility functions.
+ */
+/**
+ * Check if a hostname is localhost.
+ *
+ * Uses the centralized LOCALHOST_HOSTS constant to ensure consistent
+ * localhost detection across the codebase.
+ *
+ * @param hostname - The hostname to check (from URL.hostname)
+ * @returns true if the hostname is localhost
+ */
+export declare function isLocalhost(hostname: string): boolean;
+//# sourceMappingURL=network.d.ts.map

package/dist/utils/network.js

@@ -0,0 +1,17 @@
+/**
+ * Network utility functions.
+ */
+import { CLI_SECURITY } from '../constants.js';
+/**
+ * Check if a hostname is localhost.
+ *
+ * Uses the centralized LOCALHOST_HOSTS constant to ensure consistent
+ * localhost detection across the codebase.
+ *
+ * @param hostname - The hostname to check (from URL.hostname)
+ * @returns true if the hostname is localhost
+ */
+export function isLocalhost(hostname) {
+    return CLI_SECURITY.LOCALHOST_HOSTS.includes(hostname);
+}
+//# sourceMappingURL=network.js.map

package/dist/utils/sanitize.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Input sanitization utilities for prompt injection protection.
+ *
+ * These utilities help prevent malicious content in MCP server responses
+ * from manipulating LLM behavior through prompt injection attacks.
+ */
+/**
+ * Result of sanitization with metadata about what was found.
+ */
+export interface SanitizeResult {
+    /** The sanitized text */
+    sanitized: string;
+    /** Whether any potential injection patterns were detected */
+    hadInjectionPatterns: boolean;
+    /** List of detected patterns (for logging) */
+    detectedPatterns: string[];
+    /** Whether structural characters were escaped */
+    hadStructuralChars: boolean;
+}
+/**
+ * Sanitize user-provided text for safe inclusion in LLM prompts.
+ *
+ * This function:
+ * 1. Detects potential prompt injection patterns
+ * 2. Escapes structural characters that could manipulate prompt format
+ * 3. Wraps content in clear data delimiters
+ *
+ * @param text - The text to sanitize (e.g., tool description, schema)
+ * @param options - Sanitization options
+ * @returns Sanitized text safe for prompt inclusion
+ */
+export declare function sanitizeForPrompt(text: string, options?: {
+    /** Whether to escape structural characters */
+    escapeStructural?: boolean;
+    /** Whether to wrap in data delimiters */
+    wrapInDelimiters?: boolean;
+    /** Custom delimiter name */
+    delimiterName?: string;
+    /** Whether to strip detected injection patterns */
+    stripInjections?: boolean;
+}): SanitizeResult;
+/**
+ * Sanitize a JSON object for prompt inclusion.
+ * Recursively sanitizes all string values.
+ *
+ * @param obj - The object to sanitize
+ * @returns Sanitized object with all strings processed
+ */
+export declare function sanitizeObjectForPrompt(obj: unknown): unknown;
+/**
+ * Create a safely delimited data section for prompts.
+ * Uses instruction/data separation pattern to prevent injection.
+ *
+ * @param label - Label for the data section
+ * @param content - Content to include
+ * @returns Formatted data section
+ */
+export declare function createDataSection(label: string, content: string): string;
+/**
+ * Sanitize a tool for safe inclusion in prompts.
+ * Returns a structured representation with sanitized fields.
+ *
+ * @param tool - Tool object with name, description, and schema
+ * @returns Sanitized prompt-safe representation
+ */
+export declare function sanitizeToolForPrompt(tool: {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}): {
+    name: string;
+    description: string;
+    schema: string;
+    warnings: string[];
+};
+/**
+ * Check if text contains potential injection patterns without modifying it.
+ *
+ * @param text - Text to check
+ * @returns True if potential injection detected
+ */
+export declare function hasInjectionPatterns(text: string): boolean;
+/**
+ * Truncate text to a maximum length with indicator.
+ * Useful for limiting context size in prompts.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length
+ * @returns Truncated text
+ */
+export declare function truncateForPrompt(text: string, maxLength: number): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/utils/sanitize.js

@@ -0,0 +1,191 @@
+/**
+ * Input sanitization utilities for prompt injection protection.
+ *
+ * These utilities help prevent malicious content in MCP server responses
+ * from manipulating LLM behavior through prompt injection attacks.
+ */
+/**
+ * Patterns that may indicate prompt injection attempts.
+ * These patterns look for instruction-like content in user data.
+ */
+const INJECTION_PATTERNS = [
+    // Direct instruction patterns
+    /ignore\s+(all\s+)?(previous|above|prior)\s+(instructions?|prompts?|rules?)/i,
+    /disregard\s+(all\s+)?(previous|above|prior)/i,
+    /forget\s+(everything|all|what)\s+(you|i)/i,
+    // New instruction patterns
+    /new\s+instructions?:/i,
+    /system\s*:\s*you\s+(are|should|must|will)/i,
+    /\bact\s+as\s+(if|though)\b/i,
+    /\byou\s+are\s+now\b/i,
+    /\bpretend\s+(to\s+be|you\s+are)\b/i,
+    // Output manipulation
+    /\breturn\s+(only|just)\s+["']?success/i,
+    /\balways\s+(return|respond|output|say)\b/i,
+    /\bnever\s+(return|respond|output|mention|reveal)\b/i,
+    // Role/persona manipulation
+    /\byour\s+(new\s+)?role\s+is\b/i,
+    /\bswitch\s+(to\s+)?(role|persona|mode)\b/i,
+    // Jailbreak attempts
+    /\bdo\s+anything\s+now\b/i,
+    /\bdan\s+mode\b/i,
+    /\bdeveloper\s+mode\b/i,
+    // Markdown/formatting exploits
+    /```\s*(system|instruction|prompt)/i,
+];
+/**
+ * Characters that could be used for prompt structure manipulation.
+ */
+const STRUCTURAL_CHARS = {
+    '`': '\\`',
+    '$': '\\$',
+    '{': '\\{',
+    '}': '\\}',
+};
+/**
+ * Sanitize user-provided text for safe inclusion in LLM prompts.
+ *
+ * This function:
+ * 1. Detects potential prompt injection patterns
+ * 2. Escapes structural characters that could manipulate prompt format
+ * 3. Wraps content in clear data delimiters
+ *
+ * @param text - The text to sanitize (e.g., tool description, schema)
+ * @param options - Sanitization options
+ * @returns Sanitized text safe for prompt inclusion
+ */
+export function sanitizeForPrompt(text, options = {}) {
+    const { escapeStructural = true, wrapInDelimiters = false, delimiterName = 'DATA', stripInjections = false, } = options;
+    let sanitized = text;
+    const detectedPatterns = [];
+    let hadStructuralChars = false;
+    // Detect injection patterns
+    for (const pattern of INJECTION_PATTERNS) {
+        if (pattern.test(sanitized)) {
+            detectedPatterns.push(pattern.source);
+            if (stripInjections) {
+                // Replace detected patterns with a placeholder
+                sanitized = sanitized.replace(pattern, '[FILTERED]');
+            }
+        }
+    }
+    // Escape structural characters
+    if (escapeStructural) {
+        for (const [char, escaped] of Object.entries(STRUCTURAL_CHARS)) {
+            if (sanitized.includes(char)) {
+                hadStructuralChars = true;
+                sanitized = sanitized.split(char).join(escaped);
+            }
+        }
+    }
+    // Wrap in delimiters if requested
+    if (wrapInDelimiters) {
+        sanitized = `<${delimiterName}>\n${sanitized}\n</${delimiterName}>`;
+    }
+    return {
+        sanitized,
+        hadInjectionPatterns: detectedPatterns.length > 0,
+        detectedPatterns,
+        hadStructuralChars,
+    };
+}
+/**
+ * Sanitize a JSON object for prompt inclusion.
+ * Recursively sanitizes all string values.
+ *
+ * @param obj - The object to sanitize
+ * @returns Sanitized object with all strings processed
+ */
+export function sanitizeObjectForPrompt(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (typeof obj === 'string') {
+        return sanitizeForPrompt(obj, { escapeStructural: true }).sanitized;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => sanitizeObjectForPrompt(item));
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            // Also sanitize keys (though less critical)
+            const sanitizedKey = sanitizeForPrompt(key, { escapeStructural: true }).sanitized;
+            result[sanitizedKey] = sanitizeObjectForPrompt(value);
+        }
+        return result;
+    }
+    // Numbers, booleans, etc. pass through
+    return obj;
+}
+/**
+ * Create a safely delimited data section for prompts.
+ * Uses instruction/data separation pattern to prevent injection.
+ *
+ * @param label - Label for the data section
+ * @param content - Content to include
+ * @returns Formatted data section
+ */
+export function createDataSection(label, content) {
+    const sanitized = sanitizeForPrompt(content, { escapeStructural: true });
+    // Use XML-like delimiters that are less likely to be in user data
+    return `<${label.toUpperCase()}_DATA>
+${sanitized.sanitized}
+</${label.toUpperCase()}_DATA>`;
+}
+/**
+ * Sanitize a tool for safe inclusion in prompts.
+ * Returns a structured representation with sanitized fields.
+ *
+ * @param tool - Tool object with name, description, and schema
+ * @returns Sanitized prompt-safe representation
+ */
+export function sanitizeToolForPrompt(tool) {
+    const warnings = [];
+    // Sanitize name (should be safe, but check anyway)
+    const nameResult = sanitizeForPrompt(tool.name, { escapeStructural: true });
+    if (nameResult.hadInjectionPatterns) {
+        warnings.push(`Tool name contains suspicious patterns: ${tool.name}`);
+    }
+    // Sanitize description
+    const descResult = sanitizeForPrompt(tool.description ?? 'No description provided', { escapeStructural: true });
+    if (descResult.hadInjectionPatterns) {
+        warnings.push(`Tool description contains potential injection patterns`);
+    }
+    // Sanitize schema
+    let schemaStr = 'No schema provided';
+    if (tool.inputSchema) {
+        const sanitizedSchema = sanitizeObjectForPrompt(tool.inputSchema);
+        schemaStr = JSON.stringify(sanitizedSchema, null, 2);
+    }
+    return {
+        name: nameResult.sanitized,
+        description: descResult.sanitized,
+        schema: schemaStr,
+        warnings,
+    };
+}
+/**
+ * Check if text contains potential injection patterns without modifying it.
+ *
+ * @param text - Text to check
+ * @returns True if potential injection detected
+ */
+export function hasInjectionPatterns(text) {
+    return INJECTION_PATTERNS.some(pattern => pattern.test(text));
+}
+/**
+ * Truncate text to a maximum length with indicator.
+ * Useful for limiting context size in prompts.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length
+ * @returns Truncated text
+ */
+export function truncateForPrompt(text, maxLength) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return text.substring(0, maxLength - 3) + '...';
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/utils/semantic.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Semantic text analysis utilities.
+ *
+ * Provides stemming, negation handling, constraint normalization,
+ * and enhanced keyword extraction for semantic matching.
+ */
+/**
+ * Stem a single word using simplified Porter-like rules.
+ *
+ * @param word - Word to stem (should be lowercase)
+ * @returns Stemmed word
+ */
+export declare function stem(word: string): string;
+/**
+ * Stem all words in a text.
+ *
+ * @param text - Text to stem
+ * @returns Text with all words stemmed
+ */
+export declare function stemText(text: string): string;
+/**
+ * Extract keywords with stemming applied.
+ *
+ * @param text - Text to extract keywords from
+ * @returns Set of stemmed keywords
+ */
+export declare function extractStemmedKeywords(text: string): Set<string>;
+/**
+ * Calculate keyword overlap with stemming.
+ *
+ * @param text1 - First text
+ * @param text2 - Second text
+ * @returns Overlap percentage (0-100)
+ */
+export declare function calculateStemmedKeywordOverlap(text1: string, text2: string): number;
+/**
+ * Result of negation analysis.
+ */
+export interface NegationResult {
+    /** Negated words found in text */
+    negatedWords: string[];
+    /** Whether the overall sentiment is negated */
+    isNegated: boolean;
+    /** Original text with negations marked */
+    markedText: string;
+}
+/**
+ * Analyze text for negation patterns.
+ *
+ * @param text - Text to analyze
+ * @returns Negation analysis result
+ */
+export declare function analyzeNegation(text: string): NegationResult;
+/**
+ * Check if a severity keyword is negated in the text.
+ *
+ * @param text - Text to check
+ * @param keyword - Severity keyword to look for
+ * @returns True if keyword is negated
+ */
+export declare function isSeverityNegated(text: string, keyword: string): boolean;
+/**
+ * Extract severity from text with negation handling.
+ *
+ * @param text - Text to extract severity from
+ * @returns Extracted severity level
+ */
+export declare function extractSeverityWithNegation(text: string): 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Normalized constraint value.
+ */
+export interface NormalizedConstraint {
+    /** Original constraint string */
+    original: string;
+    /** Type of constraint */
+    type: 'size' | 'time' | 'rate' | 'count' | 'unknown';
+    /** Numeric value */
+    value: number;
+    /** Normalized unit */
+    unit: string;
+    /** Value in base units (bytes for size, ms for time, per-second for rate) */
+    baseValue: number;
+}
+/**
+ * Parse and normalize a constraint value.
+ *
+ * @param constraint - Constraint string (e.g., "10MB", "30 seconds", "100 requests/min")
+ * @returns Normalized constraint or undefined if not parseable
+ */
+export declare function normalizeConstraint(constraint: string): NormalizedConstraint | undefined;
+/**
+ * Compare two constraint values with unit normalization.
+ *
+ * @param a - First constraint
+ * @param b - Second constraint
+ * @returns Similarity score (0-100)
+ */
+export declare function compareConstraints(a: string | undefined, b: string | undefined): number;
+/**
+ * Extended security category keywords including new categories.
+ */
+export declare const EXTENDED_SECURITY_KEYWORDS: Record<string, string[]>;
+/**
+ * Extract security category from text using extended keywords.
+ *
+ * @param text - Text to analyze
+ * @returns Detected security category
+ */
+export declare function extractSecurityCategoryExtended(text: string): string;
+/**
+ * Check if two texts are semantically similar considering stemming.
+ *
+ * @param text1 - First text
+ * @param text2 - Second text
+ * @param threshold - Minimum similarity threshold (0-100, default 60)
+ * @returns True if texts are similar
+ */
+export declare function areSemanticallySimular(text1: string, text2: string, threshold?: number): boolean;
+/**
+ * Database type qualifiers that distinguish different injection types.
+ */
+export type DatabaseQualifier = 'sql' | 'nosql' | 'mongodb' | 'redis' | 'generic';
+/**
+ * Direction qualifiers for file/data operations.
+ */
+export type DirectionQualifier = 'upload' | 'download' | 'read' | 'write' | 'generic';
+/**
+ * Timeout type qualifiers.
+ */
+export type TimeoutQualifier = 'connection' | 'read' | 'write' | 'request' | 'response' | 'idle' | 'generic';
+/**
+ * Polarity indicator for assertions (positive vs negative statements).
+ */
+export type Polarity = 'positive' | 'negative' | 'neutral';
+/**
+ * Full qualifier extraction result.
+ */
+export interface QualifierResult {
+    database: DatabaseQualifier;
+    direction: DirectionQualifier;
+    timeout: TimeoutQualifier;
+    polarity: Polarity;
+    isNegated: boolean;
+    rateTimeUnit: 'second' | 'minute' | 'hour' | 'day' | 'unknown';
+}
+/**
+ * Extract database type qualifier from text.
+ * Distinguishes SQL from NoSQL/MongoDB/Redis etc.
+ */
+export declare function extractDatabaseQualifier(text: string): DatabaseQualifier;
+/**
+ * Extract direction qualifier from text.
+ * Distinguishes upload from download, read from write.
+ */
+export declare function extractDirectionQualifier(text: string): DirectionQualifier;
+/**
+ * Extract timeout type qualifier from text.
+ * Distinguishes connection timeout from read/write/request timeouts.
+ */
+export declare function extractTimeoutQualifier(text: string): TimeoutQualifier;
+/**
+ * Extract rate limit time unit from text.
+ * Distinguishes per-second from per-minute from per-hour limits.
+ */
+export declare function extractRateTimeUnit(text: string): 'second' | 'minute' | 'hour' | 'day' | 'unknown';
+/**
+ * Detect overall polarity of an assertion.
+ * Returns 'negative' if the statement is negated/denied.
+ */
+export declare function detectPolarity(text: string): Polarity;
+/**
+ * Check if a security finding or assertion is negated.
+ * Returns true if the text explicitly denies the assertion/vulnerability.
+ */
+export declare function isSecurityFindingNegated(text: string): boolean;
+/**
+ * Extract all qualifiers from text.
+ * Provides comprehensive context for semantic comparison.
+ */
+export declare function extractQualifiers(text: string): QualifierResult;
+/**
+ * Compare qualifiers between two texts.
+ * Returns a compatibility score (0-100).
+ */
+export declare function compareQualifiers(text1: string, text2: string): {
+    score: number;
+    incompatibilities: string[];
+};
+/**
+ * Check if two texts have compatible qualifiers for matching.
+ * Returns false if there are critical incompatibilities.
+ */
+export declare function qualifiersCompatible(text1: string, text2: string): boolean;
+//# sourceMappingURL=semantic.d.ts.map