socketduct 0.1.25 → 0.1.26

package/test/unit/config/environment.test.js

@@ -1,578 +1,558 @@
-import assert from "node:assert/strict"
-import test from "node:test"
+import {describe, expect, it} from "@velocious/testing"
 
 import {isLoopbackHost, loadEnvironmentConfig} from "../../../src/config/environment.js"
 
-test("loadEnvironmentConfig parses relay Docker environment", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_RELAY_HOST: "0.0.0.0",
-    SOCKETDUCT_RELAY_PORT: "3100",
-    SOCKETDUCT_RESUME_WINDOW_MS: "45000",
-    SOCKETDUCT_AUTH_TOKENS: "edge:token-one,backup:token-two",
-    SOCKETDUCT_TARGET_ALLOWLIST: "tensorbuzz.internal:443,127.0.0.1:8080"
-  })
-
-  assert.deepEqual(config, {
-    mode: "relay",
-    relayHost: "0.0.0.0",
-    relayPort: 3100,
-    resumeWindowMs: 45000,
-    maxTargetBufferBytes: 1_048_576,
-    maxTotalBufferBytes: 16_777_216,
-    initialTargetRetryDelayMs: 250,
-    initialTargetRetryMaxDelayMs: 5_000,
-    initialTargetConnectTimeoutMs: 10_000,
-    handshakeTimeoutMs: 10_000,
-    maxInputBytesPerConnection: 65_536,
-    statusIntervalMs: 30_000,
-    compression: "auto",
-    protocolVersion: 2,
-    minCompressBytes: 256,
-    maxDecompressedBytes: 16_777_216,
-    maxExpansionRatio: 1000,
-    authTokens: [
-      {username: "edge", token: "token-one"},
-      {username: "backup", token: "token-two"}
-    ],
-    targetAllowlist: [
-      {host: "tensorbuzz.internal", port: 443},
-      {host: "127.0.0.1", port: 8080}
-    ],
-    allowInsecurePublic: false
-  })
-})
-
-test("loadEnvironmentConfig accepts legacy Seamline relay secrets during migration", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "relay",
-    SEAMLINE_AUTH_TOKENS: "edge:legacy-token",
-    SEAMLINE_TARGET_ALLOWLIST: "docker-socket-shim:2375"
+describe("environment config", () => {
+  it("loadEnvironmentConfig parses relay Docker environment", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "relay",
+      SOCKETDUCT_RELAY_HOST: "0.0.0.0",
+      SOCKETDUCT_RELAY_PORT: "3100",
+      SOCKETDUCT_RESUME_WINDOW_MS: "45000",
+      SOCKETDUCT_AUTH_TOKENS: "edge:token-one,backup:token-two",
+      SOCKETDUCT_TARGET_ALLOWLIST: "tensorbuzz.internal:443,127.0.0.1:8080"
+    })
+
+    expect(config).toEqual({
+      mode: "relay",
+      relayHost: "0.0.0.0",
+      relayPort: 3100,
+      resumeWindowMs: 45000,
+      maxTargetBufferBytes: 1_048_576,
+      maxTotalBufferBytes: 16_777_216,
+      initialTargetRetryDelayMs: 250,
+      initialTargetRetryMaxDelayMs: 5_000,
+      initialTargetConnectTimeoutMs: 10_000,
+      handshakeTimeoutMs: 10_000,
+      maxInputBytesPerConnection: 65_536,
+      statusIntervalMs: 30_000,
+      compression: "auto",
+      protocolVersion: 2,
+      minCompressBytes: 256,
+      maxDecompressedBytes: 16_777_216,
+      maxExpansionRatio: 1000,
+      authTokens: [
+        {username: "edge", token: "token-one"},
+        {username: "backup", token: "token-two"}
+      ],
+      targetAllowlist: [
+        {host: "tensorbuzz.internal", port: 443},
+        {host: "127.0.0.1", port: 8080}
+      ],
+      allowInsecurePublic: false
+    })
   })
 
-  assert.deepEqual(config.authTokens, [{username: "edge", token: "legacy-token"}])
-  assert.deepEqual(config.targetAllowlist, [{host: "docker-socket-shim", port: 2375}])
-})
+  it("loadEnvironmentConfig accepts legacy Seamline relay secrets during migration", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "relay",
+      SEAMLINE_AUTH_TOKENS: "edge:legacy-token",
+      SEAMLINE_TARGET_ALLOWLIST: "docker-socket-shim:2375"
+    })
 
-test("loadEnvironmentConfig prefers Socketduct relay secrets over legacy Seamline aliases", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_AUTH_TOKENS: "edge:new-token",
-    SOCKETDUCT_TARGET_ALLOWLIST: "docker-socket-shim:2375",
-    SEAMLINE_AUTH_TOKENS: "edge:legacy-token",
-    SEAMLINE_TARGET_ALLOWLIST: "legacy-docker:2375"
+    expect(config.authTokens).toEqual([{username: "edge", token: "legacy-token"}])
+    expect(config.targetAllowlist).toEqual([{host: "docker-socket-shim", port: 2375}])
   })
 
