# Configuring TLS Fingerprint Stealth with OmniRoute: A Complete Guide

> Learn how to configure TLS fingerprint stealth with OmniRoute. Disguise outbound TLS handshakes to bypass bot detection and mimic real browsers. A complete guide.

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

---

**OmniRoute disguises outbound TLS handshakes to mimic real web browsers, bypassing bot-detection systems that inspect JA3/JA4 fingerprints by using the `wreq-js` library to generate Chrome-style TLS client hellos.**

TLS fingerprint stealth is essential for avoiding detection by modern anti-bot systems. OmniRoute implements this capability through a transport layer that forges browser-like TLS handshakes, making automated requests indistinguishable from genuine user traffic. This article covers how to enable, configure, and deploy TLS fingerprinting in OmniRoute based on the actual source code implementation.

## How TLS Fingerprint Stealth Works in OmniRoute

The stealth system operates through two complementary components that work together to mask automation signatures.

### Core Components

| Component | Purpose | Source Location |
|-----------|---------|---------------|
| **TLS fingerprint transport** | Generates Chrome-style TLS client hellos using `wreq-js` and forwards requests through the forged TLS stack | [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts) |
| **TPROXY capture** (optional) | Terminates inbound TLS, decrypts requests, logs traffic, then re-encrypts outbound traffic with the forged fingerprint | [`src/mitm/tproxy/tlsCapture.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/tlsCapture.ts) |

Both components remain **disabled by default**. Activation requires a single environment variable.

## Enabling TLS Fingerprint Mode

Set the environment variable `ENABLE_TLS_FINGERPRINT` to `true`:

```bash
export ENABLE_TLS_FINGERPRINT=true

```

Or in a `.env` file:

```yaml

# .env

ENABLE_TLS_FINGERPRINT=true

```

When enabled, the runtime attempts to `require("wreq-js")`. If the module is missing, OmniRoute prints a warning and silently disables TLS fingerprint transport, falling back to standard Node.js HTTP behavior.

## Using the TLS-Aware Fetch Helper

The primary interface for TLS fingerprinted requests is `tlsFetch` from [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts). This function wraps `wreq-js` sessions and returns native `Response` objects compatible with the standard Fetch API.

### Basic Usage Pattern

```ts
import { tlsFetch } from "@/open-sse/utils/tlsClient";

const response = await tlsFetch("https://api.example.com/v1/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "hello" }),
});

const data = await response.json();

```

### Advanced Configuration Options

| Option | Description | Implementation Detail |
|--------|-------------|----------------------|
| `proxy` | HTTP/HTTPS proxy for the request | Respects `HTTPS_PROXY → HTTP_PROXY → ALL_PROXY` precedence (lines 45-53) |
| `sessionScope` | Isolates cookies and circuit-breaker state | Creates separate `wreq-js` sessions per scope (line 76) |
| `timeout` | Request timeout in milliseconds | Defaults to `getTlsClientTimeoutConfig()` value (line 3) |

### Complete Example with Session Scoping

```ts
import { tlsFetch } from "@/open-sse/utils/tlsClient";

// Isolated session for account-specific state
const response = await tlsFetch("https://api.example.com/v1/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "hello" }),
  proxy: "http://proxy.local:3128",
  sessionScope: "account-42", // Cookies and circuit state isolated to this account
});

```

The `sessionScope` parameter ensures that **cookie jars and circuit-breaker state remain separated across different logical sessions**, preventing cross-contamination between accounts or connection contexts.

## Implementing TPROXY Capture for Transparent Interception

For deployments requiring full traffic inspection, the TPROXY capture layer in [`src/mitm/tproxy/tlsCapture.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/tlsCapture.ts) terminates TLS on the inbound side, logs decrypted traffic, then re-encrypts using the forged fingerprint.

### Setting Up the Capture Server

```ts
import http from "node:http";
import { handleDecryptedRequest } from "@/src/mitm/tproxy/tlsCapture";

http.createServer((req, res) => {
  // `dest` provided by transparent listener (original destination)
  const dest = { 
    ip: "93.184.216.34", 
    port: 443, 
    sni: "api.example.com" 
  };
  
  handleDecryptedRequest(req, res, dest, {
    buffer: globalTrafficBuffer,
    forward: realForward,
    now: () => performance.now(),
    randomId: () => randomUUID(),
  });
}).listen(8080);

```

The `handleDecryptedRequest` function:

1. Parses the decrypted HTTP request
2. Logs to `globalTrafficBuffer` for analysis
3. Forwards to the original destination using `tlsFetch` with the forged fingerprint

