If you discover a security vulnerability in OmniRoute, please report it responsibly:

1. DO NOT open a public GitHub issue
2. Use GitHub Security Advisories
3. Include: description, reproduction steps, and potential impact

After 3.8.59 the next version is 3.9.0, which opens the long-term support line on the stable/v3 branch (see ROADMAP.md → "Phase 3 — v3.9.0 LTS").

• What stable/v3 receives: bug fixes, security patches and provider updates. New features go to the v4 channel; the LTS line is stability-first. npm install omniroute (the latest dist-tag) stays on v3 during the whole v4 cycle.
• Window duration: stable/v3 receives security fixes and critical regressions for 12 months after the 3.9.0 cut, or until 90 days after v4.0.0 is published as latest — whichever is later. The resulting end date is recorded in the 3.9.0 release notes and in ROADMAP.md when the cut happens.
• Reporting a vulnerability in the LTS line: same channel as any other version — a private GitHub Security Advisory, never a public issue. Say which version you tested (for example 3.9.2); fixes land on stable/v3 and are forward-ported to v4.
• Security baseline at the LTS cut: measured scanner state, route-guard and public-credential proofs are recorded in docs/security/LTS_SECURITY_BASELINE.md.

OmniRoute implements a multi-layered security model:

Request → CORS → Authz pipeline (classify → policies → enforce)
       → Guardrails (PII masker, prompt injection, vision bridge)
       → Rate Limiter → Circuit Breaker → Cooldown → Model Lockout → Provider

All sensitive data stored in SQLite is encrypted using AES-256-GCM with scrypt key derivation:

• API keys, access tokens, refresh tokens, and ID tokens
• Versioned format: enc:v1:<iv>:<ciphertext>:<authTag>
• Passthrough mode (plaintext) when STORAGE_ENCRYPTION_KEY is not set

# Generate encryption key:
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)

OmniRoute ships a hot-reloadable guardrails registry (src/lib/guardrails/) with 3 built-in guardrails ordered by priority:

Custom guardrails register via registerGuardrail(new MyGuardrail()). The model is fail-open (exceptions never block traffic). Per-request opt-out via x-omniroute-disabled-guardrails header. → See docs/security/GUARDRAILS.md.

Best-effort heuristic middleware that detects prompt injection patterns in LLM requests. Not a complete prompt-injection firewall — can produce false positives (benign persona/RPG prompts) and false negatives (leetspeak, spacing, non-English patterns).

Only High severity detections are blocked in block mode. Medium-severity families are logged but never blocked by sanitizeRequest.

Configure via dashboard (Settings → Security) or .env:

INPUT_SANITIZER_ENABLED=true
INPUT_SANITIZER_MODE=block    # warn | block (injection policy; legacy "redact" does not strip injection text)
INPUT_SANITIZER_BLOCK_THRESHOLD=high  # high (default) | medium | low — severities at/above this are blocked in block mode

Automatic detection and optional redaction of personally identifiable information:

PII_REDACTION_ENABLED=true   # request PII rewrite; independent of INPUT_SANITIZER_MODE
PII_RESPONSE_SANITIZATION=true  # optional: redact PII in provider responses returned to clients

All secrets must be set before starting the server. The server will fail fast if they are missing or weak.

# REQUIRED — server will not start without these:
JWT_SECRET=$(openssl rand -base64 48)     # min 32 chars
API_KEY_SECRET=$(openssl rand -hex 32)    # min 16 chars

# RECOMMENDED — enables encryption at rest:
STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)

The server actively rejects known-weak values like changeme, secret, or password.

• Use non-root user in production
• Mount secrets as read-only volumes
• Never copy .env files into Docker images
• Use .dockerignore to exclude sensitive files
• Set AUTH_COOKIE_SECURE=true when behind HTTPS

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --read-only \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  -e JWT_SECRET="$(openssl rand -base64 48)" \
  -e API_KEY_SECRET="$(openssl rand -hex 32)" \
  -e STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  diegosouzapw/omniroute:latest

