---
title: CORS Configuration & Security
---

# CORS Configuration & Security

OmniRoute controls which **browser origins** may read cross-origin responses
from a single, centralized allowlist. The model is **fail-closed by default**:
no origin is allowed until you opt one in. This page documents how the allowlist
resolves, what `CORS_ALLOW_ALL=true` actually exposes (and, importantly, what it
does **not**), how to configure dev vs production safely, and the runtime warning
the dashboard shows when a wildcard is live.

**Source of truth:** `src/server/cors/origins.ts` (`resolveAllowedOrigin`,
`applyCorsHeaders`, `getCorsStatus`). The allowlist is applied once, in the
middleware (`src/server/authz/pipeline.ts`) — per-route handlers do not set
`Access-Control-Allow-Origin` themselves.

## How an origin is resolved

For each request the middleware computes the `Access-Control-Allow-Origin` value
in this order:

1. **`CORS_ALLOW_ALL=true`** (or the legacy `CORS_ORIGIN=*`) → echo the caller's
   `Origin` back (or `*` when there is no `Origin` header), with `Vary: Origin`
   so caches stay correct.
2. Otherwise, the request `Origin` is normalized (lower-cased, trailing slash
   stripped) and matched against the **merged allowlist**:
   - env **`CORS_ALLOWED_ORIGINS`** — comma-separated list, and
   - the runtime **`corsOrigins`** setting (Dashboard → Security → _CORS Allowed
     Origins_), injected via `setRuntimeAllowedOrigins()` from
     `src/lib/config/runtimeSettings.ts`.
3. No match → **no `Access-Control-Allow-Origin` header is emitted**. The browser
   blocks the cross-origin read. This is the intended fail-closed default.

| Env var                | Meaning                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `CORS_ALLOWED_ORIGINS` | CSV of exact origins to allow (recommended).                                         |
| `CORS_ALLOW_ALL`       | `true`/`1` → echo any origin (wildcard). Dev only.                                   |
| `CORS_ORIGIN`          | Legacy. `*` behaves like `CORS_ALLOW_ALL`; a single value is added to the allowlist. |

## Threat model — what `CORS_ALLOW_ALL=true` really exposes

The generic OWASP warning ("wildcard CORS = any site can call your API") is worth
taking seriously, but OmniRoute's exposure is **narrower than the generic case**,
because of one concrete implementation fact:

> **The central `applyCorsHeaders()` never emits
> `Access-Control-Allow-Credentials`.** A browser will not expose a _credentialed_
> (cookie-bearing) cross-origin response unless the server sends
> `Access-Control-Allow-Credentials: true`. OmniRoute's shared CORS path never
> does.

What that means per surface, even with `CORS_ALLOW_ALL=true`:

| Surface                             | Auth mechanism              | Effect of wildcard CORS                                                                                                                                                                                                          |
| ----------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dashboard / MANAGEMENT `/api/*`     | Cookie session              | Origin is echoed, but **without `Allow-Credentials`** the browser **blocks** the credentialed read. A malicious cross-origin site **cannot read** your authenticated dashboard responses, and the session cookie is not exposed. |
| Client API `/v1/*`, `/v1beta/*`     | Bearer / `x-api-key` header | Already permissive **by design** (`relaxForTokenAuth`): browsers never auto-attach `Authorization`/`x-api-key`, so an attacker's page cannot supply your key. `CORS_ALLOW_ALL` does not widen this.                              |
| Public read-only (`/api/health`, …) | None                        | Non-sensitive; wildcard is harmless.                                                                                                                                                                                             |

So the **residual** exposure of `CORS_ALLOW_ALL=true` is limited to: (a)
non-credentialed cross-origin **reads** of already-unauthenticated data, and (b)
letting CORS **preflight pass** on management routes — which still require auth
that a cross-origin page cannot provide. It is **not** a session-hijack or
credential-theft vector on the shared CORS path.

### One genuine exception — `/api/v1/agents/`

