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 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:
  - 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:6bcaa5aacbeec06ec2450df735bd590282c0e51659095917bbe58f244c0576ee","contract":["SocksClient.createUDPFrame and SocksClient.parseUDPFrame round-trip IPv4, IPv6, and hostname UDP relay frames with payload and frameNumber intact","new SocksClient validates SocksClientOptions and exposes socksClientOptions, throwing SocksClientError on invalid commands","SocksClient.createConnection negotiates a SOCKS5 connect handshake over an existing_socket Duplex stream and resolves the established socket and remoteHost"],"goal":"verify SocksClient in pkg:npm/socks@2.8.7","kind":"HOW","packages":["pkg:npm/socks@2.8.7"],"schemaVersion":1,"symbols":["SocksClient"]},"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@2.8.7"],"schemaVersion":1,"subject":"pkg:npm/socks@2.8.7","symbols":["SocksClient"],"verifierAdapter":"node-typescript@1"}

{
  "name": "socks-client-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "socks-client-sample",
      "version": "1.0.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": "socks-client-sample",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "socks": "2.8.7"
  }
}

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

import { Duplex } from 'node:stream';
import { SocksClient, SocksClientError } from 'socks';

export function roundTripUDPFrame(host, port, payload, frameNumber = 0) {
  const frame = SocksClient.createUDPFrame({
    frameNumber,
    remoteHost: { host, port },
    data: payload,
  });
  return {
    frame,
    parsed: SocksClient.parseUDPFrame(frame),
  };
}

export async function connectSocks5OverDuplex(destinationHost, destinationPort) {
  const sentPackets = [];
  let step = 0;

  const mockSocket = new Duplex({
    read() {},
    write(chunk, _encoding, callback) {
      const buf = Buffer.from(chunk);
      sentPackets.push(buf);
      step += 1;
      const currentStep = step;
      callback();
      setImmediate(() => {
        if (currentStep === 1) {
          // Respond to SOCKS5 greeting: version 5, NoAuth (0x00)
          this.push(Buffer.from([0x05, 0x00]));
        } else if (currentStep === 2) {
          // Respond to SOCKS5 CONNECT command: version 5, Granted (0x00), RSV (0x00), IPv4 (0x01), 127.0.0.1:1080
          this.push(Buffer.from([0x05, 0x00, 0x00, 0x01, 127, 0, 0, 1, 0x04, 0x38]));
        }
      });
    },
  });

  const established = await SocksClient.createConnection({
    proxy: {
      host: '127.0.0.1',
      port: 1080,
      type: 5,
    },
    command: 'connect',
    destination: {
      host: destinationHost,
      port: destinationPort,
    },
    existing_socket: mockSocket,
  });

  return {
    established,
    sentPackets,
  };
}

export function createClientInstance(options) {
  return new SocksClient(options);
}

export { SocksClient, SocksClientError };

import assert from 'node:assert/strict';
import {
  SocksClient,
  SocksClientError,
  roundTripUDPFrame,
  connectSocks5OverDuplex,
  createClientInstance,
} from '../src/index.mjs';

// 1. Verify UDP frame creation and parsing for IPv4, IPv6, and hostname
const payload = Buffer.from('hello-socks');

const ipv4Result = roundTripUDPFrame('127.0.0.1', 8080, payload, 1);
assert.equal(Buffer.isBuffer(ipv4Result.frame), true);
assert.equal(ipv4Result.parsed.frameNumber, 1);
assert.deepEqual(ipv4Result.parsed.remoteHost, { host: '127.0.0.1', port: 8080 });
assert.deepEqual(ipv4Result.parsed.data, payload);

const domainResult = roundTripUDPFrame('example.com', 443, payload, 2);
assert.equal(domainResult.parsed.frameNumber, 2);
assert.deepEqual(domainResult.parsed.remoteHost, { host: 'example.com', port: 443 });
assert.deepEqual(domainResult.parsed.data, payload);

const ipv6Result = roundTripUDPFrame('::1', 9000, payload, 0);
assert.equal(ipv6Result.parsed.frameNumber, 0);
assert.equal(ipv6Result.parsed.remoteHost.port, 9000);
assert.equal(ipv6Result.parsed.remoteHost.host, '0000:0000:0000:0000:0000:0000:0000:0001');
assert.deepEqual(ipv6Result.parsed.data, payload);

// 2. Verify SocksClient instance creation and option validation
const client = createClientInstance({
  proxy: { host: '127.0.0.1', port: 1080, type: 5 },
  command: 'connect',
  destination: { host: 'example.com', port: 80 },
});
assert.equal(client instanceof SocksClient, true);
assert.deepEqual(client.socksClientOptions.destination, { host: 'example.com', port: 80 });

assert.throws(
  () =>
    createClientInstance({
      proxy: { host: '127.0.0.1', port: 1080, type: 5 },
      command: 'invalid-cmd',
      destination: { host: 'example.com', port: 80 },
    }),
  (err) => err instanceof SocksClientError
);

// 3. Verify SocksClient.createConnection SOCKS5 handshake over existing_socket Duplex
const { established, sentPackets } = await connectSocks5OverDuplex('example.com', 80);
assert.equal(sentPackets.length, 2);
assert.deepEqual(sentPackets[0], Buffer.from([0x05, 0x01, 0x00]));
assert.equal(sentPackets[1][0], 0x05);
assert.equal(sentPackets[1][1], 0x01);
assert.equal(sentPackets[1][3], 0x03); // Hostname address type
assert.deepEqual(established.remoteHost, { host: '127.0.0.1', port: 1080 });
assert.equal(typeof established.socket.write, 'function');
established.socket.destroy();