socks 2.8.10: SocksClient.createConnectionChain

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@2.8.10
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/socks@2.8.10
Demonstrate these symbols/APIs:
  - SocksClient.createConnectionChain

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:c21dd3b29695fb4901c75b60f13b37de63759a02d01b6eec47501a7672c14578","contract":["SocksClient.createConnectionChain establishes connection through a chain of SOCKS proxies","SocksClient.createConnectionChain transmits and receives data through established proxy chain","SocksClient.createConnectionChain rejects when fewer than two proxies are provided"],"goal":"verify pkg:npm/socks@2.8.10","kind":"HOW","packages":["pkg:npm/socks@2.8.10"],"schemaVersion":1,"symbols":["SocksClient.createConnectionChain"]},"contractCommand":["node","test/contract.cjs"],"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@2.8.10"],"schemaVersion":1,"subject":"pkg:npm/socks@2.8.10","symbols":["SocksClient.createConnectionChain"],"verifierAdapter":"node-typescript@1"}

'use strict';

const { SocksClient, SocksClientError } = require('socks');

/**
 * Creates a SOCKS connection chain through multiple SOCKS proxies.
 * @param {import('socks').SocksClientChainOptions} options
 * @param {Function} [callback]
 * @returns {Promise<import('socks').SocksClientEstablishedEvent>}
 */
async function createSocksConnectionChain(options, callback) {
  return await SocksClient.createConnectionChain(options, callback);
}

module.exports = {
  SocksClient,
  SocksClientError,
  createSocksConnectionChain
};

{
  "name": "sample-socks-chain",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-socks-chain",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "socks": "2.8.10"
      }
    },
    "node_modules/ip-address": {
      "version": "10.7.0",
      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.0.tgz",
      "integrity": "sha512-BGFsyJd5mpXp3rK6jIdADLNgpJUK1jnjzvYF8lK+VyDab9JAmqN0YOKDdP17HlgKb2+ehPgDc8EtnRLbGCAMhA==",
      "license": "MIT",
      "engines": {
        "node": ">= 12"
      }
    },
    "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.10",
      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.10.tgz",
      "integrity": "sha512-e0VyvkVTwVYViNovRkZ9aodhxVlyoMn7eJhVUPxZ+eK9P/7CBkxvvsBOHqFPEH416726W8tLXXXjKwqgTErrCQ==",
      "license": "MIT",
      "dependencies": {
        "ip-address": "^10.1.1",
        "smart-buffer": "^4.2.0"
      },
      "engines": {
        "node": ">= 10.0.0",
        "npm": ">= 3.0.0"
      }
    }
  }
}

{
  "name": "sample-socks-chain",
  "version": "1.0.0",
  "private": true,
  "description": "verify pkg:npm/socks@2.8.10",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "socks": "2.8.10"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/socks@2.8.10",
  "kind": "HOW",
  "packages": [
    "pkg:npm/socks@2.8.10"
  ],
  "symbols": [
    "SocksClient.createConnectionChain"
  ]
}

'use strict';

const assert = require('assert');
const net = require('net');
const { SocksClient, SocksClientError, createSocksConnectionChain } = require('../index.js');

