socks 2.8.7: SocksClient

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 socks.SocksClient in pkg:npm/socks@2.8.7
Kind: HOW

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

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:3864478aefa51309718ef3ef1a549d0b73149ef2e74d8209f4ec6880950e33b2","contract":["SocksClient connects via SOCKS5 proxy using event-driven interface","SocksClient.createConnection establishes a SOCKS5 proxy connection","SocksClient creates and parses UDP request frames","SocksClient rejects invalid proxy configuration"],"goal":"verify socks.SocksClient in pkg:npm/socks@2.8.7","kind":"HOW","packages":["pkg:npm/socks@2.8.7"],"schemaVersion":1,"symbols":["socks.SocksClient"]},"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.7"],"schemaVersion":1,"subject":"pkg:npm/socks@2.8.7","symbols":["socks.SocksClient"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

/**
 * Creates a connection using the SocksClient instance event interface.
 * @param {import('socks').SocksClientOptions} options
 * @returns {Promise<import('socks').SocksClientBoundEvent>}
 */
function connectWithClient(options) {
  return new Promise((resolve, reject) => {
    const client = new SocksClient(options);
    client.on('established', (info) => {
      resolve(info);
    });
    client.on('error', (err) => {
      reject(err);
    });
    client.connect();
  });
}

/**
 * Creates a SOCKS5 UDP frame.
 * @param {{ remoteHost: { host: string, port: number }, data: Buffer }} options
 * @returns {Buffer}
 */
function createUdpPacket(options) {
  return SocksClient.createUDPFrame(options);
}

/**
 * Parses a SOCKS5 UDP frame.
 * @param {Buffer} data
 * @returns {import('socks').SocksUDPFrameDetails}
 */
function parseUdpPacket(data) {
  return SocksClient.parseUDPFrame(data);
}

module.exports = {
  SocksClient,
  SocksClientError,
  connectWithClient,
  createUdpPacket,
  parseUdpPacket
};

{
  "name": "sample-socks-client",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-socks-client",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "socks": "2.8.7"
      }
    },
    "node_modules/ip-address": {
      "version": "10.7.4",
      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.4.tgz",
      "integrity": "sha512-DWBMKyeM25D70nrIiTkgQth59/G+naKOTep6huF9j+GmeK3DMD60Zvxg5d5qQnz+38AHgou6ean2LECX+lrKDg==",
      "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.7",
      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.7.tgz",
      "integrity": "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A==",
      "license": "MIT",
      "dependencies": {
        "ip-address": "^10.0.1",
        "smart-buffer": "^4.2.0"
      },
      "engines": {
        "node": ">= 10.0.0",
        "npm": ">= 3.0.0"
      }
    }
  }
}

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

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

'use strict';

const assert = require('assert');
const net = require('net');
const {
  SocksClient,
  connectWithClient,
  createUdpPacket,
  parseUdpPacket
} = require('../index.js');

async function run() {
  // 1. 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, 'SOCKS version 5 expected');
        // Reply: version 5, no authentication required (0x00)
        socket.write(Buffer.from([0x05, 0x00]));
        state = 'REQUEST';
      } else if (state === 'REQUEST') {
        assert.strictEqual(chunk[0], 0x05, 'SOCKS version 5 expected');
        assert.strictEqual(chunk[1], 0x01, 'CONNECT command expected');
        // Reply: version 5, success (0x00), RSV 0x00, ATYP IPv4 (0x01), 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') {
        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 connects via SOCKS5 proxy using event-driven interface
    const info = await connectWithClient({
      proxy: {
        ipaddress: '127.0.0.1',
        port: proxyPort,
        type: 5
      },
      command: 'connect',
      destination: {
        host: '127.0.0.1',
        port: 8080
      }
    });

    assert(info && info.socket, 'Connection info and socket must exist');
    assert(info.socket instanceof net.Socket, 'info.socket must be a net.Socket instance');

    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');
    });
    assert.strictEqual(received, 'ECHO:ping', 'Data should be echoed through proxy');
    info.socket.destroy();

    // 3. SocksClient.createConnection establishes a SOCKS5 proxy connection
    const staticInfo = await SocksClient.createConnection({
      proxy: {
        ipaddress: '127.0.0.1',
        port: proxyPort,
        type: 5
      },
      command: 'connect',
      destination: {
        host: '127.0.0.1',
        port: 8080
      }
    });
    assert(staticInfo && staticInfo.socket, 'SocksClient.createConnection must establish connection');
    staticInfo.socket.destroy();

    // 4. SocksClient creates and parses UDP request frames
    const payload = Buffer.from('test-udp-payload');
    const udpFrame = createUdpPacket({
      remoteHost: { host: '127.0.0.1', port: 9000 },
      data: payload
    });
    assert(Buffer.isBuffer(udpFrame), 'createUdpPacket must return a Buffer');

    const parsedFrame = parseUdpPacket(udpFrame);
    assert(parsedFrame, 'parseUdpPacket must return frame details');
    assert.strictEqual(parsedFrame.remoteHost.host, '127.0.0.1');
    assert.strictEqual(parsedFrame.remoteHost.port, 9000);
    assert.strictEqual(parsedFrame.data.toString('utf8'), 'test-udp-payload');

    // 5. SocksClient rejects invalid proxy configuration
    let caughtError = null;
    try {
      await connectWithClient({
        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, 'Must fail when invalid proxy type is provided');

    console.log('Contract tests passed.');
    process.exit(0);
  } finally {
    server.close();
  }
}

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