@od-oneapp/ai-platform 0.1.0

package/src/security/guardrails/pii-filter.ts

@@ -0,0 +1,396 @@
+/**
+ * PII (Personally Identifiable Information) filtering
+ */
+
+import { logWarn } from '@repo/shared/logs';
+
+import { GuardrailViolationError } from '../types';
+
+import type { PIIFilterConfig, PIIType } from '../types';
+
+/**
+ * PII detection patterns
+ */
+const PII_PATTERNS: Record<PIIType, RegExp | null> = {
+  email: null,
+  phone: null,
+  ssn: /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/g,
+  credit_card: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
+  name: /\b[A-Z][a-z]+\s+[A-Z][a-z]+\b/g, // Simple name pattern
+  address:
+    /\b\d+\s+[A-Za-z]+\s+(?:Street|St|Avenue|Ave|Road|Rd|Boulevard|Blvd|Lane|Ln|Drive|Dr)\b/gi,
+};
+
+const SUPPORTED_PII_TYPES: ReadonlyArray<PIIType> = Object.keys(PII_PATTERNS) as PIIType[];
+
+const EMAIL_TOKEN_START_TRIM = new Set(['(', '[', '{', '<', '"', "'"]);
+const EMAIL_TOKEN_END_TRIM = new Set([')', ']', '}', '>', '.', ',', ';', ':', '!', '?', '"', "'"]);
+
+const isAlphaNumeric = (char: string): boolean => {
+  const code = char.charCodeAt(0);
+  return (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+};
+
+const isDigit = (char: string): boolean => {
+  const code = char.charCodeAt(0);
+  return code >= 48 && code <= 57;
+};
+
+const isEmailLocalChar = (char: string): boolean =>
+  isAlphaNumeric(char) ||
+  char === '.' ||
+  char === '_' ||
+  char === '%' ||
+  char === '+' ||
+  char === '-';
+
+const isEmailDomainChar = (char: string): boolean =>
+  isAlphaNumeric(char) || char === '.' || char === '-';
+
+const trimEmailToken = (token: string): { value: string; offset: number } => {
+  let start = 0;
+  let end = token.length;
+
+  while (start < end) {
+    const char = token[start];
+    if (!char || !EMAIL_TOKEN_START_TRIM.has(char)) break;
+    start += 1;
+  }
+
+  while (end > start) {
+    const char = token[end - 1];
+    if (!char || !EMAIL_TOKEN_END_TRIM.has(char)) break;
+    end -= 1;
+  }
+
+  return { value: token.slice(start, end), offset: start };
+};
+
+const isValidEmailCandidate = (candidate: string): boolean => {
+  if (candidate.length > 320) return false;
+
+  const atIndex = candidate.indexOf('@');
+  if (atIndex <= 0 || atIndex !== candidate.lastIndexOf('@')) return false;
+
+  const local = candidate.slice(0, atIndex);
+  const domain = candidate.slice(atIndex + 1);
+
+  if (local.length === 0 || local.length > 64) return false;
+  if (domain.length === 0 || domain.length > 255) return false;
+  if (!domain.includes('.')) return false;
+  if (local.startsWith('.') || local.endsWith('.')) return false;
+  if (domain.startsWith('.') || domain.endsWith('.')) return false;
+  if (local.includes('..') || domain.includes('..')) return false;
+
+  for (const char of local) {
+    if (!isEmailLocalChar(char)) return false;
+  }
+
+  for (const char of domain) {
+    if (!isEmailDomainChar(char)) return false;
+  }
+
+  const labels = domain.split('.');
+  if (labels.some(label => label.length === 0)) return false;
+
+  return true;
+};
+
+const findEmailMatches = (text: string): Array<{ value: string; index: number }> => {
+  const matches: Array<{ value: string; index: number }> = [];
+  const seen = new Set<string>();
+  let searchIndex = 0;
+
+  while (searchIndex < text.length) {
+    const atIndex = text.indexOf('@', searchIndex);
+    if (atIndex === -1) break;
+
+    let start = atIndex - 1;
+    while (start >= 0 && isEmailLocalChar(text[start] ?? '')) {
+      start -= 1;
+    }
+    start += 1;
+
+    let end = atIndex + 1;
+    while (end < text.length && isEmailDomainChar(text[end] ?? '')) {
+      end += 1;
+    }
+
+    const candidate = text.slice(start, end);
+    if (isValidEmailCandidate(candidate)) {
+      const key = `${start}:${candidate}`;
+      if (!seen.has(key)) {
+        matches.push({ value: candidate, index: start });
+        seen.add(key);
+      }
+    } else {
+      const trimmed = trimEmailToken(candidate);
+      if (trimmed.value && isValidEmailCandidate(trimmed.value)) {
+        const key = `${start + trimmed.offset}:${trimmed.value}`;
+        if (!seen.has(key)) {
+          matches.push({ value: trimmed.value, index: start + trimmed.offset });
+          seen.add(key);
+        }
+      }
+    }
+
+    searchIndex = atIndex + 1;
+  }
+
+  return matches;
+};
+
+const maskValue = (value: string): string => {
+  if (value.length <= 4) return '****';
+  return value.slice(0, 2) + '*'.repeat(value.length - 4) + value.slice(-2);
+};
+
+const maskEmail = (text: string): string => {
+  const matches = findEmailMatches(text);
+  if (matches.length === 0) return text;
+
+  const ordered = [...matches].sort((a, b) => b.index - a.index);
+  let result = text;
+
+  for (const match of ordered) {
+    const masked = maskValue(match.value);
+    result = result.slice(0, match.index) + masked + result.slice(match.index + match.value.length);
+  }
+
+  return result;
+};
+
+const isPhoneChar = (char: string): boolean =>
+  isDigit(char) ||
+  char === '+' ||
+  char === '-' ||
+  char === '.' ||
+  char === ' ' ||
+  char === '(' ||
+  char === ')';
+
+const extractDigits = (value: string): string => {
+  let digits = '';
+  for (const char of value) {
+    if (isDigit(char)) {
+      digits += char;
+    }
+  }
+  return digits;
+};
+
+const isValidPhoneCandidate = (candidate: string): boolean => {
+  const digits = extractDigits(candidate);
+  if (digits.length === 10) return true;
+  if (digits.length === 11 && digits.startsWith('1')) return true;
+  return false;
+};
+
+const findPhoneMatches = (text: string): Array<{ value: string; index: number }> => {
+  const matches: Array<{ value: string; index: number }> = [];
+  let index = 0;
+
+  while (index < text.length) {
+    const char = text[index];
+    if (!char || (!isDigit(char) && char !== '+')) {
+      index += 1;
+      continue;
+    }
+
+    const prevChar = index > 0 ? text[index - 1] : undefined;
+    if (prevChar && isAlphaNumeric(prevChar)) {
+      index += 1;
+      continue;
+    }
+
+    let startIndex = index;
+    if (prevChar === '(') {
+      startIndex = index - 1;
+    }
+
+    let end = index + 1;
+    while (end < text.length) {
+      const next = text[end];
+      if (!next || !isPhoneChar(next)) break;
+      end += 1;
+    }
+
+    let trimmedEnd = end;
+    while (trimmedEnd > startIndex) {
+      const trailing = text[trimmedEnd - 1];
+      if (
+        trailing === ' ' ||
+        trailing === '.' ||
+        trailing === ',' ||
+        trailing === ';' ||
+        trailing === ':'
+      ) {
+        trimmedEnd -= 1;
+        continue;
+      }
+      break;
+    }
+
+    const nextChar = trimmedEnd < text.length ? text[trimmedEnd] : undefined;
+    if (nextChar && isAlphaNumeric(nextChar)) {
+      index = end;
+      continue;
+    }
+
+    const candidate = text.slice(startIndex, trimmedEnd);
+    if (isValidPhoneCandidate(candidate)) {
+      matches.push({ value: candidate, index: startIndex });
+    }
+
+    index = end;
+  }
+
+  return matches;
+};
+
+const maskPhone = (text: string): string => {
+  const matches = findPhoneMatches(text);
+  if (matches.length === 0) return text;
+
+  const ordered = [...matches].sort((a, b) => b.index - a.index);
+  let result = text;
+
+  for (const match of ordered) {
+    const masked = maskValue(match.value);
+    result = result.slice(0, match.index) + masked + result.slice(match.index + match.value.length);
+  }
+
+  return result;
+};
+
+/**
+ * PII detection result
+ */
+export interface PIIDetectionResult {
+  found: boolean;
+  matches: Array<{
+    type: PIIType;
+    value: string;
+    index: number;
+  }>;
+}
+
+/**
+ * Detect PII in text
+ */
+export function detectPII(
+  text: string,
+  types: PIIType[] = Object.keys(PII_PATTERNS) as PIIType[],
+): PIIDetectionResult {
+  const matches: PIIDetectionResult['matches'] = [];
+
+  for (const type of types) {
+    if (type === 'email') {
+      for (const match of findEmailMatches(text)) {
+        matches.push({
+          type,
+          value: match.value,
+          index: match.index,
+        });
+      }
+      continue;
+    }
+
+    if (type === 'phone') {
+      for (const match of findPhoneMatches(text)) {
+        matches.push({
+          type,
+          value: match.value,
+          index: match.index,
+        });
+      }
+      continue;
+    }
+
+    const pattern = PII_PATTERNS[type];
+    if (!pattern) continue;
+
+    // Reset lastIndex for global patterns
+    pattern.lastIndex = 0;
+
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      matches.push({
+        type,
+        value: match[0],
+        index: match.index,
+      });
+    }
+  }
+
+  return {
+    found: matches.length > 0,
+    matches,
+  };
+}
+
+/**
+ * Mask PII in text
+ */
+export function maskPII(text: string, types: PIIType[] = [...SUPPORTED_PII_TYPES]): string {
+  let masked = text;
+
+  for (const type of types) {
+    if (type === 'email') {
+      masked = maskEmail(masked);
+      continue;
+    }
+
+    if (type === 'phone') {
+      masked = maskPhone(masked);
+      continue;
+    }
+
+    const pattern = PII_PATTERNS[type];
+    if (!pattern) continue;
+
+    masked = masked.replace(pattern, match => {
+      // Preserve some characters for context
+      return maskValue(match);
+    });
+  }
+
+  return masked;
+}
+
+/**
+ * Create PII filter middleware
+ */
+export function createPIIFilter(config: PIIFilterConfig) {
+  return {
+    filter: (text: string): string => {
+      const result = detectPII(text, config.types);
+
+      if (!result.found) return text;
+
+      switch (config.action) {
+        case 'block':
+          throw new GuardrailViolationError(
+            `PII detected: ${result.matches.map(m => m.type).join(', ')}`,
+            'pii',
+            {
+              matches: result.matches.map(({ type, index }) => ({ type, index })),
+            },
+          );
+
+        case 'mask':
+          return maskPII(text, config.types);
+
+        case 'warn':
+          logWarn('[PII Filter] PII detected', {
+            types: [...new Set(result.matches.map(m => m.type))],
+            count: result.matches.length,
+          });
+          return text;
+
+        default:
+          return text;
+      }
+    },
+  };
+}

