https-proxy-agent 5.0.1

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/https-proxy-agent@5.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/https-proxy-agent@5.0.1

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:e9ceb5a25090592e054d5273086aa7825c5746c0a411a234ee055b28ee401ac7","contract":["createProxyAgent instantiates an HttpsProxyAgent from a string URL with parsed host, port, and protocol","supports proxy options object configuration with custom headers","automatically resolves default port 80 for HTTP and 443 for HTTPS proxy URLs when port is omitted","detects HTTPS proxy scheme or secureProxy option to enable secureProxy mode with ALPNProtocols http 1.1","normalizes authentication credentials from proxy options and formats Proxy-Authorization header","strips path and pathname from parsed proxy configuration when host is specified","getProxyConfig extracts normalized proxy configuration from the agent instance","implements callback method establishing CONNECT tunnel to HTTP proxy","handles non-200 proxy response status by returning a buffered socket that replays error data","throws an error when proxy configuration is missing or invalid"],"goal":"verify pkg:npm/https-proxy-agent@5.0.1","kind":"HOW","packages":["pkg:npm/https-proxy-agent@5.0.1"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/https-proxy-agent@5.0.1"],"schemaVersion":1,"subject":"pkg:npm/https-proxy-agent@5.0.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-https-proxy-agent",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-https-proxy-agent",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "https-proxy-agent": "5.0.1"
      }
    },
    "node_modules/agent-base": {
      "version": "6.0.2",
      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",
      "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==",
      "license": "MIT",
      "dependencies": {
        "debug": "4"
      },
      "engines": {
        "node": ">= 6.0.0"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/https-proxy-agent": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
      "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==",
      "license": "MIT",
      "dependencies": {
        "agent-base": "6",
        "debug": "4"
      },
      "engines": {
        "node": ">= 6"
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-https-proxy-agent",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "https-proxy-agent": "5.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/https-proxy-agent@5.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/https-proxy-agent@5.0.1"
  ]
}

import HttpsProxyAgent from 'https-proxy-agent';

/**
 * Creates an HttpsProxyAgent instance from a URL or options object.
 * @param {string | object} opts - Proxy URL string or options object.
 * @returns {HttpsProxyAgent}
 */
export function createProxyAgent(opts) {
  return new HttpsProxyAgent(opts);
}

/**
 * Extracts and returns normalized proxy configuration from the agent instance.
 * @param {HttpsProxyAgent} agent - The HttpsProxyAgent instance.
 * @returns {object} Normalized proxy configuration object.
 */
export function getProxyConfig(agent) {
  return {
    host: agent.proxy.host,
    port: agent.proxy.port,
    protocol: agent.proxy.protocol,
    secureProxy: agent.secureProxy,
    auth: agent.proxy.auth,
    headers: agent.proxy.headers,
  };
}

export { HttpsProxyAgent };
export default HttpsProxyAgent;

import assert from 'node:assert/strict';
import http from 'node:http';
import net from 'node:net';
import HttpsProxyAgent from 'https-proxy-agent';
import { createProxyAgent, getProxyConfig } from '../src/index.mjs';

// 1. createProxyAgent instantiates an HttpsProxyAgent from a string URL with parsed host, port, and protocol
{
  const agent = createProxyAgent('http://proxy.example.com:8080');
  assert(agent instanceof HttpsProxyAgent);
  assert.equal(agent.proxy.hostname, 'proxy.example.com');
  assert.equal(agent.proxy.port, 8080);
  assert.equal(agent.proxy.protocol, 'http:');
  assert.equal(agent.secureProxy, false);
}

// 2. supports proxy options object configuration with custom headers
{
  const agent = new HttpsProxyAgent({
    host: 'proxy.example.com',
    port: 3128,
    headers: {
      'User-Agent': 'CustomTestAgent/1.0',
      'X-Proxy-Custom': 'val-123'
    }
  });
  assert.equal(agent.proxy.host, 'proxy.example.com');
  assert.equal(agent.proxy.port, 3128);
  assert.equal(agent.proxy.headers['User-Agent'], 'CustomTestAgent/1.0');
  assert.equal(agent.proxy.headers['X-Proxy-Custom'], 'val-123');
}

// 3. automatically resolves default port 80 for HTTP and 443 for HTTPS proxy URLs when port is omitted
{
  const httpAgent = new HttpsProxyAgent('http://proxy.example.com');
  assert.equal(httpAgent.proxy.port, 80);

  const httpsAgent = new HttpsProxyAgent('https://secure-proxy.example.com');
  assert.equal(httpsAgent.proxy.port, 443);
}

// 4. detects HTTPS proxy scheme or secureProxy option to enable secureProxy mode with ALPNProtocols http 1.1
{
  const agentUrl = new HttpsProxyAgent('https://secure-proxy.example.com:8443');
  assert.equal(agentUrl.secureProxy, true);
  assert.deepEqual(agentUrl.proxy.ALPNProtocols, ['http 1.1']);

  const agentOpt = new HttpsProxyAgent({
    host: 'proxy.example.com',
    port: 443,
    secureProxy: true
  });
  assert.equal(agentOpt.secureProxy, true);
  assert.deepEqual(agentOpt.proxy.ALPNProtocols, ['http 1.1']);
}

// 5. normalizes authentication credentials from proxy options and formats Proxy-Authorization header
{
  const authAgent = new HttpsProxyAgent({
    host: 'proxy.example.com',
    port: 8080,
    auth: 'alice:wonderland'
  });
  assert.equal(authAgent.proxy.auth, 'alice:wonderland');
}

// 6. strips path and pathname from parsed proxy configuration when host is specified
{
  const agent = new HttpsProxyAgent('http://proxy.example.com:8080/some/path?query=1');
  assert.equal(agent.proxy.path, undefined);
  assert.equal(agent.proxy.pathname, undefined);
  assert.equal(agent.proxy.hostname, 'proxy.example.com');
}

// 7. getProxyConfig extracts normalized proxy configuration from the agent instance
{
  const agent = createProxyAgent({
    host: 'proxy.example.com',
    port: 8080,
    auth: 'alice:wonderland',
    headers: { 'X-Custom': 'yes' }
  });
  const config = getProxyConfig(agent);
  assert.equal(config.host, 'proxy.example.com');
  assert.equal(config.port, 8080);
  assert.equal(config.auth, 'alice:wonderland');
  assert.deepEqual(config.headers, { 'X-Custom': 'yes' });
}

// 8. implements callback method establishing CONNECT tunnel to HTTP proxy
{
  let clientSock = null;

  const server = http.createServer();
  server.on('connect', (req, socket, head) => {
    clientSock = socket;
    socket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
  });

  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
  const { port } = server.address();

  const agent = new HttpsProxyAgent(`http://127.0.0.1:${port}`);
  const req = new http.ClientRequest({
    host: 'target.example.com',
    port: 443,
    method: 'GET'
  });
  req.on('error', () => {});

  const socket = await agent.callback(req, {
    host: 'target.example.com',
    port: 443,
    secureEndpoint: false
  });

  assert(socket instanceof net.Socket);

  socket.destroy();
  if (clientSock) clientSock.destroy();
  if (server.closeAllConnections) server.closeAllConnections();
  await new Promise(resolve => server.close(resolve));
  req.destroy();
}

// 9. handles non-200 proxy response status by returning a buffered socket that replays error data
{
  let clientSock = null;

  const server = http.createServer();
  server.on('connect', (req, socket, head) => {
    clientSock = socket;
    socket.write('HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: Basic\r\n\r\n');
  });

  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
  const { port } = server.address();

  const agent = new HttpsProxyAgent(`http://127.0.0.1:${port}`);
  const req = new http.ClientRequest({
    host: 'target.example.com',
    port: 443,
    method: 'GET'
  });
  req.on('error', () => {});

  const socket = await agent.callback(req, {
    host: 'target.example.com',
    port: 443,
    secureEndpoint: false
  });

  assert(socket instanceof net.Socket);
  assert.equal(socket.writable, false);

  socket.destroy();
  if (clientSock) clientSock.destroy();
  if (server.closeAllConnections) server.closeAllConnections();
  await new Promise(resolve => server.close(resolve));
  req.destroy();
}

// 10. throws an error when proxy configuration is missing or invalid
{
  assert.throws(() => new HttpsProxyAgent(), {
    message: /an HTTP\(S\) proxy server `host` and `port` must be specified!/
  });
  assert.throws(() => new HttpsProxyAgent(null), {
    message: /an HTTP\(S\) proxy server `host` and `port` must be specified!/
  });
}

console.log('Contract tests passed successfully.');