Add support for HTTP-over-SOCKS interception

This is disabled by default, but can be enabled with the new `socks`
option to support incoming SOCKS connections on the same port as all
other traffic.

Author: pimterry

package.json

@@ -141,6 +141,7 @@
     "request": "^2.75.0",
     "request-promise-native": "^1.0.3",
     "rimraf": "^2.5.4",
+    "socks": "^2.8.4",
     "source-map-support": "^0.5.3",
     "stream-browserify": "^3.0.0",
     "tmp-promise": "^1.0.3",
@@ -160,7 +161,7 @@
   "dependencies": {
     "@graphql-tools/schema": "^8.5.0",
     "@graphql-tools/utils": "^8.8.0",
-    "@httptoolkit/httpolyglot": "^2.2.1",
+    "@httptoolkit/httpolyglot": "^3.0.0",
     "@httptoolkit/subscriptions-transport-ws": "^0.11.2",
     "@httptoolkit/util": "^0.1.6",
     "@httptoolkit/websocket-stream": "^6.0.1",

src/mockttp.ts

@@ -695,10 +695,10 @@ export type MockttpHttpsOptions = CAOptions & {
      * options will throw an error.
      *
      * Each element in this list must be an object with a 'hostname' field for the
-     * hostname that should be matched. Wildcards are supported (following the 
+     * hostname that should be matched. Wildcards are supported (following the
      * [URLPattern specification](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API)),
      * eg. `{hostname: '*.example.com'}`.
-     * 
+     *
      * In future more options may be supported
      * here for additional configuration of this behaviour.
      */
@@ -715,10 +715,10 @@ export type MockttpHttpsOptions = CAOptions & {
      * options will throw an error.
      *
      * Each element in this list must be an object with a 'hostname' field for the
-     * hostname that should be matched. Wildcards are supported (following the 
+     * hostname that should be matched. Wildcards are supported (following the
      * [URLPattern specification](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API)),
      * eg. `{hostname: '*.example.com'}`.
-     * 
+     *
      * In future more options may be supported
      * here for additional configuration of this behaviour.
      */
@@ -774,6 +774,15 @@ export interface MockttpOptions {
      */
     http2?: true | 'fallback' | false;
 
+    /**
+     * Should the server accept incoming SOCKS connections? Defaults to false.
+     * If set to true, the server will listen for incoming SOCKS connections
+     * on the same port as the HTTP server, unwrap received connections, and
+     * handle them like any other incoming TCP connection (intercepting HTTP(S)
+     * from within the SOCKS connection as normal).
+     */
+    socks?: boolean;
+
     /**
      * By default, requests that match no rules will receive an explanation of the
      * request & existing rules, followed by some suggested example Mockttp code

src/server/http-combo-server.ts

@@ -9,7 +9,7 @@ import * as streams from 'stream';
 import * as semver from 'semver';
 import { makeDestroyable, DestroyableServer } from 'destroyable-server';
 import * as httpolyglot from '@httptoolkit/httpolyglot';
-import { delay } from '@httptoolkit/util';
+import { delay, unreachableCheck } from '@httptoolkit/util';
 import {
     calculateJa3FromFingerprintData,
     calculateJa4FromHelloData,
@@ -27,6 +27,7 @@ import {
     buildSocketEventData
 } from '../util/socket-util';
 import { MockttpHttpsOptions } from '../mockttp';
+import { buildSocksServer, SocksTcpAddress } from './socks-server';
 
 // Hardcore monkey-patching: force TLSSocket to link servername & remoteAddress to
 // sockets as soon as they're available, without waiting for the handshake to fully
@@ -53,10 +54,11 @@ const originalSocketInit = (<any>tls.TLSSocket.prototype)._init;
     };
 };
 
-export type ComboServerOptions = {
-    debug: boolean,
-    https: MockttpHttpsOptions | undefined,
-    http2: true | false | 'fallback'
+export interface ComboServerOptions {
+    debug: boolean;
+    https: MockttpHttpsOptions | undefined;
+    http2: boolean | 'fallback';
+    socks: boolean;
 };
 
 // Takes an established TLS socket, calls the error listener if it's silently closed
@@ -147,9 +149,10 @@ export async function createComboServer(
     tlsPassthroughListener: (socket: net.Socket, address: string, port?: number) => void
 ): Promise<DestroyableServer<net.Server>> {
     let server: net.Server;
-    if (!options.https) {
-        server = httpolyglot.createServer(requestListener);
-    } else {
+    let tlsServer: tls.Server | undefined = undefined;
+    let socksServer: net.Server | undefined = undefined;
+
+    if (options.https) {
         const ca = await getCA(options.https);
         const defaultCert = ca.generateCertificate(options.https.defaultDomain ?? 'localhost');
 
@@ -179,7 +182,7 @@ export async function createComboServer(
                 ALPNProtocols: serverProtocolPreferences
             }
 
-        const tlsServer = tls.createServer({
+        tlsServer = tls.createServer({
             key: defaultCert.key,
             cert: defaultCert.cert,
             ca: [defaultCert.ca],
@@ -208,10 +211,35 @@ export async function createComboServer(
             options.https.tlsInterceptOnly,
             tlsPassthroughListener
         );
+    }
+
+    if (options.socks) {
+        socksServer = buildSocksServer();
+        socksServer.on('socks-tcp-connect', (socket: net.Socket, address: SocksTcpAddress) => {
+            const addressString =
+                address.type === 'ipv4'
+                    ? `${address.ip}:${address.port}`
+                : address.type === 'ipv6'
+                    ? `[${address.ip}]:${address.port}`
+                : address.type === 'hostname'
+                    ? `${address.hostname}:${address.port}`
+                : unreachableCheck(address)
+
+            if (options.debug) console.log(`Proxying SOCKS TCP connection to ${addressString}`);
+
+            socket.__timingInfo!.tunnelSetupTimestamp = now();
+            socket.__lastHopConnectAddress = addressString;
 
-        server = httpolyglot.createServer(tlsServer, requestListener);
+            // Put the socket back into the server, so we can handle the data within:
+            server.emit('connection', socket);
+        });
     }
 
+    server = httpolyglot.createServer({
+        tls: tlsServer,
+        socks: socksServer,
+    }, requestListener);
+
     // In Node v20, this option was added, rejecting all requests with no host header. While that's good, in
     // our case, we want to handle the garbage requests too, so we disable it:
     (server as any)._httpServer.requireHostHeader = false;
@@ -393,9 +421,22 @@ function analyzeAndMaybePassThroughTls(
         try {
             const helloData = await readTlsClientHello(socket);
 
-            const [connectHostname, connectPort] = socket.__lastHopConnectAddress?.split(':') ?? [];
             const sniHostname = helloData.serverName;
 
+            // SNI is a good clue for where the request is headed, but an explicit proxy address (via
+            // CONNECT or SOCKS) is even better. Note that this may be a hostname or IPv4/6 address:
+            let connectHostname: string | undefined;
+            let connectPort: string | undefined;
+            if (socket.__lastHopConnectAddress) {
+                const lastColonIndex = socket.__lastHopConnectAddress.lastIndexOf(':');
+                if (lastColonIndex !== -1) {
+                    connectHostname = socket.__lastHopConnectAddress.slice(0, lastColonIndex);
+                    connectPort = socket.__lastHopConnectAddress.slice(lastColonIndex + 1);
+                } else {
+                    connectHostname = socket.__lastHopConnectAddress;
+                }
+            }
+
             socket.__tlsMetadata = {
                 sniHostname,
                 connectHostname,

src/server/mockttp-server.ts

@@ -86,7 +86,8 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
     private webSocketRuleSets: { [priority: number]: WebSocketRule[] } = {};
 
     private httpsOptions: MockttpHttpsOptions | undefined;
-    private isHttp2Enabled: true | false | 'fallback';
+    private isHttp2Enabled: boolean | 'fallback';
+    private socksEnabled: boolean;
     private maxBodySize: number;
 
     private app: connect.Server;
@@ -105,6 +106,7 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
 
         this.httpsOptions = options.https;
         this.isHttp2Enabled = options.http2 ?? 'fallback';
+        this.socksEnabled = options.socks ?? false;
         this.maxBodySize = options.maxBodySize ?? Infinity;
         this.eventEmitter = new EventEmitter();
 
@@ -130,6 +132,7 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
             debug: this.debug,
             https: this.httpsOptions,
             http2: this.isHttp2Enabled,
+            socks: this.socksEnabled
         }, this.app, this.announceTlsErrorAsync.bind(this), this.passthroughSocket.bind(this));
 
         // We use a mutex here to avoid contention on ports with parallel setup