socketduct 0.1.15

package/src/proxy/tcp-relay.js

@@ -0,0 +1,1191 @@
+import {createConnection, createServer} from "node:net"
+import {createServer as createTlsServer} from "node:tls"
+import {readFileSync} from "node:fs"
+
+import {AdaptiveCompressor, availableCodecs, decodeStreamPayload, encodeStreamPayload, getMaxDecompressedBytes} from "../protocol/compression.js"
+import {encodeCompactAck, encodeCompactData, encodeFrame, FrameDecoder} from "../protocol/frame.js"
+import {handleControlMessage} from "../server/control-handler.js"
+
+/**
+ * @typedef {import('../protocol/compression.js').CompressionLimits} CompressionLimits
+ * @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 {{sequence: number, chunk: Buffer}} SentChunk
+ * @typedef {object} TcpRelayOptions
+ * @property {string} [host] - Relay listen host.
+ * @property {number} [port] - Relay listen port.
+ * @property {number} [resumeWindowMs] - How long to keep session target sockets after tunnel drops.
+ * @property {number} [maxReplayBytes] - Maximum bytes of unacknowledged target-to-client data retained for replay. Default 16 MiB.
+ * @property {number} [maxTargetBufferBytes] - Per-session byte limit for buffered target data while the tunnel is detached. Default 1 MiB.
+ * @property {number} [maxTotalBufferBytes] - Process-wide byte limit for buffered target data across all sessions. Default 16 MiB.
+ * @property {number} [initialTargetRetryDelayMs] - Initial target acquisition retry delay. Default 250ms.
+ * @property {number} [initialTargetRetryMaxDelayMs] - Maximum initial target acquisition retry delay. Default 5000ms.
+ * @property {number} [initialTargetConnectTimeoutMs] - Maximum time for one initial target TCP connect attempt. Default 10000ms.
+ * @property {number} [handshakeTimeoutMs] - Milliseconds to wait for auth after TCP/TLS connect before closing the socket. Default 10000.
+ * @property {number} [maxInputBytesPerConnection] - Per-connection input byte budget before the first authenticated session frame. Default 65536.
+ * @property {boolean} [compressionEnabled] - Whether to negotiate stream.data compression when the runtime supports it. Default true.
+ * @property {CompressionLimits} [compressionLimits] - Compression size and expansion-ratio bounds.
+ * @property {(input: {principal: Principal, target: SessionTarget}) => boolean} authorizeTarget - Target authorization policy.
+ * @property {TokenAuthenticator} tokens - Token store.
+ * @property {SessionStore} sessions - Session store.
+ * @property {(options: {host: string, port: number}) => import('node:net').Socket} [createTargetConnection] - Target socket factory.
+ * @property {{certFile: string, keyFile: string, clientCaFile?: string}} [tls] - TLS configuration.
+ * @typedef {object} TcpRelayHandle
+ * @property {import('node:tls').Server | import('node:net').Server} server - Relay server.
+ * @property {number} port - Bound relay port.
+ * @property {() => {activeTunnels: number, activeTargets: number, sessions: number, attachedSessions: number, detachedSessions: number, bufferedTargetBytes: number, targetConnectionAttempts: number, targetRetryTimers: number}} status - Safe runtime counters.
+ * @property {() => Promise<void>} closeActiveTunnel - Closes active tunnel sockets after their relay-side close handlers ran.
+ * @property {() => Promise<void>} close - Close function.
+ */
+
+/** @typedef {{active: boolean, announced: boolean}} SessionLifecycle */
+
+/**
+ * @param {TcpRelayOptions} options - Relay options.
+ * @returns {Promise<TcpRelayHandle>} - Started relay.
+ */
+export async function startTcpRelay(options) {
+  /** @type {Set<import('node:net').Socket>} */
+  const tunnels = new Set()
+  /** @type {Map<import('node:net').Socket, {promise?: Promise<void>}>} */
+  const tunnelCloseSettlements = new Map()
+  /** @type {Set<import('node:net').Socket>} */
+  const targets = new Set()
+  /** @type {Map<string, import('node:net').Socket>} */
+  const sessionTargets = new Map()
+  /** @type {Map<string, import('node:net').Socket>} */
+  const sessionInitialTargetAttempts = new Map()
+  /** @type {Map<string, ReturnType<typeof setTimeout>>} */
+  const sessionInitialTargetRetryTimers = new Map()
+  /** @type {Map<string, ReturnType<typeof setTimeout>>} */
+  const sessionInitialTargetConnectTimers = new Map()
+  /**
+   * Active tunnel send functions, one per session. Each session has at most one
+   * owning tunnel at a time. On resume the new tunnel's sendFrame replaces the
+   * old one atomically.
+   *
+   * **Sender-capture rule**: functions that deliver target data MUST capture
+   * the sender from this map at enqueue time, not at delivery time, because
+   * `queueSessionSend` defers execution. A target data event observed with a
+   * sender must use that sender; an event observed detached (sender undefined)
+   * must buffer. Resume replay/flush captures the resumed sender that owns its
+   * queued operation so stale work cannot adopt a later tunnel.
+   * @type {Map<string, (header: import('../protocol/frame.js').FrameHeader, payload?: Buffer) => Promise<boolean>>}
+   */
+  const sessionSenders = new Map()
+  /** @type {Map<string, Buffer[]>} */
+  const sessionTargetBuffers = new Map()
+  /** @type {Map<string, SentChunk[]>} */
+  const sessionTargetSentChunks = new Map()
+  /** @type {Map<string, ReturnType<typeof setTimeout>>} */
+  const sessionTargetExpiryTimers = new Map()
+  /** @type {Map<string, import('../protocol/frame.js').FrameHeader>} */
+  const sessionTargetTerminalState = new Map()
+
+  /** @type {Map<string, number>} */
+  const sessionPendingClientSequence = new Map()
+
+  /** Codec negotiated on the connection currently serving each session. */
+  /** @type {Map<string, string>} */
+  const sessionSendCodec = new Map()
+
+  /** @type {Map<string, AdaptiveCompressor>} */
+  const sessionCompressor = new Map()
+
+  /** @type {Map<string, {tail: Promise<void>}>} */
+  const sessionSendQueue = new Map()
+
+  /** @type {Map<string, {lifecycle: SessionLifecycle, sender: (header: import('../protocol/frame.js').FrameHeader, payload?: Buffer) => Promise<boolean>, chunks: Buffer[], bytes: number}>} */
+  const sessionQueuedTargetBatch = new Map()
+
+  /** Object identity prevents stale async work from attaching to a reused identifier. */
+  /** @type {Map<string, SessionLifecycle>} */
+  const sessionLifecycles = new Map()
+
+  /** @type {Map<string, number>} */
+  const sessionTargetBufferBytes = new Map()
+  let totalProcessBufferBytes = 0
+
+  const compressionLimits = options.compressionLimits ?? {}
+  getMaxDecompressedBytes(compressionLimits)
+  const supportedCodecs = options.compressionEnabled === false ? [] : availableCodecs()
+
+  const maxReplayBytes = options.maxReplayBytes ?? (16 * 1024 * 1024)
+  const maxTargetBufferBytes = options.maxTargetBufferBytes ?? (1_048_576)
+  const maxTotalBufferBytes = options.maxTotalBufferBytes ?? (16_777_216)
+  const initialTargetRetryDelayMs = options.initialTargetRetryDelayMs ?? 250
+  const initialTargetRetryMaxDelayMs = options.initialTargetRetryMaxDelayMs ?? 5_000
+  const initialTargetConnectTimeoutMs = options.initialTargetConnectTimeoutMs ?? 10_000
+  const createTargetConnection = options.createTargetConnection ?? ((target) => createConnection(target))
+  const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 10_000
+  const maxInputBytesPerConnection = options.maxInputBytesPerConnection ?? 65_536
+  if (!Number.isSafeInteger(initialTargetRetryDelayMs) || initialTargetRetryDelayMs <= 0) {
+    throw new Error("initialTargetRetryDelayMs must be a positive integer")
+  }
+  if (!Number.isSafeInteger(initialTargetRetryMaxDelayMs) || initialTargetRetryMaxDelayMs < initialTargetRetryDelayMs) {
+    throw new Error("initialTargetRetryMaxDelayMs must be an integer greater than or equal to initialTargetRetryDelayMs")
+  }
+  if (!Number.isSafeInteger(initialTargetConnectTimeoutMs) || initialTargetConnectTimeoutMs <= 0) {
+    throw new Error("initialTargetConnectTimeoutMs must be a positive integer")
+  }
+  let closing = false
+
+  const tlsEnabled = options.tls !== undefined
+  /** @type {{cert: Buffer, key: Buffer, ca?: Buffer} | undefined} */
+  let tlsContext
+  if (tlsEnabled) {
+    const tlsOptions = /** @type {NonNullable<typeof options.tls>} */ (options.tls)
+    tlsContext = {
+      cert: readFileSync(tlsOptions.certFile),
+      key: readFileSync(tlsOptions.keyFile)
+    }
+    if (tlsOptions.clientCaFile !== undefined) {
+      tlsContext.ca = readFileSync(tlsOptions.clientCaFile)
+    }
+  }
+
+  /** @type {(identifier: string) => void} */
+  const clearSessionTargetExpiry = (identifier) => {
+    const timer = sessionTargetExpiryTimers.get(identifier)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      sessionTargetExpiryTimers.delete(identifier)
+    }
+  }
+
+  /** @type {(identifier: string) => void} */
+  const clearInitialTargetRetry = (identifier) => {
+    const timer = sessionInitialTargetRetryTimers.get(identifier)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      sessionInitialTargetRetryTimers.delete(identifier)
+    }
+  }
+
+  /** @type {(identifier: string) => void} */
+  const clearInitialTargetConnectTimeout = (identifier) => {
+    const timer = sessionInitialTargetConnectTimers.get(identifier)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      sessionInitialTargetConnectTimers.delete(identifier)
+    }
+  }
+
+  /** @type {(identifier: string) => void} */
+  const destroyInitialTargetAttempt = (identifier) => {
+    clearInitialTargetRetry(identifier)
+    clearInitialTargetConnectTimeout(identifier)
+    const attempt = sessionInitialTargetAttempts.get(identifier)
+    sessionInitialTargetAttempts.delete(identifier)
+    if (attempt !== undefined) {
+      attempt.removeAllListeners()
+      attempt.destroy()
+    }
+  }
+
+  /** @type {(identifier: string) => void} */
+  const destroySessionTarget = (identifier) => {
+    destroyInitialTargetAttempt(identifier)
+    const lifecycle = sessionLifecycles.get(identifier)
+    if (lifecycle !== undefined) {
+      lifecycle.active = false
+      sessionLifecycles.delete(identifier)
+    }
+    clearSessionTargetExpiry(identifier)
+    const bufferBytes = sessionTargetBufferBytes.get(identifier) ?? 0
+    if (bufferBytes > 0) {
+      totalProcessBufferBytes -= bufferBytes
+      sessionTargetBufferBytes.delete(identifier)
+    }
+    sessionTargetBuffers.delete(identifier)
+    sessionTargetSentChunks.delete(identifier)
+    sessionTargetTerminalState.delete(identifier)
+    sessionPendingClientSequence.delete(identifier)
+    sessionSendCodec.delete(identifier)
+    sessionCompressor.delete(identifier)
+    sessionSendQueue.delete(identifier)
+    sessionQueuedTargetBatch.delete(identifier)
+    const sessionTarget = sessionTargets.get(identifier)
+    sessionTargets.delete(identifier)
+    if (sessionTarget !== undefined) {
+      targets.delete(sessionTarget)
+      sessionTarget.removeAllListeners()
+      sessionTarget.destroy()
+    }
+  }
+
+  /** @type {(identifier: string, ackSequence: number) => void} */
+  const acknowledgeTargetData = (identifier, ackSequence) => {
+    const chunks = sessionTargetSentChunks.get(identifier)
+    if (chunks === undefined || chunks.length === 0) {
+      return
+    }
+    const remaining = chunks.filter((entry) => entry.sequence > ackSequence)
+    if (remaining.length === 0) {
+      sessionTargetSentChunks.delete(identifier)
+    } else {
+      sessionTargetSentChunks.set(identifier, remaining)
+    }
+  }
+
+  /** @type {(identifier: string) => number} */
+  const currentReplayBytes = (identifier) => {
+    const chunks = sessionTargetSentChunks.get(identifier)
+    if (chunks === undefined) {
+      return 0
+    }
+    return chunks.reduce((sum, entry) => sum + entry.chunk.length, 0)
+  }
+
+  /**
+   * Encodes one target-to-client chunk for the wire. Retained replay chunks stay
+   * raw, so a replayed frame is re-encoded under whatever codec the current
+   * connection negotiated (including none).
+   * @type {(identifier: string, lifecycle: SessionLifecycle, sender: (header: import('../protocol/frame.js').FrameHeader, payload?: Buffer) => Promise<boolean>, sequence: number, chunk: Buffer) => Promise<boolean>}
+   */
+  const sendStreamData = async (identifier, lifecycle, sender, sequence, chunk) => {
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) {
+      return false
+    }
+    const codec = sessionSendCodec.get(identifier)
+    const encoded = await encodeStreamPayload(chunk, codec, sessionCompressor.get(identifier), compressionLimits)
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) {
+      return false
+    }
+    /** @type {import('../protocol/frame.js').FrameHeader} */
+    const header = {type: "stream.data", direction: "target-to-client", sequence}
+    if (encoded.encoding !== undefined) {
+      header.encoding = encoded.encoding
+      header.dataLength = encoded.dataLength
+    }
+    // A close while awaiting socket drain does not discard bytes already
+    // observed with this captured sender: retain them for replay on resume.
+    await sender(header, encoded.payload)
+    return lifecycle.active && sessionLifecycles.get(identifier) === lifecycle
+  }
+
+  /**
+   * Replays all unacknowledged target-to-client chunks for a session. Called
+   * on resume inside the session send queue after the sender has been
+   * registered. The resume operation supplies its owning sender so stale work
+   * cannot adopt a later tunnel after a second disconnect.
+   * @param {string} identifier - Session identifier.
+   * @param {SessionLifecycle} lifecycle - Current live session lifecycle.
+   * @param {(header: import('../protocol/frame.js').FrameHeader, payload?: Buffer) => Promise<boolean>} sender - Sender owned by this resume operation.
+   * @returns {Promise<void>} - Resolves after all replays are sent.
+   */
+  const replayUnackedTargetData = async (identifier, lifecycle, sender) => {
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle || sessionSenders.get(identifier) !== sender) {
+      return
+    }
+    const chunks = sessionTargetSentChunks.get(identifier)
+    if (chunks === undefined || chunks.length === 0) {
+      return
+    }
+    for (const entry of chunks) {
+      if (!await sendStreamData(identifier, lifecycle, sender, entry.sequence, entry.chunk)) {
+        return
+      }
+    }
+  }
+
+  /** @type {(identifier: string) => void} */
+  const expireSessionTargetLater = (identifier) => {
+    clearSessionTargetExpiry(identifier)
+    const lifecycle = sessionLifecycles.get(identifier)
+    const timer = setTimeout(() => {
+      if (lifecycle === undefined || !lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) {
+        return
+      }
+      sessionTargetExpiryTimers.delete(identifier)
+      destroySessionTarget(identifier)
+      try {
+        if (options.sessions.get(identifier) !== undefined) {
+          options.sessions.transition(identifier, "expired")
+        }
+      } catch {
+        // session already in a terminal state
+      }
+      options.sessions.delete(identifier)
+    }, options.resumeWindowMs ?? 30_000)
+    sessionTargetExpiryTimers.set(identifier, timer)
+  }
+
+  /**
+   * Serializes all target-to-client encoding, replay, and delivery work for a
+   * session. Zstd runs asynchronously, so this queue — not callback completion
+   * order — defines the protocol's uncompressed sequence order.
+   *
+   * **Sender-capture rule**: because operations are deferred through this queue,
+   * callers that deliver target data MUST capture the sender from
+   * `sessionSenders` before calling this function, not inside the queued
+   * operation. Otherwise a queued operation could observe a different tunnel's
+   * sender after a disconnect/resume cycle.
+   * @param {string} identifier - Session identifier.
+   * @param {() => Promise<void>} operation - One ordered operation.
+   * @returns {Promise<void>} - Resolves after the operation completes.
+   */
+  const queueSessionSend = (identifier, operation) => {
+    const queue = sessionSendQueue.get(identifier)
+    // Start an idle queue synchronously. Async compression may yield, but a sole
+    // target chunk is never held merely to see whether another chunk arrives.
+    const next = queue === undefined
+      ? Promise.resolve(operation())
+      : queue.tail.then(operation)
+    const state = {tail: next.catch(() => {})}
+    sessionSendQueue.set(identifier, state)
+    state.tail.finally(() => {
+      if (sessionSendQueue.get(identifier) === state) sessionSendQueue.delete(identifier)
+    })
+    return next
+  }
+
+  /**
+   * Persists a target terminal result before placing its delivery behind any
+   * queued data. The first terminal result wins (notably, error before close),
+   * and the state remains resumable until normal session destruction/expiry.
+   * @param {string} identifier - Session identifier.
+   * @param {SessionLifecycle} lifecycle - Lifecycle captured by the target.
+   * @param {import('../protocol/frame.js').FrameHeader} terminal - Terminal frame.
+   */
+  const persistAndQueueTargetTerminal = (identifier, lifecycle, terminal) => {
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle || sessionTargetTerminalState.has(identifier)) return
+    sessionTargetTerminalState.set(identifier, terminal)
+    const sender = sessionSenders.get(identifier)
+    if (sender === undefined) return
+    void queueSessionSend(identifier, async () => {
+      if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle ||
+          sessionSenders.get(identifier) !== sender || sessionTargetTerminalState.get(identifier) !== terminal) return
+      await sender(terminal)
+    })
+  }
+
+  /**
+   * Enqueues one target-to-client chunk for ordered delivery. Captures the
+   * current sender at enqueue time so the queued operation cannot later read
+   * a different tunnel's sender after a disconnect/resume cycle. When the
+   * session is detached (sender undefined) the chunk will be buffered.
+   * @param {string} identifier - Session identifier.
+   * @param {SessionLifecycle} lifecycle - Lifecycle captured by the target socket.
+   * @param {Buffer} chunk - Raw target data chunk.
+   * @returns {Promise<void>} - Resolves after the chunk is delivered or buffered.
+   */
+  const deliverTargetChunk = (identifier, lifecycle, chunk) => {
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) {
+      return Promise.resolve()
+    }
+    const sender = sessionSenders.get(identifier)
+    if (sender === undefined) {
+      bufferDetachedTargetChunk(identifier, lifecycle, chunk)
+      return Promise.resolve()
+    }
+
+    const maxBytes = getMaxDecompressedBytes(compressionLimits)
+    if (chunk.length > maxBytes) {
+      const deliveries = []
+      for (let offset = 0; offset < chunk.length; offset += maxBytes) {
+        deliveries.push(deliverTargetChunk(identifier, lifecycle, chunk.subarray(offset, Math.min(offset + maxBytes, chunk.length))))
+      }
+      return Promise.all(deliveries).then(() => {})
+    }
+    const queuedBatch = sessionQueuedTargetBatch.get(identifier)
+    if (sessionSendQueue.has(identifier) && queuedBatch !== undefined &&
+        queuedBatch.lifecycle === lifecycle && queuedBatch.sender === sender &&
+        queuedBatch.bytes + chunk.length <= maxBytes) {
+      // Copy while the target's data callback still owns the bytes. This batch
+      // exists only because earlier async send/compression work is in flight.
+      queuedBatch.chunks.push(Buffer.from(chunk))
+      queuedBatch.bytes += chunk.length
+      return sessionSendQueue.get(identifier)?.tail ?? Promise.resolve()
+    }
+
+    if (sessionSendQueue.has(identifier)) {
+      const batch = {lifecycle, sender, chunks: [Buffer.from(chunk)], bytes: chunk.length}
+      sessionQueuedTargetBatch.set(identifier, batch)
+      return queueSessionSend(identifier, async () => {
+        if (sessionQueuedTargetBatch.get(identifier) === batch) sessionQueuedTargetBatch.delete(identifier)
+        const merged = batch.chunks.length === 1 ? batch.chunks[0] : Buffer.concat(batch.chunks, batch.bytes)
+        if (merged !== undefined) await deliverTargetChunkNow(identifier, lifecycle, merged, sender)
+      })
+    }
+
+    return queueSessionSend(identifier, async () => {
+      await deliverTargetChunkNow(identifier, lifecycle, chunk, sender)
+    })
+  }
+
+  /**
+   * Copies, charges and admits detached target data synchronously, before any
+   * earlier asynchronous send in the ordered queue can complete.
+   * @param {string} identifier
+   * @param {SessionLifecycle} lifecycle
+   * @param {Buffer} chunk
+   */
+  const bufferDetachedTargetChunk = (identifier, lifecycle, chunk) => {
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) return
+
+    const chunkCopy = Buffer.from(chunk)
+    const previousSessionBytes = sessionTargetBufferBytes.get(identifier) ?? 0
+    const newSessionBytes = previousSessionBytes + chunkCopy.length
+    const perSessionOverflow = newSessionBytes > maxTargetBufferBytes
+    const newTotalBytes = totalProcessBufferBytes + chunkCopy.length
+    const totalOverflow = newTotalBytes > maxTotalBufferBytes
+
+    if (perSessionOverflow || totalOverflow) {
+      if (previousSessionBytes > 0) totalProcessBufferBytes -= previousSessionBytes
+      sessionTargetBufferBytes.delete(identifier)
+      sessionTargetBuffers.delete(identifier)
+      const terminalError = perSessionOverflow
+        ? {type: "error", code: "TARGET_BUFFER_OVERFLOW", message: `Session target-to-client buffer exceeded the per-session limit of ${maxTargetBufferBytes} bytes while the tunnel was detached.`, retryable: false}
+        : {type: "error", code: "TARGET_BUFFER_OVERFLOW", message: `Process-wide target-to-client buffer exceeded the limit of ${maxTotalBufferBytes} bytes while the tunnel was detached.`, retryable: false}
+      sessionTargetTerminalState.set(identifier, terminalError)
+      const sessionTarget = sessionTargets.get(identifier)
+      sessionTarget?.destroy()
+      sessionTargets.delete(identifier)
+      clearSessionTargetExpiry(identifier)
+      return
+    }
+
+    totalProcessBufferBytes = newTotalBytes
+    sessionTargetBufferBytes.set(identifier, newSessionBytes)
+    const buffer = sessionTargetBuffers.get(identifier) ?? []
+    buffer.push(chunkCopy)
+    sessionTargetBuffers.set(identifier, buffer)
+  }
+
+  /**
+   * Delivers (or buffers) one target-to-client chunk. The sender must be
+   * captured by the caller at enqueue time — see {@link deliverTargetChunk}.
+   *
+   * When the captured sender is undefined the chunk is buffered and will be
+   * flushed later by {@link flushBufferedTargetChunksNow} on resume. When a
+   * sender is present the chunk is encoded, sent, and retained for replay.
+   * @param {string} identifier - Session identifier.
+   * @param {SessionLifecycle} lifecycle - Lifecycle captured by the target socket.
+   * @param {Buffer} chunk - Raw target data chunk.
+   * @param {((header: import('../protocol/frame.js').FrameHeader, payload?: Buffer) => Promise<boolean>) | undefined} sender - Captured sender (undefined if detached).
+   * @returns {Promise<boolean>} - True when the chunk entered replay retention.
+   */
+  async function deliverTargetChunkNow(identifier, lifecycle, chunk, sender) {
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle || sender === undefined) {
+      return false
+    }
+
+    // Sequences, replay retention and every byte limit stay in uncompressed units.
+    const current = options.sessions.get(identifier)?.relaySequence ?? 0
+    const nextRelaySequence = current + chunk.length
+    if (!await sendStreamData(identifier, lifecycle, sender, nextRelaySequence, chunk)) return false
+
+    // Do not move protocol state until async encoding has completed successfully.
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle || options.sessions.get(identifier) === undefined) return false
+    options.sessions.updateSequences(identifier, {relaySequence: nextRelaySequence})
+
+    const sentChunks = sessionTargetSentChunks.get(identifier) ?? []
+    sentChunks.push({sequence: nextRelaySequence, chunk: Buffer.from(chunk)})
+    sessionTargetSentChunks.set(identifier, sentChunks)
+
+    const newTotal = currentReplayBytes(identifier)
+    if (newTotal > maxReplayBytes) {
+      const sessionTarget = sessionTargets.get(identifier)
+      const terminalError = {type: "error", code: "SPOOL_TOO_LARGE", message: "Unacknowledged replay buffer exceeded maximum size.", retryable: false}
+      sender(terminalError)
+      sessionTargetTerminalState.set(identifier, terminalError)
+      sessionTarget?.destroy()
+      sessionTargets.delete(identifier)
+      clearSessionTargetExpiry(identifier)
+    }
+    return true
+  }
+
+  /**
+   * Flushes all buffered target-to-client chunks for a session. Called on
+   * resume after replay with the sender owned by that resume operation.
+   * @param {string} identifier - Session identifier.
+   * @param {SessionLifecycle} lifecycle - Current live session lifecycle.
+   * @param {(header: import('../protocol/frame.js').FrameHeader, payload?: Buffer) => Promise<boolean>} sender - Sender owned by this resume operation.
+   * @returns {Promise<void>} - Resolves after all buffered chunks are delivered.
+   */
+  const flushBufferedTargetChunksNow = async (identifier, lifecycle, sender) => {
+    if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle || sessionSenders.get(identifier) !== sender) return
+    const chunks = sessionTargetBuffers.get(identifier)
+    while (chunks !== undefined && chunks.length > 0) {
+      if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle || sessionSenders.get(identifier) !== sender) return
+      const chunk = chunks[0]
+      if (chunk === undefined || !await deliverTargetChunkNow(identifier, lifecycle, chunk, sender)) return
+
+      // Transfer ownership only after the chunk has entered replay retention.
+      // If the tunnel detaches before the next iteration, the remaining chunks
+      // and their accounting stay available for the following resume.
+      chunks.shift()
+      const previousSessionBytes = sessionTargetBufferBytes.get(identifier) ?? 0
+      const remainingSessionBytes = previousSessionBytes - chunk.length
+      totalProcessBufferBytes -= chunk.length
+      if (remainingSessionBytes > 0) {
+        sessionTargetBufferBytes.set(identifier, remainingSessionBytes)
+      } else {
+        sessionTargetBufferBytes.delete(identifier)
+        sessionTargetBuffers.delete(identifier)
+      }
+    }
+  }
+
+  const server = tlsEnabled
+    ? createTlsServer({
+      .../** @type {NonNullable<typeof tlsContext>} */ (tlsContext),
+      requestCert: tlsContext?.ca !== undefined,
+      rejectUnauthorized: true
+    }, (socket) => {
+      setupTunnel(socket)
+    })
+    : createServer((socket) => {
+      setupTunnel(socket)
+    })
+
+  /** @type {(socket: import('node:net').Socket) => void} */
+  function setupTunnel(socket) {
+    tunnels.add(socket)
+    /** @type {{promise?: Promise<void>}} */
+    const tunnelCloseSettlement = {}
+    tunnelCloseSettlements.set(socket, tunnelCloseSettlement)
+    const decoder = new FrameDecoder({maxInputBytes: maxInputBytesPerConnection, compactDirection: "client-to-target"})
+    let authenticatedSession = false
+    /** @type {string | undefined} */
+    let sessionIdentifier
+    /** @type {SessionLifecycle | undefined} */
+    let tunnelSessionLifecycle
+    /** Codec negotiated for this connection; undefined means uncompressed compact data. */
+    /** @type {string | undefined} */
+    let connectionCodec
+    /** @type {number | undefined} */
+    let connectionFraming
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let handshakeTimer
+
+    const clearHandshakeTimeout = () => {
+      if (handshakeTimer !== undefined) {
+        clearTimeout(handshakeTimer)
+        handshakeTimer = undefined
+      }
+    }
+
+    handshakeTimer = setTimeout(() => {
+      if (!authenticatedSession) {
+        const errorFrame = encodeFrame({type: "error", code: "HANDSHAKE_TIMEOUT", message: "Authentication not completed within the handshake deadline.", retryable: false})
+        try {
+          if (!socket.destroyed && socket.writable) {
+            socket.end(errorFrame)
+          }
+        } catch {
+          // socket may already be destroyed
+        }
+      }
+    }, handshakeTimeoutMs)
+
+    /** @type {(header: import('../protocol/frame.js').FrameHeader, payload?: Buffer) => Promise<boolean>} */
+    const sendFrame = (header, payload = Buffer.alloc(0)) => {
+      if (socket.destroyed || socket.writableEnded || !socket.writable) {
+        return Promise.resolve(false)
+      }
+
+      try {
+        let bytes
+        if ((header.type === "stream.data" || header.type === "stream.ack") && connectionFraming !== 2) {
+          throw new Error("Refusing to emit a non-compact stream record")
+        }
+        if (header.type === "stream.data") {
+          bytes = encodeCompactData({sequence: /** @type {number} */ (header.sequence), payload, ...(header.encoding === "zstd" ? {dataLength: /** @type {number} */ (header.dataLength)} : {})})
+        } else if (header.type === "stream.ack") {
+          bytes = encodeCompactAck(/** @type {number} */ (header.ackSequence))
+        } else {
+          bytes = encodeFrame(header, payload)
+        }
+        const writable = socket.write(bytes, (error) => {
+          if (error !== null && error !== undefined) {
+            socket.destroy(error)
+          }
+        })
+        if (writable) return Promise.resolve(true)
+        return new Promise((resolve) => {
+          const cleanup = () => {
+            socket.off("drain", onDrain)
+            socket.off("close", onClose)
+          }
+          const onDrain = () => {
+            cleanup()
+            resolve(true)
+          }
+          const onClose = () => {
+            cleanup()
+            resolve(false)
+          }
+          socket.once("drain", onDrain)
+          socket.once("close", onClose)
+        })
+      } catch (error) {
+        socket.destroy(error instanceof Error ? error : undefined)
+        return Promise.resolve(false)
+      }
+    }
+
+    /**
+     * Removes a session that never crossed the readiness/announcement boundary.
+     * Object identity prevents a stale tunnel callback from deleting a reused id.
+     * @param {string} identifier
+     * @param {SessionLifecycle} lifecycle
+     */
+    const deleteUnannouncedSession = (identifier, lifecycle) => {
+      if (lifecycle.announced || sessionLifecycles.get(identifier) !== lifecycle) return
+      destroySessionTarget(identifier)
+      sessionSenders.delete(identifier)
+      options.sessions.delete(identifier)
+      if (sessionIdentifier === identifier) {
+        sessionIdentifier = undefined
+        tunnelSessionLifecycle = undefined
+      }
+    }
+
+    /**
+     * Installs handlers for a target that has crossed the TCP connect boundary.
+     * Initial connection failures never enter this terminal target lifecycle.
+     * @param {string} identifier
+     * @param {SessionLifecycle} lifecycle
+     * @param {import('node:net').Socket} targetSocket
+     */
+    const attachConnectedTarget = (identifier, lifecycle, targetSocket) => {
+      targetSocket.on("data", (chunk) => {
+        void deliverTargetChunk(identifier, lifecycle, chunk).catch((error) => {
+          if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) return
+          const terminalError = {
+            type: "error",
+            code: "TARGET_CLOSED",
+            message: "Target-to-client delivery failed.",
+            retryable: false
+          }
+          persistAndQueueTargetTerminal(identifier, lifecycle, terminalError)
+          targetSocket.destroy(error instanceof Error ? error : undefined)
+        })
+      })
+      targetSocket.on("error", () => {
+        if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) return
+        targets.delete(targetSocket)
+        if (sessionTargets.get(identifier) === targetSocket) sessionTargets.delete(identifier)
+        if (!sessionTargetTerminalState.has(identifier)) {
+          persistAndQueueTargetTerminal(identifier, lifecycle, {
+            type: "error",
+            code: "TARGET_CLOSED",
+            message: "Target connection failed.",
+            retryable: false
+          })
+        }
+      })
+      targetSocket.on("close", () => {
+        targets.delete(targetSocket)
+        if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle) return
+        if (sessionTargets.get(identifier) === targetSocket) sessionTargets.delete(identifier)
+        if (!sessionTargetTerminalState.has(identifier)) {
+          persistAndQueueTargetTerminal(identifier, lifecycle, {type: "session.close", direction: "target-to-client"})
+        }
+      })
+    }
+
+    /**
+     * Starts one bounded-rate initial target acquisition loop for this tunnel.
+     * @param {string} identifier
+     * @param {SessionLifecycle} lifecycle
+     * @param {import('../protocol/frame.js').FrameHeader} createdResponse
+     */
+    const startInitialTargetAcquisition = (identifier, lifecycle, createdResponse) => {
+      let retryDelayMs = initialTargetRetryDelayMs
+
+      const acquisitionStopped = () => closing || socket.destroyed || socket.writableEnded || !socket.writable ||
+        !lifecycle.active || lifecycle.announced || sessionLifecycles.get(identifier) !== lifecycle ||
+        options.sessions.get(identifier)?.state !== "creating"
+
+      const scheduleRetry = () => {
+        if (acquisitionStopped() || sessionInitialTargetRetryTimers.has(identifier)) return
+        const timer = setTimeout(() => {
+          if (sessionInitialTargetRetryTimers.get(identifier) !== timer) return
+          sessionInitialTargetRetryTimers.delete(identifier)
+          attemptTarget()
+        }, retryDelayMs)
+        sessionInitialTargetRetryTimers.set(identifier, timer)
+        retryDelayMs = Math.min(retryDelayMs * 2, initialTargetRetryMaxDelayMs)
+      }
+
+      const attemptTarget = () => {
+        if (acquisitionStopped() || sessionInitialTargetAttempts.has(identifier) || sessionInitialTargetRetryTimers.has(identifier)) return
+        const session = options.sessions.get(identifier)
+        if (session === undefined) return
+        const attempt = createTargetConnection({host: session.target.host, port: session.target.port})
+        sessionInitialTargetAttempts.set(identifier, attempt)
+        let settled = false
+
+        const clearAttempt = () => {
+          clearInitialTargetConnectTimeout(identifier)
+          if (sessionInitialTargetAttempts.get(identifier) === attempt) {
+            sessionInitialTargetAttempts.delete(identifier)
+          }
+          attempt.off("connect", onConnect)
+          attempt.off("error", onFailure)
+          attempt.off("close", onFailure)
+        }
+        const onFailure = () => {
+          if (settled) return
+          settled = true
+          clearAttempt()
+          attempt.destroy()
+          scheduleRetry()
+        }
+        const onConnect = () => {
+          if (settled) return
+          settled = true
+          clearAttempt()
+          if (acquisitionStopped()) {
+            attempt.destroy()
+            return
+          }
+
+          clearInitialTargetRetry(identifier)
+          sessionTargets.set(identifier, attempt)
+          targets.add(attempt)
+          attachConnectedTarget(identifier, lifecycle, attempt)
+          options.sessions.transition(identifier, "active")
+
+          void (async () => {
+            const announced = await sendFrame({...createdResponse, state: "active"})
+            if (!announced || closing || socket.destroyed || !lifecycle.active ||
+                sessionLifecycles.get(identifier) !== lifecycle) {
+              deleteUnannouncedSession(identifier, lifecycle)
+              return
+            }
+            lifecycle.announced = true
+            // Only a terminal observed before publishing this sender lacks its
+            // own ordered queue entry. Later terminals enqueue behind live data.
+            const detachedTerminalState = sessionTargetTerminalState.get(identifier)
+            sessionSenders.set(identifier, sendFrame)
+            if (connectionCodec === undefined) {
+              sessionSendCodec.delete(identifier)
+              sessionCompressor.delete(identifier)
+            } else {
+              sessionSendCodec.set(identifier, connectionCodec)
+              sessionCompressor.set(identifier, new AdaptiveCompressor())
+            }
+            await queueSessionSend(identifier, async () => {
+              if (!lifecycle.active || sessionLifecycles.get(identifier) !== lifecycle || sessionSenders.get(identifier) !== sendFrame) return
+              await flushBufferedTargetChunksNow(identifier, lifecycle, sendFrame)
+              if (detachedTerminalState !== undefined && sessionTargetTerminalState.get(identifier) === detachedTerminalState && sessionSenders.get(identifier) === sendFrame) await sendFrame(detachedTerminalState)
+            })
+          })()
+        }
+
+        attempt.once("connect", onConnect)
+        attempt.once("error", onFailure)
+        attempt.once("close", onFailure)
+        const connectTimer = setTimeout(() => {
+          if (sessionInitialTargetConnectTimers.get(identifier) !== connectTimer ||
+              sessionInitialTargetAttempts.get(identifier) !== attempt || acquisitionStopped()) return
+          onFailure()
+        }, initialTargetConnectTimeoutMs)
+        connectTimer.unref?.()
+        sessionInitialTargetConnectTimers.set(identifier, connectTimer)
+      }
+
+      attemptTarget()
+    }
+
+    let tunnelFrameQueue = Promise.resolve()
+
+    socket.on("data", (chunk) => {
+      const frameOperation = tunnelFrameQueue.then(async () => {
+        let frames
+        try {
+          frames = decoder.push(chunk)
+        } catch {
+          const errorFrame = encodeFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "Malformed frame.", retryable: false})
+          socket.end(errorFrame)
+          return
+        }
+
+        for (const frame of frames) {
+          if (frame.wireFormat === "compact" && authenticatedSession && connectionFraming !== 2) {
+            sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "Compact framing version 2 was not negotiated.", retryable: false})
+            socket.end()
+            return
+          }
+          if (frame.header.type === "session.create" || frame.header.type === "session.resume") {
+            if (authenticatedSession) {
+              await sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "A tunnel can authenticate exactly one session.", retryable: false})
+              socket.end()
+              return
+            }
+            const response = handleControlMessage({
+              tokens: options.tokens,
+              sessions: options.sessions,
+              authorizeTarget: options.authorizeTarget,
+              supportedCodecs,
+              supportedFraming: [2]
+            }, frame.header)
+            if (response.type !== "session.created" && response.type !== "session.resumed") {
+              await sendFrame(response)
+              continue
+            }
+
+            authenticatedSession = true
+            decoder.disableInputBudget()
+            clearHandshakeTimeout()
+            connectionCodec = typeof response.compression === "string" ? response.compression : undefined
+            connectionFraming = response.framing === 2 ? 2 : undefined
+            sessionIdentifier = typeof response.identifier === "string" ? response.identifier : undefined
+            if (sessionIdentifier === undefined) {
+              await sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "Session response did not contain an identifier.", retryable: false})
+              socket.end()
+              return
+            }
+
+            if (frame.header.type === "session.create") {
+              const lifecycle = {active: true, announced: false}
+              tunnelSessionLifecycle = lifecycle
+              sessionLifecycles.set(sessionIdentifier, lifecycle)
+              startInitialTargetAcquisition(sessionIdentifier, lifecycle, response)
+              continue
+            }
+
+            const lifecycle = sessionLifecycles.get(sessionIdentifier)
+            if (lifecycle === undefined || !lifecycle.active || !lifecycle.announced) {
+              await sendFrame({type: "error", code: "SESSION_NOT_FOUND", message: "Session target is not available for resume.", retryable: false})
+              socket.end()
+              return
+            }
+            tunnelSessionLifecycle = lifecycle
+            const sent = await sendFrame(response)
+            if (!sent || socket.destroyed || !lifecycle.active || sessionLifecycles.get(sessionIdentifier) !== lifecycle) return
+            if (options.sessions.get(sessionIdentifier)?.state === "resuming") {
+              options.sessions.transition(sessionIdentifier, "active")
+            }
+            // Snapshot before publishing the replacement sender. A terminal
+            // observed afterward owns a queue entry behind preceding target data.
+            const detachedTerminalState = sessionTargetTerminalState.get(sessionIdentifier)
+            sessionSenders.set(sessionIdentifier, sendFrame)
+            if (connectionCodec === undefined) {
+              sessionSendCodec.delete(sessionIdentifier)
+              sessionCompressor.delete(sessionIdentifier)
+            } else {
+              sessionSendCodec.set(sessionIdentifier, connectionCodec)
+              sessionCompressor.set(sessionIdentifier, new AdaptiveCompressor())
+            }
+            const resumedSessionIdentifier = sessionIdentifier
+            if (typeof frame.header.targetToClientAck === "number") {
+              acknowledgeTargetData(resumedSessionIdentifier, frame.header.targetToClientAck)
+            }
+            await queueSessionSend(resumedSessionIdentifier, async () => {
+              if (!lifecycle.active || sessionLifecycles.get(resumedSessionIdentifier) !== lifecycle || sessionSenders.get(resumedSessionIdentifier) !== sendFrame) return
+              await replayUnackedTargetData(resumedSessionIdentifier, lifecycle, sendFrame)
+              await flushBufferedTargetChunksNow(resumedSessionIdentifier, lifecycle, sendFrame)
+              if (detachedTerminalState !== undefined && sessionTargetTerminalState.get(resumedSessionIdentifier) === detachedTerminalState && lifecycle.active && sessionLifecycles.get(resumedSessionIdentifier) === lifecycle && sessionSenders.get(resumedSessionIdentifier) === sendFrame) {
+                await sendFrame(detachedTerminalState)
+              }
+            })
+            continue
+          }
+
+          if (frame.header.type === "stream.data" && frame.header.direction === "client-to-target") {
+            if (!authenticatedSession) {
+              sendFrame({type: "error", code: "AUTH_REQUIRED", message: "Authentication is required before stream data.", retryable: false})
+              continue
+            }
+
+            const lifecycle = sessionIdentifier === undefined ? undefined : sessionLifecycles.get(sessionIdentifier)
+            if (lifecycle === undefined || !lifecycle.active || !lifecycle.announced) {
+              await sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "Stream data is forbidden before target readiness.", retryable: false})
+              socket.end()
+              return
+            }
+
+            if (frame.wireFormat !== "compact") {
+              sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "Length-prefixed stream.data is forbidden after framing version 2 is established.", retryable: false})
+              socket.end()
+              return
+            }
+
+            if (sessionIdentifier !== undefined && sessionSenders.get(sessionIdentifier) !== sendFrame) {
+              continue
+            }
+
+            const sequence = frame.header.sequence
+            if (!isValidStreamDataSequence(sequence)) {
+              sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "stream.data sequence must be a positive safe integer.", retryable: false})
+              continue
+            }
+
+            // Decompress and verify before any sequence accounting: the contiguity
+            // check below is defined over uncompressed bytes, so a lying dataLength
+            // must never be able to move the acknowledgement watermark.
+            /** @type {Buffer} */
+            let dataBytes
+            try {
+              dataBytes = await decodeStreamPayload(frame.header, frame.payload ?? Buffer.alloc(0), connectionCodec, compressionLimits)
+            } catch (error) {
+            // Fail closed: a frame we cannot decode is never written to the target,
+            // and the connection ends rather than continuing on a desynchronised
+            // uncompressed byte stream.
+              const detail = error instanceof Error ? error.message : String(error)
+              sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: detail, retryable: false})
+              socket.end()
+              return
+            }
+
+            const currentSession = sessionIdentifier !== undefined ? options.sessions.get(sessionIdentifier) : undefined
+            const committedClientSequence = currentSession?.clientSequence ?? 0
+            const pendingClientSeq = sessionIdentifier !== undefined ? (sessionPendingClientSequence.get(sessionIdentifier) ?? 0) : 0
+            const effectiveClientSequence = Math.max(committedClientSequence, pendingClientSeq)
+            const payloadLength = dataBytes.length
+            const expectedSequence = effectiveClientSequence + payloadLength
+
+            if (sequence <= effectiveClientSequence) {
+              sendFrame({type: "stream.ack", direction: "client-to-target", ackSequence: committedClientSequence})
+              continue
+            }
+
+            if (sequence !== expectedSequence) {
+              const detail = sequence < expectedSequence
+                ? `overlap (expected contiguous offset ${expectedSequence})`
+                : `gap (expected contiguous offset ${expectedSequence})`
+              sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: `stream.data sequence ${sequence} creates a ${detail}.`, retryable: false})
+              continue
+            }
+
+            const destination = sessionIdentifier === undefined ? undefined : sessionTargets.get(sessionIdentifier)
+            if (destination === undefined || destination.destroyed) {
+              sendFrame({type: "error", code: "TARGET_CLOSED", message: "Target socket is not available.", retryable: false})
+              socket.destroy()
+              continue
+            }
+
+            const targetSessionIdentifier = sessionIdentifier
+            if (targetSessionIdentifier === undefined) continue
+            sessionPendingClientSequence.set(targetSessionIdentifier, sequence)
+            destination.write(dataBytes, (error) => {
+              if (error || destination.destroyed) {
+                const terminalError = {type: "error", code: "TARGET_CLOSED", message: "Target write failed; delivery outcome is uncertain.", retryable: false}
+                persistAndQueueTargetTerminal(targetSessionIdentifier, lifecycle, terminalError)
+                sendFrame(terminalError)
+                socket.destroy()
+                return
+              }
+              options.sessions.updateSequences(targetSessionIdentifier, {clientSequence: sequence})
+              const newCommitted = options.sessions.get(targetSessionIdentifier)?.clientSequence ?? 0
+              const currentPending = sessionPendingClientSequence.get(targetSessionIdentifier) ?? 0
+              sessionPendingClientSequence.set(targetSessionIdentifier, Math.max(currentPending, newCommitted))
+              sendFrame({type: "stream.ack", direction: "client-to-target", ackSequence: sequence})
+            })
+            continue
+          }
+
+          if (frame.header.type === "stream.ack") {
+            const lifecycle = sessionIdentifier === undefined ? undefined : sessionLifecycles.get(sessionIdentifier)
+            if (authenticatedSession && (lifecycle === undefined || !lifecycle.active || !lifecycle.announced)) {
+              await sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "Stream acknowledgements are forbidden before target readiness.", retryable: false})
+              socket.end()
+              return
+            }
+            if (authenticatedSession && frame.wireFormat !== "compact") {
+              sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: "Length-prefixed stream.ack is forbidden after framing version 2 is established.", retryable: false})
+              socket.end()
+              return
+            }
+            if (frame.header.direction === "target-to-client" && typeof frame.header.ackSequence === "number" && sessionIdentifier !== undefined) {
+              if (sessionSenders.get(sessionIdentifier) !== sendFrame) {
+                continue
+              }
+              acknowledgeTargetData(sessionIdentifier, frame.header.ackSequence)
+            }
+            continue
+          }
+
+          if (frame.header.type === "session.close" && frame.header.direction === "client-to-relay") {
+            if (!authenticatedSession) {
+              sendFrame({type: "error", code: "AUTH_REQUIRED", message: "Authentication is required.", retryable: false})
+              continue
+            }
+            const lifecycle = sessionIdentifier === undefined ? undefined : sessionLifecycles.get(sessionIdentifier)
+            if (sessionIdentifier !== undefined && lifecycle !== undefined && !lifecycle.announced) {
+              const sid = sessionIdentifier
+              deleteUnannouncedSession(sid, lifecycle)
+              await sendFrame({type: "session.close", direction: "target-to-client", acknowledged: true})
+              continue
+            }
+            if (sessionIdentifier !== undefined && sessionSenders.get(sessionIdentifier) !== sendFrame) {
+              continue
+            }
+            if (sessionIdentifier !== undefined) {
+              const sid = sessionIdentifier
+              destroySessionTarget(sid)
+              sessionSenders.delete(sid)
+              try {
+                if (options.sessions.get(sid) !== undefined) {
+                  options.sessions.transition(sid, "closed")
+                }
+              } catch {
+              // session already in a terminal state
+              }
+              options.sessions.delete(sid)
+              sendFrame({type: "session.close", direction: "target-to-client", acknowledged: true})
+              sessionIdentifier = undefined
+              tunnelSessionLifecycle = undefined
+            }
+            continue
+          }
+
+          sendFrame({type: "error", code: "PROTOCOL_VIOLATION", message: `Unsupported frame type: ${frame.header.type}`, retryable: false})
+        }
+      })
+      tunnelFrameQueue = frameOperation.catch((error) => {
+        socket.destroy(error instanceof Error ? error : new Error(String(error)))
+      })
+    })
+
+    socket.on("close", () => {
+      clearHandshakeTimeout()
+      tunnels.delete(socket)
+      const settleTunnelClose = () => {
+        const lifecycle = tunnelSessionLifecycle
+        if (sessionIdentifier !== undefined && lifecycle !== undefined &&
+            sessionLifecycles.get(sessionIdentifier) === lifecycle && !lifecycle.announced) {
+          deleteUnannouncedSession(sessionIdentifier, lifecycle)
+        } else if (sessionIdentifier !== undefined && lifecycle !== undefined &&
+                   sessionLifecycles.get(sessionIdentifier) === lifecycle &&
+                   sessionSenders.get(sessionIdentifier) === sendFrame) {
+          sessionSenders.delete(sessionIdentifier)
+          sessionPendingClientSequence.delete(sessionIdentifier)
+          sessionSendCodec.delete(sessionIdentifier)
+          sessionCompressor.delete(sessionIdentifier)
+          expireSessionTargetLater(sessionIdentifier)
+        }
+      }
+      // A TLS socket can emit close after delivering bytes but before the
+      // promise-backed frame queue has processed them. Settle every frame that
+      // was received first so an intentional session.close wins over the
+      // transport-detach/resume path.
+      const settleAndForget = () => {
+        try {
+          settleTunnelClose()
+        } finally {
+          tunnelCloseSettlements.delete(socket)
+        }
+      }
+      const settlement = tunnelFrameQueue.then(settleAndForget, settleAndForget)
+      tunnelCloseSettlement.promise = settlement
+    })
+    socket.on("error", () => {
+      clearHandshakeTimeout()
+    })
+  }
+
+  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("Relay did not bind to a TCP port")
+  }
+
+  return {
+    server,
+    port: address.port,
+    status: () => {
+      let announcedSessions = 0
+      for (const lifecycle of sessionLifecycles.values()) {
+        if (lifecycle.announced) announcedSessions += 1
+      }
+      return {
+        activeTunnels: tunnels.size,
+        activeTargets: targets.size,
+        sessions: sessionLifecycles.size,
+        attachedSessions: sessionSenders.size,
+        detachedSessions: Math.max(0, announcedSessions - sessionSenders.size),
+        bufferedTargetBytes: totalProcessBufferBytes,
+        targetConnectionAttempts: sessionInitialTargetAttempts.size,
+        targetRetryTimers: sessionInitialTargetRetryTimers.size
+      }
+    },
+    closeActiveTunnel: async () => {
+      const closing = [...tunnelCloseSettlements].map(async ([tunnel, closeSettlement]) => {
+        if (!tunnel.closed) {
+          await new Promise((resolve) => {
+            tunnel.once("close", resolve)
+            tunnel.destroy()
+          })
+        }
+        if (closeSettlement?.promise === undefined) {
+          throw new Error("Tunnel close settlement was not registered")
+        }
+        await closeSettlement.promise
+      })
+      await Promise.all(closing)
+    },
+    close: async () => {
+      closing = true
+      for (const timer of sessionInitialTargetRetryTimers.values()) clearTimeout(timer)
+      sessionInitialTargetRetryTimers.clear()
+      for (const timer of sessionInitialTargetConnectTimers.values()) clearTimeout(timer)
+      sessionInitialTargetConnectTimers.clear()
+      for (const attempt of sessionInitialTargetAttempts.values()) {
+        attempt.removeAllListeners()
+        attempt.destroy()
+      }
+      sessionInitialTargetAttempts.clear()
+      for (const [identifier, lifecycle] of sessionLifecycles) {
+        if (!lifecycle.announced) options.sessions.delete(identifier)
+      }
+      for (const tunnel of tunnels) {
+        tunnel.destroy()
+      }
+      for (const target of targets) {
+        target.destroy()
+      }
+      sessionTargets.clear()
+      sessionSenders.clear()
+      sessionTargetBuffers.clear()
+      sessionTargetSentChunks.clear()
+      sessionTargetTerminalState.clear()
+      sessionPendingClientSequence.clear()
+      sessionSendCodec.clear()
+      sessionCompressor.clear()
+      sessionSendQueue.clear()
+      sessionQueuedTargetBatch.clear()
+      for (const lifecycle of sessionLifecycles.values()) lifecycle.active = false
+      sessionLifecycles.clear()
+      sessionTargetBufferBytes.clear()
+      totalProcessBufferBytes = 0
+      for (const timer of sessionTargetExpiryTimers.values()) {
+        clearTimeout(timer)
+      }
+      sessionTargetExpiryTimers.clear()
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error)
+            return
+          }
+          resolve(undefined)
+        })
+      })
+    }
+  }
+}
+
+/**
+ * @param {unknown} value - Candidate sequence value.
+ * @returns {value is number} - True if valid.
+ */
+function isValidStreamDataSequence(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+}