socks 2.8.7

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

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

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:6a6bf005eebafefaec42b755f8409e92c5bce1f95c003b53d5a20caa26056813","contract":["SocksClient.createUDPFrame and SocksClient.parseUDPFrame round-trip hostname and IPv4 SOCKS5 UDP frames with frameNumber, remoteHost, and payload Buffer.","SocksClient.createConnection negotiates a SOCKS5 connect handshake over an existing_socket Duplex stream and resolves with the established socket and remoteHost.","SocksClient.createConnection rejects with SocksClientError when passed a non-connect command."],"goal":"verify pkg:npm/socks@2.8.7","kind":"HOW","packages":["pkg:npm/socks@2.8.7"],"schemaVersion":1},"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","verifierAdapter":"node-typescript@1"}

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

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

import assert from "node:assert/strict";
import { Duplex } from "node:stream";
import { SocksClient, SocksClientError } from "socks";

// 1. Verify UDP frame creation and parsing for hostname and IPv4
const payload = Buffer.from("hello-socks");
const frame = SocksClient.createUDPFrame({
  frameNumber: 3,
  remoteHost: { host: "example.com", port: 8080 },
  data: payload,
});
assert.ok(Buffer.isBuffer(frame));

const parsed = SocksClient.parseUDPFrame(frame);
assert.equal(parsed.frameNumber, 3);
assert.deepEqual(parsed.remoteHost, { host: "example.com", port: 8080 });
assert.deepEqual(parsed.data, payload);

const ipv4Frame = SocksClient.createUDPFrame({
  remoteHost: { host: "127.0.0.1", port: 1080 },
  data: Buffer.from("ping"),
});
const parsedIpv4 = SocksClient.parseUDPFrame(ipv4Frame);
assert.equal(parsedIpv4.frameNumber, 0);
assert.deepEqual(parsedIpv4.remoteHost, { host: "127.0.0.1", port: 1080 });
assert.equal(parsedIpv4.data.toString("utf8"), "ping");

// 2. Verify SocksClient.createConnection SOCKS5 handshake over an in-memory Duplex stream
const writtenChunks = [];
const mockSocket = new Duplex({
  read() {},
  write(chunk, _encoding, callback) {
    writtenChunks.push(Buffer.from(chunk));
    if (writtenChunks.length === 1) {
      // Respond to SOCKS5 initial greeting (0x05, 0x01, 0x00) with NoAuth (0x05, 0x00)
      setImmediate(() => {
        mockSocket.push(Buffer.from([0x05, 0x00]));
      });
    } else if (writtenChunks.length === 2) {
      // Respond to SOCKS5 CONNECT command with Granted (0x05, 0x00, 0x00, IPv4=0x01, 127.0.0.1, port 1080)
      setImmediate(() => {
        mockSocket.push(
          Buffer.from([0x05, 0x00, 0x00, 0x01, 127, 0, 0, 1, 0x04, 0x38])
        );
      });
    }
    callback();
  },
});

const established = await SocksClient.createConnection({
  proxy: {
    host: "127.0.0.1",
    port: 1080,
    type: 5,
  },
  command: "connect",
  destination: {
    host: "example.com",
    port: 443,
  },
  existing_socket: mockSocket,
});

assert.equal(established.socket, mockSocket);
assert.deepEqual(established.remoteHost, { host: "127.0.0.1", port: 1080 });
assert.equal(writtenChunks.length, 2);
assert.deepEqual(writtenChunks[0], Buffer.from([0x05, 0x01, 0x00]));

// 3. Verify option validation rejects with SocksClientError
await assert.rejects(
  () =>
    SocksClient.createConnection({
      proxy: { host: "127.0.0.1", port: 1080, type: 5 },
      command: "bind",
      destination: { host: "example.com", port: 443 },
    }),
  (err) => err instanceof SocksClientError
);