@sproutboat/runtime 0.42.1 → 0.42.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sproutboat/runtime
 
+## 0.42.2
+
+### Patch Changes
+
+- 5ef3159: Security fix: on the embedded transport, a `connect()` socket opened with `secureTransport: "starttls"` could send application data in plaintext after `startTls()`. The I/O thread moved everything the app had queued, including writes issued after the upgrade call, into its write buffer and flushed it in the clear before switching the socket to TLS, so a write that raced the upgrade (about 7% of connections in a loopback test) left unencrypted. The host now records the queue position at the upgrade and only flushes the bytes queued before it in plaintext; everything after waits for the TLS engine, which only emits application data once the handshake is done. On the JS side, `startTls()` closes the plaintext socket's writable (its queued writes still go out, new writes are refused, as in workerd), and the new socket's writes are held until the upgrade is queued behind them. The I/O thread also reports a drained send queue right after flushing instead of after the next input, so a write past the high-water mark no longer waits on the peer. The broker tunnel, which already orders the upgrade among the data frames, no longer stays paused on the plain socket's drain when the upgrade happens under backpressure. Regression tests on both transports record the raw bytes at the origin and refuse anything but a TLS handshake record after the plaintext phase. No compatibility date: `connect()` ships from `2026-11-17`, and the old behaviour was never correct.
+
 ## 0.42.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/runtime",
-  "version": "0.42.1",
+  "version": "0.42.2",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/native-fetch-prelude.js

@@ -14704,8 +14704,18 @@ function __sbTcpRelease(st) {
   __sbTcpOpen--;
 }
 