-  assert.deepEqual(config.authTokens, [{username: "edge", token: "new-token"}])
-  assert.deepEqual(config.targetAllowlist, [{host: "docker-socket-shim", port: 2375}])
-})
-
-test("loadEnvironmentConfig rejects malformed ports and list entries", () => {
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_RELAY_PORT: "0"}), /positive integer/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_RELAY_PORT: "70000"}), /TCP port/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_AUTH_TOKENS: "missing-token"}), /username:token/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_TARGET_ALLOWLIST: "missing-port"}), /host:port/)
-})
-
-test("loadEnvironmentConfig parses or disables the status interval", () => {
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_STATUS_INTERVAL_MS: "45000"}).statusIntervalMs, 45_000)
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_STATUS_INTERVAL_MS: "0"}).statusIntervalMs, 0)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_STATUS_INTERVAL_MS: "-1"}), /non-negative integer/)
-})
+  it("loadEnvironmentConfig prefers Socketduct relay secrets over legacy Seamline aliases", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_AUTH_TOKENS: "edge:new-token",
+      SOCKETDUCT_TARGET_ALLOWLIST: "docker-socket-shim:2375",
+      SEAMLINE_AUTH_TOKENS: "edge:legacy-token",
+      SEAMLINE_TARGET_ALLOWLIST: "legacy-docker:2375"
+    })
 
-test("loadEnvironmentConfig keeps persistent logging disabled by default and parses compressed bounds", () => {
-  assert.equal(loadEnvironmentConfig({}).fileLogging, undefined)
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_LOG_DIRECTORY: "   "}).fileLogging, undefined)
-  assert.deepEqual(loadEnvironmentConfig({
-    SOCKETDUCT_LOG_DIRECTORY: "  /var/log/socketduct  ",
-    SOCKETDUCT_LOG_FRAME_MAX_BYTES: "2097152",
-    SOCKETDUCT_LOG_FLUSH_INTERVAL_MS: "1500",
-    SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS: "200",
-    SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "268435456",
-    SOCKETDUCT_LOG_RETENTION_DAYS: "14",
-    SOCKETDUCT_LOG_RETENTION_MAX_BYTES: "3221225472",
-    SOCKETDUCT_LOG_QUEUE_MAX_BYTES: "33554432",
-    SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES: "4194304",
-    SOCKETDUCT_LOG_COMPRESSION_LEVEL: "18"
-  }).fileLogging, {
-    directory: "/var/log/socketduct",
-    frameMaxBytes: 2_097_152,
-    flushIntervalMs: 1_500,
-    criticalFlushIntervalMs: 200,
-    maxSegmentBytes: 268_435_456,
-    retentionDays: 14,
-    retentionBytes: 3_221_225_472,
-    maxQueueBytes: 33_554_432,
-    criticalReserveBytes: 4_194_304,
-    compressionLevel: 18
+    expect(config.authTokens).toEqual([{username: "edge", token: "new-token"}])
+    expect(config.targetAllowlist).toEqual([{host: "docker-socket-shim", port: 2375}])
   })
-})
-
-test("loadEnvironmentConfig rejects unsafe compressed logging bounds", () => {
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_FRAME_MAX_BYTES: "100"
-  }), /SOCKETDUCT_LOG_FRAME_MAX_BYTES/)
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_COMPRESSION_LEVEL: "23"
-  }), /SOCKETDUCT_LOG_COMPRESSION_LEVEL/)
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_QUEUE_MAX_BYTES: "1024",
-    SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES: "1024"
-  }), /SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES/)
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "5368709120",
-    SOCKETDUCT_LOG_RETENTION_MAX_BYTES: "4294967296"
-  }), /SOCKETDUCT_LOG_SEGMENT_MAX_BYTES/)
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_MAX_FILE_BYTES: "10485760"
-  }), /SOCKETDUCT_LOG_MAX_FILE_BYTES/)
-})
 
-test("loadEnvironmentConfig accepts a paired hub-only fingerprint key and epoch", () => {
-  const encodedKey = Buffer.alloc(32, 0x5a).toString("base64url")
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "reverse-hub",
-    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: encodedKey,
-    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "hub-2026-09"
-  })
-  assert.deepEqual(config.connectionFingerprint, {key: Buffer.alloc(32, 0x5a), keyEpoch: "hub-2026-09"})
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "reverse-hub",
-    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct"
-  }), /SOCKETDUCT_CONNECTION_FINGERPRINT_KEY/)
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "reverse-gateway",
-    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: encodedKey,
-    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "hub-2026-09"
-  }), /hub-only/)
-})
-
-test("loadEnvironmentConfig selects v3 explicitly and keeps v2 as rollback default", () => {
-  assert.equal(loadEnvironmentConfig({}).protocolVersion, 2)
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_PROTOCOL_VERSION: "3"}).protocolVersion, 3)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_PROTOCOL_VERSION: "1"}), /must be 2 or 3/)
-})
+  it("loadEnvironmentConfig rejects malformed ports and list entries", () => {
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_RELAY_PORT: "0"})).toThrow(/positive integer/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_RELAY_PORT: "70000"})).toThrow(/TCP port/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_AUTH_TOKENS: "missing-token"})).toThrow(/username:token/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_TARGET_ALLOWLIST: "missing-port"})).toThrow(/host:port/)
+  })
 
-test("loadEnvironmentConfig rejects placeholder auth tokens", () => {
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:replace-with-generated-token",
-      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
-    }),
-    /placeholder/
-  )
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:paste-generated-token-here",
-      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
-    }),
-    /placeholder/
-  )
-})
+  it("loadEnvironmentConfig parses or disables the status interval", () => {
+    expect(loadEnvironmentConfig({SOCKETDUCT_STATUS_INTERVAL_MS: "45000"}).statusIntervalMs).toBe(45_000)
+    expect(loadEnvironmentConfig({SOCKETDUCT_STATUS_INTERVAL_MS: "0"}).statusIntervalMs).toBe(0)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_STATUS_INTERVAL_MS: "-1"})).toThrow(/non-negative integer/)
+  })
 
