socketduct 0.1.15

package/src/reverse/hub.js

@@ -0,0 +1,563 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-property-description, jsdoc/require-returns */
+import {readFileSync} from "node:fs"
+import {createServer as createTlsServer} from "node:tls"
+
+import {availableCodecs, negotiateCodec, zstdAvailable} from "../protocol/compression.js"
+import {decodeV3Data, encodeV3Data, AdaptiveCompressor} from "../protocol/v3-compression.js"
+import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../protocol/v3-frame.js"
+import {
+  DEFAULT_FRAME_BYTES,
+  DEFAULT_HANDSHAKE_MS,
+  DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS,
+  DEFAULT_MAX_INPUT_BYTES,
+  DEFAULT_MAX_STREAMS,
+  DEFAULT_WINDOW,
+  GATEWAY_ID,
+  MAX_CONTROL_BYTES,
+  parseTarget,
+  positiveInteger,
+  protocolError,
+  STABLE_IDENTIFIER,
+  writeSocket
+} from "./common.js"
+
+/**
+ * @typedef {{userId: string, username: string}} Principal
+ * @typedef {{host: string, port: number}} Target
+ * @typedef {object} ReverseGatewayHubOptions
+ * @property {string} [host] - TLS listen host, default loopback.
+ * @property {number} [port] - TLS listen port.
+ * @property {{authenticate(token: string): Principal | undefined}} tokens - Client and gateway bearer authenticator.
+ * @property {{certFile: string, keyFile: string, clientCaFile?: string}} tls - Mandatory outer TLS server configuration.
+ * @property {(input: {principal: Principal, gatewayId: string}) => boolean} authorizeGateway - Stable gateway identity binding.
+ * @property {(input: {principal: Principal, gatewayId: string}) => boolean} authorizeClientGateway - Client-to-gateway selection policy.
+ * @property {(input: {principal: Principal, gatewayId: string, target: Target}) => boolean} authorizeOpen - Hub-side route policy.
+ * @property {string[]} [knownGatewayIds] - Configured IDs that may be temporarily unavailable.
+ * @property {number} [initialWindowBytes] - Per-direction flow-control window.
+ * @property {number} [maxFrameBytes] - Maximum uncompressed DATA frame.
+ * @property {number} [maxStreams] - Process-wide bridge limit.
+ * @property {number} [maxPhysicalConnections] - Simultaneous TCP connection bound, including pre-TLS handshakes.
+ * @property {number} [maxConnectionIdentities] - Retained stale-generation identity bound.
+ * @property {number} [handshakeTimeoutMs] - Authentication deadline.
+ * @property {number} [maxInputBytesPerConnection] - Pre-authentication byte bound.
+ * @property {import('../protocol/compression.js').CompressionLimits} [compressionLimits] - zstd safety bounds.
+ * @typedef {object} HubPhysical
+ * @property {import('node:tls').TLSSocket} socket
+ * @property {Principal | undefined} principal
+ * @property {'gateway' | 'client' | undefined} role
+ * @property {string | undefined} connectionId
+ * @property {number} generation
+ * @property {string | undefined} codec
+ * @property {string | undefined} gatewayId
+ * @property {Map<number, Bridge>} streams
+ * @property {number} lastClientStreamId
+ * @property {number} nextGatewayStreamId
+ * @property {boolean} authenticated
+ * @property {boolean} closing
+ * @property {(() => void) | undefined} clearHandshake
+ * @typedef {object} GatewayOwner
+ * @property {string} gatewayId
+ * @property {string} connectionId
+ * @property {string} userId
+ * @property {number} generation
+ * @property {HubPhysical | undefined} physical
+ * @typedef {object} ClientOwner
+ * @property {string} connectionId
+ * @property {string} userId
+ * @property {number} generation
+ * @property {HubPhysical | undefined} physical
+ * @typedef {object} Bridge
+ * @property {HubPhysical} client
+ * @property {number} clientStreamId
+ * @property {HubPhysical} gateway
+ * @property {number} gatewayStreamId
+ * @property {string} identifier
+ * @property {Target} target
+ * @property {'opening' | 'open' | 'half-closed' | 'closing'} state
+ * @property {number} clientToGatewaySequence
+ * @property {number} gatewayToClientSequence
+ * @property {number} clientToGatewayAck
+ * @property {number} gatewayToClientAck
+ * @property {boolean} clientEnded
+ * @property {boolean} gatewayEnded
+ * @property {AdaptiveCompressor} clientToGatewayCompressor
+ * @property {AdaptiveCompressor} gatewayToClientCompressor
+ */
+
+/** Starts the Server3 reverse hub. */
+export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions} */ options) {
+  validateOptions(options)
+  const initialWindow = positiveInteger(options.initialWindowBytes, "initialWindowBytes", DEFAULT_WINDOW)
+  const maxFrameBytes = Math.min(positiveInteger(options.maxFrameBytes, "maxFrameBytes", DEFAULT_FRAME_BYTES), 64 * 1024)
+  const maxStreams = positiveInteger(options.maxStreams, "maxStreams", DEFAULT_MAX_STREAMS)
+  const maxIdentities = positiveInteger(options.maxConnectionIdentities, "maxConnectionIdentities", 4096)
+  const maxPhysicalConnections = positiveInteger(options.maxPhysicalConnections, "maxPhysicalConnections", 8192)
+  /** @type {Map<string, GatewayOwner>} */
+  const gateways = new Map()
+  /** @type {Map<string, ClientOwner>} */
+  const clients = new Map()
+  /** @type {Set<HubPhysical>} */
+  const physicals = new Set()
+  /** @type {Set<import('node:net').Socket>} */
+  const tcpSockets = new Set()
+  /** @type {Map<string, {socket: import('node:net').Socket, timer: ReturnType<typeof setTimeout>}>} */
+  const pendingTls = new Map()
+  let bridges = 0
+  let physicalAccepts = 0
+  let gatewayRegistrations = 0
+  let rejectedRegistrations = 0
+  let rejectedOpens = 0
+  let rawDataBytes = 0
+  let wireDataBytes = 0
+  let closing = false
+
+  const server = createTlsServer({
+    cert: readFileSync(options.tls.certFile),
+    key: readFileSync(options.tls.keyFile),
+    ...(options.tls.clientCaFile === undefined ? {} : {ca: readFileSync(options.tls.clientCaFile)}),
+    requestCert: options.tls.clientCaFile !== undefined,
+    rejectUnauthorized: options.tls.clientCaFile !== undefined
+  }, accept)
+  server.prependListener("connection", admitTcp)
+
+  /** @param {import('node:net').Socket} socket - Newly accepted TCP socket before TLS negotiation. */
+  function admitTcp(socket) {
+    if (closing || tcpSockets.size >= maxPhysicalConnections) { socket.destroy(); return }
+    physicalAccepts += 1
+    tcpSockets.add(socket)
+    const key = socketKey(socket)
+    const timer = setTimeout(() => socket.destroy(), options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_MS)
+    timer.unref?.()
+    pendingTls.set(key, {socket, timer})
+    socket.once("close", () => {
+      clearTimeout(timer)
+      tcpSockets.delete(socket)
+      if (pendingTls.get(key)?.socket === socket) pendingTls.delete(key)
+    })
+  }
+
+  /** @param {import('node:tls').TLSSocket} socket - Accepted verified server-side TLS socket. */
+  function accept(socket) {
+    const pending = pendingTls.get(socketKey(socket))
+    if (closing || pending === undefined) { socket.destroy(); return }
+    clearTimeout(pending.timer)
+    pendingTls.delete(socketKey(socket))
+    socket.setNoDelay(true)
+    socket.setKeepAlive(true, DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS)
+    /** @type {HubPhysical} */
+    const physical = {
+      socket,
+      principal: undefined,
+      role: undefined,
+      connectionId: undefined,
+      generation: 0,
+      codec: undefined,
+      gatewayId: undefined,
+      streams: new Map(),
+      lastClientStreamId: 0,
+      nextGatewayStreamId: 2,
+      authenticated: false,
+      closing: false,
+      clearHandshake: undefined
+    }
+    physicals.add(physical)
+    const decoder = new V3FrameDecoder({maxFrameBytes: Math.max(MAX_CONTROL_BYTES, maxFrameBytes + 4), maxBufferedBytes: Math.max(MAX_CONTROL_BYTES, maxFrameBytes + 4) * 2})
+    let unauthenticatedBytes = 0
+    let queue = Promise.resolve()
+    const handshakeTimer = setTimeout(() => terminate(physical, "HANDSHAKE_TIMEOUT"), options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_MS)
+    handshakeTimer.unref?.()
+
+    socket.on("data", (chunk) => {
+      socket.pause()
+      if (!physical.authenticated) unauthenticatedBytes += chunk.length
+      queue = queue.then(async () => {
+        if (!physical.authenticated && unauthenticatedBytes > (options.maxInputBytesPerConnection ?? DEFAULT_MAX_INPUT_BYTES)) throw protocolError("INPUT_LIMIT_EXCEEDED")
+        const frames = decoder.push(chunk)
+        for (const frame of frames) await handleFrame(physical, frame)
+      }).catch(async (error) => {
+        const code = typeof /** @type {{code?: unknown}} */ (error).code === "string" ? /** @type {{code: string}} */ (error).code : "PROTOCOL_VIOLATION"
+        await sendControl(physical, V3FrameType.GOAWAY, 0, 0, {code}).catch(() => {})
+        socket.destroy()
+      }).finally(() => {
+        if (!socket.destroyed && !physical.closing) socket.resume()
+      })
+    })
+    socket.on("error", () => {})
+    socket.once("close", () => {
+      clearTimeout(handshakeTimer)
+      void queue.finally(() => detachPhysical(physical, "TRANSPORT_CLOSED"))
+    })
+    physical.clearHandshake = () => clearTimeout(handshakeTimer)
+  }
+
+  /** @param {HubPhysical} physical - Source. @param {import('../protocol/v3-frame.js').V3Frame} frame - Frame. */
+  async function handleFrame(physical, frame) {
+    if (physical.closing) throw protocolError("STALE_GENERATION")
+    if (!physical.authenticated) {
+      if (frame.type !== V3FrameType.AUTH || frame.streamId !== 0 || frame.flags !== 0) throw protocolError("AUTH_REQUIRED")
+      const auth = decodeV3Control(frame.payload)
+      if ((auth.role !== "gateway" && auth.role !== "client") || !Array.isArray(auth.versions) || !auth.versions.includes(3) || typeof auth.connectionId !== "string" || !STABLE_IDENTIFIER.test(auth.connectionId) || !Number.isSafeInteger(auth.generation) || /** @type {number} */ (auth.generation) <= 0) throw protocolError("PROTOCOL_NEGOTIATION_FAILED")
+      const principal = typeof auth.token === "string" ? options.tokens.authenticate(auth.token) : undefined
+      if (principal === undefined) {
+        await sendControl(physical, V3FrameType.AUTH_ERROR, 0, 0, {code: "AUTH_REQUIRED"})
+        physical.socket.end()
+        return
+      }
+      physical.role = auth.role
+      physical.principal = principal
+      physical.connectionId = auth.connectionId
+      physical.generation = /** @type {number} */ (auth.generation)
+      physical.codec = negotiateCodec(auth.compression, availableCodecs())
+      if (auth.role === "client") authenticateClientOwner(physical, maxIdentities)
+      physical.authenticated = true
+      physical.clearHandshake?.()
+      await sendControl(physical, V3FrameType.AUTH_OK, 0, physical.generation, {
+        version: 3,
+        role: physical.role,
+        connectionId: physical.connectionId,
+        generation: physical.generation,
+        compression: physical.codec ?? null,
+        initialWindow
+      })
+      return
+    }
+    if (frame.type === V3FrameType.PING) {
+      await sendControl(physical, V3FrameType.PONG, 0, frame.sequence, {})
+      return
+    }
+    if (frame.type === V3FrameType.PONG) return
+    if (frame.type === V3FrameType.GOAWAY) {
+      physical.socket.end()
+      return
+    }
+    if (physical.role === "gateway" && physical.gatewayId !== undefined && gateways.get(physical.gatewayId)?.physical !== physical) throw protocolError("STALE_GENERATION")
+    if (physical.role === "client" && physical.connectionId !== undefined && clients.get(physical.connectionId)?.physical !== physical) throw protocolError("STALE_GENERATION")
+    if (physical.role === "gateway" && physical.gatewayId === undefined) {
+      if (frame.type !== V3FrameType.GATEWAY_REGISTER) throw protocolError("GATEWAY_REGISTRATION_REQUIRED")
+      await registerGateway(physical, frame)
+      return
+    }
+    if (physical.role === "client" && physical.gatewayId === undefined) {
+      if (frame.type !== V3FrameType.GATEWAY_SELECT) throw protocolError("GATEWAY_SELECTION_REQUIRED")
+      await selectGateway(physical, frame)
+      return
+    }
+    if (frame.type === V3FrameType.GATEWAY_REGISTER || frame.type === V3FrameType.GATEWAY_REGISTERED || frame.type === V3FrameType.GATEWAY_SELECT || frame.type === V3FrameType.GATEWAY_SELECTED || frame.type === V3FrameType.AUTH || frame.type === V3FrameType.AUTH_OK || frame.type === V3FrameType.AUTH_ERROR || frame.type === V3FrameType.RESUME || frame.type === V3FrameType.RESUMED) throw protocolError("UNSUPPORTED_FRAME")
+    if (physical.role === "client" && frame.type === V3FrameType.OPEN) {
+      await openBridge(physical, frame)
+      return
+    }
+    await relayStreamFrame(physical, frame)
+  }
+
+  /** @param {HubPhysical} physical - Authenticated client owner. @param {number} limit - Bound. */
+  function authenticateClientOwner(physical, limit) {
+    const id = /** @type {string} */ (physical.connectionId)
+    const principal = /** @type {Principal} */ (physical.principal)
+    const existing = clients.get(id)
+    if (existing !== undefined && existing.userId !== principal.userId) throw protocolError("AUTH_OWNERSHIP_MISMATCH")
+    if (existing !== undefined && physical.generation <= existing.generation) throw protocolError("STALE_GENERATION")
+    if (existing === undefined && clients.size >= limit) evictDisconnectedClientIdentity()
+    if (existing === undefined && clients.size >= limit) throw protocolError("IDENTITY_LIMIT")
+    if (existing?.physical !== undefined) terminate(existing.physical, "CONNECTION_REPLACED")
+    clients.set(id, {connectionId: id, userId: principal.userId, generation: physical.generation, physical})
+  }
+
+  /** Evicts the oldest disconnected client identity while active owners remain fenced. */
+  function evictDisconnectedClientIdentity() {
+    for (const [id, owner] of clients) {
+      if (owner.physical !== undefined) continue
+      clients.delete(id)
+      return
+    }
+  }
+
+  /** @param {HubPhysical} physical - Authenticated gateway. @param {import('../protocol/v3-frame.js').V3Frame} frame - Register frame. */
+  async function registerGateway(physical, frame) {
+    if (frame.streamId !== 0 || frame.sequence !== physical.generation || frame.flags !== 0) throw protocolError("INVALID_GATEWAY_REGISTRATION")
+    const request = decodeV3Control(frame.payload)
+    if (typeof request.gatewayId !== "string" || !GATEWAY_ID.test(request.gatewayId) || physical.principal === undefined || options.authorizeGateway({principal: physical.principal, gatewayId: request.gatewayId}) !== true) {
+      rejectedRegistrations += 1
+      throw protocolError("GATEWAY_UNAUTHORIZED")
+    }
+    const existing = gateways.get(request.gatewayId)
+    const connectionId = /** @type {string} */ (physical.connectionId)
+    if (existing !== undefined && existing.userId !== physical.principal.userId) {
+      rejectedRegistrations += 1
+      throw protocolError("AUTH_OWNERSHIP_MISMATCH")
+    }
+    if (existing !== undefined && existing.connectionId !== connectionId) {
+      rejectedRegistrations += 1
+      throw protocolError("DUPLICATE_GATEWAY")
+    }
+    if (existing !== undefined && physical.generation <= existing.generation) {
+      rejectedRegistrations += 1
+      throw protocolError("STALE_GENERATION")
+    }
+    if (existing === undefined && gateways.size >= maxIdentities) throw protocolError("IDENTITY_LIMIT")
+    if (existing?.physical !== undefined) terminate(existing.physical, "GATEWAY_REPLACED")
+    physical.gatewayId = request.gatewayId
+    gateways.set(request.gatewayId, {
+      gatewayId: request.gatewayId,
+      connectionId,
+      userId: physical.principal.userId,
+      generation: physical.generation,
+      physical
+    })
+    gatewayRegistrations += 1
+    await sendControl(physical, V3FrameType.GATEWAY_REGISTERED, 0, physical.generation, {gatewayId: request.gatewayId, generation: physical.generation})
+  }
+
+  /** @param {HubPhysical} physical - Authenticated client. @param {import('../protocol/v3-frame.js').V3Frame} frame - Selection frame. */
+  async function selectGateway(physical, frame) {
+    if (frame.streamId !== 0 || frame.sequence !== physical.generation || frame.flags !== 0) throw protocolError("INVALID_GATEWAY_SELECTION")
+    const request = decodeV3Control(frame.payload)
+    if (typeof request.gatewayId !== "string" || !GATEWAY_ID.test(request.gatewayId)) throw protocolError("INVALID_GATEWAY_SELECTION")
+    if (physical.principal === undefined || options.authorizeClientGateway({principal: physical.principal, gatewayId: request.gatewayId}) !== true) throw protocolError("GATEWAY_UNAUTHORIZED")
+    const owner = gateways.get(request.gatewayId)
+    const known = owner !== undefined || options.knownGatewayIds?.includes(request.gatewayId) === true
+    if (!known) throw protocolError("UNKNOWN_GATEWAY_ID")
+    if (owner?.physical === undefined) throw protocolError("GATEWAY_UNAVAILABLE")
+    physical.gatewayId = request.gatewayId
+    await sendControl(physical, V3FrameType.GATEWAY_SELECTED, 0, physical.generation, {gatewayId: request.gatewayId, generation: physical.generation})
+  }
+
+  /** @param {HubPhysical} client - Client physical. @param {import('../protocol/v3-frame.js').V3Frame} frame - OPEN. */
+  async function openBridge(client, frame) {
+    if (frame.sequence !== 0) throw protocolError("INVALID_STREAM_OPEN")
+    if (frame.streamId % 2 === 0 || frame.streamId <= client.lastClientStreamId || client.streams.size >= maxStreams || bridges >= maxStreams) throw protocolError("INVALID_STREAM_ID")
+    client.lastClientStreamId = frame.streamId
+    const request = decodeV3Control(frame.payload)
+    const target = parseTarget(request.target)
+    if (target === undefined || typeof request.gatewayId !== "string" || request.gatewayId !== client.gatewayId || !GATEWAY_ID.test(request.gatewayId) || typeof request.identifier !== "string" || !STABLE_IDENTIFIER.test(request.identifier) || typeof request.name !== "string" || request.name.length === 0 || request.name.length > 256 || client.principal === undefined) {
+      await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "INVALID_STREAM_OPEN"})
+      return
+    }
+    if (options.authorizeOpen({principal: client.principal, gatewayId: request.gatewayId, target}) !== true) {
+      rejectedOpens += 1
+      await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "TARGET_UNAUTHORIZED"})
+      return
+    }
+    const gatewayOwner = gateways.get(request.gatewayId)
+    const gateway = gatewayOwner?.physical
+    if (gateway === undefined || gateway.socket.destroyed || gateway.gatewayId !== request.gatewayId) {
+      rejectedOpens += 1
+      await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: gatewayOwner === undefined ? "UNKNOWN_GATEWAY_ID" : "GATEWAY_UNAVAILABLE"})
+      return
+    }
+    const gatewayStreamId = gateway.nextGatewayStreamId
+    if (gatewayStreamId > 0xffff_fffe || gateway.streams.size >= maxStreams) {
+      await sendControl(client, V3FrameType.RESET, frame.streamId, 0, {code: "GATEWAY_STREAM_LIMIT"})
+      return
+    }
+    gateway.nextGatewayStreamId += 2
+    /** @type {Bridge} */
+    const bridge = {
+      client,
+      clientStreamId: frame.streamId,
+      gateway,
+      gatewayStreamId,
+      identifier: request.identifier,
+      target,
+      state: "opening",
+      clientToGatewaySequence: 0,
+      gatewayToClientSequence: 0,
+      clientToGatewayAck: 0,
+      gatewayToClientAck: 0,
+      clientEnded: false,
+      gatewayEnded: false,
+      clientToGatewayCompressor: new AdaptiveCompressor(),
+      gatewayToClientCompressor: new AdaptiveCompressor()
+    }
+    client.streams.set(frame.streamId, bridge)
+    gateway.streams.set(gatewayStreamId, bridge)
+    bridges += 1
+    await sendControl(gateway, V3FrameType.OPEN, gatewayStreamId, 0, {identifier: request.identifier, name: request.name, target, initialWindow})
+  }
+
+  /** @param {HubPhysical} source - Frame source. @param {import('../protocol/v3-frame.js').V3Frame} frame - Stream frame. */
+  async function relayStreamFrame(source, frame) {
+    const bridge = source.streams.get(frame.streamId)
+    if (bridge === undefined) {
+      if (frame.type !== V3FrameType.CLOSE && frame.type !== V3FrameType.RESET) await sendControl(source, V3FrameType.RESET, frame.streamId, 0, {code: "UNKNOWN_STREAM"})
+      return
+    }
+    const fromClient = source === bridge.client
+    const destination = fromClient ? bridge.gateway : bridge.client
+    const destinationStreamId = fromClient ? bridge.gatewayStreamId : bridge.clientStreamId
+    if (frame.type === V3FrameType.OPENED) {
+      if (fromClient || bridge.state !== "opening" || frame.sequence !== 0) throw protocolError("UNEXPECTED_OPENED")
+      const detail = decodeV3Control(frame.payload)
+      if (detail.identifier !== bridge.identifier) throw protocolError("OPEN_IDENTIFIER_MISMATCH")
+      bridge.state = "open"
+      await sendControl(destination, V3FrameType.OPENED, destinationStreamId, 0, {identifier: bridge.identifier, initialWindow})
+      return
+    }
+    if (bridge.state === "opening" && frame.type !== V3FrameType.RESET) throw protocolError("STREAM_NOT_OPEN")
+    if (frame.type === V3FrameType.ACK) {
+      const maximum = fromClient ? bridge.gatewayToClientSequence : bridge.clientToGatewaySequence
+      const previous = fromClient ? bridge.gatewayToClientAck : bridge.clientToGatewayAck
+      if (!Number.isSafeInteger(frame.sequence) || frame.sequence < previous || frame.sequence > maximum) throw protocolError("INVALID_ACK")
+      if (fromClient) bridge.gatewayToClientAck = frame.sequence
+      else bridge.clientToGatewayAck = frame.sequence
+      if (bridge.state !== "closing") await sendControl(destination, V3FrameType.ACK, destinationStreamId, frame.sequence, {})
+      return
+    }
+    if (frame.type === V3FrameType.WINDOW) {
+      if (frame.sequence <= 0 || frame.sequence > initialWindow) throw protocolError("INVALID_WINDOW")
+      if (bridge.state !== "closing") await sendControl(destination, V3FrameType.WINDOW, destinationStreamId, frame.sequence, {})
+      return
+    }
+    if (bridge.state === "closing") {
+      if (frame.type === V3FrameType.DATA || frame.type === V3FrameType.END) {
+        closeBridge(bridge, "STREAM_CLOSING")
+        return
+      }
+      if (frame.type !== V3FrameType.CLOSE && frame.type !== V3FrameType.RESET) throw protocolError("STREAM_CLOSING")
+    }
+    if (frame.type === V3FrameType.DATA) {
+      if (fromClient ? bridge.clientEnded : bridge.gatewayEnded) throw protocolError("DATA_AFTER_END")
+      const raw = await decodeV3Data(frame, source.codec, options.compressionLimits)
+      if (raw.length === 0 || raw.length > maxFrameBytes) throw protocolError("FRAME_TOO_LARGE")
+      const expected = (fromClient ? bridge.clientToGatewaySequence : bridge.gatewayToClientSequence) + raw.length
+      if (frame.sequence !== expected) throw protocolError("SEQUENCE_GAP")
+      if (fromClient) bridge.clientToGatewaySequence = frame.sequence
+      else bridge.gatewayToClientSequence = frame.sequence
+      const encoded = await encodeV3Data(raw, destination.codec, fromClient ? bridge.clientToGatewayCompressor : bridge.gatewayToClientCompressor, options.compressionLimits)
+      rawDataBytes += encoded.rawBytes
+      wireDataBytes += encoded.wireBytes
+      const delivered = await writeSocket(destination.socket, encodeV3Frame({type: V3FrameType.DATA, streamId: destinationStreamId, sequence: frame.sequence, flags: encoded.flags}, encoded.payload))
+      if (!delivered) closeBridge(bridge, "DESTINATION_CLOSED", source)
+      return
+    }
+    if (frame.type === V3FrameType.END) {
+      const expected = fromClient ? bridge.clientToGatewaySequence : bridge.gatewayToClientSequence
+      if (frame.sequence !== expected || (fromClient ? bridge.clientEnded : bridge.gatewayEnded)) throw protocolError("INVALID_END")
+      if (fromClient) bridge.clientEnded = true
+      else bridge.gatewayEnded = true
+      bridge.state = "half-closed"
+      await sendControl(destination, V3FrameType.END, destinationStreamId, frame.sequence, {})
+      return
+    }
+    if (frame.type === V3FrameType.CLOSE || frame.type === V3FrameType.RESET) {
+      const expected = fromClient ? bridge.clientToGatewaySequence : bridge.gatewayToClientSequence
+      if ((frame.type === V3FrameType.CLOSE && frame.sequence !== expected) || (frame.type === V3FrameType.RESET && frame.sequence !== 0)) throw protocolError("INVALID_STREAM_CLOSE")
+      const detail = frame.payload.length === 0 ? {} : decodeV3Control(frame.payload)
+      await sendControl(destination, frame.type, destinationStreamId, frame.sequence, detail)
+      if (frame.type === V3FrameType.RESET || fromClient) removeBridge(bridge)
+      else bridge.state = "closing"
+      return
+    }
+    throw protocolError("UNSUPPORTED_FRAME")
+  }
+
+  /** @param {Bridge} bridge - Stream. */
+  function removeBridge(bridge) {
+    const existed = bridge.client.streams.delete(bridge.clientStreamId)
+    bridge.gateway.streams.delete(bridge.gatewayStreamId)
+    if (existed) bridges = Math.max(0, bridges - 1)
+  }
+
+  /** @param {Bridge} bridge - Stream. @param {string} code - Reset code. @param {HubPhysical} [excluded] - Already-dead peer. */
+  function closeBridge(bridge, code, excluded) {
+    if (bridge.client !== excluded && !bridge.client.socket.destroyed) void sendControl(bridge.client, V3FrameType.RESET, bridge.clientStreamId, 0, {code})
+    if (bridge.gateway !== excluded && !bridge.gateway.socket.destroyed) void sendControl(bridge.gateway, V3FrameType.RESET, bridge.gatewayStreamId, 0, {code})
+    removeBridge(bridge)
+  }
+
+  /** @param {HubPhysical} physical - Connection. @param {string} code - Reason. */
+  function terminate(physical, code) {
+    if (physical.closing) return
+    physical.closing = true
+    const forceTimer = setTimeout(() => physical.socket.destroy(), 1_000)
+    forceTimer.unref?.()
+    void sendControl(physical, V3FrameType.GOAWAY, 0, 0, {code}).finally(() => {
+      clearTimeout(forceTimer)
+      physical.socket.destroy()
+    })
+  }
+
+  /** @param {HubPhysical} physical - Closed connection. @param {string} code - Stream reset. */
+  function detachPhysical(physical, code) {
+    if (!physicals.delete(physical)) return
+    physical.closing = true
+    for (const bridge of [...physical.streams.values()]) closeBridge(bridge, physical.role === "gateway" ? "GATEWAY_DISCONNECTED" : code, physical)
+    if (physical.gatewayId !== undefined) {
+      const owner = gateways.get(physical.gatewayId)
+      if (physical.role === "gateway" && owner?.physical === physical) {
+        owner.physical = undefined
+        for (const client of [...physicals]) {
+          if (client.role === "client" && client.gatewayId === physical.gatewayId) terminate(client, "GATEWAY_DISCONNECTED")
+        }
+      }
+    }
+    if (physical.role === "client" && physical.connectionId !== undefined) {
+      const owner = clients.get(physical.connectionId)
+      if (owner?.physical === physical) owner.physical = undefined
+    }
+  }
+
+  /** @param {HubPhysical} physical - Destination. @param {number} type - Frame type. @param {number} streamId - Stream ID. @param {number} sequence - Sequence. @param {Record<string, unknown>} value - Control body. */
+  async function sendControl(physical, type, streamId, sequence, value) {
+    return await writeSocket(physical.socket, encodeV3Frame({type, streamId, sequence}, encodeV3Control(value)))
+  }
+
+  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) })
+  })
+  const address = server.address()
+  if (address === null || typeof address === "string") throw new Error("Reverse gateway hub did not bind to a TCP port")
+
+  return {
+    server,
+    port: address.port,
+    status: () => ({
+      physicalAccepts,
+      physicalConnections: tcpSockets.size,
+      gatewayPhysicalConnections: [...physicals].filter((physical) => physical.role === "gateway" && physical.gatewayId !== undefined).length,
+      clientPhysicalConnections: [...physicals].filter((physical) => physical.role === "client" && physical.authenticated).length,
+      retainedClientIdentities: clients.size,
+      registeredGateways: gateways.size,
+      healthyGateways: [...gateways.values()].filter((owner) => owner.physical !== undefined).length,
+      gatewayRegistrations,
+      rejectedRegistrations,
+      rejectedOpens,
+      virtualStreams: bridges,
+      rawDataBytes,
+      wireDataBytes,
+      compressionBytesSaved: Math.max(0, rawDataBytes - wireDataBytes)
+    }),
+    closeActiveGateway: async (/** @type {string} */ gatewayId) => {
+      const physical = gateways.get(gatewayId)?.physical
+      if (physical === undefined) return
+      await new Promise((resolve) => { physical.socket.once("close", resolve); physical.socket.destroy() })
+    },
+    close: async () => {
+      if (closing) return
+      closing = true
+      for (const {socket} of pendingTls.values()) socket.destroy()
+      for (const physical of [...physicals]) terminate(physical, "HUB_SHUTDOWN")
+      await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve(undefined)))
+      gateways.clear()
+      clients.clear()
+    }
+  }
+}
+
+/** @param {import('node:net').Socket} socket - TCP or TLS socket. */
+function socketKey(socket) {
+  return `${socket.remoteAddress}\0${socket.remotePort}\0${socket.localAddress}\0${socket.localPort}`
+}
+
+/** @param {ReverseGatewayHubOptions} options - Options. */
+function validateOptions(options) {
+  if (typeof options !== "object" || options === null || options.tokens === undefined || typeof options.tokens.authenticate !== "function") throw new TypeError("Reverse gateway hub requires a token authenticator")
+  if (typeof options.authorizeGateway !== "function" || typeof options.authorizeClientGateway !== "function" || typeof options.authorizeOpen !== "function") throw new TypeError("Reverse gateway hub requires gateway, client selection, and open authorization policies")
+  if (typeof options.tls !== "object" || options.tls === null || typeof options.tls.certFile !== "string" || typeof options.tls.keyFile !== "string") throw new TypeError("Reverse gateway hub requires TLS certFile and keyFile")
+  if (!zstdAvailable()) throw new Error("Reverse gateway hub requires Node.js zstd support")
+  if (options.knownGatewayIds !== undefined && (!Array.isArray(options.knownGatewayIds) || options.knownGatewayIds.some((gatewayId) => typeof gatewayId !== "string" || !GATEWAY_ID.test(gatewayId)) || new Set(options.knownGatewayIds).size !== options.knownGatewayIds.length)) throw new TypeError("knownGatewayIds must contain unique valid gateway IDs")
+  const frame = positiveInteger(options.maxFrameBytes, "maxFrameBytes", DEFAULT_FRAME_BYTES)
+  const window = positiveInteger(options.initialWindowBytes, "initialWindowBytes", DEFAULT_WINDOW)
+  if (frame > window) throw new RangeError("maxFrameBytes must not exceed initialWindowBytes")
+}