This creates a **transparent proxy chain**: inbound TLS terminates, traffic is inspected, then outbound TLS uses browser-like fingerprints to reach target servers.

## Fallback Behavior When TLS Fingerprinting Is Disabled

When `ENABLE_TLS_FINGERPRINT` is unset or `false`, OmniRoute automatically falls back to the standard Node/Undici HTTP client stack:

```ts
process.env.ENABLE_TLS_FINGERPRINT = "false";

import { tlsFetch } from "@/open-sse/utils/tlsClient";

// Uses regular Node/Undici without TLS forgery
const response = await tlsFetch("https://example.org");

```

This fallback preserves **original behavior and performance characteristics**, ensuring no dependency on `wreq-js` for deployments that don't require stealth.

## Key Implementation Details from Source Code

The [`tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tlsClient.ts) file (lines 27-99) handles critical normalization tasks:

- **Header normalization**: Ensures consistent header ordering and casing to match browser signatures
- **Error sanitization**: Strips internal implementation details from error responses
- **Response adaptation**: Converts `wreq-js` responses into spec-compliant native `Response` objects

Proxy resolution follows conventional precedence:

```typescript
// Lines 45-53 in tlsClient.ts
const proxy = options.proxy 
  || process.env.HTTPS_PROXY 
  || process.env.HTTP_PROXY 
  || process.env.ALL_PROXY;

```

Timeout configuration merges with global fetch settings through `getTlsClientTimeoutConfig()`, ensuring consistent behavior across all HTTP operations in OmniRoute.

## Service Layer Integration

For internal OmniRoute executors, [`open-sse/services/tlsClientProxy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/tlsClientProxy.ts) exposes the TLS fingerprint transport as a reusable service. This abstraction allows multiple request paths to share the same `wreq-js` session management and fingerprint configuration without direct dependency on the lower-level [`tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tlsClient.ts) module.

## Essential Source Files Reference

| File | Purpose | Direct Link |
|------|---------|-------------|
| [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts) | Core `tlsFetch` implementation, `wreq-js` integration, response adaptation | [View source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/utils/tlsClient.ts) |
| [`open-sse/services/tlsClientProxy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/tlsClientProxy.ts) | Service abstraction for executor consumption | [View source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/services/tlsClientProxy.ts) |
| [`src/mitm/tproxy/tlsCapture.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/tlsCapture.ts) | TPROXY TLS termination and re-encryption | [View source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/mitm/tproxy/tlsCapture.ts) |
| [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) | Environment variable documentation | [View docs](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/docs/reference/ENVIRONMENT.md) |
| [`docs/security/STEALTH_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/STEALTH_GUIDE.md) | Broader stealth technique coverage | [View docs](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/docs/security/STEALTH_GUIDE.md) |

## Summary

- **Enable TLS fingerprint stealth** by setting `ENABLE_TLS_FINGERPRINT=true` in your environment
- **Use `tlsFetch`** from [`open-sse/utils/tlsClient.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/tlsClient.ts) for direct, fingerprinted HTTP requests that return native `Response` objects
- **Leverage `sessionScope`** to isolate cookies and circuit state between logical sessions
- **Deploy TPROXY capture** via [`src/mitm/tproxy/tlsCapture.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/tlsCapture.ts) when transparent interception and logging are required
- **Rely on automatic fallback** to standard Node/Undici when TLS fingerprinting is disabled or `wreq-js` is unavailable

## Frequently Asked Questions

### What is a TLS fingerprint and why does it matter for bot detection?

A TLS fingerprint is a hash of the parameters in a TLS Client Hello message—cipher suites, extensions, and supported versions. Anti-bot systems like Cloudflare and DataDome use JA3/JA4 fingerprints to identify automated tools, which typically present different signatures than real browsers. OmniRoute's stealth mode forges Chrome-compatible fingerprints to evade these detection mechanisms.

### Does OmniRoute require `wreq-js` as a runtime dependency?

No. `wreq-js` is loaded dynamically via `require()` only when `ENABLE_TLS_FINGERPRINT=true`. If the module is absent, OmniRoute prints a warning and continues with normal HTTP behavior. This optional dependency design keeps deployments lightweight when stealth features aren't needed.

### Can I use TLS fingerprinting with rotating proxies?

Yes. The `proxy` option in `tlsFetch` accepts any HTTP/HTTPS proxy URL, and proxy configuration follows standard environment variable precedence. Combine with `sessionScope` to maintain separate cookie jars across different proxy endpoints, ensuring clean identity separation per connection.