HTTPS Proxy Agent

A lightweight and production-oriented HTTPS proxy agent for Node.js.

@xof/https-proxy-agent creates secure tunnels through HTTP and HTTPS proxy servers using the standard HTTP CONNECT method. It is designed for reliable proxy routing while maintaining compatibility with the native Node.js http.Agent interface.

Features

• HTTP proxy support
• HTTPS proxy support
• HTTPS destination support
• HTTP CONNECT tunneling
• Proxy authentication
• Custom proxy headers
• Dynamic proxy headers
• TLS configuration
• Custom CA certificates
• Client certificates
• SNI support
• ALPN support
• IPv4 and IPv6 support
• Proxy connection events
• Keep-alive support
• Native Node.js Agent compatibility
• Zero runtime dependencies
• Node.js 18+ support

Requirements

• Node.js >=18

Installation

npm install @xof/https-proxy-agent

Basic Usage

'use strict';

const https = require('https');
const HttpsProxyAgent = require('@xof/https-proxy-agent');

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080'
);

https.get('https://example.com', {
	agent
}, response => {
	response.pipe(process.stdout);
});

Proxy URL

The constructor accepts a proxy URL as either a string or a URL object.

String

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080'
);

URL

const proxy = new URL(
	'http://127.0.0.1:8080'
);

const agent = new HttpsProxyAgent(proxy);

HTTP Proxy

An HTTP proxy can be used to create a secure tunnel to an HTTPS destination.

const agent = new HttpsProxyAgent(
	'http://proxy.example.com:8080'
);

Connection flow:

Node.js
   │
   │ CONNECT
   ▼
HTTP Proxy
   │
   │ Tunnel
   ▼
HTTPS Server

HTTPS Proxy

HTTPS proxies are supported as well.

const agent = new HttpsProxyAgent(
	'https://proxy.example.com:8443'
);

The connection to the proxy is established over TLS before the CONNECT request is sent.

Connection flow:

Node.js
   │
   │ TLS
   ▼
HTTPS Proxy
   │
   │ CONNECT
   ▼
HTTPS Server

Proxy Authentication

Credentials can be included directly in the proxy URL.

const agent = new HttpsProxyAgent(
	'http://username:[email protected]:8080'
);

The agent automatically generates the Proxy-Authorization header.

URL-encoded Credentials

Credentials containing reserved URL characters should be encoded.

const username = encodeURIComponent('[email protected]');
const password = encodeURIComponent('p@ss:word');

const agent = new HttpsProxyAgent(
	`http://${username}:${password}@127.0.0.1:8080`
);

Proxy Headers

Custom headers can be supplied through the headers option.

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		headers: {
			'X-Proxy-Client': 'XOF',
			'X-Request-ID': 'example'
		}
	}
);

These headers are sent with the proxy CONNECT request.

Dynamic Proxy Headers

Headers can also be generated dynamically.

const crypto = require('crypto');

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		headers: () => ({
			'X-Request-ID': crypto.randomUUID()
		})
	}
);

The function is evaluated when a proxy connection is created.

TLS Configuration

TLS options can be passed through the agent configuration.

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		rejectUnauthorized: true
	}
);

Custom CA

const fs = require('fs');

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		ca: fs.readFileSync('./ca.pem')
	}
);

Client Certificate

const fs = require('fs');

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		cert: fs.readFileSync('./client.crt'),
		key: fs.readFileSync('./client.key')
	}
);

Server Name Indication

The destination hostname is automatically used for TLS SNI when appropriate.

A custom server name can also be specified:

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		servername: 'example.com'
	}
);

IPv6

IPv6 proxy addresses are supported.

const agent = new HttpsProxyAgent(
	'http://[::1]:8080'
);

IPv6 destination hosts are correctly formatted for CONNECT requests.

Proxy Connection Events

proxyConnect

The proxyConnect event is emitted after the proxy responds to the CONNECT request.

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080'
);

agent.on('proxyConnect', response => {
	console.log('Status:', response.statusCode);
	console.log('Message:', response.statusMessage);
	console.log('Headers:', response.headers);
});

A successful connection normally returns:

200 Connection Established

CONNECT Tunneling

The agent uses the standard HTTP CONNECT method.

For an HTTPS destination such as:

https://example.com:443

the proxy receives a request similar to:

CONNECT example.com:443 HTTP/1.1
Host: example.com:443
Proxy-Connection: Keep-Alive

After a successful 200 response, the connection becomes a tunnel and TLS communication with the destination occurs through that tunnel.

Connection Flow

Application
     │
     ▼
HTTPS Proxy Agent
     │
     ├── Parse proxy URL
     │
     ├── Connect to proxy
     │
     ├── Establish TLS
     │      └── HTTPS proxy only
     │
     ├── Send CONNECT request
     │
     ├── Receive proxy response
     │
     ├── Validate response
     │
     ├── Establish destination TLS
     │
     ▼
HTTPS Destination

Proxy Response

The proxy response contains:

• HTTP status code
• HTTP status message
• Response headers

Example:

agent.on('proxyConnect', response => {
	console.log(response.statusCode);
	console.log(response.statusMessage);
	console.log(response.headers);
});

Proxy Errors

