proxy-chain 3.0.1-beta.5 → 3.0.1-beta.7

package/README.md

@@ -560,18 +560,23 @@ specified by the `proxyUrl` parameter.
 The optional `options` parameter is an object with the following properties:
 - `port: Number` - Enables specifying the local port to listen at. By default `0`,
    which means a random port will be selected.
-- `hostname: String` - Local hostname to listen at. By default `localhost`.
+- `hostname: String` - Local hostname to listen at. By default `127.0.0.1`.
 - `ignoreProxyCertificate` - For HTTPS proxy, ignore certificate errors in proxy requests. Useful for proxy with self-signed certificate. By default `false`.
 - `verbose: Boolean` - If `true`, the functions logs a lot. By default `false`.
 
-The result of the function is a local endpoint in a form of `hostname:port`.
+The result of the function is a local endpoint in a form of `hostname:port`,
+where `hostname` is the address the tunnel actually bound to. IPv6 addresses are
+bracketed, e.g. `[::1]:56836`.
+
 All TCP connections made to the local endpoint will be tunneled through the proxy to the target host and port.
 For example, this is useful if you want to access a certain service from a specific IP address.
 
-The tunnel should be eventually closed by calling the `closeTunnel()` function.
+The tunnel does not authenticate its clients and forwards the `proxyUrl`
+credentials upstream, which is why it listens on `127.0.0.1` by default. Only
+pass a non-loopback `hostname` if you restrict access to it by other means -
+doing so emits a `ProxyChainSecurityWarning` via `process.emitWarning()`.
 
