feat: add https proxy server implementation (#626)

Author: bliuchak

README.md

@@ -110,6 +110,99 @@ server.on('requestFailed', ({ request, error }) => {
 });
 ```
 
+## Run a simple HTTPS proxy server
+
+This example demonstrates how to create an HTTPS proxy server with a self-signed certificate. The HTTPS proxy server works identically to the HTTP version but with TLS encryption.
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+const ProxyChain = require('proxy-chain');
+
+(async () => {
+    // TODO: update these lines to use your own key and cert
+    const sslKey = fs.readFileSync(path.join(__dirname, 'ssl.key'));
+    const sslCrt = fs.readFileSync(path.join(__dirname, 'ssl.crt'));
+
+    const server = new ProxyChain.Server({
+        // Main difference between 'http' and 'https' is additional event listening:
+        //
+        // http
+        // -> listen for 'connection' events to track raw TCP sockets
+        //
+        // https:
+        // -> listen for 'securedConnection' events (instead of 'connection') to track only post-TLS-handshake sockets
+        // -> additionally listen for 'tlsError' events to handle TLS handshake errors
+        //
+        // Default value is 'http'
+        serverType: 'https',
+
+        // Provide the TLS certificate and private key
+        httpsOptions: {
+            key: sslKey,
+            cert: sslCrt,
+        },
+
+        // Port where the server will listen
+        port: 8443,
+
+        // Enable verbose logging to see what's happening
+        verbose: true,
+
+        // Optional: Add authentication and upstream proxy configuration
+        prepareRequestFunction: ({ username, hostname, port }) => {
+            console.log(`Request to ${hostname}:${port} from user: ${username || 'anonymous'}`);
+
+            // Allow the request
+            return {};
+        },
+    });
+
+    // Handle failed HTTP/HTTPS requests
+    server.on('requestFailed', ({ request, error }) => {
+        console.log(`Request ${request.url} failed`);
+        console.error(error);
+    });
+
+    // Handle TLS handshake errors
+    server.on('tlsError', ({ error, socket }) => {
+        console.error(`TLS error from ${socket.remoteAddress}: ${error.message}`);
+    });
+
+    // Emitted when HTTP/HTTPS connection is closed
+    server.on('connectionClosed', ({ connectionId, stats }) => {
+        console.log(`Connection ${connectionId} closed`);
+        console.dir(stats);
+    });
+
+    // Start the server
+    await server.listen();
+
+    // Handle graceful shutdown
+    process.on('SIGINT', async () => {
+        console.log('\nShutting down server...');
+        await server.close(true);
+        console.log('Server closed.');
+        process.exit(0);
+    });
+
+    // Keep the server running
+    await new Promise(() => { });
+})();
+```
+
+Run server:
+
+```bash
+node https_proxy_server.js
+```
+
+Send request via proxy:
+
+```bash
+curl --proxy-insecure -x https://localhost:8443 -k https://example.com
+```
+
 ## Use custom HTTP agents for connection pooling
 
 You can provide custom HTTP/HTTPS agents to enable connection pooling and reuse with upstream proxies. This is particularly useful for maintaining sticky IP addresses or reducing connection overhead:

package.json

@@ -1,6 +1,6 @@
 {
     "name": "proxy-chain",
-    "version": "2.6.1",
+    "version": "2.7.0",
     "description": "Node.js implementation of a proxy server (think Squid) with support for SSL, authentication, upstream proxy chaining, and protocol tunneling.",
     "main": "dist/index.js",
     "keywords": [
@@ -37,8 +37,9 @@
         "clean": "rimraf dist",
         "prepublishOnly": "npm run build",
         "local-proxy": "node ./dist/run_locally.js",
-        "test": "nyc cross-env NODE_OPTIONS=--insecure-http-parser mocha --bail",
-        "test:docker": "docker build --tag proxy-chain-tests --file test/Dockerfile . &&  docker run proxy-chain-tests",
+        "test": "nyc cross-env NODE_OPTIONS=--insecure-http-parser mocha",
+        "test:docker": "docker build --tag proxy-chain-tests --file test/Dockerfile . && docker run proxy-chain-tests",
+        "test:docker:all": "bash scripts/test-docker-all.sh",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix"
     },

scripts/test-docker-all.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+echo "Starting parallel Docker tests for Node 14, 16, and 18..."
+
+# Run builds in parallel, capture PIDs.
+docker build --build-arg NODE_IMAGE=node:14.21.3-bullseye --tag proxy-chain-tests:node14 --file test/Dockerfile . && docker run proxy-chain-tests:node14 &
+pid14=$!
+docker build --build-arg NODE_IMAGE=node:16.20.2-bookworm --tag proxy-chain-tests:node16 --file test/Dockerfile . && docker run proxy-chain-tests:node16 &
+pid16=$!
+docker build --build-arg NODE_IMAGE=node:18.20.8-bookworm --tag proxy-chain-tests:node18 --file test/Dockerfile . && docker run proxy-chain-tests:node18 &
+pid18=$!
+
+# Wait for all and capture exit codes.
+wait $pid14
+ec14=$?
+wait $pid16
+ec16=$?
+wait $pid18
+ec18=$?
+
+echo ""
+echo "========== Results =========="
+echo "Node 14: $([ $ec14 -eq 0 ] && echo 'PASS' || echo 'FAIL')"
+echo "Node 16: $([ $ec16 -eq 0 ] && echo 'PASS' || echo 'FAIL')"
+echo "Node 18: $([ $ec18 -eq 0 ] && echo 'PASS' || echo 'FAIL')"
+echo "============================="
+
+# Exit with non-zero if any failed.
+exit $((ec14 + ec16 + ec18))

src/server.ts

@@ -3,7 +3,7 @@ import { Buffer } from 'node:buffer';
 import type dns from 'node:dns';
 import { EventEmitter } from 'node:events';
 import http from 'node:http';
-import type https from 'node:https';
+import https from 'node:https';
 import type net from 'node:net';
 import { URL } from 'node:url';
 import util from 'node:util';
@@ -19,7 +19,7 @@ import type { HandlerOpts as ForwardOpts } from './forward';
 import { forward } from './forward';
 import { forwardSocks } from './forward_socks';
 import { RequestError } from './request_error';
-import type { Socket } from './socket';
+import type { Socket, TLSSocket } from './socket';
 import { badGatewayStatusCodes } from './statuses';
 import { getTargetStats } from './utils/count_target_bytes';
 import { nodeify } from './utils/nodeify';
@@ -41,10 +41,23 @@ export const SOCKS_PROTOCOLS = ['socks:', 'socks4:', 'socks4a:', 'socks5:', 'soc
 const DEFAULT_AUTH_REALM = 'ProxyChain';
 const DEFAULT_PROXY_SERVER_PORT = 8000;
 
+const HTTPS_DEFAULT_OPTIONS = {
+    // Disable TLS 1.0 and 1.1 (deprecated, insecure).
+    // All other TLS settings use Node.js defaults for cipher selection (automatically updated).
+    minVersion: 'TLSv1.2',
+} as const;
+
+/**
+ * Connection statistics for bandwidth tracking.
+ */
 export type ConnectionStats = {
+    // Bytes sent by proxy to client.
     srcTxBytes: number;
+    // Bytes received by proxy from client.
     srcRxBytes: number;
+    // Bytes sent by proxy to target.
     trgTxBytes: number | null;
+    // Bytes received by proxy from target.
     trgRxBytes: number | null;
 };
 
@@ -96,10 +109,31 @@ export type PrepareRequestFunctionResult = {
 type Promisable<T> = T | Promise<T>;
 export type PrepareRequestFunction = (opts: PrepareRequestFunctionOpts) => Promisable<undefined | PrepareRequestFunctionResult>;
 
+type ServerOptionsBase = {
+    port?: number;
+    host?: string;
+    prepareRequestFunction?: PrepareRequestFunction;
+    verbose?: boolean;
+    authRealm?: unknown;
+};
+
+export type HttpServerOptions = ServerOptionsBase & {
+    serverType?: 'http';
+};
+
+export type HttpsServerOptions = ServerOptionsBase & {
+    serverType: 'https';
+    httpsOptions: https.ServerOptions;
+};
+
+export type ServerOptions = HttpServerOptions | HttpsServerOptions;
+
 /**
  * Represents the proxy server.
  * It emits the 'requestFailed' event on unexpected request errors, with the following parameter `{ error, request }`.
  * It emits the 'connectionClosed' event when connection to proxy server is closed, with parameter `{ connectionId, stats }`.
+ * It emits the 'tlsError' event on TLS handshake failures (HTTPS servers only), with parameter `{ error, socket }`.
+ * with parameter `{ connectionId, reason, hasParent, parentType }`.
  */
 export class Server extends EventEmitter {
     port: number;
@@ -112,7 +146,9 @@ export class Server extends EventEmitter {
 
     verbose: boolean;
 
-    server: http.Server;
+    server: http.Server | https.Server;
+
+    serverType: 'http' | 'https';
 
     lastHandlerId: number;
 
@@ -124,6 +160,9 @@ export class Server extends EventEmitter {
      * Initializes a new instance of Server class.
      * @param options
      * @param [options.port] Port where the server will listen. By default 8000.
+     * @param [options.serverType] Type of server to create: 'http' or 'https'. By default 'http'.
+     * @param [options.httpsOptions] HTTPS server options (required when serverType is 'https').
+     * Accepts standard Node.js https.ServerOptions including key, cert, ca, passphrase, etc.
      * @param [options.prepareRequestFunction] Custom function to authenticate proxy requests,
      * provide URL to upstream proxy or potentially provide a function that generates a custom response to HTTP requests.
      * It accepts a single parameter which is an object:
@@ -154,13 +193,7 @@ export class Server extends EventEmitter {
      * @param [options.authRealm] Realm used in the Proxy-Authenticate header and also in the 'Server' HTTP header. By default it's `ProxyChain`.
      * @param [options.verbose] If true, the server will output logs
      */
-    constructor(options: {
-        port?: number,
-        host?: string,
-        prepareRequestFunction?: PrepareRequestFunction,
-        verbose?: boolean,
-        authRealm?: unknown,
-    } = {}) {
+    constructor(options: ServerOptions = {}) {
         super();
 
         if (options.port === undefined || options.port === null) {
@@ -174,11 +207,43 @@ export class Server extends EventEmitter {
         this.authRealm = options.authRealm || DEFAULT_AUTH_REALM;
         this.verbose = !!options.verbose;
 
-        this.server = http.createServer();
+        // Keep legacy behavior (http) as default behavior.
+        this.serverType = options.serverType === 'https' ? 'https' : 'http';
+
+        if (options.serverType === 'https') {
+            if (!options.httpsOptions) {
+                throw new Error('httpsOptions is required when serverType is "https"');
+            }
+
+            // Apply secure TLS defaults (user options can override).
+            const effectiveOptions: https.ServerOptions = {
+                ...HTTPS_DEFAULT_OPTIONS,
+                honorCipherOrder: true,
+                ...options.httpsOptions,
+            };
+
+            this.server = https.createServer(effectiveOptions);
+        } else {
+            this.server = http.createServer();
+        }
+
+        // Attach common event handlers (same for both HTTP and HTTPS).
         this.server.on('clientError', this.onClientError.bind(this));
         this.server.on('request', this.onRequest.bind(this));
         this.server.on('connect', this.onConnect.bind(this));
-        this.server.on('connection', this.onConnection.bind(this));
+
+        // Attach connection tracking based on server type.
+        // Only listen to one connection event to avoid double registration.
+        if (this.serverType === 'https') {
+            // For HTTPS: Track only post-TLS-handshake sockets (secureConnection).
+            // This ensures we track the TLS-wrapped socket with correct bytesRead/bytesWritten.
+            this.server.on('secureConnection', this.onConnection.bind(this));
+            // Handle TLS handshake errors to prevent server crashes.
+            this.server.on('tlsClientError', this.onTLSClientError.bind(this));
+        } else {
+            // For HTTP: Track raw TCP sockets (connection).
+            this.server.on('connection', this.onConnection.bind(this));
+        }
 
         this.lastHandlerId = 0;
         this.stats = {
@@ -189,6 +254,29 @@ export class Server extends EventEmitter {
         this.connections = new Map();
     }
 
+    /**
+     * Handles TLS handshake errors for HTTPS servers.
+     * Without this handler, unhandled TLS errors can crash the server.
+     * Common errors: ECONNRESET, ERR_SSL_SSLV3_ALERT_CERTIFICATE_UNKNOWN,
+     * ERR_SSL_TLSV1_ALERT_PROTOCOL_VERSION, ERR_SSL_SSLV3_ALERT_HANDSHAKE_FAILURE
+     */
+    onTLSClientError(err: NodeJS.ErrnoException, tlsSocket: TLSSocket): void {
+        const connectionId = (tlsSocket as TLSSocket).proxyChainId;
+        this.log(connectionId, `TLS handshake failed: ${err.message}`);
+
+        // Emit event in first place before any return statement.
+        this.emit('tlsError', { error: err, socket: tlsSocket });
+
+        // If connection already reset or socket not writable, nothing more to do.
+        if (err.code === 'ECONNRESET' || !tlsSocket.writable) {
+            return;
+        }
+
+        // TLS handshake failed before HTTP, cannot send HTTP response.
+        // Destroy the socket to clean up.
+        tlsSocket.destroy(err);
+    }
+
     log(connectionId: unknown, str: string): void {
         if (this.verbose) {
             const logPrefix = connectionId != null ? `${String(connectionId)} | ` : '';

test/Dockerfile

@@ -1,4 +1,5 @@
-FROM node:18.20.8-bookworm@sha256:c6ae79e38498325db67193d391e6ec1d224d96c693a8a4d943498556716d3783
+ARG NODE_IMAGE=node:18.20.8-bookworm
+FROM ${NODE_IMAGE}
 
 RUN apt-get update && apt-get install -y --no-install-recommends chromium \
     && rm -rf /var/lib/apt/lists/*