forgedev 1.2.0 → 1.3.0

package/templates/ai/guardrails-py/backend/app/ai/input_guard.py

@@ -0,0 +1,98 @@
+"""AI Input Guard — Prompt injection detection and input sanitization.
+
+Compliance: EU AI Act Art. 15 (robustness), NIST AI RMF Manage 2.2
+"""
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class InputValidationResult:
+    blocked: bool
+    reason: str | None = None
+    detected_patterns: list[str] = field(default_factory=list)
+
+
+# --- Injection Detection Patterns ---
+
+INJECTION_PATTERNS: list[tuple[re.Pattern, str]] = [
+    # Direct instruction override
+    (re.compile(r"ignore\s+(all\s+)?(previous|prior|above)\s+(instructions|prompts|rules)", re.I), "instruction-override"),
+    (re.compile(r"disregard\s+(all\s+)?(previous|prior|above|your)\s+(instructions|prompts|rules|training)", re.I), "instruction-override"),
+    (re.compile(r"forget\s+(all\s+)?(previous|prior|your)\s+(instructions|context|rules)", re.I), "instruction-override"),
+
+    # Role manipulation
+    (re.compile(r"you\s+are\s+now\s+(a|an|the)\s+", re.I), "role-manipulation"),
+    (re.compile(r"act\s+as\s+(if\s+you\s+are|a|an)\s+", re.I), "role-manipulation"),
+    (re.compile(r"pretend\s+(to\s+be|you\s+are)\s+", re.I), "role-manipulation"),
+    (re.compile(r"from\s+now\s+on\s+(you|your)\s+", re.I), "role-manipulation"),
+
+    # System prompt extraction
+    (re.compile(r"what\s+(is|are)\s+your\s+(system\s+)?(prompt|instructions|rules)", re.I), "prompt-extraction"),
+    (re.compile(r"show\s+me\s+your\s+(system\s+)?(prompt|instructions)", re.I), "prompt-extraction"),
+    (re.compile(r"repeat\s+(your|the)\s+(system\s+)?(prompt|instructions)", re.I), "prompt-extraction"),
+    (re.compile(r"print\s+(your|the)\s+(system\s+)?(prompt|instructions)", re.I), "prompt-extraction"),
+
+    # Delimiter injection
+    (re.compile(r"</?system>", re.I), "delimiter-injection"),
+    (re.compile(r"\[INST\]", re.I), "delimiter-injection"),
+    (re.compile(r"<\|im_start\|", re.I), "delimiter-injection"),
+    (re.compile(r"###\s*(system|instruction|human|assistant)", re.I), "delimiter-injection"),
+
+    # Data exfiltration
+    (re.compile(r"send\s+(this|the|all)\s+(data|info|conversation)\s+to", re.I), "data-exfiltration"),
+    (re.compile(r"forward\s+(this|everything)\s+to", re.I), "data-exfiltration"),
+]
+
+SUSPICIOUS_PATTERNS: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"eval\s*\(", re.I), "code-execution"),
+    (re.compile(r"exec\s*\(", re.I), "code-execution"),
+    (re.compile(r"import\s+(?:os|subprocess)|subprocess\.", re.I), "code-execution"),
+    (re.compile(r"[A-Za-z0-9+/]{100,}={0,2}", re.I), "encoded-payload"),
+]
+
+
+def validate_input(text: str) -> InputValidationResult:
+    """Validate input for prompt injection and safety concerns."""
+    import unicodedata
+    # Normalize Unicode to defeat homoglyph attacks (e.g., Cyrillic "а" for Latin "a")
+    normalized = unicodedata.normalize("NFKC", text)
+    detected: list[str] = []
+
+    for pattern, name in INJECTION_PATTERNS:
+        if pattern.search(normalized):
+            detected.append(name)
+
+    if detected:
+        unique = list(set(detected))
+        return InputValidationResult(
+            blocked=True,
+            reason=f"Potential prompt injection detected: {', '.join(unique)}",
+            detected_patterns=unique,
+        )
+
+    suspicious: list[str] = []
+    for pattern, name in SUSPICIOUS_PATTERNS:
+        if pattern.search(normalized):
+            suspicious.append(name)
+
+    if suspicious:
+        return InputValidationResult(
+            blocked=False,
+            reason=f"Suspicious patterns detected (not blocked): {', '.join(suspicious)}",
+            detected_patterns=suspicious,
+        )
+
+    return InputValidationResult(blocked=False)
+
+
+def sanitize_input(text: str) -> str:
+    """Remove known dangerous patterns from input."""
+    sanitized = re.sub(r"</?system>", "", text, flags=re.I)
+    sanitized = re.sub(r"\[INST\]", "", sanitized, flags=re.I)
+    sanitized = re.sub(r"<\|im_start\|[^>]*>?", "", sanitized, flags=re.I)
+    sanitized = re.sub(r"<\|im_end\|>?", "", sanitized, flags=re.I)
+    sanitized = re.sub(r"###\s*(system|instruction|human|assistant)", "", sanitized, flags=re.I)
+    sanitized = sanitized.replace("\x00", "")
+    return sanitized

