socks 2.8.10: SocksClient.parseUDPFrame

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.parseUDPFrame in 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.parseUDPFrame

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:f4a5989a8aeedfae5bea2247177136416c6ead4847eba071c8e96325bf57305c","contract":["SocksClient exports static parseUDPFrame and createUDPFrame methods","parseUDPFrame extracts IPv4 address, port, frame number, and payload from SOCKS5 UDP frame","parseUDPFrame normalizes IPv6 destination address to canonical full form in parsed frame details","parseUDPFrame parses domain name hostnames with variable length encoding","parseUDPFrame preserves non-zero fragment frame number","parseUDPFrame decodes raw RFC 1928 binary UDP packet buffers","parseUDPFrame throws bounds error when frame buffer is truncated or malformed"],"goal":"verify SocksClient.parseUDPFrame in pkg:npm/socks@2.8.10","kind":"HOW","packages":["pkg:npm/socks@2.8.10"],"schemaVersion":1,"symbols":["SocksClient.parseUDPFrame"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/socks@2.8.10"],"schemaVersion":1,"subject":"pkg:npm/socks@2.8.10","symbols":["SocksClient.parseUDPFrame"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-socks-parse-udp-frame",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-socks-parse-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-parse-udp-frame",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for SocksClient.parseUDPFrame",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "socks": "2.8.10"
  }
}

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

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

/**
 * Parses a SOCKS5 UDP frame buffer into frame details.
 *
 * @param {Buffer} data - Binary SOCKS5 UDP frame buffer
 * @returns {import('socks').SocksUDPFrameDetails} Parsed frame details containing remoteHost, port, frameNumber, and data
 */
function parseUDPFrame(data) {
  return SocksClient.parseUDPFrame(data);
}

/**
 * Encapsulates a payload into a SOCKS5 UDP frame buffer.
 *
 * @param {import('socks').SocksUDPFrameDetails} options - UDP frame options
 * @returns {Buffer} SOCKS5 UDP frame buffer
 */
function createUDPFrame(options) {
  return SocksClient.createUDPFrame(options);
}

