socketduct 0.1.15

package/test/unit/server/relay-runtime.test.js

@@ -0,0 +1,434 @@
+import assert from "node:assert/strict"
+import {createConnection, createServer} from "node:net"
+import {mkdtempSync, rmSync} from "node:fs"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import test from "node:test"
+
+import {encodeFrame, FrameDecoder} from "../../../src/protocol/frame.js"
+import {encodeV3Control, encodeV3Frame, V3FrameType} from "../../../src/protocol/v3-frame.js"
+import {MultiplexedSocketductConnection} from "../../../src/client/multiplexed-connection.js"
+import {startRelayRuntime} from "../../../src/server/relay-runtime.js"
+import {generateTestCertificates} from "../../helpers/tls-certificates.js"
+
+/** @returns {Promise<{host: string, port: number, close: () => Promise<void>}>} Started TCP target. */
+async function startTargetServer() {
+  const server = createServer((socket) => {
+    socket.on("data", (chunk) => socket.write(chunk))
+  })
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject)
+      resolve(undefined)
+    })
+  })
+
+  const address = server.address()
+  if (address === null || typeof address === "string") {
+    throw new Error("Target server did not bind to a TCP port")
+  }
+
+  return {
+    host: "127.0.0.1",
+    port: address.port,
+    close: async () => {
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error)
+            return
+          }
+          resolve(undefined)
+        })
+      })
+    }
+  }
+}
+
+test("startRelayRuntime starts a token-authenticated allowlisted relay", async () => {
+  const target = await startTargetServer()
+  const runtime = await startRelayRuntime({
+    mode: "relay",
+    relayHost: "127.0.0.1",
+    relayPort: 0,
+    resumeWindowMs: 30_000,
+    maxTargetBufferBytes: 1_048_576,
+    maxTotalBufferBytes: 16_777_216,
+    handshakeTimeoutMs: 10_000,
+    maxInputBytesPerConnection: 65_536,
+    authTokens: [{username: "edge", token: "secret-token"}],
+    targetAllowlist: [{host: target.host, port: target.port}],
+    allowInsecurePublic: false
+  })
+
+  test.after(async () => {
+    await runtime.close()
+    await target.close()
+  })
+
+  assert.deepEqual(runtime.relay.status(), {
+    activeTunnels: 0,
+    activeTargets: 0,
+    sessions: 0,
+    attachedSessions: 0,
+    detachedSessions: 0,
+    bufferedTargetBytes: 0,
+    targetConnectionAttempts: 0,
+    targetRetryTimers: 0
+  })
+
+  const socket = await new Promise((resolve, reject) => {
+    const connection = createConnection({host: "127.0.0.1", port: runtime.relay.port})
+    connection.once("error", reject)
+    connection.once("connect", () => {
+      connection.off("error", reject)
+      resolve(connection)
+    })
+  })
+
+  const response = await sendControl(socket, {
+    type: "session.create",
+    token: "secret-token",
+    name: "docker-test",
+    target: {host: target.host, port: target.port}
+  })
+
+  assert.equal(response.type, "session.created")
+  socket.destroy()
+})
+
+test("startRelayRuntime can select protocol v3 while v2 remains the default", async () => {
+  const target = await startTargetServer()
+  const runtime = await startRelayRuntime({
+    mode: "relay",
+    protocolVersion: 3,
+    relayHost: "127.0.0.1",
+    relayPort: 0,
+    resumeWindowMs: 30_000,
+    maxTargetBufferBytes: 1_048_576,
+    maxTotalBufferBytes: 16_777_216,
+    handshakeTimeoutMs: 10_000,
+    maxInputBytesPerConnection: 65_536,
+    authTokens: [{username: "edge", token: "secret-token"}],
+    targetAllowlist: [{host: target.host, port: target.port}],
+    allowInsecurePublic: false
+  })
+  const connection = new MultiplexedSocketductConnection({
+    relay: {host: "127.0.0.1", port: runtime.relay.port, token: "secret-token"}
+  })
+  try {
+    const socket = connection.createConnection({host: target.host, port: target.port})
+    await new Promise((resolve, reject) => {
+      socket.once("connect", resolve)
+      socket.once("error", reject)
+    })
+    const response = new Promise((resolve, reject) => {
+      socket.once("data", (chunk) => resolve(chunk.toString()))
+      socket.once("error", reject)
+    })
+    socket.write("v3-runtime")
+    assert.equal(await response, "v3-runtime")
+    assert.equal(/** @type {{physicalAccepts: number}} */ (runtime.relay.status()).physicalAccepts, 1)
+    socket.destroy()
+  } finally {
+    await connection.close()
+    await runtime.close()
+    await target.close()
+  }
+})
+
+test("startRelayRuntime enforces configured cumulative v3 unauthenticated input bytes", async () => {
+  const runtime = await startRelayRuntime({
+    mode: "relay",
+    protocolVersion: 3,
+    relayHost: "127.0.0.1",
+    relayPort: 0,
+    resumeWindowMs: 30_000,
+    maxTargetBufferBytes: 1_048_576,
+    maxTotalBufferBytes: 16_777_216,
+    handshakeTimeoutMs: 10_000,
+    maxInputBytesPerConnection: 32,
+    authTokens: [{username: "edge", token: "secret-token"}],
+    targetAllowlist: [{host: "127.0.0.1", port: 1}],
+    allowInsecurePublic: false
+  })
+  const socket = createConnection({host: "127.0.0.1", port: runtime.relay.port})
+  try {
+    await new Promise((resolve, reject) => {
+      socket.once("connect", resolve)
+      socket.once("error", reject)
+    })
+    const auth = encodeV3Frame({type: V3FrameType.AUTH, streamId: 0, sequence: 1}, encodeV3Control({
+      version: 3,
+      token: "secret-token",
+      connectionId: "runtime_input_limit_01",
+      generation: 1
+    }))
+    assert(auth.length > 33)
+    socket.resume()
+    const closed = new Promise((resolve) => socket.once("close", resolve))
+    socket.write(auth.subarray(0, 33))
+    await Promise.race([
+      closed,
+      new Promise((_, reject) => setTimeout(() => reject(new Error("v3 unauthenticated input limit was not enforced")), 250))
+    ])
+  } finally {
+    socket.destroy()
+    await runtime.close()
+  }
+})
+
+test("startRelayRuntime requires tokens and target allowlist", async () => {
+  await assert.rejects(
+    () => startRelayRuntime({
+      mode: "relay",
+      relayHost: "127.0.0.1",
+      relayPort: 0,
+      resumeWindowMs: 30_000,
+      maxTargetBufferBytes: 1_048_576,
+      maxTotalBufferBytes: 16_777_216,
+      handshakeTimeoutMs: 10_000,
+      maxInputBytesPerConnection: 65_536,
+      authTokens: [],
+      targetAllowlist: [{host: "127.0.0.1", port: 1}],
+      allowInsecurePublic: false
+    }),
+    /SOCKETDUCT_AUTH_TOKENS/
+  )
+
+  await assert.rejects(
+    () => startRelayRuntime({
+      mode: "relay",
+      relayHost: "127.0.0.1",
+      relayPort: 0,
+      resumeWindowMs: 30_000,
+      maxTargetBufferBytes: 1_048_576,
+      maxTotalBufferBytes: 16_777_216,
+      handshakeTimeoutMs: 10_000,
+      maxInputBytesPerConnection: 65_536,
+      authTokens: [{username: "edge", token: "secret-token"}],
+      targetAllowlist: [],
+      allowInsecurePublic: false
+    }),
+    /SOCKETDUCT_TARGET_ALLOWLIST/
+  )
+})
+
+/**
+ * @param {import('node:net').Socket} socket - Connected relay socket.
+ * @param {Record<string, unknown> & {type: string}} header - Control frame header.
+ * @returns {Promise<Record<string, unknown>>} Decoded response header.
+ */
+async function sendControl(socket, header) {
+  const decoder = new FrameDecoder()
+  return await new Promise((resolve, reject) => {
+    socket.on("data", (chunk) => {
+      for (const frame of decoder.push(chunk)) {
+        resolve(frame.header)
+      }
+    })
+    socket.once("error", reject)
+    const framedHeader = header.type === "session.create" || header.type === "session.resume"
+      ? {...header, framing: header.framing ?? [2]}
+      : header
+    socket.write(encodeFrame(framedHeader))
+  })
+}
+
+test("startRelayRuntime refuses non-loopback public bind without TLS or opt-out", async () => {
+  await assert.rejects(
+    () => startRelayRuntime({
+      mode: "relay",
+      relayHost: "0.0.0.0",
+      relayPort: 0,
+      resumeWindowMs: 30_000,
+      maxTargetBufferBytes: 1_048_576,
+      maxTotalBufferBytes: 16_777_216,
+      handshakeTimeoutMs: 10_000,
+      maxInputBytesPerConnection: 65_536,
+      authTokens: [{username: "edge", token: "secret-token"}],
+      targetAllowlist: [{host: "127.0.0.1", port: 1}],
+      allowInsecurePublic: false
+    }),
+    /public host.*without TLS/
+  )
+
+  await assert.rejects(
+    () => startRelayRuntime({
+      mode: "relay",
+      relayHost: "192.168.1.1",
+      relayPort: 0,
+      resumeWindowMs: 30_000,
+      maxTargetBufferBytes: 1_048_576,
+      maxTotalBufferBytes: 16_777_216,
+      handshakeTimeoutMs: 10_000,
+      maxInputBytesPerConnection: 65_536,
+      authTokens: [{username: "edge", token: "secret-token"}],
+      targetAllowlist: [{host: "127.0.0.1", port: 1}],
+      allowInsecurePublic: false
+    }),
+    /public host.*without TLS/
+  )
+})
+
+test("startRelayRuntime allows non-loopback public bind with explicit opt-out", async () => {
+  const target = await startTargetServer()
+  const runtime = await startRelayRuntime({
+    mode: "relay",
+    relayHost: "0.0.0.0",
+    relayPort: 0,
+    resumeWindowMs: 30_000,
+    maxTargetBufferBytes: 1_048_576,
+    maxTotalBufferBytes: 16_777_216,
+    handshakeTimeoutMs: 10_000,
+    maxInputBytesPerConnection: 65_536,
+    authTokens: [{username: "edge", token: "secret-token"}],
+    targetAllowlist: [{host: target.host, port: target.port}],
+    allowInsecurePublic: true
+  })
+
+  test.after(async () => {
+    await runtime.close()
+    await target.close()
+  })
+
+  const socket = await new Promise((resolve, reject) => {
+    const connection = createConnection({host: "127.0.0.1", port: runtime.relay.port})
+    connection.once("error", reject)
+    connection.once("connect", () => {
+      connection.off("error", reject)
+      resolve(connection)
+    })
+  })
+
+  const response = await sendControl(socket, {
+    type: "session.create",
+    token: "secret-token",
+    name: "insecure-test",
+    target: {host: target.host, port: target.port}
+  })
+
+  assert.equal(response.type, "session.created")
+  socket.destroy()
+})
+
+test("startRelayRuntime accepts loopback bind without TLS", async () => {
+  const target = await startTargetServer()
+  const runtime = await startRelayRuntime({
+    mode: "relay",
+    relayHost: "127.0.0.1",
+    relayPort: 0,
+    resumeWindowMs: 30_000,
+    maxTargetBufferBytes: 1_048_576,
+    maxTotalBufferBytes: 16_777_216,
+    handshakeTimeoutMs: 10_000,
+    maxInputBytesPerConnection: 65_536,
+    authTokens: [{username: "edge", token: "secret-token"}],
+    targetAllowlist: [{host: target.host, port: target.port}],
+    allowInsecurePublic: false
+  })
+
+  test.after(async () => {
+    await runtime.close()
+    await target.close()
+  })
+
+  const socket = await new Promise((resolve, reject) => {
+    const connection = createConnection({host: "127.0.0.1", port: runtime.relay.port})
+    connection.once("error", reject)
+    connection.once("connect", () => {
+      connection.off("error", reject)
+      resolve(connection)
+    })
+  })
+
+  const response = await sendControl(socket, {
+    type: "session.create",
+    token: "secret-token",
+    name: "loopback-test",
+    target: {host: target.host, port: target.port}
+  })
+
+  assert.equal(response.type, "session.created")
+  socket.destroy()
+})
+
+test("startRelayRuntime starts a TLS relay with valid certificate files", async () => {
+  const target = await startTargetServer()
+  const certDir = mkdtempSync(join(tmpdir(), "socketduct-tls-startup-"))
+  const certs = generateTestCertificates(certDir)
+
+  const runtime = await startRelayRuntime({
+    mode: "relay",
+    relayHost: "127.0.0.1",
+    relayPort: 0,
+    resumeWindowMs: 30_000,
+    maxTargetBufferBytes: 1_048_576,
+    maxTotalBufferBytes: 16_777_216,
+    handshakeTimeoutMs: 10_000,
+    maxInputBytesPerConnection: 65_536,
+    authTokens: [{username: "edge", token: "secret-token"}],
+    targetAllowlist: [{host: target.host, port: target.port}],
+    relayTls: {certFile: certs.serverCertFile, keyFile: certs.serverKeyFile},
+    allowInsecurePublic: false
+  })
+
+  test.after(async () => {
+    await runtime.close()
+    await target.close()
+    rmSync(certDir, {recursive: true, force: true})
+  })
+
+  assert.ok(runtime.relay.port > 0)
+})
+
+test("startRelayRuntime fails loudly on missing TLS certificate file", async () => {
+  await assert.rejects(
+    () => startRelayRuntime({
+      mode: "relay",
+      relayHost: "127.0.0.1",
+      relayPort: 0,
+      resumeWindowMs: 30_000,
+      maxTargetBufferBytes: 1_048_576,
+      maxTotalBufferBytes: 16_777_216,
+      handshakeTimeoutMs: 10_000,
+      maxInputBytesPerConnection: 65_536,
+      authTokens: [{username: "edge", token: "secret-token"}],
+      targetAllowlist: [{host: "127.0.0.1", port: 1}],
+      relayTls: {certFile: "/nonexistent/cert.crt", keyFile: "/nonexistent/key.key"},
+      allowInsecurePublic: false
+    }),
+    /ENOENT/
+  )
+})
+
+test("startRelayRuntime allows non-loopback bind with TLS configured", async () => {
+  const target = await startTargetServer()
+  const certDir = mkdtempSync(join(tmpdir(), "socketduct-tls-loopback-"))
+  const certs = generateTestCertificates(certDir)
+
+  const runtime = await startRelayRuntime({
+    mode: "relay",
+    relayHost: "0.0.0.0",
+    relayPort: 0,
+    resumeWindowMs: 30_000,
+    maxTargetBufferBytes: 1_048_576,
+    maxTotalBufferBytes: 16_777_216,
+    handshakeTimeoutMs: 10_000,
+    maxInputBytesPerConnection: 65_536,
+    authTokens: [{username: "edge", token: "secret-token"}],
+    targetAllowlist: [{host: target.host, port: target.port}],
+    relayTls: {certFile: certs.serverCertFile, keyFile: certs.serverKeyFile},
+    allowInsecurePublic: false
+  })
+
+  test.after(async () => {
+    await runtime.close()
+    await target.close()
+    rmSync(certDir, {recursive: true, force: true})
+  })
+
+  assert.ok(runtime.relay.port > 0)
+})

