Add TLS version endpoints, restructuring the TLS handler approach

pimterry · pimterry · commit ea669ee9722f · 2026-02-06T21:53:31.000+01:00
We now manually build a TLSSocket on each socket, instead of using a
server. Mostly simpler, some small workarounds required.
diff --git a/src/endpoints/tls-index.ts b/src/endpoints/tls-index.ts
@@ -12,3 +12,4 @@ export * from './tls/alpn-specifiers.js';
 export * from './tls/cert-modes.js';
 export * from './tls/example.js';
 export * from './tls/no-tls.js';
+export * from './tls/tls-versions.js';
diff --git a/src/endpoints/tls/tls-versions.ts b/src/endpoints/tls/tls-versions.ts
@@ -0,0 +1,78 @@
+import * as tls from 'tls';
+import * as crypto from 'crypto';
+import { TlsEndpoint } from '../tls-index.js';
+
+const {
+    SSL_OP_NO_TLSv1,
+    SSL_OP_NO_TLSv1_1,
+    SSL_OP_NO_TLSv1_2,
+    SSL_OP_NO_TLSv1_3
+} = crypto.constants;
+
+const ALL_VERSIONS_DISABLED = SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1 | SSL_OP_NO_TLSv1_2 | SSL_OP_NO_TLSv1_3;
+
+const VERSION_FLAGS: Record<tls.SecureVersion, number> = {
+    'TLSv1': SSL_OP_NO_TLSv1,
+    'TLSv1.1': SSL_OP_NO_TLSv1_1,
+    'TLSv1.2': SSL_OP_NO_TLSv1_2,
+    'TLSv1.3': SSL_OP_NO_TLSv1_3,
+};
+
+const VERSION_ORDER: tls.SecureVersion[] = ['TLSv1', 'TLSv1.1', 'TLSv1.2', 'TLSv1.3'];
+
+function enableTlsVersion(opts: tls.SecureContextOptions, version: tls.SecureVersion) {
+    // Start with all versions disabled if not set
+    if (opts.secureOptions === undefined) {
+        opts.secureOptions = ALL_VERSIONS_DISABLED;
+    }
+
+    // Remove the disable flag for this version (enable it)
+    opts.secureOptions &= ~VERSION_FLAGS[version];
+
+    // Set minVersion to the lowest enabled version (Node.js defaults to TLSv1.2)
+    const versionIndex = VERSION_ORDER.indexOf(version);
+    const currentMinIndex = opts.minVersion
+        ? VERSION_ORDER.indexOf(opts.minVersion)
+        : VERSION_ORDER.length;
+
+    if (versionIndex < currentMinIndex) {
+        opts.minVersion = version;
+    }
+
+    // Legacy TLS versions require lowered cipher security level
+    if (versionIndex <= 1 && !opts.ciphers?.includes('@SECLEVEL=0')) {
+        opts.ciphers = `${opts.ciphers || 'DEFAULT'}@SECLEVEL=0`;
+    }
+}
+
+export const tlsV1: TlsEndpoint = {
+    sniPart: 'tls-v1-0',
+    configureTlsOptions(tlsOptions) {
+        enableTlsVersion(tlsOptions, 'TLSv1');
+        return tlsOptions;
+    },
+};
+
+export const tlsV1_1: TlsEndpoint = {
+    sniPart: 'tls-v1-1',
+    configureTlsOptions(tlsOptions) {
+        enableTlsVersion(tlsOptions, 'TLSv1.1');
+        return tlsOptions;
+    },
+};
+
+export const tlsV1_2: TlsEndpoint = {
+    sniPart: 'tls-v1-2',
+    configureTlsOptions(tlsOptions) {
+        enableTlsVersion(tlsOptions, 'TLSv1.2');
+        return tlsOptions;
+    },
+};
+
+export const tlsV1_3: TlsEndpoint = {
+    sniPart: 'tls-v1-3',
+    configureTlsOptions(tlsOptions) {
+        enableTlsVersion(tlsOptions, 'TLSv1.3');
+        return tlsOptions;
+    },
+};
diff --git a/src/http-handler.ts b/src/http-handler.ts
@@ -8,7 +8,7 @@ import { HttpRequest, HttpResponse } from './endpoints/http-index.js';
 
 const MAX_CHAIN_DEPTH = 10;
 