module.exports = {
  SocksClient,
  parseUDPFrame,
  createUDPFrame
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { SocksClient, parseUDPFrame, createUDPFrame } = require('../src/index.js');

async function testContract() {
  // 1. SocksClient exports static parseUDPFrame and createUDPFrame methods
  assert.equal(typeof SocksClient.parseUDPFrame, 'function', 'SocksClient.parseUDPFrame should be a function');
  assert.equal(typeof SocksClient.createUDPFrame, 'function', 'SocksClient.createUDPFrame should be a function');
  assert.equal(typeof parseUDPFrame, 'function', 'parseUDPFrame helper should be a function');
  assert.equal(typeof createUDPFrame, 'function', 'createUDPFrame helper should be a function');

  // 2. parseUDPFrame extracts IPv4 address, port, frame number, and payload from SOCKS5 UDP frame
  const ipv4Payload = Buffer.from('socks5-udp-ipv4-payload');
  const ipv4Frame = createUDPFrame({
    remoteHost: { host: '192.168.1.1', port: 8080 },
    data: ipv4Payload
  });
  const parsedIpv4 = parseUDPFrame(ipv4Frame);
  assert.equal(parsedIpv4.frameNumber, 0, 'default frameNumber should be 0');
  assert.equal(parsedIpv4.remoteHost.host, '192.168.1.1', 'parsed IPv4 host should match input');
  assert.equal(parsedIpv4.remoteHost.port, 8080, 'parsed port should match input');
  assert.ok(parsedIpv4.data.equals(ipv4Payload), 'parsed payload buffer should match input data');

  // 3. parseUDPFrame normalizes IPv6 destination address to canonical full form in parsed frame details
  const ipv6Payload = Buffer.from('socks5-udp-ipv6-payload');
  const ipv6Frame1 = createUDPFrame({
    remoteHost: { host: '::1', port: 9000 },
    data: ipv6Payload
  });
  const parsedIpv61 = parseUDPFrame(ipv6Frame1);
  assert.equal(
    parsedIpv61.remoteHost.host,
    '0000:0000:0000:0000:0000:0000:0000:0001',
    'IPv6 ::1 must be parsed to canonical zero-padded form'
  );
  assert.equal(parsedIpv61.remoteHost.port, 9000, 'parsed IPv6 port should match');
  assert.ok(parsedIpv61.data.equals(ipv6Payload), 'parsed IPv6 payload buffer should match');

  const ipv6Frame2 = createUDPFrame({
    remoteHost: { host: '2001:db8::1', port: 8443 },
    data: Buffer.from('ipv6-test-2')
  });
  const parsedIpv62 = parseUDPFrame(ipv6Frame2);
  assert.equal(
    parsedIpv62.remoteHost.host,
    '2001:0db8:0000:0000:0000:0000:0000:0001',
    'IPv6 2001:db8::1 must be parsed to canonical form'
  );
  assert.equal(parsedIpv62.remoteHost.port, 8443, 'parsed port should match');

  // 4. parseUDPFrame parses domain name hostnames with variable length encoding
  const domainPayload = Buffer.from('socks5-udp-domain-payload');
  const domainFrame = createUDPFrame({
    remoteHost: { host: 'example.com', port: 53 },
    data: domainPayload
  });
  const parsedDomain = parseUDPFrame(domainFrame);
  assert.equal(parsedDomain.frameNumber, 0, 'frameNumber should be 0');
  assert.equal(parsedDomain.remoteHost.host, 'example.com', 'domain hostname should be preserved');
  assert.equal(parsedDomain.remoteHost.port, 53, 'destination port should match');
  assert.ok(parsedDomain.data.equals(domainPayload), 'payload buffer should match');

  // 5. parseUDPFrame preserves non-zero fragment frame number
  const fragPayload = Buffer.from('fragment-payload-chunk');
  const fragFrame = createUDPFrame({
    frameNumber: 7,
    remoteHost: { host: '10.0.0.1', port: 1234 },
    data: fragPayload
  });
  const parsedFrag = parseUDPFrame(fragFrame);
  assert.equal(parsedFrag.frameNumber, 7, 'non-zero frameNumber should be preserved');
  assert.equal(parsedFrag.remoteHost.host, '10.0.0.1', 'remote host should match');
  assert.equal(parsedFrag.remoteHost.port, 1234, 'remote port should match');
  assert.ok(parsedFrag.data.equals(fragPayload), 'payload buffer should match');

  // 6. parseUDPFrame decodes raw RFC 1928 binary UDP packet buffers
  const rawRfcPayload = Buffer.from('rfc1928-direct-packet-bytes');
  const rawRfcBuffer = Buffer.concat([
    Buffer.from([
      0x00, 0x00,             // RSV: reserved 0x0000
      0x00,                   // FRAG: standalone datagram (0)
      0x01,                   // ATYP: IPv4 (0x01)
      127, 0, 0, 1,           // DST.ADDR: 127.0.0.1
      0x04, 0xd2              // DST.PORT: 1234 (0x04d2)
    ]),
    rawRfcPayload
  ]);
  const parsedRaw = SocksClient.parseUDPFrame(rawRfcBuffer);
  assert.equal(parsedRaw.frameNumber, 0, 'raw frame FRAG should be 0');
  assert.equal(parsedRaw.remoteHost.host, '127.0.0.1', 'raw frame IPv4 address should be 127.0.0.1');
  assert.equal(parsedRaw.remoteHost.port, 1234, 'raw frame port should be 1234');
  assert.ok(parsedRaw.data.equals(rawRfcPayload), 'raw frame data should match');

  // 7. parseUDPFrame throws bounds error when frame buffer is truncated or malformed
  assert.throws(
    () => SocksClient.parseUDPFrame(Buffer.from([])),
    /Target offset is beyond the bounds of the internal SmartBuffer data/,
    'empty buffer should throw bounds error on offset'
  );

  const truncatedIpv4 = Buffer.from([0x00, 0x00, 0x00, 0x01, 127, 0, 0, 1]);
  assert.throws(
    () => SocksClient.parseUDPFrame(truncatedIpv4),
    /Attempted to read beyond the bounds of the managed data/,
    'truncated IPv4 buffer should throw bounds error on port'
  );

  const truncatedHost = Buffer.from([0x00, 0x00, 0x00, 0x03, 10, 0x61, 0x62, 0x63]);
  assert.throws(
    () => SocksClient.parseUDPFrame(truncatedHost),
    /Attempted to read beyond the bounds of the managed data/,
    'truncated domain buffer should throw bounds error on string read'
  );

  console.log('All SocksClient.parseUDPFrame contract assertions passed successfully.');
}

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