Add mirrorTlsFingerprint option to passthrough rules

Author: pimterry

package.json

@@ -204,5 +204,8 @@
     "socks-proxy-agent": "^8.0.5",
     "urlpattern-polyfill": "^10.1.0",
     "ws": "^8.20.0"
+  },
+  "optionalDependencies": {
+    "tls-impersonate": "^0.1.0"
   }
 }

src/rules/passthrough-handling-definitions.ts

@@ -121,6 +121,19 @@ export interface PassThroughStepConnectionOptions {
      * transparently proxy network traffic, errors and all.
      */
     simulateConnectionErrors?: boolean;
+
+    /**
+     * Mirror the inbound connection's TLS fingerprint into the upstream connection, so
+     * that the proxied request presents the same TLS ClientHello (cipher suites, extensions,
+     * curves, etc) as the original client, instead of Mockttp's own default fingerprint.
+     *
+     * This only applies to intercepted HTTPS/TLS traffic (where we have a client hello to
+     * mirror), and requires the native `tls-impersonate` module - fully effective on Node
+     * v26.4+. Where impersonation isn't available, this falls back to the default fingerprint.
+     *
+     * Defaults to false.
+     */
+    mirrorTlsFingerprint?: boolean;
 }
 
 /**

src/rules/passthrough-handling.ts

@@ -19,7 +19,9 @@ import { isMockttpBody, encodeBodyBuffer } from '../util/request-utils';
 import { areFFDHECurvesSupported } from '../util/openssl-compat';
 import { findRawHeaderIndex, getHeaderValue } from '../util/header-utils';
 import { getDefaultPort } from '../util/url';
-import { TlsMetadata } from '../util/socket-extensions';
+import { TlsMetadata, TlsClientHello } from '../util/socket-extensions';
+import { buildTlsImpersonationConfig } from '../util/tls-impersonation';
+import type { Connection } from './http-agents';
 
 import {
     CallbackRequestResult,
@@ -37,6 +39,11 @@ import { applyMatchReplace } from './match-replace';
 // issues so far as possible, by closely emulating a Firefox Client Hello:
 const NEW_CURVES_SUPPORTED = areFFDHECurvesSupported(process.versions.openssl);
 
+// Trust intermediate certificates from the trusted CA list too. Without this, trusted CAs
+// are only used when they are self-signed root certificates. Seems to cause issues in Node v20
+// in HTTP/2 tests, so disabled below the supported v22 version.
+const allowPartialTrustChain = semver.satisfies(process.version, '>=22.9.0');
+
 const SSL_OP_LEGACY_SERVER_CONNECT = 1 << 2;
 const SSL_OP_TLSEXT_PADDING = 1 << 4;
 const SSL_OP_NO_ENCRYPT_THEN_MAC = 1 << 19;
@@ -49,7 +56,10 @@ export function getUpstreamTlsOptions({
 
     ignoreHostHttpsErrors,
     clientCertificateHostMap,
-    trustedCAs
+    trustedCAs,
+
+    connection,
+    tryHttp2Upstream
 }: {
     // The effective hostname & port we're connecting to - note that this isn't exactly
     // the same as the destination (e.g. if you tunnel to an IP but set a hostname via SNI
@@ -60,7 +70,13 @@ export function getUpstreamTlsOptions({
     // The general config that's relevant to this request:
     ignoreHostHttpsErrors: string[] | boolean,
     clientCertificateHostMap: { [host: string]: { pfx: Buffer, passphrase?: string } },
-    trustedCAs: Array<string> | undefined
+    trustedCAs: Array<string> | undefined,
+
+    // The downstream connection, used to mirror client hellos.
+    connection?: Connection,
+
+    // Whether we're going to attempt HTTP/2 upstream, required to control our ALPN configuration.
+    tryHttp2Upstream?: boolean
 }): tls.ConnectionOptions {
     const strictHttpsChecks = shouldUseStrictHttps(hostname, port, ignoreHostHttpsErrors);
 
@@ -70,12 +86,53 @@ export function getUpstreamTlsOptions({
         clientCertificateHostMap['*'] ||
         {};
 
-    return {
+    // Allow connecting to old servers that don't support secure renegotiation, iff not strict:
+    const maybeLegacyConnect = strictHttpsChecks ? 0 : SSL_OP_LEGACY_SERVER_CONNECT;
+
+    const trustOptions: tls.SecureContextOptions = {
+        allowPartialTrustChain,
+        ...(trustedCAs ? { ca: trustedCAs } : {}),
+        ...clientCert
+    };
+
+    const connectionOptions: tls.ConnectionOptions = {
         servername: hostname && !isIP(hostname)
             ? hostname
             : undefined, // Can't send IPs in SNI
+        rejectUnauthorized: strictHttpsChecks
+    };
+
+    // If the connection carries an inbound client hello to mirror, reproduce its TLS fingerprint
+    // upstream instead of our default.
+    const clientHello = connection?.[TlsClientHello];
+    if (connection && clientHello) {
+        const impersonationConfig = buildTlsImpersonationConfig(connection, clientHello, {
+            ...trustOptions,
+            ...(maybeLegacyConnect ? { secureOptions: maybeLegacyConnect } : {}),
+            security: strictHttpsChecks ? 'secure' : 'insecure'
+        });
+
+        // This should only be undefined if impersonation isn't supported:
+        if (impersonationConfig) {
+            // Mirror the client's ALPN, filtered to protocols we want upstream.
+            // N.b. http2-wrapper currently overrides ALPN on the H2 path regardless (for now).
+            const speakableUpstreamAlpn = tryHttp2Upstream ? ['h2', 'http/1.1'] : ['http/1.1'];
+            const mirroredAlpn = impersonationConfig.tlsOptions.ALPNProtocols
+                ?.filter(p => speakableUpstreamAlpn.includes(p));
+
+            return {
+                ...connectionOptions,
+                ...impersonationConfig.tlsOptions,
+                ALPNProtocols: mirroredAlpn?.length ? mirroredAlpn : undefined
+            };
+        }
+    }
+
+    // Default fingerprint, emulating a Firefox v103 client hello to limit TLS fingerprinting issues:
+    return {
+        ...connectionOptions,
+        ...trustOptions,
 
-        // We precisely control the various TLS parameters here to limit TLS fingerprinting issues:
         ecdhCurve: [
             'X25519',
             'prime256v1', // N.B. Equivalent to secp256r1
@@ -127,32 +184,11 @@ export function getUpstreamTlsOptions({
                 : []
             )
         ].join(':'),
-        secureOptions: strictHttpsChecks
-            ? SSL_OP_TLSEXT_PADDING | SSL_OP_NO_ENCRYPT_THEN_MAC
-            : SSL_OP_TLSEXT_PADDING | SSL_OP_NO_ENCRYPT_THEN_MAC | SSL_OP_LEGACY_SERVER_CONNECT,
-        ...({
-            // Valid, but not included in Node.js TLS module types:
-            requestOSCP: true
-        } as any),
-
-        // Trust intermediate certificates from the trusted CA list too. Without this, trusted CAs
-        // are only used when they are self-signed root certificates. Seems to cause issues in Node v20
-        // in HTTP/2 tests, so disabled below the supported v22 version.
-        allowPartialTrustChain: semver.satisfies(process.version, '>=22.9.0'),
+        secureOptions: SSL_OP_TLSEXT_PADDING | SSL_OP_NO_ENCRYPT_THEN_MAC | maybeLegacyConnect,
+        requestOCSP: true,
 
         // Allow TLSv1, if !strict:
-        minVersion: strictHttpsChecks ? tls.DEFAULT_MIN_VERSION : 'TLSv1',
-
-        // Skip certificate validation entirely, if not strict:
-        rejectUnauthorized: strictHttpsChecks,
-
-        // Override the set of trusted CAs, if configured to do so:
-        ...(trustedCAs ? {
-            ca: trustedCAs
-        } : {}),
-
-        // Use a client cert, if one matches for this hostname+port:
-        ...clientCert
+        minVersion: strictHttpsChecks ? tls.DEFAULT_MIN_VERSION : 'TLSv1'
     }
 }
 

src/rules/requests/request-step-definitions.ts

@@ -682,6 +682,7 @@ export interface SerializedPassThroughData {
     clientCertificateHostMap?: { [host: string]: { pfx: string, passphrase?: string } };
     lookupOptions?: PassThroughLookupOptions;
     simulateConnectionErrors?: boolean;
+    mirrorTlsFingerprint?: boolean;
 
     transformRequest?: Replace<RequestTransform, {
         'replaceBody'?: string, // Serialized as base64 buffer
@@ -756,6 +757,8 @@ export class PassThroughStep extends Serializable implements RequestStepDefiniti
 
     public readonly simulateConnectionErrors: boolean;
 
+    public readonly mirrorTlsFingerprint: boolean;
+
     constructor(options: PassThroughStepOptions = {}) {
         super();
 
@@ -767,6 +770,7 @@ export class PassThroughStep extends Serializable implements RequestStepDefiniti
         this.lookupOptions = options.lookupOptions;
         this.proxyConfig = options.proxyConfig;
         this.simulateConnectionErrors = !!options.simulateConnectionErrors;
+        this.mirrorTlsFingerprint = !!options.mirrorTlsFingerprint;
 
         this.extraCACertificates = options.additionalTrustedCAs || [];
 
@@ -919,6 +923,7 @@ export class PassThroughStep extends Serializable implements RequestStepDefiniti
             proxyConfig: serializeProxyConfig(this.proxyConfig, channel),
             lookupOptions: this.lookupOptions,
             simulateConnectionErrors: this.simulateConnectionErrors,
+            mirrorTlsFingerprint: this.mirrorTlsFingerprint,
             ignoreHostCertificateErrors: this.ignoreHostHttpsErrors,
             extraCACertificates: this.extraCACertificates.map((certObject) => {
                 // We use toString to make sure that buffers always end up as

src/rules/requests/request-step-impls.ts

@@ -799,7 +799,13 @@ export class PassThroughStepImpl extends PassThroughStep {
                     port: effectivePort,
                     ignoreHostHttpsErrors: this.ignoreHostHttpsErrors,
                     clientCertificateHostMap: this.clientCertificateHostMap,
-                    trustedCAs
+                    trustedCAs,
+
+                    // Pass the connection through to mirror its inbound TLS fingerprint upstream,
+                    // if that's enabled (getUpstreamTlsOptions reads the hello from it):
+                    ...(this.mirrorTlsFingerprint && protocol === 'https:'
+                        ? { connection, tryHttp2Upstream: shouldTryH2Upstream }
+                        : {})
                 })
             }, (serverRes) => (async () => {
                 serverRes.on('error', (e: any) => {
@@ -1423,6 +1429,7 @@ export class PassThroughStepImpl extends PassThroughStep {
             } as ResponseTransform : undefined,
             lookupOptions: data.lookupOptions,
             simulateConnectionErrors: !!data.simulateConnectionErrors,
+            mirrorTlsFingerprint: !!data.mirrorTlsFingerprint,
             ignoreHostHttpsErrors: data.ignoreHostCertificateErrors,
             additionalTrustedCAs: data.extraCACertificates,
             clientCertificateHostMap: _.mapValues(data.clientCertificateHostMap,

src/server/http-combo-server.ts

@@ -38,6 +38,7 @@ import {
     LastTunnelAddress,
     LastHopEncrypted,
     TlsMetadata,
+    TlsClientHello,
     TlsSetupCompleted,
     SocketMetadata,
     Expects100Continue,
@@ -366,6 +367,7 @@ export async function createComboServer(options: ComboServerOptions): Promise<De
             // With TLS metadata, we only propagate directly from parent sockets, not through
             // CONNECT etc - we only want it if the final hop is TLS, previous values don't matter.
             socket[TlsMetadata] ??= parentSocket[TlsMetadata];
+            socket[TlsClientHello] ??= parentSocket[TlsClientHello];
         } else if (!socket[SocketTimingInfo]) {
             socket[SocketTimingInfo] = buildSocketTimingInfo();
         }
@@ -383,6 +385,7 @@ export async function createComboServer(options: ComboServerOptions): Promise<De
     server!.on('session', (session) => {
         session.once('remoteSettings', () => {
             (session.socket as tls.TLSSocket)[TlsSetupCompleted] = true;
+            session[TlsClientHello] ??= session.initialSocket?.[TlsClientHello];
         });
     });
 
@@ -542,6 +545,10 @@ function analyzeAndMaybePassThroughTls(
                 ja4Fingerprint: calculateJa4(helloData)
             };
 
+            // Keep the raw parsed hello too, so it can be mirrored into the upstream TLS
+            // connection later (fingerprint impersonation):
+            socket[TlsClientHello] = helloData;
+
             if (shouldPassThrough(upstreamDestination?.hostname, passThroughPatterns, interceptOnlyPatterns)) {
                 passthroughListener(socket, upstreamDestination.hostname, upstreamDestination.port);
                 return; // Do not continue with TLS

src/util/socket-extensions.ts

@@ -1,6 +1,7 @@
 import type * as streams from 'stream';
 import type * as net from 'net';
 import type * as tls from 'tls';
+import type { TlsClientHelloMessage } from 'read-tls-client-hello';
 import { TlsSocketMetadata } from '../types';
 
 // We store a bunch of metadata that we directly attach to sockets, TLS
@@ -16,6 +17,7 @@ export const SocketTimingInfo = Symbol('socket-timing-info');
 export const SocketMetadata = Symbol('socket-metadata');
 export const Expects100Continue = Symbol('expects-100-continue');
 export const UpstreamConnectionAgents = Symbol('upstream-connection-agents');
+export const TlsClientHello = Symbol('tls-client-hello');
 
 /**
  * The set of upstream agents dedicated to a single downstream connection (or
@@ -73,6 +75,7 @@ declare module 'net' {
         [TlsMetadata]?: TlsSocketMetadata;
         [InitialRemoteAddress]?: string;
         [InitialRemotePort]?: number;
+        [TlsClientHello]?: TlsClientHelloMessage;
 
         /**
          * Arbitrary custom metadata that may be added during socket processing,
@@ -112,6 +115,8 @@ declare module 'tls' {
          */
         [InitialRemoteAddress]?: string;
         [InitialRemotePort]?: number;
