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

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 (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 (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 (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, line 26)
• Grok: Uses Chrome 146 profile (open-sse/services/grokTlsClient.ts, line 28)
• Claude: Uses Chrome 146 profile (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:

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:

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

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:

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:

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

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:

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 (lines 440-447) to TlsClient in 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 (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.

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