-The `createTunnel()` function returns a promise that resolves to a String with
-the path to the local endpoint.
+The tunnel should be eventually closed by calling the `closeTunnel()` function.
 
 For more information, read this [blog post](https://blog.apify.com/tunneling-arbitrary-protocols-over-http-proxy-with-static-ip-address-b3a2222191ff).
 
@@ -579,7 +584,7 @@ Example:
 
 ```javascript
 const host = await createTunnel('http://bob:pass123@proxy.example.com:8000', 'service.example.com:356');
-// Prints something like "localhost:56836"
+// Prints something like "127.0.0.1:56836"
 console.log(host);
 ```
 

package/dist/anonymize_proxy.d.ts

@@ -3,7 +3,7 @@ import type http from 'node:http';
 import type net from 'node:net';
 export interface AnonymizeProxyOptions {
     url: string;
-    port: number;
+    port?: number;
     ignoreProxyCertificate?: boolean;
 }
 /**

package/dist/anonymize_proxy.js

@@ -1,5 +1,6 @@
 import { URL } from 'node:url';
 import { Server, SOCKS_PROTOCOLS } from './server.js';
+import { validateListenPort } from './utils/validate_listen_port.js';
 // Dictionary, key is value returned from anonymizeProxy(), value is Server instance.
 const anonymizedProxyUrlToServer = {};
 /**
@@ -16,10 +17,9 @@ export const anonymizeProxy = async (options) => {
     }
     else {
         proxyUrl = options.url;
-        port = options.port;
-        if (port < 0 || port > 65535) {
-            throw new Error('Invalid "port" option: only values equals or between 0-65535 are valid');
-        }
+        // Port 0 tells the OS to pick a free ephemeral port, which we read back after `listen()`.
+        port = options.port ?? 0;
+        validateListenPort(port);
         if (options.ignoreProxyCertificate !== undefined) {
             ignoreProxyCertificate = options.ignoreProxyCertificate;
         }

package/dist/tcp_tunnel_tools.d.ts

@@ -1,4 +1,6 @@
 export declare function createTunnel(proxyUrl: string, targetHost: string, options?: {
+    port?: number;
+    hostname?: string;
     verbose?: boolean;
     ignoreProxyCertificate?: boolean;
 }): Promise<string>;

package/dist/tcp_tunnel_tools.js

@@ -1,7 +1,16 @@
 import net from 'node:net';
 import { URL } from 'node:url';
 import { chain } from './chain.js';
+import { validateListenPort } from './utils/validate_listen_port.js';
 const runningServers = {};
+// The tunnel does not authenticate its clients and forwards the proxyUrl credentials
+// upstream, so it must not be reachable off the local machine by default.
+const DEFAULT_LISTEN_HOSTNAME = '127.0.0.1';
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '::1', '0:0:0:0:0:0:0:1']);
+const isLoopbackHostname = (hostname) => {
+    const normalized = hostname.toLowerCase();
+    return LOOPBACK_HOSTNAMES.has(normalized) || normalized.startsWith('127.');
+};
 const getAddress = (server) => {
     const { address: host, port, family } = server.address();
     if (family === 'IPv6') {
@@ -21,7 +30,14 @@ export async function createTunnel(proxyUrl, targetHost, options) {
     if (!url.port) {
         throw new Error('Missing target port');
     }
-    const verbose = options && options.verbose;
+    const listenPort = options?.port ?? 0;
+    const listenHostname = options?.hostname || DEFAULT_LISTEN_HOSTNAME;
+    validateListenPort(listenPort);
+    if (!isLoopbackHostname(listenHostname)) {
+        process.emitWarning(`The tunnel is listening on "${listenHostname}", so it may be reachable from other machines.`
+            + ' It does not authenticate its clients and forwards the proxyUrl credentials upstream.', 'ProxyChainSecurityWarning');
+    }
+    const verbose = options?.verbose ?? false;
     const server = net.createServer();
     const log = (...args) => {
         // eslint-disable-next-line no-console
@@ -51,8 +67,7 @@ export async function createTunnel(proxyUrl, targetHost, options) {
     });
     const promise = new Promise((resolve, reject) => {
         server.once('error', reject);
-        // Let the system pick a random listening port
-        server.listen(0, () => {
+        server.listen(listenPort, listenHostname, () => {
             const address = getAddress(server);
             server.off('error', reject);
             runningServers[address] = { server, connections: new Set() };

package/dist/utils/validate_listen_port.d.ts

@@ -0,0 +1,2 @@
+/** Throws if `port` is not a valid TCP port number (0-65535). */
+export declare const validateListenPort: (port: number) => void;

package/dist/utils/validate_listen_port.js

@@ -0,0 +1,6 @@
+/** Throws if `port` is not a valid TCP port number (0-65535). */
+export const validateListenPort = (port) => {
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`The "port" option must be an integer between 0 and 65535 (was ${port})`);
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proxy-chain",
-  "version": "3.0.1-beta.5",
+  "version": "3.0.1-beta.7",
   "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",
   "type": "module",
@@ -51,45 +51,29 @@
   "devDependencies": {
     "@apify/eslint-config": "^1.0.0",
     "@apify/tsconfig": "^0.1.0",
-    "@types/jest": "^28.1.2",
     "@types/node": "^20.19.29",
+    "@vitest/coverage-v8": "^4.1.11",
     "basic-auth": "^2.0.1",
     "basic-auth-parser": "^0.0.2",
     "body-parser": "^1.19.0",
-    "chai": "^4.3.4",
     "cross-env": "^7.0.3",
     "eslint": "^9.18.0",
     "express": "^4.17.1",
     "faye-websocket": "^0.11.4",
     "got-scraping": "^3.2.4-beta.0",
-    "isparta": "^4.1.1",
-    "mocha": "^10.0.0",
-    "nyc": "^15.1.0",
     "portastic": "^1.0.1",
     "proxy": "^1.0.2",
     "puppeteer": "^25.1.0",
     "request": "^2.88.2",
     "rimraf": "^4.1.2",
-    "sinon": "^13.0.2",
-    "sinon-stub-promise": "^4.0.0",
     "socksv5": "^0.0.6",
-    "through": "^2.3.8",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.20.0",
     "underscore": "^1.13.1",
+    "vitest": "^4.1.11",
     "ws": "^8.2.2"
   },
-  "nyc": {
-    "reporter": [
-      "text",
-      "html",
-      "lcov"
-    ],
-    "exclude": [
-      "**/test/**"
-    ]
-  },
   "dependencies": {
     "socks": "^2.8.3",
     "socks-proxy-agent": "^8.0.3",
@@ -100,13 +84,22 @@
     "build": "tsc",
     "clean": "rimraf dist",
     "local-proxy": "tsx test/utils/run_locally.js",
-    "test": "nyc cross-env NODE_OPTIONS=--insecure-http-parser mocha 'test/unit/**/*.js' 'test/e2e/**/*.js'",
-    "test:unit": "mocha 'test/unit/**/*.js'",
-    "test:e2e": "nyc cross-env NODE_OPTIONS=--insecure-http-parser mocha 'test/e2e/**/*.js'",
-    "test:bun": "bun --bun run mocha --no-config --exit 'test/unit/**/*.js'",
-    "test:bun:e2e:compatible": "bun --bun run mocha --no-config --exit --grep 'throws error' test/e2e/tcp_tunnel.js",
-    "test:bun:e2e:full": "bun --bun run mocha --no-config --exit 'test/e2e/**/*.js'",
-    "test:docker": "docker build --tag proxy-chain-tests --file test/Dockerfile . && docker run --add-host localhost-test:127.0.0.1 proxy-chain-tests",
+    "test": "vitest run --coverage",
+    "test:unit": "vitest run --project unit",
+    "test:e2e": "vitest run --project e2e --coverage",
+    "test:bun": "bun --bun run vitest run --project unit",
+    "test:bun:e2e:full": "cross-env NODE_OPTIONS=--insecure-http-parser bun --bun run vitest run --project e2e",
+    "test:bun:e2e:compatible": "pnpm run test:bun:e2e:full test/e2e/tcp_tunnel.js -t 'throws error'",
+    "test:bun:all": "pnpm run test:bun && pnpm run test:bun:e2e:full",
+    "test:bun:supported": "pnpm run test:bun && pnpm run test:bun:e2e:compatible",
+    "docker:build": "docker build --tag proxy-chain-tests --file test/Dockerfile .",
+    "docker:run": "docker run --rm --add-host localhost-test:127.0.0.1 proxy-chain-tests",
+    "test:docker": "pnpm run docker:build && pnpm run docker:run -- test",
+    "test:docker:bun": "pnpm run docker:build && pnpm run docker:run -- test:bun:supported",
+    "test:docker:bun:unit": "pnpm run docker:build && pnpm run docker:run -- test:bun",
+    "test:docker:bun:e2e:compatible": "pnpm run docker:build && pnpm run docker:run -- test:bun:e2e:compatible",
+    "test:docker:bun:e2e:full": "pnpm run docker:build && pnpm run docker:run -- test:bun:e2e:full",
+    "test:docker:bun:full": "pnpm run docker:build && pnpm run docker:run -- test:bun:all",
     "test:docker:all": "bash scripts/test-docker-all.sh",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"