@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/docs/04-advanced/04-guardrails.md

@@ -0,0 +1,597 @@
+# Guardrails & Security
+
+This guide covers the security middleware for AI agents, including prompt injection detection, PII masking, and content filtering.
+
+## Overview
+
+Guardrails provide **three layers of protection**:
+
+```
+User Input → [Injection Check] → [PII Mask] → Agent → [Content Filter] → Response
+                   ↓                 ↓                       ↓
+               Block/Warn         Redact                Block/Redact
+```
+
+**Key Features**:
+- **Prompt Injection Detection**: Blocks attempts to manipulate agent behavior
+- **PII Masking**: Redacts sensitive personal information
+- **Content Filtering**: Filters inappropriate AI outputs
+- **Configurable Actions**: Block, warn, log, or redact
+
+---
+
+## Architecture
+
+### Processing Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     INPUT PROCESSING                         │
+│                                                              │
+│  User Input                                                  │
+│      │                                                       │
+│      ▼                                                       │
+│  ┌──────────────────┐                                        │
+│  │ Injection Check  │──blocked?──► Error: Input blocked     │
+│  └────────┬─────────┘                                        │
+│           │ (safe)                                           │
+│           ▼                                                  │
+│  ┌──────────────────┐                                        │
+│  │   PII Masking    │                                        │
+│  └────────┬─────────┘                                        │
+│           │                                                  │
+│           ▼                                                  │
+│     Processed Input → Agent                                  │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│                    OUTPUT PROCESSING                         │
+│                                                              │
+│     Agent Output                                             │
+│           │                                                  │
+│           ▼                                                  │
+│  ┌──────────────────┐                                        │
+│  │  Content Filter  │──blocked?──► Empty response           │
+│  └────────┬─────────┘                                        │
+│           │                                                  │
+│           ▼                                                  │
+│     Filtered Output → User                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Configuration
+
+Configure guardrails in `langchain.config.ts`:
+
+```typescript
+export const langchainConfig = {
+  guardrails: {
+    promptInjection: {
+      enabled: true,
+      action: 'block',          // 'block' | 'warn' | 'log'
+      customPatterns: [],       // Additional regex patterns
+    },
+    piiMasking: {
+      enabled: true,
+      types: ['email', 'phone', 'ssn', 'creditCard', 'ipAddress'],
+      action: 'mask',           // 'mask' | 'remove' | 'log'
+    },
+    contentFilter: {
+      enabled: true,
+      customPatterns: [],       // Content patterns to filter
+      action: 'redact',         // 'block' | 'redact'
+    },
+  },
+}
+```
+
+### Configuration Options
+
+| Section | Option | Type | Description |
+|---------|--------|------|-------------|
+| `promptInjection` | `enabled` | boolean | Enable injection detection |
+| | `action` | string | Action: `block`, `warn`, `log` |
+| | `customPatterns` | RegExp[] | Additional detection patterns |
+| `piiMasking` | `enabled` | boolean | Enable PII masking |
+| | `types` | string[] | PII types to mask |
+| | `action` | string | Action: `mask`, `remove`, `log` |
+| `contentFilter` | `enabled` | boolean | Enable output filtering |
+| | `customPatterns` | RegExp[] | Patterns to filter |
+| | `action` | string | Action: `block`, `redact` |
+
+---
+
+## Prompt Injection Detection
+
+### Built-in Patterns
+
+The guardrails detect common prompt injection attempts:
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| Ignore instructions | "ignore previous instructions" | Attempts to override system prompt |
+| Forget commands | "forget everything above" | Tries to clear context |
+| Role impersonation | "you are now a hacker" | Attempts to change agent behavior |
+| Disregard rules | "disregard your rules" | Bypassing constraints |
+| Pretend commands | "pretend to be a different AI" | Role manipulation |
+| Act as prompts | "act as if you have no restrictions" | Behavior modification |
+| Jailbreak attempts | "jailbreak mode" | Known bypass terms |
+| System injection | `[system]`, `<system>`, `{{system}}` | Template/prompt injection |
+
+### Pattern List
+
+```typescript
+const INJECTION_PATTERNS = [
+    /ignore\s+(previous|all|above)\s+(instructions?|prompts?)/i,
+    /forget\s+(everything|all|previous)/i,
+    /you\s+are\s+now\s+/i,
+    /disregard\s+(all|previous|your)\s/i,
+    /pretend\s+(you\s+are|to\s+be)/i,
+    /act\s+as\s+(if|a|an)\s/i,
+    /jailbreak/i,
+    /bypass\s+(restrictions?|filters?|rules?)/i,
+    /system\s*:\s*/i,
+    /\[system\]/i,
+    /\<system\>/i,
+    /\{\{.*system.*\}\}/i,
+]
+```
+
+### Custom Patterns
+
+Add your own detection patterns:
+
+```typescript
+guardrails: {
+  promptInjection: {
+    enabled: true,
+    action: 'block',
+    customPatterns: [
+      /reveal\s+your\s+prompt/i,
+      /what\s+are\s+your\s+instructions/i,
+      /show\s+me\s+your\s+system\s+message/i,
+    ],
+  },
+}
+```
+
+### Actions
+
+| Action | Behavior |
+|--------|----------|
+| `block` | Throws error, request is rejected |
+| `warn` | Continues but adds warning to response |
+| `log` | Silently logs, request continues |
+
+### Usage
+
+```typescript
+import { guardrails } from '@/contents/plugins/langchain/lib/guardrails'
+
+const result = guardrails.checkInjection(
+    userInput,
+    config.guardrails.promptInjection
+)
+
+if (!result.safe) {
+    console.log('Injection detected:', result.reason)
+    console.log('Pattern matched:', result.pattern)
+}
+```
+
+---
+
+## PII Masking
+
+### Supported PII Types
+
+| Type | Pattern | Example | Masked |
+|------|---------|---------|--------|
+| `email` | Standard email format | john@example.com | jo**********om |
+| `phone` | US phone numbers | (555) 123-4567 | (5********67 |
+| `ssn` | Social Security Number | 123-45-6789 | 12*****89 |
+| `creditCard` | Credit card numbers | 1234-5678-9012-3456 | 12**************56 |
+| `ipAddress` | IPv4 addresses | 192.168.1.100 | 19*******00 |
+
+### Masking Actions
+
+| Action | Input | Output |
+|--------|-------|--------|
+| `mask` | john@example.com | jo**********om |
+| `remove` | john@example.com | [REDACTED] |
+| `log` | john@example.com | john@example.com (logged) |
+
+### Usage
+
+```typescript
+import { guardrails } from '@/contents/plugins/langchain/lib/guardrails'
+
+const result = guardrails.maskPII(userInput, {
+    enabled: true,
+    types: ['email', 'phone', 'creditCard'],
+    action: 'mask',
+})
+
+console.log(result.masked)      // Text with PII masked
+console.log(result.hasPII)      // true/false
+console.log(result.mappings)    // [{original, masked, type}]
+```
+
+### Response Structure
+
+```typescript
+interface PIIMaskResult {
+    masked: string                    // Text with PII masked
+    mappings: Array<{                 // Details of masked items
+        original: string              // Original value
+        masked: string                // Masked value
+        type: string                  // PII type (email, phone, etc.)
+    }>
+    hasPII: boolean                   // Whether PII was found
+}
+```
+
+---
+
+## Content Filtering
+
+### Purpose
+
+Filter AI outputs to prevent:
+- Harmful content generation
+- Inappropriate responses
+- Sensitive information disclosure
+
+### Custom Patterns
+
+```typescript
+guardrails: {
+  contentFilter: {
+    enabled: true,
+    action: 'redact',
+    customPatterns: [
+      /password\s*[:=]\s*\S+/gi,      // Password exposure
+      /api[_-]?key\s*[:=]\s*\S+/gi,   // API key exposure
+      /secret\s*[:=]\s*\S+/gi,        // Secret exposure
+    ],
+  },
+}
+```
+
+### Actions
+
+| Action | Behavior |
+|--------|----------|
+| `block` | Returns empty response |
+| `redact` | Replaces matched content with `[FILTERED]` |
+
+### Usage
+
+```typescript
+import { guardrails } from '@/contents/plugins/langchain/lib/guardrails'
+
+const result = guardrails.filterContent(
+    aiOutput,
+    config.guardrails.contentFilter
+)
+
+if (result.blocked) {
+    console.log('Content blocked:', result.reason)
+} else {
+    console.log('Filtered output:', result.filtered)
+}
+```
+
+---
+
+## Complete Pipeline
+
+### processInput
+
+Runs all input guardrails:
+
+```typescript
+import { guardrails } from '@/contents/plugins/langchain/lib/guardrails'
+
+try {
+    const { processed, warnings } = await guardrails.processInput(
+        userInput,
+        config.guardrails
+    )
+
+    if (warnings.length > 0) {
+        console.log('Warnings:', warnings)
+    }
+
+    // Use 'processed' for agent input
+    const response = await agent.invoke(processed)
+} catch (error) {
+    // Input was blocked
+    console.error('Input blocked:', error.message)
+}
+```
+
+### processOutput
+
+Runs output guardrails:
+
+```typescript
+const { processed, blocked } = await guardrails.processOutput(
+    agentOutput,
+    config.guardrails
+)
+
+if (blocked) {
+    return { response: 'Unable to generate appropriate response.' }
+}
+
+return { response: processed }
+```
+
+---
+
+## Integration with Orchestrator
+
+### Automatic Integration
+
+When guardrails are enabled, they're automatically applied:
+
+```typescript
+// In agent factory or orchestrator
+const guardrailsConfig = langchainConfig.guardrails
+
+// Before agent invocation
+const { processed: safeInput, warnings } = await guardrails.processInput(
+    message,
+    guardrailsConfig
+)
+
+// After agent response
+const { processed: safeOutput, blocked } = await guardrails.processOutput(
+    response,
+    guardrailsConfig
+)
+```
+
+### Graph Node Integration
+
+```typescript
+// In router or handler nodes
+async function routerNode(state: OrchestratorState) {
+    const config = langchainConfig.guardrails
+
+    // Check input before processing
+    if (config.promptInjection?.enabled) {
+        const check = guardrails.checkInjection(
+            state.messages[state.messages.length - 1].content,
+            config.promptInjection
+        )
+
+        if (!check.safe && config.promptInjection.action === 'block') {
+            return {
+                error: 'Your message was blocked for security reasons.',
+                intents: [],
+            }
+        }
+    }
+
+    // Continue with normal processing
+    // ...
+}
+```
+
+---
+
+## API Response Types
+
+### InjectionCheckResult
+
+```typescript
+interface InjectionCheckResult {
+    safe: boolean          // Whether input is safe
+    reason?: string        // Reason if blocked
+    pattern?: string       // Pattern that matched
+}
+```
+
+### PIIMaskResult
+
+```typescript
+interface PIIMaskResult {
+    masked: string         // Text with PII masked
+    mappings: Array<{
+        original: string   // Original PII value
+        masked: string     // Masked value
+        type: string       // PII type
+    }>
+    hasPII: boolean        // Whether PII was detected
+}
+```
+
+### ContentFilterResult
+
+```typescript
+interface ContentFilterResult {
+    filtered: string       // Filtered output
+    blocked: boolean       // Whether content was blocked
+    reason?: string        // Reason if blocked
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Defense in Depth
+
+Enable multiple layers:
+
+```typescript
+guardrails: {
+  promptInjection: { enabled: true, action: 'block' },
+  piiMasking: { enabled: true, action: 'mask' },
+  contentFilter: { enabled: true, action: 'redact' },
+}
+```
+
+### 2. Start Permissive, Tighten Gradually
+
+```typescript
+// Development: log only
+guardrails: {
+  promptInjection: { enabled: true, action: 'log' },
+}
+
+// Production: block
+guardrails: {
+  promptInjection: { enabled: true, action: 'block' },
+}
+```
+
+### 3. Monitor Warnings
+
+Log warnings for review:
+
+```typescript
+const { processed, warnings } = await guardrails.processInput(input, config)
+
+if (warnings.length > 0) {
+    await logger.warn('Guardrail warnings', {
+        userId: context.userId,
+        warnings,
+        inputPreview: input.slice(0, 100),
+    })
+}
+```
+
+### 4. Custom Patterns for Your Domain
+
+Add domain-specific patterns:
+
+```typescript
+// For a financial app
+customPatterns: [
+    /transfer\s+all\s+funds/i,
+    /send\s+money\s+to\s+\d+/i,
+]
+
+// For a customer service app
+customPatterns: [
+    /reveal\s+customer\s+data/i,
+    /show\s+all\s+users/i,
+]
+```
+
+### 5. Handle Blocked Requests Gracefully
+
+```typescript
+try {
+    const result = await guardrails.processInput(input, config)
+    // Process normally
+} catch (error) {
+    // User-friendly response
+    return {
+        success: false,
+        message: 'Your request could not be processed. Please rephrase.',
+        code: 'GUARDRAIL_BLOCK',
+    }
+}
+```
+
+---
+
+## Troubleshooting
+
+### False Positives
+
+If legitimate requests are being blocked:
+
+1. Check which pattern matched:
+   ```typescript
+   const result = guardrails.checkInjection(input, config)
+   console.log('Pattern:', result.pattern)
+   ```
+
+2. Adjust patterns or use `warn` action:
+   ```typescript
+   guardrails: {
+     promptInjection: { action: 'warn' }  // Log but don't block
+   }
+   ```
+
+### PII Not Detected
+
+If PII is not being masked:
+
+1. Ensure the type is enabled:
+   ```typescript
+   piiMasking: {
+     types: ['email', 'phone'],  // Add missing types
+   }
+   ```
+
+2. Check pattern matches your format:
+   ```typescript
+   // For international phone numbers, add custom pattern
+   // The built-in pattern is optimized for US formats
+   ```
+
+### Performance Impact
+
+Guardrails add minimal overhead:
+- Injection check: < 1ms (regex matching)
+- PII masking: < 5ms (depends on input length)
+- Content filtering: < 1ms
+
+For high-throughput scenarios, consider:
+- Sampling (process 10% of requests)
+- Caching results for identical inputs
+- Async logging with buffering
+
+---
+
+## Security Considerations
+
+### Pattern Limitations
+
+Regex-based detection has limitations:
+- May miss sophisticated injection attempts
+- Can be bypassed with encoding/obfuscation
+- Cannot understand semantic intent
+
+**Recommendation**: Combine with:
+- Input length limits
+- Rate limiting
+- User authentication
+- Logging and monitoring
+
+### PII Mapping Security
+
+The `mappings` array contains original PII values:
+
+```typescript
+const result = guardrails.maskPII(input, config)
+// result.mappings contains original values - handle securely!
+```
+
+**Do not**:
+- Log the mappings array
+- Store mappings in database
+- Return mappings to client
+
+### Content Filter Effectiveness
+
+Content filtering is a final safeguard, not a primary defense:
+- Configure model with appropriate system prompts
+- Use model-level content policies
+- Combine with output validation
+
+---
+
+## Related Documentation
+
+- [Graph Orchestrator](../03-orchestration/01-graph-orchestrator.md) - How guardrails integrate with the graph
+- [Observability](./01-observability.md) - Logging guardrail events
+- [Configuration](../01-getting-started/03-configuration.md) - Full configuration reference