OmniRoute/docs/security/BAN_DETECTION.md

title

title
Account-Ban / Banned-Keyword Detection

Account-Ban / Banned-Keyword Detection

OmniRoute scans upstream error responses for signals that indicate a provider account is permanently dead (suspended / deactivated / ToS-banned) and, when matched, moves that connection into a terminal banned state so it is no longer selected for requests. This is what the Security → Banned Keywords settings card configures ("Additional keywords that trigger permanent account ban detection. Built-in keywords always apply.").

This page documents the built-in list, the detection flow, its scope, how to add custom keywords safely, and how to recover a flagged connection. The terminal state itself is part of the resilience model — see RESILIENCE_GUIDE ("Terminal states").

Source of truth: open-sse/services/accountFallback.ts (ACCOUNT_DEACTIVATED_SIGNALS, getMergedBannedSignals(), isAccountDeactivated()).

Built-in keywords

These 8 substrings always apply (case-insensitive), regardless of any custom list:

account_deactivated
account has been deactivated
account has been disabled
your account has been suspended
this account is deactivated
verify your account to continue                                 (Antigravity / Google Cloud Code)
this service has been disabled in this account for violation    (Antigravity)
this service has been disabled in this account                  (Antigravity)

This list evolves as providers change their ban wording. The authoritative copy is ACCOUNT_DEACTIVATED_SIGNALS in open-sse/services/accountFallback.ts; treat the block above as a snapshot.

Two adjacent, separate signal tables live in the same file and are not part of banned-keyword detection:

• CREDITS_EXHAUSTED_SIGNALS — billing/quota depleted (insufficient_quota, credit_balance_too_low, payment required, …) → terminal credits_exhausted.
• OAUTH_INVALID_TOKEN_SIGNALS — non-terminal; a token refresh can recover.

Note: common transient phrases like rate limit / 429 are handled by the rate-limit / connection-cooldown path and are not ban signals.

Detection flow

upstream error response
  → body stringified + lowercased
  → isAccountDeactivated(body): getMergedBannedSignals().some(sig => body.includes(sig))   [substring match]
  → match?
      → connection testStatus = "banned"      (permanent — 1-year cooldown, never auto-recovers)
      → if setting `autoDisableBannedAccounts` is on and `autoDisableBannedScope`
        includes this connection (`all`, or `subscription` for OAuth/cookie/session)
        → also isActive = false. Prepaid API keys stay active when scope is
        `subscription`.
      → connection is skipped during account selection (combo QUOTA_BLOCKING statuses)

• The match is a case-insensitive substring search on the response body (isAccountDeactivated, accountFallback.ts).
• The permanent banned terminalization fires on a banned-signal body at any HTTP status (via markAccountUnavailable → checkFallbackError). The narrower deactivated label (isActive=false when the connection has no spare API keys) is written by the inline chatCore.ts path on HTTP 401 / 403 (classified via classifyProviderError → ACCOUNT_DEACTIVATED). Note the markAccountUnavailable() path writes a different terminal status — expired — for the same ACCOUNT_DEACTIVATED signal (via resolveTerminalConnectionStatus), so the same ban can surface as either deactivated or expired depending on which path handled the response. (The older code comment says "when a 401 body contains these strings" — that understates the current behavior.)
• A banned connection is excluded from selection everywhere terminal statuses are filtered (isTerminalConnectionStatus, combo QUOTA_BLOCKING_CONNECTION_STATUSES).

Scope — which providers are scanned

All providers. The check runs in the generic error-handling pipeline that every failed upstream request flows through — it is not gated to OAuth/subscription scrapers. The resulting terminal state is per connection, not per provider.

That said, the built-in strings are oriented toward subscription/OAuth providers with real ban risk (ChatGPT Web Codex, Claude Web, Codex, Muse Spark, Antigravity). An API-key provider will only trip the detector if its error body literally contains one of the substrings.

autoDisableBannedScope (all | subscription, default all) controls whether a match also flips isActive=false. subscription means login-style seats (paid subscriptions and free accounts, including web-cookie sessions). It still records testStatus=banned for prepaid API keys but leaves them in the routing pool. The durable design is a per-provider and per-account override; the global enum is the first cut.

Custom banned keywords

Add or remove keywords in Security → Banned Keywords (persisted as the global customBannedSignals setting via PATCH /api/settings). They are added to the built-in list — never a replacement — and hot-reload on save (and at startup) via setCustomBannedSignals(). Each keyword is capped at 200 characters; there is no array-length limit.

