@nextsparkjs/core 0.1.0-beta.2 → 0.1.0-beta.4

package/templates/contents/plugins/langchain/docs/04-advanced/04-guardrails.md

@@ -1,597 +0,0 @@
-# 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