OmniRoute/docs/security/GUARDRAILS.md

title, version, lastUpdated

title	version	lastUpdated
Guardrails	3.8.50	2026-08-14

Guardrails

Source of truth: src/lib/guardrails/ Last updated: 2026-08-15 — v3.8.50 (Video Bridge broker confinement)

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 six guardrails in priority order on import (see registry.ts → registerDefaultGuardrails()):

Priority	Name	Stage(s)	File
5	vision-bridge	preCall	visionBridge.ts
6	audio-bridge	preCall	audioBridge.ts
7	video-bridge	preCall	videoBridge.ts
10	pii-masker	pre + post	piiMasker.ts
20	prompt-injection	preCall	promptInjection.ts
95	credential-masker	pre + post	credentialMasker.ts

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)

Mode	Default	Behavior
auto	✔	Legacy heuristic, untouched (#6640/#7204): non-combo/auto/ models reroute to the best vision model unless the original model already has usable credentials (then describe); combo targets always describe.
describe		Always describe — the reroute block is skipped entirely; the user's chosen model always answers.
reroute		Force reroute: the keep-credentialed-model guard is bypassed. The reroute-target credential guard still applies — when no usable vision target exists, the request falls through to describe so raw images never reach a text-only backend (#8430).

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)

Key	Default	Range
modalityBridgeVisionMaxChars	0	0 or 100–50000

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:

Key	Default	Range
modalityBridgeCacheEnabled	true	—
modalityBridgeCacheTtlMinutes	60	1–1440
modalityBridgeCacheMaxEntries	200	10–5000

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 { attempts, successes, bridged, cacheHits, failures, totalLatencyMs, latencySamples, averageLatencyMs, lastUsedAt } for vision, audio, and video. averageLatencyMs uses latencySamples, not all attempts, as its denominator; an operation without timing does not fabricate a zero-millisecond sample. bridged remains the backward-compatible alias for successful conversions; failed attempts do not increment it. 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. The Video tab is functional: it reports the FFmpeg/ffprobe runtime state, persists enable/model/frame/video/timeout limits, filters the model picker to vision-capable models, and exposes video counters.

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:

Key	Default	Range
modalityBridgeAudioEnabled	true	—
modalityBridgeAudioModel	""	Auto or STT ID
modalityBridgeAudioTimeout	60000	1000–300000
modalityBridgeAudioMaxClips	3	1–10

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

Video Bridge (videoBridge.ts)

Intercepts top-level video parts in Chat Completions messages and Responses API input before a target without known native video support is called. Supported shapes are input_video, video_url, video_source, HTTPS URLs, and data:video/*;base64,... data URIs. Plain filenames in text are not treated as video.

The public /v1 request path never imports or invokes a subprocess. Remote videos are downloaded under a 50 MiB bound; inline base64 videos have a conservative 36 MiB decoded per-video cap so the model/messages/framing envelope can remain inside the public JSON request admission limit of 50 MiB. Inline length and decoded-size estimates are checked before allocation. HTTPS is required on the initial remote URL and every redirect, using the existing public-only outbound guard with DNS pinning. The bytes then cross the exact internal POST /api/modality-bridge/video/extract broker boundary. That route is both LOCAL_ONLY and SPAWN_CAPABLE, accepts only a per-process authenticated, trusted-loopback request, and never accepts a URL, filesystem path, executable, or argument list. The API body-size pipeline and the handler's incremental body reader independently enforce a 50 MiB broker input cap. Its bounded queue runs one extraction at a time, allows four pending jobs, and caps pending input at 100 MiB.

Inside the broker, ffprobe reads a private local file; the fixed format allowlist excludes playlist and manifest formats. For allowed MOV-family containers, external MOV data references remain disabled by default, and the fixed command does not opt in to them. Both ffprobe and ffmpeg use the file-only protocol whitelist, one thread, fixed argument arrays, no shell, and executables resolved from PATH. Attached-picture cover streams are not playable candidates. All playable streams must satisfy the limits, and an explicit default stream is preferred before the deterministic lowest-index fallback. Videos are limited to 600 seconds, 8,192 pixels per dimension, and 33,554,432 source pixels. FFmpeg samples 1–16 midpoint JPEG frames, scales down the long edge to at most 1,024 pixels without upscaling smaller inputs, and never receives a URL. Each frame is limited to 4 MiB, all raw frames together to 23 MiB, and the serialized broker response to 32 MiB. A private temporary directory is removed in finally. OmniRoute does not bundle FFmpeg and does not accept a custom executable path.

Frames are captioned sequentially with the configured Video model. An empty Video override inherits the Vision setting; if both are empty, the Vision auto-router selects the effective vision-capable model. Successful captions replace the original part with a stable [Video description: prefix that also marks the text as an untrusted media-derived observation and tells downstream models not to follow instructions found in the media. Frame-caption cache keys include the JPEG bytes, prompt, timestamp, and effective model; only successful captions are cached. Cache entries retain the actual successful producer model, including a fallback model; the bridge reports mixed when different frames were produced by different models. A cache hit reuses that producer identity instead of relabeling it as the requested routing plan.

The guardrail extracts every supported video part but describes no more than modalityBridgeVideoMaxVideos. For a target proven to have supportsVideo === false, failed and over-limit videos become explicit safe text markers so no raw video survives. When capability is unknown, those parts remain untouched. Targets with supportsVideo === true bypass the bridge. The client request abort signal propagates through download, broker queue, subprocesses, and caption calls; aborts stop between videos and never fail open to raw media.

Runtime settings are DB-backed and Zod-validated:

Key	Default	Range / behavior
modalityBridgeVideoEnabled	false	Optional runtime, opt-in
modalityBridgeVideoModel	""	Inherit the Vision Bridge model
modalityBridgeVideoFrameCount	8	1–16
modalityBridgeVideoMaxVideos	1	1–4
modalityBridgeVideoTimeout	120000	1000–120000 ms

Legacy persisted Video timeout values above 120 seconds are clamped to the broker deadline; new settings writes above that limit are rejected. GET /api/modality-bridge/video/runtime requires trusted stamped loopback locality before authentication or runtime probing, then requires management auth. It returns only available, sanitized FFmpeg/ffprobe versions, and a fixed reason when the runtime is unavailable. The internal extraction endpoint is not a public upload API: queue saturation returns 503 plus Retry-After, a caller disconnect returns 499, and the fixed broker deadline returns 504. Converted responses add video->text;model=<visionModel>;parts=<videos> to the central x-omniroute-modality-bridge header without removing Vision or Audio segments.

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:

Setting	Env var	Default	Effect
Enabled	INPUT_SANITIZER_ENABLED	true	When false, guardrail short-circuits.
Mode	INJECTION_GUARD_MODE / INPUT_SANITIZER_MODE	warn	Injection policy: block, warn, or log. (redact is accepted for back-compat but does not strip injection text; request PII rewrite is controlled by PII_REDACTION_ENABLED.)
Block threshold	blockThreshold option / INPUT_SANITIZER_BLOCK_THRESHOLD (alias INJECTION_GUARD_BLOCK_THRESHOLD)	high	Minimum severity required to block. Medium is observe-only at default.

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;
  signal?: AbortSignal;
  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. signal?: AbortSignal carries the caller lifecycle into guardrails. A request abort is the deliberate fail-open exception: media bridges stop work and cleanup without restoring raw media to a target known not to support it.

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:

Variable	Used by	Effect
INPUT_SANITIZER_ENABLED	prompt-injection	Set false to disable detection entirely.
INPUT_SANITIZER_MODE	prompt-injection	Injection policy: warn, block, or log. Legacy value redact does not rewrite injection text.
INJECTION_GUARD_MODE	prompt-injection	Mode for the injection guard; also a DB feature flag that overrides the env vars (DB > ENV).
INPUT_SANITIZER_BLOCK_THRESHOLD	prompt-injection	Minimum severity that MODE=block rejects: high (default), medium, or low.
INJECTION_GUARD_BLOCK_THRESHOLD	prompt-injection	Legacy alias for INPUT_SANITIZER_BLOCK_THRESHOLD.
PII_REDACTION_ENABLED	pii-masker	When true, request PII is redacted (independent of injection mode).
PII_RESPONSE_SANITIZATION / _MODE	pii-masker (downstream)	Controls response-side masker behavior.

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.

Video uses modalityBridgeVideoEnabled, modalityBridgeVideoModel, modalityBridgeVideoFrameCount, modalityBridgeVideoMaxVideos, and modalityBridgeVideoTimeout, plus the shared modalityBridgeCache* settings. It is disabled by default because FFmpeg/ffprobe are optional operational dependencies and frame captioning adds latency and model cost.

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).

Type	Routes	Default mode
Text (existing)	/v1/chat/completions, /v1/completions, /v1/relay/chat/completions	warn
Generative	/v1/messages, /v1/responses, /v1/images/generations, /v1/images/edits, /v1/videos/generations, /v1/music/generations, /v1/audio/speech	warn
Data	/v1/embeddings, /v1/rerank, /v1/search, /v1/moderations	warn

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.