family-ai-agent 1.0.0

package/src/safety/audit-logger.ts

@@ -0,0 +1,357 @@
+import { createHash } from 'crypto';
+import { query } from '../database/client.js';
+import { config } from '../config/index.js';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('AuditLogger');
+
+export interface AuditLogEntry {
+  id: string;
+  userId?: string;
+  agentId?: string;
+  actionType: string;
+  actionDetails: Record<string, unknown>;
+  inputHash?: string;
+  outputHash?: string;
+  status: 'success' | 'failure' | 'blocked';
+  errorMessage?: string;
+  executionTimeMs?: number;
+  createdAt: Date;
+}
+
+export type AuditActionType =
+  | 'user_input'
+  | 'agent_execution'
+  | 'tool_call'
+  | 'memory_access'
+  | 'document_upload'
+  | 'safety_block'
+  | 'error'
+  | 'handoff'
+  | 'api_request';
+
+export class AuditLogger {
+  private enabled: boolean;
+
+  constructor() {
+    this.enabled = config.ENABLE_AUDIT_LOGGING;
+  }
+
+  // Hash sensitive content for logging
+  private hashContent(content: string): string {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+  }
+
+  // Log an action
+  async log(
+    actionType: AuditActionType,
+    details: Record<string, unknown>,
+    options: {
+      userId?: string;
+      agentId?: string;
+      input?: string;
+      output?: string;
+      status?: 'success' | 'failure' | 'blocked';
+      error?: string;
+      executionTimeMs?: number;
+    } = {}
+  ): Promise<string | null> {
+    if (!this.enabled) {
+      return null;
+    }
+
+    try {
+      const result = await query<{ id: string }>(
+        `INSERT INTO audit_logs
+         (user_id, agent_id, action_type, action_details, input_hash, output_hash, status, error_message, execution_time_ms)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+         RETURNING id`,
+        [
+          options.userId ?? null,
+          options.agentId ?? null,
+          actionType,
+          JSON.stringify(details),
+          options.input ? this.hashContent(options.input) : null,
+          options.output ? this.hashContent(options.output) : null,
+          options.status ?? 'success',
+          options.error ?? null,
+          options.executionTimeMs ?? null,
+        ]
+      );
+
+      const logId = result.rows[0]?.id;
+      logger.debug('Audit log created', { logId, actionType });
+      return logId ?? null;
+    } catch (error) {
+      logger.error('Failed to create audit log', { error, actionType });
+      // Don't throw - audit logging should not break the main flow
+      return null;
+    }
+  }
+
+  // Log user input
+  async logUserInput(
+    input: string,
+    options: { userId?: string; metadata?: Record<string, unknown> } = {}
+  ): Promise<string | null> {
+    return this.log(
+      'user_input',
+      {
+        inputLength: input.length,
+        ...options.metadata,
+      },
+      {
+        userId: options.userId,
+        input,
+        status: 'success',
+      }
+    );
+  }
+
+  // Log agent execution
+  async logAgentExecution(
+    agentId: string,
+    input: string,
+    output: string,
+    executionTimeMs: number,
+    options: { userId?: string; success?: boolean; error?: string } = {}
+  ): Promise<string | null> {
+    return this.log(
+      'agent_execution',
+      {
+        inputLength: input.length,
+        outputLength: output.length,
+        executionTimeMs,
+      },
+      {
+        userId: options.userId,
+        agentId,
+        input,
+        output,
+        status: options.success !== false ? 'success' : 'failure',
+        error: options.error,
+        executionTimeMs,
+      }
+    );
+  }
+
+  // Log tool call
+  async logToolCall(
+    toolName: string,
+    input: unknown,
+    output: unknown,
+    options: {
+      agentId?: string;
+      userId?: string;
+      success?: boolean;
+      error?: string;
+      executionTimeMs?: number;
+    } = {}
+  ): Promise<string | null> {
+    return this.log(
+      'tool_call',
+      {
+        toolName,
+        inputType: typeof input,
+        outputType: typeof output,
+      },
+      {
+        agentId: options.agentId,
+        userId: options.userId,
+        input: JSON.stringify(input),
+        output: JSON.stringify(output),
+        status: options.success !== false ? 'success' : 'failure',
+        error: options.error,
+        executionTimeMs: options.executionTimeMs,
+      }
+    );
+  }
+
+  // Log safety block
+  async logSafetyBlock(
+    reason: string,
+    details: Record<string, unknown>,
+    options: { userId?: string; input?: string } = {}
+  ): Promise<string | null> {
+    return this.log(
+      'safety_block',
+      {
+        reason,
+        ...details,
+      },
+      {
+        userId: options.userId,
+        input: options.input,
+        status: 'blocked',
+        error: reason,
+      }
+    );
+  }
+
+  // Query audit logs
+  async query(
+    filters: {
+      userId?: string;
+      agentId?: string;
+      actionType?: AuditActionType;
+      status?: 'success' | 'failure' | 'blocked';
+      startDate?: Date;
+      endDate?: Date;
+    } = {},
+    options: { limit?: number; offset?: number } = {}
+  ): Promise<AuditLogEntry[]> {
+    const { limit = 50, offset = 0 } = options;
+
+    let sql = `
+      SELECT id, user_id, agent_id, action_type, action_details,
+             input_hash, output_hash, status, error_message,
+             execution_time_ms, created_at
+      FROM audit_logs
+      WHERE 1=1
+    `;
+    const params: unknown[] = [];
+    let paramIndex = 1;
+
+    if (filters.userId) {
+      sql += ` AND user_id = $${paramIndex}`;
+      params.push(filters.userId);
+      paramIndex++;
+    }
+
+    if (filters.agentId) {
+      sql += ` AND agent_id = $${paramIndex}`;
+      params.push(filters.agentId);
+      paramIndex++;
+    }
+
+    if (filters.actionType) {
+      sql += ` AND action_type = $${paramIndex}`;
+      params.push(filters.actionType);
+      paramIndex++;
+    }
+
+    if (filters.status) {
+      sql += ` AND status = $${paramIndex}`;
+      params.push(filters.status);
+      paramIndex++;
+    }
+
+    if (filters.startDate) {
+      sql += ` AND created_at >= $${paramIndex}`;
+      params.push(filters.startDate);
+      paramIndex++;
+    }
+
+    if (filters.endDate) {
+      sql += ` AND created_at <= $${paramIndex}`;
+      params.push(filters.endDate);
+      paramIndex++;
+    }
+
+    sql += ` ORDER BY created_at DESC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`;
+    params.push(limit, offset);
+
+    try {
+      const result = await query<{
+        id: string;
+        user_id: string | null;
+        agent_id: string | null;
+        action_type: string;
+        action_details: Record<string, unknown>;
+        input_hash: string | null;
+        output_hash: string | null;
+        status: 'success' | 'failure' | 'blocked';
+        error_message: string | null;
+        execution_time_ms: number | null;
+        created_at: Date;
+      }>(sql, params);
+
+      return result.rows.map((row) => ({
+        id: row.id,
+        userId: row.user_id ?? undefined,
+        agentId: row.agent_id ?? undefined,
+        actionType: row.action_type,
+        actionDetails: row.action_details,
+        inputHash: row.input_hash ?? undefined,
+        outputHash: row.output_hash ?? undefined,
+        status: row.status,
+        errorMessage: row.error_message ?? undefined,
+        executionTimeMs: row.execution_time_ms ?? undefined,
+        createdAt: row.created_at,
+      }));
+    } catch (error) {
+      logger.error('Failed to query audit logs', { error });
+      return [];
+    }
+  }
+
+  // Get statistics
+  async getStats(
+    userId?: string,
+    days: number = 7
+  ): Promise<{
+    totalRequests: number;
+    successRate: number;
+    avgExecutionTime: number;
+    blockedCount: number;
+  }> {
+    const startDate = new Date();
+    startDate.setDate(startDate.getDate() - days);
+
+    let sql = `
+      SELECT
+        COUNT(*) as total,
+        COUNT(*) FILTER (WHERE status = 'success') as success_count,
+        COUNT(*) FILTER (WHERE status = 'blocked') as blocked_count,
+        AVG(execution_time_ms) FILTER (WHERE execution_time_ms IS NOT NULL) as avg_time
+      FROM audit_logs
+      WHERE created_at >= $1
+    `;
+    const params: unknown[] = [startDate];
+
+    if (userId) {
+      sql += ' AND user_id = $2';
+      params.push(userId);
+    }
+
+    try {
+      const result = await query<{
+        total: string;
+        success_count: string;
+        blocked_count: string;
+        avg_time: string | null;
+      }>(sql, params);
+
+      const row = result.rows[0];
+      const total = parseInt(row?.total ?? '0', 10);
+      const successCount = parseInt(row?.success_count ?? '0', 10);
+
+      return {
+        totalRequests: total,
+        successRate: total > 0 ? (successCount / total) * 100 : 100,
+        avgExecutionTime: parseFloat(row?.avg_time ?? '0'),
+        blockedCount: parseInt(row?.blocked_count ?? '0', 10),
+      };
+    } catch (error) {
+      logger.error('Failed to get audit stats', { error });
+      return {
+        totalRequests: 0,
+        successRate: 100,
+        avgExecutionTime: 0,
+        blockedCount: 0,
+      };
+    }
+  }
+}
+
+// Singleton instance
+let auditInstance: AuditLogger | null = null;
+
+export function getAuditLogger(): AuditLogger {
+  if (!auditInstance) {
+    auditInstance = new AuditLogger();
+  }
+  return auditInstance;
+}
+
+export default AuditLogger;