package/templates/ai/guardrails-ts/src/lib/ai/audit-log.ts.template

@@ -0,0 +1,164 @@
+/**
+ * AI Audit Logger — Structured logging of all AI interactions.
+ *
+ * Compliance: EU AI Act Art. 12 (logging and traceability),
+ *             NIST AI RMF Manage 1.3 (monitoring)
+ *
+ * Every AI call is logged with:
+ * - Input preview (truncated, no PII in logs)
+ * - Output confidence score
+ * - Model version and parameters
+ * - Human review decisions
+ * - Latency and token usage
+ * - Error details
+ *
+ * Logs are structured JSON for easy ingestion into observability platforms
+ * (Datadog, Grafana, ELK, etc.)
+ */
+
+export interface AuditEntry {
+  /** Unique interaction ID (matches AIResponse.auditId) */
+  id: string;
+  /** ISO 8601 timestamp */
+  timestamp: string;
+  /** Model identifier */
+  model: string;
+  /** Business purpose of this AI call */
+  purpose: string;
+  /** Truncated input for traceability (never log full PII) */
+  inputPreview: string;
+  /** Confidence score (0-1) */
+  confidence: number;
+  /** Whether human review was triggered */
+  needsHumanReview: boolean;
+  /** Total latency in milliseconds */
+  latencyMs: number;
+  /** Token usage for cost tracking */
+  tokenUsage?: { inputTokens: number; outputTokens: number };
+  /** Whether the call succeeded */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+  /** Human reviewer action (if reviewed) */
+  humanAction?: 'approved' | 'rejected' | 'modified';
+  /** Human reviewer ID (if reviewed) */
+  humanReviewerId?: string;
+}
+
+export interface AuditLogConfig {
+  /** Where to send logs: 'console' or custom handler */
+  destination: 'console' | 'custom';
+  /** Custom log handler */
+  handler?: (entry: AuditEntry) => void;
+  /** Log level filter: only log entries with confidence below this */
+  confidenceAlertThreshold?: number;
+}
+
+class AIAuditLog {
+  private config: AuditLogConfig;
+  private entries: AuditEntry[] = [];
+  private maxInMemory = 1000;
+
+  constructor(config?: Partial<AuditLogConfig>) {
+    this.config = {
+      destination: config?.destination || 'console',
+      handler: config?.handler,
+      confidenceAlertThreshold: config?.confidenceAlertThreshold ?? 0.5,
+    };
+  }
+
+  log(entry: AuditEntry): void {
+    // In-memory buffer for health metrics
+    this.entries.push(entry);
+    if (this.entries.length > this.maxInMemory) {
+      this.entries = this.entries.slice(-this.maxInMemory);
+    }
+
+    // Structured log output (exclude inputPreview to avoid PII in logs)
+    const { inputPreview: _preview, ...safeEntry } = entry;
+    const logEntry = {
+      level: entry.success ? 'info' : 'error',
+      type: 'ai_interaction',
+      ...safeEntry,
+    };
+
+    switch (this.config.destination) {
+      case 'console':
+        if (!entry.success || (entry.confidence < (this.config.confidenceAlertThreshold ?? 0.5))) {
+          console.warn('[AI_AUDIT]', JSON.stringify(logEntry));
+        } else {
+          console.log('[AI_AUDIT]', JSON.stringify(logEntry));
+        }
+        break;
+      case 'custom':
+        this.config.handler?.(entry);
+        break;
+    }
+  }
+
+  /**
+   * Record a human review decision against an existing audit entry.
+   */
+  recordHumanReview(auditId: string, action: 'approved' | 'rejected' | 'modified', reviewerId?: string): void {
+    const entry = this.entries.find(e => e.id === auditId);
+    if (!entry) {
+      console.warn(`[AI_AUDIT] Cannot record human review: audit entry ${auditId} not found`);
+      return;
+    }
+    entry.humanAction = action;
+    entry.humanReviewerId = reviewerId;
+    // Re-emit to log destination without adding duplicate to buffer
+    const logEntry = {
+      level: 'info',
+      type: 'ai_interaction_review',
+      ...entry,
+    };
+    if (this.config.destination === 'console') {
+      console.log('[AI_AUDIT]', JSON.stringify(logEntry));
+    } else if (this.config.destination === 'custom') {
+      this.config.handler?.(entry);
+    }
+  }
+
+  /**
+   * Get recent entries for monitoring dashboard.
+   */
+  getRecentEntries(count = 50): AuditEntry[] {
+    return this.entries.slice(-count);
+  }
+
+  /**
+   * Get aggregate stats for AI health reporting.
+   */
+  getStats(windowMs = 3600_000): {
+    totalCalls: number;
+    successRate: number;
+    avgConfidence: number;
+    avgLatencyMs: number;
+    humanReviewRate: number;
+    errorRate: number;
+  } {
+    const cutoff = new Date(Date.now() - windowMs).toISOString();
+    const recent = this.entries.filter(e => e.timestamp >= cutoff);
+
+    if (recent.length === 0) {
+      return { totalCalls: 0, successRate: 1, avgConfidence: 0, avgLatencyMs: 0, humanReviewRate: 0, errorRate: 0 };
+    }
+
+    const successes = recent.filter(e => e.success).length;
+    const reviews = recent.filter(e => e.needsHumanReview).length;
+
+    return {
+      totalCalls: recent.length,
+      successRate: successes / recent.length,
+      avgConfidence: recent.reduce((sum, e) => sum + e.confidence, 0) / recent.length,
+      avgLatencyMs: recent.reduce((sum, e) => sum + e.latencyMs, 0) / recent.length,
+      humanReviewRate: reviews / recent.length,
+      errorRate: 1 - (successes / recent.length),
+    };
+  }
+}
+
+// --- Singleton ---
+
+export const aiAuditLog = new AIAuditLog();

