Security Features Implemented in OmniRoute: A Defense-in-Depth Analysis

OmniRoute implements a comprehensive defense-in-depth security model that combines route guards, circuit breakers, intelligent connection cooldowns, model lockouts, content guardrails, and sanitized error handling to protect API traffic at every layer of the request pipeline.

The open-source repository diegosouzapw/OmniRoute embeds security controls directly into its routing and resilience infrastructure. These security features implemented in OmniRoute ensure that sensitive endpoints remain inaccessible to external networks, failing providers are automatically isolated, and user data is scrubbed of PII before reaching upstream services.

API Routing Security with Route Guards

OmniRoute’s first line of defense operates at the HTTP routing layer, classifying every endpoint before authentication occurs.

Route Classification and Enforcement

The Route Guard system in src/server/authz/routeGuard.ts maintains three critical whitelists: LOCAL_ONLY_API_PREFIXES, ALWAYS_PROTECTED_API_PATHS, and SPAWN_CAPABLE_PREFIXES. Every API route imports helpers like isLocalOnlyPath or isAlwaysProtectedPath to abort unauthorized requests immediately.

// src/server/authz/routeGuard.ts
import { isLocalOnlyPath } from "@/server/authz/routeGuard";

export async function POST(req: Request) {
  if (!isLocalOnlyPath(req.url)) {
    return new Response("Forbidden", { status: 403 });
  }
  // … proceed with privileged logic …
}

