socketduct 0.1.15

package/src/server/control-handler.js

@@ -0,0 +1,170 @@
+import {negotiateCodec} from "../protocol/compression.js"
+
+/**
+ * @typedef {import('../sessions/session.js').SessionStore} SessionStore
+ * @typedef {{host: string, port: number}} SessionTarget
+ * @typedef {{userId: string, username: string}} Principal
+ * @typedef {object} TokenAuthenticator
+ * @property {(value: string) => Principal | undefined} authenticate - Authenticate a bearer token.
+ * @typedef {object} ControlHandlerOptions
+ * @property {TokenAuthenticator} tokens - Authentication token store.
+ * @property {SessionStore} sessions - Session store.
+ * @property {(input: {principal: Principal, target: SessionTarget}) => boolean} [authorizeTarget] - Target authorization policy.
+ * @property {string[]} [supportedCodecs] - stream.data codecs this relay accepts, in preference order. Empty or absent disables compression.
+ * @property {number[]} [supportedFraming] - Compact framing versions accepted by the relay.
+ * @typedef {Record<string, unknown> & {type: string}} ControlMessage
+ * @typedef {Record<string, unknown> & {type: string}} ControlResponse
+ */
+
+/**
+ * @param {ControlHandlerOptions} options - Handler dependencies.
+ * @param {ControlMessage} message - Incoming control message.
+ * @returns {ControlResponse} - Machine-readable response.
+ */
+export function handleControlMessage(options, message) {
+  if (message.type === "session.create") {
+    const framingError = requireFramingV2(message.framing, options.supportedFraming ?? [])
+    if (framingError !== undefined) {
+      return framingError
+    }
+
+    const principal = authenticate(options.tokens, message.token)
+    if (!principal) {
+      return errorResponse("AUTH_REQUIRED", "Authentication is required.", false)
+    }
+
+    if (typeof message.name !== "string" || message.name.length === 0) {
+      return errorResponse("PROTOCOL_VIOLATION", "Session name is required.", false)
+    }
+
+    const target = parseTarget(message.target)
+    if (target === undefined) {
+      return errorResponse("PROTOCOL_VIOLATION", "Target host and port are required.", false)
+    }
+
+    if (options.authorizeTarget?.({principal, target}) !== true) {
+      return errorResponse("TARGET_UNAUTHORIZED", "Target is not authorized for this principal.", false)
+    }
+
+    /** @type {ReturnType<SessionStore['create']>} */
+    let session
+    try {
+      session = options.sessions.create({
+        name: message.name,
+        ownerId: principal.userId,
+        target,
+        ...(typeof message.identifier === "string" ? {identifier: message.identifier} : {})
+      })
+    } catch {
+      return errorResponse("SESSION_EXISTS", "Session identifier already exists.", false)
+    }
+
+    const createdCodec = negotiateCodec(message.compression, options.supportedCodecs ?? [])
+
+    return {
+      type: "session.created",
+      identifier: session.identifier,
+      name: session.name,
+      state: session.state,
+      target: session.target,
+      ...(createdCodec !== undefined ? {compression: createdCodec} : {}),
+      framing: 2
+    }
+  }
+
+  if (message.type === "session.resume") {
+    const framingError = requireFramingV2(message.framing, options.supportedFraming ?? [])
+    if (framingError !== undefined) {
+      return framingError
+    }
+
+    const principal = authenticate(options.tokens, message.token)
+    if (!principal) {
+      return errorResponse("AUTH_REQUIRED", "Authentication is required.", false)
+    }
+
+    if (typeof message.identifier !== "string" || message.identifier.length === 0) {
+      return errorResponse("PROTOCOL_VIOLATION", "Session identifier is required.", false)
+    }
+
+    try {
+      const session = options.sessions.resume({identifier: message.identifier, ownerId: principal.userId})
+      const resumedCodec = negotiateCodec(message.compression, options.supportedCodecs ?? [])
+
+      return {
+        type: "session.resumed",
+        identifier: session.identifier,
+        name: session.name,
+        state: session.state,
+        target: session.target,
+        serverLastSequence: session.relaySequence,
+        serverLastAck: session.clientSequence,
+        replayFromSequence: session.clientSequence + 1,
+        ...(resumedCodec !== undefined ? {compression: resumedCodec} : {}),
+        framing: 2
+      }
+    } catch (error) {
+      const messageText = error instanceof Error ? error.message : String(error)
+      const code = messageText.includes("expired") ? "SESSION_EXPIRED" : "SESSION_NOT_FOUND"
+      return errorResponse(code, "Session does not exist or is not owned by this user.", false)
+    }
+  }
+
+  return errorResponse("PROTOCOL_VIOLATION", `Unsupported message type: ${message.type}`, false)
+}
+
+/**
+ * @param {unknown} offer - Client framing offer.
+ * @param {number[]} supported - Relay framing versions.
+ * @returns {ControlResponse | undefined} - Error when framing v2 cannot be negotiated.
+ */
+function requireFramingV2(offer, supported) {
+  if (Array.isArray(offer) && offer.includes(2) && supported.includes(2)) {
+    return undefined
+  }
+  return errorResponse("PROTOCOL_VIOLATION", "Socketduct protocol framing version 2 is required.", false)
+}
+
+/**
+ * @param {TokenAuthenticator} tokens - Token store.
+ * @param {unknown} token - Token value.
+ * @returns {Principal | undefined} - Authenticated principal.
+ */
+function authenticate(tokens, token) {
+  if (typeof token !== "string") {
+    return undefined
+  }
+  return tokens.authenticate(token)
+}
+
+/**
+ * @param {unknown} value - Incoming target field.
+ * @returns {SessionTarget | undefined} - Validated target.
+ */
+function parseTarget(value) {
+  if (typeof value !== "object" || value === null) {
+    return undefined
+  }
+
+  const candidate = /** @type {{host?: unknown, port?: unknown}} */ (value)
+  if (typeof candidate.host !== "string" || candidate.host.length === 0) {
+    return undefined
+  }
+
+  const port = candidate.port
+  if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65_535) {
+    return undefined
+  }
+
+  return {host: candidate.host, port}
+}
+
+/**
+ * @param {string} code - Error code.
+ * @param {string} message - Error message.
+ * @param {boolean} retryable - Retry hint.
+ * @returns {ControlResponse} - Error response.
+ */
+export function errorResponse(code, message, retryable) {
+  return {type: "error", code, message, retryable}
+}