-test("loadEnvironmentConfig parses TLS cert/key as an atomic pair", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt",
-    SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key"
+  it("loadEnvironmentConfig keeps persistent logging disabled by default and parses compressed bounds", () => {
+    expect(loadEnvironmentConfig({}).fileLogging).toBeUndefined()
+    expect(loadEnvironmentConfig({SOCKETDUCT_LOG_DIRECTORY: "   "}).fileLogging).toBeUndefined()
+    expect(loadEnvironmentConfig({
+      SOCKETDUCT_LOG_DIRECTORY: "  /var/log/socketduct  ",
+      SOCKETDUCT_LOG_FRAME_MAX_BYTES: "2097152",
+      SOCKETDUCT_LOG_FLUSH_INTERVAL_MS: "1500",
+      SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS: "200",
+      SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "268435456",
+      SOCKETDUCT_LOG_RETENTION_DAYS: "14",
+      SOCKETDUCT_LOG_RETENTION_MAX_BYTES: "3221225472",
+      SOCKETDUCT_LOG_QUEUE_MAX_BYTES: "33554432",
+      SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES: "4194304",
+      SOCKETDUCT_LOG_COMPRESSION_LEVEL: "18"
+    }).fileLogging).toEqual({
+      directory: "/var/log/socketduct",
+      frameMaxBytes: 2_097_152,
+      flushIntervalMs: 1_500,
+      criticalFlushIntervalMs: 200,
+      maxSegmentBytes: 268_435_456,
+      retentionDays: 14,
+      retentionBytes: 3_221_225_472,
+      maxQueueBytes: 33_554_432,
+      criticalReserveBytes: 4_194_304,
+      compressionLevel: 18
+    })
   })
 
-  assert.deepEqual(config.relayTls, {
-    certFile: "/certs/relay.crt",
-    keyFile: "/certs/relay.key"
+  it("loadEnvironmentConfig rejects unsafe compressed logging bounds", () => {
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+      SOCKETDUCT_LOG_FRAME_MAX_BYTES: "100"
+    })).toThrow(/SOCKETDUCT_LOG_FRAME_MAX_BYTES/)
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+      SOCKETDUCT_LOG_COMPRESSION_LEVEL: "23"
+    })).toThrow(/SOCKETDUCT_LOG_COMPRESSION_LEVEL/)
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+      SOCKETDUCT_LOG_QUEUE_MAX_BYTES: "1024",
+      SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES: "1024"
+    })).toThrow(/SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES/)
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+      SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "5368709120",
+      SOCKETDUCT_LOG_RETENTION_MAX_BYTES: "4294967296"
+    })).toThrow(/SOCKETDUCT_LOG_SEGMENT_MAX_BYTES/)
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+      SOCKETDUCT_LOG_MAX_FILE_BYTES: "10485760"
+    })).toThrow(/SOCKETDUCT_LOG_MAX_FILE_BYTES/)
   })
-})
 
-test("loadEnvironmentConfig parses optional client CA for mTLS", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt",
-    SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key",
-    SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt"
+  it("loadEnvironmentConfig accepts a paired hub-only fingerprint key and epoch", () => {
+    const encodedKey = Buffer.alloc(32, 0x5a).toString("base64url")
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "reverse-hub",
+      SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+      SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: encodedKey,
+      SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "hub-2026-09"
+    })
+    expect(config.connectionFingerprint?.key.equals(Buffer.alloc(32, 0x5a))).toBe(true)
+    expect(config.connectionFingerprint?.keyEpoch).toBe("hub-2026-09")
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "reverse-hub",
+      SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct"
+    })).toThrow(/SOCKETDUCT_CONNECTION_FINGERPRINT_KEY/)
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "reverse-gateway",
+      SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: encodedKey,
+      SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "hub-2026-09"
+    })).toThrow(/hub-only/)
   })
 
-  assert.deepEqual(config.relayTls, {
-    certFile: "/certs/relay.crt",
-    keyFile: "/certs/relay.key",
-    clientCaFile: "/certs/client-ca.crt"
+  it("loadEnvironmentConfig selects v3 explicitly and keeps v2 as rollback default", () => {
+    expect(loadEnvironmentConfig({}).protocolVersion).toBe(2)
+    expect(loadEnvironmentConfig({SOCKETDUCT_PROTOCOL_VERSION: "3"}).protocolVersion).toBe(3)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_PROTOCOL_VERSION: "1"})).toThrow(/must be 2 or 3/)
   })
-})
 
-test("loadEnvironmentConfig returns undefined relayTls when no TLS vars are set", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_AUTH_TOKENS: "edge:token",
-    SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
+  it("loadEnvironmentConfig rejects placeholder auth tokens", () => {
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:replace-with-generated-token",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
+      })
+    ).toThrow(/placeholder/)
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_AUTH_TOKENS: "tensorbuzz-edge:paste-generated-token-here",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
+      })
+    ).toThrow(/placeholder/)
   })
 
-  assert.equal(config.relayTls, undefined)
-})
+  it("loadEnvironmentConfig parses TLS cert/key as an atomic pair", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt",
+      SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key"
+    })
 
-test("loadEnvironmentConfig rejects TLS cert without key", () => {
-  assert.throws(
-    () => loadEnvironmentConfig({SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt"}),
-    /atomic pair/
-  )
-  assert.throws(
-    () => loadEnvironmentConfig({SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key"}),
-    /atomic pair/
-  )
-})
+    expect(config.relayTls).toEqual({
+      certFile: "/certs/relay.crt",
+      keyFile: "/certs/relay.key"
+    })
+  })
 
-test("loadEnvironmentConfig trims whitespace from TLS file paths", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_TLS_CERT_FILE: "  /certs/relay.crt  ",
-    SOCKETDUCT_TLS_KEY_FILE: "  /certs/relay.key  "
+  it("loadEnvironmentConfig parses optional client CA for mTLS", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt",
+      SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key",
+      SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt"
+    })
+
+    expect(config.relayTls).toEqual({
+      certFile: "/certs/relay.crt",
+      keyFile: "/certs/relay.key",
+      clientCaFile: "/certs/client-ca.crt"
+    })
   })
 
