socks 2.8.10: SocksClient.createConnection

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.createConnection

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:ae12e021dda66cbda5700958cf2c48d132208c93884a57a23dbc7a6b6103c1b6","contract":["SocksClient.createConnection establishes a SOCKS5 connection to a proxy server and returns socket info","SocksClient transmits and receives data through established SOCKS5 proxy connection","SocksClient throws SocksClientError when provided invalid proxy configuration options"],"goal":"verify pkg:npm/socks@2.8.10","kind":"HOW","packages":["pkg:npm/socks@2.8.10"],"schemaVersion":1,"symbols":["SocksClient.createConnection"]},"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.createConnection"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

/**
 * Creates a SOCKS connection using SocksClient.
 * @param {import('socks').SocksClientOptions} options
 * @returns {Promise<import('socks').SocksClientEstablishedEvent>}
 */
async function createSocksConnection(options) {
  return await SocksClient.createConnection(options);
}

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

{
  "name": "sample-socks-connection",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-socks-connection",
      "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-connection",
  "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.createConnection"
  ]
}

'use strict';

const assert = require('assert');
const net = require('net');
const { SocksClient, SocksClientError, createSocksConnection } = 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');
        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, () => {
          const bndPortBuf = Buffer.alloc(2);
          bndPortBuf.writeUInt16BE(destPort);
          const reply = Buffer.concat([
            Buffer.from([0x05, 0x00, 0x00, 0x01, 127, 0, 0, 1]),
            bndPortBuf
          ]);
          clientSocket.write(reply);
          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 proxy = createMockSocks5Proxy();
  const proxyPort = await proxy.listen();

  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')}`);
    });
  });
  await new Promise((resolve) => destServer.listen(0, '127.0.0.1', resolve));
  const destPort = destServer.address().port;

  try {
    // 1. SocksClient.createConnection establishes a SOCKS5 connection to a proxy server and returns socket info
    const info = await SocksClient.createConnection({
      proxy: {
        ipaddress: '127.0.0.1',
        port: proxyPort,
        type: 5
      },
      command: 'connect',
      destination: {
        host: '127.0.0.1',
        port: destPort
      }
    });

    assert(info, 'Result info must be defined');
    assert(info.socket instanceof net.Socket, 'info.socket must be an instance of net.Socket');
    assert.strictEqual(info.remoteHost.host, '127.0.0.1');
    assert.strictEqual(info.remoteHost.port, destPort);

    // 2. SocksClient transmits and receives data through established SOCKS5 proxy connection
    const received = await new Promise((resolve, reject) => {
      info.socket.once('data', (data) => resolve(data.toString('utf8')));
      info.socket.once('error', reject);
      info.socket.write('ping-socks5');
    });
    assert.strictEqual(received, 'ECHO:ping-socks5', 'Data must be echoed across proxy stream');
    info.socket.destroy();

    // Verify helper function createSocksConnection as well
    const helperInfo = await createSocksConnection({
      proxy: {
        ipaddress: '127.0.0.1',
        port: proxyPort,
        type: 5
      },
      command: 'connect',
      destination: {
        host: '127.0.0.1',
        port: destPort
      }
    });
    assert(helperInfo && helperInfo.socket, 'createSocksConnection helper must establish connection');
    helperInfo.socket.destroy();

    // 3. SocksClient throws SocksClientError when provided invalid proxy configuration options
    let caughtError = null;
    try {
      await SocksClient.createConnection({
        proxy: {
          ipaddress: '127.0.0.1',
          port: proxyPort,
          type: 99
        },
        command: 'connect',
        destination: {
          host: '127.0.0.1',
          port: destPort
        }
      });
    } catch (err) {
      caughtError = err;
    }
    assert(caughtError, 'Should throw error on invalid proxy configuration options');
    assert(
      caughtError instanceof SocksClientError || caughtError instanceof Error,
      'Caught error must be instance of SocksClientError or Error'
    );

    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 proxy.close();
  }
}

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