package/src/server/primary.js

@@ -0,0 +1,64 @@
+import cluster from "node:cluster"
+import {availableParallelism} from "node:os"
+
+/**
+ * @typedef {object} ClusterLike
+ * @property {boolean} isPrimary - Whether this process is the primary process.
+ * @property {(env?: Record<string, string>) => WorkerLike} fork - Forks a worker process.
+ * @property {(event: 'exit', listener: (worker: WorkerLike, code: number | null, signal: string | null) => void) => void} on - Registers a cluster event listener.
+ * @typedef {object} WorkerLike
+ * @property {number | string | undefined} [id] - Worker identifier.
+ * @typedef {object} LoggerLike
+ * @property {(message: string) => void} [info] - Info logger.
+ * @property {(message: string) => void} [warn] - Warning logger.
+ * @typedef {object} PrimaryOptions
+ * @property {number} [workers] - Configured worker count.
+ * @property {ClusterLike} [clusterApi] - Cluster API implementation.
+ * @property {LoggerLike} [logger] - Logger implementation.
+ * @property {() => number} [availableCpus] - CPU-count provider.
+ * @typedef {object} PrimaryStartResult
+ * @property {'primary' | 'worker'} role - Process role.
+ * @property {number} workers - Worker count.
+ */
+
+/**
+ * @param {number | undefined} configuredWorkers - Explicit worker count.
+ * @param {() => number} [availableCpus] - CPU-count provider.
+ * @returns {number} - Safe worker count.
+ */
+export function resolveWorkerCount(configuredWorkers, availableCpus = availableParallelism) {
+  if (configuredWorkers !== undefined) {
+    if (!Number.isInteger(configuredWorkers) || configuredWorkers < 1) {
+      throw new Error(`Invalid worker count: ${configuredWorkers}`)
+    }
+    return configuredWorkers
+  }
+
+  return Math.max(1, availableCpus())
+}
+
+/**
+ * @param {PrimaryOptions} [options] - Primary start options.
+ * @returns {PrimaryStartResult} - Start summary.
+ */
+export function startPrimary(options = {}) {
+  const clusterApi = options.clusterApi ?? cluster
+  const logger = options.logger ?? console
+  const workers = resolveWorkerCount(options.workers, options.availableCpus)
+
+  if (!clusterApi.isPrimary) {
+    return {role: "worker", workers: 0}
+  }
+
+  for (let index = 0; index < workers; index += 1) {
+    clusterApi.fork({SOCKETDUCT_WORKER_INDEX: String(index)})
+  }
+
+  clusterApi.on("exit", (worker, code, signal) => {
+    logger.warn?.(`Socketduct worker ${String(worker.id ?? "unknown")} exited with code ${String(code)} signal ${String(signal)}; restarting`)
+    clusterApi.fork()
+  })
+
+  logger.info?.(`Socketduct primary started ${workers} worker(s)`)
+  return {role: "primary", workers}
+}