-  assert.deepEqual(config.relayTls, {
-    certFile: "/certs/relay.crt",
-    keyFile: "/certs/relay.key"
+  it("loadEnvironmentConfig returns undefined relayTls when no TLS vars are set", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_AUTH_TOKENS: "edge:token",
+      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:443"
+    })
+
+    expect(config.relayTls).toBeUndefined()
   })
-})
 
-test("loadEnvironmentConfig parses SOCKETDUCT_ALLOW_INSECURE_PUBLIC valid values", () => {
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "1"}).allowInsecurePublic, true)
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "true"}).allowInsecurePublic, true)
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "  true  "}).allowInsecurePublic, true)
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: ""}).allowInsecurePublic, false)
-  assert.equal(loadEnvironmentConfig({}).allowInsecurePublic, false)
-})
+  it("loadEnvironmentConfig rejects TLS cert without key", () => {
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt"})
+    ).toThrow(/atomic pair/)
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key"})
+    ).toThrow(/atomic pair/)
+  })
 
-test("loadEnvironmentConfig rejects invalid SOCKETDUCT_ALLOW_INSECURE_PUBLIC values", () => {
-  assert.throws(
-    () => loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "yes"}),
-    /SOCKETDUCT_ALLOW_INSECURE_PUBLIC/
-  )
-  assert.throws(
-    () => loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "0"}),
-    /SOCKETDUCT_ALLOW_INSECURE_PUBLIC/
-  )
-  assert.throws(
-    () => loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "false"}),
-    /SOCKETDUCT_ALLOW_INSECURE_PUBLIC/
-  )
-})
+  it("loadEnvironmentConfig trims whitespace from TLS file paths", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_TLS_CERT_FILE: "  /certs/relay.crt  ",
+      SOCKETDUCT_TLS_KEY_FILE: "  /certs/relay.key  "
+    })
 
-test("loadEnvironmentConfig rejects client CA without cert/key pair", () => {
-  assert.throws(
-    () => loadEnvironmentConfig({SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt"}),
-    /SOCKETDUCT_TLS_CLIENT_CA_FILE/
-  )
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt",
-      SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt"
-    }),
-    /SOCKETDUCT_TLS_CLIENT_CA_FILE/
-  )
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt",
-      SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key"
-    }),
-    /SOCKETDUCT_TLS_CLIENT_CA_FILE/
-  )
-})
+    expect(config.relayTls).toEqual({
+      certFile: "/certs/relay.crt",
+      keyFile: "/certs/relay.key"
+    })
+  })
 
-test("isLoopbackHost identifies loopback addresses", () => {
-  assert.equal(isLoopbackHost("127.0.0.1"), true)
-  assert.equal(isLoopbackHost("127.0.0.2"), true)
-  assert.equal(isLoopbackHost("127.255.255.255"), true)
-  assert.equal(isLoopbackHost("localhost"), true)
-  assert.equal(isLoopbackHost("::1"), true)
-  assert.equal(isLoopbackHost("[::1]"), true)
-})
+  it("loadEnvironmentConfig parses SOCKETDUCT_ALLOW_INSECURE_PUBLIC valid values", () => {
+    expect(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "1"}).allowInsecurePublic).toBe(true)
+    expect(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "true"}).allowInsecurePublic).toBe(true)
+    expect(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "  true  "}).allowInsecurePublic).toBe(true)
+    expect(loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: ""}).allowInsecurePublic).toBe(false)
+    expect(loadEnvironmentConfig({}).allowInsecurePublic).toBe(false)
+  })
 
-test("isLoopbackHost rejects non-loopback addresses", () => {
-  assert.equal(isLoopbackHost("0.0.0.0"), false)
-  assert.equal(isLoopbackHost("192.168.1.1"), false)
-  assert.equal(isLoopbackHost("10.0.0.1"), false)
-  assert.equal(isLoopbackHost("172.16.0.1"), false)
-  assert.equal(isLoopbackHost("::ffff:127.0.0.1"), false)
-})
+  it("loadEnvironmentConfig rejects invalid SOCKETDUCT_ALLOW_INSECURE_PUBLIC values", () => {
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "yes"})
+    ).toThrow(/SOCKETDUCT_ALLOW_INSECURE_PUBLIC/)
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "0"})
+    ).toThrow(/SOCKETDUCT_ALLOW_INSECURE_PUBLIC/)
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_ALLOW_INSECURE_PUBLIC: "false"})
+    ).toThrow(/SOCKETDUCT_ALLOW_INSECURE_PUBLIC/)
+  })
 
