# How OmniRoute Manages Upstream Headers: Security Rules and Validation Logic

> Learn how OmniRoute secures upstream headers by blocking hop-by-hop and authentication headers. Discover the validation logic in upstreamHeaders.ts.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-14

---

**OmniRoute sanitizes all headers forwarded to upstream providers using a centralized denylist in [`src/shared/constants/upstreamHeaders.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/upstreamHeaders.ts) defines these restricted names:

```typescript
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:

```typescript
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:

```typescript
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.

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/schemas.ts). The schema uses `isForbiddenCustomHeaderName` to reject illegal headers at the API boundary:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
// 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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/schemas.ts) for API validation and [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/upstreamHeaders.ts) defines the rules, [`src/shared/constants/schemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/schemas.ts) validates incoming requests using Zod schemas, and [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.