How OmniRoute TLS Stealth Fingerprinting Bypasses AI Provider Blocking

OmniRoute defeats IP-, TLS-, and browser-fingerprinting filters used by AI providers through two complementary techniques: a custom TLS fingerprint transport that mimics real browser handshakes, and a stealth browser pool that injects realistic HTTP headers and solves cookie challenges.

OmniRoute's TLS stealth fingerprinting architecture is designed specifically to route requests past aggressive blocking mechanisms employed by Cloudflare-protected endpoints, Claude-Web, Perplexity, Grok, and similar providers. According to the diegosouzapw/OmniRoute source code, the system layers transport-level and application-level deception to make automated traffic indistinguishable from genuine browser sessions.

TLS Stealth Transport: Fingerprinting at the Handshake Level

The first layer of OmniRoute's bypass operates at the TLS handshake level. When a request travels through a proxy to a provider listed in TLS_FINGERPRINT_PROVIDERS, OmniRoute injects a custom TLS client that reproduces the exact TLS handshake a real browser would emit—including SNI, cipher suite lists, and TLS extensions.

Feature Flag and Configuration

The capability is gated by a feature flag defined in src/shared/constants/featureFlagDefinitions.ts:

// src/shared/constants/featureFlagDefinitions.ts#L112
{
  key: "ENABLE_TLS_FINGERPRINT",
  label: "Enable TLS fingerprint stealth mode",
  description: "Use custom TLS client to spoof browser fingerprint for blocked providers",
  defaultValue: false,
  type: "boolean"
}

Operators enable the feature via environment variables:

export ENABLE_TLS_FINGERPRINT=true
export TLS_FINGERPRINT_PROVIDERS="codex,groq,perplexity"

Core Routing Logic in proxyFetch.ts

The central fetch wrapper at open-sse/utils/proxyFetch.ts implements the routing decision. Functions tlsFingerprintProviderAllowed() and tlsFingerprintContext.run() determine whether to apply the fingerprinted transport:

// open-sse/utils/proxyFetch.ts#L82-L121
export async function proxyFetch(
  url: string,
  init: RequestInit,
  context: ProxyContext
): Promise<{ result: Response; tlsFingerprintUsed: boolean }> {
  const shouldFingerprint = tlsFingerprintProviderAllowed(context.provider, context.proxied);
  
  if (shouldFingerprint) {
    return tlsFingerprintContext.run({ used: false }, async (store) => {
      const result = await tlsFetchWithFingerprint(url, init, context);
      return { result, tlsFingerprintUsed: store.used };
    });
  }
  
  // Standard fetch path for non-fingerprinted providers
  const result = await standardFetch(url, init);
  return { result, tlsFingerprintUsed: false };
}

The AsyncLocalStorage context tracks whether the fingerprint was actually employed, enabling observability and billing attribution.

TLS Client Construction

The custom TLS client builds a tls.ClientHello that mirrors a real browser's handshake. This includes:

• Cipher suites: Exact ordering matching Chrome/Edge
• Extensions: Supported groups, signature algorithms, ALPN protocols
• SNI: Correct server name indication for the target provider

The client establishes the TLS tunnel presenting a byte-identical fingerprint to any ordinary browser, defeating TLS-only fingerprinting filters.

Deterministic Error Handling

If the fingerprinted handshake fails, OmniRoute surfaces TLS_FINGERPRINT_FAILED and never retries with a different fingerprint. This prevents inadvertent replay attacks and provider-side rate limiting. The behavior is validated in tests/unit/tls-proxy-context.test.ts, which asserts specific error message patterns.

Stealth Browser Pool: HTTP Fingerprinting and Cookie Management

The second layer addresses HTTP header fingerprinting and cookie challenges through a shared headless Chromium pool with the puppeteer-stealth plugin.

Browser Pool Implementation

The pool state is maintained in open-sse/services/browserPool.ts:

// open-sse/services/browserPool.ts#L402-L410
interface BrowserPoolState {
  cloakLaunch: BrowserLaunchContext | null;
  stealthAvailable: boolean;
  contexts: Map<string, BrowserContext>;
}

public get isStealthAvailable(): boolean {
  return this.state.cloakLaunch !== null && this.state.browser?.isConnected() ?? false;
}

The stealthAvailable flag indicates whether a stealth browser is currently warmed and ready for reuse.

Cookie Challenge Resolution

For web-cookie providers like Claude-Web, open-sse/services/browserBackedChat.ts launches a stealth browser to solve provider cookie challenges before issuing LLM requests:

// open-sse/services/browserBackedChat.ts#L635-L645
async refreshCookiesViaBrowser(provider: string): Promise<AuthCookies> {
  const browser = await this.browserPool.acquireStealthBrowser({ poolKey: provider });
  const page = await browser.newPage();
  
  // Navigate to provider login/challenge page
  await page.goto(this.getChallengeUrl(provider), { waitUntil: "networkidle2" });
  
  // Extract cookies after successful challenge completion
  const cookies = await page.cookies();
  return this.normalizeCookies(cookies);
}

