sovr-mcp-proxy 7.0.0 → 7.2.0

package/dist/semanticAnalyzer.d.mts

@@ -0,0 +1,247 @@
+/**
+ * SOVR Semantic Analyzer v2 — Deterministic Intent Detection Engine
+ *
+ * Architecture principle: "AI hallucinations cannot check AI hallucinations."
+ * All analysis layers are deterministic — zero LLM dependency.
+ *
+ * Three analysis layers (all evidence-based, all deterministic):
+ *   Layer 1: Rule-based pattern matching (fast, regex + keyword)
+ *   Layer 2: Structural analysis (AST-like decomposition of commands)
+ *   Layer 3: Formal verification (path constraints, state machine, type checking)
+ *
+ * Design principle per ADR-135+:
+ *   - "Evidence-based over LLM semantic"
+ *   - "Use math and deterministic rules to constrain AI, not AI to constrain AI"
+ *   - LLM is ONLY used for post-hoc audit report generation, NEVER for real-time decisions
+ */
+interface SemanticAnalysisConfig {
+    /** Custom intent rules */
+    customRules: IntentRule[];
+    /** Enable structural analysis (Layer 2) */
+    enableStructural: boolean;
+    /** Enable formal verification (Layer 3) */
+    enableFormalVerification: boolean;
+    /** Sensitivity level */
+    sensitivity: 'low' | 'medium' | 'high' | 'paranoid';
+    /** Allowed base directories for file operations */
+    allowedPaths: string[];
+    /** Known safe SQL tables (for type checking) */
+    safeTables: string[];
+    /** Maximum command complexity score before auto-block */
+    maxComplexity: number;
+}
+interface IntentRule {
+    /** Rule ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Category of intent */
+    category: IntentCategory;
+    /** Patterns to match (any match triggers) */
+    patterns: IntentPattern[];
+    /** Risk level when matched */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Priority (higher = evaluated first) */
+    priority: number;
+    /** Whether this rule is a positive (allow) or negative (block) indicator */
+    polarity: 'positive' | 'negative';
+}
+interface IntentPattern {
+    /** Pattern type */
+    type: 'regex' | 'keyword' | 'structural' | 'sequence';
+    /** The pattern value */
+    value: string;
+    /** Where to look */
+    target: 'command' | 'arguments' | 'tool_name' | 'full_context';
+    /** Case sensitive */
+    caseSensitive?: boolean;
+}
+type IntentCategory = 'data_destruction' | 'data_exfiltration' | 'privilege_escalation' | 'code_execution' | 'network_access' | 'file_modification' | 'credential_access' | 'system_modification' | 'financial_operation' | 'communication' | 'read_only' | 'benign';
+interface AnalysisResult {
+    /** Overall risk level */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Overall risk score (0-100) */
+    riskScore: number;
+    /** Confidence in the analysis (0-1) */
+    confidence: number;
+    /** Detected intents */
+    intents: DetectedIntent[];
+    /** Layer results */
+    layers: {
+        rules: LayerResult;
+        structural: LayerResult;
+        formal?: LayerResult;
+    };
+    /** Recommended action */
+    recommendation: 'allow' | 'warn' | 'block' | 'require-approval';
+    /** Human-readable explanation */
+    explanation: string;
+    /** Analysis duration (ms) */
+    durationMs: number;
+}
+interface DetectedIntent {
+    category: IntentCategory;
+    description: string;
+    confidence: number;
+    source: 'rule' | 'structural' | 'formal';
+    evidence: string[];
+}
+interface LayerResult {
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    riskScore: number;
+    confidence: number;
+    findings: string[];
+}
+/** State machine states for command safety */
+type SafetyState = 'safe' | 'elevated' | 'destructive' | 'irreversible';
+interface StateTransition {
+    from: SafetyState;
+    trigger: string;
+    to: SafetyState;
+    pattern: RegExp;
+}
+interface PathConstraint {
+    /** Path being accessed */
+    path: string;
+    /** Operation type */
+    operation: 'read' | 'write' | 'delete' | 'execute';
+    /** Whether the path is within allowed boundaries */
+    withinBounds: boolean;
+    /** Violation reason if out of bounds */
+    violation?: string;
+}
+interface SQLTypeCheck {
+    /** SQL statement type */
+    statementType: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'DROP' | 'CREATE' | 'ALTER' | 'TRUNCATE' | 'UNKNOWN';
+    /** Whether WHERE clause exists (for UPDATE/DELETE) */
+    hasWhereClause: boolean;
+    /** Tables referenced */
+    tables: string[];
+    /** Whether tables are in safe list */
+    tablesAreSafe: boolean;
+    /** Violations found */
+    violations: string[];
+}
+interface FormalVerificationResult {
+    /** Path constraint violations */
+    pathViolations: PathConstraint[];
+    /** Safety state machine final state */
+    finalState: SafetyState;
+    /** State transitions taken */
+    transitions: {
+        trigger: string;
+        from: SafetyState;
+        to: SafetyState;
+    }[];
+    /** SQL type check results */
+    sqlCheck?: SQLTypeCheck;
+    /** Command complexity score */
+    complexityScore: number;
+    /** Whether complexity exceeds threshold */
+    complexityExceeded: boolean;
+    /** Overall formal risk score */
+    riskScore: number;
+    /** Formal verification findings */
+    findings: string[];
+}
+declare const BUILTIN_RULES: IntentRule[];
+interface CommandStructure {
+    /** Pipe segments */
+    pipes: string[];
+    /** Redirect targets */
+    redirections: string[];
+    /** Subshell/command substitution instances */
+    subshells: string[];
+    /** File paths referenced */
+    filePaths: string[];
+    /** Network targets (URLs, IPs) */
+    networkTargets: string[];
+    /** Environment variables referenced */
+    envVars: string[];
+    /** Complexity score */
+    complexity: number;
+}
+declare function analyzeStructure(command: string): CommandStructure;
+declare function structuralRiskAssessment(structure: CommandStructure): LayerResult;
+/**
+ * Path Constraint Solver — proves whether file operations stay within allowed boundaries.
+ * Pure string analysis, no filesystem access needed.
+ */
+declare function verifyPathConstraints(command: string, filePaths: string[], allowedPaths: string[]): PathConstraint[];
+/**
+ * SQL Type Checker — verifies SQL statement safety through structural analysis.
+ * No database connection needed — pure syntax analysis.
+ */
+declare function checkSQLType(sql: string, safeTables: string[]): SQLTypeCheck;
+/**
+ * Run the safety state machine on a command.
+ * Returns the final state and all transitions taken.
+ */
+declare function runStateMachine(command: string): {
+    finalState: SafetyState;
+    transitions: {
+        trigger: string;
+        from: SafetyState;
+        to: SafetyState;
+    }[];
+};
+/**
+ * Full formal verification — combines path constraints, state machine, and SQL type checking.
+ */
+declare function formalVerify(command: string, args: Record<string, unknown>, structure: CommandStructure, config: SemanticAnalysisConfig): FormalVerificationResult;
+/**
+ * Maps rule findings and structural findings to correct IntentCategory.
+ * This was the bug: previously everything was mapped to 'code_execution'.
+ * Now we properly extract the category from the matched rule.
+ */
+/** Map a rule finding back to its IntentCategory */
+declare function findRuleCategoryByName(ruleName: string, rules: IntentRule[]): IntentCategory;
+/** Map structural findings to IntentCategory based on content analysis */
+declare function classifyStructuralFinding(finding: string): IntentCategory;
+/** Map formal verification findings to IntentCategory */
+declare function classifyFormalFinding(finding: string): IntentCategory;
+declare class SemanticAnalyzer {
+    private config;
+    private rules;
+    constructor(config?: Partial<SemanticAnalysisConfig>);
+    /**
+     * Analyze a tool call for security risks.
+     * All three layers are deterministic — zero LLM dependency.
+     */
+    analyze(toolName: string, args: Record<string, unknown>): Promise<AnalysisResult>;
+    /** Quick synchronous check (Layer 1 only, for hot path) */
+    quickCheck(toolName: string, args: Record<string, unknown>): {
+        riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+        riskScore: number;
+        topFinding: string;
+    };
+    /** Add custom rules at runtime */
+    addRule(rule: IntentRule): void;
+    /** Get all active rules */
+    getRules(): IntentRule[];
+    private analyzeWithRules;
+    private extractCommand;
+    private getPatternTarget;
+    private riskLevelToScore;
+    private applySensitivity;
+    /**
+     * Collect intents with CORRECT IntentCategory mapping.
+     *
+     * BUG FIX: Previously all intents were mapped to 'code_execution'.
+     * Now we properly extract the category from:
+     *   - Rule findings → look up the matched rule's category
+     *   - Structural findings → classify based on finding content
+     *   - Formal findings → classify based on violation type
+     */
+    private collectIntents;
+    private combineResults;
+}
+/** Create a semantic analyzer with default settings */
+declare function createSemanticAnalyzer(overrides?: Partial<SemanticAnalysisConfig>): SemanticAnalyzer;
+/** Create a paranoid analyzer (highest sensitivity, all layers, strictest constraints) */
+declare function createParanoidAnalyzer(config?: {
+    allowedPaths?: string[];
+    safeTables?: string[];
+}): SemanticAnalyzer;
+
+export { type AnalysisResult, BUILTIN_RULES, type CommandStructure, type DetectedIntent, type FormalVerificationResult, type IntentCategory, type IntentPattern, type IntentRule, type LayerResult, type PathConstraint, type SQLTypeCheck, type SafetyState, type SemanticAnalysisConfig, SemanticAnalyzer, type StateTransition, analyzeStructure, checkSQLType, classifyFormalFinding, classifyStructuralFinding, createParanoidAnalyzer, createSemanticAnalyzer, findRuleCategoryByName, formalVerify, runStateMachine, structuralRiskAssessment, verifyPathConstraints };