package/src/safety/guardrails/input-guardrail.ts

@@ -0,0 +1,191 @@
+import { config } from '../../config/index.js';
+import { createLogger, logSafetyEvent } from '../../utils/logger.js';
+import { SafetyError, ValidationError } from '../../utils/errors.js';
+
+const logger = createLogger('InputGuardrail');
+
+export interface InputValidationResult {
+  valid: boolean;
+  sanitizedInput: string;
+  warnings: string[];
+  blockedReason?: string;
+}
+
+// Patterns that indicate potentially harmful content
+const HARMFUL_PATTERNS = [
+  // Injection attempts
+  /ignore\s+(previous|all)\s+instructions/i,
+  /disregard\s+(your|the)\s+(rules|guidelines)/i,
+  /you\s+are\s+now\s+(a|an)\s+different/i,
+  /pretend\s+you\s+(are|have)\s+no\s+restrictions/i,
+  /jailbreak/i,
+  /bypass\s+(safety|security|filters)/i,
+
+  // Dangerous requests
+  /how\s+to\s+(make|build|create)\s+(a\s+)?(bomb|weapon|explosive)/i,
+  /how\s+to\s+(hack|break\s+into)/i,
+  /how\s+to\s+harm\s+(myself|others|someone)/i,
+
+  // Personal information extraction
+  /give\s+me\s+(your|the)\s+(api|secret)\s+key/i,
+  /what\s+is\s+(your|the)\s+password/i,
+];
+
+// Patterns for PII detection
+const PII_PATTERNS = [
+  { name: 'SSN', pattern: /\b\d{3}-\d{2}-\d{4}\b/ },
+  { name: 'Credit Card', pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/ },
+  { name: 'Email', pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/ },
+  { name: 'Phone', pattern: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/ },
+];
+
+// Maximum input lengths
+const MAX_INPUT_LENGTH = 50000; // 50k characters
+const MAX_TOKENS_ESTIMATE = 12500; // Roughly 50k chars / 4
+
+export class InputGuardrail {
+  private enabled: boolean;
+  private enablePiiDetection: boolean;
+
+  constructor() {
+    this.enabled = config.ENABLE_CONTENT_FILTER;
+    this.enablePiiDetection = config.ENABLE_PII_DETECTION;
+  }
+
+  // Main validation method
+  async validate(input: string): Promise<InputValidationResult> {
+    const warnings: string[] = [];
+    let sanitizedInput = input;
+
+    // Check if guardrails are enabled
+    if (!this.enabled) {
+      return { valid: true, sanitizedInput, warnings };
+    }
+
+    // Length validation
+    if (input.length > MAX_INPUT_LENGTH) {
+      throw new ValidationError(
+        `Input exceeds maximum length of ${MAX_INPUT_LENGTH} characters`
+      );
+    }
+
+    // Empty input check
+    if (!input.trim()) {
+      throw new ValidationError('Input cannot be empty');
+    }
+
+    // Check for harmful patterns
+    for (const pattern of HARMFUL_PATTERNS) {
+      if (pattern.test(input)) {
+        logSafetyEvent('harmful_content_detected', true, 'Input matches harmful pattern');
+        throw new SafetyError(
+          'Your request contains content that violates safety guidelines'
+        );
+      }
+    }
+
+    // PII detection
+    if (this.enablePiiDetection) {
+      const piiResult = this.detectPii(input);
+      if (piiResult.detected) {
+        warnings.push(
+          `Potential PII detected: ${piiResult.types.join(', ')}. ` +
+          'Please be careful with personal information.'
+        );
+        logSafetyEvent('pii_detected', false, 'PII detected in input', {
+          types: piiResult.types,
+        });
+      }
+    }
+
+    // Sanitize input
+    sanitizedInput = this.sanitize(input);
+
+    return {
+      valid: true,
+      sanitizedInput,
+      warnings,
+    };
+  }
+
+  // Detect PII in input
+  private detectPii(input: string): { detected: boolean; types: string[] } {
+    const detectedTypes: string[] = [];
+
+    for (const { name, pattern } of PII_PATTERNS) {
+      if (pattern.test(input)) {
+        detectedTypes.push(name);
+      }
+    }
+
+    return {
+      detected: detectedTypes.length > 0,
+      types: detectedTypes,
+    };
+  }
+
+  // Sanitize input
+  private sanitize(input: string): string {
+    let sanitized = input;
+
+    // Remove null bytes
+    sanitized = sanitized.replace(/\0/g, '');
+
+    // Normalize unicode
+    sanitized = sanitized.normalize('NFC');
+
+    // Remove control characters (except newlines and tabs)
+    sanitized = sanitized.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+
+    // Trim excessive whitespace
+    sanitized = sanitized.replace(/\s{10,}/g, '          ');
+
+    return sanitized.trim();
+  }
+
+  // Quick check for obviously harmful content
+  isObviouslyHarmful(input: string): boolean {
+    const lowerInput = input.toLowerCase();
+
+    const obviousPatterns = [
+      'ignore previous instructions',
+      'ignore all instructions',
+      'you are now',
+      'pretend you have no',
+      'jailbreak',
+      'bypass safety',
+    ];
+
+    return obviousPatterns.some((pattern) => lowerInput.includes(pattern));
+  }
+
+  // Estimate token count
+  estimateTokens(input: string): number {
+    // Rough estimate: 1 token ≈ 4 characters
+    return Math.ceil(input.length / 4);
+  }
+
+  // Check if input is within token limits
+  isWithinTokenLimit(input: string, maxTokens?: number): boolean {
+    const limit = maxTokens ?? config.MAX_TOKENS_PER_REQUEST;
+    return this.estimateTokens(input) <= limit;
+  }
+}
+
+// Singleton instance
+let guardrailInstance: InputGuardrail | null = null;
+
+export function getInputGuardrail(): InputGuardrail {
+  if (!guardrailInstance) {
+    guardrailInstance = new InputGuardrail();
+  }
+  return guardrailInstance;
+}
+
+// Convenience function
+export async function validateInput(input: string): Promise<InputValidationResult> {
+  const guardrail = getInputGuardrail();
+  return guardrail.validate(input);
+}
+
+export default InputGuardrail;

