@openguardrails/gateway 1.0.0

package/src/index.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * OpenGuardrails AI Security Gateway
+ *
+ * Local HTTP proxy that intercepts LLM API calls, sanitizes sensitive data
+ * before sending to providers, and restores it in responses.
+ * Supports Anthropic, OpenAI, and Gemini protocols.
+ */
+
+import { createServer } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { loadConfig, validateConfig } from "./config.js";
+import type { GatewayConfig } from "./types.js";
+import { handleAnthropicRequest } from "./handlers/anthropic.js";
+import { handleOpenAIRequest } from "./handlers/openai.js";
+import { handleGeminiRequest } from "./handlers/gemini.js";
+
+const GATEWAY_MODE = process.env.GATEWAY_MODE || "selfhosted";
+
+let config: GatewayConfig;
+
+/**
+ * Main request handler
+ */
+async function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const { method, url } = req;
+
+  // Log request
+  console.log(`[ai-security-gateway] ${method} ${url}`);
+
+  // CORS headers (for browser-based clients)
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, x-api-key, anthropic-version");
+
+  // Handle OPTIONS for CORS preflight
+  if (method === "OPTIONS") {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  // Health check (allow GET)
+  if (url === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ status: "ok", version: "1.0.0" }));
+    return;
+  }
+
+  // Only allow POST for API endpoints
+  if (method !== "POST") {
+    res.writeHead(405, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Method not allowed" }));
+    return;
+  }
+
+  // Route to appropriate handler
+  try {
+    if (url === "/v1/messages") {
+      // Anthropic Messages API
+      await handleAnthropicRequest(req, res, config);
+    } else if (url === "/v1/chat/completions") {
+      // OpenAI Chat Completions API
+      await handleOpenAIRequest(req, res, config);
+    } else if (url?.match(/^\/v1\/models\/(.+):generateContent$/)) {
+      // Gemini API
+      const match = url.match(/^\/v1\/models\/(.+):generateContent$/);
+      const modelName = match?.[1];
+      if (modelName) {
+        await handleGeminiRequest(req, res, config, modelName);
+      } else {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Model name required" }));
+      }
+    } else {
+      // Unknown endpoint
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found", url }));
+    }
+  } catch (error) {
+    console.error("[ai-security-gateway] Request handler error:", error);
+    res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        error: "Internal server error",
+        message: error instanceof Error ? error.message : String(error),
+      }),
+    );
+  }
+}
+
+/**
+ * Start gateway server
+ */
+export function startGateway(configPath?: string): void {
+  try {
+    // Load and validate configuration
+    config = loadConfig(configPath);
+    validateConfig(config);
+
+    console.log("[ai-security-gateway] Configuration loaded:");
+    console.log(`  Mode: ${GATEWAY_MODE}`);
+    console.log(`  Port: ${config.port}`);
+    console.log(
+      `  Backends: ${Object.keys(config.backends).join(", ")}`,
+    );
+
+    // Create HTTP server
+    const server = createServer(handleRequest);
+
+    // Start listening
+    server.listen(config.port, "127.0.0.1", () => {
+      console.log(
+        `[ai-security-gateway] Server listening on http://127.0.0.1:${config.port}`,
+      );
+      console.log("[ai-security-gateway] Ready to proxy requests");
+      console.log("");
+      console.log("Endpoints:");
+      console.log(`  POST http://127.0.0.1:${config.port}/v1/messages - Anthropic`);
+      console.log(`  POST http://127.0.0.1:${config.port}/v1/chat/completions - OpenAI`);
+      console.log(`  POST http://127.0.0.1:${config.port}/v1/models/:model:generateContent - Gemini`);
+      console.log(`  GET  http://127.0.0.1:${config.port}/health - Health check`);
+    });
+
+    // Handle shutdown
+    process.on("SIGINT", () => {
+      console.log("\n[ai-security-gateway] Shutting down...");
+      server.close(() => {
+        console.log("[ai-security-gateway] Server stopped");
+        process.exit(0);
+      });
+    });
+
+    process.on("SIGTERM", () => {
+      console.log("\n[ai-security-gateway] Shutting down...");
+      server.close(() => {
+        console.log("[ai-security-gateway] Server stopped");
+        process.exit(0);
+      });
+    });
+  } catch (error) {
+    console.error("[ai-security-gateway] Failed to start:", error);
+    process.exit(1);
+  }
+}
+
+// Re-export for programmatic use
+export { sanitize, sanitizeMessages } from "./sanitizer.js";
+export { restore, restoreJSON, restoreSSELine } from "./restorer.js";
+export type { GatewayConfig, MappingTable, SanitizeResult, EntityMatch } from "./types.js";
+
+// Start if run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const configPath = process.argv[2];
+  startGateway(configPath);
+}

package/src/restorer.ts