package/dist/semanticAnalyzer.d.ts

@@ -0,0 +1,247 @@
+/**
+ * SOVR Semantic Analyzer v2 — Deterministic Intent Detection Engine
+ *
+ * Architecture principle: "AI hallucinations cannot check AI hallucinations."
+ * All analysis layers are deterministic — zero LLM dependency.
+ *
+ * Three analysis layers (all evidence-based, all deterministic):
+ *   Layer 1: Rule-based pattern matching (fast, regex + keyword)
+ *   Layer 2: Structural analysis (AST-like decomposition of commands)
+ *   Layer 3: Formal verification (path constraints, state machine, type checking)
+ *
+ * Design principle per ADR-135+:
+ *   - "Evidence-based over LLM semantic"
+ *   - "Use math and deterministic rules to constrain AI, not AI to constrain AI"
+ *   - LLM is ONLY used for post-hoc audit report generation, NEVER for real-time decisions
+ */
+interface SemanticAnalysisConfig {
+    /** Custom intent rules */
+    customRules: IntentRule[];
+    /** Enable structural analysis (Layer 2) */
+    enableStructural: boolean;
+    /** Enable formal verification (Layer 3) */
+    enableFormalVerification: boolean;
+    /** Sensitivity level */
+    sensitivity: 'low' | 'medium' | 'high' | 'paranoid';
+    /** Allowed base directories for file operations */
+    allowedPaths: string[];
+    /** Known safe SQL tables (for type checking) */
+    safeTables: string[];
+    /** Maximum command complexity score before auto-block */
+    maxComplexity: number;
+}
+interface IntentRule {
+    /** Rule ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Category of intent */
+    category: IntentCategory;
+    /** Patterns to match (any match triggers) */
+    patterns: IntentPattern[];
+    /** Risk level when matched */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Priority (higher = evaluated first) */
+    priority: number;
+    /** Whether this rule is a positive (allow) or negative (block) indicator */
+    polarity: 'positive' | 'negative';
+}
+interface IntentPattern {
+    /** Pattern type */
+    type: 'regex' | 'keyword' | 'structural' | 'sequence';
+    /** The pattern value */
+    value: string;
+    /** Where to look */
+    target: 'command' | 'arguments' | 'tool_name' | 'full_context';
+    /** Case sensitive */
+    caseSensitive?: boolean;
+}
+type IntentCategory = 'data_destruction' | 'data_exfiltration' | 'privilege_escalation' | 'code_execution' | 'network_access' | 'file_modification' | 'credential_access' | 'system_modification' | 'financial_operation' | 'communication' | 'read_only' | 'benign';
+interface AnalysisResult {
+    /** Overall risk level */
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    /** Overall risk score (0-100) */
+    riskScore: number;
+    /** Confidence in the analysis (0-1) */
+    confidence: number;
+    /** Detected intents */
+    intents: DetectedIntent[];
+    /** Layer results */
+    layers: {
+        rules: LayerResult;
+        structural: LayerResult;
+        formal?: LayerResult;
+    };
+    /** Recommended action */
+    recommendation: 'allow' | 'warn' | 'block' | 'require-approval';
+    /** Human-readable explanation */
+    explanation: string;
+    /** Analysis duration (ms) */
+    durationMs: number;
+}
+interface DetectedIntent {
+    category: IntentCategory;
+    description: string;
+    confidence: number;
+    source: 'rule' | 'structural' | 'formal';
+    evidence: string[];
+}
+interface LayerResult {
+    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+    riskScore: number;
+    confidence: number;
+    findings: string[];
+}
+/** State machine states for command safety */
+type SafetyState = 'safe' | 'elevated' | 'destructive' | 'irreversible';
+interface StateTransition {
+    from: SafetyState;
+    trigger: string;
+    to: SafetyState;
+    pattern: RegExp;
+}
+interface PathConstraint {
+    /** Path being accessed */
+    path: string;
+    /** Operation type */
+    operation: 'read' | 'write' | 'delete' | 'execute';
+    /** Whether the path is within allowed boundaries */
+    withinBounds: boolean;
+    /** Violation reason if out of bounds */
+    violation?: string;
+}
+interface SQLTypeCheck {
+    /** SQL statement type */
+    statementType: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'DROP' | 'CREATE' | 'ALTER' | 'TRUNCATE' | 'UNKNOWN';
+    /** Whether WHERE clause exists (for UPDATE/DELETE) */
+    hasWhereClause: boolean;
+    /** Tables referenced */
+    tables: string[];
+    /** Whether tables are in safe list */
+    tablesAreSafe: boolean;
+    /** Violations found */
+    violations: string[];
+}
+interface FormalVerificationResult {
+    /** Path constraint violations */
+    pathViolations: PathConstraint[];
+    /** Safety state machine final state */
+    finalState: SafetyState;
+    /** State transitions taken */
+    transitions: {
+        trigger: string;
+        from: SafetyState;
+        to: SafetyState;
+    }[];
+    /** SQL type check results */
+    sqlCheck?: SQLTypeCheck;
+    /** Command complexity score */
+    complexityScore: number;
+    /** Whether complexity exceeds threshold */
+    complexityExceeded: boolean;
+    /** Overall formal risk score */
+    riskScore: number;
+    /** Formal verification findings */
+    findings: string[];
+}
+declare const BUILTIN_RULES: IntentRule[];
+interface CommandStructure {
+    /** Pipe segments */
+    pipes: string[];
+    /** Redirect targets */
+    redirections: string[];
+    /** Subshell/command substitution instances */
+    subshells: string[];
+    /** File paths referenced */
+    filePaths: string[];
+    /** Network targets (URLs, IPs) */
+    networkTargets: string[];
+    /** Environment variables referenced */
+    envVars: string[];
+    /** Complexity score */
+    complexity: number;
+}
+declare function analyzeStructure(command: string): CommandStructure;
+declare function structuralRiskAssessment(structure: CommandStructure): LayerResult;
+/**
+ * Path Constraint Solver — proves whether file operations stay within allowed boundaries.
+ * Pure string analysis, no filesystem access needed.
+ */
+declare function verifyPathConstraints(command: string, filePaths: string[], allowedPaths: string[]): PathConstraint[];
+/**
+ * SQL Type Checker — verifies SQL statement safety through structural analysis.
+ * No database connection needed — pure syntax analysis.
+ */
+declare function checkSQLType(sql: string, safeTables: string[]): SQLTypeCheck;
+/**
+ * Run the safety state machine on a command.
+ * Returns the final state and all transitions taken.
+ */
+declare function runStateMachine(command: string): {
+    finalState: SafetyState;
+    transitions: {
+        trigger: string;
+        from: SafetyState;
+        to: SafetyState;
+    }[];
+};
+/**
+ * Full formal verification — combines path constraints, state machine, and SQL type checking.
+ */
+declare function formalVerify(command: string, args: Record<string, unknown>, structure: CommandStructure, config: SemanticAnalysisConfig): FormalVerificationResult;
+/**
+ * Maps rule findings and structural findings to correct IntentCategory.
+ * This was the bug: previously everything was mapped to 'code_execution'.
+ * Now we properly extract the category from the matched rule.
+ */
+/** Map a rule finding back to its IntentCategory */
+declare function findRuleCategoryByName(ruleName: string, rules: IntentRule[]): IntentCategory;
+/** Map structural findings to IntentCategory based on content analysis */
+declare function classifyStructuralFinding(finding: string): IntentCategory;
+/** Map formal verification findings to IntentCategory */
+declare function classifyFormalFinding(finding: string): IntentCategory;
+declare class SemanticAnalyzer {
+    private config;
+    private rules;
+    constructor(config?: Partial<SemanticAnalysisConfig>);
+    /**
+     * Analyze a tool call for security risks.
+     * All three layers are deterministic — zero LLM dependency.
+     */
+    analyze(toolName: string, args: Record<string, unknown>): Promise<AnalysisResult>;
+    /** Quick synchronous check (Layer 1 only, for hot path) */
+    quickCheck(toolName: string, args: Record<string, unknown>): {
+        riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
+        riskScore: number;
+        topFinding: string;
+    };
+    /** Add custom rules at runtime */
+    addRule(rule: IntentRule): void;
+    /** Get all active rules */
+    getRules(): IntentRule[];
+    private analyzeWithRules;
+    private extractCommand;
+    private getPatternTarget;
+    private riskLevelToScore;
+    private applySensitivity;
+    /**
+     * Collect intents with CORRECT IntentCategory mapping.
+     *
+     * BUG FIX: Previously all intents were mapped to 'code_execution'.
+     * Now we properly extract the category from:
+     *   - Rule findings → look up the matched rule's category
+     *   - Structural findings → classify based on finding content
+     *   - Formal findings → classify based on violation type
+     */
+    private collectIntents;
+    private combineResults;
+}
+/** Create a semantic analyzer with default settings */
+declare function createSemanticAnalyzer(overrides?: Partial<SemanticAnalysisConfig>): SemanticAnalyzer;
+/** Create a paranoid analyzer (highest sensitivity, all layers, strictest constraints) */
+declare function createParanoidAnalyzer(config?: {
+    allowedPaths?: string[];
+    safeTables?: string[];
+}): SemanticAnalyzer;
+
+export { type AnalysisResult, BUILTIN_RULES, type CommandStructure, type DetectedIntent, type FormalVerificationResult, type IntentCategory, type IntentPattern, type IntentRule, type LayerResult, type PathConstraint, type SQLTypeCheck, type SafetyState, type SemanticAnalysisConfig, SemanticAnalyzer, type StateTransition, analyzeStructure, checkSQLType, classifyFormalFinding, classifyStructuralFinding, createParanoidAnalyzer, createSemanticAnalyzer, findRuleCategoryByName, formalVerify, runStateMachine, structuralRiskAssessment, verifyPathConstraints };