package/src/safety/guardrails/output-guardrail.ts

@@ -0,0 +1,160 @@
+import { config } from '../../config/index.js';
+import { createLogger, logSafetyEvent } from '../../utils/logger.js';
+
+const logger = createLogger('OutputGuardrail');
+
+export interface OutputValidationResult {
+  valid: boolean;
+  sanitizedOutput: string;
+  warnings: string[];
+  redactions: string[];
+}
+
+// Patterns for sensitive information in outputs
+const SENSITIVE_PATTERNS = [
+  // API keys and tokens
+  { name: 'API Key', pattern: /\b(sk|pk|api[_-]?key)[_-]?[a-zA-Z0-9]{20,}\b/gi },
+  { name: 'Bearer Token', pattern: /bearer\s+[a-zA-Z0-9_-]{20,}/gi },
+  { name: 'JWT', pattern: /eyJ[a-zA-Z0-9_-]*\.eyJ[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*/g },
+
+  // Credentials
+  { name: 'Password Field', pattern: /password['":\s]*['"]?[^'"\s,]{8,}['"]?/gi },
+  { name: 'Secret', pattern: /secret['":\s]*['"]?[a-zA-Z0-9_-]{16,}['"]?/gi },
+
+  // Personal Information
+  { name: 'SSN', pattern: /\b\d{3}-\d{2}-\d{4}\b/g },
+  { name: 'Credit Card', pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g },
+
+  // Private keys
+  { name: 'Private Key', pattern: /-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA\s+)?PRIVATE\s+KEY-----/g },
+];
+
+// Harmful content patterns in output
+const HARMFUL_OUTPUT_PATTERNS = [
+  /how\s+to\s+(make|build|create)\s+(a\s+)?(bomb|weapon|explosive)/i,
+  /instructions\s+for\s+(making|building)\s+(a\s+)?weapon/i,
+  /step[\s-]by[\s-]step\s+guide\s+to\s+harm/i,
+];
+
+export class OutputGuardrail {
+  private enabled: boolean;
+
+  constructor() {
+    this.enabled = config.ENABLE_CONTENT_FILTER;
+  }
+
+  // Main validation method
+  validate(output: string): OutputValidationResult {
+    const warnings: string[] = [];
+    const redactions: string[] = [];
+    let sanitizedOutput = output;
+
+    if (!this.enabled) {
+      return { valid: true, sanitizedOutput, warnings, redactions };
+    }
+
+    // Check for harmful content
+    for (const pattern of HARMFUL_OUTPUT_PATTERNS) {
+      if (pattern.test(output)) {
+        logSafetyEvent('harmful_output_blocked', true, 'Output contains harmful content');
+        return {
+          valid: false,
+          sanitizedOutput: '[Content blocked due to safety guidelines]',
+          warnings: ['Output contained potentially harmful content'],
+          redactions: [],
+        };
+      }
+    }
+
+    // Redact sensitive information
+    for (const { name, pattern } of SENSITIVE_PATTERNS) {
+      const matches = output.match(pattern);
+      if (matches) {
+        for (const match of matches) {
+          sanitizedOutput = sanitizedOutput.replace(match, `[REDACTED: ${name}]`);
+          redactions.push(name);
+        }
+      }
+    }
+
+    if (redactions.length > 0) {
+      logSafetyEvent('sensitive_data_redacted', false, 'Sensitive data redacted from output', {
+        redactionTypes: [...new Set(redactions)],
+      });
+      warnings.push(
+        `Sensitive information was redacted from the output: ${[...new Set(redactions)].join(', ')}`
+      );
+    }
+
+    return {
+      valid: true,
+      sanitizedOutput,
+      warnings,
+      redactions: [...new Set(redactions)],
+    };
+  }
+
+  // Check if output contains code that might be dangerous
+  containsDangerousCode(output: string): boolean {
+    const dangerousPatterns = [
+      // Shell commands that could be harmful
+      /rm\s+-rf\s+\//,
+      /mkfs\./,
+      /dd\s+if=.*of=\/dev/,
+      /:(){ :|:& };:/,  // Fork bomb
+
+      // Dangerous SQL
+      /drop\s+table/i,
+      /delete\s+from\s+.*where\s+1\s*=\s*1/i,
+      /truncate\s+table/i,
+
+      // Dangerous code patterns
+      /eval\s*\(\s*['"`].*['"`]\s*\)/,
+      /exec\s*\(\s*['"`].*['"`]\s*\)/,
+    ];
+
+    return dangerousPatterns.some((pattern) => pattern.test(output));
+  }
+
+  // Truncate output if too long
+  truncate(output: string, maxLength: number = 10000): string {
+    if (output.length <= maxLength) {
+      return output;
+    }
+
+    const truncated = output.slice(0, maxLength);
+    const lastNewline = truncated.lastIndexOf('\n');
+
+    // Try to truncate at a natural break point
+    if (lastNewline > maxLength * 0.8) {
+      return truncated.slice(0, lastNewline) + '\n\n[Output truncated...]';
+    }
+
+    return truncated + '\n\n[Output truncated...]';
+  }
+
+  // Format code blocks safely
+  formatCodeSafely(code: string, language: string = ''): string {
+    // Escape any existing code fence markers
+    const escapedCode = code.replace(/```/g, '\\`\\`\\`');
+    return `\`\`\`${language}\n${escapedCode}\n\`\`\``;
+  }
+}
+
+// Singleton instance
+let guardrailInstance: OutputGuardrail | null = null;
+
+export function getOutputGuardrail(): OutputGuardrail {
+  if (!guardrailInstance) {
+    guardrailInstance = new OutputGuardrail();
+  }
+  return guardrailInstance;
+}
+
+// Convenience function
+export function validateOutput(output: string): OutputValidationResult {
+  const guardrail = getOutputGuardrail();
+  return guardrail.validate(output);
+}
+
+export default OutputGuardrail;