A response other than 200 does not establish a tunnel.

Common proxy responses include:

400 Bad Request
403 Forbidden
404 Not Found
407 Proxy Authentication Required
502 Bad Gateway
503 Service Unavailable

The connection is only promoted to a destination tunnel after a successful CONNECT response.

Proxy Authentication Retry

An authentication callback can be used when proxy authentication is required.

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		onProxyAuth: async ({ response, scheme }) => {
			console.log(
				'Authentication scheme:',
				scheme
			);

			return {
				headers: {
					'Proxy-Authorization':
						'Basic ' +
						Buffer
							.from('username:password')
							.toString('base64')
				}
			};
		}
	}
);

Keep-Alive

The agent supports Node.js keep-alive configuration.

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		keepAlive: true
	}
);

Connection reuse can reduce the overhead of repeatedly establishing proxy connections.

Actual reuse depends on the Node.js Agent configuration and proxy behavior.

Using With http.request()

const http = require('http');
const HttpsProxyAgent = require('@xof/https-proxy-agent');

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080'
);

const request = http.request({
	hostname: 'example.com',
	port: 80,
	path: '/',
	method: 'GET',
	agent
});

request.on('response', response => {
	response.pipe(process.stdout);
});

request.on('error', error => {
	console.error(error);
});

request.end();

Using With https.request()

const https = require('https');
const HttpsProxyAgent = require('@xof/https-proxy-agent');

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080'
);

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

request.on('response', response => {
	response.pipe(process.stdout);
});

request.on('error', error => {
	console.error(error);
});

request.end();

Constructor

new HttpsProxyAgent(proxy, options);

proxy

Type:

string | URL

Supported proxy protocols:

http:
https:

options

Type:

object

Common options:

| Option | Type | Description | |---|---|---| | headers | object \| function | Headers sent with the CONNECT request | | keepAlive | boolean | Enables keep-alive behavior | | ca | string \| Buffer \| Array | Custom CA certificate | | cert | string \| Buffer | Client certificate | | key | string \| Buffer | Client private key | | servername | string | TLS SNI hostname | | rejectUnauthorized | boolean | TLS certificate verification | | timeout | number | Socket timeout |

Additional compatible Node.js Agent and TLS options may also be supplied.

Exports

The package can be imported directly:

const HttpsProxyAgent = require(
	'@xof/https-proxy-agent'
);

A named export is also available:

const {
	HttpsProxyAgent
} = require(
	'@xof/https-proxy-agent'
);

Both references point to the same constructor.

Performance

@xof/https-proxy-agent is designed to keep the proxy layer lightweight and minimize unnecessary processing.

The implementation uses Node.js native networking primitives without adding another HTTP client abstraction.

Performance is primarily affected by:

• Proxy latency
• Destination latency
• TLS handshake overhead
• Proxy server performance
• Network bandwidth
• Connection reuse
• Keep-alive configuration
• DNS resolution
• Network congestion

Connection Reuse

Using keepAlive: true can improve performance for applications that make multiple requests through the same proxy.

const agent = new HttpsProxyAgent(
	'http://127.0.0.1:8080',
	{
		keepAlive: true
	}
);

Reusing an established connection can avoid repeatedly paying the TCP and TLS connection setup cost.

Memory Usage

The agent does not buffer destination response bodies.

Response data remains handled by the underlying Node.js streams.

This makes the agent suitable for:

• API requests
• Large downloads
• Streaming responses
• Long-lived connections

Actual memory usage depends on the request implementation and how the application handles response streams.

Network Overhead

The proxy layer adds the required CONNECT handshake before the destination tunnel is established.

For HTTP proxies, this introduces an additional proxy negotiation step.

For HTTPS proxies, TLS negotiation with the proxy adds additional cryptographic overhead.

Once the tunnel is established, application traffic flows through the proxy connection normally.

Error Handling

Always attach an error listener to requests using the agent.

const request = https.get(
	'https://example.com',
	{ agent },
	response => {
		response.pipe(process.stdout);
	}
);

request.on('error', error => {
	console.error(
		'Request failed:',
		error.message
	);
});

Possible errors include:

• Proxy connection failures
• DNS resolution failures
• Socket errors
• TLS errors
• Invalid proxy responses
• Proxy authentication failures
• Connection timeouts
• Destination connection failures

Security

Proxy credentials are sensitive information.

Avoid hardcoding credentials directly into application source code.

Use environment variables where appropriate:

const proxy = new URL(
	process.env.HTTPS_PROXY
);

const agent = new HttpsProxyAgent(proxy);

Do not log complete proxy URLs when they contain credentials.

TLS certificate verification should remain enabled unless there is a specific reason to disable it.

Browser Support

@xof/https-proxy-agent is designed for Node.js.

It relies on Node.js networking APIs and is not intended for browser environments.

Runtime Dependencies

The package does not require third-party runtime dependencies.

It uses Node.js built-in modules such as:

http
https
net
tls
url
events

License

MIT License.

See LICENSE for the complete license text.

Repository

The source code and project development files are maintained in the official repository.

Changelog

See CHANGELOG.md for release history.

@xof/https-proxy-agent — Secure proxy tunneling for Node.js.