• Run npm audit regularly (npm run audit:deps covers main + electron)
• Keep dependencies updated
• The project uses husky + lint-staged for pre-commit checks (lint-staged + check-docs-sync + check:any-budget:t11)
• CI pipeline runs ESLint security rules on every push (no-eval, no-implied-eval, no-new-func = error)
• Provider constants validated at module load via Zod (src/shared/validation/schemas.ts)
• Secure-by-default libraries used: dompurify / isomorphic-dompurify (XSS), jose (JWT), better-sqlite3 (no SQLi risk via parameterized queries), bcryptjs (password hashing)

These rules are enforced by tooling and reviewers:

1. Never commit secrets — .env is gitignored; .env.example is the template (no literals, comments only — see PUBLIC_CREDS.md below)
2. Never use eval(), new Function(), or implied eval — ESLint enforces
3. Never bypass Husky hooks (--no-verify, --no-gpg-sign) without explicit operator approval
4. Never write raw SQL in routes — always go through src/lib/db/ (parameterized)
5. Always validate inputs with Zod — src/shared/validation/schemas.ts
6. Always sanitize upstream headers — denylist in src/shared/constants/upstreamHeaders.ts
7. Encrypt credentials at rest — AES-256-GCM via src/lib/db/encryption.ts
8. Public upstream OAuth identifiers via resolvePublicCred() — never embed AIza… / GOCSPX-… / …apps.googleusercontent.com literals in source. See docs/security/PUBLIC_CREDS.md.
9. Error responses through buildErrorBody() / sanitizeErrorMessage() — never put raw err.stack / err.message in HTTP / SSE / executor / MCP response bodies. See docs/security/ERROR_SANITIZATION.md.
10. exec() / spawn() runtime values via the env option — never string-interpolate external paths or untrusted values into shell-passed scripts. Reference: src/mitm/cert/install.ts::updateNssDatabases.
11. Prefer secure-by-default libraries — see tldrsec/awesome-secure-defaults (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). Reach for them before rolling your own.

Scope note: socket.yml at the repository root only shapes projectIgnorePaths for Socket.dev's registry-side post-publish scan of the published npm artifact — it is not an enforced CI/PR merge gate. No workflow in .github/workflows, no package.json script, and no Makefile target invokes Socket.dev.

The published omniroute npm artifact bundles the Next.js output: "standalone" build, which means every route handler — including documented privileged features (MITM, Zed import, Cloud Sync, embedded service supervisor) — ends up in .next/server/*.js minified chunks. Heuristic supply-chain scanners frequently pattern-match those chunks against malware signatures.

The scanner configuration we use lives at socket.yml in the repo root (Socket.dev GitHub App format v2 — see https://docs.socket.dev/docs/socket-yml). It explicitly excludes non-shipped directories (tests/, _tasks/, _references/, _ideia/, _mono_repo/, docs/, etc.) so the scanner only reports on code paths that actually reach published users — the scan itself is driven by the Socket GitHub App reading that file, not by a workflow in this repository.

For each finding category we maintain a per-finding maintainer attestation:

• docs/security/SOCKET_DEV_FINDINGS.md — per-finding map: source file ↔ flagged chunk ↔ behaviour ↔ mitigation applied in v3.8.6.
• In-source SECURITY-AUDITOR-NOTE: blocks at each flagged function point back to the same document.

For users whose pipeline cannot relax the alert: build with OMNIROUTE_BUILD_PROFILE=minimal npm run build. That replaces the four sensitive modules with stubs that return HTTP 503 feature-disabled at runtime, so the privileged code paths are physically absent from the bundle. See docs/security/SOCKET_DEV_FINDINGS.md for the publishing recipe.

• docs/architecture/AUTHZ_GUIDE.md — authorization pipeline
• docs/security/GUARDRAILS.md — guardrails framework
• docs/security/COMPLIANCE.md — audit log and retention
• docs/security/PUBLIC_CREDS.md — mandatory pattern for public upstream credentials
• docs/security/ERROR_SANITIZATION.md — mandatory pattern for error responses
• docs/security/SOCKET_DEV_FINDINGS.md — maintainer attestation for supply-chain scanner findings
• docs/architecture/RESILIENCE_GUIDE.md — circuit breaker + cooldown + lockout
• docs/security/STEALTH_GUIDE.md — TLS fingerprinting (legal/ethical notice)
• CLAUDE.md — hard rules for AI agents
• tldrsec/awesome-secure-defaults — curated secure-by-default libraries