-function resolveEndpointChain(initialPath: string, hostnamePrefix: string | undefined) {
+function resolveEndpointChain(initialPath: string, hostnamePrefix?: string) {
     const entries: Array<{ endpoint: typeof httpEndpoints[number]; path: string }> = [];
     let needsRawData = false;
     let path: string | undefined = initialPath;
diff --git a/src/server.ts b/src/server.ts
@@ -140,7 +140,7 @@ const createTcpHandler = async (options: ServerOptions = {}) => {
                 // Non-TLS traffic or malformed client hello - continue without fingerprint
             }
             conn.pause();
-            tlsHandler.emit('connection', conn);
+            tlsHandler.handleConnection(conn);
         },
         (conn) => httpHandler.emit('connection', conn),
         (conn) => http2Handler.emit('connection', conn)
diff --git a/src/tls-certificates/local-ca.ts b/src/tls-certificates/local-ca.ts
@@ -10,7 +10,7 @@ const crypto = globalThis.crypto;
 
 // This is all approximately based on Mockttp's src/util/certificates.ts CA implementation
 
-export interface CAOptions {
+interface CAOptions {
     key: string;
     cert: string;
 
diff --git a/src/tls-handler.ts b/src/tls-handler.ts
@@ -1,11 +1,14 @@
 import * as tls from 'tls';
 import * as crypto from 'node:crypto';
+import * as stream from 'stream';
+import { EventEmitter } from 'events';
 
 import { ConnectionProcessor } from './process-connection.js';
 import { LocalCA } from './tls-certificates/local-ca.js';
 import { CertOptions, calculateCertCacheKey } from './tls-certificates/cert-definitions.js';
 import { SecureContextCache } from './tls-certificates/secure-context-cache.js';
 import { tlsEndpoints } from './endpoints/endpoint-index.js';
+import { ErrorLike } from '@httptoolkit/util';
 
 const secureContextCache = new SecureContextCache();
 
@@ -40,7 +43,7 @@ interface TlsHandlerConfig {
     cert: string;
     ca: string;
     generateCertificate: CertGenerator;
-    localCA?: LocalCA;
+    localCA: LocalCA;
 }
 
 const DEFAULT_ALPN_PROTOCOLS = ['http/1.1', 'h2'];
@@ -54,7 +57,7 @@ const getSNIPrefixParts = (servername: string, rootDomain: string) => {
     return serverNamePrefix.split('.');
 };
 
-const MAX_SNI_PARTS = 3;
+const MAX_SNI_PARTS = 4;
 
 const PROACTIVE_DOMAIN_REFRESH_INTERVAL = 1000 * 60 * 60 * 24; // Daily cert check for proactive domains
 
@@ -92,82 +95,26 @@ function getEndpointConfig(serverNameParts: string[]) {
     return { certOptions, tlsOptions, alpnPreferences };
 }
 
-export async function createTlsHandler(
-    tlsConfig: TlsHandlerConfig,
-    connProcessor: ConnectionProcessor
-) {
-    const server = tls.createServer({
-        key: tlsConfig.key,
-        cert: tlsConfig.cert,
-        ca: [tlsConfig.ca],
-
-        ALPNCallback: ({ servername, protocols: clientProtocols }) => {
-            const { alpnPreferences } = getEndpointConfig(getSNIPrefixParts(servername, tlsConfig.rootDomain));
-            const protocols = alpnPreferences.length > 0 ? alpnPreferences : DEFAULT_ALPN_PROTOCOLS;
-            // Enforce our own preference order (client can specify via SNI e.g. http2.http1.*)
-            return protocols.find(p => clientProtocols.includes(p));
-        },
-        SNICallback: async (domain: string, cb: Function) => {
-            try {
-                const serverNameParts = getSNIPrefixParts(domain, tlsConfig.rootDomain);
-
-                if (serverNameParts.length > MAX_SNI_PARTS) {
-                    return cb(new Error(`Too many SNI parts (${serverNameParts.length})`), null);
-                }
-
-                const uniqueParts = new Set(serverNameParts);
-                if (uniqueParts.size !== serverNameParts.length) {
-                    return cb(new Error(`Duplicate SNI parts in '${domain}'`), null);
-                }
-
-                const { certOptions, tlsOptions } = getEndpointConfig(serverNameParts);
-
-                const certDomain = certOptions.overridePrefix
-                    ? `${certOptions.overridePrefix}.${tlsConfig.rootDomain}`
-                    : domain;
-
-                const cacheKey = calculateContextCacheKey(certDomain, certOptions, tlsOptions);
-
-                const secureContext = await secureContextCache.getOrCreate(cacheKey, async () => {
-                    const cert = await tlsConfig.generateCertificate(certDomain, certOptions);
-                    return {
-                        context: tls.createSecureContext({
-                            key: cert.key,
-                            cert: cert.cert,
-                            ca: cert.ca,
-                            ...tlsOptions
-                        }),
-                        expiry: getCertExpiry(cert.cert)
-                    };
-                });
-
-                cb(null, secureContext);
-            } catch (e) {
-                console.error('TLS setup error', e);
-                cb(e);
-            }
-        }
-    });
-
-    proactivelyRefreshDomains(tlsConfig.rootDomain, 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;
-        }
-    });
+class TlsConnectionHandler {
     
-    // Handle OCSP stapling requests
-    if (tlsConfig.localCA) {
-        server.on('OCSPRequest', async (cert, issuer, callback) => {
+    // To keep Node happy, we need a TLS server attached to our sockets in some cases
+    // to enable some features (like OCSP). This'll do:
+    private ocspServer = new EventEmitter();
+
+    constructor(
+        private tlsConfig: TlsHandlerConfig,
+        private connProcessor: ConnectionProcessor
+    ) {
+        this.ocspServer.on('OCSPRequest', async (
+            certificate: Buffer,
+            _issuer: Buffer,
+            callback: (err: Error | null, response: Buffer) => void
+        ) => {
             try {
-                const ocspResponse = await tlsConfig.localCA!.getOcspResponse(cert);
+                const ocspResponse = await this.tlsConfig.localCA!.getOcspResponse(certificate);
                 if (ocspResponse) {
                     callback(null, ocspResponse);
                 } else {
-                    // No OCSP response available - don't staple anything
                     callback(null, Buffer.alloc(0));
                 }
             } catch (e) {
@@ -177,9 +124,98 @@ export async function createTlsHandler(
         });
     }
 
-    server.on('secureConnection', (socket) => {
-        connProcessor.processConnection(socket);
-    });
+    async handleConnection(rawSocket: stream.Duplex) {
+        try {
+            const serverName = rawSocket.tlsClientHello?.serverName;
+            const domain = serverName || this.tlsConfig.rootDomain;
+
+            const serverNameParts = getSNIPrefixParts(domain, this.tlsConfig.rootDomain);
+
+            if (serverNameParts.length > MAX_SNI_PARTS) {
+                console.error(`Too many SNI parts (${serverNameParts.length})`);
+                rawSocket.destroy();
+                return;
+            }
+
+            const uniqueParts = new Set(serverNameParts);
+            if (uniqueParts.size !== serverNameParts.length) {
+                console.error(`Duplicate SNI parts in '${domain}'`);
+                rawSocket.destroy();
+                return;
+            }
+
+            const { certOptions, tlsOptions, alpnPreferences } = getEndpointConfig(serverNameParts);
+
+            const certDomain = certOptions.overridePrefix
+                ? `${certOptions.overridePrefix}.${this.tlsConfig.rootDomain}`
+                : domain;
+
+            const cacheKey = calculateContextCacheKey(certDomain, certOptions, tlsOptions);
+
+            const secureContext = await secureContextCache.getOrCreate(cacheKey, async () => {
+                const cert = await this.tlsConfig.generateCertificate(certDomain, certOptions);
+                return {
+                    context: tls.createSecureContext({
+                        key: cert.key,
+                        cert: cert.cert,
+                        ca: cert.ca,
+                        ...tlsOptions
+                    }),
+                    expiry: getCertExpiry(cert.cert)
+                };
+            });
+
+            const alpnProtocols = alpnPreferences.length > 0
+                ? alpnPreferences
+                : DEFAULT_ALPN_PROTOCOLS;
+
+            // Check if client requested OCSP stapling (extension 5 = status_request)
+            const clientExtensions = rawSocket.tlsClientHello?.fingerprintData?.[2];
+            const clientRequestedOCSP = clientExtensions?.includes(5) ?? false;
+
+            const tlsSocket = new tls.TLSSocket(rawSocket, {
+                isServer: true,
+                secureContext,
+                ALPNProtocols: alpnProtocols,
+                // Only set up OCSP machinery if client requested it
+                ...(clientRequestedOCSP ? {
+                    server: this.ocspServer as tls.Server,
+                    // Stub SNICallback to works around a Node limitation where non-server TLS
+                    // sockets don't call OCSPRequest in most cases.
+                    SNICallback: (
+                        _servername: string,
+                        callback: (err: Error | null, ctx?: tls.SecureContext) => void
+                    ) => callback(null, secureContext)
+                } : {})
+            });
+
+            // Transfer tlsClientHello metadata
+            if (rawSocket.tlsClientHello) {
+                tlsSocket.tlsClientHello = rawSocket.tlsClientHello;
+            }
+
+            tlsSocket.on('secure', () => {
+                this.connProcessor.processConnection(tlsSocket);
+            });
+
+            tlsSocket.on('error', (err: ErrorLike) => {
+                // Expected errors during handshake (version mismatch, etc.)
+                if (err.code !== 'ECONNRESET') {
+                    console.error('TLS socket error:', err.message);
+                }
+            });
+        } catch (e) {
+            console.error('TLS setup error', e);
+            rawSocket.destroy();
+        }
+    }
+}
 
-    return server;
-}
+export async function createTlsHandler(
+    tlsConfig: TlsHandlerConfig,
+    connProcessor: ConnectionProcessor
+) {
+    const handler = new TlsConnectionHandler(tlsConfig, connProcessor);
+    proactivelyRefreshDomains(tlsConfig.rootDomain, tlsConfig.proactiveCertDomains ?? [], tlsConfig.generateCertificate);
+    return handler;
+}
diff --git a/test/tls-versions.spec.ts b/test/tls-versions.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -140,7 +140,7 @@ const createTcpHandler = async (options: ServerOptions = {}) => {`
`140`	`140`	`// Non-TLS traffic or malformed client hello - continue without fingerprint`
`141`	`141`	`}`
`142`	`142`	`conn.pause();`
`143`		`- tlsHandler.emit('connection', conn);`
	`143`	`+ tlsHandler.handleConnection(conn);`
`144`	`144`	`},`
`145`	`145`	`(conn) => httpHandler.emit('connection', conn),`
`146`	`146`	`(conn) => http2Handler.emit('connection', conn)`