How OmniRoute's TLS Stealth Fingerprinting Works for Provider Requests

OmniRoute masks outbound provider API calls by emulating Chrome 124's TLS fingerprint through a dynamic TlsClient utility that loads the wreq-js library when ENABLE_TLS_FINGERPRINT is enabled.

TLS stealth fingerprinting in OmniRoute prevents provider-side detection by making automated requests appear to originate from a legitimate Chrome browser on macOS. The implementation lives entirely in open-sse/utils/tlsClient.ts and integrates seamlessly with the rest of the request pipeline—provider code simply swaps native fetch for tlsClient.fetch() without handling TLS details directly.

What Is TLS Stealth Fingerprinting?

TLS fingerprinting allows servers to identify clients by analyzing the Client Hello message sent during the TLS handshake. Unique combinations of cipher suites, extensions, and compression methods create a fingerprint that distinguishes automation tools from real browsers. OmniRoute counters this by using wreq-js to replicate Chrome 124's exact TLS signature, making provider requests indistinguishable from genuine browser traffic.

How OmniRoute Implements TLS Fingerprinting

Dynamic Library Loading

The TlsClient class attempts to require('wreq-js') only when process.env.ENABLE_TLS_FINGERPRINT === 'true'. If the library is missing, it logs a warning and gracefully degrades to standard fetch behavior (source):

// From open-sse/utils/tlsClient.ts
let wreq: any;
if (process.env.ENABLE_TLS_FINGERPRINT === 'true') {
  try {
    wreq = require('wreq-js');
  } catch (err) {
    logger.warn('wreq-js not installed; TLS fingerprinting disabled');
  }
}

This conditional loading keeps the dependency optional—applications only pay the bundle cost when explicitly enabled.

Session Isolation with Deterministic Keys

Each request binds to a session key derived from:

• The proxy URL (if provided)
• A caller-supplied session scope (typically an account or user identifier)

The key is computed as a SHA-256 hash in base64url encoding (source):

const sessionKey = crypto
  .createHash('sha256')
  .update(`${proxyUrl || 'direct'}:${sessionScope || 'default'}`)
  .digest('base64url');

This design ensures that requests sharing the same proxy and scope reuse TLS sessions—maintaining consistent fingerprints—while isolating unrelated traffic.

Chrome 124 Fingerprint Configuration

When creating a new session, TlsClient passes hardcoded browser and OS identifiers to wreq-js (source):

const sessionOpts = {
  browser: 'chrome_124',
  os: 'macos',
  // additional wreq-js options...
};

These values instruct wreq-js to construct a Client Hello matching Chrome 124 on macOS, including the correct cipher suite ordering, ALPN protocols, and extension layout that providers expect from legitimate users.

Circuit-Breaker Protection

The TLS client incorporates resilience through per-session circuit breakers. Each session key tracks consecutive failures; after maxFailures = 3, the circuit opens and blocks further attempts for a back-off period that grows exponentially up to 10× the base cooldown (source).

This prevents hammering providers with fingerprinted requests that are likely to fail, preserving the stealth benefit for when the underlying issue resolves.

Proxy Handling in TLS Requests

TlsClient respects standard environment variables (HTTPS_PROXY, HTTP_PROXY, ALL_PROXY) while allowing per-request overrides through the options.proxy parameter (source):

Proxy Value	Behavior
undefined	Uses environment variable lookup
string	Explicit proxy URL for this request
null	Forces direct connection (no proxy)

The session key incorporates the resolved proxy URL, so switching proxies automatically isolates sessions even with the same scope.

Usage in Provider Requests

Provider executors call tlsClient.fetch() identically to native fetch, with two additional options:

import tlsClient from '@/open-sse/utils/tlsClient';

const response = await tlsClient.fetch(
  'https://api.openai.com/v1/chat/completions',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({ 
      model: 'gpt-4o', 
      messages: [{ role: 'user', content: 'Hello' }] 
    }),
    proxy: null,           // Optional: force direct connection
    sessionScope: 'org-42' // Optional: isolate by tenant
  }
);

The client handles:

1. Resolving proxy and computing session key
2. Checking circuit state (throws TLS_CIRCUIT_OPEN if tripped)
3. Lazily creating the fingerprinted wreq-js session
4. Executing the request and normalizing the response to a standard Response object
5. Recording outcome to update circuit breaker state

Debugging Circuit State

import tlsClient from '@/open-sse/utils/tlsClient';

// Check if circuit is open for a specific scope
const state = tlsClient.getCircuitState(undefined, 'org-42');
console.log('Failures:', state.failureCount, 'Open:', state.circuitTripped);

// Reset all circuits after manual intervention
tlsClient.resetCircuit();

Error Sanitization

Transport-layer errors from wreq-js are wrapped before propagation to strip potentially sensitive connection details (source). Callers receive safe error objects without internal stack traces or TLS implementation specifics.

Key Source Files

File	Purpose
open-sse/utils/tlsClient.ts	Core TLS fingerprinting, session management, circuit breakers, and proxy handling
open-sse/utils/proxyFamily.ts	Proxy family detection for routing decisions
src/shared/utils/runtimeTimeouts.ts	Configurable getTlsClientTimeoutConfig() for request deadlines
open-sse/utils/upstreamErrorPassthrough.ts	Error wrapping utilities for transport failures
open-sse/utils/providerRequestLogging.ts	Provider request telemetry and debugging

Summary

• Opt-in activation: Set ENABLE_TLS_FINGERPRINT=true to load wreq-js and enable Chrome 124 emulation
• Session isolation: SHA-256 session keys combine proxy URL and scope for consistent, separated fingerprints
• Hardcoded profile: browser: "chrome_124", os: "macos" replicates modern browser TLS signatures
• Circuit-breaker resilience: Per-session failure tracking with exponential back-off prevents detection through error patterns
• Transparent API: Drop-in fetch replacement with proxy and sessionScope options—no TLS knowledge required

Frequently Asked Questions

What TLS fingerprint does OmniRoute emulate?

OmniRoute emulates Chrome 124 on macOS by passing browser: "chrome_124" and os: "macos" to the underlying wreq-js library. This specific profile was selected for its prevalence and low detection rates against major API providers.

Can I use TLS fingerprinting without the wreq-js dependency?

No—wreq-js is required for actual fingerprint emulation. However, OmniRoute handles its absence gracefully: if wreq-js is not installed, TlsClient logs a warning and falls back to standard Node.js fetch with identical semantics but no fingerprint masking.

How do I force a direct connection bypassing all proxies?

Pass proxy: null in the fetch options. This overrides environment variables (HTTPS_PROXY, HTTP_PROXY, ALL_PROXY) and forces TlsClient to establish a direct TLS connection to the target host.

What happens when the circuit breaker opens?

When a session accumulates 3 consecutive failures, the circuit opens and tlsClient.fetch() immediately throws a TLS_CIRCUIT_OPEN error without attempting the request. The back-off period grows exponentially with each failure, capped at 10× the base cooldown. Use tlsClient.resetCircuit() to manually clear all circuit states.

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