Add TLS fingerprint endpoint

Author: pimterry

package-lock.json

@@ -38,6 +38,7 @@
     "cookie": "^1.0.2",
     "lodash": "^4.17.23",
     "parse-multipart-data": "^1.5.0",
+    "read-tls-client-hello": "^1.1.0",
     "tsx": "^4.19.3"
   },
   "devDependencies": {

package.json

@@ -44,4 +44,5 @@ export * from './http/encoding/gzip.js';
 export * from './http/encoding/deflate.js';
 export * from './http/encoding/zstd.js';
 export * from './http/encoding/brotli.js';
-export * from './http/encoding/identity.js';
+export * from './http/encoding/identity.js';
+export * from './http/tls-fingerprint.js';

src/endpoints/http-index.ts

@@ -0,0 +1,46 @@
+import { TLSSocket } from 'tls';
+import { HttpEndpoint, HttpRequest } from '../http-index.js';
+
+function getTlsSocket(req: HttpRequest): TLSSocket | undefined {
+    // HTTP/1: socket is directly available
+    if (req.socket instanceof TLSSocket) {
+        return req.socket;
+    }
+
+    // HTTP/2: socket is on the session
+    const stream = (req as any).stream;
+    const session = stream?.session;
+    const socket = session?.socket;
+    if (socket instanceof TLSSocket) {
+        return socket;
+    }
+
+    return undefined;
+}
+
+export const tlsFingerprint: HttpEndpoint = {
+    matchPath: (path) => path === '/tls/fingerprint',
+    handle: (req, res) => {
+        const tlsSocket = getTlsSocket(req);
+
+        if (!tlsSocket) {
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Not a TLS connection' }));
+            return;
+        }
+
+        const tlsClientHello = (tlsSocket as any).tlsClientHello;
+
+        if (!tlsClientHello?.ja3 || !tlsClientHello?.ja4) {
+            res.writeHead(500, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'TLS fingerprint not available' }));
+            return;
+        }
+
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({
+            ja3: tlsClientHello.ja3,
+            ja4: tlsClientHello.ja4
+        }));
+    }
+};

src/endpoints/http/tls-fingerprint.ts

@@ -243,14 +243,6 @@ export class ConnectionProcessor {
 
         if (isTLS(initialData)) {
             connection.unshift(initialData);
-            // For TLS, set up data capturing on the raw connection
-            connection.receivedData = [];
-            connection.once('readable', () => {
-                connection.on('data', (data) => {
-                    connection.receivedData?.push(data);
-                });
-            });
-            connection.pause();
             this.tlsHandler(connection);
         } else if (isHTTP2(initialData)) {
             // For HTTP/2, wrap in a capturing stream because http2 module

src/process-connection.ts

@@ -1,5 +1,12 @@
 import * as net from 'net';
 
+import {
+    readTlsClientHello,
+    calculateJa3FromFingerprintData,
+    calculateJa4FromHelloData,
+    TlsHelloData
+} from 'read-tls-client-hello';
+
 import { createHttp1Handler, createHttp2Handler } from './http-handler.js';
 import { createTlsHandler, CertMode } from './tls-handler.js';
 import { ConnectionProcessor } from './process-connection.js';
@@ -14,6 +21,11 @@ declare module 'stream' {
         // Pipelining detection: tracks concurrent requests
         requestsInBatch?: number;
         pipelining?: boolean;
+        // TLS fingerprint data (set for TLS connections)
+        tlsClientHello?: TlsHelloData & {
+            ja3: string;
+            ja4: string;
+        };
     }
 }
 
@@ -108,7 +120,18 @@ async function generateTlsConfig(options: ServerOptions) {
 
 const createTcpHandler = async (options: ServerOptions = {}) => {
     const connProcessor = new ConnectionProcessor(
-        (conn) => {
+        async (conn) => {
+            // Read and store TLS fingerprint before TLS handshake
+            try {
+                const helloData = await readTlsClientHello(conn);
+                conn.tlsClientHello = {
+                    ...helloData,
+                    ja3: calculateJa3FromFingerprintData(helloData.fingerprintData),
+                    ja4: calculateJa4FromHelloData(helloData)
+                };
+            } catch (e) {
+                // Non-TLS traffic or malformed client hello - continue without fingerprint
+            }
             conn.pause();
             tlsHandler.emit('connection', conn);
         },

src/server.ts

@@ -138,6 +138,14 @@ export async function createTlsHandler(
 
     proactivelyRefreshDomains(tlsConfig.proactiveCertDomains ?? [], tlsConfig.generateCertificate);
 
+    // Copy TLS fingerprint from underlying socket to TLS socket
+    server.prependListener('secureConnection', (tlsSocket) => {
+        const parent = (tlsSocket as any)._parent;
+        if (parent?.tlsClientHello) {
+            (tlsSocket as any).tlsClientHello = parent.tlsClientHello;
+        }
+    });
+
     server.on('secureConnection', (socket) => {
         connProcessor.processConnection(socket);
     });

src/tls-handler.ts

@@ -0,0 +1,44 @@
+import * as net from 'net';
+import * as https from 'https';
+import * as streamConsumers from 'stream/consumers';
+
+import { expect } from 'chai';
+import { DestroyableServer, makeDestroyable } from 'destroyable-server';
+
+import { createServer } from '../src/server.js';
+
+describe("TLS fingerprint endpoint", () => {
+
+    let server: DestroyableServer;
+    let serverPort: number;
+
+    beforeEach(async () => {
+        server = makeDestroyable(await createServer());
+        await new Promise<void>((resolve) => server.listen(resolve));
+        serverPort = (server.address() as net.AddressInfo).port;
+    });
+
+    afterEach(async () => {
+        await server.destroy();
+    });
+
+    it("returns ja3 and ja4 fingerprints for TLS connections", async () => {
+        const response = await new Promise<{ ja3: string; ja4: string }>((resolve, reject) => {
+            https.get(`https://localhost:${serverPort}/tls/fingerprint`, {
+                rejectUnauthorized: false
+            }, async (res) => {
+                try {
+                    const body = await streamConsumers.text(res);
+                    resolve(JSON.parse(body));
+                } catch (e) {
+                    reject(e);
+                }
+            }).on('error', reject);
+        });
+
+        // Expected fingerprints for Node 24's TLS client
+        expect(response.ja3).to.equal('944d1e1858cd278718f8a46b65d3212f');
+        expect(response.ja4).to.equal('t13d521100_b262b3658495_8e6e362c5eac');
+    });
+
+});