Guardrails

Source of truth: src/lib/guardrails/ Last updated: 2026-08-08 — v3.8.50 (Modality Bridge PR-3: Audio Bridge runtime and functional Audio settings tab)

Guardrails enforce safety, policy, and content transformations at the boundary between OmniRoute and upstream providers. Each guardrail can inspect (and optionally reject, transform, or annotate) request payloads (preCall) and upstream responses (postCall).

The system is fail-open: if a guardrail throws while executing, the registry records the error and continues with the next guardrail rather than failing the request. Blocking is an explicit decision (block: true), never an accident.

Built-in Guardrails

The registry auto-loads five guardrails in priority order on import (see registry.ts → registerDefaultGuardrails()):

Lower priority numbers run first.

Vision Bridge (visionBridge.ts) — Modality Bridge PR-1

Intercepts image-bearing requests aimed at non-vision models and either reroutes the whole request to a vision-capable model or replaces the image parts with text descriptions produced by a configurable vision model before the upstream call. This lets text-only providers transparently handle multimodal payloads.

Flow:

1. Skip if the target model already supports vision (unless it appears in the forced-bridge list isVisionBridgeForcedModel).
2. Extract image parts via extractImageParts(messages) (visionBridgeHelpers.ts), which delegates to the unified media detector detectMediaParts() in open-sse/utils/mediaParts.ts — the single source of truth shared with the combo compatibility filter. Extraction is allowlisted to top-level parts of the shapes replaceImageParts can splice back (the extract↔replace contract): OpenAI image_url, Anthropic base64 source.type:"base64", Anthropic URL source.type:"url", and Responses API input_image. Nested hits and indicator-only shapes are combo-filter material and are never extracted. Skip if none found.
3. Resolve runtime config via resolveVisionBridgeRuntimeSettings() (src/shared/constants/modalityBridgeDefaults.ts): new modalityBridge* settings keys win; legacy visionBridge* keys remain a one-cycle fallback (rollback window). Skip before any media traversal when the bridge is disabled.
4. Mode selector (modalityBridgeVisionMode, see table below) decides reroute vs describe. Reroute returns modifiedPayload with only model swapped, plus meta { rerouted, fromModel, toModel, imagesKept }.
5. Describe path: cap images at maxImages, compose the task-aware prompt, consult the describe cache, call the vision model in parallel (Promise.allSettled), and inject [Image N]: <description> text parts in their place. A failed describe yields null and the original image part is preserved (#4012) — except on the combo describe path when every describe failed, where a confirmed non-vision upstream gets an (unavailable — no vision-capable provider connected) stub instead (#8430).
6. Return modifiedPayload + meta (imagesProcessed, descriptions, processingTimeMs, visionModel).

Mode selector (modalityBridgeVisionMode)

Forced modes short-circuit before the auto heuristic runs; auto behavior is byte-identical to the pre-PR-1 guardrail.

Task-aware describe prompt (modalityBridgeVisionTaskAware)

Default true. composeVisionPrompt() (visionBridgeHelpers.ts) appends the text of the last user message (truncated to 500 chars) to the base describe prompt, steering the description toward what the user actually asked (codex-vision-proxy pattern) and asking the vision model to transcribe visible text. With the flag off — or no user text — the base prompt is used unchanged.

Describe output cap (modalityBridgeVisionMaxChars)

0 (default) means no cap — the description returned by callVisionModel() is passed through unmodified, preserving the existing behavior. Any value in the 100–50000 range truncates the description with a … suffix before it is spliced back as [Image N]: <description> (VisionBridgeGuardrail.preCall() in src/lib/guardrails/visionBridge.ts). Raise this for detail-heavy OCR tasks where the downstream model needs the full transcription; lower it to bound token usage on chatty vision models. The dashboard field lives on the Vision tab's Advanced panel (modality-bridge-max-chars in ModalityBridgeVisionTab.tsx) and clamps any value between 1 and 99 up to the 100 floor while leaving an explicit 0 untouched — 0 is a valid Zod value in its own right (z.union([z.literal(0), z.number().int().min(100).max(50000)])), not merely the "unset" default.

Describe cache (modalityBridge/bridgeCache.ts)

In-memory LRU + TTL cache for describe outputs, shared process-wide. Key = sha256(imageRef + composedPrompt + configuredBridgeModel) with length-prefix framing (no field-boundary collisions). The model component is the configured bridge model, not the model that actually answered — callVisionModel may fall back internally, and keying per attempt would fragment the cache. Failed describes are never cached. Settings:

Remote image normalization (self-loop describe/base64 fetch)

When the bridge fetches a remote image itself — the Anthropic describe self-call and the claude-wire-format base64 conversion (ensureBase64ImagesForClaudeWire), both via fetchRemoteImageAsDataUri() in visionBridgeHelpers.ts — the resulting data URI is passed through normalizeDataUri() (open-sse/utils/imageNormalize.ts) before being embedded in the vision-model request. Oversized images are downscaled to a 2048px long edge (matching the resize cap OpenAI/Anthropic already apply server-side), which cuts upload bytes/latency without changing what the vision model sees. Resizing uses sharp, loaded via dynamic import: on a platform where its native binary fails to load, normalizeDataUri() never throws — it falls back to a passthrough of the original bytes, so the describe/base64-conversion path always keeps working. Non-image bytes (a fetch that did not return a decodable image) are also passed through untouched. This normalization is scoped to images the bridge fetches for its own self-call — it is never applied to the caller's raw passthrough payload, consistent with the opt-in-only mutation principle (Hard Rule #20).

Settings schema + migration

The new modalityBridge* keys are Zod-validated in updateSettingsSchema (src/shared/validation/settingsSchemas.ts): modalityBridgeVisionEnabled, modalityBridgeVisionMode, modalityBridgeVisionModel, modalityBridgeVisionTaskAware, modalityBridgeVisionPrompt, modalityBridgeVisionTimeout, modalityBridgeVisionMaxImages, modalityBridgeVisionMaxChars, the modalityBridgeCache* trio, and the modalityBridgeAudio* group used by the Audio Bridge. Migration 141_modality_bridge_settings.sql copies existing legacy visionBridge* values to the matching new keys (idempotent, never overwrites an operator-set modalityBridge* value); the legacy keys stay accepted as a read fallback for one release cycle.

Transparency header + stats

Describe-transformed responses carry x-omniroute-modality-bridge: image->text;model=<visionModel>;parts=<n> (built by buildModalityBridgeHeader() in modalityBridge/bridgeStats.ts, stamped by withModalityBridgeHeader() in src/sse/handlers/chatHelpers.ts). Rerouted requests get no header — the payload was untouched and the model swap is already visible in the response body's model field.

GET /api/modality-bridge/stats (management auth, same tier as GET /api/settings) returns the in-memory per-modality counters { bridged, cacheHits, failures, lastUsedAt } for vision and audio. Counters reset on process restart by design (telemetry, not accounting).

Dashboard configuration

The dedicated dashboard page is /dashboard/settings/modality-bridge. Its URL-addressable Vision, Audio, and Video tabs preserve query parameters while switching the tab value. The Vision tab exposes enablement, mode, model selection (including the automatic default), task-aware prompting, advanced timeout/image/description-length/cache limits, runtime counters, and a guarded sample request. The Audio tab is also live: it exposes enablement, an STT-only model picker with Auto, timeout/max-clip limits, audio counters, and an input_audio sample test. Video remains the explicit placeholder tracked in issue #9760.

The former Vision Bridge card under AI settings is a compatibility link to the new page; it no longer owns a second copy of the form. Media Providers also links Image-to-Text and Speech-to-Text workflows to the corresponding Modality Bridge tabs without removing the existing Speech-to-Text playground.

Self-loop admission bypass: when the describe call routes through OmniRoute's own /v1 self-loop (non-standard provider model), the sub-request sends x-omniroute-admission-bypass: internal and is authenticated with the resolved self-loop credential — the local sk_omniroute sentinel in local mode, or the operator-configured OMNIROUTE_API_KEY / ROUTER_API_KEY env key (#1350) so REQUIRE_API_KEY=true deployments can still run the describe call. The bypass is only honored for those exact credentials, so external clients cannot use the header to skip admission.

Legacy defaults live in src/shared/constants/visionBridgeDefaults.ts; the new mode/task-aware/cache defaults and the settings resolver live in src/shared/constants/modalityBridgeDefaults.ts. The guardrail exposes a deps constructor option so tests can inject fake getSettings and callVisionModel implementations.

Audio Bridge (audioBridge.ts) — Modality Bridge PR-3

Intercepts audio-bearing chat requests before they reach a target that is not known to accept audio input. It never reroutes the chat request: audio parts are transcribed through the existing OpenAI-compatible multipart endpoint and the chosen chat model continues with text transcripts.

Flow:

1. Resolve supportsAudio through getResolvedModelCapabilities(). Explicit provider-registry metadata wins, then static model metadata, then synced modalities_input. A declared input list without audio is false; no capability evidence remains null. Both false and null activate the conservative bridge, while true bypasses it.
2. Resolve modalityBridgeAudio* settings and extract spliceable top-level audio parts from every message through the shared detectMediaParts() detector. Supported wire shapes are OpenAI input_audio, audio_url, and source.media_type: "audio/*". Nested audio is detected for routing but not removed by the splice path. Work is capped by modalityBridgeAudioMaxClips; later parts stay untouched.
3. Honor a configured provider/model, or let selectAudioBridgeModel() walk AUDIO_TRANSCRIPTION_PROVIDERS in stable catalog order and select the first model with a usable active provider credential.
4. callAudioTranscription() converts base64/data-URI audio to a multipart file, or downloads a remote audio_url through the public-only outbound guard with DNS pinning and a 25 MB bound. It then POSTs the file and selected model to the local /v1/audio/transcriptions self-loop, authenticated with resolveSelfLoopBearer(). The existing transcription route performs normal credential lookup, cooldown/rate-limit handling, and provider dispatch.
5. Successful calls replace their parts with [Audio N]: <transcript>. Calls run with Promise.allSettled: an individual failure preserves that original audio part (#4012 contract). If every call fails and the target is proven supportsAudio === false, the parts become [Audio N]: (unavailable — no STT provider connected) (#8430 contract). For an unknown target (null), an all-failure result stays untouched. A proven text-only target with no usable STT credential receives the same explicit stub without issuing a network call.

Successful transcripts use the process-wide Modality Bridge LRU/TTL cache. The key combines the audio reference, the stable audio-transcription operation label, and selected STT model; failures are never cached. Audio attempts update the shared bridged, cacheHits, failures, and lastUsedAt counters. Transformed responses carry x-omniroute-modality-bridge: audio->text;model=<sttModel>;parts=<n>; untouched requests do not receive an Audio Bridge segment.

Runtime settings are DB-backed and Zod-validated:

The shared cache remains controlled by modalityBridgeCacheEnabled, modalityBridgeCacheTtlMinutes, and modalityBridgeCacheMaxEntries.

PII Masker (piiMasker.ts)

Runs on both stages.

• preCall clones the payload, walks system, messages, input, and prompt (including plain string items), and applies processPII() (from @/shared/utils/inputSanitizer) to string content/text fields. When PII_REDACTION_ENABLED=true, detected PII is redacted in the outbound payload. This is independent of INPUT_SANITIZER_MODE (which only controls prompt-injection policy). When redaction is off, the call records detection counts without rewriting content.
• postCall deep-clones the response, runs sanitizePIIResponse() plus the Responses-API-shape masker (maskResponsesOutput — covers output_text and output[].content[].text). If any redaction occurs, the modified response replaces the original.

The guardrail never blocks; it only annotates (meta.detections, meta.redacted) or rewrites.

Prompt Injection (promptInjection.ts)

Detects adversarial structures in user-supplied content and enforces the configured policy. Behavior is driven by environment variables and constructor options:

Mode precedence (getMode): caller options.mode → INJECTION_GUARD_MODE DB feature-flag override (Dashboard → Settings → Feature Flags) → INJECTION_GUARD_MODE env → INPUT_SANITIZER_MODE env → warn. A dashboard override therefore wins over the env vars, so the Feature Flags UI controls the running guard live (no restart). The DB read is fail-safe: if it errors, the guard falls back to the env-based behavior, and when no override is set behavior is identical to env-only resolution.

Detection sources:

1. sanitizeRequest() from @/shared/utils/inputSanitizer (shared detector set used elsewhere in the pipeline).
2. Built-in DEFAULT_GUARD_PATTERNS (currently system_override_inline and markdown_system_block, both high severity).
3. Optional customPatterns passed via constructor options (strings, regex, or { name, pattern, severity } records).

When mode === "block" and at least one detection meets the severity threshold, preCall returns { block: true, message: "Request rejected: suspicious content detected" }. In warn/log modes the guardrail logs but allows the call. The shared helper evaluatePromptInjection() is also exported for callers that need to evaluate prompts without going through the registry.

Scan bound (v3.8.20): the detector only inspects the first 16 KB of joined prompt text — MAX_INJECTION_SCAN_BYTES = 16 * 1024 (16 384 bytes) in src/shared/utils/inputSanitizer.ts. Both detectInjection() and evaluatePromptInjection() slice(0, MAX_INJECTION_SCAN_BYTES) before running the pattern loop. Injection directives sit near the top of an input, so this caps regex CPU/GC on multi-hundred-KB payloads without weakening detection (cf. #3932, #4041).

Credential Masker (credentialMasker.ts)

Runs on both stages, last in the default chain (priority 95). Redacts well-known API-key / secret-token patterns from the outbound payload (message content, tool-call arguments, tool results) and the provider response, so a credential pasted into a prompt (or echoed back by a tool result) is not leaked to the upstream provider or back to the client.

• Opt-in only, same convention as PII redaction (Hard Rule #20-adjacent): disabled unless settings.credentialRedactionEnabled === true or CREDENTIAL_REDACTION_ENABLED=true. With it off, the guardrail is a no-op — it never blocks and never rewrites.
• redactCredentials() walks the full payload/response tree (walkValue(), prototype-pollution-safe, cycle-safe via WeakSet) and replaces matches with a [REDACTED:<type>] placeholder, cloning only the branches that actually changed.
• CREDENTIAL_PATTERNS covers LLM provider keys (OpenAI, OpenAI-proj, Anthropic, Google, Hugging Face, Replicate), VCS/SaaS tokens (GitHub, Slack, Linear, Notion, npm, Postman, Discord), payment keys (Stripe, Square), cloud keys (AWS access key, Twilio, SendGrid, Mailgun), private keys / JWTs, credential-bearing connection strings (mongodb://user:pass@..., etc.), and a generic Authorization/x-api-key/api-key/apikey header-value pattern. Header-shaped keys (authorization, x-api-key, api-key, apikey) are redacted structurally (value only, scheme prefix like Bearer /Basic preserved) rather than via the generic text regex.
• The guardrail never blocks; it only rewrites (modifiedPayload / modifiedResponse) and annotates (meta.credentialsRedacted, meta.count).

Regression guard: tests/unit/credential-masker-guardrail.test.ts.

Base Contract (base.ts)

class BaseGuardrail {
  enabled: boolean;
  name: string;
  priority: number;

  constructor(name: string, options?: { enabled?: boolean; priority?: number });

  async preCall(payload: unknown, context: GuardrailContext): Promise<GuardrailResult | void>;

  async postCall(response: unknown, context: GuardrailContext): Promise<GuardrailResult | void>;
}

interface GuardrailResult<TValue = unknown> {
  block?: boolean; // true short-circuits the chain
  message?: string; // surfaced when blocking
  meta?: Record<string, unknown> | null;
  modifiedPayload?: TValue; // returned by preCall to rewrite the request
  modifiedResponse?: TValue; // returned by postCall to rewrite the response
}

interface GuardrailContext {
  apiKeyInfo?: Record<string, unknown> | null;
  disabledGuardrails?: string[] | null;
  endpoint?: string | null;
  headers?: Headers | Record<string, unknown> | null;
  log?: GuardrailLog | Console | null;
  method?: string | null;
  model?: string | null;
  provider?: string | null;
  sourceFormat?: string | null;
  stream?: boolean;
  targetFormat?: string | null;
}

A guardrail signals "no change" by returning either void, {}, or { block: false }. Returning a modifiedPayload/modifiedResponse replaces the value flowing through the chain for downstream guardrails.

Registry (registry.ts)

The singleton guardrailRegistry exposes:

• register(guardrail) — adds (or replaces by normalized name) a guardrail and re-sorts by ascending priority.
• clear() / list() — administrative helpers.
• runPreCallHooks(payload, context) — iterates active guardrails, threads the payload through modifiedPayload, and stops on the first block: true.
• runPostCallHooks(response, context) — same flow on the response side.
• resetGuardrailsForTests({ registerDefaults }) — clears state and optionally re-registers the defaults for clean test isolation.

Both runners return { blocked, payload|response, results, guardrail?, message? } where results is an array of GuardrailExecutionResult records that include per-guardrail blocked, skipped, modified, error, and meta fields, useful for tracing.

Disabling Guardrails Per-Request

resolveDisabledGuardrails({ apiKeyInfo, body, headers }) aggregates a de-duplicated list of guardrail names that should be skipped for the current request. Sources (all optional, all merged):

• apiKeyInfo.disabledGuardrails
• Request body disabledGuardrails (top-level)
• Request body metadata.disabledGuardrails
• Header x-omniroute-disabled-guardrails (or legacy x-disabled-guardrails)

Values may be arrays of strings or a comma-separated string; names are normalized to lowercase kebab-case (pii_masker → pii-masker). The result is passed through context.disabledGuardrails to the registry, which skips matching guardrails (skipped: true in results).

Execution Order

For each request flowing through src/sse/handlers/chat.ts and open-sse/handlers/chatCore.ts:

1. resolveDisabledGuardrails(...) builds the skip list from API key, body, and headers.
2. guardrailRegistry.runPreCallHooks(body, ctx) runs guardrails in ascending priority order:
   • Disabled guardrails are recorded as skipped.
   • Each guardrail's preCall may rewrite the payload via modifiedPayload.
   • The first block: true short-circuits the chain and the handler returns a guardrail rejection response.
3. The (potentially rewritten) payload flows into combo routing and upstream dispatch.
4. After the response is assembled, guardrailRegistry.runPostCallHooks(...) runs the same chain on the response. block: true here drops the upstream response.

Guardrails that throw are recorded with error: <message> and logged via logger.warn, but the chain continues — fail-open by design.

Configuration

Environment variables read by the built-in guardrails:

The Modality Bridge guardrails read runtime config from the DB-backed settings store (getSettings()), not env vars. Vision's primary keys are modalityBridgeVisionEnabled, modalityBridgeVisionMode, modalityBridgeVisionModel, modalityBridgeVisionTaskAware, modalityBridgeVisionPrompt, modalityBridgeVisionTimeout, modalityBridgeVisionMaxImages, modalityBridgeVisionMaxChars, modalityBridgeCacheEnabled, modalityBridgeCacheTtlMinutes, and modalityBridgeCacheMaxEntries. The legacy visionBridge* keys are accepted only as the documented one-cycle read fallback; dashboard writes use the primary keys. Defaults and the fallback resolver live in src/shared/constants/modalityBridgeDefaults.ts, with legacy constants retained in src/shared/constants/visionBridgeDefaults.ts.

Audio uses modalityBridgeAudioEnabled, modalityBridgeAudioModel, modalityBridgeAudioTimeout, and modalityBridgeAudioMaxClips, plus the shared modalityBridgeCache* settings. Audio has no legacy-key fallback because these keys were introduced with the Modality Bridge schema.

Custom Guardrails

import { BaseGuardrail, guardrailRegistry } from "@/lib/guardrails";

class BudgetGuardrail extends BaseGuardrail {
  constructor() {
    super("budget", { priority: 50 });
  }

  async preCall(payload, ctx) {
    if (ctx.apiKeyInfo?.budgetExceeded) {
      return { block: true, message: "Daily budget exceeded" };
    }
    return { block: false };
  }
}

guardrailRegistry.register(new BudgetGuardrail());

Steps:

1. Create src/lib/guardrails/myGuardrail.ts extending BaseGuardrail.
2. Implement preCall and/or postCall.
3. Either register at import time (push from registerDefaultGuardrails) or call guardrailRegistry.register(...) at runtime — the registry replaces any prior guardrail with the same normalized name.
4. Add tests under tests/unit/ (existing examples: tests/unit/guardrails-registry.test.ts, tests/unit/prompt-injection-guard.test.ts, tests/unit/guardrails/visionBridge.test.ts).

Testing

Use resetGuardrailsForTests() between tests to start from a known state. Pass { registerDefaults: false } to start with an empty registry and register only the guardrails under test. Vision Bridge accepts dependency injection (deps.getSettings, deps.callVisionModel); Audio Bridge exposes the equivalent seams for settings, capabilities, STT model selection, credential checks, and transcription. Tests can therefore exercise both flows without DB or network access.

See Also

• src/lib/guardrails/ — implementation
• src/shared/utils/inputSanitizer.ts — shared detector that powers prompt-injection and PII masking
• src/shared/constants/visionBridgeDefaults.ts — Vision Bridge defaults and forced-bridge model list
• src/shared/constants/modalityBridgeDefaults.ts — shared Vision/Audio runtime defaults
• docs/architecture/RESILIENCE_GUIDE.md — orthogonal layer (circuit breaker, cooldowns)
• docs/reference/ENVIRONMENT.md — full env var reference

Injection-guard route coverage & red-team (Phase 8 · Block D)

The injection-guard (createInjectionGuard / withInjectionGuard) covers all routes that accept user prompts. It respects INJECTION_GUARD_MODE (default warn = log only; block = returns HTTP 400 SECURITY_001).

Text extraction (extractMessageContents) covers messages/input/prompt/query+documents/instructions/system.

Red-team (nightly, nightly-llm-security.yml): promptfoo validates that each route blocks the OWASP-LLM corpus in INJECTION_GUARD_MODE=block; garak runs probes (skips without secret). moderations is included for consistency — operators in block-mode can exempt it via resolveDisabledGuardrails.

The nightly workflow (.github/workflows/nightly-llm-security.yml, cron + manual dispatch) has two jobs:

• promptfoo-guard (blocking) — runs promptfoo eval -c promptfooconfig.yaml with INJECTION_GUARD_MODE=block. Each adversarial case (e.g. "ignore all previous instructions…", DAN-style jailbreaks) asserts the response carries error.code === "SECURITY_001", i.e. the guard actually rejected the request.
• garak (advisory) — runs garak --probes promptinject,dan,leakreplay against a local OmniRoute instance (http://localhost:20128/v1). Gated on a provider secret (PROMPTFOO_PROVIDER_KEY); skips gracefully and is suffixed || true, so it reports without failing CI.

Coverage of the guard helper (createInjectionGuard / withInjectionGuard) spans every prompt-bearing /v1 route; prompt text is pulled from messages/input/prompt/query+documents/instructions/system by extractMessageContents() in src/shared/utils/inputSanitizer.ts.