From 02f07322b3e2d0880441f65a35b9566d41761b5a Mon Sep 17 00:00:00 2001
From: Tim Perry <pimterry@gmail.com>
Date: Thu, 25 Jun 2026 21:36:11 +0200
Subject: [PATCH] quic: add support for custom app ticket data config & 0RTT
 validation

Signed-off-by: Tim Perry <pimterry@gmail.com>
---
 doc/api/quic.md                           |  25 +++-
 lib/internal/quic/quic.js                 |  22 ++++
 src/quic/application.cc                   |  44 ++++++-
 src/quic/application.h                    |  18 ++-
 src/quic/bindingdata.h                    |   1 +
 src/quic/session.cc                       |  23 ++--
 src/quic/session.h                        |   7 ++
 test/parallel/test-quic-appticketdata.mjs | 140 ++++++++++++++++++++++
 8 files changed, 261 insertions(+), 19 deletions(-)
 create mode 100644 test/parallel/test-quic-appticketdata.mjs

diff --git a/doc/api/quic.md b/doc/api/quic.md
index d36825d6943264..35fa21518fb7bb 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -379,7 +379,9 @@ Two pieces of state from a prior connection make this possible:
 If the server accepts the session ticket, any data sent before the handshake
 completes is 0-RTT early data. On the server side, `stream.early` is `true`
 for streams carrying early data. The server can reject the 0-RTT attempt
-(for example, if its configuration has changed since the ticket was issued).
+(for example, if its configuration has changed since the ticket was issued);
+[`sessionOptions.appTicketData`][] lets a server gate this explicitly, rejecting
+early data whose ticket does not exactly match the server's current value.
 When this happens, all streams opened during the 0-RTT phase are destroyed and
 the client's [`session.onearlyrejected`][] callback fires. The connection
 falls back to a normal 1-RTT handshake and the application can reopen streams.
