# How to Configure TLS Stealth (JA3/JA4) with wreq-js for Provider Access in OmniRoute

> Configure TLS stealth JA3/JA4 in OmniRoute using wreq-js. Impersonate browser TLS fingerprints like Chrome 124 for provider access. Enable fingerprinting and install the module for secure routing.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Set `ENABLE_TLS_FINGERPRINT=true` and install the `wreq-js` native module to route all provider HTTP requests through a TLS-impersonating client that spoofs JA3/JA4 hashes using browser profiles like Chrome 124.**

OmniRoute provides built-in TLS stealth capabilities through the native Rust library `wreq-js`, enabling your application to impersonate modern browser fingerprints when accessing AI providers. By configuring a single environment variable, you activate JA3/JA4 spoofing across all outbound requests without changing your existing fetch logic. This guide covers the exact implementation details based on the `diegosouzapw/OmniRoute` source code.

## How TLS Stealth Works in OmniRoute

OmniRoute intercepts HTTP requests at the proxy layer and conditionally routes them through a native TLS client that mimics browser handshake characteristics. This happens transparently once you enable the feature flag.

### The Request Flow

The architecture follows a strict decision chain:

1. **Feature Flag Check**: In [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) (line 110), the `ENABLE_TLS_FINGERPRINT` flag is defined as a boolean string environment variable.

2. **Proxy Interception**: The `proxyFetch` helper in [`open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFetch.ts) (lines 440-447) calls `isTlsFingerprintEnabled()` to determine routing. When the flag is active and `tlsClient.available` returns true, requests forward to `tlsClient.fetch` instead of the standard Node fetch.

3. **TLS Impersonation**: The `TlsClient` class in [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts) (lines 65-72) lazily loads `wreq-js` and initializes a browser session—defaulting to **Chrome 124**—which performs the actual HTTPS handshake with spoofed JA3/JA4 fingerprints and HTTP/2 SETTINGS frames (lines 152-165, 171-179).

4. **Fallback Protection**: If the native module fails to load or the circuit breaker trips, `tlsClient.available` becomes `false` and requests automatically fall back to standard fetch with a warning emission.

### Browser Profile Selection

Different providers use specific browser profiles to avoid detection:

- **Perplexity**: Uses Firefox 148 profile ([`open-sse/services/perplexityTlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/perplexityTlsClient.ts), line 26)
- **Grok**: Uses Chrome 146 profile ([`open-sse/services/grokTlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/grokTlsClient.ts), line 28)
- **Claude**: Uses Chrome 146 profile ([`open-sse/services/claudeTlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/claudeTlsClient.ts), line 23)

## Installation and Configuration

### Installing wreq-js

The `wreq-js` package is a native Node module that requires compilation during installation:

```bash
npm install wreq-js

```

The post-install step automatically compiles the platform-specific `.node` binary for your operating system.

### Environment Configuration

Set the following variables in your `.env` file or process environment:

```bash
export ENABLE_TLS_FINGERPRINT=true
export HTTPS_PROXY=http://my-proxy:3128

```

The `TlsClient` reads proxy URLs from `HTTPS_PROXY`, `HTTP_PROXY`, or `ALL_PROXY` (lines 25-33 in [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts)) and passes them to `wreq-js` to preserve the fingerprint while traversing proxies (lines 57-60).

### Optional Timeout Configuration