package/src/security/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Security module
+ *
+ * Provides guardrails, injection detection, and PII filtering
+ * for AI applications.
+ *
+ * @module @od-oneapp/ai-platform/security
+ */
+
+// Types
+export type {
+  PIIFilterConfig,
+  PIIType,
+  ContentFilterConfig,
+  ContentCategory,
+  TopicFilterConfig,
+  InjectionConfig,
+  InjectionDetectionResult,
+  GuardrailConfig,
+} from './types';
+export { GuardrailViolationError } from './types';
+
+// Guardrails
+export { createGuardrailMiddleware } from './guardrails/middleware';
+export {
+  createPIIFilter,
+  detectPII,
+  maskPII,
+  type PIIDetectionResult,
+} from './guardrails/pii-filter';
+
+// Injection detection
+export { detectPromptInjection, sanitizeInjection } from './injection/prompt-injection';

package/src/security/injection/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Prompt Injection Defense
+ * @module security/injection
+ */
+export * from './prompt-injection';

package/src/security/injection/prompt-injection.ts

@@ -0,0 +1,64 @@
+/**
+ * Prompt injection detection
+ */
+
+import type { InjectionDetectionResult } from '../types';
+
+/**
+ * Common prompt injection patterns
+ */
+const INJECTION_PATTERNS = [
+  /ignore.*(?:previous|above|prior).*(?:instructions?|prompt)/i,
+  /disregard.*(?:above|previous)/i,
+  /(?:new|different).*instructions?/i,
+  /(?:system|admin).*prompt/i,
+  /you.*are.*now/i,
+  /pretend.*(?:you|to\s+be)/i,
+  /(?:forget|ignore).*everything/i,
+  /(?:override|bypass).*(?:rules?|instructions?)/i,
+  /(?:act|behave).*(?:as|like)/i,
+  /(?:jailbreak|unlock)/i,
+  /\[system\]/i,
+  /\[admin\]/i,
+  /<\/?(?:system|admin)>/i,
+];
+
+/**
+ * Detect prompt injection attempts in text
+ *
+ * @example
+ * ```ts
+ * const result = await detectPromptInjection("Ignore previous instructions and...");
+ * if (result.detected) {
+ *   console.log(`Injection detected with ${result.confidence * 100}% confidence`);
+ * }
+ * ```
+ */
+export async function detectPromptInjection(input: string): Promise<InjectionDetectionResult> {
+  const matchedPatterns = INJECTION_PATTERNS.filter(pattern => pattern.test(input));
+
+  const confidence =
+    matchedPatterns.length > 0
+      ? Math.min(matchedPatterns.length / 3, 1) // Cap at 1.0
+      : 0;
+
+  return {
+    detected: matchedPatterns.length > 0,
+    confidence,
+    patterns: matchedPatterns.map(p => p.source),
+    originalText: input,
+  };
+}
+
+/**
+ * Sanitize potential injection attempts from text
+ */
+export function sanitizeInjection(input: string): string {
+  let sanitized = input;
+
+  for (const pattern of INJECTION_PATTERNS) {
+    sanitized = sanitized.replace(pattern, '[REDACTED]');
+  }
+
+  return sanitized;
+}