The browser injects realistic headers including User-Agent, Accept-Language, Sec-CH-UA, and Sec-CH-UA-Platform, making requests indistinguishable from genuine user traffic.

MCP Observability Tool

Operators can query the stealth pool status via the MCP tool defined in open-sse/mcp-server/tools/poolTools.ts:

// open-sse/mcp-server/tools/poolTools.ts#L147-L200
@mcpTool()
async browser_pool_status(): Promise<PoolStatusResult> {
  return {
    stealthEnabled: this.config.stealthMode,
    stealthAvailable: this.browserPool.isStealthAvailable,
    activeContexts: this.browserPool.activeContextCount,
    queuedRequests: this.browserPool.queueDepth
  };
}

How the Bypass Works in Practice

1. Feature activation: Set ENABLE_TLS_FINGERPRINT=true and optionally restrict to specific providers via TLS_FINGERPRINT_PROVIDERS.

2. Request interception: proxyFetch checks tlsFingerprintProviderAllowed() for each proxied request.

3. Fingerprint application: Eligible requests run inside tlsFingerprintContext with a custom TLS client that reproduces browser handshake bytes.

4. Browser fallback: For cookie-dependent providers, browserBackedChat acquires or launches a stealth Chromium instance to solve challenges and cache credentials.

5. Traffic emission: The final request presents matching TLS and HTTP fingerprints, passing provider filters that would block standard automated clients.

Provider-Specific Coverage

Provider Type	TLS Fingerprint	Stealth Browser	Example Providers
API with proxy blocking	✅	❌	Groq, Codex
Web-cookie models	✅	✅	Claude-Web, Perplexity
Image generation (cookie auth)	⚠️ Optional	✅	Pollinations Image
Standard API (no blocking)	❌	❌	OpenAI direct, Anthropic API

Key Files Reference

• src/shared/constants/featureFlagDefinitions.ts — Feature flag definitions for TLS stealth
• open-sse/utils/proxyFetch.ts — Central fetch wrapper with fingerprint routing logic
• open-sse/services/browserPool.ts — Shared stealth browser pool management
• open-sse/services/browserBackedChat.ts — Cookie challenge resolution for web models
• open-sse/mcp-server/tools/poolTools.ts — MCP observability interface
• tests/unit/tls-proxy-context.test.ts — TLS fingerprint error handling validation
• tests/unit/proxy-fetch.test.ts — Fingerprint usage reporting tests
• tests/unit/notion-web-models-discovery.test.ts — HTTP header fingerprint presence checks

Summary

• OmniRoute TLS stealth fingerprinting bypasses AI provider blocking through transport-level TLS handshake spoofing and application-level browser emulation.
• The TLS fingerprint transport in proxyFetch.ts applies custom tls.ClientHello construction only to providers in TLS_FINGERPRINT_PROVIDERS.
• The stealth browser pool in browserPool.ts and browserBackedChat.ts solves cookie challenges and injects realistic HTTP headers for web-cookie models.
• Both mechanisms are opt-in per provider, minimizing overhead for compatible endpoints.
• Deterministic error handling prevents fingerprint replay attacks when bypass fails.

Frequently Asked Questions

What providers does OmniRoute TLS fingerprinting work against?

OmniRoute's TLS stealth fingerprinting targets providers employing aggressive TLS and browser fingerprinting including Cloudflare-protected web-cookie models, Claude-Web, Perplexity, and Grok. The specific provider list is configurable via the TLS_FINGERPRINT_PROVIDERS environment variable, allowing operators to enable the feature only where necessary.

How does OmniRoute prevent detection of its stealth browsers?

OmniRoute uses the puppeteer-stealth plugin to inject realistic HTTP headers including User-Agent, Accept-Language, and Sec-CH-UA values matching genuine Chrome installations. The browser pool reuses existing instances across requests, maintaining consistent fingerprints and established cookie stores that appear as legitimate returning user sessions rather than fresh automated clients.

Can operators observe when TLS fingerprinting is active?

Yes. The proxyFetch wrapper returns tlsFingerprintUsed: boolean with every response, enabling request-level observability. Additionally, the MCP tool browser_pool_status exposes whether the stealth browser pool is active, how many contexts are live, and queue depths. These metrics are surfaced from open-sse/mcp-server/tools/poolTools.ts for operational monitoring.

What happens when TLS fingerprinting fails?

OmniRoute surfaces a deterministic TLS_FINGERPRINT_FAILED error and does not retry with alternative fingerprints. This design prevents inadvertent replay attacks and respects provider rate limits. Operators can inspect the specific failure mode through test validations in tests/unit/tls-proxy-context.test.ts and adjust provider configurations accordingly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}