Routes that spawn child processes—such as /api/services/* and /api/mcp/*—are documented in src/lib/security/localEndpoints.ts and forced to be local-only by the guard, preventing remote exploitation of dangerous capabilities.

Network Interface Validation

The same route guard module exports isLoopbackHost and isPrivateLanHost helpers that inspect inbound request origins. These functions reject traffic from non-trusted network interfaces for sensitive paths, ensuring internal services remain inaccessible from public networks.

Provider Resilience and Circuit Breakers

To prevent cascading failures, OmniRoute implements a Provider Circuit Breaker pattern that monitors upstream health.

The breaker tracks four states—closed, degraded, open, and half-open—and automatically transitions between them based on error thresholds. Implemented in src/shared/utils/circuitBreaker.ts, downstream handlers consult getCircuitBreaker(provider) before each request:

// src/shared/utils/circuitBreaker.ts
import { getCircuitBreaker } from "@/shared/utils/circuitBreaker";

const breaker = getCircuitBreaker("openai");
if (breaker.state === "OPEN") {
  return { error: "Provider temporarily unavailable" };
}

When a provider repeatedly returns 5xx errors, the breaker opens, stopping all traffic to that provider until a timeout resets the state.

Connection and Model Protection

OmniRoute isolates failures to specific credentials or models without disrupting overall service availability.

Connection Cooldown

When a request receives a rate-limit (429) or transient error, src/lib/services/accountFallback.ts records a rateLimitedUntil timestamp on the connection record. The connection selector in src/lib/services/auth.ts skips any connection whose cooldown period is active:

// Connection cooldown check
import { getProviderCredentials } from "@/sse/services/auth";

const creds = await getProviderCredentials("openai");
if (creds.rateLimitedUntil && new Date(creds.rateLimitedUntil) > Date.now()) {
  // rotate to another key or return a rate-limit error
}

Model Lockout Isolation

While connection cooldown affects entire accounts, Model Lockout isolates specific quota-limited models. The src/lib/resilience/modelLockoutSettings.ts file defines lockout policies, while src/lib/services/accountFallback.ts maintains a Map<string, ModelLockoutEntry> that evicts entries based on configurable max-size limits.

// src/lib/resilience/modelLockoutSettings.ts
import { resolveModelLockoutSettings } from "@/lib/resilience/modelLockoutSettings";

const lockout = resolveModelLockoutSettings({ model: "gpt-4" });
if (lockout && lockout.remainingMs > 0) {
  // avoid using this model for the next `lockout.remainingMs` ms
}

This ensures that one model's quota exhaustion does not render the entire connection unusable.

Content Safety Guardrails

The Guardrail Registry in src/lib/guardrails/registry.ts provides a plugin architecture for running pre-call and post-call validations on every request.

PII and Credential Masking

Before dispatching to providers, OmniRoute scans payloads for sensitive data. The PII Masker (src/lib/guardrails/piiMasker.ts) redacts email patterns, credit card numbers, and other identifiers, replacing them with <redacted>. Simultaneously, the Credential Masker (src/lib/guardrails/credentialMasker.ts) applies regex patterns to scrub Authorization: Bearer … headers and api_key=… parameters from user prompts.

Prompt Injection Detection

The Prompt-Injection Guardrail (src/lib/guardrails/promptInjectionGuardrail.ts) validates user messages against forbidden phrases that attempt to inject system instructions or retrieve hidden context. Blocked requests return sanitized error messages without exposing internal validation logic.

// src/lib/guardrails/registry.ts
import { guardrailRegistry } from "@/lib/guardrails";

const pre = await guardrailRegistry.runPreCallHooks(requestBody);
if (pre.blocked) {
  return new Response(pre.message, { status: 400 });
}

Error Sanitization and Transport Security

OmniRoute guarantees that error responses never leak stack traces, absolute file paths, or credentials. The open-sse/utils/error.ts module exports sanitizeErrorMessage, which keeps only the first error line and strips sensitive data, and buildErrorBody, which structures HTTP status JSON responses.

// open-sse/utils/error.ts
import { sanitizeErrorMessage, buildErrorBody } from "@/open-sse/utils/error";

try {
  await riskyOperation();
} catch (err) {
  const safeMsg = sanitizeErrorMessage(err);
  return new Response(buildErrorBody(500, safeMsg));
}

Additionally, src/lib/usage/providerLimits.ts implements Global Rate Limits and Quota Checks, enforcing per-provider, per-account, and per-model limits with exponential backoff logic.

Observability and Audit Trails

Every resilience event—circuit breaker trips, model lockouts, and connection cooldowns—is recorded in monitoring tables (domain_circuit_breakers, provider_health_matrix) and exposed via /api/monitoring/health. This visibility, implemented in src/lib/monitoring/providerHealthMatrix.ts, allows operators to detect abuse patterns and intervene manually when necessary.

Summary

• Route Guards in src/server/authz/routeGuard.ts classify endpoints as local-only or protected, blocking external access to dangerous routes before authentication.
• Circuit Breakers monitor provider health and automatically isolate failing upstream services to prevent cascading failures.
• Connection Cooldown and Model Lockout mechanisms isolate rate-limit errors to specific credentials or models, preserving overall service availability.
• Guardrail Registry runs pre-call and post-call checks to redact PII, scrub credentials, and block prompt injection attempts.
• Sanitized Error Handling ensures stack traces and file paths never leak to clients, while network validation restricts sensitive endpoints to loopback or private LAN interfaces.

Frequently Asked Questions

How does OmniRoute prevent external access to dangerous routes?

OmniRoute uses the Route Guard system in src/server/authz/routeGuard.ts to classify endpoints using whitelists like LOCAL_ONLY_API_PREFIXES and SPAWN_CAPABLE_PREFIXES. Routes that spawn child processes import isLocalOnlyPath and abort requests with 403 status codes if the traffic originates from non-loopback or non-private LAN hosts, ensuring privileged operations remain inaccessible from public networks.

What happens when an upstream AI provider fails repeatedly?

The Provider Circuit Breaker in src/shared/utils/circuitBreaker.ts tracks provider health through four states: closed, degraded, open, and half-open. After a configurable threshold of 5xx errors, the breaker opens and rejects subsequent requests for a cooldown period, preventing cascading failures and allowing the provider to recover before traffic resumes.

How does OmniRoute protect against prompt injection attacks?

The Prompt-Injection Guardrail in src/lib/guardrails/promptInjectionGuardrail.ts validates incoming messages against a list of forbidden phrases designed to extract system instructions or hidden context. The guardrail runs as a pre-call hook via the registry in src/lib/guardrails/registry.ts, blocking malicious requests with a sanitized 400 error before they reach upstream providers.

Are API keys and personal data visible to AI providers?

No. OmniRoute implements PII Masker and Credential Masker guardrails that scan request bodies in src/lib/guardrails/piiMasker.ts and src/lib/guardrails/credentialMasker.ts respectively. These components regex-match and redact email addresses, credit card numbers, bearer tokens, and API keys, replacing sensitive values with <redacted> before dispatching to external services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}