{"id":17337,"library":"proxying-agent","title":"Node HTTP/HTTPS Forward Proxy Agent","description":"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.","status":"abandoned","version":"2.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/capriza/node-proxying-agent","tags":["javascript","http","https","agent","proxy","tunnel","ntlm"],"install":[{"cmd":"npm install proxying-agent","lang":"bash","label":"npm"},{"cmd":"yarn add proxying-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add proxying-agent","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import proxyingAgent from 'proxying-agent';","symbol":"module object","correct":"const proxyingAgent = require('proxying-agent');"},{"note":"The 'create' method is a named property of the CommonJS module's default export.","wrong":"import { create } from 'proxying-agent';","symbol":"create","correct":"const { create } = require('proxying-agent');"},{"note":"The 'globalize' method is a named property of the CommonJS module's default export, used to set a global proxy agent.","wrong":"import { globalize } from 'proxying-agent';","symbol":"globalize","correct":"const { globalize } = require('proxying-agent');"}],"quickstart":{"code":"const http = require('http');\nconst https = require('https');\n\nconst proxyOptions = {\n  proxy: 'http://username:password@proxy.example.com:8080',\n  authType: 'ntlm',\n  ntlm: {\n    domain: 'MYDOMAIN',\n    workstation: process.env.WORKSTATION_NAME ?? 'my-machine' // Optional, for NTLM\n  }\n};\n\nconst proxyingAgent = require('proxying-agent').create(proxyOptions, 'https://target.example.com');\n\nconst req = https.request({\n  host: 'target.example.com',\n  port: 443,\n  method: 'GET',\n  path: '/',\n  agent: proxyingAgent\n});\n\nreq.on('socket', (socket) => {\n  // For NTLM, delay sending request data until the socket is assigned to prevent premature closure.\n  // For other auth types, you might send data immediately after req creation.\n  console.log('Socket assigned, sending request data...');\n  req.end('Hello from client!'); // No data for GET, but demonstrates the pattern\n});\n\nreq.on('response', (res) => {\n  console.log(`STATUS: ${res.statusCode}`);\n  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);\n  res.setEncoding('utf8');\n  res.on('data', (chunk) => {\n    console.log(`BODY: ${chunk}`);\n  });\n  res.on('end', () => {\n    console.log('No more data in response.');\n  });\n});\n\nreq.on('error', (e) => {\n  console.error(`problem with request: ${e.message}`);\n});\n\n// If not using NTLM or delaying data, you would call req.end() directly here.\n// req.end(); // For non-NTLM or immediate data send\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.4.0"},{"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(); });`","message":"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.","severity":"gotcha","affected_versions":">=0.8.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.8.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=0.8.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use CommonJS `require` syntax: `const proxyingAgent = require('proxying-agent');` or `const { create } = require('proxying-agent');`.","cause":"Attempting to use ES module `import` syntax (`import proxyingAgent from 'proxying-agent';`) for a CommonJS-only package, or incorrectly destructuring named exports.","error":"TypeError: require(...) is not a function"},{"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.","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.","error":"Error: tunneling socket could not be established, statusCode=407"},{"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.","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.","error":"Error: CERT_HAS_EXPIRED"},{"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.","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.","error":"TypeError: The agent.addRequest method is not supported for custom agents. Please use the agent option on http.request and https.request directly."}],"ecosystem":"npm","meta_description":null}