package/src/server/relay-runtime.js

@@ -0,0 +1,124 @@
+import {StaticTokenStore} from "../auth/static-token-store.js"
+import {isLoopbackHost} from "../config/environment.js"
+import {startTcpRelay} from "../proxy/tcp-relay.js"
+import {startMultiplexedTcpRelay} from "../proxy/multiplexed-relay.js"
+import {SessionStore} from "../sessions/session.js"
+
+/**
+ * @typedef {import('../config/environment.js').RelayEnvironmentConfig} RelayEnvironmentConfig
+ * @typedef {import('../config/environment.js').TargetEndpoint} TargetEndpoint
+ * @typedef {object} RelayRuntimeHandle
+ * @property {{server: import('node:net').Server | import('node:tls').Server, port: number, status: () => object, close: () => Promise<void>}} relay - Relay server handle.
+ * @property {() => Promise<void>} close - Close function.
+ */
+
+/**
+ * @param {RelayEnvironmentConfig} config - Relay runtime configuration.
+ * @returns {Promise<RelayRuntimeHandle>} Started relay runtime.
+ */
+export async function startRelayRuntime(config) {
+  validateRelayConfig(config)
+
+  const host = config.relayHost
+  const publicBind = !isLoopbackHost(host)
+  const tlsEnabled = config.relayTls !== undefined
+
+  if (publicBind && !tlsEnabled && !config.allowInsecurePublic) {
+    throw new Error(
+      `Relay binds to public host ${host} without TLS. Set SOCKETDUCT_TLS_CERT_FILE + SOCKETDUCT_TLS_KEY_FILE, or explicitly opt out with SOCKETDUCT_ALLOW_INSECURE_PUBLIC=1.`
+    )
+  }
+
+  /** @type {{certFile: string, keyFile: string, clientCaFile?: string} | undefined} */
+  let tlsOptions
+  if (tlsEnabled) {
+    const tls = /** @type {import('../config/environment.js').RelayTlsConfig} */ (config.relayTls)
+    /** @type {{certFile: string, keyFile: string, clientCaFile?: string}} */
+    const opts = {certFile: tls.certFile, keyFile: tls.keyFile}
+    if (tls.clientCaFile !== undefined) {
+      opts.clientCaFile = tls.clientCaFile
+    }
+    tlsOptions = opts
+  }
+
+  const tokens = new StaticTokenStore(config.authTokens)
+  const sessions = new SessionStore()
+  const allowedTargets = new Set(config.targetAllowlist.map(formatTarget))
+  /** @type {import('../protocol/compression.js').CompressionLimits} */
+  const compressionLimits = {}
+  if (config.minCompressBytes !== undefined) {
+    compressionLimits.minCompressBytes = config.minCompressBytes
+  }
+  if (config.maxDecompressedBytes !== undefined) {
+    compressionLimits.maxDecompressedBytes = config.maxDecompressedBytes
+  }
+  if (config.maxExpansionRatio !== undefined) {
+    compressionLimits.maxExpansionRatio = config.maxExpansionRatio
+  }
+  if (config.protocolVersion === 3) {
+    const relay = await startMultiplexedTcpRelay({
+      host,
+      port: config.relayPort,
+      resumeWindowMs: config.resumeWindowMs,
+      maxStreamBufferBytes: config.maxTargetBufferBytes,
+      maxConnectionBufferBytes: config.maxTotalBufferBytes,
+      maxTotalBufferBytes: config.maxTotalBufferBytes,
+      handshakeTimeoutMs: config.handshakeTimeoutMs,
+      maxInputBytesPerConnection: config.maxInputBytesPerConnection,
+      ...(config.initialTargetConnectTimeoutMs === undefined ? {} : {targetConnectTimeoutMs: config.initialTargetConnectTimeoutMs}),
+      tokens,
+      authorizeTarget: ({target}) => allowedTargets.has(formatTarget(target)),
+      ...(tlsOptions === undefined ? {} : {tls: tlsOptions})
+    })
+    return {relay, close: relay.close}
+  }
+
+  /** @type {import('../proxy/tcp-relay.js').TcpRelayOptions} */
+  const relayOptions = {
+    host,
+    port: config.relayPort,
+    resumeWindowMs: config.resumeWindowMs,
+    maxTargetBufferBytes: config.maxTargetBufferBytes,
+    maxTotalBufferBytes: config.maxTotalBufferBytes,
+    ...(config.initialTargetRetryDelayMs === undefined ? {} : {initialTargetRetryDelayMs: config.initialTargetRetryDelayMs}),
+    ...(config.initialTargetRetryMaxDelayMs === undefined ? {} : {initialTargetRetryMaxDelayMs: config.initialTargetRetryMaxDelayMs}),
+    ...(config.initialTargetConnectTimeoutMs === undefined ? {} : {initialTargetConnectTimeoutMs: config.initialTargetConnectTimeoutMs}),
+    handshakeTimeoutMs: config.handshakeTimeoutMs,
+    maxInputBytesPerConnection: config.maxInputBytesPerConnection,
+    compressionEnabled: config.compression !== "off",
+    compressionLimits,
+    tokens,
+    sessions,
+    authorizeTarget: ({target}) => allowedTargets.has(formatTarget(target))
+  }
+  if (tlsOptions !== undefined) {
+    relayOptions.tls = tlsOptions
+  }
+  const relay = await startTcpRelay(relayOptions)
+
+  return {
+    relay,
+    close: relay.close
+  }
+}
+
+/**
+ * @param {RelayEnvironmentConfig} config - Relay runtime configuration.
+ * @returns {void}
+ */
+function validateRelayConfig(config) {
+  if (config.authTokens.length === 0) {
+    throw new Error("SOCKETDUCT_AUTH_TOKENS must contain at least one username:token entry in relay mode")
+  }
+  if (config.targetAllowlist.length === 0) {
+    throw new Error("SOCKETDUCT_TARGET_ALLOWLIST must contain at least one host:port entry in relay mode")
+  }
+}
+
+/**
+ * @param {TargetEndpoint} target - Target endpoint.
+ * @returns {string} Canonical allowlist key.
+ */
+function formatTarget(target) {
+  return `${target.host}:${target.port}`
+}

