tls: native bidirectional TLS bridge for kernel-adjacent forwarding (TUN/VPN/proxy workloads)

What is the problem this feature will solve?

Node’s TLSSocket is designed for application-level stream I/O: cleartext is delivered to JavaScript via the streams API ('data', read(), backpressure via pause()/drain). For high-throughput, full-duplex, kernel-adjacent forwarding (TUN/TAP tunnels, VPN bridges, L3 proxies), users must implement a JS pump between a native fd and a TLSSocket.

That pattern degrades badly in practice:

• Per-chunk V8 boundary — TLSWrap::ClearOut() reads via SSL_read, copies into an allocated buffer, and EmitRead() into JS (src/crypto/crypto_tls.cc, kClearOutChunkSize = 16384).
• Extra event-loop turns — sync underlying writes are deferred with SetImmediate before WriteWrap::Done() (EncOut() / empty DoWrite() paths).
• Dual backpressure — the app must coordinate pause/resume between two independent stream endpoints (e.g. TUN poll + TLS socket) in JavaScript.
• No framing help — TLS is a byte stream; L3 frames (e.g. IPv6 packets) often require reassembly across multiple reads in userland.
• Real-world impact: projects doing iOS CoreDevice / CDTunnel-style forwarding (e.g. Appium appium-ios-tuntap) had to leave Node TLS entirely and implement OpenSSL forwarding in a native addon with dedicated blocking I/O threads — duplicating logic that conceptually belongs next to TLSWrap.

The stream API remains correct for HTTP, RPC, etc.; this gap is specifically for payload forwarding where JS should never see the bytes.

What is the feature you are proposing to solve the problem?

Add a first-class native TLS bridge API that pumps cleartext between an encrypted TCP (or pipe) stream and another native I/O endpoint without surfacing payload data to JavaScript.

Proposed API (sketch):

import tls from 'node:tls';
import net from 'node:net';
const tcp = net.connect({ port });
const bridge = tls.createBridge({
  socket: tcp,              // existing net.Socket / fd
  sink: tunFd,              // numeric fd or native handle (TUN, pipe, etc.)
  credentials: { cert, key }, // or secureContext / PSK options
  direction: 'duplex',      // 'duplex' | 'encrypt-only' | 'decrypt-only'
  onError(err) { /* lifecycle */ },
  onClose() { /* cleanup */ },
});
await bridge.handshake();   // or auto on first I/O
bridge.start();
bridge.stop();

Implementation outline (in core, built on existing TLSWrap):

• Reuse TLSWrap + OpenSSL session setup (lockdown cert, TLS-PSK, etc.) — same crypto as tls.connect().
• Run the hot loop in native code (dedicated per-connection thread or integrated read/write cycle in TLSWrap), analogous to ClearIn → ClearOut → EncOut but wired directly to the sink fd instead of EmitRead/DoWrite.
• JavaScript receives only: handshake result, errors, close — not per-packet callbacks.
• Support dup()/fd ownership semantics documented clearly (who closes what).

Success criteria:

1. Sustained bidirectional TLS 1.2 forwarding at path-MTU record sizes without per-chunk JS allocation.
   p99 latency and CPU use materially better than an equivalent socket.on('data') ↔ tun.write() pump.
2. Add-on authors (TUN, userspace VPN, transparent proxies) can delete custom OpenSSL pthread forwarders.

What alternatives have you considered?

• Stay on TLSSocket + streams — Correct for apps, insufficient for tunnel workloads; requires JS pump and suffers the costs above. This is what forced native-addon workarounds today.
• socket.on('data') + onread static buffer — Helps TCP; TLSWrap::ClearOut() still copies before JS (test-tls-onread-static-buffer.js covers TCP onread, not a TLS zero-copy path). Does not remove the V8 boundary for cleartext payload.
• Third-party native addons (custom OpenSSL in N-API) — Works (proven in production) but duplicates TLSWrap session management, cert/PSK handling, and security updates. Every VPN/tunnel project reinvents the same forwarder.
• node:quic patterns — QUIC has native stream handling oriented toward protocol I/O; CDTunnel / lockdown TLS 1.2 over TCP is a different stack and not a drop-in substitute.
• Document “don’t use TLS for this” only — Honest but pushes ecosystem fragmentation; a small, targeted tls.createBridge() (or similar) keeps advanced use cases on supported Node APIs.

Beginne mit dem Lesen von src/crypto/crypto_tls.cc rund um TLSWrap::ClearOut(), EncOut() und DoWrite(), und sieh dir anschließend test-tls-onread-static-buffer.js an. Für diesen Vorschlag ist die Zustimmung der Maintainer zur API, zum Besitz von fd, zum Threading und zum Verhalten im Lebenszyklus erforderlich. Abgeschlossen ist die Arbeit, wenn abgestimmte Tests und Benchmarks eine bidirektionale TLS-Weiterleitung ohne JavaScript-Payload-Verarbeitung pro Chunk demonstrieren.