package/src/reverse/index.js

@@ -0,0 +1,3 @@
+export {createReverseGatewayConnection, ReverseGatewayConnection} from "./client.js"
+export {createOutboundReverseGateway, OutboundReverseGateway} from "./gateway.js"
+export {startReverseGatewayHub} from "./hub.js"

package/src/reverse/runtime.js

@@ -0,0 +1,78 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
+import {StaticTokenStore} from "../auth/static-token-store.js"
+import {OutboundReverseGateway} from "./gateway.js"
+import {startReverseGatewayHub} from "./hub.js"
+
+/** @param {import('../config/environment.js').RelayEnvironmentConfig} config - Parsed environment. */
+export async function startReverseHubRuntime(config) {
+  if (config.mode !== "reverse-hub") throw new Error("Reverse hub runtime requires SOCKETDUCT_MODE=reverse-hub")
+  if (config.relayTls === undefined) throw new Error("Reverse hub mode requires SOCKETDUCT_TLS_CERT_FILE and SOCKETDUCT_TLS_KEY_FILE")
+  if (config.authTokens.length === 0) throw new Error("SOCKETDUCT_AUTH_TOKENS must contain hub client and gateway credentials")
+  if (config.reverseGatewayBindings === undefined || config.reverseGatewayBindings.length === 0) throw new Error("SOCKETDUCT_REVERSE_GATEWAY_BINDINGS must bind at least one gateway ID to a credential username")
+  if (config.reverseRoutes === undefined || config.reverseRoutes.length === 0) throw new Error("SOCKETDUCT_REVERSE_ROUTES must allow at least one client/gateway/target route")
+  if (config.compression === "off") throw new Error("Reverse hub mode requires SOCKETDUCT_COMPRESSION=auto")
+  const bindings = new Map(config.reverseGatewayBindings.map((binding) => [binding.gatewayId, binding.username]))
+  const routes = new Set(config.reverseRoutes.map((route) => formatRoute(route.username, route.gatewayId, {host: route.host, port: route.port})))
+  const selections = new Set(config.reverseRoutes.map((route) => `${route.username}\0${route.gatewayId}`))
+  if (bindings.size !== config.reverseGatewayBindings.length) throw new Error("SOCKETDUCT_REVERSE_GATEWAY_BINDINGS contains a duplicate gateway ID")
+  if (routes.size !== config.reverseRoutes.length) throw new Error("SOCKETDUCT_REVERSE_ROUTES contains a duplicate route")
+  const relayTls = config.relayTls
+  const tls = {
+    certFile: relayTls.certFile,
+    keyFile: relayTls.keyFile,
+    ...(relayTls.clientCaFile === undefined ? {} : {clientCaFile: relayTls.clientCaFile})
+  }
+  const hub = await startReverseGatewayHub({
+    host: config.relayHost,
+    port: config.relayPort,
+    tls,
+    tokens: new StaticTokenStore(config.authTokens),
+    knownGatewayIds: [...bindings.keys()],
+    authorizeGateway: ({principal, gatewayId}) => bindings.get(gatewayId) === principal.username,
+    authorizeClientGateway: ({principal, gatewayId}) => selections.has(`${principal.username}\0${gatewayId}`),
+    authorizeOpen: ({principal, gatewayId, target}) => routes.has(formatRoute(principal.username, gatewayId, target)),
+    handshakeTimeoutMs: config.handshakeTimeoutMs,
+    maxInputBytesPerConnection: config.maxInputBytesPerConnection,
+    compressionLimits: compressionLimits(config)
+  })
+  return {hub, close: hub.close}
+}
+
+/** @param {import('../config/environment.js').RelayEnvironmentConfig} config - Parsed environment. @param {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional structured logger. */
+export async function startOutboundReverseGatewayRuntime(config, logger) {
+  if (config.mode !== "reverse-gateway") throw new Error("Outbound gateway runtime requires SOCKETDUCT_MODE=reverse-gateway")
+  if (config.reverseGatewayId === undefined || config.reverseGatewayId.length === 0) throw new Error("SOCKETDUCT_REVERSE_GATEWAY_ID is required")
+  if (config.reverseConnectionId === undefined || config.reverseConnectionId.length === 0) throw new Error("SOCKETDUCT_REVERSE_CONNECTION_ID is required")
+  if (config.reverseHub === undefined || config.reverseHub.host.length === 0 || config.reverseHub.token.length === 0) throw new Error("SOCKETDUCT_REVERSE_HUB_HOST and SOCKETDUCT_REVERSE_TOKEN are required")
+  if (config.targetAllowlist.length === 0) throw new Error("SOCKETDUCT_TARGET_ALLOWLIST must contain at least one local gateway target")
+  if (config.compression === "off") throw new Error("Reverse gateway mode requires SOCKETDUCT_COMPRESSION=auto")
+  const targets = new Set(config.targetAllowlist.map((target) => `${target.host}:${target.port}`))
+  const gateway = new OutboundReverseGateway({
+    gatewayId: config.reverseGatewayId,
+    connectionId: config.reverseConnectionId,
+    hub: config.reverseHub,
+    tls: config.reverseHubTls ?? {},
+    authorizeTarget: (target) => targets.has(`${target.host}:${target.port}`),
+    ...(config.initialTargetConnectTimeoutMs === undefined ? {} : {targetConnectTimeoutMs: config.initialTargetConnectTimeoutMs}),
+    maxStreamBufferBytes: config.maxTargetBufferBytes,
+    maxTotalBufferBytes: config.maxTotalBufferBytes,
+    compressionLimits: compressionLimits(config),
+    ...(logger === undefined ? {} : {logger})
+  })
+  await gateway.start()
+  return {gateway, close: () => gateway.close()}
+}
+
+/** @param {string} username - Client. @param {string} gatewayId - Gateway. @param {{host: string, port: number}} target - Target. */
+function formatRoute(username, gatewayId, target) {
+  return `${username}\0${gatewayId}\0${target.host}\0${target.port}`
+}
+
+/** @param {import('../config/environment.js').RelayEnvironmentConfig} config - Runtime limits. @returns {import('../protocol/compression.js').CompressionLimits} Defined codec limits. */
+function compressionLimits(config) {
+  return {
+    ...(config.minCompressBytes === undefined ? {} : {minCompressBytes: config.minCompressBytes}),
+    ...(config.maxDecompressedBytes === undefined ? {} : {maxDecompressedBytes: config.maxDecompressedBytes}),
+    ...(config.maxExpansionRatio === undefined ? {} : {maxExpansionRatio: config.maxExpansionRatio})
+  }
+}