How OmniRoute Manages Upstream Headers: Security Rules and Validation Logic

OmniRoute sanitizes all headers forwarded to upstream providers using a centralized denylist in src/shared/constants/upstreamHeaders.ts that blocks hop-by-hop headers like Host and Connection while strictly forbidding authentication headers such as Authorization from custom header injection to prevent credential leakage.

OmniRoute implements strict upstream header management to ensure secure, consistent communication with LLM providers. By centralizing header validation logic in a single constants file, the framework prevents harmful header injection and protects sensitive credentials. This article examines how the upstreamHeaders.ts module defines forbidden headers and enforces these rules across validation and execution layers.

The Core Forbidden Header Set

OmniRoute maintains a forbidden header set containing standard HTTP hop-by-hop headers that the transport layer manages automatically. These headers must never reach upstream providers because they control connection framing and could disrupt the request pipeline.

The FORBIDDEN constant in src/shared/constants/upstreamHeaders.ts defines these restricted names:

const FORBIDDEN = new Set([
  "host",
  "connection",
  "content-length",
  "keep-alive",
  "proxy-connection",
  "transfer-encoding",
  "te",
  "trailer",
  "upgrade",
].map(s => s.toLowerCase()));

The isForbiddenUpstreamHeaderName Helper

To validate headers against this set, OmniRoute provides the isForbiddenUpstreamHeaderName() function. This utility normalizes input by converting names to lowercase and trimming whitespace before checking membership in the FORBIDDEN set:

export function isForbiddenUpstreamHeaderName(name: string): boolean {
  const n = String(name).trim().toLowerCase();
  return FORBIDDEN.has(n);
}

This function serves as the primary gatekeeper for transport-layer headers, ensuring that critical connection management headers never leak to upstream services.

Authentication Header Restrictions

Beyond transport headers, OmniRoute strictly controls authentication headers to prevent credential leakage. Custom headers provided by users cannot override credentials stored in the connection configuration, maintaining a clear separation between user input and sensitive authentication data.

The FORBIDDEN_AUTH Set

The FORBIDDEN_AUTH constant explicitly blocks common credential-bearing headers:

const FORBIDDEN_AUTH = new Set(
  ["authorization", "x-api-key", "x-goog-api-key", "api-key", "cookie"]
    .map(s => s.toLowerCase())
);

This set includes industry-standard authentication headers such as Authorization, various API key formats, and Cookie headers. By centralizing these definitions, OmniRoute ensures that validation logic remains consistent across the entire codebase.

Unified Custom Header Validation

When operators configure custom upstream headers through the request schema, OmniRoute combines both forbidden sets into a single validation layer. The isForbiddenCustomHeaderName() function performs this unified check, rejecting any header that appears in either the transport or authentication denylists.

export function isForbiddenCustomHeaderName(name: string): boolean {
  const n = String(name).trim().toLowerCase();
  return isForbiddenUpstreamHeaderName(n) || FORBIDDEN_AUTH.has(n);
}

This function is exported from src/shared/constants/upstreamHeaders.ts and serves as the definitive authority for custom header permissibility.

Schema Validation Integration

The validation logic propagates to request parsing through Zod schemas defined in src/shared/constants/schemas.ts. The schema uses isForbiddenCustomHeaderName to reject illegal headers at the API boundary:

import { z } from 'zod';
import { isForbiddenCustomHeaderName } from '@/shared/constants/upstreamHeaders';

const customHeadersSchema = z.record(
  z.string().refine(name => !isForbiddenCustomHeaderName(name), {
    message: 'Header name is forbidden',
  }),
  z.string()
);

// Valid usage
const headers = { 'x-custom-id': '12345' };
customHeadersSchema.parse(headers); // ✅ passes

This schema-level enforcement ensures that malformed requests fail fast before reaching the execution layer.

Runtime Enforcement in Executors

During request execution, open-sse/executors/default.ts applies custom headers only after verifying they are not forbidden. The executor iterates through user-provided headers and applies the same validation function used by the schema:

// Inside open-sse/executors/default.ts
for (const [name, value] of Object.entries(customHeaders)) {
  if (!isForbiddenCustomHeaderName(name)) {
    requestHeaders.set(name, value);
  }
}

This dual-layer validation—once at the schema level and again at runtime—guarantees that no forbidden headers reach upstream providers even if validation is bypassed.

Programmatic Header Checking

Developers can also check header validity programmatically using the exported utilities:

import { isForbiddenCustomHeaderName } from '@/shared/constants/upstreamHeaders';

// Example: user-supplied header
const headerName = 'Authorization';
if (isForbiddenCustomHeaderName(headerName)) {
  console.warn(`${headerName} is not allowed as a custom upstream header`);
}

Summary

• Centralized denylist: All forbidden upstream headers are defined in src/shared/constants/upstreamHeaders.ts, including transport headers (Host, Connection) and authentication headers (Authorization, X-Api-Key).
• Dual validation layers: The isForbiddenCustomHeaderName() function enforces rules at both schema validation time and request execution time.
• Credential protection: Authentication headers are strictly isolated from custom header injection, preventing user-supplied values from overriding stored credentials.
• Consistent enforcement: The same validation logic runs in src/shared/constants/schemas.ts for API validation and open-sse/executors/default.ts for runtime safety.

Frequently Asked Questions

What headers are forbidden in OmniRoute upstream requests?

OmniRoute blocks two categories of headers: hop-by-hop transport headers (host, connection, content-length, keep-alive, transfer-encoding, te, trailer, upgrade) and authentication headers (authorization, x-api-key, x-goog-api-key, api-key, cookie). These are defined in the FORBIDDEN and FORBIDDEN_AUTH sets within src/shared/constants/upstreamHeaders.ts.

How does OmniRoute prevent custom headers from overriding credentials?

The framework uses the isForbiddenCustomHeaderName() function to reject any custom header that matches the FORBIDDEN_AUTH set. This ensures that credentials stored in the connection configuration remain the single source of truth, preventing injection attacks that might attempt to steal or manipulate API keys through malicious header values.

Where is upstream header validation enforced in the codebase?

Validation occurs in three locations: src/shared/constants/upstreamHeaders.ts defines the rules, src/shared/constants/schemas.ts validates incoming requests using Zod schemas, and open-sse/executors/default.ts performs final runtime checks before sending requests to upstream providers. The test suite in tests/upstream-headers-sanitize.test.ts verifies this behavior.

Can I add custom headers to upstream requests in OmniRoute?

Yes, but only headers that pass the isForbiddenCustomHeaderName() check. You can specify custom headers in the request schema, and they will be forwarded to upstream providers as long as they do not appear in the forbidden transport or authentication sets. Use headers like x-custom-id or x-request-context instead of reserved names.

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