-test("loadEnvironmentConfig parses reverse hub identity bindings, exact routes, and route-class routes", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "reverse-hub",
-    SOCKETDUCT_AUTH_TOKENS: "home-o2:gateway-token,tensorbuzz:client-token",
-    SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2,zyxel:home-zyxel",
-    SOCKETDUCT_REVERSE_ROUTES: "tensorbuzz:o2:docker-server:2375,tensorbuzz:zyxel:docker-server:2375",
-    SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: "tensorbuzz:starlink:o2:docker-a:2375,tensorbuzz:starlink:zyxel:docker-b:2375",
-    SOCKETDUCT_TLS_CERT_FILE: "/certs/hub.crt",
-    SOCKETDUCT_TLS_KEY_FILE: "/certs/hub.key"
-  })
-  assert.equal(config.mode, "reverse-hub")
-  assert.deepEqual(config.reverseGatewayBindings, [{gatewayId: "o2", username: "home-o2"}, {gatewayId: "zyxel", username: "home-zyxel"}])
-  assert.deepEqual(config.reverseRoutes, [
-    {username: "tensorbuzz", gatewayId: "o2", host: "docker-server", port: 2375},
-    {username: "tensorbuzz", gatewayId: "zyxel", host: "docker-server", port: 2375}
-  ])
-  assert.deepEqual(config.reverseRouteClassRoutes, [
-    {username: "tensorbuzz", routeClass: "starlink", gatewayId: "o2", host: "docker-a", port: 2375},
-    {username: "tensorbuzz", routeClass: "starlink", gatewayId: "zyxel", host: "docker-b", port: 2375}
-  ])
-})
+  it("loadEnvironmentConfig rejects client CA without cert/key pair", () => {
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt"})
+    ).toThrow(/SOCKETDUCT_TLS_CLIENT_CA_FILE/)
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt",
+        SOCKETDUCT_TLS_CERT_FILE: "/certs/relay.crt"
+      })
+    ).toThrow(/SOCKETDUCT_TLS_CLIENT_CA_FILE/)
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_TLS_CLIENT_CA_FILE: "/certs/client-ca.crt",
+        SOCKETDUCT_TLS_KEY_FILE: "/certs/relay.key"
+      })
+    ).toThrow(/SOCKETDUCT_TLS_CLIENT_CA_FILE/)
+  })
 
-test("loadEnvironmentConfig parses outbound reverse gateway verified TLS settings", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "reverse-gateway",
-    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
-    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
-    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
-    SOCKETDUCT_REVERSE_HUB_PORT: "443",
-    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
-    SOCKETDUCT_REVERSE_HUB_CA_FILE: "/certs/ca.crt",
-    SOCKETDUCT_REVERSE_HUB_CLIENT_CERT_FILE: "/certs/client.crt",
-    SOCKETDUCT_REVERSE_HUB_CLIENT_KEY_FILE: "/certs/client.key",
-    SOCKETDUCT_REVERSE_HUB_SERVERNAME: "server3.example.test",
-    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375"
-  })
-  assert.equal(config.mode, "reverse-gateway")
-  assert.equal(config.reverseGatewayId, "starlink")
-  assert.equal(config.reverseConnectionId, "home_starlink_01")
-  assert.deepEqual(config.reverseHub, {host: "server3.example.test", port: 443, token: "gateway-token"})
-  assert.deepEqual(config.reverseHubTls, {caFile: "/certs/ca.crt", certFile: "/certs/client.crt", keyFile: "/certs/client.key", servername: "server3.example.test"})
-})
+  it("isLoopbackHost identifies loopback addresses", () => {
+    expect(isLoopbackHost("127.0.0.1")).toBe(true)
+    expect(isLoopbackHost("127.0.0.2")).toBe(true)
+    expect(isLoopbackHost("127.255.255.255")).toBe(true)
+    expect(isLoopbackHost("localhost")).toBe(true)
+    expect(isLoopbackHost("::1")).toBe(true)
+    expect(isLoopbackHost("[::1]")).toBe(true)
+  })
 
-test("loadEnvironmentConfig parses the reverse-gateway spool directory", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "reverse-gateway",
-    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
-    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
-    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
-    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
-    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
-    SOCKETDUCT_SPOOL_DIRECTORY: " /spool/reverse-gateway "
-  })
-  assert.equal(config.spoolDirectory, "/spool/reverse-gateway")
-  assert.equal("spoolDirectory" in loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "reverse-gateway",
-    SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
-    SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
-    SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
-    SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
-    SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
-    SOCKETDUCT_SPOOL_DIRECTORY: "   "
-  }), false)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "relay", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_SPOOL_DIRECTORY: "/spool"}), /reverse-gateway-only/)
-})
+  it("isLoopbackHost rejects non-loopback addresses", () => {
+    expect(isLoopbackHost("0.0.0.0")).toBe(false)
+    expect(isLoopbackHost("192.168.1.1")).toBe(false)
+    expect(isLoopbackHost("10.0.0.1")).toBe(false)
+    expect(isLoopbackHost("172.16.0.1")).toBe(false)
+    expect(isLoopbackHost("::ffff:127.0.0.1")).toBe(false)
+  })
 
-test("loadEnvironmentConfig rejects malformed reverse mode policy and credentials", () => {
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "unknown"}), /Unsupported SOCKETDUCT_MODE/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "missing-user"}), /gatewayId:username/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_ROUTES: "too:few:fields"}), /username:gatewayId:host:port/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: "too:few:fields"}), /username:routeClass:gatewayId:host:port/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-gateway", SOCKETDUCT_REVERSE_TOKEN: "replace-me"}), /placeholder/)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-gateway", SOCKETDUCT_REVERSE_HUB_CLIENT_CERT_FILE: "/certs/client.crt"}), /must both be set/)
-})
+  it("loadEnvironmentConfig parses reverse hub identity bindings, exact routes, and route-class routes", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "reverse-hub",
+      SOCKETDUCT_AUTH_TOKENS: "home-o2:gateway-token,tensorbuzz:client-token",
+      SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "o2:home-o2,zyxel:home-zyxel",
+      SOCKETDUCT_REVERSE_ROUTES: "tensorbuzz:o2:docker-server:2375,tensorbuzz:zyxel:docker-server:2375",
+      SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: "tensorbuzz:starlink:o2:docker-a:2375,tensorbuzz:starlink:zyxel:docker-b:2375",
+      SOCKETDUCT_TLS_CERT_FILE: "/certs/hub.crt",
+      SOCKETDUCT_TLS_KEY_FILE: "/certs/hub.key"
+    })
+    expect(config.mode).toBe("reverse-hub")
+    expect(config.reverseGatewayBindings).toEqual([{gatewayId: "o2", username: "home-o2"}, {gatewayId: "zyxel", username: "home-zyxel"}])
+    expect(config.reverseRoutes).toEqual([
+      {username: "tensorbuzz", gatewayId: "o2", host: "docker-server", port: 2375},
+      {username: "tensorbuzz", gatewayId: "zyxel", host: "docker-server", port: 2375}
+    ])
+    expect(config.reverseRouteClassRoutes).toEqual([
+      {username: "tensorbuzz", routeClass: "starlink", gatewayId: "o2", host: "docker-a", port: 2375},
+      {username: "tensorbuzz", routeClass: "starlink", gatewayId: "zyxel", host: "docker-b", port: 2375}
+    ])
+  })
 
