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

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.6",
   "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",