package/test/unit/sessions/session.test.js

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {
+  createSession,
+  resumeSession,
+  transitionSession,
+  SessionStore
+} from "../../../src/sessions/session.js"
+
+test("createSession creates a named creating session with an opaque identifier", () => {
+  const session = createSession({name: "Office link", ownerId: "user-1", target: {host: "127.0.0.1", port: 22}})
+
+  assert.equal(session.name, "Office link")
+  assert.equal(session.ownerId, "user-1")
+  assert.equal(session.state, "creating")
+  assert.match(session.identifier, /^[a-zA-Z0-9_-]{32,}$/)
+  assert.equal(session.clientSequence, 0)
+  assert.equal(session.relaySequence, 0)
+  assert.deepEqual(session.target, {host: "127.0.0.1", port: 22})
+})
+
+test("transitionSession only allows legal lifecycle transitions", () => {
+  const session = createSession({name: "Flaky line", ownerId: "user-1", target: {host: "127.0.0.1", port: 22}, identifier: "session_123456789012345678901234567890"})
+
+  assert.equal(transitionSession(session, "active").state, "active")
+  assert.equal(transitionSession({...session, state: "interrupted"}, "resuming").state, "resuming")
+  assert.equal(transitionSession({...session, state: "resuming"}, "active").state, "active")
+
+  assert.throws(
+    () => transitionSession({...session, state: "active"}, "resuming"),
+    /illegal session state transition/i
+  )
+})
+
+test("SessionStore resumes sessions by identifier for the owning user", () => {
+  const store = new SessionStore()
+  const session = store.create({name: "Müggelheim relay", ownerId: "kasper", target: {host: "127.0.0.1", port: 22}})
+  store.transition(session.identifier, "active")
+  store.transition(session.identifier, "interrupted")
+
+  const resumed = resumeSession(store, {
+    identifier: session.identifier,
+    ownerId: "kasper"
+  })
+
+  assert.equal(resumed.identifier, session.identifier)
+  assert.equal(resumed.state, "resuming")
+})
+
+test("SessionStore rejects resume for a missing or expired session", () => {
+  const store = new SessionStore({now: () => 2_000})
+  store.create({name: "Expired", ownerId: "user-1", target: {host: "127.0.0.1", port: 22}, identifier: "expired_session_12345678901234567890", expiresAt: 1_000})
+
+  assert.throws(
+    () => resumeSession(store, {identifier: "missing_session_12345678901234567890", ownerId: "user-1"}),
+    /not found/i
+  )
+  assert.throws(
+    () => resumeSession(store, {identifier: "expired_session_12345678901234567890", ownerId: "user-1"}),
+    /expired/i
+  )
+})
+
+test("SessionStore rejects resume while initial target acquisition is still creating", () => {
+  const store = new SessionStore()
+  const session = store.create({name: "Pending", ownerId: "user-1", target: {host: "127.0.0.1", port: 22}})
+
+  assert.throws(
+    () => resumeSession(store, {identifier: session.identifier, ownerId: "user-1"}),
+    /not resumable/i
+  )
+  assert.equal(store.get(session.identifier)?.state, "creating")
+})
+
+test("SessionStore prevents a different user from resuming a session", () => {
+  const store = new SessionStore()
+  const session = store.create({name: "Private", ownerId: "owner", target: {host: "127.0.0.1", port: 22}})
+
+  assert.throws(
+    () => resumeSession(store, {identifier: session.identifier, ownerId: "other-user"}),
+    /does not belong/i
+  )
+})