socks-proxy-agent 8.0.5

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/socks-proxy-agent@8.0.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/socks-proxy-agent@8.0.5

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:9415c77c410ea54c3a4a8b2338e991b5076449a95195ce8e9cdfaabb26ddb684","contract":["SocksProxyAgent is exported as a constructor class","createSocksProxyAgent instantiates SocksProxyAgent from a socks5 URL string with default port 1080","supports socks5h protocol without client-side DNS lookup","supports socks4 protocol with client-side DNS lookup and socks4a without client-side DNS lookup","supports WHATWG URL instance input and optional timeout and socketOptions configuration","getSocksProxyDetails extracts normalized proxy details and configuration","throws TypeError when URL protocol is unsupported","implements connect method for establishing proxy connections"],"goal":"verify pkg:npm/socks-proxy-agent@8.0.5","kind":"HOW","packages":["pkg:npm/socks-proxy-agent@8.0.5"],"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/socks-proxy-agent@8.0.5"],"schemaVersion":1,"subject":"pkg:npm/socks-proxy-agent@8.0.5","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-socks-proxy-agent",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-socks-proxy-agent",
      "version": "1.0.0",
      "dependencies": {
        "socks-proxy-agent": "8.0.5"
      }
    },
    "node_modules/agent-base": {
      "version": "7.1.4",
      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
      "license": "MIT",
      "engines": {
        "node": ">= 14"
      }
    },
    "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/ip-address": {
      "version": "10.5.0",
      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.5.0.tgz",
      "integrity": "sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g==",
      "license": "MIT",
      "engines": {
        "node": ">= 12"
      }
    },
    "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"
    },
    "node_modules/smart-buffer": {
      "version": "4.2.0",
      "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
      "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
      "license": "MIT",
      "engines": {
        "node": ">= 6.0.0",
        "npm": ">= 3.0.0"
      }
    },
    "node_modules/socks": {
      "version": "2.8.9",
      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.9.tgz",
      "integrity": "sha512-LJhUYUvItdQ0LkJTmPeaEObWXAqFyfmP85x0tch/ez9cahmhlBBLbIqDFnvBnUJGagb0JbIQrkBs1wJ+yRYpEw==",
      "license": "MIT",
      "dependencies": {
        "ip-address": "^10.1.1",
        "smart-buffer": "^4.2.0"
      },
      "engines": {
        "node": ">= 10.0.0",
        "npm": ">= 3.0.0"
      }
    },
    "node_modules/socks-proxy-agent": {
      "version": "8.0.5",
      "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-8.0.5.tgz",
      "integrity": "sha512-HehCEsotFqbPW9sJ8WVYB6UbmIMv7kUUORIF2Nncq4VQvBfNBLibW9YZR5dlYCSUhwcD628pRllm7n+E+YTzJw==",
      "license": "MIT",
      "dependencies": {
        "agent-base": "^7.1.2",
        "debug": "^4.3.4",
        "socks": "^2.8.3"
      },
      "engines": {
        "node": ">= 14"
      }
    }
  }
}

{
  "name": "sample-socks-proxy-agent",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of socks-proxy-agent",
  "main": "src/index.js",
  "dependencies": {
    "socks-proxy-agent": "8.0.5"
  }
}

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

const { SocksProxyAgent } = require('socks-proxy-agent');

/**
 * Creates a SocksProxyAgent instance from a URL string or URL object and optional settings.
 *
 * @param {string | URL} proxy - SOCKS proxy URL string or WHATWG URL instance
 * @param {object} [options] - Additional agent and proxy options
 * @returns {SocksProxyAgent} Configured SocksProxyAgent instance
 */
function createSocksProxyAgent(proxy, options) {
  return new SocksProxyAgent(proxy, options);
}

/**
 * Extracts and normalizes SOCKS proxy configuration details from a SocksProxyAgent instance.
 *
 * @param {SocksProxyAgent} agent - The SocksProxyAgent instance
 * @returns {object} Normalized proxy configuration details
 */
