Read TLS Client Hello

2.0.0 · active · verified Wed Apr 22

A pure-JS module for Node.js environments, `read-tls-client-hello` provides robust functionality to intercept and parse TLS Client Hello messages from incoming socket connections before the full TLS handshake commences. This library, currently at version 2.0.0, is distinguished by its zero runtime dependencies and its capability to unshift the parsed data back into the socket, allowing the connection to proceed normally after analysis. It enables the calculation of TLS fingerprints (JA3/JA4), offering insights into the type of client initiating the connection, such as browsers or specific tools, independent of request content. While there isn't a strict release cadence, updates are typically driven by feature enhancements or necessary maintenance. Its core differentiator lies in its minimal overhead and its unique ability to pre-process TLS handshakes without disrupting the connection flow, making it ideal for proxying, security analysis, or custom server logic that requires early client identification. It succeeds the deprecated `read-tls-fingerprint` package, expanding its scope beyond just fingerprinting.

Common errors

```
Error: Cannot find module 'read-tls-fingerprint'
```
cause The package was renamed from `read-tls-fingerprint` to `read-tls-client-hello` in v2.0.0.

fix Update your `package.json` to depend on `read-tls-client-hello` and adjust `import`/`require` paths.
```
TypeError: Cannot read properties of undefined (reading 'trackClientHellos')
```
cause Attempting to use `trackClientHellos` as a default import or incorrectly destructuring named exports. Alternatively, using `require()` in an ES module context.

fix Ensure you are using `import { trackClientHellos } from 'read-tls-client-hello';` for named exports, or verify module type configuration in your `package.json`.
```
Error: readTlsClientHello failed: Invalid TLS ClientHello format
```
cause The stream provided to `readTlsClientHello` did not contain valid TLS Client Hello data, or the stream was read from before `readTlsClientHello` was called.

fix Ensure the input stream is an initial socket connection containing a raw TLS Client Hello message and no other data has been consumed from it prior to calling `readTlsClientHello`.

Warnings

breaking The package was renamed from `read-tls-fingerprint` to `read-tls-client-hello` in version 2.0.0. Projects upgrading from `v1.x` of the old package must update their `package.json` dependency and all import statements.
Fix: Update `package.json` to `"read-tls-client-hello": "^2.0.0"` and change all `import` or `require` paths accordingly.
breaking Version 2.0.0 and above explicitly require Node.js version 20.0.0 or higher. Running on older Node.js versions will result in compatibility errors.
Fix: Upgrade your Node.js runtime to version 20.0.0 or later.
gotcha TLS fingerprinting (JA3/JA4) is not a 100% reliable method for client identification. Sophisticated clients can modify their fingerprints to evade detection or mimic other clients, potentially leading to incorrect assumptions about the connecting party.
Fix: Combine TLS fingerprint data with other client identification techniques (e.g., User-Agent headers, IP reputation, behavioral analysis) for more robust and reliable client classification.

Install

npm install read-tls-client-hello npm
yarn add read-tls-client-hello yarn
pnpm add read-tls-client-hello pnpm

Imports

trackClientHellos
wrong:
```
const { trackClientHellos } = require('read-tls-client-hello');
```
correct:
```
import { trackClientHellos } from 'read-tls-client-hello';
```
While the README examples show `require()`, `import` syntax is standard for modern Node.js and TypeScript projects. Using `require()` in an ESM module will lead to errors.

readTlsClientHello

wrong:

import readTlsClientHello from 'read-tls-client-hello';

correct:

import { readTlsClientHello } from 'read-tls-client-hello';

`readTlsClientHello` is a named export, not a default export.

TlsClientHelloMessage
```
import type { TlsClientHelloMessage } from 'read-tls-client-hello';
```
Type import for the interface returned by `readTlsClientHello`.

Quickstart

This quickstart demonstrates how to set up an HTTPS server using Node.js's `https` module and integrate `read-tls-client-hello` to automatically track and access TLS Client Hello information, including JA3/JA4 fingerprints, on incoming request sockets.

import * as https from 'https';
import { trackClientHellos } from 'read-tls-client-hello';
import type { TlsClientHelloMessage } from 'read-tls-client-hello';

// In a real application, you'd load these from environment variables or a config file.
// For example, using `mkcert` to generate local TLS certificates:
// mkcert -install
// mkcert localhost
const key = process.env.TLS_KEY ?? ''; // Replace with your actual TLS private key content
const cert = process.env.TLS_CERT ?? ''; // Replace with your actual TLS certificate content

if (!key || !cert) {
  console.error('TLS_KEY and TLS_CERT environment variables are required for the example.');
  process.exit(1);
}

const server = new https.Server({
    key,
    cert
});

trackClientHellos(server); // <-- Automatically track everything on this server

server.on('request', (request, response) => {
    const socket = request.socket as (typeof request.socket & { tlsClientHello?: TlsClientHelloMessage });
    // In your normal request handler, check `tlsClientHello` on the request's socket:
    if (socket.tlsClientHello) {
        console.log('Received request with TLS client hello:', {
            version: socket.tlsClientHello.version,
            sni: socket.tlsClientHello.extensions.find(ext => ext.id === 0)?.data?.server_name,
            ja3: socket.tlsClientHello.ja3,
            ja4: socket.tlsClientHello.ja4
        });
    } else {
        console.log('Received request without TLS client hello data (e.g., HTTP/2 over TLS without initial ClientHello tracking, or an error occurred).');
    }
    response.writeHead(200, { 'Content-Type': 'text/plain' });
    response.end('Hello from tracked server!');
});

server.listen(8443, () => {
    console.log('HTTPS server listening on https://localhost:8443');
    console.log('Try connecting with curl: curl -k https://localhost:8443');
});

view raw JSON →