socketduct 0.1.15

package/src/client/virtual-socket.js

@@ -0,0 +1,256 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/no-undefined-types, jsdoc/require-returns, jsdoc/ts-no-empty-object-type */
+import {Duplex} from "node:stream"
+
+/**
+ * @typedef {object} VirtualSocketOwner
+ * @property {(streamId: number, data: Buffer, callback: (error?: Error | null) => void) => void} _writeStream - Accept application bytes.
+ * @property {(streamId: number, callback: (error?: Error | null) => void) => void} _endStream - End the writable side.
+ * @property {(streamId: number, error: Error | null) => void} _destroyStream - Destroy the virtual stream.
+ * @property {(streamId: number) => void} _resumeReadable - Resume inbound flow.
+ * @property {() => {address?: string, port?: number}} physicalAddress - Current physical endpoint.
+ * @property {() => unknown} ref - Reference owner resources.
+ * @property {() => unknown} unref - Unreference owner resources.
+ */
+
+/** A stream-local failure where the physical connection may remain usable. */
+export class SocketductStreamError extends Error {
+  /**
+   * @param {string} message - Safe description.
+   * @param {string} code - Stable code.
+   */
+  constructor(message, code = "SOCKETDUCT_STREAM_ERROR") {
+    super(message)
+    this.name = "SocketductStreamError"
+    this.code = code
+  }
+}
+
+/** An unrecoverable resumable-session loss requiring caller reconciliation. */
+export class SocketductSessionLostError extends SocketductStreamError {
+  /**
+   * @param {string} message - Safe description.
+   * @param {string} [code] - Stable code.
+   */
+  constructor(message, code = "SOCKETDUCT_SESSION_LOST") {
+    super(message, code)
+    this.name = "SocketductSessionLostError"
+  }
+}
+
+/**
+ * A net.Socket-compatible Duplex backed by one v3 virtual stream.
+ * @augments Duplex
+ */
+export class VirtualSocket extends Duplex {
+  /** @type {VirtualSocketOwner} */
+  #connection
+
+  /** @type {number} */
+  #streamId
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  #timeoutTimer
+
+  /** @type {number} */
+  #timeoutMs = 0
+
+  /** @type {boolean} */
+  #connected = false
+
+  /** @type {boolean} */
+  #remoteEnded = false
+
+  /** @type {boolean} */
+  connecting = true
+
+  /** @type {boolean} */
+  pending = true
+
+  /** @type {number} */
+  bytesRead = 0
+
+  /** @type {number} */
+  bytesWritten = 0
+
+  /** @type {string | undefined} */
+  remoteAddress
+
+  /** @type {number | undefined} */
+  remotePort
+
+  /** @type {string | undefined} */
+  localAddress
+
+  /** @type {number | undefined} */
+  localPort
+
+  /** @type {string} */
+  remoteFamily = "IPv4"
+
+  /**
+   * @param {VirtualSocketOwner} connection - Owner.
+   * @param {number} streamId - Allocated stream ID.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} options - Socket metadata/options.
+   */
+  constructor(connection, streamId, options) {
+    super({
+      allowHalfOpen: options.allowHalfOpen ?? false,
+      ...(options.readableHighWaterMark === undefined ? {} : {readableHighWaterMark: options.readableHighWaterMark}),
+      ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark})
+    })
+    this.#connection = connection
+    this.#streamId = streamId
+    this.remoteAddress = options.host
+    this.remotePort = options.port
+    this.remoteFamily = options.host.includes(":") ? "IPv6" : "IPv4"
+  }
+
+  /** @returns {number} Protocol stream ID. */
+  get streamId() {
+    return this.#streamId
+  }
+
+  /** @returns {this} Socket-style no-op connect; opening starts at construction. */
+  connect() {
+    return this
+  }
+
+  /**
+   * @override
+   * @returns {void} Resume inbound flow.
+   */
+  _read() {
+    this.#connection._resumeReadable(this.#streamId)
+  }
+
+  /**
+   * @override
+   * @param {Buffer | string | Uint8Array} chunk - Application bytes.
+   * @param {BufferEncoding} encoding - Encoding.
+   * @param {(error?: Error | null) => void} callback - Completion.
+   * @returns {void}
+   */
+  _write(chunk, encoding, callback) {
+    const data = typeof chunk === "string" ? Buffer.from(chunk, encoding) : Buffer.from(chunk)
+    this.#resetTimeout()
+    this.#connection._writeStream(this.#streamId, data, (error) => {
+      if (error === undefined) this.bytesWritten += data.length
+      callback(error)
+    })
+  }
+
+  /**
+   * @override
+   * @param {(error?: Error | null) => void} callback - Completion.
+   * @returns {void}
+   */
+  _final(callback) {
+    this.#connection._endStream(this.#streamId, callback)
+  }
+
+  /**
+   * @override
+   * @param {Error | null} error - Destroy cause.
+   * @param {(error?: Error | null) => void} callback - Completion.
+   * @returns {void}
+   */
+  _destroy(error, callback) {
+    this.#clearTimeout()
+    this.connecting = false
+    this.pending = false
+    this.#connection._destroyStream(this.#streamId, error)
+    callback(error)
+  }
+
+  /** @param {Buffer} chunk - Inbound bytes from the owner. @returns {boolean} Readable capacity. */
+  _receive(chunk) {
+    if (this.destroyed || this.#remoteEnded) return false
+    this.bytesRead += chunk.length
+    this.#resetTimeout()
+    return this.push(chunk)
+  }
+
+  /** Marks target readiness and emits standard socket events. @returns {void} */
+  _markConnected() {
+    if (this.destroyed) return
+    if (this.#connected) {
+      this.emit("ready")
+      return
+    }
+    this.#connected = true
+    this.connecting = false
+    this.pending = false
+    const physical = this.#connection.physicalAddress()
+    this.localAddress = physical.address
+    this.localPort = physical.port
+    this.emit("connect")
+    this.emit("ready")
+  }
+
+  /** Ends the readable side without affecting siblings. @returns {void} */
+  _receiveEnd() {
+    if (this.#remoteEnded || this.destroyed) return
+    this.#remoteEnded = true
+    this.push(null)
+  }
+
+  /** @param {Error} error - Stream-local terminal failure. @returns {void} */
+  _receiveError(error) {
+    if (!this.destroyed) this.destroy(error)
+  }
+
+  /**
+   * @param {number} timeout - Milliseconds.
+   * @param {() => void} [callback] - Timeout listener.
+   * @returns {this} This socket.
+   */
+  setTimeout(timeout, callback) {
+    if (!Number.isFinite(timeout) || timeout < 0) throw new RangeError("Timeout must be a non-negative finite number")
+    if (callback !== undefined) this.once("timeout", callback)
+    this.#timeoutMs = timeout
+    this.#resetTimeout()
+    return this
+  }
+
+  /** @returns {this} Compatibility no-op; framing controls batching. */
+  setNoDelay() {
+    return this
+  }
+
+  /** @returns {this} Compatibility no-op; heartbeat is connection-scoped. */
+  setKeepAlive() {
+    return this
+  }
+
+  /** @returns {{address: string, family: string, port: number} | {}} Local physical endpoint metadata. */
+  address() {
+    if (this.localAddress === undefined || this.localPort === undefined) return {}
+    return {address: this.localAddress, family: this.localAddress.includes(":") ? "IPv6" : "IPv4", port: this.localPort}
+  }
+
+  /** @returns {this} References the shared transport. */
+  ref() {
+    this.#connection.ref()
+    return this
+  }
+
+  /** @returns {this} Unreferences the shared transport. */
+  unref() {
+    this.#connection.unref()
+    return this
+  }
+
+  /** @returns {void} */
+  #clearTimeout() {
+    if (this.#timeoutTimer !== undefined) clearTimeout(this.#timeoutTimer)
+    this.#timeoutTimer = undefined
+  }
+
+  /** @returns {void} */
+  #resetTimeout() {
+    this.#clearTimeout()
+    if (this.#timeoutMs === 0 || this.destroyed) return
+    this.#timeoutTimer = setTimeout(() => this.emit("timeout"), this.#timeoutMs)
+    this.#timeoutTimer.unref?.()
+  }
+}

package/src/config/environment.js

@@ -0,0 +1,400 @@
+import {isIP} from "node:net"
+
+import {DEFAULT_LOG_MAX_FILE_BYTES, DEFAULT_LOG_MAX_FILES, MAX_LOG_FILES, MIN_LOG_MAX_FILE_BYTES} from "../logging/structured-logger.js"
+
+const DEFAULT_RELAY_HOST = "127.0.0.1"
+const DEFAULT_RELAY_PORT = 3100
+const DEFAULT_RESUME_WINDOW_MS = 30_000
+const DEFAULT_MAX_TARGET_BUFFER_BYTES = 1_048_576
+const DEFAULT_MAX_TOTAL_BUFFER_BYTES = 16_777_216
+const DEFAULT_INITIAL_TARGET_RETRY_DELAY_MS = 250
+const DEFAULT_INITIAL_TARGET_RETRY_MAX_DELAY_MS = 5_000
+const DEFAULT_INITIAL_TARGET_CONNECT_TIMEOUT_MS = 10_000
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000
+const DEFAULT_MAX_INPUT_BYTES_PER_CONNECTION = 65_536
+const DEFAULT_STATUS_INTERVAL_MS = 30_000
+const PLACEHOLDER_TOKENS = new Set([
+  "replace-with-generated-token",
+  "replace-me",
+  "changeme",
+  "example-token",
+  "paste-generated-token-here"
+])
+const DEFAULT_MIN_COMPRESS_BYTES = 256
+const DEFAULT_MAX_DECOMPRESSED_BYTES = 16_777_216
+const DEFAULT_MAX_EXPANSION_RATIO = 1000
+const LOOPBACK_V6_ADDRESS = "::1"
+const SUPPORTED_MODES = new Set(["relay", "reverse-hub", "reverse-gateway", "summary"])
+const SUPPORTED_COMPRESSION = new Set(["auto", "off"])
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([2, 3])
+
+/**
+ * @typedef {object} TargetEndpoint
+ * @property {string} host - Target host.
+ * @property {number} port - Target port.
+ * @typedef {object} StaticTokenConfig
+ * @property {string} username - Username associated with the token.
+ * @property {string} token - Opaque bearer token.
+ * @typedef {object} RelayTlsConfig
+ * @property {string} certFile - Path to PEM certificate file.
+ * @property {string} keyFile - Path to PEM private key file.
+ * @property {string} [clientCaFile] - Optional path to client CA for mTLS.
+ * @typedef {object} RelayEnvironmentConfig
+ * @property {'summary' | 'relay' | 'reverse-hub' | 'reverse-gateway'} mode - Runtime mode.
+ * @property {string} relayHost - Relay listen host.
+ * @property {number} relayPort - Relay listen port.
+ * @property {number} resumeWindowMs - Resume window in milliseconds.
+ * @property {number} maxTargetBufferBytes - Per-session byte limit for buffered target data while the tunnel is detached.
+ * @property {number} maxTotalBufferBytes - Process-wide byte limit for buffered target data across all sessions.
+ * @property {number} [initialTargetRetryDelayMs] - Initial delay between target acquisition attempts. Default 250.
+ * @property {number} [initialTargetRetryMaxDelayMs] - Maximum delay between target acquisition attempts. Default 5000.
+ * @property {number} [initialTargetConnectTimeoutMs] - Maximum time for one initial target TCP connect attempt. Default 10000.
+ * @property {number} handshakeTimeoutMs - Milliseconds to wait for auth after TCP/TLS connect before closing the socket. Default 10000.
+ * @property {number} maxInputBytesPerConnection - Per-connection input byte budget before the first authenticated session frame. Default 65536.
+ * @property {number} [statusIntervalMs] - Safe status-log interval; zero disables periodic status logs.
+ * @property {{directory: string, maxFileBytes: number, maxFiles: number}} [fileLogging] - Optional persistent JSONL logging configuration.
+ * @property {'auto' | 'off'} [compression] - Whether to negotiate stream.data compression when the runtime supports it. Defaults to auto.
+ * @property {2 | 3} [protocolVersion] - Relay wire protocol; defaults to rollback-compatible v2.
+ * @property {number} [minCompressBytes] - Payloads smaller than this are sent raw.
+ * @property {number} [maxDecompressedBytes] - Maximum accepted decompressed stream.data size.
+ * @property {number} [maxExpansionRatio] - Maximum accepted decompressed/compressed expansion ratio.
+ * @property {StaticTokenConfig[]} authTokens - Static bearer tokens.
+ * @property {TargetEndpoint[]} targetAllowlist - Allowed target endpoints.
+ * @property {boolean} allowInsecurePublic - Explicit opt-out for non-loopback without TLS.
+ * @property {RelayTlsConfig} [relayTls] - Optional TLS configuration.
+ * @property {Array<{gatewayId: string, username: string}>} [reverseGatewayBindings] - Hub gateway identity bindings.
+ * @property {Array<{username: string, gatewayId: string, host: string, port: number}>} [reverseRoutes] - Hub client route policy.
+ * @property {string} [reverseGatewayId] - Outbound gateway stable ID.
+ * @property {string} [reverseConnectionId] - Outbound gateway stable transport identity.
+ * @property {{host: string, port: number, token: string}} [reverseHub] - Outbound hub endpoint.
+ * @property {{caFile?: string, certFile?: string, keyFile?: string, servername?: string}} [reverseHubTls] - Verified hub TLS options.
+ */
+
+/**
+ * @param {Record<string, string | undefined>} env - Process environment.
+ * @returns {RelayEnvironmentConfig} Runtime configuration.
+ */
+export function loadEnvironmentConfig(env = process.env) {
+  const rawMode = env.SOCKETDUCT_MODE?.trim()
+  if (rawMode !== undefined && !SUPPORTED_MODES.has(rawMode)) {
+    throw new Error(`Unsupported SOCKETDUCT_MODE: "${rawMode}". Must be one of: ${[...SUPPORTED_MODES].join(", ")}`)
+  }
+  const mode = rawMode === undefined ? "summary" : /** @type {'summary' | 'relay' | 'reverse-hub' | 'reverse-gateway'} */ (rawMode)
+  const rawCompression = env.SOCKETDUCT_COMPRESSION?.trim()
+  if (rawCompression !== undefined && !SUPPORTED_COMPRESSION.has(rawCompression)) {
+    throw new Error(`Unsupported SOCKETDUCT_COMPRESSION: "${rawCompression}". Must be one of: ${[...SUPPORTED_COMPRESSION].join(", ")}`)
+  }
+  const compression = rawCompression === "off" ? "off" : "auto"
+  const protocolVersion = parseProtocolVersion(env.SOCKETDUCT_PROTOCOL_VERSION)
+  const certFile = env.SOCKETDUCT_TLS_CERT_FILE?.trim() || undefined
+  const keyFile = env.SOCKETDUCT_TLS_KEY_FILE?.trim() || undefined
+  const clientCaFile = env.SOCKETDUCT_TLS_CLIENT_CA_FILE?.trim() || undefined
+  let relayTls
+
+  if (clientCaFile !== undefined && (certFile === undefined || keyFile === undefined)) {
+    throw new Error("SOCKETDUCT_TLS_CLIENT_CA_FILE requires SOCKETDUCT_TLS_CERT_FILE and SOCKETDUCT_TLS_KEY_FILE to be set (mTLS needs a TLS cert/key pair)")
+  }
+
+  if (certFile !== undefined || keyFile !== undefined) {
+    if (certFile === undefined || keyFile === undefined) {
+      throw new Error("SOCKETDUCT_TLS_CERT_FILE and SOCKETDUCT_TLS_KEY_FILE must both be set (atomic pair)")
+    }
+    /** @type {RelayTlsConfig} */
+    const tlsConfig = {certFile, keyFile}
+    if (clientCaFile !== undefined) {
+      tlsConfig.clientCaFile = clientCaFile
+    }
+    relayTls = tlsConfig
+  }
+
+  const initialTargetRetryDelayMs = parsePositiveInteger(
+    env.SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS,
+    "SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS",
+    DEFAULT_INITIAL_TARGET_RETRY_DELAY_MS
+  )
+  const initialTargetRetryMaxDelayMs = parsePositiveInteger(
+    env.SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS,
+    "SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS",
+    DEFAULT_INITIAL_TARGET_RETRY_MAX_DELAY_MS
+  )
+  if (initialTargetRetryMaxDelayMs < initialTargetRetryDelayMs) {
+    throw new Error("SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS must be greater than or equal to SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS")
+  }
+
+  const reverseToken = env.SOCKETDUCT_REVERSE_TOKEN?.trim()
+  if (mode === "reverse-gateway" && reverseToken !== undefined && PLACEHOLDER_TOKENS.has(reverseToken.toLowerCase())) throw new Error("SOCKETDUCT_REVERSE_TOKEN must not be a placeholder token")
+  const reverseClientCertFile = env.SOCKETDUCT_REVERSE_HUB_CLIENT_CERT_FILE?.trim() || undefined
+  const reverseClientKeyFile = env.SOCKETDUCT_REVERSE_HUB_CLIENT_KEY_FILE?.trim() || undefined
+  if (mode === "reverse-gateway" && (reverseClientCertFile === undefined) !== (reverseClientKeyFile === undefined)) throw new Error("SOCKETDUCT_REVERSE_HUB_CLIENT_CERT_FILE and SOCKETDUCT_REVERSE_HUB_CLIENT_KEY_FILE must both be set")
+  const reverseHubTls = {
+    ...(env.SOCKETDUCT_REVERSE_HUB_CA_FILE?.trim() ? {caFile: env.SOCKETDUCT_REVERSE_HUB_CA_FILE.trim()} : {}),
+    ...(reverseClientCertFile === undefined ? {} : {certFile: reverseClientCertFile, keyFile: /** @type {string} */ (reverseClientKeyFile)}),
+    ...(env.SOCKETDUCT_REVERSE_HUB_SERVERNAME?.trim() ? {servername: env.SOCKETDUCT_REVERSE_HUB_SERVERNAME.trim()} : {})
+  }
+  const logDirectory = env.SOCKETDUCT_LOG_DIRECTORY?.trim() || undefined
+  let fileLogging
+  if (logDirectory !== undefined) {
+    const maxFileBytes = parsePositiveInteger(env.SOCKETDUCT_LOG_MAX_FILE_BYTES, "SOCKETDUCT_LOG_MAX_FILE_BYTES", DEFAULT_LOG_MAX_FILE_BYTES)
+    if (!Number.isSafeInteger(maxFileBytes) || maxFileBytes < MIN_LOG_MAX_FILE_BYTES) throw new Error(`SOCKETDUCT_LOG_MAX_FILE_BYTES must be a safe integer of at least ${MIN_LOG_MAX_FILE_BYTES}`)
+    const maxFiles = parsePositiveInteger(env.SOCKETDUCT_LOG_MAX_FILES, "SOCKETDUCT_LOG_MAX_FILES", DEFAULT_LOG_MAX_FILES)
+    if (maxFiles > MAX_LOG_FILES) throw new Error(`SOCKETDUCT_LOG_MAX_FILES must be no greater than ${MAX_LOG_FILES}`)
+    fileLogging = {directory: logDirectory, maxFileBytes, maxFiles}
+  }
+
+  return {
+    mode,
+    relayHost: env.SOCKETDUCT_RELAY_HOST ?? DEFAULT_RELAY_HOST,
+    relayPort: parsePort(env.SOCKETDUCT_RELAY_PORT, "SOCKETDUCT_RELAY_PORT", DEFAULT_RELAY_PORT),
+    resumeWindowMs: parsePositiveInteger(
+      env.SOCKETDUCT_RESUME_WINDOW_MS,
+      "SOCKETDUCT_RESUME_WINDOW_MS",
+      DEFAULT_RESUME_WINDOW_MS
+    ),
+    maxTargetBufferBytes: parsePositiveInteger(
+      env.SOCKETDUCT_MAX_TARGET_BUFFER_BYTES,
+      "SOCKETDUCT_MAX_TARGET_BUFFER_BYTES",
+      DEFAULT_MAX_TARGET_BUFFER_BYTES
+    ),
+    maxTotalBufferBytes: parsePositiveInteger(
+      env.SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES,
+      "SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES",
+      DEFAULT_MAX_TOTAL_BUFFER_BYTES
+    ),
+    initialTargetRetryDelayMs,
+    initialTargetRetryMaxDelayMs,
+    initialTargetConnectTimeoutMs: parsePositiveInteger(
+      env.SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS,
+      "SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS",
+      DEFAULT_INITIAL_TARGET_CONNECT_TIMEOUT_MS
+    ),
+    handshakeTimeoutMs: parsePositiveInteger(
+      env.SOCKETDUCT_HANDSHAKE_TIMEOUT_MS,
+      "SOCKETDUCT_HANDSHAKE_TIMEOUT_MS",
+      DEFAULT_HANDSHAKE_TIMEOUT_MS
+    ),
+    maxInputBytesPerConnection: parsePositiveInteger(
+      env.SOCKETDUCT_MAX_INPUT_BYTES_PER_CONNECTION,
+      "SOCKETDUCT_MAX_INPUT_BYTES_PER_CONNECTION",
+      DEFAULT_MAX_INPUT_BYTES_PER_CONNECTION
+    ),
+    statusIntervalMs: parseNonNegativeInteger(
+      env.SOCKETDUCT_STATUS_INTERVAL_MS,
+      "SOCKETDUCT_STATUS_INTERVAL_MS",
+      DEFAULT_STATUS_INTERVAL_MS
+    ),
+    ...(fileLogging === undefined ? {} : {fileLogging}),
+    compression,
+    protocolVersion,
+    minCompressBytes: parsePositiveInteger(
+      env.SOCKETDUCT_MIN_COMPRESS_BYTES,
+      "SOCKETDUCT_MIN_COMPRESS_BYTES",
+      DEFAULT_MIN_COMPRESS_BYTES
+    ),
+    maxDecompressedBytes: parsePositiveInteger(
+      env.SOCKETDUCT_MAX_DECOMPRESSED_BYTES,
+      "SOCKETDUCT_MAX_DECOMPRESSED_BYTES",
+      DEFAULT_MAX_DECOMPRESSED_BYTES
+    ),
+    maxExpansionRatio: parsePositiveInteger(
+      env.SOCKETDUCT_MAX_EXPANSION_RATIO,
+      "SOCKETDUCT_MAX_EXPANSION_RATIO",
+      DEFAULT_MAX_EXPANSION_RATIO
+    ),
+    authTokens: parseAuthTokens(envValue(env, "SOCKETDUCT_AUTH_TOKENS", "SEAMLINE_AUTH_TOKENS") ?? ""),
+    targetAllowlist: parseTargetAllowlist(envValue(env, "SOCKETDUCT_TARGET_ALLOWLIST", "SEAMLINE_TARGET_ALLOWLIST") ?? ""),
+    allowInsecurePublic: parseInsecurePublic(env.SOCKETDUCT_ALLOW_INSECURE_PUBLIC),
+    ...(relayTls !== undefined ? {relayTls} : {}),
+    ...(mode === "reverse-hub" ? {
+      reverseGatewayBindings: parseReverseGatewayBindings(env.SOCKETDUCT_REVERSE_GATEWAY_BINDINGS ?? ""),
+      reverseRoutes: parseReverseRoutes(env.SOCKETDUCT_REVERSE_ROUTES ?? "")
+    } : {}),
+    ...(mode === "reverse-gateway" ? {
+      reverseGatewayId: env.SOCKETDUCT_REVERSE_GATEWAY_ID?.trim() ?? "",
+      reverseConnectionId: env.SOCKETDUCT_REVERSE_CONNECTION_ID?.trim() ?? "",
+      reverseHub: {
+        host: env.SOCKETDUCT_REVERSE_HUB_HOST?.trim() ?? "",
+        port: parsePort(env.SOCKETDUCT_REVERSE_HUB_PORT, "SOCKETDUCT_REVERSE_HUB_PORT", DEFAULT_RELAY_PORT),
+        token: reverseToken ?? ""
+      },
+      reverseHubTls
+    } : {})
+  }
+}
+
+/**
+ * @param {string} value - Comma-separated gatewayId:username bindings.
+ * @returns {Array<{gatewayId: string, username: string}>} Bindings.
+ */
+function parseReverseGatewayBindings(value) {
+  return splitList(value).map((entry) => {
+    const fields = entry.split(":")
+    if (fields.length !== 2 || fields.some((field) => field.length === 0)) throw new Error("SOCKETDUCT_REVERSE_GATEWAY_BINDINGS entries must use gatewayId:username")
+    return {gatewayId: /** @type {string} */ (fields[0]), username: /** @type {string} */ (fields[1])}
+  })
+}
+
+/**
+ * @param {string} value - Comma-separated username:gatewayId:host:port routes.
+ * @returns {Array<{username: string, gatewayId: string, host: string, port: number}>} Routes.
+ */
+function parseReverseRoutes(value) {
+  return splitList(value).map((entry) => {
+    const first = entry.indexOf(":")
+    const second = entry.indexOf(":", first + 1)
+    const last = entry.lastIndexOf(":")
+    if (first <= 0 || second <= first + 1 || last <= second + 1 || last === entry.length - 1) throw new Error("SOCKETDUCT_REVERSE_ROUTES entries must use username:gatewayId:host:port")
+    return {
+      username: entry.slice(0, first),
+      gatewayId: entry.slice(first + 1, second),
+      host: entry.slice(second + 1, last),
+      port: parsePort(entry.slice(last + 1), "SOCKETDUCT_REVERSE_ROUTES port", DEFAULT_RELAY_PORT)
+    }
+  })
+}
+
+/**
+ * @param {string | undefined} value - Raw version.
+ * @returns {2 | 3} Selected protocol version.
+ */
+function parseProtocolVersion(value) {
+  if (value === undefined || value === "") return 2
+  const parsed = Number(value)
+  if (!SUPPORTED_PROTOCOL_VERSIONS.has(parsed)) throw new Error("SOCKETDUCT_PROTOCOL_VERSION must be 2 or 3")
+  return /** @type {2 | 3} */ (parsed)
+}
+
+/**
+ * @param {Record<string, string | undefined>} env - Process environment.
+ * @param {string} primaryName - Preferred environment variable name.
+ * @param {string} legacyName - Legacy environment variable name accepted during rename migration.
+ * @returns {string | undefined} Environment value.
+ */
+function envValue(env, primaryName, legacyName) {
+  return env[primaryName] ?? env[legacyName]
+}
+
+/**
+ * @param {string | undefined} value - Raw value.
+ * @param {string} name - Environment variable name.
+ * @param {number} defaultValue - Default value.
+ * @returns {number} Parsed port.
+ */
+function parsePort(value, name, defaultValue) {
+  const parsed = parsePositiveInteger(value, name, defaultValue)
+  if (parsed > 65_535) {
+    throw new Error(`${name} must be a TCP port from 1 to 65535`)
+  }
+  return parsed
+}
+
+/**
+ * @param {string | undefined} value - Raw value.
+ * @param {string} name - Environment variable name.
+ * @param {number} defaultValue - Default value.
+ * @returns {number} Parsed positive integer.
+ */
+function parsePositiveInteger(value, name, defaultValue) {
+  if (value === undefined || value === "") {
+    return defaultValue
+  }
+
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${name} must be a positive integer`)
+  }
+  return parsed
+}
+
+/**
+ * @param {string | undefined} value - Raw value.
+ * @param {string} name - Environment variable name.
+ * @param {number} defaultValue - Default value.
+ * @returns {number} Parsed non-negative integer.
+ */
+function parseNonNegativeInteger(value, name, defaultValue) {
+  if (value === undefined || value === "") return defaultValue
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${name} must be a non-negative integer`)
+  }
+  return parsed
+}
+
+/**
+ * @param {string} value - Comma-separated username:token entries.
+ * @returns {StaticTokenConfig[]} Parsed static tokens.
+ */
+function parseAuthTokens(value) {
+  return splitList(value).map((entry) => {
+    const separator = entry.indexOf(":")
+    if (separator <= 0 || separator === entry.length - 1) {
+      throw new Error("SOCKETDUCT_AUTH_TOKENS entries must use username:token")
+    }
+
+    const token = entry.slice(separator + 1)
+    if (PLACEHOLDER_TOKENS.has(token.toLowerCase())) {
+      throw new Error("SOCKETDUCT_AUTH_TOKENS must not contain placeholder tokens")
+    }
+
+    return {
+      username: entry.slice(0, separator),
+      token
+    }
+  })
+}
+
+/**
+ * @param {string} value - Comma-separated host:port entries.
+ * @returns {TargetEndpoint[]} Parsed target allowlist.
+ */
+function parseTargetAllowlist(value) {
+  return splitList(value).map((entry) => {
+    const separator = entry.lastIndexOf(":")
+    if (separator <= 0 || separator === entry.length - 1) {
+      throw new Error("SOCKETDUCT_TARGET_ALLOWLIST entries must use host:port")
+    }
+
+    return {
+      host: entry.slice(0, separator),
+      port: parsePort(entry.slice(separator + 1), "SOCKETDUCT_TARGET_ALLOWLIST port", DEFAULT_RELAY_PORT)
+    }
+  })
+}
+
+/**
+ * @param {string} value - Comma-separated values.
+ * @returns {string[]} Trimmed non-empty entries.
+ */
+function splitList(value) {
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+}
+
+/**
+ * @param {string | undefined} value - Raw environment value.
+ * @returns {boolean} - True only for allowed insecure-public values.
+ */
+function parseInsecurePublic(value) {
+  if (value === undefined || value === "") {
+    return false
+  }
+  const normalised = value.trim().toLowerCase()
+  if (normalised === "1" || normalised === "true") {
+    return true
+  }
+  throw new Error("SOCKETDUCT_ALLOW_INSECURE_PUBLIC must be 1 or true when set")
+}
+
+/**
+ * @param {string} host - Listen host.
+ * @returns {boolean} - True if the host is a loopback address.
+ */
+export function isLoopbackHost(host) {
+  const lower = host.toLowerCase()
+  if (lower === "localhost" || lower === LOOPBACK_V6_ADDRESS || lower === "[::1]") {
+    return true
+  }
+  return isIP(lower) === 4 && lower.startsWith("127.")
+}