CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-socks

Fully featured SOCKS proxy client supporting SOCKSv4, SOCKSv4a, and SOCKSv5 with Bind and Associate functionality.

—

Pending
Overview
Eval results
Files

validation-utilities.mddocs/

Validation and Utility Functions

Utility and validation functions for SOCKS client configuration validation and IP address manipulation. These functions are primarily used internally by the SOCKS client but are exported for advanced use cases.

Capabilities

Configuration Validation

Functions that validate SOCKS client configuration objects to ensure they contain valid and complete settings.

SocksClientOptions Validation

Validates a SocksClientOptions object for use with single proxy connections.

/**
 * Validates the provided SocksClientOptions
 * @param options - The SocksClientOptions to validate
 * @param acceptedCommands - List of accepted SOCKS commands (default: ['connect', 'bind', 'associate'])
 * @throws SocksClientError if validation fails
 */
function validateSocksClientOptions(
  options: SocksClientOptions,
  acceptedCommands?: string[]
): void;

Usage Example:

import { validateSocksClientOptions, SocksClientError } from "socks";

try {
  validateSocksClientOptions({
    command: 'connect',
    proxy: {
      host: '127.0.0.1',
      port: 1080,
      type: 5
    },
    destination: {
      host: 'example.com',
      port: 80
    }
  });
  console.log('Configuration is valid');
} catch (error) {
  if (error instanceof SocksClientError) {
    console.error('Configuration error:', error.message);
  }
}

SocksClientChainOptions Validation

Validates a SocksClientChainOptions object for use with proxy chaining.

/**
 * Validates the SocksClientChainOptions
 * @param options - The SocksClientChainOptions to validate
 * @throws SocksClientError if validation fails
 */
function validateSocksClientChainOptions(
  options: SocksClientChainOptions
): void;

Usage Example:

import { validateSocksClientChainOptions, SocksClientError } from "socks";

try {
  validateSocksClientChainOptions({
    command: 'connect',
    destination: {
      host: 'example.com',
      port: 80
    },
    proxies: [
      { host: '127.0.0.1', port: 1080, type: 5 },
      { host: '127.0.0.1', port: 1081, type: 5 }
    ]
  });
  console.log('Chain configuration is valid');
} catch (error) {
  if (error instanceof SocksClientError) {
    console.error('Chain configuration error:', error.message);
  }
}

IP Address Utilities

Low-level utility functions for converting between different IP address representations used by SOCKS protocols.

IPv4 to 32-bit Integer Conversion

Converts an IPv4 address string to a 32-bit unsigned integer.

/**
 * Converts an IPv4 address string to a 32-bit unsigned integer
 * @param ip - IPv4 address in dotted decimal notation (e.g., "192.168.1.1")
 * @returns 32-bit unsigned integer representation
 */
function ipv4ToInt32(ip: string): number;

Usage Example:

import { ipv4ToInt32 } from "socks";

const ipInt = ipv4ToInt32("192.168.1.1");
console.log(ipInt); // 3232235777

32-bit Integer to IPv4 Conversion

Converts a 32-bit unsigned integer back to an IPv4 address string.

/**
 * Converts a 32-bit unsigned integer to an IPv4 address string
 * @param int32 - 32-bit unsigned integer representation
 * @returns IPv4 address in dotted decimal notation
 */
function int32ToIpv4(int32: number): string;

Usage Example:

import { int32ToIpv4 } from "socks";

const ipString = int32ToIpv4(3232235777);
console.log(ipString); // "192.168.1.1"

IP Address to Buffer Conversion

Converts an IP address (IPv4 or IPv6) to a Buffer representation for network transmission.

/**
 * Converts an IP address to a Buffer for network transmission
 * @param ip - IPv4 or IPv6 address string
 * @returns Buffer containing the binary representation of the IP address
 * @throws Error if the IP address format is invalid
 */
function ipToBuffer(ip: string): Buffer;

Usage Examples:

import { ipToBuffer } from "socks";

// IPv4 address
const ipv4Buffer = ipToBuffer("192.168.1.1");
console.log(ipv4Buffer); // <Buffer c0 a8 01 01>

// IPv6 address
const ipv6Buffer = ipToBuffer("2001:db8::1");
console.log(ipv6Buffer); // <Buffer 20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01>

// Invalid address throws error
try {
  ipToBuffer("invalid-ip");
} catch (error) {
  console.error('Invalid IP address format');
}

Validation Details

The validation functions check the following:

SocksClientOptions Validation

  • Command is one of: 'connect', 'bind', 'associate'
  • Destination host is a valid string and port is 0-65535
  • Proxy configuration is complete and valid
  • Custom authentication settings are properly configured (if used)
  • Timeout value is positive (if specified)
  • Existing socket is a Duplex stream (if provided)

SocksClientChainOptions Validation

  • Command is 'connect' (only supported command for chaining)
  • Destination host and port are valid
  • At least 2 proxies are provided in the chain
  • Each proxy in the chain passes individual proxy validation
  • Timeout value is positive (if specified)

Custom Authentication Validation

When custom authentication is configured, the validation ensures:

  • Authentication method is in the valid range (0x80-0xFE)
  • Request handler function is provided
  • Response size is specified
  • Response handler function is provided

Error Handling

All validation functions throw SocksClientError instances with descriptive messages when validation fails. The error object includes the original options that failed validation for debugging purposes.

try {
  validateSocksClientOptions(invalidOptions);
} catch (error) {
  if (error instanceof SocksClientError) {
    console.error('Error:', error.message);
    console.error('Failed options:', error.options);
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-socks

docs

index.md

udp-frames.md

validation-utilities.md

tile.json