socketduct 0.1.15

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

@@ -0,0 +1,507 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+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"
+  })
+
+  assert.deepEqual(config.authTokens, [{username: "edge", token: "legacy-token"}])
+  assert.deepEqual(config.targetAllowlist, [{host: "docker-socket-shim", port: 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"
+  })
+
+  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/)
+})
+
+test("loadEnvironmentConfig keeps persistent logging disabled by default and parses explicit 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_MAX_FILE_BYTES: "2097152",
+    SOCKETDUCT_LOG_MAX_FILES: "4"
+  }).fileLogging, {
+    directory: "/var/log/socketduct",
+    maxFileBytes: 2_097_152,
+    maxFiles: 4
+  })
+})
+
+test("loadEnvironmentConfig rejects unsafe persistent logging bounds", () => {
+  assert.throws(() => loadEnvironmentConfig({
+    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+    SOCKETDUCT_LOG_MAX_FILE_BYTES: "100"
+  }), /SOCKETDUCT_LOG_MAX_FILE_BYTES/)
+  assert.throws(() => loadEnvironmentConfig({
+    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+    SOCKETDUCT_LOG_MAX_FILE_BYTES: "9007199254740992"
+  }), /SOCKETDUCT_LOG_MAX_FILE_BYTES/)
+  assert.throws(() => loadEnvironmentConfig({
+    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+    SOCKETDUCT_LOG_MAX_FILES: "0"
+  }), /SOCKETDUCT_LOG_MAX_FILES/)
+  assert.throws(() => loadEnvironmentConfig({
+    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+    SOCKETDUCT_LOG_MAX_FILES: "101"
+  }), /SOCKETDUCT_LOG_MAX_FILES/)
+})
+
+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/)
+})
+
+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/
+  )
+})
+
+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"
+  })
+
+  assert.deepEqual(config.relayTls, {
+    certFile: "/certs/relay.crt",
+    keyFile: "/certs/relay.key"
+  })
+})
+
+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"
+  })
+
+  assert.deepEqual(config.relayTls, {
+    certFile: "/certs/relay.crt",
+    keyFile: "/certs/relay.key",
+    clientCaFile: "/certs/client-ca.crt"
+  })
+})
+
+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"
+  })
+
+  assert.equal(config.relayTls, undefined)
+})
+
+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/
+  )
+})
+
+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  "
+  })
+
+  assert.deepEqual(config.relayTls, {
+    certFile: "/certs/relay.crt",
+    keyFile: "/certs/relay.key"
+  })
+})
+
+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)
+})
+
+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/
+  )
+})
+
+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/
+  )
+})
+
+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)
+})
+
+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)
+})
+
+test("loadEnvironmentConfig parses reverse hub identity bindings and exact 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_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}
+  ])
+})
+
+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"})
+})
+
+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-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/)
+})
+
+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)
+})
+
+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)
+})
+
+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)
+})
+
+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"
+  })
+
+  assert.equal(config.maxTargetBufferBytes, 65536)
+  assert.equal(config.maxTotalBufferBytes, 262144)
+})
+
+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)
+})
+
+test("loadEnvironmentConfig rejects an unknown SOCKETDUCT_COMPRESSION instead of silently defaulting", () => {
+  assert.throws(
+    () => loadEnvironmentConfig({
+      SOCKETDUCT_MODE: "relay",
+      SOCKETDUCT_COMPRESSION: "zstd",
+      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"
+  })
+
+  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",
+      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/
+  )
+
+  assert.throws(
+    () => loadEnvironmentConfig({
+      SOCKETDUCT_MAX_TOTAL_BUFFER_BYTES: "not-a-number",
+      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"
+  })
+
+  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"
+  })
+
+  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)
+})
+
+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/
+  )
+})
+
+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"
+  })
+
+  assert.equal(config.handshakeTimeoutMs, 10_000)
+  assert.equal(config.maxInputBytesPerConnection, 65_536)
+})
+
+test("loadEnvironmentConfig rejects non-positive handshakeTimeoutMs and maxInputBytesPerConnection", () => {
+  assert.throws(
+    () => loadEnvironmentConfig({
+      SOCKETDUCT_HANDSHAKE_TIMEOUT_MS: "0",
+      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/
+  )
+})
+
+test("loadEnvironmentConfig mode validation", async (t) => {
+  await t.test("defaults to summary when SOCKETDUCT_MODE is not set", () => {
+    const config = loadEnvironmentConfig({})
+    assert.equal(config.mode, "summary")
+  })
+
+  await t.test("returns relay when SOCKETDUCT_MODE is relay", () => {
+    const config = loadEnvironmentConfig({SOCKETDUCT_MODE: "relay"})
+    assert.equal(config.mode, "relay")
+  })
+
+  await t.test("returns summary when SOCKETDUCT_MODE is summary", () => {
+    const config = loadEnvironmentConfig({SOCKETDUCT_MODE: "summary"})
+    assert.equal(config.mode, "summary")
+  })
+
+  await t.test("throws on invalid SOCKETDUCT_MODE", () => {
+    assert.throws(
+      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "relya"}),
+      /Unsupported SOCKETDUCT_MODE/
+    )
+  })
+
+  await t.test("throws on arbitrary SOCKETDUCT_MODE value", () => {
+    assert.throws(
+      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "garbage"}),
+      /Unsupported SOCKETDUCT_MODE/
+    )
+  })
+
+  await t.test("mode validation is case-sensitive", () => {
+    assert.throws(
+      () => loadEnvironmentConfig({SOCKETDUCT_MODE: "RELAY"}),
+      /Unsupported SOCKETDUCT_MODE/
+    )
+  })
+})

