{"id":16514,"library":"read-tls-client-hello","title":"Read TLS Client Hello","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/httptoolkit/read-tls-client-hello","tags":["javascript","tls","fingerprint","fingerprinting","client-hello","alpn","sni","https","ja3","typescript"],"install":[{"cmd":"npm install read-tls-client-hello","lang":"bash","label":"npm"},{"cmd":"yarn add read-tls-client-hello","lang":"bash","label":"yarn"},{"cmd":"pnpm add read-tls-client-hello","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { trackClientHellos } = require('read-tls-client-hello');","symbol":"trackClientHellos","correct":"import { trackClientHellos } from 'read-tls-client-hello';"},{"note":"`readTlsClientHello` is a named export, not a default export.","wrong":"import readTlsClientHello from 'read-tls-client-hello';","symbol":"readTlsClientHello","correct":"import { readTlsClientHello } from 'read-tls-client-hello';"},{"note":"Type import for the interface returned by `readTlsClientHello`.","symbol":"TlsClientHelloMessage","correct":"import type { TlsClientHelloMessage } from 'read-tls-client-hello';"}],"quickstart":{"code":"import * as https from 'https';\nimport { trackClientHellos } from 'read-tls-client-hello';\nimport type { TlsClientHelloMessage } from 'read-tls-client-hello';\n\n// In a real application, you'd load these from environment variables or a config file.\n// For example, using `mkcert` to generate local TLS certificates:\n// mkcert -install\n// mkcert localhost\nconst key = process.env.TLS_KEY ?? ''; // Replace with your actual TLS private key content\nconst cert = process.env.TLS_CERT ?? ''; // Replace with your actual TLS certificate content\n\nif (!key || !cert) {\n  console.error('TLS_KEY and TLS_CERT environment variables are required for the example.');\n  process.exit(1);\n}\n\nconst server = new https.Server({\n    key,\n    cert\n});\n\ntrackClientHellos(server); // <-- Automatically track everything on this server\n\nserver.on('request', (request, response) => {\n    const socket = request.socket as (typeof request.socket & { tlsClientHello?: TlsClientHelloMessage });\n    // In your normal request handler, check `tlsClientHello` on the request's socket:\n    if (socket.tlsClientHello) {\n        console.log('Received request with TLS client hello:', {\n            version: socket.tlsClientHello.version,\n            sni: socket.tlsClientHello.extensions.find(ext => ext.id === 0)?.data?.server_name,\n            ja3: socket.tlsClientHello.ja3,\n            ja4: socket.tlsClientHello.ja4\n        });\n    } else {\n        console.log('Received request without TLS client hello data (e.g., HTTP/2 over TLS without initial ClientHello tracking, or an error occurred).');\n    }\n    response.writeHead(200, { 'Content-Type': 'text/plain' });\n    response.end('Hello from tracked server!');\n});\n\nserver.listen(8443, () => {\n    console.log('HTTPS server listening on https://localhost:8443');\n    console.log('Try connecting with curl: curl -k https://localhost:8443');\n});\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Update `package.json` to `\"read-tls-client-hello\": \"^2.0.0\"` and change all `import` or `require` paths accordingly.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js runtime to version 20.0.0 or later.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Update your `package.json` to depend on `read-tls-client-hello` and adjust `import`/`require` paths.","cause":"The package was renamed from `read-tls-fingerprint` to `read-tls-client-hello` in v2.0.0.","error":"Error: Cannot find module 'read-tls-fingerprint'"},{"fix":"Ensure you are using `import { trackClientHellos } from 'read-tls-client-hello';` for named exports, or verify module type configuration in your `package.json`.","cause":"Attempting to use `trackClientHellos` as a default import or incorrectly destructuring named exports. Alternatively, using `require()` in an ES module context.","error":"TypeError: Cannot read properties of undefined (reading 'trackClientHellos')"},{"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`.","cause":"The stream provided to `readTlsClientHello` did not contain valid TLS Client Hello data, or the stream was read from before `readTlsClientHello` was called.","error":"Error: readTlsClientHello failed: Invalid TLS ClientHello format"}],"ecosystem":"npm"}