# How to Configure Prompt Injection Guard for Chat Completion APIs in OmniRoute

> Learn to configure prompt injection guard for chat completion APIs in OmniRoute. Customize thresholds and patterns or disable per request for robust security.

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

---

**Configuring the prompt injection guard for chat completion APIs involves wrapping your Next.js route handler with `withInjectionGuard`, passing `PromptInjectionGuardrailOptions` to customize severity thresholds and detection patterns, and optionally disabling the guard per-request via the `x-omniroute-disabled-guardrails` header.**

OmniRoute provides a built-in **prompt injection guard** designed to protect chat completion APIs from malicious input manipulation. This security layer operates as a composable middleware that inspects request bodies at the edge, allowing developers to configure detection thresholds, custom regex patterns, and blocking behaviors without modifying core business logic.

## Architecture of the Prompt Injection Guard

The guard is structured as a pipeline of specialized functions that parse, evaluate, and either block or forward requests to your chat completion handler.

### Core Components

| Component | Source File | Responsibility |
|-----------|-------------|----------------|
| **`createInjectionGuard`** | [[`src/middleware/promptInjectionGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts) | Factory that builds the `guardRequest` function using configured options. |
| **`withInjectionGuard`** | [[`src/middleware/promptInjectionGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts) | Higher-order wrapper that clones the request, parses the JSON body once, and orchestrates the guard evaluation before calling your handler. |
| **`evaluatePromptInjection`** | [[`src/lib/guardrails/promptInjection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts) | Core engine that scans payloads for injection signatures, applies custom patterns, and returns a decision object with `blocked` status and detection details. |
| **`resolveDisabledGuardrails`** | [[`src/lib/guardrails/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts) | Inspects incoming headers and environment variables to determine if specific guardrails should be bypassed for the current request. |

### Request Flow

When a `POST`, `PUT`, or `PATCH` request hits your chat completion endpoint:

1. **`withInjectionGuard`** clones the `Request` object and parses the body using `request.clone().json()` to avoid consuming the stream.
2. The parsed payload is passed to the guard created by **`createInjectionGuard`**, which invokes **`evaluatePromptInjection`**.
3. If **`resolveDisabledGuardrails`** detects the `x-omniroute-disabled-guardrails: promptInjection` header, evaluation is skipped entirely.
4. If the guard returns `blocked: true`, the middleware returns a `400` response with the `SECURITY_001` error code and [`CORS_HEADERS`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/cors.ts) applied.
5. If the guard flags but does not block (non-blocking mode), it adds `X-Injection-Flagged` and `X-Injection-Detections` headers to the response.
6. When the payload is clean, the original handler receives the `request`, `context`, and pre-parsed `parsedBody` as a third argument, eliminating the need for redundant JSON parsing.

## Configuration Options

The **`PromptInjectionGuardrailOptions`** type in [[`src/lib/guardrails/promptInjection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts) exposes several tunable parameters:

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `severityThreshold` | `'low' \| 'medium' \| 'high'` | Minimum severity level that triggers a block. | `'high'` |
| `customPatterns` | `Array<RegExp \| string>` | Additional regex patterns to detect organization-specific injection vectors. | `[]` |
| `mode` | `'block' \| 'warn' \| 'off'` | Control behavior: reject request, add warning headers only, or disable. | `'block'` |
| `logger` | `Console \| Logger` | Custom logging instance for security events. Falls back to `console`. | `console` |

## Implementing the Guard on Chat Completion Routes

To protect your `/v1/chat/completions` endpoint, import the wrapper and apply it to your handler:

```typescript
// src/app/api/v1/chat/completions/route.ts
import { withInjectionGuard } from '@/middleware/promptInjectionGuard';
import type { PromptInjectionGuardrailOptions } from '@/lib/guardrails/promptInjection';
import { handleChat } from '@/open-sse/handlers/chatCore';

const guardOptions: PromptInjectionGuardrailOptions = {
  severityThreshold: 'high',
  mode: 'block',
  customPatterns: [/secret\s*key/i, /internal-api-token/],
};

// The wrapper passes the parsed body as the third argument to your handler
export const POST = withInjectionGuard(handleChat, guardOptions);

```

The `handleChat` function receives the original request, context, and the parsed body object, allowing immediate access to messages without re-parsing JSON.

## Per-Request Disabling

For debugging or legacy client compatibility, you can bypass the guard for specific requests by including the header:

```

x-omniroute-disabled-guardrails: promptInjection

```

The [`resolveDisabledGuardrails`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts) utility parses this comma-separated list and excludes specified guardrails from the evaluation pipeline.

## Summary

- The **prompt injection guard** in OmniRoute is a middleware-based security layer that evaluates chat completion requests before they reach your business logic.
- Configure detection sensitivity using **`PromptInjectionGuardrailOptions`** with `severityThreshold`, `customPatterns`, and `mode` settings.
- Apply the guard via **`withInjectionGuard`**, which handles request cloning, single-pass JSON parsing, and consistent CORS headers for blocked responses.
- Disable the guard temporarily using the **`x-omniroute-disabled-guardrails`** header for specific clients or testing scenarios.

## Frequently Asked Questions

### What is the prompt injection guard in OmniRoute?

The prompt injection guard is a security middleware that inspects incoming request bodies for malicious patterns attempting to manipulate AI model behavior. It uses the **`evaluatePromptInjection`** engine to analyze payloads against configurable signatures and either blocks malicious requests or flags them for downstream logging, operating transparently within Next.js API routes.

### How do I customize detection patterns for my organization?

Pass an array of regular expressions or strings to the `customPatterns` property in your **`PromptInjectionGuardrailOptions`**. These patterns are evaluated alongside the built-in detection heuristics in [[`src/lib/guardrails/promptInjection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts)](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts), allowing you to catch organization-specific keywords like internal API keys or sensitive command sequences.

### Can I disable the guard for specific API clients without redeploying?

Yes. Send the HTTP header `x-omniroute-disabled-guardrails: promptInjection` with your request. The [**`resolveDisabledGuardrails`**](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts) function checks this header at runtime and skips the injection evaluation for that specific request, making it suitable for debugging or supporting legacy integrations.

### Does adding the guard impact performance for legitimate requests?

The guard adds minimal overhead because it performs a single `request.clone().json()` parse and a synchronous regex evaluation pipeline. According to the implementation in [**`withInjectionGuard`**](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts), the parsed body is forwarded to your handler as a parameter, eliminating the need for duplicate JSON parsing and maintaining sub-millisecond latency for most payloads.