function createMockSocks5Proxy() {
  const sockets = new Set();
  const server = net.createServer((clientSocket) => {
    sockets.add(clientSocket);
    clientSocket.on('close', () => sockets.delete(clientSocket));
    let state = 'AUTH';
    let targetSocket = null;

    clientSocket.on('data', (data) => {
      if (state === 'PIPE') {
        if (targetSocket && !targetSocket.destroyed) {
          targetSocket.write(data);
        }
        return;
      }
      if (state === 'AUTH') {
        assert.strictEqual(data[0], 0x05, 'Expected SOCKS5 version');
        // Reply no authentication required
        clientSocket.write(Buffer.from([0x05, 0x00]));
        state = 'REQ';
      } else if (state === 'REQ') {
        assert.strictEqual(data[0], 0x05, 'Expected SOCKS5 version');
        assert.strictEqual(data[1], 0x01, 'Expected CONNECT command');
        let destHost;
        let destPort;
        const atyp = data[3];
        let offset = 4;
        if (atyp === 0x01) {
          destHost = `${data[offset]}.${data[offset + 1]}.${data[offset + 2]}.${data[offset + 3]}`;
          offset += 4;
        } else if (atyp === 0x03) {
          const len = data[offset++];
          destHost = data.subarray(offset, offset + len).toString('utf8');
          offset += len;
        }
        destPort = data.readUInt16BE(offset);

        targetSocket = net.connect(destPort, destHost, () => {
          clientSocket.write(Buffer.from([0x05, 0x00, 0x00, 0x01, 127, 0, 0, 1, 0x1f, 0x90]));
          state = 'PIPE';
          targetSocket.pipe(clientSocket);
        });
        sockets.add(targetSocket);
        targetSocket.on('error', () => {
          clientSocket.destroy();
        });
      }
    });

    clientSocket.on('error', () => {
      if (targetSocket) targetSocket.destroy();
    });
  });

  return {
    server,
    listen: () =>
      new Promise((resolve) =>
        server.listen(0, '127.0.0.1', () => resolve(server.address().port))
      ),
    close: () => {
      for (const s of sockets) s.destroy();
      return new Promise((resolve) => server.close(resolve));
    }
  };
}

async function runContractTests() {
  const proxy1 = createMockSocks5Proxy();
  const proxy2 = createMockSocks5Proxy();
  const destSockets = new Set();
  const destServer = net.createServer((socket) => {
    destSockets.add(socket);
    socket.on('close', () => destSockets.delete(socket));
    socket.on('data', (data) => {
      socket.write(`ECHO:${data.toString('utf8')}`);
    });
  });

  const p1Port = await proxy1.listen();
  const p2Port = await proxy2.listen();
  await new Promise((resolve) => destServer.listen(0, '127.0.0.1', resolve));
  const destPort = destServer.address().port;

  try {
    // 1. SocksClient.createConnectionChain establishes connection through a chain of SOCKS proxies
    const chainOptions = {
      proxies: [
        { ipaddress: '127.0.0.1', port: p1Port, type: 5 },
        { ipaddress: '127.0.0.1', port: p2Port, type: 5 }
      ],
      destination: { host: '127.0.0.1', port: destPort },
      command: 'connect'
    };

    const directInfo = await SocksClient.createConnectionChain(chainOptions);
    assert(directInfo && directInfo.socket, 'createConnectionChain must return socket info');
    assert(directInfo.socket instanceof net.Socket, 'directInfo.socket must be a net.Socket instance');

    // 2. SocksClient.createConnectionChain transmits and receives data through established proxy chain
    const echoed = await new Promise((resolve, reject) => {
      directInfo.socket.once('data', (data) => resolve(data.toString('utf8')));
      directInfo.socket.once('error', reject);
      directInfo.socket.write('ping-proxy-chain');
    });
    assert.strictEqual(echoed, 'ECHO:ping-proxy-chain', 'Data must pass through entire chain to destination');
    directInfo.socket.destroy();

    // Verify helper function createSocksConnectionChain as well
    const helperInfo = await createSocksConnectionChain(chainOptions);
    assert(helperInfo && helperInfo.socket, 'createSocksConnectionChain helper must establish connection');
    helperInfo.socket.destroy();

    // 3. SocksClient.createConnectionChain rejects when fewer than two proxies are provided
    let caughtErr = null;
    try {
      await SocksClient.createConnectionChain({
        proxies: [
          { ipaddress: '127.0.0.1', port: p1Port, type: 5 }
        ],
        destination: { host: '127.0.0.1', port: destPort },
        command: 'connect'
      });
    } catch (err) {
      caughtErr = err;
    }
    assert(caughtErr, 'Should reject when fewer than two proxies provided');
    assert(caughtErr instanceof SocksClientError, 'Caught error must be SocksClientError instance');

    console.log('Contract assertions passed successfully.');
    process.exit(0);
  } finally {
    for (const s of destSockets) s.destroy();
    await new Promise((resolve) => destServer.close(resolve));
    await proxy1.close();
    await proxy2.close();
  }
}

runContractTests().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});