-test("isLoopbackHost rejects 127-prefixed hostnames", () => {
-  assert.equal(isLoopbackHost("127.0.0.1.nip.io"), false)
-  assert.equal(isLoopbackHost("127localhost"), false)
-  assert.equal(isLoopbackHost("127anything"), false)
-})
+  it("loadEnvironmentConfig parses outbound reverse gateway verified TLS settings", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "reverse-gateway",
+      SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+      SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+      SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+      SOCKETDUCT_REVERSE_HUB_PORT: "443",
+      SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+      SOCKETDUCT_REVERSE_HUB_CA_FILE: "/certs/ca.crt",
+      SOCKETDUCT_REVERSE_HUB_CLIENT_CERT_FILE: "/certs/client.crt",
+      SOCKETDUCT_REVERSE_HUB_CLIENT_KEY_FILE: "/certs/client.key",
+      SOCKETDUCT_REVERSE_HUB_SERVERNAME: "server3.example.test",
+      SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375"
+    })
+    expect(config.mode).toBe("reverse-gateway")
+    expect(config.reverseGatewayId).toBe("starlink")
+    expect(config.reverseConnectionId).toBe("home_starlink_01")
+    expect(config.reverseHub).toEqual({host: "server3.example.test", port: 443, token: "gateway-token"})
+    expect(config.reverseHubTls).toEqual({caFile: "/certs/ca.crt", certFile: "/certs/client.crt", keyFile: "/certs/client.key", servername: "server3.example.test"})
+  })
 
-test("isLoopbackHost rejects invalid loopback-like IPs", () => {
-  assert.equal(isLoopbackHost("127.0.0."), false)
-  assert.equal(isLoopbackHost("127.0.0"), false)
-  assert.equal(isLoopbackHost("127."), false)
-  assert.equal(isLoopbackHost("127.0.0.0.1"), false)
-})
+  it("loadEnvironmentConfig parses the reverse-gateway spool directory", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "reverse-gateway",
+      SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+      SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+      SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+      SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+      SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+      SOCKETDUCT_SPOOL_DIRECTORY: " /spool/reverse-gateway "
+    })
+    expect(config.spoolDirectory).toBe("/spool/reverse-gateway")
+    expect("spoolDirectory" in loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "reverse-gateway",
+      SOCKETDUCT_REVERSE_GATEWAY_ID: "starlink",
+      SOCKETDUCT_REVERSE_CONNECTION_ID: "home_starlink_01",
+      SOCKETDUCT_REVERSE_HUB_HOST: "server3.example.test",
+      SOCKETDUCT_REVERSE_TOKEN: "gateway-token",
+      SOCKETDUCT_TARGET_ALLOWLIST: "docker-server:2375",
+      SOCKETDUCT_SPOOL_DIRECTORY: "   "
+    })).toBe(false)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "relay", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"})).toThrow(/reverse-gateway-only/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_SPOOL_DIRECTORY: "/spool"})).toThrow(/reverse-gateway-only/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_SPOOL_DIRECTORY: "/spool"})).toThrow(/reverse-gateway-only/)
+  })
 
-test("isLoopbackHost rejects loopback IPs with invalid octets", () => {
-  assert.equal(isLoopbackHost("127.999.999.999"), false)
-  assert.equal(isLoopbackHost("127.256.0.1"), false)
-  assert.equal(isLoopbackHost("127.-1.0.1"), false)
-})
+  it("loadEnvironmentConfig rejects malformed reverse mode policy and credentials", () => {
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "unknown"})).toThrow(/Unsupported SOCKETDUCT_MODE/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_GATEWAY_BINDINGS: "missing-user"})).toThrow(/gatewayId:username/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_ROUTES: "too:few:fields"})).toThrow(/username:gatewayId:host:port/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-hub", SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES: "too:few:fields"})).toThrow(/username:routeClass:gatewayId:host:port/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-gateway", SOCKETDUCT_REVERSE_TOKEN: "replace-me"})).toThrow(/placeholder/)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_MODE: "reverse-gateway", SOCKETDUCT_REVERSE_HUB_CLIENT_CERT_FILE: "/certs/client.crt"})).toThrow(/must both be set/)
+  })
 
-test("loadEnvironmentConfig parses SOCKETDUCT_MAX_TARGET_BUFFER_BYTES and SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_MAX_TARGET_BUFFER_BYTES: "65536",
-    SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES: "262144",
-    SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
-    SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+  it("isLoopbackHost rejects 127-prefixed hostnames", () => {
+    expect(isLoopbackHost("127.0.0.1.nip.io")).toBe(false)
+    expect(isLoopbackHost("127localhost")).toBe(false)
+    expect(isLoopbackHost("127anything")).toBe(false)
   })
 
-  assert.equal(config.maxTargetBufferBytes, 65536)
-  assert.equal(config.maxTotalBufferBytes, 262144)
-})
+  it("isLoopbackHost rejects invalid loopback-like IPs", () => {
+    expect(isLoopbackHost("127.0.0.")).toBe(false)
+    expect(isLoopbackHost("127.0.0")).toBe(false)
+    expect(isLoopbackHost("127.")).toBe(false)
+    expect(isLoopbackHost("127.0.0.0.1")).toBe(false)
+  })
 
