mcp-rubber-duck 1.7.0 → 1.9.0

package/src/config/types.ts

@@ -43,6 +43,72 @@ export const PricingConfigSchema = z.record(
   z.record(z.string(), ModelPricingSchema) // model name -> pricing
 );
 
+// Guardrails Plugin Configs
+export const RateLimiterConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  priority: z.number().min(0).max(1000).default(10),
+  requests_per_minute: z.number().min(1).default(60),
+  requests_per_hour: z.number().min(1).default(1000),
+  per_provider: z.boolean().default(false),
+  burst_allowance: z.number().min(0).default(5),
+});
+
+export const TokenLimiterConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  priority: z.number().min(0).max(1000).default(20),
+  max_input_tokens: z.number().min(1).default(8192),
+  max_output_tokens: z.number().min(1).optional(),
+  warn_at_percentage: z.number().min(0).max(100).default(80),
+});
+
+export const PatternBlockerConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  priority: z.number().min(0).max(1000).default(30),
+  blocked_patterns: z.array(z.string()).default([]),
+  blocked_patterns_regex: z.array(z.string()).default([]),
+  case_sensitive: z.boolean().default(false),
+  action_on_match: z.enum(['block', 'warn', 'redact']).default('block'),
+});
+
+export const PIIRedactorConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  priority: z.number().min(0).max(1000).default(25),
+  detect_emails: z.boolean().default(true),
+  detect_phones: z.boolean().default(true),
+  detect_ssn: z.boolean().default(true),
+  detect_api_keys: z.boolean().default(true),
+  detect_credit_cards: z.boolean().default(true),
+  detect_ip_addresses: z.boolean().default(false),
+  custom_patterns: z
+    .array(
+      z.object({
+        name: z.string(),
+        pattern: z.string(),
+        placeholder: z.string(),
+      })
+    )
+    .default([]),
+  allowlist: z.array(z.string()).default([]),
+  allowlist_domains: z.array(z.string()).default([]),
+  restore_on_response: z.boolean().default(false),
+  log_detections: z.boolean().default(true),
+});
+
+export const GuardrailsPluginsConfigSchema = z.object({
+  rate_limiter: RateLimiterConfigSchema.optional(),
+  token_limiter: TokenLimiterConfigSchema.optional(),
+  pattern_blocker: PatternBlockerConfigSchema.optional(),
+  pii_redactor: PIIRedactorConfigSchema.optional(),
+});
+
+export const GuardrailsConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  log_violations: z.boolean().default(true),
+  log_modifications: z.boolean().default(false),
+  fail_open: z.boolean().default(false), // If true, allow on plugin errors
+  plugins: GuardrailsPluginsConfigSchema.optional(),
+});
+
 export const ConfigSchema = z.object({
   providers: z.record(z.string(), ProviderConfigSchema),
   default_provider: z.string().optional(),
@@ -52,6 +118,7 @@ export const ConfigSchema = z.object({
   log_level: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
   mcp_bridge: MCPBridgeConfigSchema.optional(),
   pricing: PricingConfigSchema.optional(),
+  guardrails: GuardrailsConfigSchema.optional(),
 });
 
 export type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
@@ -59,6 +126,12 @@ export type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
 export type MCPBridgeConfig = z.infer<typeof MCPBridgeConfigSchema>;
 export type ModelPricing = z.infer<typeof ModelPricingSchema>;
 export type PricingConfig = z.infer<typeof PricingConfigSchema>;
+export type RateLimiterConfig = z.infer<typeof RateLimiterConfigSchema>;
+export type TokenLimiterConfig = z.infer<typeof TokenLimiterConfigSchema>;
+export type PatternBlockerConfig = z.infer<typeof PatternBlockerConfigSchema>;
+export type PIIRedactorConfig = z.infer<typeof PIIRedactorConfigSchema>;
+export type GuardrailsPluginsConfig = z.infer<typeof GuardrailsPluginsConfigSchema>;
+export type GuardrailsConfig = z.infer<typeof GuardrailsConfigSchema>;
 export type Config = z.infer<typeof ConfigSchema>;
 
 export interface ConversationMessage {

package/src/guardrails/context.ts

@@ -0,0 +1,37 @@
+import { randomUUID } from 'crypto';
+import { GuardrailContext, CreateContextOptions } from './types.js';
+
+/**
+ * Create a new guardrail context with defaults
+ */
+export function createGuardrailContext(options: CreateContextOptions = {}): GuardrailContext {
+  return {
+    requestId: options.requestId || randomUUID(),
+    provider: options.provider || 'unknown',
+    model: options.model || 'unknown',
+    timestamp: new Date(),
+    messages: options.messages || [],
+    prompt: options.prompt,
+    response: options.response,
+    toolName: options.toolName,
+    toolArgs: options.toolArgs,
+    toolResult: options.toolResult,
+    metadata: new Map(),
+    violations: [],
+    modifications: [],
+  };
+}
+
+/**
+ * Clone a guardrail context (deep copy metadata but shallow copy violations/modifications)
+ */
+export function cloneContext(context: GuardrailContext): GuardrailContext {
+  return {
+    ...context,
+    messages: [...context.messages],
+    toolArgs: context.toolArgs ? { ...context.toolArgs } : undefined,
+    metadata: new Map(context.metadata),
+    violations: [...context.violations],
+    modifications: [...context.modifications],
+  };
+}

package/src/guardrails/errors.ts

@@ -0,0 +1,46 @@
+/**
+ * Error thrown when a guardrail blocks a request
+ */
+export class GuardrailBlockError extends Error {
+  public readonly pluginName: string;
+  public readonly reason: string;
+
+  constructor(pluginName: string, reason: string) {
+    super(`Request blocked by guardrail '${pluginName}': ${reason}`);
+    this.name = 'GuardrailBlockError';
+    this.pluginName = pluginName;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Error thrown when a guardrail plugin fails to initialize
+ */
+export class GuardrailInitError extends Error {
+  public readonly pluginName: string;
+  public readonly cause: Error | undefined;
+
+  constructor(pluginName: string, message: string, cause?: Error) {
+    super(`Failed to initialize guardrail plugin '${pluginName}': ${message}`);
+    this.name = 'GuardrailInitError';
+    this.pluginName = pluginName;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Error thrown when a guardrail plugin execution fails
+ */
+export class GuardrailExecutionError extends Error {
+  public readonly pluginName: string;
+  public readonly phase: string;
+  public readonly cause: Error | undefined;
+
+  constructor(pluginName: string, phase: string, message: string, cause?: Error) {
+    super(`Guardrail plugin '${pluginName}' failed during '${phase}': ${message}`);
+    this.name = 'GuardrailExecutionError';
+    this.pluginName = pluginName;
+    this.phase = phase;
+    this.cause = cause;
+  }
+}

package/src/guardrails/index.ts

@@ -0,0 +1,20 @@
+// Core types
+export * from './types.js';
+
+// Errors
+export * from './errors.js';
+
+// Context
+export { createGuardrailContext, cloneContext } from './context.js';
+
+// Service
+export { GuardrailsService } from './service.js';
+
+// Plugins
+export {
+  BaseGuardrailPlugin,
+  RateLimiterPlugin,
+  TokenLimiterPlugin,
+  PatternBlockerPlugin,
+  PIIRedactorPlugin,
+} from './plugins/index.js';

package/src/guardrails/plugins/base-plugin.ts

@@ -0,0 +1,103 @@
+import {
+  GuardrailPlugin,
+  GuardrailPhase,
+  GuardrailContext,
+  GuardrailResult,
+} from '../types.js';
+
+/**
+ * Abstract base class for guardrail plugins
+ */
+export abstract class BaseGuardrailPlugin implements GuardrailPlugin {
+  abstract name: string;
+  abstract phases: GuardrailPhase[];
+
+  enabled: boolean = false;
+  priority: number = 100;
+
+  protected config: Record<string, unknown> = {};
+
+  initialize(config: Record<string, unknown>): Promise<void> {
+    this.config = config;
+    this.enabled = true;
+    if (typeof config.priority === 'number') {
+      this.priority = config.priority;
+    }
+    return Promise.resolve();
+  }
+
+  abstract execute(phase: GuardrailPhase, context: GuardrailContext): Promise<GuardrailResult>;
+
+  shutdown(): Promise<void> {
+    this.enabled = false;
+    return Promise.resolve();
+  }
+
+  /**
+   * Helper to create an 'allow' result
+   */
+  protected allow(context: GuardrailContext): GuardrailResult {
+    return { action: 'allow', context };
+  }
+
+  /**
+   * Helper to create a 'block' result
+   */
+  protected block(context: GuardrailContext, reason: string): GuardrailResult {
+    return {
+      action: 'block',
+      context,
+      blockedBy: this.name,
+      blockReason: reason,
+    };
+  }
+
+  /**
+   * Helper to create a 'modify' result
+   */
+  protected modify(context: GuardrailContext): GuardrailResult {
+    return { action: 'modify', context };
+  }
+
+  /**
+   * Helper to add a violation to context
+   */
+  protected addViolation(
+    context: GuardrailContext,
+    phase: GuardrailPhase,
+    rule: string,
+    severity: 'info' | 'warning' | 'error' | 'critical',
+    message: string,
+    details?: Record<string, unknown>
+  ): void {
+    context.violations.push({
+      pluginName: this.name,
+      phase,
+      rule,
+      severity,
+      message,
+      details,
+    });
+  }
+
+  /**
+   * Helper to add a modification to context
+   */
+  protected addModification(
+    context: GuardrailContext,
+    phase: GuardrailPhase,
+    field: string,
+    reason: string,
+    originalValue?: unknown,
+    newValue?: unknown
+  ): void {
+    context.modifications.push({
+      pluginName: this.name,
+      phase,
+      field,
+      originalValue,
+      newValue,
+      reason,
+    });
+  }
+}

package/src/guardrails/plugins/index.ts

@@ -0,0 +1,5 @@
+export { BaseGuardrailPlugin } from './base-plugin.js';
+export { RateLimiterPlugin } from './rate-limiter.js';
+export { TokenLimiterPlugin } from './token-limiter.js';
+export { PatternBlockerPlugin } from './pattern-blocker.js';
+export { PIIRedactorPlugin } from './pii-redactor/index.js';

package/src/guardrails/plugins/pattern-blocker.ts

@@ -0,0 +1,190 @@
+import { BaseGuardrailPlugin } from './base-plugin.js';
+import { GuardrailPhase, GuardrailContext, GuardrailResult } from '../types.js';
+import { PatternBlockerConfig } from '../../config/types.js';
+
+interface PatternMatch {
+  pattern: string;
+  isRegex: boolean;
+  matchedText: string;
+  position: number;
+}
+
+/**
+ * Pattern blocker plugin - blocks or warns on specific patterns
+ */
+export class PatternBlockerPlugin extends BaseGuardrailPlugin {
+  name = 'pattern_blocker';
+  phases: GuardrailPhase[] = ['pre_request', 'pre_tool_input'];
+
+  private blockedPatterns: string[] = [];
+  private blockedPatternsRegex: RegExp[] = [];
+  private caseSensitive: boolean = false;
+  private actionOnMatch: 'block' | 'warn' | 'redact' = 'block';
+
+  async initialize(config: Record<string, unknown>): Promise<void> {
+    await super.initialize(config);
+
+    const typedConfig = config as Partial<PatternBlockerConfig>;
+    this.blockedPatterns = typedConfig.blocked_patterns ?? [];
+    this.caseSensitive = typedConfig.case_sensitive ?? false;
+    this.actionOnMatch = typedConfig.action_on_match ?? 'block';
+    this.priority = typedConfig.priority ?? 30;
+
+    // Compile regex patterns
+    this.blockedPatternsRegex = [];
+    for (const pattern of typedConfig.blocked_patterns_regex ?? []) {
+      try {
+        const flags = this.caseSensitive ? 'g' : 'gi';
+        this.blockedPatternsRegex.push(new RegExp(pattern, flags));
+      } catch (error) {
+        // Invalid regex, skip it
+      }
+    }
+  }
+
+  execute(phase: GuardrailPhase, context: GuardrailContext): Promise<GuardrailResult> {
+    if (!this.phases.includes(phase)) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    // Get text to check based on phase
+    let textToCheck: string;
+    let fieldName: string;
+
+    if (phase === 'pre_request') {
+      textToCheck = context.prompt || '';
+      fieldName = 'prompt';
+    } else if (phase === 'pre_tool_input') {
+      textToCheck = JSON.stringify(context.toolArgs || {});
+      fieldName = 'toolArgs';
+    } else {
+      return Promise.resolve(this.allow(context));
+    }
+
+    // Find matches
+    const matches = this.findMatches(textToCheck);
+
+    if (matches.length === 0) {
+      return Promise.resolve(this.allow(context));
+    }
+
+    // Handle matches based on action
+    const matchSummary = matches.map((m) => m.pattern).join(', ');
+
+    if (this.actionOnMatch === 'block') {
+      this.addViolation(
+        context,
+        phase,
+        'blocked_pattern',
+        'error',
+        `Blocked patterns found: ${matchSummary}`,
+        { matches: matches.map((m) => ({ pattern: m.pattern, position: m.position })) }
+      );
+      return Promise.resolve(this.block(context, `Blocked pattern detected: ${matchSummary}`));
+    }
+
+    if (this.actionOnMatch === 'warn') {
+      this.addViolation(
+        context,
+        phase,
+        'blocked_pattern_warning',
+        'warning',
+        `Suspicious patterns found: ${matchSummary}`,
+        { matches: matches.map((m) => ({ pattern: m.pattern, position: m.position })) }
+      );
+      return Promise.resolve(this.allow(context));
+    }
+
+    if (this.actionOnMatch === 'redact') {
+      // Redact matches from text
+      let redactedText = textToCheck;
+      for (const match of matches) {
+        redactedText = redactedText.replace(
+          match.matchedText,
+          '[REDACTED]'
+        );
+      }
+
+      this.addModification(
+        context,
+        phase,
+        fieldName,
+        `Redacted ${matches.length} blocked patterns`,
+        textToCheck,
+        redactedText
+      );
+
+      // Update context
+      if (phase === 'pre_request') {
+        context.prompt = redactedText;
+        // Also update last message if present (create new object to avoid mutating original)
+        if (context.messages.length > 0) {
+          const lastIndex = context.messages.length - 1;
+          context.messages[lastIndex] = {
+            ...context.messages[lastIndex],
+            content: redactedText,
+          };
+        }
+      } else if (phase === 'pre_tool_input') {
+        try {
+          context.toolArgs = JSON.parse(redactedText) as Record<string, unknown>;
+        } catch {
+          // If parse fails, leave as is
+        }
+      }
+
+      return Promise.resolve(this.modify(context));
+    }
+
+    return Promise.resolve(this.allow(context));
+  }
+
+  /**
+   * Find all pattern matches in text
+   */
+  private findMatches(text: string): PatternMatch[] {
+    const matches: PatternMatch[] = [];
+    const searchText = this.caseSensitive ? text : text.toLowerCase();
+
+    // Check simple string patterns
+    for (const pattern of this.blockedPatterns) {
+      const searchPattern = this.caseSensitive ? pattern : pattern.toLowerCase();
+      let position = searchText.indexOf(searchPattern);
+      while (position !== -1) {
+        matches.push({
+          pattern,
+          isRegex: false,
+          matchedText: text.substring(position, position + pattern.length),
+          position,
+        });
+        position = searchText.indexOf(searchPattern, position + 1);
+      }
+    }
+
+    // Check regex patterns
+    for (const regex of this.blockedPatternsRegex) {
+      regex.lastIndex = 0; // Reset regex state
+      let match;
+      while ((match = regex.exec(text)) !== null) {
+        matches.push({
+          pattern: regex.source,
+          isRegex: true,
+          matchedText: match[0],
+          position: match.index,
+        });
+      }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Get configured patterns (for testing)
+   */
+  getPatterns(): { simple: string[]; regex: string[] } {
+    return {
+      simple: [...this.blockedPatterns],
+      regex: this.blockedPatternsRegex.map((r) => r.source),
+    };
+  }
+}

package/src/guardrails/plugins/pii-redactor/detectors.ts

@@ -0,0 +1,200 @@
+export type PIIType =
+  | 'email'
+  | 'phone'
+  | 'ssn'
+  | 'api_key'
+  | 'credit_card'
+  | 'ip_address'
+  | 'custom';
+
+export interface PIIDetection {
+  type: PIIType;
+  value: string;
+  startIndex: number;
+  endIndex: number;
+  confidence: number;
+}
+
+export interface PIIDetectorConfig {
+  detectEmails: boolean;
+  detectPhones: boolean;
+  detectSSN: boolean;
+  detectAPIKeys: boolean;
+  detectCreditCards: boolean;
+  detectIPAddresses: boolean;
+  customPatterns: Array<{ name: string; pattern: string; placeholder: string }>;
+  allowlist: string[];
+  allowlistDomains: string[];
+}
+
+/**
+ * PII detector using regex patterns
+ */
+export class PIIDetector {
+  private patterns: Map<PIIType, RegExp> = new Map();
+  private allowlist: Set<string>;
+  private allowlistDomains: Set<string>;
+  private customPatterns: Array<{ name: string; regex: RegExp; placeholder: string }> = [];
+
+  constructor(config: PIIDetectorConfig) {
+    this.allowlist = new Set(config.allowlist.map((a) => a.toLowerCase()));
+    this.allowlistDomains = new Set(config.allowlistDomains.map((d) => d.toLowerCase()));
+
+    // Initialize built-in patterns
+    if (config.detectEmails) {
+      this.patterns.set(
+        'email',
+        /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g
+      );
+    }
+
+    if (config.detectPhones) {
+      // Handles multiple phone formats: US, international, with/without country code
+      this.patterns.set(
+        'phone',
+        /\b(?:\+?1[-.\s]?)?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}\b/g
+      );
+    }
+
+    if (config.detectSSN) {
+      // US SSN format: XXX-XX-XXXX or XXXXXXXXX
+      this.patterns.set(
+        'ssn',
+        /\b[0-9]{3}[-\s]?[0-9]{2}[-\s]?[0-9]{4}\b/g
+      );
+    }
+
+    if (config.detectAPIKeys) {
+      // Common API key patterns
+      this.patterns.set(
+        'api_key',
+        /\b(sk-[a-zA-Z0-9]{20,}|gsk_[a-zA-Z0-9]{20,}|api[_-]?key[_-]?[a-zA-Z0-9]{16,})\b/gi
+      );
+    }
+
+    if (config.detectCreditCards) {
+      // Credit card patterns (Visa, Mastercard, Amex, Discover)
+      // Simplified - doesn't validate Luhn, just matches format
+      this.patterns.set(
+        'credit_card',
+        /\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13}|6(?:011|5[0-9]{2})[0-9]{12})\b/g
+      );
+    }
+
+    if (config.detectIPAddresses) {
+      // IPv4 addresses
+      this.patterns.set(
+        'ip_address',
+        /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g
+      );
+    }
+
+    // Custom patterns
+    for (const custom of config.customPatterns) {
+      try {
+        this.customPatterns.push({
+          name: custom.name,
+          regex: new RegExp(custom.pattern, 'g'),
+          placeholder: custom.placeholder,
+        });
+      } catch {
+        // Invalid regex, skip it
+      }
+    }
+  }
+
+  /**
+   * Detect PII in text
+   */
+  detect(text: string): PIIDetection[] {
+    const detections: PIIDetection[] = [];
+
+    // Check built-in patterns
+    for (const [type, pattern] of this.patterns) {
+      pattern.lastIndex = 0; // Reset regex state
+      let match;
+      while ((match = pattern.exec(text)) !== null) {
+        const value = match[0];
+
+        // Check allowlist
+        if (this.isAllowlisted(value, type)) {
+          continue;
+        }
+
+        detections.push({
+          type,
+          value,
+          startIndex: match.index,
+          endIndex: match.index + value.length,
+          confidence: this.calculateConfidence(type, value),
+        });
+      }
+    }
+
+    // Check custom patterns
+    for (const custom of this.customPatterns) {
+      custom.regex.lastIndex = 0;
+      let match;
+      while ((match = custom.regex.exec(text)) !== null) {
+        const value = match[0];
+
+        if (this.allowlist.has(value.toLowerCase())) {
+          continue;
+        }
+
+        detections.push({
+          type: 'custom',
+          value,
+          startIndex: match.index,
+          endIndex: match.index + value.length,
+          confidence: 0.9,
+        });
+      }
+    }
+
+    // Sort by position (for consistent pseudonymization)
+    return detections.sort((a, b) => a.startIndex - b.startIndex);
+  }
+
+  private isAllowlisted(value: string, type: PIIType): boolean {
+    const lowerValue = value.toLowerCase();
+
+    if (this.allowlist.has(lowerValue)) {
+      return true;
+    }
+
+    // For emails, check domain allowlist
+    if (type === 'email') {
+      const domain = lowerValue.split('@')[1];
+      if (domain && this.allowlistDomains.has(domain)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private calculateConfidence(type: PIIType, value: string): number {
+    // Simple confidence scoring based on format strictness
+    switch (type) {
+      case 'ssn':
+        return 0.95; // High confidence for strict format
+      case 'credit_card':
+        return 0.95; // High confidence for strict format
+      case 'email':
+        return 0.9;
+      case 'phone':
+        return 0.85;
+      case 'api_key':
+        // Higher confidence for longer keys or known prefixes
+        if (value.startsWith('sk-') || value.startsWith('gsk_')) {
+          return 0.95;
+        }
+        return 0.7; // Lower confidence due to possible false positives
+      case 'ip_address':
+        return 0.8;
+      default:
+        return 0.8;
+    }
+  }
+}