@@ -0,0 +1,101 @@
+/**
+ * AI Security Gateway - Content restorer
+ *
+ * Restores sanitized placeholders back to original values using the mapping table.
+ */
+
+import type { MappingTable } from "./types.js";
+
+/**
+ * Restore placeholders in a string
+ */
+function restoreText(text: string, mappingTable: MappingTable): string {
+  let restored = text;
+
+  // Sort placeholders by length descending to handle nested cases
+  const placeholders = Array.from(mappingTable.keys()).sort(
+    (a, b) => b.length - a.length,
+  );
+
+  for (const placeholder of placeholders) {
+    const originalValue = mappingTable.get(placeholder)!;
+    // Use split/join for safe replacement (handles special regex chars)
+    restored = restored.split(placeholder).join(originalValue);
+  }
+
+  return restored;
+}
+
+/**
+ * Recursively restore any value (string, object, array)
+ */
+function restoreValue(value: any, mappingTable: MappingTable): any {
+  // String: restore placeholders
+  if (typeof value === "string") {
+    return restoreText(value, mappingTable);
+  }
+
+  // Array: restore each element
+  if (Array.isArray(value)) {
+    return value.map((item) => restoreValue(item, mappingTable));
+  }
+
+  // Object: restore each property
+  if (value !== null && typeof value === "object") {
+    const restored: any = {};
+    for (const [key, val] of Object.entries(value)) {
+      restored[key] = restoreValue(val, mappingTable);
+    }
+    return restored;
+  }
+
+  // Primitives: return as-is
+  return value;
+}
+
+/**
+ * Restore any content (object, array, string) using the mapping table
+ */
+export function restore(content: any, mappingTable: MappingTable): any {
+  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 {
+    // Try to parse as JSON first
+    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)}\n`;
+  } catch {
+    // Fallback to text restoration
+    return `data: ${restoreText(dataContent, mappingTable)}\n`;
+  }
+}

package/src/sanitizer.ts

@@ -0,0 +1,278 @@
+/**
+ * AI Security Gateway - Content sanitizer
+ *
+ * Recursively processes message structures, replaces sensitive data with
+ * numbered placeholders, and returns a mapping table for restoration.
+ */
+
+import type { SanitizeResult, MappingTable, EntityMatch } from "./types.js";
+
+// =============================================================================
+// Entity Definitions
+// =============================================================================
+
+type Entity = {
+  category: string;
+  categoryKey: string; // Used for numbered placeholders: __email_1__, __email_2__
+  pattern: RegExp;
+};
+
+const ENTITIES: Entity[] = [
+  // URLs (must come before email to avoid partial matches)
+  {
+    category: "URL",
+    categoryKey: "url",
+    pattern: /https?:\/\/[^\s<>"{}|\\^`\[\]]+/g,
+  },
+  // Email
+  {
+    category: "EMAIL",
+    categoryKey: "email",
+    pattern: /[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}/g,
+  },
+  // Credit Card (4 groups of 4 digits)
+  {
+    category: "CREDIT_CARD",
+    categoryKey: "credit_card",
+    pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
+  },
+  // Bank Card (Chinese format: 16-19 digits)
+  {
+    category: "BANK_CARD",
+    categoryKey: "bank_card",
+    pattern: /\b\d{16,19}\b/g,
+  },
+  // SSN (###-##-####)
+  {
+    category: "SSN",
+    categoryKey: "ssn",
+    pattern: /\b\d{3}-\d{2}-\d{4}\b/g,
+  },
+  // IBAN
+  {
+    category: "IBAN",
+    categoryKey: "iban",
+    pattern: /\b[A-Z]{2}\d{2}[A-Z0-9]{4}\d{7}[A-Z0-9]{0,16}\b/g,
+  },
+  // IP Address
+  {
+    category: "IP_ADDRESS",
+    categoryKey: "ip",
+    pattern: /\b(?:[0-9]{1,3}\.){3}[0-9]{1,3}\b/g,
+  },
+  // Phone numbers (US/intl formats, including +86-xxx-xxxx-xxxx)
+  {
+    category: "PHONE",
+    categoryKey: "phone",
+    pattern: /[+]?[0-9]{1,3}?[-\s.]?[(]?[0-9]{3}[)]?[-\s.][0-9]{3,4}[-\s.][0-9]{4,6}\b/g,
+  },
+];
+
+// Known secret prefixes
+const SECRET_PREFIXES = [
+  "sk-",
+  "sk_",
+  "pk_",
+  "ghp_",
+  "AKIA",
+  "xox",
+  "SG.",
+  "hf_",
+  "api-",
+  "token-",
+  "secret-",
+];
+
+const BEARER_PATTERN = /Bearer\s+[A-Za-z0-9\-_.~+/]+=*/g;
+
+const SECRET_PREFIX_PATTERN = new RegExp(
+  `(?:${SECRET_PREFIXES.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})[A-Za-z0-9\\-_.~+/]{8,}=*`,
+  "g",
+);
+
+// =============================================================================
+// Shannon Entropy
+// =============================================================================
+
+function shannonEntropy(s: string): number {
+  if (s.length === 0) return 0;
+  const freq = new Map<string, number>();
+  for (const ch of s) {
+    freq.set(ch, (freq.get(ch) ?? 0) + 1);
+  }
+  let entropy = 0;
+  for (const count of freq.values()) {
+    const p = count / s.length;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+// =============================================================================
+// Match Collection
+// =============================================================================
+
+function collectMatches(content: string): EntityMatch[] {
+  const matches: EntityMatch[] = [];
+
+  // Regex-based entities
+  for (const entity of ENTITIES) {
+    entity.pattern.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = entity.pattern.exec(content)) !== null) {
+      matches.push({
+        originalText: m[0],
+        category: entity.categoryKey,
+        placeholder: "", // Will be set later with numbering
+      });
+    }
+  }
+
+  // Secret prefixes
+  SECRET_PREFIX_PATTERN.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = SECRET_PREFIX_PATTERN.exec(content)) !== null) {
+    matches.push({
+      originalText: m[0],
+      category: "secret",
+      placeholder: "",
+    });
+  }
+
+  // Bearer tokens
+  BEARER_PATTERN.lastIndex = 0;
+  while ((m = BEARER_PATTERN.exec(content)) !== null) {
+    matches.push({
+      originalText: m[0],
+      category: "secret",
+      placeholder: "",
+    });
+  }
+
+  // High-entropy tokens
+  const tokenPattern = /\b[A-Za-z0-9\-_.~+/]{20,}={0,3}\b/g;
+  tokenPattern.lastIndex = 0;
+  while ((m = tokenPattern.exec(content)) !== null) {
+    const token = m[0];
+    if (matches.some((existing) => existing.originalText === token)) continue;
+    if (/^[a-z]+$/.test(token)) continue;
+    if (shannonEntropy(token) >= 4.0) {
+      matches.push({
+        originalText: token,
+        category: "secret",
+        placeholder: "",
+      });
+    }
+  }
+
+  return matches;
+}
+
+// =============================================================================
+// Text Sanitization
+// =============================================================================
+
+function sanitizeText(
+  text: string,
+  mappingTable: MappingTable,
+  categoryCounters: Map<string, number>,
+): string {
+  const matches = collectMatches(text);
+  if (matches.length === 0) return text;
+
+  // Deduplicate by original text
+  const unique = new Map<string, EntityMatch>();
+  for (const match of matches) {
+    if (!unique.has(match.originalText)) {
+      unique.set(match.originalText, match);
+    }
+  }
+
+  // Sort by length descending
+  const sorted = [...unique.values()].sort(
+    (a, b) => b.originalText.length - a.originalText.length,
+  );
+
+  // Replace and build mapping table
+  let sanitized = text;
+  for (const match of sorted) {
+    // Generate numbered placeholder
+    const counter = (categoryCounters.get(match.category) ?? 0) + 1;
+    categoryCounters.set(match.category, counter);
+    const placeholder = `__${match.category}_${counter}__`;
+
+    // Replace all occurrences
+    const parts = sanitized.split(match.originalText);
+    if (parts.length > 1) {
+      sanitized = parts.join(placeholder);
+      mappingTable.set(placeholder, match.originalText);
+    }
+  }
+
+  return sanitized;
+}
+
+// =============================================================================
+// Recursive Sanitization
+// =============================================================================
+
+/**
+ * Recursively sanitize any value (string, object, array)
+ */
+function sanitizeValue(
+  value: any,
+  mappingTable: MappingTable,
+  categoryCounters: Map<string, number>,
+): any {
+  // String: sanitize directly
+  if (typeof value === "string") {
+    return sanitizeText(value, mappingTable, categoryCounters);
+  }
+
+  // Array: sanitize each element
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      sanitizeValue(item, mappingTable, categoryCounters),
+    );
+  }
+
+  // Object: sanitize each property
+  if (value !== null && typeof value === "object") {
+    const sanitized: any = {};
+    for (const [key, val] of Object.entries(value)) {
+      sanitized[key] = sanitizeValue(val, mappingTable, categoryCounters);
+    }
+    return sanitized;
+  }
+
+  // Primitives: return as-is
+  return value;
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Sanitize any content (messages array, object, string)
+ * Returns sanitized content and mapping table for restoration
+ */
+export function sanitize(content: any): SanitizeResult {
+  const mappingTable: MappingTable = new Map();
+  const categoryCounters = new Map<string, number>();
+
+  const sanitized = sanitizeValue(content, mappingTable, categoryCounters);
+
+  return {
+    sanitized,
+    mappingTable,
+    redactionCount: mappingTable.size,
+  };
+}
+
+/**
+ * Sanitize messages array (common case for LLM APIs)
+ */
+export function sanitizeMessages(messages: any[]): SanitizeResult {
+  return sanitize(messages);
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+/**
+ * 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
+};
+
+// Gateway configuration
+export type GatewayConfig = {
+  port: number;
+  backends: {
+    anthropic?: {
+      baseUrl: string;
+      apiKey: string;
+    };
+    openai?: {
+      baseUrl: string;
+      apiKey: string;
+    };
+    gemini?: {
+      baseUrl: string;
+      apiKey: string;
+    };
+  };
+  // Optional: route specific paths to specific backends
+  routing?: {
+    [path: string]: keyof GatewayConfig["backends"];
+  };
+};
+
+// Entity match
+export type EntityMatch = {
+  originalText: string;
+  category: string;
+  placeholder: string;
+};