-test("loadEnvironmentConfig parses SOCKETDUCT_COMPRESSION and its limits", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_COMPRESSION: "off",
-    SOCKETDUCT_MIN_COMPRESS_BYTES: "1024",
-    SOCKETDUCT_MAX_DECOMPRESSED_BYTES: "65536",
-    SOCKETDUCT_MAX_EXPANSION_RATIO: "50",
-    SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
-    SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
-  })
-
-  assert.equal(config.compression, "off")
-  assert.equal(config.minCompressBytes, 1024)
-  assert.equal(config.maxDecompressedBytes, 65536)
-  assert.equal(config.maxExpansionRatio, 50)
-})
+  it("isLoopbackHost rejects loopback IPs with invalid octets", () => {
+    expect(isLoopbackHost("127.999.999.999")).toBe(false)
+    expect(isLoopbackHost("127.256.0.1")).toBe(false)
+    expect(isLoopbackHost("127.-1.0.1")).toBe(false)
+  })
 
-test("loadEnvironmentConfig rejects an unknown SOCKETDUCT_COMPRESSION instead of silently defaulting", () => {
-  assert.throws(
-    () => loadEnvironmentConfig({
+  it("loadEnvironmentConfig parses SOCKETDUCT_MAX_TARGET_BUFFER_BYTES and SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES", () => {
+    const config = loadEnvironmentConfig({
       SOCKETDUCT_MODE: "relay",
-      SOCKETDUCT_COMPRESSION: "zstd",
+      SOCKETDUCT_MAX_TARGET_BUFFER_BYTES: "65536",
+      SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES: "262144",
       SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
       SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
-    }),
-    /Unsupported SOCKETDUCT_COMPRESSION/
-  )
-})
+    })
 
-test("loadEnvironmentConfig defaults buffer limits when env vars are absent", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
-    SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+    expect(config.maxTargetBufferBytes).toBe(65536)
+    expect(config.maxTotalBufferBytes).toBe(262144)
   })
 
-  assert.equal(config.maxTargetBufferBytes, 1_048_576)
-  assert.equal(config.maxTotalBufferBytes, 16_777_216)
-})
-
-test("loadEnvironmentConfig rejects non-positive buffer limit values", () => {
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_MAX_TARGET_BUFFER_BYTES: "0",
+  it("loadEnvironmentConfig parses SOCKETDUCT_COMPRESSION and its limits", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "relay",
+      SOCKETDUCT_COMPRESSION: "off",
+      SOCKETDUCT_MIN_COMPRESS_BYTES: "1024",
+      SOCKETDUCT_MAX_DECOMPRESSED_BYTES: "65536",
+      SOCKETDUCT_MAX_EXPANSION_RATIO: "50",
       SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
       SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
-    }),
-    /positive integer/
-  )
+    })
 
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_MAX_TARGET_BUFFER_BYTES: "-1",
-      SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
-      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
-    }),
-    /positive integer/
-  )
+    expect(config.compression).toBe("off")
+    expect(config.minCompressBytes).toBe(1024)
+    expect(config.maxDecompressedBytes).toBe(65536)
+    expect(config.maxExpansionRatio).toBe(50)
+  })
 
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES: "not-a-number",
+  it("loadEnvironmentConfig rejects an unknown SOCKETDUCT_COMPRESSION instead of silently defaulting", () => {
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_MODE: "relay",
+        SOCKETDUCT_COMPRESSION: "zstd",
+        SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+      })
+    ).toThrow(/Unsupported SOCKETDUCT_COMPRESSION/)
+  })
+
+  it("loadEnvironmentConfig defaults buffer limits when env vars are absent", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "relay",
       SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
       SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
-    }),
-    /positive integer/
-  )
-})
+    })
 
-test("loadEnvironmentConfig parses handshakeTimeoutMs and maxInputBytesPerConnection", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_HANDSHAKE_TIMEOUT_MS: "5000",
-    SOCKETDUCT_MAX_INPUT_BYTES_PER_CONNECTION: "32768",
-    SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
-    SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+    expect(config.maxTargetBufferBytes).toBe(1_048_576)
+    expect(config.maxTotalBufferBytes).toBe(16_777_216)
   })
 
-  assert.equal(config.handshakeTimeoutMs, 5000)
-  assert.equal(config.maxInputBytesPerConnection, 32768)
-})
-
-test("loadEnvironmentConfig parses and validates initial target retry delays", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS: "25",
-    SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS: "200"
+  it("loadEnvironmentConfig rejects non-positive buffer limit values", () => {
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_MAX_TARGET_BUFFER_BYTES: "0",
+        SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+      })
+    ).toThrow(/positive integer/)
+
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_MAX_TARGET_BUFFER_BYTES: "-1",
+        SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+      })
+    ).toThrow(/positive integer/)
+
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES: "not-a-number",
+        SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+      })
+    ).toThrow(/positive integer/)
   })
 
-  assert.equal(config.initialTargetRetryDelayMs, 25)
-  assert.equal(config.initialTargetRetryMaxDelayMs, 200)
-  assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS: "0"}), /positive integer/)
-  assert.throws(() => loadEnvironmentConfig({
-    SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS: "500",
-    SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS: "250"
-  }), /greater than or equal/i)
-})
+  it("loadEnvironmentConfig parses handshakeTimeoutMs and maxInputBytesPerConnection", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "relay",
+      SOCKETDUCT_HANDSHAKE_TIMEOUT_MS: "5000",
+      SOCKETDUCT_MAX_INPUT_BYTES_PER_CONNECTION: "32768",
+      SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
+      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+    })
 
