socks 2.8.10: SocksClient.createUDPFrame

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

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:b0b64cb9bdb63a820a917744e1c03b808e49e9fe763e6a335feb2e2297f7473b","contract":["SocksClient.createUDPFrame encodes an IPv4 destination and payload into a SOCKS5 UDP frame buffer","SocksClient.createUDPFrame encodes a domain hostname destination into a SOCKS5 UDP frame buffer","SocksClient.createUDPFrame encodes an IPv6 destination and preserves frame sequence number and binary payload"],"goal":"verify pkg:npm/socks@2.8.10","kind":"HOW","packages":["pkg:npm/socks@2.8.10"],"schemaVersion":1,"symbols":["SocksClient.createUDPFrame"]},"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.createUDPFrame"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

/**
 * Creates a SOCKS UDP frame Buffer from UDP frame details.
 * @param {import('socks').SocksUDPFrameDetails} options
 * @returns {Buffer}
 */
function createSocksUDPFrame(options) {
  return SocksClient.createUDPFrame(options);
}

module.exports = {
  SocksClient,
  createSocksUDPFrame
};

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

'use strict';

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

function runContractTests() {
  // 1. SocksClient.createUDPFrame encodes an IPv4 destination and payload into a SOCKS5 UDP frame buffer
  const ipv4Payload = Buffer.from('dns-query-ipv4-payload');
  const frame1 = SocksClient.createUDPFrame({
    remoteHost: { host: '127.0.0.1', port: 53 },
    data: ipv4Payload
  });

  assert(Buffer.isBuffer(frame1), 'createUDPFrame must return a Buffer');
  // RFC 1928 SOCKS5 UDP Header: RSV (2 bytes) = 0x0000, FRAG (1 byte) = 0, ATYP (1 byte) = 0x01 (IPv4)
  assert.strictEqual(frame1[0], 0x00, 'RSV byte 0 must be 0x00');
  assert.strictEqual(frame1[1], 0x00, 'RSV byte 1 must be 0x00');
  assert.strictEqual(frame1[2], 0x00, 'FRAG byte must default to 0');
  assert.strictEqual(frame1[3], 0x01, 'ATYP byte must be 0x01 for IPv4');
  assert.deepStrictEqual(Array.from(frame1.subarray(4, 8)), [127, 0, 0, 1], 'IPv4 address bytes must match 127.0.0.1');
  assert.strictEqual(frame1.readUInt16BE(8), 53, 'Port must be 53');
  assert.strictEqual(frame1.subarray(10).toString('utf8'), 'dns-query-ipv4-payload', 'Payload must match input');

  // Verify helper function createSocksUDPFrame matches
  const helperFrame1 = createSocksUDPFrame({
    remoteHost: { host: '127.0.0.1', port: 53 },
    data: ipv4Payload
  });
  assert.deepStrictEqual(helperFrame1, frame1, 'createSocksUDPFrame helper must produce identical buffer');

  const parsed1 = SocksClient.parseUDPFrame(frame1);
  assert.strictEqual(parsed1.frameNumber, 0, 'Parsed frameNumber must be 0');
  assert.strictEqual(parsed1.remoteHost.host, '127.0.0.1', 'Parsed host must be 127.0.0.1');
  assert.strictEqual(parsed1.remoteHost.port, 53, 'Parsed port must be 53');
  assert.deepStrictEqual(parsed1.data, ipv4Payload, 'Parsed data must match payload');

  // 2. SocksClient.createUDPFrame encodes a domain hostname destination into a SOCKS5 UDP frame buffer
  const domainPayload = Buffer.from('ping-domain');
  const frame2 = SocksClient.createUDPFrame({
    frameNumber: 1,
    remoteHost: { host: 'example.com', port: 443 },
    data: domainPayload
  });

  assert.strictEqual(frame2[0], 0x00, 'RSV byte 0 must be 0x00');
  assert.strictEqual(frame2[1], 0x00, 'RSV byte 1 must be 0x00');
  assert.strictEqual(frame2[2], 0x01, 'FRAG byte must be 1');
  assert.strictEqual(frame2[3], 0x03, 'ATYP byte must be 0x03 for Domain Name');
  const domainLen = frame2[4];
  assert.strictEqual(domainLen, 'example.com'.length, 'Domain length must match string length');
  assert.strictEqual(frame2.subarray(5, 5 + domainLen).toString('utf8'), 'example.com', 'Domain string must match');
  assert.strictEqual(frame2.readUInt16BE(5 + domainLen), 443, 'Port must be 443');
  assert.strictEqual(frame2.subarray(5 + domainLen + 2).toString('utf8'), 'ping-domain', 'Payload must match');

  const parsed2 = SocksClient.parseUDPFrame(frame2);
  assert.strictEqual(parsed2.frameNumber, 1, 'Parsed frameNumber must be 1');
  assert.strictEqual(parsed2.remoteHost.host, 'example.com', 'Parsed host must be example.com');
  assert.strictEqual(parsed2.remoteHost.port, 443, 'Parsed port must be 443');
  assert.deepStrictEqual(parsed2.data, domainPayload, 'Parsed data must match payload');

  // 3. SocksClient.createUDPFrame encodes an IPv6 destination and preserves frame sequence number and binary payload
  const ipv6Payload = Buffer.from([0xde, 0xad, 0xbe, 0xef]);
  const frame3 = SocksClient.createUDPFrame({
    frameNumber: 5,
    remoteHost: { host: '::1', port: 8080 },
    data: ipv6Payload
  });

  assert.strictEqual(frame3[2], 0x05, 'FRAG byte must be 5');
  assert.strictEqual(frame3[3], 0x04, 'ATYP byte must be 0x04 for IPv6');
  assert.strictEqual(frame3.readUInt16BE(20), 8080, 'Port must be 8080 at byte offset 20');
  assert.deepStrictEqual(Array.from(frame3.subarray(22)), [0xde, 0xad, 0xbe, 0xef], 'Payload must match at byte offset 22');

  const parsed3 = SocksClient.parseUDPFrame(frame3);
  assert.strictEqual(parsed3.frameNumber, 5, 'Parsed frameNumber must be 5');
  assert.strictEqual(parsed3.remoteHost.host, '0000:0000:0000:0000:0000:0000:0000:0001', 'Parsed IPv6 canonical form must match ::1');
  assert.strictEqual(parsed3.remoteHost.port, 8080, 'Parsed port must be 8080');
  assert.deepStrictEqual(parsed3.data, ipv6Payload, 'Parsed data must match payload');

  console.log('Contract assertions passed successfully.');
}

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