package/test/unit/index.test.js

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {
+  connectSocketduct,
+  createJsonlFileLogger,
+  createMultiplexedSocketductConnection,
+  createMultiplexedSocketductTransportSet,
+  createSocketductConnectionFactory,
+  getStartupSummary,
+  MultiplexedSocketductConnection,
+  MultiplexedSocketductTransportSet,
+  OutboundReverseGateway,
+  ReverseGatewayConnection,
+  SocketductHttpAgent,
+  SocketductSocket
+} from "../../src/index.js"
+import {createSocketductConnectionFactory as directCreateSocketductConnectionFactory} from "../../src/client/connect.js"
+import {SocketductHttpAgent as DirectSocketductHttpAgent} from "../../src/client/http-agent.js"
+import {connectSocketduct as directConnectSocketduct, SocketductSocket as DirectSocketductSocket} from "../../src/client/socketduct-socket.js"
+import {createJsonlFileLogger as directCreateJsonlFileLogger} from "../../src/logging/structured-logger.js"
+
+test("getStartupSummary returns the Socketduct service identity and default mode", () => {
+  assert.deepEqual(getStartupSummary(), {
+    name: "Socketduct",
+    runtime: "node",
+    mode: "single-worker"
+  })
+})
+
+test("index exports the public SocketductSocket client API", () => {
+  assert.equal(SocketductSocket, DirectSocketductSocket)
+  assert.equal(connectSocketduct, directConnectSocketduct)
+  assert.equal(createSocketductConnectionFactory, directCreateSocketductConnectionFactory)
+  assert.equal(createJsonlFileLogger, directCreateJsonlFileLogger)
+  assert.equal(SocketductHttpAgent, DirectSocketductHttpAgent)
+})
+
+test("package exports expose dedicated HTTP and HTTPS adapter entrypoints without an HTTPS barrel export", async () => {
+  const socketduct = await import("socketduct")
+  const socketductHttp = await import("socketduct/http")
+  const socketductHttps = await import("socketduct/https")
+  const {SocketductHttpsAgent} = await import("../../src/client/https-agent.js")
+
+  assert.equal(socketduct.SocketductHttpAgent, DirectSocketductHttpAgent)
+  assert.equal(socketductHttp.SocketductHttpAgent, DirectSocketductHttpAgent)
+  assert.equal(socketductHttps.SocketductHttpsAgent, SocketductHttpsAgent)
+  assert.equal("SocketductHttpsAgent" in socketduct, false)
+})
+
+test("package exports the protocol-v3 pooled connection and relay entrypoints", async () => {
+  const multiplexed = await import("socketduct/multiplexed")
+  const relay = await import("socketduct/relay")
+
+  assert.equal(multiplexed.MultiplexedSocketductConnection, MultiplexedSocketductConnection)
+  assert.equal(multiplexed.MultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet)
+  assert.equal(createMultiplexedSocketductConnection({
+    relay: {host: "127.0.0.1", port: 3100, token: "test-token"}
+  }) instanceof MultiplexedSocketductConnection, true)
+  assert.equal(createMultiplexedSocketductTransportSet({
+    connectionId: "process_identity_01",
+    spoolDirectory: "/tmp/socketduct-index-test",
+    maxTotalBufferBytes: 1024,
+    maxTotalSpoolBytes: 1024,
+    maxTotalQueuedBytes: 2048,
+    gateways: [{gatewayId: "starlink", endpoint: {relay: {host: "127.0.0.1", port: 3100, token: "test-token"}}}]
+  }) instanceof MultiplexedSocketductTransportSet, true)
+  assert.equal(typeof relay.startMultiplexedTcpRelay, "function")
+})
+
+test("package exports native reverse hub, gateway, and client entrypoints", async () => {
+  const reverse = await import("socketduct/reverse")
+  const relay = await import("socketduct/relay")
+  assert.equal(reverse.OutboundReverseGateway, OutboundReverseGateway)
+  assert.equal(reverse.ReverseGatewayConnection, ReverseGatewayConnection)
+  assert.equal(typeof reverse.startReverseGatewayHub, "function")
+  assert.equal(relay.startReverseGatewayHub, reverse.startReverseGatewayHub)
+})