@solongate/core 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -697,6 +697,57 @@ declare function validateToolInput(schema: ZodTypeAny, input: unknown, options?:
  */
 declare function createStrictSchema(shape: Record<string, ZodTypeAny>): z.ZodObject<Record<string, ZodTypeAny>, 'strict'>;
 
+/**
+ * Types for the 3-stage hybrid prompt injection detection system.
+ */
+/** Result from an individual detection stage. */
+interface StageResult {
+    /** Stage name identifier. */
+    readonly stage: 'rules' | 'embedding' | 'classifier';
+    /** Risk score from 0.0 (safe) to 1.0 (malicious). */
+    readonly score: number;
+    /** Whether this stage was actually executed. */
+    readonly enabled: boolean;
+    /** Matched patterns/details for debugging. */
+    readonly details: readonly string[];
+}
+/** Final trust score result combining all stages. */
+interface TrustScoreResult {
+    /** Trust score from 0.0 (malicious) to 1.0 (safe). */
+    readonly trustScore: number;
+    /** Whether the input should be blocked. */
+    readonly blocked: boolean;
+    /** Raw weighted score before inversion. */
+    readonly rawScore: number;
+    /** Individual stage results. */
+    readonly stages: readonly StageResult[];
+    /** Effective weights used (after redistribution). */
+    readonly weights: {
+        readonly rules: number;
+        readonly embedding: number;
+        readonly classifier: number;
+    };
+    /** Input text that was analyzed. */
+    readonly input: string;
+}
+/** Configuration for the advanced 3-stage detection system. */
+interface AdvancedDetectionConfig {
+    /** Enable the advanced detection system. Default: true */
+    readonly enabled?: boolean;
+    /** Trust score threshold below which input is blocked. Default: 0.5 */
+    readonly threshold?: number;
+    /** Stage weights (must sum to 1.0). */
+    readonly weights?: {
+        readonly rules?: number;
+        readonly embedding?: number;
+        readonly classifier?: number;
+    };
+    /** Callback when a model download starts. */
+    readonly onModelDownloadStart?: (modelName: string, sizeMB: number) => void;
+}
+/** Default configuration values. */
+declare const DEFAULT_ADVANCED_DETECTION_CONFIG: Required<Omit<AdvancedDetectionConfig, 'onModelDownloadStart'>> & Pick<AdvancedDetectionConfig, 'onModelDownloadStart'>;
+
 /**
  * Input Guard: detects and blocks dangerous patterns in tool arguments.
  *
@@ -733,6 +784,7 @@ interface InputGuardConfig {
     readonly promptInjection: boolean;
     readonly exfiltration: boolean;
     readonly boundaryEscape: boolean;
+    readonly advancedDetection?: AdvancedDetectionConfig;
 }
 declare const DEFAULT_INPUT_GUARD_CONFIG: Readonly<InputGuardConfig>;
 declare function detectPathTraversal(value: string): boolean;
@@ -753,6 +805,76 @@ declare function checkEntropyLimits(value: string): boolean;
  * Returns structured result with all detected threats.
  */
 declare function sanitizeInput(field: string, value: unknown, config?: InputGuardConfig): SanitizationResult;
+/** Extended result that includes trust score when advanced detection is used. */
+interface AsyncSanitizationResult extends SanitizationResult {
+    readonly trustScore?: TrustScoreResult;
+}
+/**
+ * Async version of sanitizeInput that supports the 3-stage hybrid prompt injection detection.
+ * The synchronous sanitizeInput() is unchanged for backward compatibility.
+ * If advancedDetection is not configured, behaves identically to sanitizeInput().
+ */
+declare function sanitizeInputAsync(field: string, value: unknown, config?: InputGuardConfig): Promise<AsyncSanitizationResult>;
+
+/**
+ * Orchestrator: runs all 3 stages and computes final Trust Score.
+ */
+
+/**
+ * Run the full 3-stage prompt injection detection pipeline.
+ *
+ * Stage 1 (rules) runs synchronously first.
+ * Stages 2 & 3 run in parallel if @huggingface/transformers is available.
+ *
+ * Returns a TrustScoreResult with the combined trust score.
+ */
+declare function detectPromptInjectionAdvanced(input: string, config?: AdvancedDetectionConfig): Promise<TrustScoreResult>;
+
+/**
+ * Stage 1: Rule-based weighted scoring for prompt injection detection.
+ * Synchronous, no ML dependencies required.
+ */
+
+/**
+ * Run rule-based weighted scoring on input text.
+ * Score = max(matched_weights) + 0.05 * (additional_category_count), capped at 1.0
+ */
+declare function runStage1Rules(input: string): StageResult;
+
+/**
+ * Stage 2: Embedding + Cosine Similarity detection.
+ * Uses Xenova/all-MiniLM-L6-v2 ONNX model via @huggingface/transformers.
+ * Compares input embedding against known attack vector embeddings.
+ */
+
+/**
+ * Run Stage 2: Embedding-based similarity detection.
+ * Returns max cosine similarity against known attack vectors.
+ */
+declare function runStage2Embedding(input: string, config?: AdvancedDetectionConfig): Promise<StageResult>;
+
+/**
+ * Stage 3: DeBERTa binary classification for prompt injection.
+ * Uses Xenova/deberta-v3-base-prompt-injection-v2 ONNX model.
+ */
+
+/**
+ * Run Stage 3: DeBERTa classification.
+ * Returns the injection probability (0-1).
+ */
+declare function runStage3Classifier(input: string, config?: AdvancedDetectionConfig): Promise<StageResult>;
+
+/**
+ * Known attack vector strings for embedding-based similarity detection.
+ * Used by Stage 2 to compute cosine similarity against incoming prompts.
+ */
+declare const ATTACK_VECTORS: readonly string[];
+
+/**
+ * Check if @huggingface/transformers is available without triggering import.
+ * Only valid after getTransformers() has been called at least once.
+ */
+declare function isTransformersAvailable(): boolean;
 
 /**
  * Response Scanner: detects indirect prompt injection in upstream tool responses.
@@ -848,4 +970,4 @@ interface TokenVerificationResult {
     readonly reason?: string;
 }
 
-export { BOUNDARY_PREFIX, BOUNDARY_SUFFIX, type CapabilityToken, DEFAULT_INPUT_GUARD_CONFIG, DEFAULT_POLICY_EFFECT, DEFAULT_RATE_LIMIT_PER_MINUTE, DEFAULT_RESPONSE_SCAN_CONFIG, DEFAULT_TOKEN_TTL_SECONDS, type DetectedThreat, type ExecutionContext, type ExecutionRequest, type ExecutionResult, type ExecutionResultAllowed, type ExecutionResultDenied, type ExecutionResultError, INPUT_GUARD_ENTROPY_THRESHOLD, INPUT_GUARD_MAX_LENGTH, INPUT_GUARD_MAX_WILDCARDS, INPUT_GUARD_MIN_ENTROPY_LENGTH, type InputGuardConfig, InputGuardError, MAX_ARGUMENTS_SIZE_BYTES, MAX_ARGUMENT_DEPTH, MAX_RATE_LIMIT_PER_MINUTE, MAX_RULES_PER_POLICY_SET, MAX_SERVER_NAME_LENGTH, MAX_TOOL_NAME_LENGTH, MIN_SECRET_LENGTH, type McpCallToolParams, type McpCallToolResult, type McpToolDefinition, type McpToolResultContent, NO_PERMISSIONS, NetworkError, POLICY_EVALUATION_TIMEOUT_MS, Permission, PermissionSchema, type PermissionSet, type PolicyDecision, PolicyDeniedError, PolicyEffect, type PolicyRule, PolicyRuleSchema, type PolicySet, PolicySetSchema, RATE_LIMIT_MAX_ENTRIES, RATE_LIMIT_WINDOW_MS, READ_ONLY, RESPONSE_WARNING_MARKER, RateLimitError, type ResponseScanConfig, type ResponseScanResult, type ResponseThreat, type ResponseThreatType, SECURITY_CONTEXT_TIMEOUT_MS, type SanitizationResult, SchemaValidationError, type SchemaValidationResult, type SchemaValidatorOptions, type SecurityContext, SolonGateError, TOKEN_ALGORITHM, TOKEN_DEFAULT_TTL_SECONDS, TOKEN_MAX_AGE_SECONDS, TOKEN_MIN_SECRET_LENGTH, type TaggedArguments, type ThreatType, type TokenConfig, type TokenVerificationResult, type ToolCapability, ToolNotFoundError, TrustEscalationError, TrustLevel, UNSAFE_CONFIGURATION_WARNINGS, UnsafeConfigurationError, assertValidTransition, checkEntropyLimits, checkLengthLimits, createDeniedToolResult, createPermissionSet, createSecurityContext, createStrictSchema, createToolCapability, detectBoundaryEscape, detectExfiltration, detectPathTraversal, detectPromptInjection, detectSQLInjection, detectSSRF, detectShellInjection, detectWildcardAbuse, hasAllPermissions, hasPermission, isValidTrustLevel, permissionForMethod, sanitizeInput, scanResponse, stripBoundaryTags, tagUserInput, validateToolInput };
+export { ATTACK_VECTORS, type AdvancedDetectionConfig, type AsyncSanitizationResult, BOUNDARY_PREFIX, BOUNDARY_SUFFIX, type CapabilityToken, DEFAULT_ADVANCED_DETECTION_CONFIG, DEFAULT_INPUT_GUARD_CONFIG, DEFAULT_POLICY_EFFECT, DEFAULT_RATE_LIMIT_PER_MINUTE, DEFAULT_RESPONSE_SCAN_CONFIG, DEFAULT_TOKEN_TTL_SECONDS, type DetectedThreat, type ExecutionContext, type ExecutionRequest, type ExecutionResult, type ExecutionResultAllowed, type ExecutionResultDenied, type ExecutionResultError, INPUT_GUARD_ENTROPY_THRESHOLD, INPUT_GUARD_MAX_LENGTH, INPUT_GUARD_MAX_WILDCARDS, INPUT_GUARD_MIN_ENTROPY_LENGTH, type InputGuardConfig, InputGuardError, MAX_ARGUMENTS_SIZE_BYTES, MAX_ARGUMENT_DEPTH, MAX_RATE_LIMIT_PER_MINUTE, MAX_RULES_PER_POLICY_SET, MAX_SERVER_NAME_LENGTH, MAX_TOOL_NAME_LENGTH, MIN_SECRET_LENGTH, type McpCallToolParams, type McpCallToolResult, type McpToolDefinition, type McpToolResultContent, NO_PERMISSIONS, NetworkError, POLICY_EVALUATION_TIMEOUT_MS, Permission, PermissionSchema, type PermissionSet, type PolicyDecision, PolicyDeniedError, PolicyEffect, type PolicyRule, PolicyRuleSchema, type PolicySet, PolicySetSchema, RATE_LIMIT_MAX_ENTRIES, RATE_LIMIT_WINDOW_MS, READ_ONLY, RESPONSE_WARNING_MARKER, RateLimitError, type ResponseScanConfig, type ResponseScanResult, type ResponseThreat, type ResponseThreatType, SECURITY_CONTEXT_TIMEOUT_MS, type SanitizationResult, SchemaValidationError, type SchemaValidationResult, type SchemaValidatorOptions, type SecurityContext, SolonGateError, type StageResult, TOKEN_ALGORITHM, TOKEN_DEFAULT_TTL_SECONDS, TOKEN_MAX_AGE_SECONDS, TOKEN_MIN_SECRET_LENGTH, type TaggedArguments, type ThreatType, type TokenConfig, type TokenVerificationResult, type ToolCapability, ToolNotFoundError, TrustEscalationError, TrustLevel, type TrustScoreResult, UNSAFE_CONFIGURATION_WARNINGS, UnsafeConfigurationError, assertValidTransition, checkEntropyLimits, checkLengthLimits, createDeniedToolResult, createPermissionSet, createSecurityContext, createStrictSchema, createToolCapability, detectBoundaryEscape, detectExfiltration, detectPathTraversal, detectPromptInjection, detectPromptInjectionAdvanced, detectSQLInjection, detectSSRF, detectShellInjection, detectWildcardAbuse, hasAllPermissions, hasPermission, isTransformersAvailable, isValidTrustLevel, permissionForMethod, runStage1Rules, runStage2Embedding, runStage3Classifier, sanitizeInput, sanitizeInputAsync, scanResponse, stripBoundaryTags, tagUserInput, validateToolInput };