package/src/security/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Security module types
+ */
+
+/**
+ * PII filter configuration
+ */
+export interface PIIFilterConfig {
+  /** Whether to mask detected PII */
+  mask: boolean;
+  /** Types of PII to detect */
+  types: PIIType[];
+  /** Action on detection */
+  action: 'mask' | 'block' | 'warn';
+}
+
+export type PIIType = 'email' | 'phone' | 'ssn' | 'credit_card' | 'name' | 'address';
+
+/**
+ * Content filter configuration
+ */
+export interface ContentFilterConfig {
+  /** Categories to filter */
+  categories: ContentCategory[];
+  /** Threshold for blocking (0-1) */
+  threshold: number;
+}
+
+export type ContentCategory = 'hate' | 'violence' | 'sexual' | 'self_harm' | 'illegal';
+
+/**
+ * Topic filter configuration
+ */
+export interface TopicFilterConfig {
+  /** Topics to block */
+  blockedTopics: string[];
+  /** Topics to allow (whitelist mode) */
+  allowedTopics?: string[];
+}
+
+/**
+ * Injection detection configuration
+ */
+export interface InjectionConfig {
+  /** Enable prompt injection detection */
+  enabled: boolean;
+  /** Confidence threshold for blocking */
+  threshold: number;
+  /** Action on detection */
+  action: 'block' | 'warn' | 'sanitize';
+}
+
+/**
+ * Injection detection result
+ */
+export interface InjectionDetectionResult {
+  detected: boolean;
+  confidence: number;
+  patterns: string[];
+  originalText: string;
+}
+
+/**
+ * Guardrail configuration
+ */
+export interface GuardrailConfig {
+  pii?: PIIFilterConfig;
+  content?: ContentFilterConfig;
+  topics?: TopicFilterConfig;
+  injection?: InjectionConfig;
+}
+
+/**
+ * Guardrail violation error
+ */
+export class GuardrailViolationError extends Error {
+  constructor(
+    message: string,
+    public readonly type: 'pii' | 'content' | 'topic' | 'injection',
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'GuardrailViolationError';
+  }
+}