Control the TLS client fetch timeout via [`src/shared/utils/runtimeTimeouts.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/runtimeTimeouts.ts):

```bash
export TLS_CLIENT_TIMEOUT_MS=30000

```

## Enabling JA3/JA4 Fingerprinting in Production

Once `wreq-js` is installed and `ENABLE_TLS_FINGERPRINT=true` is set, restart OmniRoute. The initialization sequence works as follows:

1. The `TlsClient` singleton loads `wreq-js` on first request
2. Creates a session with the target browser profile
3. All subsequent `proxyFetch` calls use `tlsClient.fetch` with the spoofed JA3/JA4 hash

**Important**: If the native module is missing or incompatible, the system silently falls back to native fetch to prevent runtime crashes, making this feature safe for production rollouts.

## Circuit Breaker and Error Handling

The TLS client implements a circuit breaker pattern to prevent cascading failures during provider outages.

### Failure Tracking

After three consecutive failures, the circuit opens for exponential backoff (30 seconds → 60 seconds → up to 10 minutes). While open, `tlsClient.available` returns `false`, forcing fallback to standard fetch.

### Debugging the Circuit State

Check current status programmatically:

```typescript
import tlsClient from "./open-sse/utils/tlsClient.ts";

console.log("TLS client state:", tlsClient.getCircuitState());
// Output: { available: true, circuitTripped: false, failureCount: 0, ... }

```

## Practical Implementation Examples

### Basic Server Configuration

Enable TLS stealth in your entry point:

```typescript
// server.ts
import { createServer } from "http";
import * as dotenv from "dotenv";

dotenv.config(); // Loads ENABLE_TLS_FINGERPRINT=true from .env

const port = 3000;
createServer((req, res) => {
  // All downstream provider calls automatically use wreq-js
  res.end("OmniRoute running with TLS stealth (JA3/JA4)");
}).listen(port, () => console.log(`Listening on http://localhost:${port}`));

```

### Direct TLS Client Usage

For provider-specific implementations that bypass `proxyFetch`:

```typescript
import tlsClient from "./open-sse/utils/tlsClient.ts";

async function fetchWithStealth(url: string) {
  const resp = await tlsClient.fetch(url, {
    method: "GET",
    headers: { "Accept": "application/json" },
  });
  return await resp.json();
}

// Example: Perplexity API with Firefox 148 fingerprint
fetchWithStealth("https://api.perplexity.ai/chat")
  .then(console.log)
  .catch(console.error);

```

### Docker Deployment

Configure in a containerized environment:

```dockerfile
FROM node:22-alpine

# Install build tools for native module compilation

RUN apk add --no-cache python3 make g++ && \
    npm install wreq-js && \
    apk del python3 make g++

ENV ENABLE_TLS_FINGERPRINT=true
ENV HTTPS_PROXY=http://proxy.internal:3128

COPY . /app
WORKDIR /app
RUN npm ci && npm run build
CMD ["node", "dist/server.js"]

```

## Summary

- **Enable the feature** by setting `ENABLE_TLS_FINGERPRINT=true` and installing `wreq-js` via npm.
- **Proxy support** automatically reads `HTTPS_PROXY`, `HTTP_PROXY`, and `ALL_PROXY` environment variables.
- **Request flow** routes through [`open-sse/utils/proxyFetch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFetch.ts) (lines 440-447) to `TlsClient` in [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts) when the flag is active.
- **Browser profiles** like Chrome 124 and Firefox 148 spoof JA3/JA4 hashes to mimic real browsers.
- **Circuit breaker** prevents failures after three consecutive errors with exponential backoff.
- **Provider-specific** implementations exist for Perplexity, Grok, and Claude with distinct fingerprint profiles.

## Frequently Asked Questions

### What is the default browser profile when enabling TLS stealth?

OmniRoute defaults to **Chrome 124** when you enable `ENABLE_TLS_FINGERPRINT`. Individual provider services in `open-sse/services/` may override this—for example, Perplexity uses Firefox 148 while Grok and Claude use Chrome 146.

### Does TLS stealth work with corporate proxies?

Yes. The `TlsClient` implementation in [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts) (lines 25-33) reads standard proxy environment variables (`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`) and passes them to `wreq-js`, preserving the JA3/JA4 fingerprint even when traffic exits through a proxy endpoint.

### What happens if wreq-js fails to load?

If the native module is missing or crashes, `tlsClient.available` returns `false` and the request automatically falls back to standard Node fetch. The circuit breaker tracks failures and opens after three consecutive errors to prevent log spam, ensuring your application remains stable.

### How do I verify that JA3/JA4 spoofing is active?

Check the circuit state using `tlsClient.getCircuitState()` which returns the availability status and failure count. Additionally, outgoing requests from providers using `proxyFetch` will show the characteristic Chrome 124 or Firefox 148 fingerprint on the receiving server's TLS logs instead of the default Node.js fingerprint.