# How OmniRoute's TLS Stealth Fingerprinting Works for Provider Requests

> Learn how OmniRoute's TLS stealth fingerprinting masks provider API calls by emulating Chrome's TLS fingerprint using a dynamic TlsClient and wreq-js library.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-10

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/utils/tlsClient.ts#L30-L38)):

```typescript
// 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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/utils/tlsClient.ts#L73-L80)):

```typescript
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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/utils/tlsClient.ts#L20-L23)):

```typescript
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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/utils/tlsClient.ts#L48-L56)).

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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/utils/tlsClient.ts#L44-L53)):

| 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:

```typescript
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

```typescript
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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/utils/tlsClient.ts#L5-L13)). Callers receive safe error objects without internal stack traces or TLS implementation specifics.

## Key Source Files

| File | Purpose |
|------|---------|
| [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts) | Core TLS fingerprinting, session management, circuit breakers, and proxy handling |
| [`open-sse/utils/proxyFamily.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFamily.ts) | Proxy family detection for routing decisions |
| [`src/shared/utils/runtimeTimeouts.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/runtimeTimeouts.ts) | Configurable `getTlsClientTimeoutConfig()` for request deadlines |
| [`open-sse/utils/upstreamErrorPassthrough.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/upstreamErrorPassthrough.ts) | Error wrapping utilities for transport failures |
| [`open-sse/utils/providerRequestLogging.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.