+
+        [TlsClientHello]?: TlsClientHelloMessage;
     }
 }
 
@@ -138,6 +143,8 @@ declare module 'http2' {
 
         // Upstream agents for this session (the connection for all its H2 requests).
         [UpstreamConnectionAgents]?: UpstreamConnectionAgentMap;
+
+        [TlsClientHello]?: TlsClientHelloMessage;
     }
 
     interface ServerHttp2Stream {
@@ -149,6 +156,8 @@ declare module 'http2' {
 
         // Upstream agents owned by this H2 CONNECT tunnel stream (plaintext requests within it).
         [UpstreamConnectionAgents]?: UpstreamConnectionAgentMap;
+
+        [TlsClientHello]?: TlsClientHelloMessage;
     }
 }
 

src/util/tls-impersonation.ts

@@ -0,0 +1,86 @@
+import type * as tls from 'tls';
+import type { TlsClientHelloMessage } from 'read-tls-client-hello';
+
+import type { Connection } from '../rules/http-agents';
+
+// We declare the bits of tls-impersonate we use locally, rather than importing its types,
+// because it's an optional dep so might not be present (old Node CI).
+export interface ImpersonateResult {
+    tlsOptions: {
+        secureContext: tls.SecureContext;
+        ALPNProtocols?: string[];
+        requestOCSP?: boolean;
+    };
+    unsupported: Array<{ kind: string, id: number, reason: string }>;
+}
+
+export interface ImpersonateOptions extends tls.SecureContextOptions {
+    security?: 'secure' | 'insecure';
+}
+
+interface TlsImpersonate {
+    isSupported(): boolean;
+    impersonateFromClientHello(
+        hello: TlsClientHelloMessage,
+        options?: ImpersonateOptions
+    ): ImpersonateResult;
+}
+
+let impersonateModule: TlsImpersonate | null | undefined;
+
+/**
+ * Load tls-impersonate, if it's usable on this runtime. It's an optional, native, Node-only module
+ * (fully effective on Node 26.4+, usable with reduced fidelity from 24.15) and may be entirely
+ * absent (unsupported platform/Node, or no native build). We tolerate all of that by disabling
+ * mirroring, so callers fall back to Mockttp's default upstream fingerprint.
+ *
+ * This is only ever reached when mirroring is explicitly enabled, so if the module isn't usable we
+ * warn once (including on older Node): the caller asked to mirror fingerprints and it won't happen.
+ */
+function loadImpersonate(): TlsImpersonate | null {
+    if (impersonateModule !== undefined) return impersonateModule;
+
+    try {
+        const loaded = require('tls-impersonate') as TlsImpersonate;
+        impersonateModule = loaded?.isSupported?.() ? loaded : null;
+    } catch {
+        impersonateModule = null;
+    }
+
+    if (!impersonateModule) {
+        console.warn('TLS fingerprint mirroring is enabled but unavailable - ' +
+            'upstream requests will use the default TLS fingerprint instead.');
+    }
+
+    return impersonateModule;
+}
+
+const impersonationCache = new WeakMap<Connection, ImpersonateResult | undefined>();
+
+/**
+ * Get (building & caching once per connection) a TLS SecureContext + connect options that
+ * reproduce the inbound ClientHello, folding in the given context options (trusted CAs, client
+ * cert). Returns undefined if impersonation is unavailable or fails, so callers fall back to
+ * Mockttp's default upstream fingerprint.
+ */
+export function buildTlsImpersonationConfig(
+    connection: Connection,
+    hello: TlsClientHelloMessage,
+    options: ImpersonateOptions
+): ImpersonateResult | undefined {
+    if (impersonationCache.has(connection)) return impersonationCache.get(connection);
+
+    const impersonate = loadImpersonate();
+    let result: ImpersonateResult | undefined;
+
+    if (impersonate) {
+        try {
+            result = impersonate.impersonateFromClientHello(hello, options);
+        } catch (e) {
+            console.warn(`Failed to impersonate inbound TLS fingerprint: ${(e as Error).message}`);
+        }
+    }
+
+    impersonationCache.set(connection, result);
+    return result;
+}