@@ -2880,6 +2882,26 @@ await listen((session) => { /* ... */ }, {
 });
 ```
 
+#### `sessionOptions.appTicketData` (server only)
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {ArrayBufferView}
+
+Opaque application data to embed in the session tickets this server issues.
+On resumption, the data carried by the presented ticket is compared
+against the value currently configured here; if it does not match exactly,
+the ticket's 0-RTT early data is rejected and the connection falls back to a
+full 1-RTT handshake. Use it to bind 0-RTT acceptance to server-side state
+that must agree between the original and resumed connection - rotating the
+value invalidates the 0-RTT of all previously issued tickets.
+
+This applies to the default QUIC application. HTTP/3 sessions carry their own
+session-ticket data, so `appTicketData` is ignored when the negotiated ALPN
+is `h3`.
+
 #### `sessionOptions.ca` (client only)
 
 <!-- YAML
@@ -4493,6 +4515,7 @@ throughput issues caused by flow control.
 [`session.onsessionticket`]: #sessiononsessionticket
 [`session.onstream`]: #sessiononstream
 [`session.sendDatagram()`]: #sessionsenddatagramdatagram-encoding
+[`sessionOptions.appTicketData`]: #sessionoptionsappticketdata-server-only
 [`sessionOptions.cc`]: #sessionoptionscc
 [`sessionOptions.ciphers`]: #sessionoptionsciphers
 [`sessionOptions.datagramDropPolicy`]: #sessionoptionsdatagramdroppolicy
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
index 99eeccc3c51d23..0f00685f6d4256 100644
--- a/lib/internal/quic/quic.js
+++ b/lib/internal/quic/quic.js
@@ -425,6 +425,10 @@ const endpointRegistry = new SafeSet();
  *   prior session, used to resume that session (client only).
  * @property {ArrayBufferView} [token] An opaque address validation token
  *   previously received from the server via `onnewtoken` (client only).
+ * @property {ArrayBufferView} [appTicketData] Opaque application data to embed
+ *   in issued session tickets (server only). This is written into new tickets,
+ *   and validated against received 0-RTT early data tickets to confirm if they
+ *   can be accepted (anything but an exact match is rejected).
  * @property {bigint|number} [handshakeTimeout] The handshake timeout
  * @property {bigint|number} [initialRtt] The initial round-trip time estimate in milliseconds.
  *   Used for PTO computation and initial pacing before the first RTT sample. Default uses
@@ -5165,6 +5169,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     qlog = false,
     sessionTicket,
     token,
+    appTicketData,
     maxPayloadSize,
     unacknowledgedPacketThreshold = 0,
     handshakeTimeout,
@@ -5219,6 +5224,22 @@ function processSessionOptions(options, config = kEmptyObject) {
     }
   }
 
+  if (appTicketData !== undefined) {
+    if (!forServer) {
+      throw new ERR_INVALID_ARG_VALUE(
+        'options.appTicketData', appTicketData,
+        'is only supported for server sessions');
+    }
+    if (!isArrayBufferView(appTicketData)) {
+      throw new ERR_INVALID_ARG_TYPE('options.appTicketData',
+                                     ['ArrayBufferView'], appTicketData);
+    }
+    if (appTicketData.byteLength === 0) {
+      throw new ERR_INVALID_ARG_VALUE('options.appTicketData', appTicketData,
+                                      'must not be empty');
+    }
+  }
+
   if (cc !== undefined) {
     validateOneOf(cc, 'options.cc', [CC_ALGO_RENO, CC_ALGO_BBR, CC_ALGO_CUBIC]);
   }
@@ -5301,6 +5322,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     maxWindow,
     sessionTicket,
     token,
+    appTicketData,
     cc,
     datagramDropPolicy,
     drainingPeriodMultiplier,
diff --git a/src/quic/application.cc b/src/quic/application.cc
index ce5d5e12154d8a..507463ff6ce9d0 100644
--- a/src/quic/application.cc
+++ b/src/quic/application.cc
@@ -225,8 +225,13 @@ std::optional<PendingTicketAppData> Session::Application::ParseTicketData(
   auto app_type =
       static_cast<Type>(reinterpret_cast<const uint8_t*>(data.base)[0]);
   switch (app_type) {
-    case Type::DEFAULT:
-      return DefaultTicketData{};
+    case Type::DEFAULT: {
+      // Everything after the leading type byte is opaque application data.
+      DefaultTicketData dtd;
+      const auto* p = reinterpret_cast<const uint8_t*>(data.base);
+      if (data.len > 1) dtd.data.assign(p + 1, p + data.len);
+      return dtd;
+    }
     case Type::HTTP3:
       return ParseHttp3TicketData(data);
     default:
@@ -235,10 +240,11 @@ std::optional<PendingTicketAppData> Session::Application::ParseTicketData(
 }
 
 bool Session::Application::ValidateTicketData(
-    const PendingTicketAppData& data, const Application_Options& options) {
+    const PendingTicketAppData& data, const Session::Options& session_options) {
   if (std::holds_alternative<Http3TicketData>(data)) {
     // TODO(@jasnell): This validation probably belongs in http3.cc but keeping
     // it here for now.
+    const auto& options = session_options.application_options;
     const auto& ticket = std::get<Http3TicketData>(data);
     return options.max_field_section_size >= ticket.max_field_section_size &&
            options.qpack_max_dtable_capacity >=
@@ -250,8 +256,19 @@ bool Session::Application::ValidateTicketData(
             options.enable_connect_protocol) &&
            (!ticket.enable_datagrams || options.enable_datagrams);
   }
-  // DefaultTicketData always validates.
-  return true;
+  if (std::holds_alternative<DefaultTicketData>(data)) {
+    // Opaque app-data (raw QUIC / non-h3): the embedded bytes must exactly
+    // match the server's currently-configured app_ticket_data.
+    const auto& dtd = std::get<DefaultTicketData>(data);
+    uv_buf_t cur = session_options.app_ticket_data.has_value()
+                       ? static_cast<uv_buf_t>(*session_options.app_ticket_data)
+                       : uv_buf_init(nullptr, 0);
+    return dtd.data.size() == cur.len &&
+           (cur.len == 0 || memcmp(dtd.data.data(), cur.base, cur.len) == 0);
+  }
+  // Unknown/unparsed ticket data -> fail closed so no 0-RTT (falls back to
+  // 1-RTT, so limited impact but avoids invalid resumptions).
+  return false;
 }
 
 Packet::Ptr Session::Application::CreateStreamDataPacket() {
@@ -734,6 +751,23 @@ class DefaultApplication final : public Session::Application {
     }
   }
 
+  void CollectSessionTicketAppData(
+      SessionTicket::AppData* app_data) const override {
+    // Layout: [type byte][optional opaque app data]. With no app data this
+    // degenerates to the single type byte written by the base class.
+    const auto& atd = session().config().options.app_ticket_data;
+    uv_buf_t bytes =
+        atd.has_value() ? static_cast<uv_buf_t>(*atd) : uv_buf_init(nullptr, 0);
+    std::vector<uint8_t> buf;
+    buf.reserve(1 + bytes.len);
+    buf.push_back(static_cast<uint8_t>(type()));  // Type::DEFAULT
+    if (bytes.len > 0) {
+      const auto* p = reinterpret_cast<const uint8_t*>(bytes.base);
+      buf.insert(buf.end(), p, p + bytes.len);
+    }
+    app_data->Set(uv_buf_init(reinterpret_cast<char*>(buf.data()), buf.size()));
+  }
+
   bool ApplySessionTicketData(const PendingTicketAppData& data) override {
     return std::holds_alternative<DefaultTicketData>(data);
   }
diff --git a/src/quic/application.h b/src/quic/application.h
index 0df9b9f0a0e68d..539520def112f5 100644
--- a/src/quic/application.h
+++ b/src/quic/application.h
@@ -4,6 +4,7 @@
 
 #include <optional>
 #include <variant>
+#include <vector>
 
 #include "base_object.h"
 #include "bindingdata.h"
@@ -17,7 +18,11 @@ namespace node::quic {
 // Parsed session ticket application data, produced by
 // Application::ParseTicketData() before ALPN negotiation and consumed
 // by Application::ApplySessionTicketData() after.
-struct DefaultTicketData {};
+struct DefaultTicketData {
+  // The opaque application data carried in the ticket (after the type byte),
+  // matched exactly against the server's current `app_ticket_data`.
+  std::vector<uint8_t> data;
+};
 struct Http3TicketData {
   uint64_t max_field_section_size;
   uint64_t qpack_max_dtable_capacity;
@@ -163,12 +168,13 @@ class Session::Application : public MemoryRetainer {
       const SessionTicket::AppData& app_data,
       SessionTicket::AppData::Source::Flag flag);
 
-  // Validates parsed ticket data against current application options.
-  // Returns false if the stored settings are more permissive than the
-  // current config (e.g., a feature was enabled when the ticket was
-  // issued but is now disabled).
+  // Validates parsed ticket data against the current session configuration.
+  // For HTTP/3 tickets this rejects settings more permissive than the
+  // current config (e.g. a feature enabled when the ticket was issued but
+  // now disabled); for default (opaque) tickets it requires the embedded data
+  // to exactly match the configured app_ticket_data. Returns false to reject.
   static bool ValidateTicketData(const PendingTicketAppData& data,
-                                 const Application_Options& options);
+                                 const Session::Options& session_options);
 
   // Parse session ticket app data before ALPN negotiation. Reads the
   // type byte and dispatches to the appropriate application-specific
diff --git a/src/quic/bindingdata.h b/src/quic/bindingdata.h
index 7879220e02b482..4184cf20ea5328 100644
--- a/src/quic/bindingdata.h
+++ b/src/quic/bindingdata.h
@@ -72,6 +72,7 @@ class SessionManager;
   V(active_connection_id_limit, "activeConnectionIDLimit")                     \
   V(address_lru_size, "addressLRUSize")                                        \
   V(allow, "allow")                                                            \
+  V(app_ticket_data, "appTicketData")                                          \
   V(application, "application")                                                \
   V(authoritative, "authoritative")                                            \
   V(bbr, "bbr")                                                                \
diff --git a/src/quic/session.cc b/src/quic/session.cc
index 8380e477c01e80..21bf37030409cb 100644
--- a/src/quic/session.cc
+++ b/src/quic/session.cc
@@ -710,6 +710,18 @@ Maybe<Session::Options> Session::Options::From(Environment* env,
     }
   }
 
+  // Parse the optional opaque application data to embed in session tickets.
+  Local<Value> app_ticket_data_val;
+  if (params->Get(env->context(), state.app_ticket_data_string())
+          .ToLocal(&app_ticket_data_val) &&
+      app_ticket_data_val->IsArrayBufferView()) {
+    Store app_ticket_data_store;
+    if (Store::From(app_ticket_data_val.As<ArrayBufferView>())
+            .To(&app_ticket_data_store)) {
+      options.app_ticket_data = std::move(app_ticket_data_store);
+    }
+  }
+
   return Just<Options>(options);
 }
 
@@ -2880,16 +2892,13 @@ SessionTicket::AppData::Status Session::ExtractSessionTicketAppData(
   if (!parsed.has_value()) {
     return SessionTicket::AppData::Status::TICKET_IGNORE_RENEW;
   }
-  // Pre-validate the ticket data against the current application options.
-  // If the stored settings are more permissive than the current config
-  // (e.g., a feature was enabled when the ticket was issued but is now
-  // disabled), reject the ticket so 0-RTT is not used. This must happen
+  // Pre-validate the ticket data against the current configuration. If it
+  // does not match, reject the ticket so 0-RTT is not used. This must happen
   // here (during TLS ticket processing) rather than in SetApplication,
   // because by SetApplication time the TLS layer has already accepted
   // the ticket and told the client 0-RTT is ok.
-  if (!Application::ValidateTicketData(*parsed,
-                                       config().options.application_options)) {
-    Debug(this, "Session ticket app data incompatible with current settings");
+  if (!Application::ValidateTicketData(*parsed, config().options)) {
+    Debug(this, "Session ticket app data incompatible with current config");
     return SessionTicket::AppData::Status::TICKET_IGNORE_RENEW;
   }
   impl_->pending_ticket_data_ = std::move(parsed);
diff --git a/src/quic/session.h b/src/quic/session.h
index 0caeb764ba56c8..07b9af4f5710a0 100644
--- a/src/quic/session.h
+++ b/src/quic/session.h
@@ -240,6 +240,13 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
     // to skip address validation. Client-side only.
     std::optional<Store> token;
 
+    // Opaque application data to embed in issued session tickets. On the
+    // server this is both written into new tickets and used to validate
+    // 0-RTT on resume (a resumed ticket whose app-data does not exactly match
+    // this value has its early data rejected). Protocol-agnostic; the
+    // built-in HTTP/3 application uses its own typed ticket data instead.
+    std::optional<Store> app_ticket_data;
+
     void MemoryInfo(MemoryTracker* tracker) const override;
     SET_MEMORY_INFO_NAME(Session::Options)
     SET_SELF_SIZE(Options)
diff --git a/test/parallel/test-quic-appticketdata.mjs b/test/parallel/test-quic-appticketdata.mjs
new file mode 100644
index 00000000000000..e08acc065fabc3
--- /dev/null
+++ b/test/parallel/test-quic-appticketdata.mjs
@@ -0,0 +1,140 @@
+// Flags: --experimental-quic --experimental-stream-iter --no-warnings
+
+// Test: the generic `appTicketData` server option. Opaque application data
+// configured on the server is embedded in issued session tickets and used to
+// exact-match-validate 0-RTT on resume. Covers:
+//   - Accept: resuming against an unchanged `appTicketData` accepts 0-RTT (the
+//     embed + parse + exact-match round-trip works and does not break resumption).
+//   - Reject: resuming against a different `appTicketData` refuses 0-RTT (the
+//     exact match fails) and falls back to a full 1-RTT handshake. Two endpoints
+//     sharing the cert + tokenSecret are used so the ticket still decrypts and
+//     the token validates; only the appTicketData differs.
+//   - Argument validation: `appTicketData` must be an ArrayBufferView.
+
+import { hasQuic, skip, mustCall } from '../common/index.mjs';
+import assert from 'node:assert';
+
+const { ok, strictEqual, rejects } = assert;
+
+if (!hasQuic) {
+  skip('QUIC is not enabled');
+}
+
+const { listen, connect } = await import('../common/quic.mjs');
+const { randomBytes } = await import('node:crypto');
+const { bytes } = await import('stream/iter');
+
+const encoder = new TextEncoder();
+const appTicketData = new Uint8Array([1, 2, 3, 4, 5]);
+
+// --- Accept path: appTicketData unchanged -> 0-RTT accepted ---
+const serverEndpoint = await listen((serverSession) => {
+  serverSession.onstream = async (stream) => {
+    try {
+      await bytes(stream);
+      stream.writer.endSync();
+      await stream.closed;
+    } catch { /* connection winding down */ }
+  };
+}, { appTicketData });
+
+let savedTicket;
+let savedToken;
+const gotTicket = Promise.withResolvers();
+const gotToken = Promise.withResolvers();
+
+const cs1 = await connect(serverEndpoint.address, {
+  onsessionticket: mustCall((ticket) => {
+    savedTicket ??= ticket;
+    gotTicket.resolve();
+  }, 2),
+  onnewtoken: mustCall((token) => {
+    savedToken ??= token;
+    gotToken.resolve();
+  }),
+});
+await cs1.opened;
+await Promise.all([gotTicket.promise, gotToken.promise]);
+
+const s1 = await cs1.createBidirectionalStream({ body: encoder.encode('first') });
+for await (const _ of s1) { /* drain */ } // eslint-disable-line no-unused-vars
+await s1.closed;
+cs1.destroy();
+
+// Resume against the same endpoint (same appTicketData) - 0-RTT accepted.
+const cs2 = await connect(serverEndpoint.address, {
+  sessionTicket: savedTicket,
+  token: savedToken,
+});
+const s2 = await cs2.createBidirectionalStream({ body: encoder.encode('early') });
+s2.closed.catch(() => {});
+const info2 = await cs2.opened;
+strictEqual(info2.earlyDataAttempted, true);
+strictEqual(info2.earlyDataAccepted, true);
+
+for await (const _ of s2) { /* drain */ } // eslint-disable-line no-unused-vars
+cs2.destroy();
+serverEndpoint.destroy();
+
+// --- Reject path: a different appTicketData -> 0-RTT rejected ---
+{
+  const tokenSecret = randomBytes(16);
+  const handler = (session) => {
+    session.onstream = async (stream) => {
+      try {
+        await bytes(stream);
+        stream.writer.endSync();
+        await stream.closed;
+      } catch { /* connection winding down */ }
+    };
+  };
+
+  const ep1 = await listen(handler, {
+    appTicketData: new Uint8Array([1, 2, 3]),
+    endpoint: { tokenSecret },
+  });
+  let ticket;
+  let token;
+  const haveTicket = Promise.withResolvers();
+  const haveToken = Promise.withResolvers();
+  const c1 = await connect(ep1.address, {
+    onsessionticket: mustCall((t) => { ticket ??= t; haveTicket.resolve(); }, 2),
+    onnewtoken: mustCall((t) => { token ??= t; haveToken.resolve(); }),
+  });
+  await c1.opened;
+  await Promise.all([haveTicket.promise, haveToken.promise]);
+  const rs = await c1.createBidirectionalStream({ body: encoder.encode('a') });
+  for await (const _ of rs) { /* drain */ } // eslint-disable-line no-unused-vars
+  c1.destroy();
+  ep1.destroy();
+
+  const ep2 = await listen(handler, {
+    appTicketData: new Uint8Array([9, 9, 9]),
+    endpoint: { tokenSecret },
+  });
+  const c2 = await connect(ep2.address, { sessionTicket: ticket, token });
+  const es = await c2.createBidirectionalStream({ body: encoder.encode('b') });
+  es.closed.catch(() => {});
+  const info = await c2.opened;
+  strictEqual(info.earlyDataAttempted, true);
+  strictEqual(info.earlyDataAccepted, false);
+  for await (const _ of es) { /* drain */ } // eslint-disable-line no-unused-vars
+  c2.destroy();
+  ep2.destroy();
+}
+
+// --- Argument validation ---
+// appTicketData is server-only: rejected on a client session.
+await rejects(connect('127.0.0.1:1', { appTicketData: new Uint8Array([1]) }), {
+  code: 'ERR_INVALID_ARG_VALUE',
+});
+// On a server it must be an ArrayBufferView.
+await rejects(listen(() => {}, { appTicketData: 123 }), {
+  code: 'ERR_INVALID_ARG_TYPE',
+});
+// An empty value is rejected: it would be indistinguishable from unset.
+await rejects(listen(() => {}, { appTicketData: new Uint8Array([]) }), {
+  code: 'ERR_INVALID_ARG_VALUE',
+});
+
+ok(true);