From cd7e2762eb7a4b5f96973031ac4ca2d0486d7450 Mon Sep 17 00:00:00 2001
From: Tim Perry <pimterry@gmail.com>
Date: Thu, 25 Jun 2026 16:10:51 +0200
Subject: [PATCH 1/2] quic: defer server session emit until TLS ClientHello is
 processed

This ensures we don't fire session events for totally invalid TLS
handshakes - fundamental errors, bad SNI/ALPN values, or anything else
that our TLS config would reject. Instead, it means servers can access
servername & alpnProtocol synchronously as soon as the event is fired -
all key session data is available and it's immediately usable.

We don't want to defer further to handshake completed, since that'd be
an extra RT, and defeat 0RTT benefits entirely. ClientHello processed
without errors is sufficient for now.

This isn't a security mechanism. Existing structures will defer
actually sending & receiving anything that's not marked explicitly as
early data until the handshake completes anyway.

Signed-off-by: Tim Perry <pimterry@gmail.com>
---
 doc/api/quic.md                               |  30 ++++-
 lib/internal/quic/quic.js                     |  24 +++-
 src/quic/endpoint.cc                          |  30 +++--
 src/quic/session.cc                           | 112 +++++++++++++++++-
 src/quic/session.h                            |  23 ++++
 src/quic/tlscontext.cc                        |   1 +
 test/parallel/test-quic-alpn-mismatch.mjs     |  17 ++-
 .../test-quic-session-emit-ordering.mjs       |  48 ++++++++
 test/parallel/test-quic-sni-mismatch.mjs      |  24 ++--
 test/parallel/test-quic-zero-rtt.mjs          |   6 +-
 10 files changed, 272 insertions(+), 43 deletions(-)
 create mode 100644 test/parallel/test-quic-session-emit-ordering.mjs

diff --git a/doc/api/quic.md b/doc/api/quic.md
index d36825d6943264..ac3f5712ba2fa6 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -1418,6 +1418,30 @@ will be silently dropped and `0n` returned. The local
 `maxDatagramFrameSize` transport parameter (default: `1200` bytes) controls
 what this endpoint advertises to the peer as its own maximum.
 
+### `session.servername`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string|undefined}
+
+The SNI (Server Name Indication) host name associated with the session, or
+`undefined` if none was set. On a client this is the `servername` requested via
+[`quic.connect()`][]. On a server it is the name sent by the peer.
+
+### `session.alpnProtocol`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string|undefined}
+
+The negotiated ALPN protocol. On a server this is available synchronously as
+soon as the session is surfaced to the `onsession` callback; on a client it is
+`undefined` until the handshake completes.
+
 ### `session.certificate`
 
 <!-- YAML
@@ -3563,7 +3587,11 @@ added: v23.8.0
 * `this` {quic.QuicEndpoint}
 * `session` {quic.QuicSession}
 