function getSocksProxyDetails(agent) {
  if (!agent || !agent.proxy) {
    throw new TypeError('Expected a SocksProxyAgent instance with a valid proxy property');
  }

  const { host, port, type } = agent.proxy;

  return {
    host,
    port,
    type,
    shouldLookup: Boolean(agent.shouldLookup),
    timeout: agent.timeout ?? null,
    protocols: SocksProxyAgent.protocols
  };
}

module.exports = {
  createSocksProxyAgent,
  getSocksProxyDetails,
  SocksProxyAgent
};

import assert from 'node:assert';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { createSocksProxyAgent, getSocksProxyDetails, SocksProxyAgent } = require('../src/index.js');

// 1. Export verification
assert.strictEqual(typeof SocksProxyAgent, 'function', 'SocksProxyAgent should be exported as a constructor function');
assert.strictEqual(typeof createSocksProxyAgent, 'function', 'createSocksProxyAgent should be exported as a function');
assert.strictEqual(typeof getSocksProxyDetails, 'function', 'getSocksProxyDetails should be exported as a function');
assert.deepStrictEqual(SocksProxyAgent.protocols, ['socks', 'socks4', 'socks4a', 'socks5', 'socks5h'], 'SocksProxyAgent.protocols should list supported protocols');

// 2. createSocksProxyAgent instantiates SocksProxyAgent from a socks5 URL string with default port 1080
const agentDefault5 = createSocksProxyAgent('socks5://127.0.0.1');
assert(agentDefault5 instanceof SocksProxyAgent, 'agentDefault5 should be an instance of SocksProxyAgent');
assert.strictEqual(agentDefault5.proxy.host, '127.0.0.1');
assert.strictEqual(agentDefault5.proxy.port, 1080);
assert.strictEqual(agentDefault5.proxy.type, 5);
assert.strictEqual(agentDefault5.shouldLookup, true, 'socks5 protocol performs client-side DNS lookup');

// 3. supports socks5h protocol without client-side DNS lookup
const agent5h = createSocksProxyAgent('socks5h://127.0.0.1:9050');
assert.strictEqual(agent5h.proxy.host, '127.0.0.1');
assert.strictEqual(agent5h.proxy.port, 9050);
assert.strictEqual(agent5h.proxy.type, 5);
assert.strictEqual(agent5h.shouldLookup, false, 'socks5h delegates DNS resolution to the proxy');

// 4. supports socks4 protocol with client-side DNS lookup and socks4a without client-side DNS lookup
const agent4 = createSocksProxyAgent('socks4://127.0.0.1:1080');
assert.strictEqual(agent4.proxy.type, 4);
assert.strictEqual(agent4.shouldLookup, true);

const agent4a = createSocksProxyAgent('socks4a://127.0.0.1:1080');
assert.strictEqual(agent4a.proxy.type, 4);
assert.strictEqual(agent4a.shouldLookup, false);

// 5. supports WHATWG URL instance input and optional timeout and socketOptions configuration
const proxyUrl = new URL('socks5://127.0.0.1:1088');
const agentWithOpts = createSocksProxyAgent(proxyUrl, {
  timeout: 5000,
  socketOptions: {
    keepAlive: true
  }
});
assert.strictEqual(agentWithOpts.proxy.host, '127.0.0.1');
assert.strictEqual(agentWithOpts.proxy.port, 1088);
assert.strictEqual(agentWithOpts.timeout, 5000);
assert.deepStrictEqual(agentWithOpts.socketOptions, { keepAlive: true });

// 6. getSocksProxyDetails extracts normalized proxy details and configuration
const details = getSocksProxyDetails(agentWithOpts);
assert.deepStrictEqual(details, {
  host: '127.0.0.1',
  port: 1088,
  type: 5,
  shouldLookup: true,
  timeout: 5000,
  protocols: ['socks', 'socks4', 'socks4a', 'socks5', 'socks5h']
});

// 7. throws TypeError when URL protocol is unsupported
assert.throws(
  () => createSocksProxyAgent('http://127.0.0.1:8080'),
  {
    name: 'TypeError',
    message: 'A "socks" protocol must be specified! Got: http:'
  }
);

// 8. implements connect method for establishing proxy connections
assert.strictEqual(typeof agentDefault5.connect, 'function', 'agent.connect should be a function');

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