package/src/server/worker.js

@@ -0,0 +1,39 @@
+import {createServer} from "node:net"
+
+/**
+ * @typedef {object} WorkerServerOptions
+ * @property {string} [host] - Listen host.
+ * @property {number} [port] - Listen port.
+ * @property {(socket: import('node:net').Socket) => void} connectionHandler - Socket connection handler.
+ * @typedef {object} WorkerServerHandle
+ * @property {import('node:net').Server} server - TCP server.
+ * @property {() => Promise<void>} close - Close function.
+ */
+
+/**
+ * @param {WorkerServerOptions} options - Worker server options.
+ * @returns {Promise<WorkerServerHandle>} - Started worker server.
+ */
+export async function startWorkerServer(options) {
+  const server = createServer(options.connectionHandler)
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(options.port ?? 0, options.host ?? "127.0.0.1", () => {
+      server.off("error", reject)
+      resolve(undefined)
+    })
+  })
+
+  return {
+    server,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error) {
+          reject(error)
+          return
+        }
+        resolve()
+      })
+    })
+  }
+}

package/src/sessions/session.js

@@ -0,0 +1,212 @@
+import {randomBytes} from "node:crypto"
+
+/**
+ * @typedef {'creating' | 'active' | 'interrupted' | 'resuming' | 'closed' | 'expired'} SessionState
+ * @typedef {object} Session
+ * @property {string} identifier - identifier value.
+ * @property {string} name - name value.
+ * @property {string} ownerId - ownerId value.
+ * @property {SessionState} state - state value.
+ * @property {number} clientSequence - clientSequence value.
+ * @property {number} relaySequence - relaySequence value.
+ * @property {{host: string, port: number}} target - Target endpoint for this session.
+ * @property {number} createdAt - createdAt value.
+ * @property {number} updatedAt - updatedAt value.
+ * @property {number} [expiresAt] - expiresAt value.
+ * @typedef {object} CreateSessionInput
+ * @property {string} name - name value.
+ * @property {string} ownerId - ownerId value.
+ * @property {{host: string, port: number}} target - Target endpoint for this session.
+ * @property {string} [identifier] - identifier value.
+ * @property {number} [clientSequence] - clientSequence value.
+ * @property {number} [relaySequence] - relaySequence value.
+ * @property {number} [createdAt] - createdAt value.
+ * @property {number} [updatedAt] - updatedAt value.
+ * @property {number} [expiresAt] - expiresAt value.
+ * @typedef {object} ResumeSessionInput
+ * @property {string} identifier - identifier value.
+ * @property {string} ownerId - ownerId value.
+ * @typedef {object} SessionStoreOptions
+ * @property {() => number} [now] - now value.
+ */
+
+/** @type {Map<SessionState, Set<SessionState>>} */
+const LEGAL_TRANSITIONS = new Map([
+  ["creating", new Set(["active", "closed"])],
+  ["active", new Set(["interrupted", "closed", "expired"])],
+  ["interrupted", new Set(["resuming", "closed", "expired"])],
+  ["resuming", new Set(["active", "interrupted", "closed", "expired"])],
+  ["closed", new Set()],
+  ["expired", new Set()]
+])
+
+/**
+ * @param {CreateSessionInput} input - input value.
+ * @returns {Session} - Result value.
+ */
+export function createSession(input) {
+  const now = input.createdAt ?? Date.now()
+  return {
+    identifier: input.identifier ?? generateSessionIdentifier(),
+    name: input.name,
+    ownerId: input.ownerId,
+    state: "creating",
+    clientSequence: input.clientSequence ?? 0,
+    relaySequence: input.relaySequence ?? 0,
+    target: input.target,
+    createdAt: now,
+    updatedAt: input.updatedAt ?? now,
+    ...(input.expiresAt === undefined ? {} : {expiresAt: input.expiresAt})
+  }
+}
+
+/**
+ * @param {Session} session - session value.
+ * @param {SessionState} nextState - nextState value.
+ * @param {number} [now] - now value.
+ * @returns {Session} - Result value.
+ */
+export function transitionSession(session, nextState, now = Date.now()) {
+  const allowed = LEGAL_TRANSITIONS.get(session.state) ?? new Set()
+  if (!allowed.has(nextState)) {
+    throw new Error(`Illegal session state transition: ${session.state} -> ${nextState}`)
+  }
+
+  return {
+    ...session,
+    state: nextState,
+    updatedAt: now
+  }
+}
+
+/**
+ * @param {SessionStore} store - store value.
+ * @param {ResumeSessionInput} input - input value.
+ * @returns {Session} - Result value.
+ */
+export function resumeSession(store, input) {
+  return store.resume(input)
+}
+
+export class SessionStore {
+  /** @type {Map<string, Session>} */
+  #sessions = new Map()
+
+  /** @type {() => number} */
+  #now
+
+  /** @param {SessionStoreOptions} [options] - Store options. */
+  constructor(options = {}) {
+    this.#now = options.now ?? Date.now
+  }
+
+  /**
+   * @param {CreateSessionInput} input - input value.
+   * @returns {Session} - Result value.
+   */
+  create(input) {
+    const now = this.#now()
+    const session = createSession({
+      ...input,
+      createdAt: input.createdAt ?? now,
+      updatedAt: input.updatedAt ?? now
+    })
+
+    if (this.#sessions.has(session.identifier)) {
+      throw new Error(`Session already exists: ${session.identifier}`)
+    }
+
+    this.#sessions.set(session.identifier, session)
+    return session
+  }
+
+  /**
+   * @param {string} identifier - identifier value.
+   * @returns {Session | undefined} - Result value.
+   */
+  get(identifier) {
+    return this.#sessions.get(identifier)
+  }
+
+  /**
+   * @param {string} identifier - identifier value.
+   * @param {SessionState} nextState - nextState value.
+   * @returns {Session} - Result value.
+   */
+  transition(identifier, nextState) {
+    const session = this.#requireSession(identifier)
+    const transitioned = transitionSession(session, nextState, this.#now())
+    this.#sessions.set(identifier, transitioned)
+    return transitioned
+  }
+
+  /**
+   * @param {string} identifier - Session identifier.
+   * @param {{clientSequence?: number, relaySequence?: number}} sequences - Committed sequence positions.
+   * @returns {Session} - Updated session.
+   */
+  updateSequences(identifier, sequences) {
+    const session = this.#requireSession(identifier)
+    const updated = {
+      ...session,
+      clientSequence: Math.max(session.clientSequence, sequences.clientSequence ?? session.clientSequence),
+      relaySequence: Math.max(session.relaySequence, sequences.relaySequence ?? session.relaySequence),
+      updatedAt: this.#now()
+    }
+    this.#sessions.set(identifier, updated)
+    return updated
+  }
+
+  /**
+   * @param {ResumeSessionInput} input - input value.
+   * @returns {Session} - Result value.
+   */
+  resume(input) {
+    const session = this.#requireSession(input.identifier)
+
+    if (session.expiresAt !== undefined && session.expiresAt <= this.#now()) {
+      const expired = {...session, state: /** @type {const} */ ("expired"), updatedAt: this.#now()}
+      this.#sessions.set(input.identifier, expired)
+      throw new Error(`Session expired: ${input.identifier}`)
+    }
+
+    if (session.ownerId !== input.ownerId) {
+      throw new Error(`Session does not belong to user: ${input.identifier}`)
+    }
+
+    if (session.state === "creating") {
+      throw new Error(`Session is not resumable before target readiness: ${input.identifier}`)
+    }
+
+    const resumeSource = session.state === "interrupted" ? session : transitionSession(session, "interrupted", this.#now())
+    const resumed = transitionSession(resumeSource, "resuming", this.#now())
+    this.#sessions.set(input.identifier, resumed)
+    return resumed
+  }
+
+  /**
+   * @param {string} identifier - Session identifier.
+   * @returns {boolean} - True when the session was in the store.
+   */
+  delete(identifier) {
+    return this.#sessions.delete(identifier)
+  }
+
+  /**
+   * @param {string} identifier - identifier value.
+   * @returns {Session} - Result value.
+   */
+  #requireSession(identifier) {
+    const session = this.#sessions.get(identifier)
+    if (!session) {
+      throw new Error(`Session not found: ${identifier}`)
+    }
+
+    return session
+  }
+}
+
+/** @returns {string} - Opaque token. */
+function generateSessionIdentifier() {
+  return randomBytes(24).toString("base64url")
+}