-test("loadEnvironmentConfig parses and validates the initial target connect timeout", () => {
-  assert.equal(loadEnvironmentConfig({SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS: "750"}).initialTargetConnectTimeoutMs, 750)
-  assert.throws(
-    () => loadEnvironmentConfig({SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS: "0"}),
-    /SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS.*positive integer/
-  )
-})
+    expect(config.handshakeTimeoutMs).toBe(5000)
+    expect(config.maxInputBytesPerConnection).toBe(32768)
+  })
 
-test("loadEnvironmentConfig defaults handshakeTimeoutMs and maxInputBytesPerConnection when env vars are absent", () => {
-  const config = loadEnvironmentConfig({
-    SOCKETDUCT_MODE: "relay",
-    SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
-    SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+  it("loadEnvironmentConfig parses and validates initial target retry delays", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS: "25",
+      SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS: "200"
+    })
+
+    expect(config.initialTargetRetryDelayMs).toBe(25)
+    expect(config.initialTargetRetryMaxDelayMs).toBe(200)
+    expect(() => loadEnvironmentConfig({SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS: "0"})).toThrow(/positive integer/)
+    expect(() => loadEnvironmentConfig({
+      SOCKETDUCT_INITIAL_TARGET_RETRY_DELAY_MS: "500",
+      SOCKETDUCT_INITIAL_TARGET_RETRY_MAX_DELAY_MS: "250"
+    })).toThrow(/greater than or equal/i)
   })
 
-  assert.equal(config.handshakeTimeoutMs, 10_000)
-  assert.equal(config.maxInputBytesPerConnection, 65_536)
-})
+  it("loadEnvironmentConfig parses and validates the initial target connect timeout", () => {
+    expect(loadEnvironmentConfig({SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS: "750"}).initialTargetConnectTimeoutMs).toBe(750)
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS: "0"})
+    ).toThrow(/SOCKETDUCT_INITIAL_TARGET_CONNECT_TIMEOUT_MS.*positive integer/)
+  })
 
-test("loadEnvironmentConfig rejects non-positive handshakeTimeoutMs and maxInputBytesPerConnection", () => {
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_HANDSHAKE_TIMEOUT_MS: "0",
+  it("loadEnvironmentConfig defaults handshakeTimeoutMs and maxInputBytesPerConnection when env vars are absent", () => {
+    const config = loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "relay",
       SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
       SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
-    }),
-    /positive integer/
-  )
+    })
 
-  assert.throws(
-    () => loadEnvironmentConfig({
-      SOCKETDUCT_MAX_INPUT_BYTES_PER_CONNECTION: "-1",
-      SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
-      SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
-    }),
-    /positive integer/
-  )
-})
+    expect(config.handshakeTimeoutMs).toBe(10_000)
+    expect(config.maxInputBytesPerConnection).toBe(65_536)
+  })
+
+  it("loadEnvironmentConfig rejects non-positive handshakeTimeoutMs and maxInputBytesPerConnection", () => {
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_HANDSHAKE_TIMEOUT_MS: "0",
+        SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+      })
+    ).toThrow(/positive integer/)
+
+    expect(
+      () => loadEnvironmentConfig({
+        SOCKETDUCT_MAX_INPUT_BYTES_PER_CONNECTION: "-1",
+        SOCKETDUCT_AUTH_TOKENS: "edge:token-one",
+        SOCKETDUCT_TARGET_ALLOWLIST: "127.0.0.1:8080"
+      })
+    ).toThrow(/positive integer/)
+  })
 
-test("loadEnvironmentConfig mode validation", async (t) => {
-  await t.test("defaults to summary when SOCKETDUCT_MODE is not set", () => {
+  it("defaults to summary when SOCKETDUCT_MODE is not set", () => {
     const config = loadEnvironmentConfig({})
-    assert.equal(config.mode, "summary")
+    expect(config.mode).toBe("summary")
   })
 
-  await t.test("returns relay when SOCKETDUCT_MODE is relay", () => {
+  it("returns relay when SOCKETDUCT_MODE is relay", () => {
     const config = loadEnvironmentConfig({SOCKETDUCT_MODE: "relay"})
-    assert.equal(config.mode, "relay")
+    expect(config.mode).toBe("relay")
   })
 
-  await t.test("returns summary when SOCKETDUCT_MODE is summary", () => {
+  it("returns summary when SOCKETDUCT_MODE is summary", () => {
     const config = loadEnvironmentConfig({SOCKETDUCT_MODE: "summary"})
-    assert.equal(config.mode, "summary")
+    expect(config.mode).toBe("summary")
   })
 
-  await t.test("throws on invalid SOCKETDUCT_MODE", () => {
-    assert.throws(
-      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "relya"}),
-      /Unsupported SOCKETDUCT_MODE/
-    )
+  it("throws on invalid SOCKETDUCT_MODE", () => {
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "relya"})
+    ).toThrow(/Unsupported SOCKETDUCT_MODE/)
   })
 
-  await t.test("throws on arbitrary SOCKETDUCT_MODE value", () => {
-    assert.throws(
-      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "garbage"}),
-      /Unsupported SOCKETDUCT_MODE/
-    )
+  it("throws on arbitrary SOCKETDUCT_MODE value", () => {
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "garbage"})
+    ).toThrow(/Unsupported SOCKETDUCT_MODE/)
   })
 
-  await t.test("mode validation is case-sensitive", () => {
-    assert.throws(
-      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "RELAY"}),
-      /Unsupported SOCKETDUCT_MODE/
-    )
+  it("mode validation is case-sensitive", () => {
+    expect(
+      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "RELAY"})
+    ).toThrow(/Unsupported SOCKETDUCT_MODE/)
   })
 })