@yan162/changewayguard 6.8.25

package/gateway/src/restorer.ts

@@ -0,0 +1,322 @@
+/**
+ * AI Security Gateway - Content Restorer
+ *
+ * Restores sanitized placeholders back to original values.
+ * Handles LLM corruption patterns (missing underscores, case variations).
+ *
+ * Placeholder format: __PII_<ENTITY_TYPE>_<SERIAL_ID>__
+ */
+
+import type { MappingTable } from "./types.js";
+
+/**
+ * Build a map from placeholder patterns to original values
+ * Handles variations that LLMs might produce
+ */
+function buildRestorationMap(mappingTable: MappingTable): Map<RegExp, string> {
+  const restorationMap = new Map<RegExp, string>();
+
+  for (const [placeholder, originalValue] of mappingTable.entries()) {
+    // Extract the core pattern from placeholder like __PII_EMAIL_ADDRESS_00000001__
+    const match = placeholder.match(/^__PII_([A-Z_]+)_(\d+)__$/);
+    if (!match) {
+      // Fallback: exact match only
+      restorationMap.set(new RegExp(escapeRegex(placeholder), "g"), originalValue);
+      continue;
+    }
+
+    const entityType = match[1];
+    const serialId = match[2];
+
+    // Create flexible pattern that handles LLM corruption:
+    // - Missing leading/trailing underscores
+    // - Case variations
+    // - Extra spaces
+    const flexiblePattern = new RegExp(
+      `_?_?PII[_\\s]*${entityType}[_\\s]*${serialId}_?_?`,
+      "gi"
+    );
+
+    restorationMap.set(flexiblePattern, originalValue);
+  }
+
+  return restorationMap;
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Restore placeholders in a string
+ */
+function restoreText(text: string, mappingTable: MappingTable): string {
+  if (mappingTable.size === 0) return text;
+
+  let restored = text;
+
+  // First pass: exact matches (fastest)
+  for (const [placeholder, originalValue] of mappingTable.entries()) {
+    if (restored.includes(placeholder)) {
+      restored = restored.split(placeholder).join(originalValue);
+    }
+  }
+
+  // Second pass: flexible patterns for LLM corruption
+  const restorationMap = buildRestorationMap(mappingTable);
+  for (const [pattern, originalValue] of restorationMap.entries()) {
+    restored = restored.replace(pattern, originalValue);
+  }
+
+  // Third pass: handle "leaked ID suffix" pattern
+  // LLM might output: "original_value_00000001" instead of just "original_value"
+  for (const [placeholder, originalValue] of mappingTable.entries()) {
+    const match = placeholder.match(/^__PII_[A-Z_]+_(\d+)__$/);
+    if (match) {
+      const serialId = match[1];
+      // Pattern: original value followed by underscore and serial ID
+      const leakedPattern = new RegExp(
+        escapeRegex(originalValue) + `[_\\s]*${serialId}`,
+        "g"
+      );
+      restored = restored.replace(leakedPattern, originalValue);
+    }
+  }
+
+  return restored;
+}
+
+/**
+ * Recursively restore any value (string, object, array)
+ */
+function restoreValue(value: unknown, mappingTable: MappingTable): unknown {
+  if (typeof value === "string") {
+    return restoreText(value, mappingTable);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => restoreValue(item, mappingTable));
+  }
+
+  if (value !== null && typeof value === "object") {
+    const restored: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      restored[key] = restoreValue(val, mappingTable);
+    }
+    return restored;
+  }
+
+  return value;
+}
+
+/**
+ * Restore any content (object, array, string) using the mapping table
+ */
+export function restore(content: unknown, mappingTable: MappingTable): unknown {
+  if (mappingTable.size === 0) return content;
+  return restoreValue(content, mappingTable);
+}
+
+/**
+ * Restore a JSON string
+ * Useful for SSE streaming where each chunk is a JSON string
+ */
+export function restoreJSON(jsonString: string, mappingTable: MappingTable): string {
+  if (mappingTable.size === 0) return jsonString;
+
+  try {
+    const parsed = JSON.parse(jsonString);
+    const restored = restore(parsed, mappingTable);
+    return JSON.stringify(restored);
+  } catch {
+    // If not valid JSON, treat as plain text
+    return restoreText(jsonString, mappingTable);
+  }
+}
+
+/**
+ * Restore SSE data line (for streaming responses)
+ * Format: "data: {...}\n"
+ */
+export function restoreSSELine(line: string, mappingTable: MappingTable): string {
+  if (mappingTable.size === 0) return line;
+  if (!line.startsWith("data: ")) return line;
+
+  const dataContent = line.slice(6); // Remove "data: " prefix
+  if (dataContent === "[DONE]") return line;
+
+  try {
+    const parsed = JSON.parse(dataContent);
+    const restored = restore(parsed, mappingTable);
+    return `data: ${JSON.stringify(restored)}`;
+  } catch {
+    // Fallback to text restoration
+    return `data: ${restoreText(dataContent, mappingTable)}`;
+  }
+}
+
+// =============================================================================
+// Streaming Restoration with Smart Buffering
+// =============================================================================
+
+// Max placeholder length: __PII_VERIFICATION_CODE_00000001__ ≈ 40 chars
+const MAX_PLACEHOLDER_LENGTH = 50;
+
+// Pattern to match complete placeholders
+const PLACEHOLDER_PATTERN = /__PII_[A-Z_]+_\d{8}__/g;
+
+/**
+ * StreamRestorer - Stateful streaming restoration with smart buffering
+ *
+ * Only buffers when `__` is detected (potential placeholder start).
+ * Otherwise streams through immediately for best UX.
+ */
+export class StreamRestorer {
+  private buffer: string = "";
+  private mappingTable: MappingTable;
+
+  constructor(mappingTable: MappingTable) {
+    this.mappingTable = mappingTable;
+  }
+
+  /**
+   * Process incoming text chunk
+   * Returns text that can be safely output (already restored or confirmed non-placeholder)
+   */
+  process(chunk: string): string {
+    // If no mappings, pass through directly
+    if (this.mappingTable.size === 0) {
+      return chunk;
+    }
+
+    this.buffer += chunk;
+    return this.flush();
+  }
+
+  /**
+   * Flush what we can safely output
+   * Keeps potential incomplete placeholders in buffer
+   */
+  private flush(): string {
+    let output = "";
+
+    while (this.buffer.length > 0) {
+      // Find position of `__` in buffer
+      const underscorePos = this.buffer.indexOf("__");
+
+      if (underscorePos === -1) {
+        // No `__` found - check if buffer ends with single `_`
+        if (this.buffer.endsWith("_")) {
+          // Keep the trailing `_` in case next chunk starts with `_`
+          output += this.buffer.slice(0, -1);
+          this.buffer = "_";
+        } else {
+          // Safe to output entire buffer
+          output += this.buffer;
+          this.buffer = "";
+        }
+        break;
+      }
+
+      // Output everything before the `__`
+      if (underscorePos > 0) {
+        output += this.buffer.slice(0, underscorePos);
+        this.buffer = this.buffer.slice(underscorePos);
+      }
+
+      // Now buffer starts with `__`
+      // Check if we have a complete placeholder
+      PLACEHOLDER_PATTERN.lastIndex = 0;
+      const match = PLACEHOLDER_PATTERN.exec(this.buffer);
+
+      if (match && match.index === 0) {
+        // Found complete placeholder at start of buffer
+        const placeholder = match[0];
+        const original = this.mappingTable.get(placeholder);
+
+        if (original) {
+          // Restore and output
+          output += original;
+        } else {
+          // Not in mapping table, output as-is
+          output += placeholder;
+        }
+
+        this.buffer = this.buffer.slice(placeholder.length);
+      } else {
+        // Check if buffer could be an incomplete placeholder
+        if (this.couldBePlaceholder(this.buffer)) {
+          // Keep buffering - might be incomplete placeholder
+          if (this.buffer.length > MAX_PLACEHOLDER_LENGTH) {
+            // Too long to be a placeholder - flush the `__` and continue
+            output += "__";
+            this.buffer = this.buffer.slice(2);
+          } else {
+            // Wait for more data
+            break;
+          }
+        } else {
+          // Definitely not a placeholder - output the `__`
+          output += "__";
+          this.buffer = this.buffer.slice(2);
+        }
+      }
+    }
+
+    return output;
+  }
+
+  /**
+   * Check if text could be the start of a placeholder
+   * Returns true if it matches the beginning of __PII_<TYPE>_<ID>__
+   */
+  private couldBePlaceholder(text: string): boolean {
+    // Must start with __
+    if (!text.startsWith("__")) return false;
+
+    // Check partial patterns
+    const partialPatterns = [
+      /^__$/,
+      /^__P$/,
+      /^__PI$/,
+      /^__PII$/,
+      /^__PII_$/,
+      /^__PII_[A-Z_]*$/,
+      /^__PII_[A-Z_]+_$/,
+      /^__PII_[A-Z_]+_\d*$/,
+      /^__PII_[A-Z_]+_\d+_?$/,
+    ];
+
+    return partialPatterns.some(pattern => pattern.test(text));
+  }
+
+  /**
+   * Finalize stream - flush any remaining buffer
+   * Call this at end of stream to ensure nothing is lost
+   */
+  finalize(): string {
+    if (this.buffer.length === 0) return "";
+
+    // Try to restore any remaining buffer
+    const result = restoreText(this.buffer, this.mappingTable);
+    this.buffer = "";
+    return result;
+  }
+
+  /**
+   * Check if there's pending data in buffer
+   */
+  hasPendingData(): boolean {
+    return this.buffer.length > 0;
+  }
+}
+
+/**
+ * Create a streaming restorer for a response
+ */
+export function createStreamRestorer(mappingTable: MappingTable): StreamRestorer {
+  return new StreamRestorer(mappingTable);
+}