-// One socket facade over a host connection. `st` is shared with the socket startTls() returns.
-function __sbTcpFacade(st, mode) {
+// Queues bytes for the host; a write past the high-water mark settles when the queue drains.
+function __sbTcpQueue(st, bytes) {
+  if (st.id === 0) throw new TypeError("This WritableStream has been closed.");
+  const queued = Number(__sbWsOp("b", st.id, __sbToBytes(bytes), 0));
+  if (queued > __SB_TCP_HWM) return new Promise((resolve) => (st.drain = resolve));
+  return undefined;
+}
+
+// One socket facade over a host connection. `st` is shared with the socket startTls() returns;
+// that socket gets `upgrade`, whose `pending` promise holds its writes back until the "S" op
+// is queued behind everything the plaintext socket had already accepted.
+function __sbTcpFacade(st, mode, upgrade) {
   const closed = new Promise((resolve, reject) => {
     st.closedResolve = resolve;
     st.closedReject = reject;
@@ -14759,12 +14769,15 @@ function __sbTcpFacade(st, mode) {
       },
       write(chunk) {
         const bytes = __sbTcpChunk(chunk);
-        if (st.id === 0) throw new TypeError("This WritableStream has been closed.");
-        const queued = Number(__sbWsOp("b", st.id, __sbToBytes(bytes), 0));
-        if (queued > __SB_TCP_HWM) return new Promise((resolve) => (st.drain = resolve));
-        return undefined;
+        if (upgrade !== null && upgrade.pending !== null) return upgrade.pending.then(() => __sbTcpQueue(st, bytes));
+        return __sbTcpQueue(st, bytes);
       },
       close() {
+        if (st.upgrading) {
+          // startTls() closed this stream: its queued writes are out, the write side stays open for TLS
+          st.upgrading = false;
+          return undefined;
+        }
         if (st.id !== 0) __sbWsOp("H", st.id, "", 0);
         st.writeClosed = true;
         return undefined;
@@ -14804,10 +14817,36 @@ function __sbTcpFacade(st, mode) {
       st.upgradedOnce = true;
       let sni = st.host;
       if (options != null && options.expectedServerHostname != null) sni = String(options.expectedServerHostname);
-      __sbWsOp("S", st.id, sni, 0);
+      // This socket's streams end here, as workerd detaches them. Its writable is closed first:
+      // what a writer had already queued still goes out in the clear, then the "S" op marks the
+      // queue position after which only TLS records leave the host; the new socket's writes wait
+      // on that (upgrade.pending), so no write issued after startTls() can precede the handshake.
+      const upgrade = { pending: null };
+      upgrade.pending = new Promise((resolve) => {
+        const request = () => {
+          st.upgrading = false;
+          if (st.id !== 0) __sbWsOp("S", st.id, sni, 0);
+          upgrade.pending = null;
+          resolve(undefined);
+        };
+        if (st.writeClosed) request();
+        else {
+          st.upgrading = true;
+          writable.close().then(request, request);
+        }
+      });
+      st.pullWake = null;
+      const oldReadable = st.readableController;
+      if (oldReadable !== null) {
+        try {
+          oldReadable.close();
+        } catch {
+          // already closed or errored
+        }
+      }
       // the old socket ends once the upgrade is under way (workerd resolves its `closed`)
       const oldResolve = st.closedResolve;
-      const next = __sbTcpFacade(st, "on");
+      const next = __sbTcpFacade(st, "on", upgrade);
       setTimeout(() => oldResolve(undefined), 0);
       return next;
     },
@@ -14832,11 +14871,11 @@ function __sbConnect(address, options) {
   const st = {
     id: 0, host: target.host, port: target.port, inbox: [], eof: false, failed: null, settled: false,
     allowHalfOpen, pullWake: null, drain: null, timer: undefined, opening: null, upgradedOnce: false,
-    closedByUser: false, writableController: null, readableController: null, reason: "", writeClosed: false, writeEnd: false,
+    closedByUser: false, writableController: null, readableController: null, reason: "", writeClosed: false, writeEnd: false, upgrading: false,
     release: null, closedResolve: null, closedReject: null,
   };
   st.release = () => __sbTcpRelease(st);
-  const socket = __sbTcpFacade(st, mode);
+  const socket = __sbTcpFacade(st, mode, null);
   if (target.port === 25) {
     st.failed = new Error("proxy request failed, cannot connect to the specified address");
     st.eof = true;

package/src/transport-embedded.js

@@ -3325,6 +3325,7 @@ typedef struct sb_wsc {
   int port, tls;
   // Raw TCP (cloudflare:sockets connect()): no WebSocket framing, bytes both ways.
   int raw, starttls_req, shutdown_req, want_drain;
+  size_t starttls_at;  // outq bytes queued before the "S" op: the last ones allowed out in the clear
   size_t unsent, window;
   char sni[256];
 } sb_wsc;
@@ -3458,10 +3459,13 @@ static int sb_wsio_raw_write(sb_wsio* io, const unsigned char* buf, size_t len)
 // connection ends (-1). out/outlen is application data to send first. With may_read false (the
 // reader is far behind) it only sends, and waits for the wake pipe.
 static long sb_wsio_pump(sb_wsc* c, sb_wsio* io, unsigned char* buf, size_t cap, unsigned char* out, size_t* outlen, int may_read, int ms) {
+  // Returns right after application bytes went out (0, as for a wake) instead of waiting for
+  // input: the caller reports the drain then, which a write past the high-water mark waits on.
   if (!io->tls) {
     if (*outlen) {
       if (sb_wsio_raw_write(io, out, *outlen) != 0) return -1;
       *outlen = 0;
+      return 0;
     }
     for (;;) {
       if (may_read) {
@@ -3478,6 +3482,7 @@ static long sb_wsio_pump(sb_wsc* c, sb_wsio* io, unsigned char* buf, size_t cap,
     }
   }
   br_ssl_engine_context* eng = &io->sc->eng;
+  int wrote = 0;
   for (;;) {
     unsigned st = br_ssl_engine_current_state(eng);
     if (st & BR_SSL_CLOSED) return -1;
@@ -3501,9 +3506,10 @@ static long sb_wsio_pump(sb_wsc* c, sb_wsio* io, unsigned char* buf, size_t cap,
       br_ssl_engine_sendapp_ack(eng, n);
       memmove(out, out + n, *outlen - n);
       *outlen -= n;
-      if (*outlen == 0) br_ssl_engine_flush(eng, 0);
+      if (*outlen == 0) { br_ssl_engine_flush(eng, 0); wrote = 1; }
       continue;
     }
+    if (wrote) return 0;
     // Handshaking, or waiting for the peer: read records while the reader may; else only wake.
     int reading = (st & BR_SSL_RECVREC) && (may_read || !(st & BR_SSL_SENDAPP));
     if (reading) {
@@ -3812,15 +3818,30 @@ static void* sb_tcp_thread(void* arg) {
     int st = c->starttls_req; c->starttls_req = 0;
     int sh = c->shutdown_req;
     char sni[256]; memcpy(sni, c->sni, sizeof(sni));
-    if (c->outq_len) {
-      if (wq_len + c->outq_len > wq_cap) {
+    // A pending startTls() splits the queue: only what the app queued before the "S" op may
+    // leave in the clear. The rest stays here until the TLS engine owns the socket, so a write
+    // that races the upgrade can only ever go out inside a TLS record.
+    size_t take = c->outq_len;
+    if (st && c->starttls_at < take) take = c->starttls_at;
+    if (take) {
+      if (wq_len + take > wq_cap) {
         size_t cap = wq_cap ? wq_cap : 4096;
-        while (cap < wq_len + c->outq_len) cap *= 2;
+        while (cap < wq_len + take) cap *= 2;
         unsigned char* grown = (unsigned char*)realloc(wq, cap);
         if (grown) { wq = grown; wq_cap = cap; }
       }
-      if (wq_len + c->outq_len <= wq_cap) { memcpy(wq + wq_len, c->outq, c->outq_len); wq_len += c->outq_len; c->outq_len = 0; }
+      if (wq_len + take <= wq_cap) {
+        memcpy(wq + wq_len, c->outq, take);
+        wq_len += take;
+        if (take < c->outq_len) memmove(c->outq, c->outq + take, c->outq_len - take);
+        c->outq_len -= take;
+      } else if (st) {
+        // no room to move the plaintext part: retry the upgrade on the next pass
+        c->starttls_req = 1;
+        st = 0;
+      }
     }
+    if (st) c->starttls_at = 0;
     c->unsent = wq_len;
     pthread_mutex_unlock(&c->lock);
     if (rel) {
@@ -3828,7 +3849,14 @@ static void* sb_tcp_thread(void* arg) {
       goto finish;
     }
     if (st && !io.tls) {
-      if (wq_len) sb_wsio_pump(c, &io, buf, sizeof(buf), wq, &wq_len, 0, 0);
+      // Everything queued before startTls() is written in the clear here (the plain write path
+      // blocks until the kernel took it all); the socket then belongs to the TLS engine, which
+      // only emits application data once the handshake is done (BR_SSL_SENDAPP).
+      if (wq_len && sb_wsio_pump(c, &io, buf, sizeof(buf), wq, &wq_len, 0, 0) < 0) {
+        snprintf(why, sizeof(why), "connection closed before the TLS handshake");
+        sb_wsc_push(c, 3, 0, why, strlen(why));
+        goto finish;
+      }
       if (sb_wsio_start_tls(&io, sni[0] ? sni : c->host, why, sizeof(why)) != 0) { sb_wsc_push(c, 3, 0, why, strlen(why)); goto finish; }
       tls_waiting = 1;
     }
@@ -4023,6 +4051,7 @@ static long long sb_wsc_op(int op, unsigned id, const char* data, size_t len, si
       pthread_mutex_lock(&c->lock);
       snprintf(c->sni, sizeof(c->sni), "%.*s", (int)(len < sizeof(c->sni) - 1 ? len : sizeof(c->sni) - 1), data ? data : "");
       c->starttls_req = 1;
+      c->starttls_at = c->outq_len;
       pthread_mutex_unlock(&c->lock);
       sb_wsc_wake_thread(c);
       return 0;

package/test/native-sockets-broker.ts

@@ -3,6 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import net from "node:net";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { Duplex } from "node:stream";
 import tls from "node:tls";
 import { ensurePorffor } from "../../toolchain/src/acquire";
 import { createBroker, listen } from "../../wire/src/broker";
@@ -82,6 +83,31 @@ export default {
         await secure.close();
         return Response.json({ greeting, go, echoed, upgraded: s.upgraded });
       }
+      if (url.pathname === "/starttls-race") {
+        const s = connect("127.0.0.1:" + port, { secureTransport: "starttls" });
+        const w = s.writable.getWriter();
+        const r = s.readable.getReader();
+        await withTimeout(readN(r, 11), 5000, "greeting");
+        await w.write(enc.encode("STARTTLS\\r\\n"));
+        await withTimeout(readN(r, 4), 5000, "go");
+        r.releaseLock();
+        w.releaseLock();
+        const secure = s.startTls({ expectedServerHostname: "localhost" });
+        const w2 = secure.writable.getWriter();
+        const r2 = secure.readable.getReader();
+        w2.write(enc.encode("secret-1"));
+        w2.write(enc.encode("secret-2"));
+        w2.write(enc.encode("secret-3"));
+        await withTimeout(secure.opened, 5000, "tls");
+        let echoed = "";
+        while (!echoed.includes("secret-3")) {
+          const chunk = await withTimeout(r2.read(), 5000, "tls echo");
+          if (chunk.done) break;
+          echoed += dec.decode(chunk.value);
+        }
+        await secure.close();
+        return Response.json({ echoed });
+      }
       if (url.pathname === "/tls") {
         const host = q.get("host") || "localhost";
         const s = connect({ hostname: host, port }, { secureTransport: "on" });
@@ -271,6 +297,34 @@ const starttlsPort = listenOn(
     });
   }),
 );
+// Every raw byte the recording origin receives after it sent "go", TLS records included.
+const rawAfterGo: Buffer[] = [];
+const starttlsRecordingPort = listenOn(
+  net.createServer((s) => {
+    // a TLSSocket over a net.Socket reads the handle directly, so the TLS side runs over a tap
+    // that replays the bytes this listener saw
+    const tap = new Duplex({
+      read() {},
+      write(chunk, _enc, done) {
+        s.write(chunk, done);
+      },
+    });
+    let afterGo = false;
+    s.prependListener("data", (c: Buffer) => {
+      if (!afterGo) return;
+      rawAfterGo.push(Buffer.from(c));
+      tap.push(c);
+    });
+    s.write("220 hello\r\n");
+    s.once("data", () => {
+      afterGo = true;
+      s.write("go\r\n");
+      const secure = new tls.TLSSocket(tap, { isServer: true, key, cert });
+      secure.on("data", (c) => secure.write(Buffer.concat([Buffer.from("tls:"), c])));
+      secure.on("error", () => {});
+    });
+  }),
+);
 const tlsPort = listenOn(
   tls.createServer({ key, cert }, (s) => {
     s.on("data", (c) => s.write(c));
@@ -386,6 +440,14 @@ try {
   });
   console.log("startTls upgrades in the broker, verified against the expected host name");
 
+  const race = await get(`/starttls-race?port=${starttlsRecordingPort}`);
+  const echoedRace = String(race.echoed);
+  for (const part of ["secret-1", "secret-2", "secret-3"]) assert.ok(echoedRace.includes(part), `echoed ${part}`);
+  const rawBytes = Buffer.concat(rawAfterGo);
+  assert.equal(rawBytes[0], 0x16, "the first bytes after the upgrade are a TLS handshake record");
+  assert.equal(rawBytes.includes("secret"), false, "no application bytes reached the origin in plaintext");
+  console.log("startTls: writes issued before the handshake finished only reach the origin inside TLS");
+
   assert.deepEqual(await get(`/tls?port=${tlsPort}`), { got: "secret" });
   const wrongName = await get(`/tls?port=${tlsPort}&host=127.0.0.1`);
   assert.match(String(wrongName.error), /proxy request failed, cannot connect/);

package/test/native-sockets-starttls.ts

@@ -0,0 +1,404 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Duplex } from "node:stream";
+import tls from "node:tls";
+
+// cloudflare:sockets connect() on the embedded transport (standalone sprouts, sproutd): no
+// application byte written after startTls(), or before `opened` on a secureTransport "on"
+// socket, may ever reach the wire in plaintext. The origins here record every raw byte they
+// receive and refuse anything but a TLS handshake record where the handshake must begin.
+//
+// The deterministic cases hold the sprout's I/O thread in its plaintext flush (a 16 MiB write
+// the origin reads only after a pause) while the handler calls startTls() and writes to the
+// new socket; the I/O thread then sees the upgrade and the new writes in one pass, which is
+// the race the TLS spike observed on 14 of 200 connections. `/burst` repeats the plain
+// immediate-write case many times, as the spike did.
+//
+// Needs SB_CLI, a sproutboat-cli checkout linked to this one (it builds the sprout).
+const BLOB = 16 << 20;
+const handler = `
+import { connect } from "cloudflare:sockets";
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const withTimeout = (p, ms, what) => Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error("TIMEOUT " + what)), ms))]);
+async function readN(reader, n) {
+  let out = "";
+  while (out.length < n) {
+    const r = await withTimeout(reader.read(), 5000, "read");
+    if (r.done) return out;
+    out += dec.decode(r.value);
+  }
+  return out;
+}
+async function readUntil(reader, needle) {
+  let out = "";
+  while (!out.includes(needle)) {
+    const r = await withTimeout(reader.read(), 5000, "read " + needle);
+    if (r.done) return out;
+    out += dec.decode(r.value);
+  }
+  return out;
+}
+let blob = null;
+function theBlob() {
+  if (blob === null) {
+    blob = new Uint8Array(${BLOB});
+    for (let i = 0; i < blob.length; i++) blob[i] = 120;
+  }
+  return blob;
+}
+// The plaintext phase every startTls route shares: greeting, STARTTLS, go.
+async function plainPhase(port) {
+  const s = connect({ hostname: "localhost", port }, { secureTransport: "starttls" });
+  const w = s.writable.getWriter();
+  const r = s.readable.getReader();
+  await readN(r, 11);
+  await w.write(enc.encode("STARTTLS\\r\\n"));
+  await readN(r, 4);
+  return { s, w, r };
+}
+export default {
+  async fetch(request) {
+    const url = new URL(request.url);
+    const q = url.searchParams;
+    const port = Number(q.get("port"));
+    try {
+      if (url.pathname === "/ping") return new Response("pong");
+      if (url.pathname === "/immediate" || url.pathname === "/queued") {
+        const { s, w, r } = await plainPhase(port);
+        // not awaited: the origin reads it only after a pause, so the host is still flushing it
+        // in the clear while everything below runs (the yield lets the host start the flush)
+        w.write(theBlob());
+        await sleep(100);
+        w.releaseLock();
+        r.releaseLock();
+        const secure = s.startTls({ expectedServerHostname: "localhost" });
+        const w2 = secure.writable.getWriter();
+        const r2 = secure.readable.getReader();
+        const n = url.pathname === "/queued" ? 3 : 1;
+        for (let i = 1; i <= n; i++) w2.write(enc.encode("secret-" + i));
+        const late = s.writable.getWriter().write(enc.encode("late-plaintext")).then(() => "accepted", (e) => e.name);
+        await withTimeout(secure.opened, 15000, "tls");
+        const echoed = await readUntil(r2, "secret-" + n);
+        await secure.close();
+        const oldWrite = await withTimeout(late, 1000, "late write").catch(() => "pending");
+        return Response.json({ echoed, oldWrite });
+      }
+      if (url.pathname === "/inflight") {
+        const { s, w, r } = await plainPhase(port);
+        w.releaseLock();
+        r.releaseLock();
+        const secure = s.startTls({ expectedServerHostname: "localhost" });
+        // the origin holds the ClientHello for a while, so the handshake is still in flight here
+        await sleep(100);
+        const w2 = secure.writable.getWriter();
+        const r2 = secure.readable.getReader();
+        w2.write(enc.encode("secret-1"));
+        await withTimeout(secure.opened, 15000, "tls");
+        const echoed = await readUntil(r2, "secret-1");
+        await secure.close();
+        return Response.json({ echoed });
+      }
+      if (url.pathname === "/on") {
+        const s = connect({ hostname: "localhost", port }, { secureTransport: "on" });
+        const w = s.writable.getWriter();
+        const r = s.readable.getReader();
+        // written before \`opened\`: it may only leave inside a TLS record
+        w.write(enc.encode("secret-1"));
+        await withTimeout(s.opened, 15000, "opened");
+        const echoed = await readUntil(r, "secret-1");
+        await s.close();
+        return Response.json({ echoed });
+      }
+      if (url.pathname === "/burst") {
+        const n = Number(q.get("n"));
+        let ok = 0;
+        const errors = [];
+        for (let i = 0; i < n; i++) {
+          try {
+            const { s, w, r } = await plainPhase(port);
+            w.releaseLock();
+            r.releaseLock();
+            const secure = s.startTls({ expectedServerHostname: "localhost" });
+            const w2 = secure.writable.getWriter();
+            const r2 = secure.readable.getReader();
+            w2.write(enc.encode("secret-" + i + "\\n"));
+            const echoed = await readUntil(r2, "secret-" + i + "\\n");
+            await secure.close();
+            if (echoed.includes("secret-" + i)) ok++;
+            else errors.push("bad echo " + i);
+          } catch (e) {
+            errors.push(String(e && e.message));
+          }
+        }
+        return Response.json({ ok, errors: errors.slice(0, 3) });
+      }
+      return new Response("no route", { status: 404 });
+    } catch (e) {
+      return Response.json({ error: String(e && e.message) }, { status: 500 });
+    }
+  },
+};
+`;
+
+const cli = process.env.SB_CLI;
+if (!cli) {
+  console.log("skipped: set SB_CLI to a sproutboat-cli checkout linked to this checkout (it builds the sprout)");
+  process.exit(0);
+}
+
+function freePort(): number {
+  const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+  const port = listener.port;
+  listener.stop(true);
+  return port;
+}
+
+const workdir = mkdtempSync(join(tmpdir(), "sb-native-sockets-starttls-"));
+const servers: net.Server[] = [];
+
+// A self-signed certificate for localhost; the sprout is told to trust it through SB_CA_BUNDLE.
+const made = Bun.spawnSync([
+  "openssl",
+  "req",
+  "-x509",
+  "-newkey",
+  "rsa:2048",
+  "-nodes",
+  "-keyout",
+  join(workdir, "key.pem"),
+  "-out",
+  join(workdir, "cert.pem"),
+  "-days",
+  "2",
+  "-subj",
+  "/CN=localhost",
+  "-addext",
+  "subjectAltName=DNS:localhost",
+]);
+assert.equal(made.exitCode, 0, `openssl failed: ${made.stderr}`);
+const cert = readFileSync(join(workdir, "cert.pem"), "utf8");
+const key = readFileSync(join(workdir, "key.pem"), "utf8");
+
+interface OriginOptions {
+  /** Plaintext bytes the client still owes after "go", swallowed before the TLS handshake. */
+  readonly plainBytes?: number;
+  /** Stop reading for this long after "go", so the client's send side fills up. */
+  readonly stallMs?: number;
+  /** Hold the first TLS record this long before the server's TLS side sees it. */
+  readonly holdHelloMs?: number;
+  /** TLS from the first byte (secureTransport "on") instead of a STARTTLS exchange. */
+  readonly tlsFromStart?: boolean;
+}
+
+/** A recording origin: `records[i]` holds every raw byte connection i sent after the plaintext phase. */
+function origin(options: OriginOptions) {
+  const records: Buffer[][] = [];
+  const server = net.createServer((s) => {
+    const raw: Buffer[] = [];
+    records.push(raw);
+    s.on("error", () => {});
+    // A TLSSocket over a net.Socket reads the handle directly, so the TLS side runs over a tap
+    // fed by the data listener that records the bytes.
+    const tap = new Duplex({
+      read() {},
+      write(chunk, _enc, done) {
+        s.write(chunk, done);
+      },
+    });
+    let plainLeft = options.plainBytes ?? 0;
+    let handshakeSeen = false;
+    const held: Buffer[] = [];
+    let holding = options.holdHelloMs !== undefined;
+    const feed = (c: Buffer) => {
+      if (!handshakeSeen) {
+        handshakeSeen = true;
+        // anything but a TLS handshake record here is a leak: end the connection at once
+        if (c[0] !== 0x16) {
+          s.destroy();
+          return;
+        }
+        if (holding) {
+          setTimeout(() => {
+            holding = false;
+            for (const h of held.splice(0)) tap.push(h);
+          }, options.holdHelloMs);
+        }
+      }
+      if (holding) held.push(c);
+      else tap.push(c);
+    };
+    const startTls = () => {
+      const secure = new tls.TLSSocket(tap, { isServer: true, key, cert });
+      secure.on("data", (c) => secure.write(Buffer.concat([Buffer.from("tls:"), c])));
+      secure.on("error", () => {});
+    };
+    let afterGo = options.tlsFromStart === true;
+    s.on("data", (c: Buffer) => {
+      if (!afterGo) return;
+      raw.push(Buffer.from(c));
+      let rest = c;
+      if (plainLeft > 0) {
+        const k = Math.min(plainLeft, rest.length);
+        plainLeft -= k;
+        rest = rest.subarray(k);
+      }
+      if (rest.length > 0) feed(rest);
+    });
+    if (afterGo) {
+      startTls();
+      return;
+    }
+    s.write("220 hello\r\n");
+    s.once("data", () => {
+      afterGo = true;
+      s.write("go\r\n");
+      if (options.stallMs !== undefined) {
+        s.pause();
+        setTimeout(() => s.resume(), options.stallMs);
+      }
+      startTls();
+    });
+  });
+  server.listen(0, "127.0.0.1");
+  servers.push(server);
+  // SAFETY: a listening TCP server's address() is an AddressInfo.
+  return { port: (server.address() as net.AddressInfo).port, records };
+}
+
+const stalled = origin({ plainBytes: BLOB, stallMs: 500 });
+const stalledQueued = origin({ plainBytes: BLOB, stallMs: 500 });
+const slowHello = origin({ holdHelloMs: 300 });
+const burst = origin({});
+const tlsOn = origin({ tlsFromStart: true });
+
+const plaintextOnly = (raw: Buffer, plainBytes: number, label: string) => {
+  assert.ok(
+    raw.length > plainBytes,
+    `${label}: the origin saw ${raw.length} bytes, expected the handshake after ${plainBytes}`,
+  );
+  if (plainBytes > 0)
+    assert.ok(
+      raw.subarray(0, plainBytes).equals(Buffer.alloc(plainBytes, 0x78)),
+      `${label}: the plaintext part is intact`,
+    );
+  assert.equal(raw[plainBytes], 0x16, `${label}: a TLS handshake record follows the plaintext phase`);
+  assert.equal(raw.includes("secret"), false, `${label}: no application bytes reached the origin in plaintext`);
+  assert.equal(raw.includes("late-plaintext"), false, `${label}: nothing written to the old socket reached the wire`);
+};
+
+let sprout: ReturnType<typeof Bun.spawn> | undefined;
+try {
+  const slug = "starttls-race";
+  const project = join(workdir, slug);
+  mkdirSync(join(project, "src"), { recursive: true });
+  writeFileSync(join(project, "src/index.js"), handler);
+  writeFileSync(
+    join(project, "sproutboat.jsonc"),
+    JSON.stringify({ name: slug, main: "src/index.js", compatibility_date: "2026-11-17" }),
+  );
+  const built = Bun.spawnSync(["bun", join(cli, "src/main.ts"), "build", "--standalone", "--target", "host"], {
+    cwd: project,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  assert.equal(built.exitCode, 0, "the CLI could not build the sprout");
+  const port = freePort();
+  sprout = Bun.spawn([join(project, "dist", slug)], {
+    cwd: project,
+    env: {
+      ...process.env,
+      PORT: String(port),
+      SB_EGRESS_ALLOW: "127.0.0.1",
+      SB_DATA_DIR: join(project, "data"),
+      SB_CA_BUNDLE: join(workdir, "cert.pem"),
+    },
+    stdout: "ignore",
+    stderr: "inherit",
+  });
+  const base = `http://127.0.0.1:${port}`;
+  let ready = false;
+  for (let attempt = 0; attempt < 100 && !ready; attempt++) {
+    try {
+      ready = (await (await fetch(`${base}/ping`, { signal: AbortSignal.timeout(500) })).text()) === "pong";
+    } catch {
+      if (sprout.exitCode !== null) break;
+      await Bun.sleep(100);
+    }
+  }
+  assert.ok(ready, "the sprout did not start");
+  // A leak makes the origin drop the connection, so a route may hang on the unfixed runtime:
+  // report it as an error and let the recorded bytes speak first.
+  const get = async (path: string) => {
+    try {
+      const res = await fetch(`${base}${path}`, { signal: AbortSignal.timeout(30_000) });
+      const text = await res.text();
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    } catch (e) {
+      return { error: `no answer from the sprout: ${e instanceof Error ? e.message : String(e)}` };
+    }
+  };
+
+  const immediate = await get(`/immediate?port=${stalled.port}`);
+  assert.equal(stalled.records.length, 1);
+  plaintextOnly(Buffer.concat(stalled.records[0]), BLOB, "immediate");
+  assert.equal(immediate.error, undefined, `immediate: ${JSON.stringify(immediate)}`);
+  assert.ok(String(immediate.echoed).includes("secret-1"), "immediate: the write was echoed over TLS");
+  assert.equal(
+    immediate.oldWrite,
+    "TypeError",
+    "immediate: a write on the plaintext socket after startTls() is refused",
+  );
+  console.log("a write right after startTls(), while the plaintext flush is still running, only leaves inside TLS");
+
+  const queued = await get(`/queued?port=${stalledQueued.port}`);
+  assert.equal(stalledQueued.records.length, 1);
+  plaintextOnly(Buffer.concat(stalledQueued.records[0]), BLOB, "queued");
+  assert.equal(queued.error, undefined, `queued: ${JSON.stringify(queued)}`);
+  for (const part of ["secret-1", "secret-2", "secret-3"])
+    assert.ok(String(queued.echoed).includes(part), `queued: ${part} echoed`);
+  assert.equal(queued.oldWrite, "TypeError");
+  console.log("several writes queued behind startTls() all wait for the handshake");
+
+  const inflight = await get(`/inflight?port=${slowHello.port}`);
+  assert.equal(slowHello.records.length, 1);
+  plaintextOnly(Buffer.concat(slowHello.records[0]), 0, "inflight");
+  assert.equal(inflight.error, undefined, `inflight: ${JSON.stringify(inflight)}`);
+  assert.ok(String(inflight.echoed).includes("secret-1"));
+  console.log("a write while the handshake is in flight is held until it completes");
+
+  const on = await get(`/on?port=${tlsOn.port}`);
+  assert.equal(tlsOn.records.length, 1);
+  plaintextOnly(Buffer.concat(tlsOn.records[0]), 0, "on");
+  assert.equal(on.error, undefined, `on: ${JSON.stringify(on)}`);
+  assert.ok(String(on.echoed).includes("secret-1"));
+  console.log("secureTransport on: a write before `opened` only leaves inside TLS");
+
+  const n = 40;
+  const many = await get(`/burst?port=${burst.port}&n=${n}`);
+  let leaked = 0;
+  for (const rec of burst.records) {
+    const raw = Buffer.concat(rec);
+    if (raw.length === 0 || raw[0] !== 0x16 || raw.includes("secret")) leaked++;
+  }
+  assert.equal(
+    leaked,
+    0,
+    `burst: ${leaked} of ${burst.records.length} connections sent application bytes in plaintext`,
+  );
+  assert.equal(many.error, undefined, `burst: ${JSON.stringify(many)}`);
+  assert.deepEqual(many, { ok: n, errors: [] });
+  console.log(`${n} immediate writes after startTls() in a row, none in plaintext`);
+} finally {
+  sprout?.kill();
+  for (const server of servers) server.close();
+  rmSync(workdir, { recursive: true, force: true });
+}