package/src/server/cache/crypto.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Cryptographic helper functions for audit logging and data integrity
+ * Provides hashing and signature generation for security-critical operations
+ */
+
+import { createHash, createHmac } from 'node:crypto';
+
+/**
+ * Generate a hash of the input data using SHA-256
+ * @param input - Data to hash (string or object)
+ * @returns Hex-encoded hash
+ */
+export function hashInput(input: string | Record<string, unknown>): string {
+  const data = typeof input === 'string' ? input : JSON.stringify(input);
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Generate an HMAC signature for the input data
+ * @param input - Data to sign
+ * @param secret - Secret key for HMAC (defaults to env var or empty string)
+ * @returns Hex-encoded HMAC signature
+ */
+export function generateSignature(
+  input: string | Record<string, unknown>,
+  secret?: string,
+): string {
+  const data = typeof input === 'string' ? input : JSON.stringify(input);
+  const key = secret || process.env.AUDIT_SECRET_KEY || '';
+  return createHmac('sha256', key).update(data).digest('hex');
+}
+
+/**
+ * Verify an HMAC signature
+ * @param input - Original data that was signed
+ * @param signature - Signature to verify
+ * @param secret - Secret key for HMAC (defaults to env var or empty string)
+ * @returns True if signature is valid
+ */
+export function verifySignature(
+  input: string | Record<string, unknown>,
+  signature: string,
+  secret?: string,
+): boolean {
+  const expected = generateSignature(input, secret);
+  return expected === signature;
+}

package/src/server/cache/performance.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Performance optimization helper functions
+ * Provides caching for expensive operations like PHI detection
+ */
+
+import { hashInput } from './crypto';
+
+/**
+ * In-memory cache for detection results
+ * In production, consider using Redis or another distributed cache
+ */
+const detectionCache = new Map<string, unknown>();
+
+/**
+ * Cache detection results for a given input
+ * @param input - Input data that was analyzed
+ * @param result - Detection results to cache
+ * @param ttl - Time to live in milliseconds (default: 1 hour)
+ */
+export function cacheDetections<T>(
+  input: string | Record<string, unknown>,
+  result: T,
+  ttl: number = 3600000,
+): void {
+  const key = hashInput(input);
+  detectionCache.set(key, {
+    result,
+    timestamp: Date.now(),
+    ttl,
+  });
+
+  // Auto-cleanup expired entries
+  setTimeout(() => {
+    detectionCache.delete(key);
+  }, ttl);
+}
+
+/**
+ * Get cached detection results for a given input
+ * @param input - Input data to look up
+ * @returns Cached results if available and not expired, otherwise undefined
+ */
+export function getCachedDetections<T>(input: string | Record<string, unknown>): T | undefined {
+  const key = hashInput(input);
+  const cached = detectionCache.get(key);
+
+  if (!cached) {
+    return undefined;
+  }
+
+  const entry = cached as { result: T; timestamp: number; ttl: number };
+  const isExpired = Date.now() - entry.timestamp > entry.ttl;
+
+  if (isExpired) {
+    detectionCache.delete(key);
+    return undefined;
+  }
+
+  return entry.result;
+}
+
+/**
+ * Clear all cached detections
+ * Useful for testing or memory management
+ */
+export function clearDetectionCache(): void {
+  detectionCache.clear();
+}
+
+/**
+ * Get cache statistics
+ * @returns Object with cache size and entries
+ */
+export function getCacheStats() {
+  return {
+    size: detectionCache.size,
+    keys: Array.from(detectionCache.keys()),
+  };
+}