⚠ False-positive risk — choose specific phrases. Detection is a raw substring match on the whole response body, and a match is permanent (1-year cooldown, manual recovery). A broad keyword can ban a perfectly healthy connection:

• Bad: quota, limit, error, denied — appear in many transient errors.
• Good: full ban sentences, e.g. your account has been suspended for, account permanently banned, violation of our terms.

Prefer the longest unambiguous phrase the provider returns on a real ban. When in doubt, watch the connection's lastError first, then add the exact wording.

Recovering a flagged connection

Terminal banned / deactivated states never auto-recover (they are excluded from the proactive-recovery tick — only unavailable cooldowns recover on their own). An operator must clear them explicitly:

1. Re-test the connection — the dashboard Test action (POST /api/providers/{id}/test); a successful probe resets testStatus to active and clears the error fields.
2. Re-authenticate / edit credentials — for OAuth providers, re-run the login / refresh flow; provider create/import routes set isActive = true.
3. Re-enable the connection — if auto-disable set isActive = false (scope all, or subscription for an OAuth/cookie/session connection), toggle it back on after fixing the account.

There is no separate "clear ban flag" button — recovery is re-test, re-auth, or re-enable, matching the general terminal-state rule in RESILIENCE_GUIDE.

Probe isolation (model test-all)

A probe-origin failure (model test-all / health-check dispatches executed inside runAsProbe) never removes a connection from the pool (#9817): it is recorded for visibility (last_error, last_error_type, error_code, last_error_at) but skips every routing mutation — cooldowns, terminal status (banned / deactivated / credits_exhausted), per-model lockouts, the provider circuit breaker, the 5-minute quota cache, OAuth token refresh and auto-disable. Only a real request-path failure deactivates. The recorded error is what makes a flagged account visible in the dashboard while it stays serving traffic.

The single decision point is shouldIsolateProbeFailures() (src/shared/utils/probeOrigin.ts), consulted by every site that could mutate routing state from a probe-origin failure:

• markAccountUnavailable (auth.ts) — record-only (lastError raw text, lastErrorType, errorCode, lastErrorAt; deliberately no backoffLevel, which would trigger the selection-time auto-decay and wipe the record)
• maybeAutoDisableBannedAccount — no auto-disable
• chatCore — FORBIDDEN, ACCOUNT_DEACTIVATED, QUOTA_EXHAUSTED (record-only, no terminal credits_exhausted), GEO_BLOCKED (no 24h exclusion), MODEL_NOT_FOUND (no lockModel), the codex 429 account-rotation failover (no markCodexScopeRateLimited, no persisted rate_limited_until, no session-affinity clear), persistCodexQuotaState (no quota-state write, no cache invalidation), recordKeyHealthStatus (key-health rotator untouched)
• OAuth refresh — both the proactive refresh in the executor base (base.ts execute(), no refresh-token rotation consumed) and the reactive 401/403 path in chatCore (no expired deactivation)
• chat.ts — provider circuit breaker and the 5-minute quota cache (markAccountExhaustedFrom429) never degraded

The recorded error is what makes a flagged account visible in the dashboard while it stays serving traffic. Note: the probe record stores the raw (unsliced) error text, unlike the real path's slice(0,100) truncation.

Operators who use test-all as a maintenance tool can restore the historical behavior (probe counts as a real generation) via either:

• the probeCanDisable setting (POST /api/settings with {"probeCanDisable": true}, or a direct key_value DB edit), or
• feature flag PROBE_CAN_DISABLE=true (env or DB override; wins over the setting).

Fail-safe: if the flag or settings lookup throws, isolation stays ON.

Source files

Concern	File
Signal tables + match	open-sse/services/accountFallback.ts
Terminalization / persistence	src/sse/services/auth.ts (markAccountUnavailable, resolveTerminalConnectionStatus, clearAccountError)
Auto-disable scope	src/shared/utils/autoDisableBanned.ts, src/sse/services/autoDisableBannedAccount.ts
Inline classification	open-sse/handlers/chatCore.ts, open-sse/services/errorClassifier.ts
Terminal-state recovery exclusion	src/lib/quota/connectionRecovery.ts
Custom-keyword runtime load	src/lib/config/runtimeSettings.ts (setCustomBannedSignals)
Settings UI	src/app/(dashboard)/dashboard/settings/components/SecurityTab.tsx