package/templates/ai/guardrails-ts/src/lib/ai/client.ts.template

@@ -0,0 +1,403 @@
+/**
+ * AI Client — Central wrapper for all LLM interactions.
+ *
+ * Every AI call goes through this client, which provides:
+ * - Input validation and prompt injection detection
+ * - Output validation against Zod schemas
+ * - Confidence scoring with human review routing
+ * - Structured audit logging (EU AI Act Art. 12)
+ * - AI disclosure headers (EU AI Act Art. 50)
+ * - Health metrics collection (NIST AI RMF Manage 3.2)
+ *
+ * Compliance: EU AI Act (2024/1689), NIST AI RMF 1.0
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import { z, type ZodSchema } from 'zod';
+import { aiAuditLog, type AuditEntry } from './audit-log.js';
+import { validateInput, type InputValidationResult } from './input-guard.js';
+import { aiHealthMetrics } from './health.js';
+
+// --- Configuration ---
+
+export interface AIClientConfig {
+  /** Anthropic API key (defaults to ANTHROPIC_API_KEY env var) */
+  apiKey?: string;
+  /** Default model to use */
+  model?: string;
+  /** Confidence threshold below which human review is required (0-1) */
+  confidenceThreshold?: number;
+  /** Maximum input length in characters */
+  maxInputLength?: number;
+  /** Enable prompt injection detection */
+  detectInjection?: boolean;
+  /** Enable structured audit logging */
+  auditLog?: boolean;
+  /** Custom moderation function (return true to block) */
+  moderator?: (input: string) => Promise<boolean>;
+}
+
+const DEFAULT_CONFIG: Required<AIClientConfig> = {
+  apiKey: process.env.ANTHROPIC_API_KEY || '',
+  model: 'claude-sonnet-4-20250514',
+  confidenceThreshold: 0.7,
+  maxInputLength: 100_000,
+  detectInjection: true,
+  auditLog: true,
+  moderator: async () => false,
+};
+
+// --- Core Client ---
+
+export class AIClient {
+  private client: Anthropic;
+  private config: Required<AIClientConfig>;
+
+  constructor(config: AIClientConfig = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    if (!this.config.apiKey) {
+      throw new Error('ANTHROPIC_API_KEY environment variable is required');
+    }
+    this.client = new Anthropic({ apiKey: this.config.apiKey });
+  }
+
+  /**
+   * Generate a structured response validated against a Zod schema.
+   *
+   * This is the primary method for AI interactions. It:
+   * 1. Validates and sanitizes input
+   * 2. Calls the model
+   * 3. Parses and validates output against the schema
+   * 4. Scores confidence
+   * 5. Logs the interaction for audit
+   * 6. Routes to human review if confidence is low
+   */
+  async generate<T>(options: {
+    prompt: string;
+    schema: ZodSchema<T>;
+    systemPrompt?: string;
+    context?: string;
+    /** Override model for this call */
+    model?: string;
+    /** Override confidence threshold for this call */
+    confidenceThreshold?: number;
+    /** Max retries on validation failure */
+    maxRetries?: number;
+    /** Purpose tag for audit log */
+    purpose?: string;
+  }): Promise<AIResponse<T>> {
+    const startTime = Date.now();
+    const model = options.model || this.config.model;
+    const threshold = options.confidenceThreshold ?? this.config.confidenceThreshold;
+    const maxRetries = options.maxRetries ?? 2;
+
+    // Step 1: Input validation
+    const inputValidation = await this.validateInputs(options.prompt, options.context);
+    if (inputValidation.blocked) {
+      const result = this.buildBlockedResponse<T>(inputValidation, startTime, model, options.purpose);
+      return result;
+    }
+
+    // Step 2: Call model with retries on parse failure
+    let lastError: Error | null = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await this.callModel(
+          options.prompt,
+          options.systemPrompt,
+          options.context,
+          model,
+          options.schema,
+        );
+
+        // Step 3: Parse and validate output
+        const parsed = options.schema.safeParse(response.content);
+        if (!parsed.success) {
+          lastError = new Error(`Output validation failed: ${parsed.error.message}`);
+          if (attempt < maxRetries) continue;
+          break;
+        }
+
+        // Step 4: Score confidence
+        const confidence = this.scoreConfidence(response);
+        const needsReview = confidence < threshold;
+
+        // Step 5: Build response
+        const result: AISuccessResponse<T> = {
+          success: true,
+          data: parsed.data,
+          confidence,
+          needsHumanReview: needsReview,
+          model,
+          latencyMs: Date.now() - startTime,
+          tokenUsage: response.usage,
+          aiGenerated: true,
+          auditId: crypto.randomUUID(),
+        };
+
+        // Step 6: Audit log
+        if (this.config.auditLog) {
+          this.logInteraction(result, options.prompt, options.purpose);
+        }
+
+        // Step 7: Health metrics
+        aiHealthMetrics.recordCall({
+          model,
+          latencyMs: result.latencyMs,
+          confidence,
+          success: true,
+          tokenUsage: response.usage,
+        });
+
+        return result;
+
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < maxRetries) continue;
+      }
+    }
+
+    // All retries exhausted
+    aiHealthMetrics.recordCall({
+      model,
+      latencyMs: Date.now() - startTime,
+      confidence: 0,
+      success: false,
+    });
+
+    return {
+      success: false,
+      model,
+      latencyMs: Date.now() - startTime,
+      aiGenerated: true,
+      auditId: crypto.randomUUID(),
+      error: lastError?.message || 'AI call failed after retries',
+    };
+  }
+
+  /**
+   * Simple text generation without schema validation.
+   * Still applies input guards, audit logging, and confidence scoring.
+   */
+  async generateText(options: {
+    prompt: string;
+    systemPrompt?: string;
+    context?: string;
+    model?: string;
+    purpose?: string;
+  }): Promise<AIResponse<string>> {
+    return this.generate({
+      ...options,
+      schema: z.any().transform(String),
+    });
+  }
+
+  // --- Private Methods ---
+
+  private async validateInputs(
+    prompt: string,
+    context?: string,
+  ): Promise<InputValidationResult> {
+    const fullInput = context ? `${prompt}\n${context}` : prompt;
+
+    if (fullInput.length > this.config.maxInputLength) {
+      return { blocked: true, reason: `Input exceeds maximum length (${this.config.maxInputLength} chars)` };
+    }
+
+    if (this.config.detectInjection) {
+      const result = validateInput(fullInput);
+      if (result.blocked) return result;
+    }
+
+    if (this.config.moderator) {
+      const blocked = await this.config.moderator(fullInput);
+      if (blocked) return { blocked: true, reason: 'Content blocked by moderation policy' };
+    }
+
+    return { blocked: false };
+  }
+
+  private async callModel(
+    prompt: string,
+    systemPrompt: string | undefined,
+    context: string | undefined,
+    model: string,
+    schema: ZodSchema,
+  ) {
+    const userContent = context
+      ? `${prompt}\n\nContext:\n${context}`
+      : prompt;
+
+    const messages: Anthropic.MessageParam[] = [
+      { role: 'user', content: userContent },
+    ];
+
+    const response = await this.client.messages.create({
+      model,
+      max_tokens: 4096,
+      system: systemPrompt || `You are an AI assistant for {{PROJECT_NAME}}. Respond with valid JSON matching the requested schema. Be precise and factual.`,
+      messages,
+    });
+
+    const textBlock = response.content.find(
+      (block): block is Anthropic.TextBlock => block.type === 'text'
+    );
+
+    return {
+      content: this.extractJSON(textBlock?.text || ''),
+      usage: {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens,
+      },
+      stopReason: response.stop_reason,
+    };
+  }
+
+  private extractJSON(text: string): unknown {
+    // Try direct parse first
+    try {
+      return JSON.parse(text);
+    } catch {
+      // Extract JSON from markdown code blocks
+      const jsonMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+      if (jsonMatch) {
+        try {
+          return JSON.parse(jsonMatch[1].trim());
+        } catch {
+          // Fall through to return raw text
+        }
+      }
+      // Return raw text for string schema
+      return text;
+    }
+  }
+
+  private scoreConfidence(response: {
+    stopReason: string | null;
+    usage: { inputTokens: number; outputTokens: number };
+  }): number {
+    let score = 0.85; // Base confidence
+
+    // Penalize if model was cut off
+    if (response.stopReason === 'max_tokens') {
+      score -= 0.3;
+    }
+
+    // Penalize very short responses (likely incomplete)
+    if (response.usage.outputTokens < 10) {
+      score -= 0.2;
+    }
+
+    // Penalize very long responses (may indicate hallucination loops)
+    if (response.usage.outputTokens > 3000) {
+      score -= 0.1;
+    }
+
+    return Math.max(0, Math.min(1, score));
+  }
+
+  private logInteraction<T>(
+    result: AISuccessResponse<T>,
+    prompt: string,
+    purpose?: string,
+  ): void {
+    const entry: AuditEntry = {
+      id: result.auditId,
+      timestamp: new Date().toISOString(),
+      model: result.model,
+      purpose: purpose || 'unspecified',
+      inputPreview: prompt.slice(0, 100) + (prompt.length > 100 ? '...' : ''),
+      confidence: result.confidence,
+      needsHumanReview: result.needsHumanReview,
+      latencyMs: result.latencyMs,
+      tokenUsage: result.tokenUsage,
+      success: true,
+    };
+    aiAuditLog.log(entry);
+  }
+
+  private buildBlockedResponse<T>(
+    validation: InputValidationResult,
+    startTime: number,
+    model: string,
+    purpose?: string,
+  ): AIErrorResponse {
+    const result: AIErrorResponse = {
+      success: false,
+      model,
+      latencyMs: Date.now() - startTime,
+      aiGenerated: false,
+      auditId: crypto.randomUUID(),
+      error: `Input blocked: ${validation.reason}`,
+      blocked: true,
+    };
+
+    if (this.config.auditLog) {
+      aiAuditLog.log({
+        id: result.auditId,
+        timestamp: new Date().toISOString(),
+        model,
+        purpose: purpose || 'unspecified',
+        inputPreview: '[BLOCKED]',
+        confidence: 0,
+        needsHumanReview: false,
+        latencyMs: result.latencyMs,
+        success: false,
+        error: validation.reason,
+      });
+    }
+
+    return result;
+  }
+}
+
+// --- Types ---
+
+interface AIResponseBase {
+  /** Model used for this call */
+  model: string;
+  /** Total latency in milliseconds */
+  latencyMs: number;
+  /** EU AI Act Art. 50: flag indicating AI-generated content */
+  aiGenerated: boolean;
+  /** Unique ID for audit trail */
+  auditId: string;
+}
+
+export interface AISuccessResponse<T> extends AIResponseBase {
+  success: true;
+  /** The validated, typed response data */
+  data: T;
+  /** Confidence score (0-1). Below threshold triggers human review */
+  confidence: number;
+  /** Whether this response needs human review before acting on it */
+  needsHumanReview: boolean;
+  /** Token usage for cost tracking */
+  tokenUsage?: { inputTokens: number; outputTokens: number };
+}
+
+export interface AIErrorResponse extends AIResponseBase {
+  success: false;
+  /** Error message describing the failure */
+  error: string;
+  /** Whether input was blocked by guards */
+  blocked?: boolean;
+}
+
+export type AIResponse<T> = AISuccessResponse<T> | AIErrorResponse;
+
+// --- Singleton ---
+
+let _defaultClient: AIClient | null = null;
+
+export function getAIClient(config?: AIClientConfig): AIClient {
+  if (!_defaultClient || config) {
+    if (_defaultClient && config) {
+      console.warn('AIClient already initialized. Ignoring new config. Use new AIClient(config) for custom instances.');
+    }
+    if (!_defaultClient) {
+      _defaultClient = new AIClient(config);
+    }
+  }
+  return _defaultClient;
+}