package/gateway/src/sanitizer.ts

@@ -0,0 +1,298 @@
+/**
+ * AI Security Gateway - Content Sanitizer
+ *
+ * Sanitizes sensitive data in a single request-response cycle.
+ * Placeholder format: __PII_<ENTITY_TYPE>_<SERIAL_ID>__
+ */
+
+import type { SanitizeResult, MappingTable } from "./types.js";
+
+// =============================================================================
+// Entity Types
+// =============================================================================
+
+type EntityType =
+  | "EMAIL_ADDRESS"
+  | "URL_ADDRESS"
+  | "PHONE_NUMBER"
+  | "BANK_NUMBER"
+  | "PRIVATE_KEY"
+  | "PASSWORD"
+  | "VERIFICATION_CODE"
+  | "API_KEY"
+  | "IP_ADDRESS"
+  | "SSN"
+  | "CREDIT_CARD";
+
+type EntityPattern = {
+  type: EntityType;
+  pattern: RegExp;
+  score: number;
+  captureGroup?: number;
+};
+
+// =============================================================================
+// Detection Patterns
+// =============================================================================
+
+const ENTITY_PATTERNS: EntityPattern[] = [
+  // PEM Private Keys
+  {
+    type: "PRIVATE_KEY",
+    pattern: /-----BEGIN (?:OPENSSH |RSA |EC |DSA )?PRIVATE KEY-----[\s\S]*?-----END (?:OPENSSH |RSA |EC |DSA )?PRIVATE KEY-----/g,
+    score: 0.95,
+  },
+  // Email addresses
+  {
+    type: "EMAIL_ADDRESS",
+    pattern: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+    score: 0.90,
+  },
+  // URLs
+  {
+    type: "URL_ADDRESS",
+    pattern: /https?:\/\/[A-Za-z0-9._~:/?#\[\]@!$&'()*+,;=%-]+/g,
+    score: 0.80,
+  },
+  // Known API key prefixes
+  {
+    type: "API_KEY",
+    pattern: /\b(?:sk-[A-Za-z0-9]{20,}|sk_(?:live|test)_[A-Za-z0-9]{20,}|pk_(?:live|test)_[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36,}|gho_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,}|AKIA[A-Z0-9]{16}|xox[baprs]-[A-Za-z0-9-]+|SG\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|hf_[A-Za-z0-9]{30,})\b/g,
+    score: 0.90,
+  },
+  // Bearer tokens
+  {
+    type: "API_KEY",
+    pattern: /Bearer\s+[A-Za-z0-9\-_.~+/]{20,}={0,3}/g,
+    score: 0.85,
+  },
+  // Hex private keys (64 hex chars)
+  {
+    type: "PRIVATE_KEY",
+    pattern: /\b[0-9a-fA-F]{64}\b/g,
+    score: 0.75,
+  },
+  // Labeled password patterns
+  {
+    type: "PASSWORD",
+    pattern: /(?:password|passwd|pwd|pass|passcode)\s*[:=]\s*["']?(\S+)["']?/gi,
+    score: 0.80,
+    captureGroup: 1,
+  },
+  // Labeled API key patterns
+  {
+    type: "API_KEY",
+    pattern: /(?:api[_-]?key|apikey|secret[_-]?key|access[_-]?token|auth[_-]?token)\s*[:=]\s*["']?([A-Za-z0-9\-_.~+/]{16,})["']?/gi,
+    score: 0.85,
+    captureGroup: 1,
+  },
+  // Phone numbers
+  {
+    type: "PHONE_NUMBER",
+    pattern: /\+?\d{1,3}[-.\s]?\(?\d{2,4}\)?[-.\s]?\d{3,4}[-.\s]?\d{3,4}/g,
+    score: 0.70,
+  },
+  // Credit card numbers
+  {
+    type: "CREDIT_CARD",
+    pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
+    score: 0.85,
+  },
+  // Bank account numbers
+  {
+    type: "BANK_NUMBER",
+    pattern: /\b\d{12,19}\b/g,
+    score: 0.60,
+  },
+  // SSN
+  {
+    type: "SSN",
+    pattern: /\b\d{3}-\d{2}-\d{4}\b/g,
+    score: 0.85,
+  },
+  // IP addresses
+  {
+    type: "IP_ADDRESS",
+    pattern: /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g,
+    score: 0.70,
+  },
+  // Labeled verification codes
+  {
+    type: "VERIFICATION_CODE",
+    pattern: /(?:verification\s*code|verify\s*code|otp|2fa\s*code|auth(?:entication)?\s*code)\s*[:=\-]?\s*([A-Za-z0-9]{4,12})/gi,
+    score: 0.80,
+    captureGroup: 1,
+  },
+];
+
+// =============================================================================
+// Match Collection
+// =============================================================================
+
+type MatchWithMeta = {
+  originalText: string;
+  type: EntityType;
+  score: number;
+  start: number;
+  end: number;
+};
+
+function collectMatches(content: string): MatchWithMeta[] {
+  const matches: MatchWithMeta[] = [];
+
+  for (const entity of ENTITY_PATTERNS) {
+    entity.pattern.lastIndex = 0;
+    let m: RegExpExecArray | null;
+
+    while ((m = entity.pattern.exec(content)) !== null) {
+      let matchedText: string;
+      let start: number;
+
+      if (entity.captureGroup !== undefined && m[entity.captureGroup]) {
+        matchedText = m[entity.captureGroup];
+        start = m.index + m[0].indexOf(matchedText);
+      } else {
+        matchedText = m[0];
+        start = m.index;
+      }
+
+      matches.push({
+        originalText: matchedText,
+        type: entity.type,
+        score: entity.score,
+        start,
+        end: start + matchedText.length,
+      });
+    }
+  }
+
+  return matches;
+}
+
+// =============================================================================
+// Span Merging
+// =============================================================================
+
+function mergeSpans(matches: MatchWithMeta[]): MatchWithMeta[] {
+  if (matches.length === 0) return [];
+
+  matches.sort((a, b) => {
+    if (a.start !== b.start) return a.start - b.start;
+    const lenDiff = (b.end - b.start) - (a.end - a.start);
+    if (lenDiff !== 0) return lenDiff;
+    return b.score - a.score;
+  });
+
+  const merged: MatchWithMeta[] = [];
+  let current = matches[0];
+
+  for (let i = 1; i < matches.length; i++) {
+    const next = matches[i];
+    if (next.start < current.end) {
+      const currentLen = current.end - current.start;
+      const nextLen = next.end - next.start;
+      if (next.score > current.score || (next.score === current.score && nextLen > currentLen)) {
+        current = next;
+      }
+    } else {
+      merged.push(current);
+      current = next;
+    }
+  }
+
+  merged.push(current);
+  return merged;
+}
+
+// =============================================================================
+// Text Sanitization
+// =============================================================================
+
+function sanitizeText(
+  text: string,
+  mappingTable: MappingTable,
+  typeCounters: Map<EntityType, number>,
+): string {
+  const matches = collectMatches(text);
+  if (matches.length === 0) return text;
+
+  const merged = mergeSpans(matches);
+  const textToPlaceholder = new Map<string, string>();
+
+  for (const match of merged) {
+    if (!textToPlaceholder.has(match.originalText)) {
+      const counter = (typeCounters.get(match.type) ?? 0) + 1;
+      typeCounters.set(match.type, counter);
+      const paddedId = counter.toString().padStart(8, "0");
+      const placeholder = `__PII_${match.type}_${paddedId}__`;
+      textToPlaceholder.set(match.originalText, placeholder);
+      mappingTable.set(placeholder, match.originalText);
+    }
+  }
+
+  let sanitized = text;
+  const sortedMatches = [...merged].sort((a, b) => b.start - a.start);
+
+  for (const match of sortedMatches) {
+    const placeholder = textToPlaceholder.get(match.originalText)!;
+    sanitized = sanitized.slice(0, match.start) + placeholder + sanitized.slice(match.end);
+  }
+
+  return sanitized;
+}
+
+// =============================================================================
+// Recursive Sanitization
+// =============================================================================
+
+function sanitizeValue(
+  value: unknown,
+  mappingTable: MappingTable,
+  typeCounters: Map<EntityType, number>,
+): unknown {
+  if (typeof value === "string") {
+    return sanitizeText(value, mappingTable, typeCounters);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeValue(item, mappingTable, typeCounters));
+  }
+
+  if (value !== null && typeof value === "object") {
+    const sanitized: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      sanitized[key] = sanitizeValue(val, mappingTable, typeCounters);
+    }
+    return sanitized;
+  }
+
+  return value;
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Sanitize any content (messages array, object, string)
+ * Returns sanitized content and mapping table for restoration
+ */
+export function sanitize(content: unknown): SanitizeResult {
+  const mappingTable: MappingTable = new Map();
+  const typeCounters = new Map<EntityType, number>();
+
+  const sanitized = sanitizeValue(content, mappingTable, typeCounters);
+
+  return {
+    sanitized,
+    mappingTable,
+    redactionCount: mappingTable.size,
+  };
+}
+
+/**
+ * Sanitize messages array (common case for LLM APIs)
+ */
+export function sanitizeMessages(messages: unknown[]): SanitizeResult {
+  return sanitize(messages);
+}

package/gateway/src/types.ts

@@ -0,0 +1,73 @@
+/**
+ * AI Security Gateway types
+ */
+
+// Mapping from placeholder to original value
+export type MappingTable = Map<string, string>;
+
+// Result of sanitization with mapping table
+export type SanitizeResult = {
+  sanitized: any; // Sanitized content (same structure as input)
+  mappingTable: MappingTable; // placeholder -> original value
+  redactionCount: number; // Total redactions made
+};
+
+// API type for backend routing
+export type ApiType = "anthropic" | "openai" | "gemini";
+
+// Backend configuration
+export type BackendConfig = {
+  baseUrl: string;
+  apiKey: string;
+  type?: ApiType;         // API type (inferred from name if not set)
+  pathPrefix?: string;    // Gateway path prefix for routing (e.g., "/v1/coding")
+  models?: string[];      // Model names this backend handles (e.g., ["gpt-4", "gpt-3.5-turbo"])
+  referer?: string;       // HTTP-Referer (OpenRouter attribution)
+  title?: string;         // X-Title (OpenRouter attribution)
+};
+
+// Gateway configuration
+export type GatewayConfig = {
+  port: number;
+  // Flexible backends: any name allowed (e.g., "vllm", "deepseek", "anthropic")
+  backends: {
+    [name: string]: BackendConfig;
+  };
+  // Optional: route specific paths to specific backends
+  routing?: {
+    [path: string]: string;  // path -> backend name
+  };
+  // Optional: default backend for each API type
+  defaultBackends?: {
+    anthropic?: string;      // backend name for /v1/messages
+    openai?: string;         // backend name for /v1/chat/completions
+    gemini?: string;         // backend name for /v1/models/:model:generateContent
+  };
+};
+
+// Entity match
+export type EntityMatch = {
+  originalText: string;
+  category: string;
+  placeholder: string;
+};
+
+// Gateway activity event for logging
+export type GatewayActivityEvent = {
+  id: string;
+  timestamp: string;
+  requestId: string;
+  type: "sanitize" | "restore";
+  direction: "request" | "response";
+  backend: string;
+  endpoint: string;
+  model?: string;
+  // Sanitization stats
+  redactionCount: number;
+  categories: Record<string, number>; // category -> count
+  // Timing
+  durationMs?: number;
+};
+
+// Activity listener callback
+export type ActivityListener = (event: GatewayActivityEvent) => void;

package/gateway/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "test"]
+}