sovr-mcp-proxy 7.1.0 → 7.2.0

package/dist/semanticAnalyzer.d.mts

@@ -1,40 +1,34 @@
 /**
- * SOVR Semantic Analyzer — Multi-Layer Intent Detection Engine
+ * SOVR Semantic Analyzer v2 — Deterministic Intent Detection Engine
  *
- * P1-2: Goes beyond regex pattern matching to understand command INTENT.
+ * Architecture principle: "AI hallucinations cannot check AI hallucinations."
+ * All analysis layers are deterministic — zero LLM dependency.
  *
- * Three analysis layers (evidence-based first, LLM last):
- *   Layer 1: Rule-based pattern matching (fast, deterministic)
+ * 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: LLM-as-Judge (optional, for ambiguous cases only)
+ *   Layer 3: Formal verification (path constraints, state machine, type checking)
  *
- * Design principle: "Evidence-based over LLM semantic" — per SOVR ADR.
- * LLM is only used as a tiebreaker, never as the sole decision maker.
+ * 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 {
-    /** Enable Layer 3 (LLM-as-Judge) */
-    enableLLM: boolean;
-    /** LLM provider function (optional) */
-    llmProvider?: LLMProvider;
-    /** Risk threshold to trigger LLM analysis (0-100) */
-    llmTriggerThreshold: number;
-    /** Maximum time for LLM analysis (ms) */
-    llmTimeout: number;
     /** Custom intent rules */
     customRules: IntentRule[];
-    /** Enable structural analysis */
+    /** Enable structural analysis (Layer 2) */
     enableStructural: boolean;
+    /** Enable formal verification (Layer 3) */
+    enableFormalVerification: boolean;
     /** Sensitivity level */
     sensitivity: 'low' | 'medium' | 'high' | 'paranoid';
-}
-interface LLMProvider {
-    analyze(prompt: string, timeout: number): Promise<LLMJudgment>;
-}
-interface LLMJudgment {
-    intent: string;
-    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
-    confidence: number;
-    reasoning: string;
+    /** 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 */
@@ -76,7 +70,7 @@ interface AnalysisResult {
     layers: {
         rules: LayerResult;
         structural: LayerResult;
-        llm?: LayerResult;
+        formal?: LayerResult;
     };
     /** Recommended action */
     recommendation: 'allow' | 'warn' | 'block' | 'require-approval';
@@ -89,7 +83,7 @@ interface DetectedIntent {
     category: IntentCategory;
     description: string;
     confidence: number;
-    source: 'rule' | 'structural' | 'llm';
+    source: 'rule' | 'structural' | 'formal';
     evidence: string[];
 }
 interface LayerResult {
@@ -98,13 +92,121 @@ interface LayerResult {
     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.
-     * Returns a comprehensive analysis result with multi-layer findings.
+     * 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) */
@@ -122,12 +224,24 @@ declare class SemanticAnalyzer {
     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) */
-declare function createParanoidAnalyzer(llmProvider?: LLMProvider): SemanticAnalyzer;
+/** Create a paranoid analyzer (highest sensitivity, all layers, strictest constraints) */
+declare function createParanoidAnalyzer(config?: {
+    allowedPaths?: string[];
+    safeTables?: string[];
+}): SemanticAnalyzer;
 
-export { type AnalysisResult, type DetectedIntent, type IntentCategory, type IntentPattern, type IntentRule, type LLMJudgment, type LLMProvider, type LayerResult, type SemanticAnalysisConfig, SemanticAnalyzer, createParanoidAnalyzer, createSemanticAnalyzer };
+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

@@ -1,40 +1,34 @@
 /**
- * SOVR Semantic Analyzer — Multi-Layer Intent Detection Engine
+ * SOVR Semantic Analyzer v2 — Deterministic Intent Detection Engine
  *
- * P1-2: Goes beyond regex pattern matching to understand command INTENT.
+ * Architecture principle: "AI hallucinations cannot check AI hallucinations."
+ * All analysis layers are deterministic — zero LLM dependency.
  *
- * Three analysis layers (evidence-based first, LLM last):
- *   Layer 1: Rule-based pattern matching (fast, deterministic)
+ * 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: LLM-as-Judge (optional, for ambiguous cases only)
+ *   Layer 3: Formal verification (path constraints, state machine, type checking)
  *
- * Design principle: "Evidence-based over LLM semantic" — per SOVR ADR.
- * LLM is only used as a tiebreaker, never as the sole decision maker.
+ * 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 {
-    /** Enable Layer 3 (LLM-as-Judge) */
-    enableLLM: boolean;
-    /** LLM provider function (optional) */
-    llmProvider?: LLMProvider;
-    /** Risk threshold to trigger LLM analysis (0-100) */
-    llmTriggerThreshold: number;
-    /** Maximum time for LLM analysis (ms) */
-    llmTimeout: number;
     /** Custom intent rules */
     customRules: IntentRule[];
-    /** Enable structural analysis */
+    /** Enable structural analysis (Layer 2) */
     enableStructural: boolean;
+    /** Enable formal verification (Layer 3) */
+    enableFormalVerification: boolean;
     /** Sensitivity level */
     sensitivity: 'low' | 'medium' | 'high' | 'paranoid';
-}
-interface LLMProvider {
-    analyze(prompt: string, timeout: number): Promise<LLMJudgment>;
-}
-interface LLMJudgment {
-    intent: string;
-    riskLevel: 'safe' | 'suspicious' | 'dangerous' | 'critical';
-    confidence: number;
-    reasoning: string;
+    /** 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 */
@@ -76,7 +70,7 @@ interface AnalysisResult {
     layers: {
         rules: LayerResult;
         structural: LayerResult;
-        llm?: LayerResult;
+        formal?: LayerResult;
     };
     /** Recommended action */
     recommendation: 'allow' | 'warn' | 'block' | 'require-approval';
@@ -89,7 +83,7 @@ interface DetectedIntent {
     category: IntentCategory;
     description: string;
     confidence: number;
-    source: 'rule' | 'structural' | 'llm';
+    source: 'rule' | 'structural' | 'formal';
     evidence: string[];
 }
 interface LayerResult {
@@ -98,13 +92,121 @@ interface LayerResult {
     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.
-     * Returns a comprehensive analysis result with multi-layer findings.
+     * 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) */
@@ -122,12 +224,24 @@ declare class SemanticAnalyzer {
     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) */
-declare function createParanoidAnalyzer(llmProvider?: LLMProvider): SemanticAnalyzer;
+/** Create a paranoid analyzer (highest sensitivity, all layers, strictest constraints) */
+declare function createParanoidAnalyzer(config?: {
+    allowedPaths?: string[];
+    safeTables?: string[];
+}): SemanticAnalyzer;
 
-export { type AnalysisResult, type DetectedIntent, type IntentCategory, type IntentPattern, type IntentRule, type LLMJudgment, type LLMProvider, type LayerResult, type SemanticAnalysisConfig, SemanticAnalyzer, createParanoidAnalyzer, createSemanticAnalyzer };
+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 };