The Cloud-Agent routes (`/api/v1/agents/{health,credentials,tasks,tasks/[id]}`) set
their **own** CORS headers
(`src/lib/cloudAgent/api.ts`, `getCloudAgentCorsHeaders`) and **do** emit
`Access-Control-Allow-Origin: <origin>|*` together with
`Access-Control-Allow-Credentials: true`. This is the single surface where
origin-echo and credentials coexist, and it is **independent of
`CORS_ALLOW_ALL`**. These routes are management-authenticated
(`requireManagementAuth`); operators who expose the dashboard off-host should be
aware that this is the one place a cross-origin credentialed read is permitted by
the response headers. Tightening it to an explicit allowlist is tracked
separately from this CORS guidance.

## Production checklist

- **Never set `CORS_ALLOW_ALL=true` in production.** Leave it unset.
- Set an **explicit** origin list — either the env var or the Security-tab field:

  ```bash
  CORS_ALLOWED_ORIGINS="https://app.example.com, https://admin.example.com"
  ```

- If OmniRoute runs behind a reverse proxy / tunnel (nginx, Caddy, Cloudflare
  Tunnel, Tailscale), CORS is **not** your only control — the loopback route
  guard still protects spawn-capable routes (see
  [ROUTE_GUARD_TIERS](./ROUTE_GUARD_TIERS.md)). Do not forge
  `X-Forwarded-For: 127.0.0.1` to "fix" a 403; that re-opens the RCE class the
  route guard closes.
- Confirm the runtime state: the dashboard shows a **persistent amber banner**
  under Dashboard → Security → Authorization Inventory whenever
  `CORS_ALLOW_ALL=true` is live, and `/api/settings/authz-inventory` returns a
  `cors: { allowAll, allowedOrigins }` envelope monitoring tools can poll.

## Development convenience — allow specific local origins

You rarely need the wildcard even in dev. Allow just the dev servers you use:

```bash
# Vite (5173) + Next.js (3000) dev servers calling a local OmniRoute
CORS_ALLOWED_ORIGINS="http://localhost:5173, http://localhost:3000"
```

Origins are matched case-insensitively with the trailing slash ignored, so
`http://localhost:3000` and `http://localhost:3000/` are equivalent. The same CSV
can be set at runtime in **Dashboard → Security → CORS Allowed Origins** without a
restart.

## API keys vs cookie sessions

- **Bearer / `x-api-key` (the `/v1/*` inference surface):** browsers never attach
  these automatically. CORS is not a meaningful barrier here — the API key is the
  barrier — which is why that surface is intentionally permissive so browser and
  Electron clients can read responses they are already entitled to.
- **Cookie session (the dashboard):** protected by the fail-closed default **and**
  by the absence of `Access-Control-Allow-Credentials` on the shared path. Keep
  management/dashboard origins out of any permissive config; they must stay exactly
  fail-closed.

## Example: reverse proxy in front of OmniRoute

CORS is enforced by OmniRoute itself, so the proxy generally should **not** add or
rewrite `Access-Control-*` headers (double headers break browsers). Terminate TLS
and forward — let OmniRoute answer preflight:

```nginx
# nginx — forward to OmniRoute; do NOT inject Access-Control-* here
location / {
    proxy_pass http://127.0.0.1:20128;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Do NOT set X-Forwarded-For to 127.0.0.1 — it defeats the loopback route guard.
}
```

Set the allowed browser origins in OmniRoute (`CORS_ALLOWED_ORIGINS` or the
Security tab), not in the proxy.

## Source files

| Concern                                         | File                                                                 |
| ----------------------------------------------- | -------------------------------------------------------------------- |
| Allowlist resolution + `getCorsStatus()`        | `src/server/cors/origins.ts`                                         |
| Middleware application (single source of truth) | `src/server/authz/pipeline.ts`                                       |
| Settings → runtime origin injection             | `src/lib/config/runtimeSettings.ts`                                  |
| Runtime status for the dashboard                | `src/app/api/settings/authz-inventory/route.ts`                      |
| Dashboard warning banner                        | `src/app/(dashboard)/dashboard/settings/components/AuthzSection.tsx` |
| CORS Allowed Origins field                      | `src/app/(dashboard)/dashboard/settings/components/SecurityTab.tsx`  |
| Cloud-Agent per-route CORS (the exception)      | `src/lib/cloudAgent/api.ts`                                          |

## See also

- [Route Guard Tiers](./ROUTE_GUARD_TIERS.md) — loopback enforcement for
  spawn-capable routes (a separate, complementary control).
- [Authorization Guide](../architecture/AUTHZ_GUIDE.md) — the full auth pipeline.