Node HTTP/HTTPS Forward Proxy Agent

2.4.0 · abandoned · verified Wed Apr 22

proxying-agent is a Node.js library providing an HTTP/HTTPS forward proxy agent. It is built upon Node's native `http.Agent` and offers features for transparently routing HTTP and HTTPS requests through a specified proxy server. Key capabilities include support for SSL tunneling via the HTTP CONNECT method, Basic authentication, and a beta implementation of NTLM authentication, allowing for domain-specific username formats (e.g., `domain\username`). The library also provides a `globalize` method to easily configure all subsequent `http` and `https` requests to use a designated proxy. The current stable version is 2.4.0, released in July 2017. Due to its age, it is considered abandoned, with no active development or maintenance since its last update. This lack of recent activity suggests potential incompatibilities with newer Node.js versions and a risk of unaddressed security vulnerabilities, making it crucial for users to assess its suitability for modern applications.

Common errors

```
TypeError: require(...) is not a function
```
cause Attempting to use ES module `import` syntax (`import proxyingAgent from 'proxying-agent';`) for a CommonJS-only package, or incorrectly destructuring named exports.

fix Use CommonJS `require` syntax: `const proxyingAgent = require('proxying-agent');` or `const { create } = require('proxying-agent');`.
```
Error: tunneling socket could not be established, statusCode=407
```
cause The proxy server rejected the CONNECT request due to authentication failure (HTTP 407 Proxy Authentication Required). This often indicates incorrect proxy credentials or an unsupported authentication type.

fix Double-check the username and password in the proxy URL (`http://username:password@proxy.example.com`). Ensure the `authType` option (`basic` or `ntlm`) matches the proxy server's requirements. For NTLM, verify `domain` and `workstation` settings.
```
Error: CERT_HAS_EXPIRED
```
cause When proxying HTTPS requests, the SSL certificate presented by the target server or the proxy itself (if it's doing SSL termination/inspection) has expired or is untrusted by Node.js's default CA store. This is a common issue with older or misconfigured certificates.

fix Inspect the certificates involved. You might need to provide custom `tlsOptions` (e.g., `ca`, `cert`, `key`) to the `create` method, or temporarily set `rejectUnauthorized: false` for testing (NOT recommended for production). Ensure your system's root CAs are up to date.
```
TypeError: The agent.addRequest method is not supported for custom agents. Please use the agent option on http.request and https.request directly.
```
cause This error occurs in newer Node.js versions (e.g., Node.js 14+) if an older custom agent tries to use the `agent.addRequest` method, which was removed from the public API. `proxying-agent` might internally use this deprecated method if it's not adapted for newer Node.js versions.

fix This package is abandoned and unlikely to be compatible with modern Node.js versions. Migrate to an actively maintained proxy agent library that supports current Node.js APIs.

Warnings

breaking The 'proxying-agent' package is effectively abandoned, with its last release (v2.4.0) in July 2017. It is highly unlikely to be compatible with modern Node.js versions (e.g., Node.js 14+), which have introduced significant changes to core HTTP/HTTPS modules and security best practices. Using an unmaintained library carries substantial risks, including unpatched security vulnerabilities and potential runtime errors due to API incompatibilities.
Fix: Consider migrating to a actively maintained proxy agent library (e.g., `https-proxy-agent`, `socks-proxy-agent`) or implementing custom proxy logic using newer Node.js APIs.
gotcha When using NTLM authentication, it is critical to delay sending any request data (e.g., via `req.write` or `req.end`) until the `socket` event is emitted on the `http.ClientRequest` object. Failing to do so will prematurely close the socket, preventing the NTLM handshake from completing successfully.
Fix: Attach an event listener for the 'socket' event to your `http.ClientRequest` object and perform `req.write()` or `req.end()` within that listener: `req.on('socket', (socket) => { req.end(); });`
gotcha The `globalize` method modifies Node.js's global `http.Agent` and `https.Agent`. It must be called *before* any `http.request` or `https.request` calls are made to ensure all subsequent requests use the configured proxy. If requests are initiated before `globalize` is invoked, they will bypass the proxy.
Fix: Ensure `require('proxying-agent').globalize(options);` is one of the very first lines of your application's entry point, or at least before any HTTP/HTTPS requests are created.
deprecated The NTLM implementation is marked as 'beta' in the README and has not seen updates since 2017. Given the complexity of NTLM, this 'beta' status combined with the package's abandonment means the NTLM feature might be unstable, incomplete, or contain security flaws.
Fix: Thoroughly test NTLM functionality in your environment and consider the security implications of using an unmaintained beta feature. If NTLM is critical, seek alternatives or custom implementations.

Install

npm install proxying-agent npm
yarn add proxying-agent yarn
pnpm add proxying-agent pnpm

Imports

module object
wrong:
```
import proxyingAgent from 'proxying-agent';
```
correct:
```
const proxyingAgent = require('proxying-agent');
```
This package exports a CommonJS module. For ESM projects, consider using a dynamic import or a CJS interop wrapper. The module object contains 'create' and 'globalize' methods.
create
wrong:
```
import { create } from 'proxying-agent';
```
correct:
```
const { create } = require('proxying-agent');
```
The 'create' method is a named property of the CommonJS module's default export.
globalize
wrong:
```
import { globalize } from 'proxying-agent';
```
correct:
```
const { globalize } = require('proxying-agent');
```
The 'globalize' method is a named property of the CommonJS module's default export, used to set a global proxy agent.

Quickstart

This example demonstrates how to create and use `proxying-agent` with NTLM authentication for an HTTPS request, including the crucial `req.on('socket')` pattern for NTLM.

const http = require('http');
const https = require('https');

const proxyOptions = {
  proxy: 'http://username:password@proxy.example.com:8080',
  authType: 'ntlm',
  ntlm: {
    domain: 'MYDOMAIN',
    workstation: process.env.WORKSTATION_NAME ?? 'my-machine' // Optional, for NTLM
  }
};

const proxyingAgent = require('proxying-agent').create(proxyOptions, 'https://target.example.com');

const req = https.request({
  host: 'target.example.com',
  port: 443,
  method: 'GET',
  path: '/',
  agent: proxyingAgent
});

req.on('socket', (socket) => {
  // For NTLM, delay sending request data until the socket is assigned to prevent premature closure.
  // For other auth types, you might send data immediately after req creation.
  console.log('Socket assigned, sending request data...');
  req.end('Hello from client!'); // No data for GET, but demonstrates the pattern
});

req.on('response', (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
});

// If not using NTLM or delaying data, you would call req.end() directly here.
// req.end(); // For non-NTLM or immediate data send

view raw JSON →