-The callback function that is invoked when a new session is initiated by a remote peer.
+The callback function that is invoked when a new server session is initiated by
+a remote peer. It is called once the peer's TLS `ClientHello` has been
+processed, so the negotiated TLS parameters are immediately available when
+the callback runs. Sessions whose handshake is rejected before this point are
+never surfaced.
 
 ### Callback: `OnStreamCallback`
 
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index 99eeccc3c51d23..1b416f35c2218f 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -744,7 +744,9 @@ setCallbacks({
     this[kOwner][kFinishClose](context, status);
   },
   /**
-   * Called when the QuicEndpoint C++ handle receives a new server-side session
+   * Called when a new server session is surfaced. The emit happens once the
+   * session's ClientHello has been processed, so its servername/protocol
+   * getters are already readable.
    * @param {object} session The QuicSession C++ handle
    */
   onSessionNew(session) {
@@ -2877,6 +2879,26 @@ class QuicSession {
     }
   }
 
+  /**
+   * The SNI servername, or undefined when none was sent.
+   * @type {string|undefined}
+   */
+  get servername() {
+    assertIsQuicSession(this);
+    if (this.destroyed) return undefined;
+    return this.#handle.getServername();
+  }
+
+  /**
+   * The negotiated ALPN protocol.
+   * @type {string|undefined}
+   */
+  get alpnProtocol() {
+    assertIsQuicSession(this);
+    if (this.destroyed) return undefined;
+    return this.#handle.getAlpnProtocol();
+  }
+
   /** @type {OnDatagramCallback} */
   get ondatagram() {
     assertIsQuicSession(this);
diff --git a/src/quic/endpoint.cc b/src/quic/endpoint.cc
index 5a728a0a2a147e..160cde981b5cdc 100644
--- a/src/quic/endpoint.cc
+++ b/src/quic/endpoint.cc
@@ -814,8 +814,8 @@ void Endpoint::AddSession(const CID& cid, BaseObjectPtr<Session> session) {
   // For server sessions, associate the client's original DCID (ocid) so
   // that 0-RTT packets arriving in a separate UDP datagram can be routed
   // to this session. This must happen after the session is added (so
-  // FindSession can resolve the mapping) but before EmitNewSession (which
-  // runs JS and may yield to libuv, allowing the 0-RTT packet to arrive).
+  // FindSession can resolve the mapping) and before any JS runs (which
+  // may yield to libuv, allowing the 0-RTT packet to arrive).
   if (session->is_server() && session->config().ocid) {
     AssociateCID(session->config().ocid, session->config().scid);
   }
@@ -825,22 +825,22 @@ void Endpoint::AddSession(const CID& cid, BaseObjectPtr<Session> session) {
   if (session->is_server() && session->config().retry_scid) {
     AssociateCID(session->config().retry_scid, session->config().scid);
   }
-  // Increment the primary session count and ref the handle BEFORE
-  // EmitNewSession. EmitNewSession calls into JS, which may close/destroy
-  // the session synchronously. The session's ~Impl calls RemoveSession
-  // which decrements the count. If we increment after EmitNewSession,
-  // RemoveSession would see count=0 and the count would be permanently
-  // off by one.
+  // Increment the primary session count and ref the handle BEFORE any
+  // JS can run for this session (the deferred EmitNewSession, or packet
+  // processing callbacks). JS may close/destroy the session
+  // synchronously; the session's ~Impl calls RemoveSession which
+  // decrements the count. If we incremented after, RemoveSession would
+  // see count=0 and the count would be permanently off by one.
   if (primary_session_count_++ == 0) {
     idle_timer_.Stop();
     udp_.Ref();
   }
   if (session->is_server()) {
     STAT_INCREMENT(Stats, server_sessions);
-    // We only emit the new session event for server sessions.
-    EmitNewSession(session);
-    // It is important to note that the session may be closed/destroyed
-    // when it is emitted here.
+    // Note that we don't emit new sessions here - that's deferred until the
+    // ClientHello has been processed (see Session::ReadPacket), so the
+    // session is exposed to JS only once its SNI/ALPN are known and invalid
+    // handshakes never surface.
   } else {
     STAT_INCREMENT(Stats, client_sessions);
   }
@@ -1980,6 +1980,12 @@ void Endpoint::EmitNewSession(const BaseObjectPtr<Session>& session) {
   // the call to MakeCallback. If that's the case, the session object still
   // exists but it is in a destroyed state. Care should be taken accessing
   // session after this point.
+
+  // Deliver any stream events that were held until the stream was setup,
+  // e.g. 0-RTT streams from the first flight.
+  if (!session->is_destroyed()) {
+    session->ReplayDeferredEmits();
+  }
 }
 
 void Endpoint::EmitClose(CloseContext context, int status) {
diff --git a/src/quic/session.cc b/src/quic/session.cc
index 8380e477c01e80..83eab0d99eaa38 100644
--- a/src/quic/session.cc
+++ b/src/quic/session.cc
@@ -184,6 +184,8 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
 #define SESSION_JS_METHODS(V)                                                  \
   V(Destroy, destroy, SIDE_EFFECT)                                             \
   V(GetRemoteAddress, getRemoteAddress, NO_SIDE_EFFECT)                        \
+  V(GetServername, getServername, NO_SIDE_EFFECT)                              \
+  V(GetAlpnProtocol, getAlpnProtocol, NO_SIDE_EFFECT)                          \
   V(GetLocalAddress, getLocalAddress, NO_SIDE_EFFECT)                          \
   V(GetCertificate, getCertificate, NO_SIDE_EFFECT)                            \
   V(GetEphemeralKeyInfo, getEphemeralKey, NO_SIDE_EFFECT)                      \
@@ -781,6 +783,8 @@ struct Session::Impl final : public MemoryRetainer {
   SocketAddress remote_address_;
   std::unique_ptr<Application> application_;
   StreamsMap streams_;
+  // Emits deferred until after session setup is completed
+  std::vector<std::function<void()>> deferred_emits_;
   TimerWrapHandle timer_;
   size_t send_scope_depth_ = 0;
   QuicError last_error_;
@@ -1001,6 +1005,36 @@ struct Session::Impl final : public MemoryRetainer {
     session->Destroy();
   }
 
+  // The SNI servername from the TLS handshake; empty (-> undefined) only if
+  // none was sent.
+  JS_METHOD(GetServername) {
+    auto env = Environment::GetCurrent(args);
+    Session* session;
+    ASSIGN_OR_RETURN_UNWRAP(&session, args.This());
+    if (session->is_destroyed()) return;
+    auto sn = session->tls_session().servername();
+    if (sn.empty()) return;
+    Local<Value> ret;
+    if (ToV8Value(env->context(), sn).ToLocal(&ret)) {
+      args.GetReturnValue().Set(ret);
+    }
+  }
+
+  // The negotiated ALPN protocol. Undefined only for clients before the
+  // handshake is completed, as ALPN is mandatory for QUIC.
+  JS_METHOD(GetAlpnProtocol) {
+    auto env = Environment::GetCurrent(args);
+    Session* session;
+    ASSIGN_OR_RETURN_UNWRAP(&session, args.This());
+    if (session->is_destroyed()) return;
+    auto proto = session->tls_session().protocol();
+    if (proto.empty()) return;
+    Local<Value> ret;
+    if (ToV8Value(env->context(), proto).ToLocal(&ret)) {
+      args.GetReturnValue().Set(ret);
+    }
+  }
+
   JS_METHOD(GetRemoteAddress) {
     auto env = Environment::GetCurrent(args);
     Session* session;
@@ -2190,6 +2224,12 @@ const Session::Options& Session::options() const {
 void Session::EmitQlog(uint32_t flags, std::string_view data) {
   if (!env()->can_call_into_js()) return;
 
+  if (!is_destroyed() && must_defer_emits()) {
+    QueueDeferredEmit(
+        [this, flags, held = std::string(data)]() { EmitQlog(flags, held); });
+    return;
+  }
+
   bool fin = (flags & NGTCP2_QLOG_WRITE_FLAG_FIN) != 0;
 
   // Fun fact... ngtcp2 does not emit the final qlog statement until the
@@ -2312,6 +2352,16 @@ bool Session::ReadPacket(const uint8_t* data,
         // Process deferred operations that couldn't run inside callback
         // scopes (e.g., HTTP/3 GOAWAY handling that calls into JS).
         application().PostReceive();
+        // Surface a server session to JS once its ClientHello has been
+        // processed (OnSelectAlpn fired: SNI + ALPN are known and reliable).
+        // Held first-flight events - including 0-RTT request streams - replay
+        // at emit. The !wrapped guard makes this fire exactly once, on
+        // whichever packet completes the ClientHello (so a multi-datagram
+        // ClientHello is handled correctly).
+        if (is_server() && hello_processed_ && !impl_->state()->wrapped &&
+            !is_destroyed()) {
+          endpoint().EmitNewSession(BaseObjectPtr<Session>(this));
+        }
       }
       return true;
     }
@@ -2975,6 +3025,30 @@ void Session::set_wrapped() {
   impl_->state()->wrapped = 1;
 }
 
+bool Session::must_defer_emits() const {
+  // Server sessions are surfaced to JS (via the deferred new-session emit)
+  // only after the ClientHello has been processed and wrapped; anything
+  // emitted before then has no JS wrapper to receive it and must be held
+  // for replay.
+  return is_server() && !impl_->state()->wrapped;
+}
+
+void Session::QueueDeferredEmit(std::function<void()> fn) {
+  impl_->deferred_emits_.emplace_back(std::move(fn));
+}
+
+void Session::ReplayDeferredEmits() {
+  if (is_destroyed()) return;
+  DCHECK(impl_->state()->wrapped);
+  // Runs synchronously immediately after the new-session callback
+  // returns (still within first-flight processing).
+  auto emits = std::move(impl_->deferred_emits_);
+  for (auto& emit : emits) {
+    if (is_destroyed()) return;
+    emit();
+  }
+}
+
 void Session::set_priority_supported(bool on) {
   DCHECK(!is_destroyed());
   impl_->state()->priority_supported = on ? 1 : 0;
@@ -3284,6 +3358,10 @@ bool Session::HandshakeCompleted() {
 
   Debug(this, "Session handshake completed");
   impl_->state()->handshake_completed = 1;
+  // This implies fully completing a handshake without setting hello_processed
+  // (set during ALPN negotiation). Should be impossible unless ALPN flow is
+  // changed drastically, but good to check as it'd lose sessions.
+  DCHECK(!is_server() || hello_processed_);
 
   STAT_RECORD_TIMESTAMP(Stats, handshake_completed_at);
   SetStreamOpenAllowed();
@@ -3482,6 +3560,7 @@ void Session::set_max_datagram_size(uint16_t size) {
 
 void Session::EmitGoaway(stream_id last_stream_id) {
   if (is_destroyed()) return;
+  if (DeferEmit([this, last_stream_id] { EmitGoaway(last_stream_id); })) return;
   if (!env()->can_call_into_js()) return;
 
   CallbackScope<Session> cb_scope(this);
@@ -3496,6 +3575,14 @@ void Session::EmitGoaway(stream_id last_stream_id) {
 
 void Session::EmitDatagram(Store&& datagram, DatagramReceivedFlags flag) {
   DCHECK(!is_destroyed());
+
+  if (must_defer_emits()) {
+    QueueDeferredEmit([this, datagram = std::move(datagram), flag]() mutable {
+      EmitDatagram(std::move(datagram), flag);
+    });
+    return;
+  }
+
   if (!env()->can_call_into_js()) return;
 
   CallbackScope<Session> cbv_scope(this);
@@ -3511,6 +3598,8 @@ void Session::EmitDatagram(Store&& datagram, DatagramReceivedFlags flag) {
 void Session::EmitDatagramStatus(datagram_id id, quic::DatagramStatus status) {
   DCHECK(!is_destroyed());
 
+  if (DeferEmit([this, id, status] { EmitDatagramStatus(id, status); })) return;
+
   if (!env()->can_call_into_js()) return;
 
   CallbackScope<Session> cb_scope(this);
@@ -3672,6 +3761,7 @@ void Session::EmitSessionTicket(Store&& ticket) {
 
 void Session::EmitApplication() {
   if (is_destroyed()) return;
+  if (DeferEmit([this] { EmitApplication(); })) return;
   if (!env()->can_call_into_js()) return;
 
   if (!has_application()) {
@@ -3742,6 +3832,10 @@ void Session::EmitNewToken(const uint8_t* token, size_t len) {
 void Session::EmitStream(const BaseObjectWeakPtr<Stream>& stream) {
   DCHECK(!is_destroyed());
 
+  if (DeferEmit([this, stream] { EmitStream(stream); })) return;
+
+  if (!stream) return;
+
   if (!env()->can_call_into_js()) return;
   CallbackScope<Session> cb_scope(this);
 
@@ -3797,6 +3891,14 @@ void Session::EmitVersionNegotiation(const ngtcp2_pkt_hd& hd,
 
 void Session::EmitOrigins(std::vector<std::string>&& origins) {
   DCHECK(!is_destroyed());
+
+  if (must_defer_emits()) {
+    QueueDeferredEmit([this, origins = std::move(origins)]() mutable {
+      EmitOrigins(std::move(origins));
+    });
+    return;
+  }
+
   if (!HasListenerFlag(impl_->state()->listener_flags,
                        SessionListenerFlags::ORIGIN))
     return;
@@ -3822,11 +3924,17 @@ void Session::EmitOrigins(std::vector<std::string>&& origins) {
 
 void Session::EmitKeylog(const char* line) {
   DCHECK(!is_destroyed());
+
+  if (must_defer_emits()) {
+    QueueDeferredEmit(
+        [this, str = std::string(line)]() { EmitKeylog(str.c_str()); });
+    return;
+  }
+
   if (!env()->can_call_into_js()) return;
 
-  auto str = std::string(line);
   Local<Value> argv[] = {Undefined(env()->isolate())};
-  if (!ToV8Value(env()->context(), str).ToLocal(&argv[0])) {
+  if (!ToV8Value(env()->context(), std::string(line)).ToLocal(&argv[0])) {
     Debug(this, "Failed to convert keylog line to V8 string");
     return;
   }
diff --git a/src/quic/session.h b/src/quic/session.h
index 0caeb764ba56c8..e8663c511c0f7e 100644
--- a/src/quic/session.h
+++ b/src/quic/session.h
@@ -536,11 +536,32 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
   // before the handshake completes.
   void PopulateEarlyTransportParamsState();
 
+  void set_hello_processed() { hello_processed_ = true; }
+
   // It's a terrible name but "wrapped" here means that the Session has been
   // passed out to JavaScript and should be "wrapped" by whatever handler is
   // defined there to manage it.
   void set_wrapped();
 
+  // True while JS emits must be held for later replay, before the handshake
+  // is complete and the server session event has been emitted.
+  bool must_defer_emits() const;
+
+  // Replays, in order, any emits held while must_defer_emits() was true.
+  // Called synchronously right after the new-session emit.
+  void ReplayDeferredEmits();
+
+  // Queues fn to be replayed by ReplayDeferredEmits(). Out-of-line so the
+  // header does not need the full Impl definition.
+  void QueueDeferredEmit(std::function<void()> fn);
+
+  template <typename F>
+  bool DeferEmit(F&& fn) {
+    if (!must_defer_emits()) return false;
+    QueueDeferredEmit(std::forward<F>(fn));
+    return true;
+  }
+
   enum class CloseMethod : uint8_t {
     // Immediate close with a roundtrip through JavaScript, causing all
     // currently opened streams to be closed. An attempt will be made to
@@ -656,6 +677,8 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
   };
   Flags flags_;
 
+  bool hello_processed_ = false;
+
   QuicConnectionPointer connection_;
   std::unique_ptr<TLSSession> tls_session_;
   friend struct NgTcp2CallbackScope;
diff --git a/src/quic/tlscontext.cc b/src/quic/tlscontext.cc
index c0a1610540ed3a..a5c0563d01bd80 100644
--- a/src/quic/tlscontext.cc
+++ b/src/quic/tlscontext.cc
@@ -375,6 +375,7 @@ int TLSContext::OnSelectAlpn(SSL* ssl,
     return SSL_TLSEXT_ERR_NOACK;
   }
   session.SetApplication(std::move(app));
+  session.set_hello_processed();
 
   return SSL_TLSEXT_ERR_OK;
 }
diff --git a/test/parallel/test-quic-alpn-mismatch.mjs b/test/parallel/test-quic-alpn-mismatch.mjs
index 64d8e1f0006380..f97b11b919de9f 100644
--- a/test/parallel/test-quic-alpn-mismatch.mjs
+++ b/test/parallel/test-quic-alpn-mismatch.mjs
@@ -8,7 +8,7 @@
 // 0x100 | <tls_alert>. For `no_application_protocol` (alert 120 / 0x78) this
 // is 0x178 == 376.
 
-import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import { hasQuic, skip, mustCall, mustNotCall } from '../common/index.mjs';
 import assert from 'node:assert';
 
 const { rejects, strictEqual, match } = assert;
@@ -29,16 +29,15 @@ const onerror = mustCall((err) => {
   strictEqual(err.code, 'ERR_QUIC_TRANSPORT_ERROR');
   strictEqual(err.errorCode, 376n);
   match(err.message, /no application protocol/);
-}, 2);
+});
 const transportParams = { maxIdleTimeout: 1 };
 
-const serverEndpoint = await listen(mustCall(async (serverSession) => {
-  await rejects(serverSession.opened, expected);
-  await rejects(serverSession.closed, expected);
-}), {
-  transportParams,
-  onerror,
-});
+// The handshake fails so the session is never surfaced to JS
+const serverEndpoint = await listen(
+  mustNotCall('server session must not be surfaced for a failed handshake'),
+  {
+    transportParams,
+  });
 
 // Client requests an ALPN the server doesn't offer.
 const clientSession = await connect(serverEndpoint.address, {
diff --git a/test/parallel/test-quic-session-emit-ordering.mjs b/test/parallel/test-quic-session-emit-ordering.mjs
new file mode 100644
index 00000000000000..59fb521183bda9
--- /dev/null
+++ b/test/parallel/test-quic-session-emit-ordering.mjs
@@ -0,0 +1,48 @@
+// Flags: --experimental-quic --no-warnings --expose-internals
+
+// Check that server `onsession` emit fires only after the session's
+// ClientHello has been processed & validated.
+
+import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import assert from 'node:assert';
+
+const { ok, notStrictEqual, strictEqual } = assert;
+
+if (!hasQuic) {
+  skip('QUIC is not enabled');
+}
+
+const { createRequire } = await import('node:module');
+const require = createRequire(import.meta.url);
+const { getQuicSessionState } = require('internal/quic/quic');
+const { listen, connect } = await import('../common/quic.mjs');
+
+const sessionSeen = Promise.withResolvers();
+
+const serverEndpoint = await listen(mustCall((serverSession) => {
+  // All assertions run synchronously in the onsession emit frame.
+
+  // The TLS details from the ClientHello are readable on the session.
+  strictEqual(serverSession.servername, 'localhost');
+  strictEqual(serverSession.alpnProtocol, 'quic-test');
+
+  // The client's transport params arrived in the first flight and have
+  // been processed by the time the session is surfaced.
+  const params = serverSession.remoteTransportParams;
+  notStrictEqual(params, undefined);
+  notStrictEqual(params, null);
+  ok(params.initialMaxStreamsBidi >= 0n);
+
+  // ALPN negotiation has completed: headers support is resolved (2 =
+  // unsupported, confirming non-h3 test ALPN)
+  strictEqual(getQuicSessionState(serverSession).headersSupported, 2);
+
+  sessionSeen.resolve();
+}));
+
+const clientSession = await connect(serverEndpoint.address);
+await clientSession.opened;
+await sessionSeen.promise;
+
+await clientSession.close();
+await serverEndpoint.close();
diff --git a/test/parallel/test-quic-sni-mismatch.mjs b/test/parallel/test-quic-sni-mismatch.mjs
index dbb2de4c011a30..e27059222a8ece 100644
--- a/test/parallel/test-quic-sni-mismatch.mjs
+++ b/test/parallel/test-quic-sni-mismatch.mjs
@@ -5,7 +5,7 @@
 // and no wildcard is configured. The handshake should fail with a
 // TLS alert (unrecognized_name).
 
-import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import { hasQuic, skip, mustCall, mustNotCall } from '../common/index.mjs';
 import assert from 'node:assert';
 import * as fixtures from '../common/fixtures.mjs';
 
@@ -24,21 +24,15 @@ const cert = readKey('agent1-cert.pem');
 
 // Server only has an entry for 'specific.example.com', no wildcard.
 // Connections to any other hostname will be rejected at the TLS level.
-const serverEndpoint = await listen(mustCall(async (serverSession) => {
-  await rejects(serverSession.opened, {
-    code: 'ERR_QUIC_TRANSPORT_ERROR',
+// The handshake fails while the server processes the client's first
+// flight, so the session is never surfaced to JS.
+const serverEndpoint = await listen(
+  mustNotCall('server session must not be surfaced for a failed handshake'),
+  {
+    sni: { 'specific.example.com': { keys: [key], certs: [cert] } },
+    alpn: ['quic-test'],
+    transportParams: { maxIdleTimeout: 1 },
   });
-  await rejects(serverSession.closed, {
-    code: 'ERR_QUIC_TRANSPORT_ERROR',
-  });
-}), {
-  sni: { 'specific.example.com': { keys: [key], certs: [cert] } },
-  alpn: ['quic-test'],
-  transportParams: { maxIdleTimeout: 1 },
-  onerror: mustCall((err) => {
-    strictEqual(err.code, 'ERR_QUIC_TRANSPORT_ERROR');
-  }),
-});
 
 // Client connects with a different servername — no matching identity.
 const clientSession = await connect(serverEndpoint.address, {
diff --git a/test/parallel/test-quic-zero-rtt.mjs b/test/parallel/test-quic-zero-rtt.mjs
index ef1a345541045b..e979bb7f898bf2 100644
--- a/test/parallel/test-quic-zero-rtt.mjs
+++ b/test/parallel/test-quic-zero-rtt.mjs
@@ -90,15 +90,15 @@ const cs2 = await connect(serverEndpoint.address, {
 });
 
 // Send data BEFORE the handshake completes — true 0-RTT.
-const s2 = await cs2.createBidirectionalStream({
-  body: encoder.encode('early data'),
-});
+const s2 = await cs2.createBidirectionalStream();
+await s2.writer.write(encoder.encode('early data'));
 
 // Now wait for handshake completion.
 const info2 = await cs2.opened;
 strictEqual(info2.earlyDataAttempted, true);
 strictEqual(info2.earlyDataAccepted, true);
 
+await s2.writer.end();
 for await (const _ of s2) { /* drain */ } // eslint-disable-line no-unused-vars
 await s2.closed;
 

From 8d11c9637b02b4b9b5344058c578f875b161b708 Mon Sep 17 00:00:00 2001
From: Tim Perry <pimterry@gmail.com>
Date: Wed, 8 Jul 2026 11:49:50 +0200
Subject: [PATCH 2/2] fixup! quic: defer server session emit until TLS
 ClientHello is processed

Cache ALPN & servername once set, update field types and docs.
---
 doc/api/quic.md           | 18 ++++++++++--------
 lib/internal/quic/quic.js | 30 ++++++++++++++++++++++--------
 src/quic/session.cc       | 27 +++++++++++++++++++--------
 src/quic/session.h        |  3 +++
 4 files changed, 54 insertions(+), 24 deletions(-)

diff --git a/doc/api/quic.md b/doc/api/quic.md
index ac3f5712ba2fa6..b11fe8b1ae138e 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -1424,11 +1424,12 @@ what this endpoint advertises to the peer as its own maximum.
 added: REPLACEME
 -->
 
-* Type: {string|undefined}
+* Type: {string|boolean|null}
 
-The SNI (Server Name Indication) host name associated with the session, or
-`undefined` if none was set. On a client this is the `servername` requested via
-[`quic.connect()`][]. On a server it is the name sent by the peer.
+The SNI (Server Name Indication) host name associated with the session. This is
+`null` before the client hello is processed. Once the hello has been
+processed, this is either the host name string or `false` if the handshake
+had no SNI.
 
 ### `session.alpnProtocol`
 
@@ -1436,11 +1437,12 @@ The SNI (Server Name Indication) host name associated with the session, or
 added: REPLACEME
 -->
 
-* Type: {string|undefined}
+* Type: {string|null}
 
-The negotiated ALPN protocol. On a server this is available synchronously as
-soon as the session is surfaced to the `onsession` callback; on a client it is
-`undefined` until the handshake completes.
+The negotiated ALPN protocol. This is `null` before the client hello is
+processed. Once ALPN has been negotiated, this is the protocol string. ALPN
+is mandatory in QUIC so this is never `false` on successful connections,
+unlike `node:tls` where this is optional.
 
 ### `session.certificate`
 
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index 1b416f35c2218f..d5d512e0756aa6 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -2729,6 +2729,8 @@ class QuicSession {
     certificate: undefined,
     peerCertificate: undefined,
     ephemeralKeyInfo: undefined,
+    servername: undefined,
+    alpnProtocol: undefined,
     localTransportParams: undefined,
     remoteTransportParams: undefined,
   };
@@ -2880,23 +2882,35 @@ class QuicSession {
   }
 
   /**
-   * The SNI servername, or undefined when none was sent.
-   * @type {string|undefined}
+   * The SNI servername: `null` until known, then the host name string, or
+   * `false` if the handshake produced no SNI.
+   * @type {string|boolean|null}
    */
   get servername() {
     assertIsQuicSession(this);
-    if (this.destroyed) return undefined;
-    return this.#handle.getServername();
+    const inner = this.#inner;
+    if (inner.servername !== undefined) return inner.servername;
+    if (this.destroyed) return null;
+    // The handle returns null until the value is final; cache it only once it
+    // settles (to a string or `false`) so earlier reads re-query.
+    const value = this.#handle.getServername();
+    if (value !== null) inner.servername = value;
+    return value;
   }
 
   /**
-   * The negotiated ALPN protocol.
-   * @type {string|undefined}
+   * The negotiated ALPN protocol: `null` until known, then the protocol
+   * string. ALPN is mandatory for QUIC, so there is no "no ALPN" case.
+   * @type {string|null}
    */
   get alpnProtocol() {
     assertIsQuicSession(this);
-    if (this.destroyed) return undefined;
-    return this.#handle.getAlpnProtocol();
+    const inner = this.#inner;
+    if (inner.alpnProtocol !== undefined) return inner.alpnProtocol;
+    if (this.destroyed) return null;
+    const value = this.#handle.getAlpnProtocol();
+    if (value !== null) inner.alpnProtocol = value;
+    return value;
   }
 
   /** @type {OnDatagramCallback} */
diff --git a/src/quic/session.cc b/src/quic/session.cc
index 83eab0d99eaa38..aad2d898cb9b27 100644
--- a/src/quic/session.cc
+++ b/src/quic/session.cc
@@ -1005,30 +1005,35 @@ struct Session::Impl final : public MemoryRetainer {
     session->Destroy();
   }
 
-  // The SNI servername from the TLS handshake; empty (-> undefined) only if
-  // none was sent.
+  // The SNI servername: null until the TLS parameters are final, then the
+  // host name string, or false if the handshake produced no SNI.
   JS_METHOD(GetServername) {
     auto env = Environment::GetCurrent(args);
     Session* session;
     ASSIGN_OR_RETURN_UNWRAP(&session, args.This());
-    if (session->is_destroyed()) return;
+    if (session->is_destroyed() || !session->tls_info_ready()) {
+      return args.GetReturnValue().SetNull();
+    }
     auto sn = session->tls_session().servername();
-    if (sn.empty()) return;
+    if (sn.empty()) return args.GetReturnValue().Set(false);
     Local<Value> ret;
     if (ToV8Value(env->context(), sn).ToLocal(&ret)) {
       args.GetReturnValue().Set(ret);
     }
   }
 
-  // The negotiated ALPN protocol. Undefined only for clients before the
-  // handshake is completed, as ALPN is mandatory for QUIC.
+  // The negotiated ALPN protocol: null until the TLS parameters are final,
+  // then the protocol string.
   JS_METHOD(GetAlpnProtocol) {
     auto env = Environment::GetCurrent(args);
     Session* session;
     ASSIGN_OR_RETURN_UNWRAP(&session, args.This());
-    if (session->is_destroyed()) return;
+    if (session->is_destroyed() || !session->tls_info_ready()) {
+      return args.GetReturnValue().SetNull();
+    }
     auto proto = session->tls_session().protocol();
-    if (proto.empty()) return;
+    // QUIC requires ALPN
+    DCHECK(!proto.empty());
     Local<Value> ret;
     if (ToV8Value(env->context(), proto).ToLocal(&ret)) {
       args.GetReturnValue().Set(ret);
@@ -3033,6 +3038,12 @@ bool Session::must_defer_emits() const {
   return is_server() && !impl_->state()->wrapped;
 }
 
+bool Session::tls_info_ready() const {
+  // hello_processed_ is set server-side, handshake_completed covers
+  // the client. Together they mark the point when SNI/ALPN are final.
+  return hello_processed_ || impl_->state()->handshake_completed;
+}
+
 void Session::QueueDeferredEmit(std::function<void()> fn) {
   impl_->deferred_emits_.emplace_back(std::move(fn));
 }
diff --git a/src/quic/session.h b/src/quic/session.h
index e8663c511c0f7e..adac1d7d0f28fc 100644
--- a/src/quic/session.h
+++ b/src/quic/session.h
@@ -538,6 +538,9 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
 
   void set_hello_processed() { hello_processed_ = true; }
 
+  // True once the negotiated TLS parameters (SNI, ALPN) are final.
+  bool tls_info_ready() const;
+
   // It's a terrible name but "wrapped" here means that the Session has been
   // passed out to JavaScript and should be "wrapped" by whatever handler is
   // defined there to manage it.