socks 2.8.9: 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.9
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/socks@2.8.9

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:28db98264bf47601cb76583c3ac73d585380009d0e147914405f8c7775307a67","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.9","kind":"HOW","packages":["pkg:npm/socks@2.8.9"],"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.9"],"schemaVersion":1,"subject":"pkg:npm/socks@2.8.9","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').SocksClientBoundEvent>}
 */
async function createSocksConnection(options) {
  return await SocksClient.createConnection(options);
}

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

{
  "name": "sample-socks",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-socks",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "socks": "2.8.9"
      }
    },
    "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/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"
      }
    }
  }
}

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

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/socks@2.8.9",
  "kind": "HOW",
  "packages": [
    "pkg:npm/socks@2.8.9"
  ]
}

'use strict';

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

async function run() {
  // 1. Set up an in-memory mock SOCKS5 proxy server
  const server = net.createServer((socket) => {
    let state = 'AUTH';
    socket.on('data', (chunk) => {
      if (state === 'AUTH') {
        assert.strictEqual(chunk[0], 0x05, 'Must be SOCKS version 5');
        // Reply with NO_AUTH required (0x05, 0x00)
        socket.write(Buffer.from([0x05, 0x00]));
        state = 'REQUEST';
      } else if (state === 'REQUEST') {
        assert.strictEqual(chunk[0], 0x05, 'Must be SOCKS version 5');
        assert.strictEqual(chunk[1], 0x01, 'Must be CONNECT command');
        // Reply with Success (0x00), BND.ADDR 127.0.0.1, BND.PORT 8080
        socket.write(Buffer.from([0x05, 0x00, 0x00, 0x01, 127, 0, 0, 1, 0x1f, 0x90]));
        state = 'STREAM';
      } else if (state === 'STREAM') {
        // Echo back data prefixed with ECHO:
        socket.write(Buffer.concat([Buffer.from('ECHO:'), chunk]));
      }
    });
  });

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

  try {
    // 2. SocksClient.createConnection establishes a connection 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: 8080
      }
    });

    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, 8080);

    // 3. 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-test');
    });
    assert.strictEqual(received, 'ECHO:ping-test', 'Data must be echoed across proxy stream');
    info.socket.destroy();

    // 4. Test helper function createSocksConnection
    const helperInfo = await createSocksConnection({
      proxy: {
        ipaddress: '127.0.0.1',
        port: proxyPort,
        type: 5
      },
      command: 'connect',
      destination: {
        host: '127.0.0.1',
        port: 8080
      }
    });
    assert(helperInfo && helperInfo.socket, 'createSocksConnection helper must return established connection');
    helperInfo.socket.destroy();

    // 5. 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: 8080
        }
      });
    } 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 tests passed successfully.');
    process.exit(0);
  } finally {
    server.close();
  }
}

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