quico 0.3.0 → 0.7.0

package/src/quic_socket.js

@@ -14,6 +14,8 @@
 
 import dgram from 'node:dgram';
 import { QUICConnection } from './quic_connection.js';
+import lemonTls from 'lemon-tls';
+import { SUPPORTED_VERSIONS, parseVersionList, versionName } from './quic_version.js';
 
 
 /**
@@ -27,6 +29,26 @@ import { QUICConnection } from './quic_connection.js';
  * opts:
  *   remoteIp, remotePort   — where to send packets
  *   hostname               — SNI / :authority for the QUIC/TLS handshake
+ *   alpn                   — ALPN protocol(s) to offer. String or array.
+ *                            Defaults to ['h3']. Non-HTTP/3 consumers pass
+ *                            their own (e.g. ['hq-interop'] for HTTP/0.9,
+ *                            ['doq'] for DNS-over-QUIC).
+ *   rejectUnauthorized      — verify the server certificate (default true)
+ *   ca                      — CA certificate(s) for verification
+ *   idleTimeout, keepAlive  — as QUICConnection's (the idle timeout in force
+ *                            is the smaller of the two sides', RFC 9000 §10.1)
+ *   key, cert, passphrase   — a client certificate, sent if the server asks
+ *                            for one (requestCert), as with tls.connect
+ *   quicVersions            — QUIC versions, the first one's first flight
+ *                            and the rest offered (default ['v1', 'v2'])
+ *   token                   — a token from an earlier connection's
+ *                            'new_token' event (NEW_TOKEN), used once
+ *   session                 — a session saved from an earlier connection's
+ *                            'session' event, to resume (tls.connect's name)
+ *   onSocket(quic, socket)  — called as soon as the QUICConnection exists,
+ *                            BEFORE the handshake starts. Use this to attach
+ *                            listeners that must observe the handshake, such
+ *                            as 'keylog'. onConnect is too late for those.
  *   onConnect(quic, socket) — called once the QUIC handshake completes
  *   onClose()              — called when the connection closes (the socket is
  *                            already closed by the time this runs)
@@ -36,6 +58,14 @@ import { QUICConnection } from './quic_connection.js';
  * socket binds, so it is delivered via onConnect rather than returned here.
  */
 function createQuicClientSocket(opts) {
+  // ecdhCurve (tls.connect's): the key-exchange groups to offer, in order —
+  // 'X25519MLKEM768:X25519' for the post-quantum hybrid first. Unset or
+  // 'auto': X25519, P-256, P-384. A name not implemented (or the hybrid in a
+  // Node without ML-KEM) throws here, as tls.connect's does.
+  var groups = lemonTls.parseEcdhCurve(opts.ecdhCurve);
+  // sigalgs (tls.connect's): the signature schemes to offer, in order; unset,
+  // lemon-tls's list. A name it does not know throws here.
+  var sigalgs = lemonTls.parseSigalgs(opts.sigalgs);
   var isIPv6 = opts.remoteIp.indexOf(':') >= 0;
   var udpSocket = dgram.createSocket(isIPv6 ? 'udp6' : 'udp4');
   var quic = null;
@@ -49,25 +79,171 @@ function createQuicClientSocket(opts) {
   });
 
   udpSocket.bind(0, function () {
-    quic = new QUICConnection({ isServer: false, hostname: opts.hostname });
+    // Grow the kernel socket buffers before any traffic flows.
+    //
+    // Node's defaults are small (and notably small on Windows). When the send
+    // buffer overflows, the datagram is dropped locally with no error — it
+    // looks exactly like network loss, so the loss-recovery machinery kicks in
+    // and the connection crawls. This was the failure that killed the third
+    // pacer-calibration attempt (see LOSS_PTO_PLAN 7.4): larger bursts spilled
+    // over the buffer and turned a lossless link into a slow one.
+    //
+    // Wrapped in try/catch because the call can throw on platforms that cap
+    // the size; failing to enlarge the buffer is not a reason to fail the
+    // connection.
+    try { udpSocket.setSendBufferSize(2 * 1024 * 1024); } catch (e) {}
+    try { udpSocket.setRecvBufferSize(2 * 1024 * 1024); } catch (e) {}
 
-    quic.on('packet', function (data) {
+    // One attempt; after a Version Negotiation, a second in a version the
+    // server offered (RFC 9000 §6.2) — once.
+    start(null, null);
+  });
+
+  function start(version, vnOffered) {
+    var q = quic = new QUICConnection({
+      isServer: false,
+      hostname: opts.hostname,
+      // Without this the client always offered 'h3' regardless of what the
+      // caller wanted, because TLSBridge falls back to ['h3'] when alpn is
+      // undefined. Normalize a bare string into an array here so callers can
+      // pass either form.
+      alpn: (function () {
+        var a = opts.alpn || ['h3'];
+        return Array.isArray(a) ? a : [a];
+      })(),
+      // Defaults to true. Pass false for self-signed certificates, or supply
+      // `ca` for a private CA.
+      rejectUnauthorized: opts.rejectUnauthorized !== false,
+      // A client certificate, for a server that asks (tls.connect's names).
+      key: opts.key || null, cert: opts.cert || null, passphrase: opts.passphrase,
+      ca: opts.ca || null,
+      session: opts.session || null,
+      requestOCSP: opts.requestOCSP === true,
+      // Encrypted Client Hello: the server's ECHConfigList, or GREASE ECH.
+      ech: opts.ech || null,
+      echGrease: opts.echGrease === true,
+      // The groups to offer (ecdhCurve, above); null: the default.
+      groups: groups,
+      sigalgs: sigalgs,
+      // A NEW_TOKEN token from an earlier connection to the server (RFC 9000
+      // §8.1.3), for the Initial packets.
+      token: opts.token || null,
+      // quic.remoteAddress / remotePort, as on a net.Socket.
+      remoteAddress: opts.remoteIp,
+      remotePort: opts.remotePort,
+      // Our transport parameters, where the caller set them (tls_bridge).
+      transportParams: opts.transportParams || null,
+      // The connection's own options: idleTimeout (ms; or
+      // transportParams.maxIdleTimeout) and keepAlive (true: PING at half the
+      // idle timeout in force; a number: every that many ms).
+      idleTimeout: opts.idleTimeout,
+      keepAlive: opts.keepAlive,
+      // The congestion window it starts with, where the caller set it.
+      initialCongestionWindow: opts.initialCongestionWindow,
+      // The connection's options (quic_connection's CONNECTION_OPTIONS).
+      startupCap: opts.startupCap,
+      pmtuDiscovery: opts.pmtuDiscovery,
+      maxUdpPayloadSize: opts.maxUdpPayloadSize,
+      initialRtt: opts.initialRtt,
+      reorderWindow: opts.reorderWindow,
+      // 0-RTT with `session` when its ticket allows it (RFC 9001 §4.6).
+      earlyData: opts.earlyData === true,
+      // The QUIC versions: the first flight's, then the others accepted
+      // (offered through version_information, RFC 9368). ['v1', 'v2'].
+      quicVersions: opts.quicVersions,
+      version: version || undefined,
+      versionNegotiation: vnOffered || undefined
+    });
+
+    // Hand the connection to the caller BEFORE connect() runs.
+    //
+    // onConnect fires after the handshake, which is too late for anything that
+    // has to observe the handshake itself. Key logging is the concrete case:
+    // lemon-tls skips building NSS lines while nothing is listening, and the
+    // handshake secrets are emitted during connect() — so a listener attached
+    // in onConnect receives nothing at all, and the client half of a capture
+    // is undecryptable. onSocket gives callers a hook at the only moment that
+    // works.
+    if (opts.onSocket) opts.onSocket(q, udpSocket);
+
+    q.on('packet', function (data) {
       udpSocket.send(data, opts.remotePort, opts.remoteIp, function (err) {
         if (err && opts.onError) opts.onError(err);
       });
     });
 
-    quic.on('connect', function () {
-      if (opts.onConnect) opts.onConnect(quic, udpSocket);
+    // A connection that never connects is a failure the caller must hear
+    // about, once: the TLS reason when there is one (a refused certificate,
+    // with node:tls's code), the handshake timeout, or — when the peer simply
+    // closed — its CONNECTION_CLOSE. Before this a refused certificate closed
+    // the connection in silence, and an HTTP/3 request or a WebTransport
+    // `ready` waited on it forever.
+    var connected = false, failed = false;
+    function fail(err) {
+      if (connected || failed) return;
+      failed = true;
+      if (opts.onError) opts.onError(err);
+    }
+
+    q.on('error', function (err) { if (q === quic) fail(err); });
+
+    q.on('connect', function () {
+      connected = true;
+      if (opts.onConnect) opts.onConnect(q, udpSocket);
+    });
+
+    // 0-RTT: the connection may carry application data now, before the
+    // handshake — onEarly(quic, socket). Refused by the server, what went is
+    // forgotten and 'early_rejected' says so (send it again after onConnect).
+    q.on('early', function () { if (opts.onEarly) opts.onEarly(q, udpSocket); });
+
+    // The server speaks none of the versions offered in this attempt: a new
+    // one, in the first of ours it offers. A Version Negotiation that
+    // answers the second attempt is not followed (§6.2: once).
+    q.on('version_negotiation', function (offered) {
+      if (vnOffered) return;
+      var prefs = opts.quicVersions ? parseVersionList(opts.quicVersions, 'quicVersions') : SUPPORTED_VERSIONS;
+      var pick = null;
+      for (var i = 0; i < prefs.length && pick === null; i++) if (offered.indexOf(prefs[i]) >= 0) pick = prefs[i];
+      if (pick === null) {
+        var err = new Error('the server supports none of our QUIC versions (it offers ' + offered.map(versionName).join(', ') + ')');
+        err.code = 'ERR_QUIC_VERSION_NEGOTIATION';
+        fail(err);
+        return;
+      }
+      start(pick, offered);
     });
 
-    quic.on('close', function () {
+    function closedError() {
+      var pc = quic.context && quic.context.peer_close;
+      var lc = !pc && quic.context && quic.context.close_frame;
+      var err = new Error('QUIC connection closed before the handshake completed' +
+        (pc ? ' (peer error 0x' + pc.error.toString(16) + (pc.reason ? ': ' + pc.reason : '') + ')' :
+         lc ? ' (error 0x' + lc.error.toString(16) + (lc.reason ? ': ' + lc.reason : '') + ')' : ''));
+      err.code = 'ERR_QUIC_HANDSHAKE_FAILED';
+      return err;
+    }
+
+    // A handshake that will not complete is reported when that is known —
+    // the peer's CONNECTION_CLOSE, or ours — not when the connection's drain
+    // (RFC 9000 §10.2, up to 3 s) ends and 'close' comes: a server that
+    // refused the ClientHello was heard 3 s late, and an HTTP/3 request
+    // waited that long to fail. On the next turn: a TLS alert of ours closes
+    // the connection first and gives its reason ('error') right after.
+    q.on('handshake_ended', function (confirmed) {
+      if (confirmed || q !== quic) return;
+      setImmediate(function () { if (q === quic && !connected) fail(closedError()); });
+    });
+
+    q.on('close', function () {
+      if (q !== quic) return;            // an attempt given up for another
       try { udpSocket.close(); } catch (e) {}
+      if (!connected) fail(closedError());
       if (opts.onClose) opts.onClose();
     });
 
-    quic.connect();
-  });
+    q.connect();
+  }
 
   return udpSocket;
 }

package/src/quic_version.js

@@ -0,0 +1,143 @@
+/*
+ * quico: HTTP/3 and QUIC implementation for Node.js
+ * Copyright 2025 colocohen
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This file is part of the open-source project hosted at:
+ *     https://github.com/colocohen/quico
+ */
+
+
+// ============================================================
+//  QUIC versions — what differs between them, in one place
+//
+//  QUIC v1 (RFC 9000/9001) and v2 (RFC 9369) are one protocol: the same
+//  frames, the same handshake, the same recovery. v2 changes what an
+//  on-path device could have learned to depend on — the version number, the
+//  salt the Initial keys come from, the labels every packet key is derived
+//  with, the Retry integrity key, and which long-header type bits mean
+//  Initial, 0-RTT, Handshake and Retry — so that QUIC stays free to change
+//  (anti-ossification). Everything a version decides lives in its profile
+//  here, and every place that builds or reads a packet, or derives a key,
+//  asks the connection's profile: the rest of the code is the same for all
+//  versions, as lemon-tls's is for TLS 1.2 and 1.3.
+//
+//  A new version is a profile here, and its entry in COMPATIBLE when a first
+//  flight in one can be read as the other (RFC 9368 §2.3).
+// ============================================================
+
+var QUIC_V1 = 0x00000001;
+var QUIC_V2 = 0x6b3343cf;
+
+function hex(s) { return new Uint8Array(Buffer.from(s, 'hex')); }
+
+var PROFILES = {};
+
+PROFILES[QUIC_V1] = {
+  version: QUIC_V1,
+  name: 'v1',
+  // RFC 9001 §5.2
+  initialSalt: hex('38762cf7f55934b34d179ae6a4c80cadccbb7f0a'),
+  // RFC 9001 §5.1, §6.1
+  labels: { key: 'quic key', iv: 'quic iv', hp: 'quic hp', ku: 'quic ku' },
+  // RFC 9001 §5.8
+  retryKey: hex('be0c690b9f66575a1d766b54e368c84e'),
+  retryNonce: hex('461599d35d632bf2239825bb'),
+  // RFC 9000 §17.2: long header type bits → packet type
+  longTypes: ['initial', '0rtt', 'handshake', 'retry']
+};
+
+PROFILES[QUIC_V2] = {
+  version: QUIC_V2,
+  name: 'v2',
+  // RFC 9369 §3.3.1
+  initialSalt: hex('0dede3def700a6db819381be6e269dcbf9bd2ed9'),
+  // RFC 9369 §3.3.2
+  labels: { key: 'quicv2 key', iv: 'quicv2 iv', hp: 'quicv2 hp', ku: 'quicv2 ku' },
+  // RFC 9369 §3.3.3
+  retryKey: hex('8fb4b01b56ac48e260fbcbcead7ccc92'),
+  retryNonce: hex('d86969bc2d7c6d9990efb04a'),
+  // RFC 9369 §3.2: Retry 0b00, Initial 0b01, 0-RTT 0b10, Handshake 0b11
+  longTypes: ['retry', 'initial', '0rtt', 'handshake']
+};
+
+// Which first flights can be read as another version's (RFC 9368 §2.3):
+// v1 and v2 differ in nothing a ClientHello carries, both ways (RFC 9369 §4).
+var COMPATIBLE = {};
+COMPATIBLE[QUIC_V1] = [QUIC_V2];
+COMPATIBLE[QUIC_V2] = [QUIC_V1];
+
+/** The versions this implementation speaks, in its default preference. */
+var SUPPORTED_VERSIONS = [QUIC_V1, QUIC_V2];
+
+function versionProfile(version) {
+  return PROFILES[version >>> 0] || null;
+}
+
+function isSupportedVersion(version) {
+  return !!PROFILES[version >>> 0];
+}
+
+/** Whether a first flight in `from` can be taken as one in `to`. */
+function isCompatible(from, to) {
+  from >>>= 0; to >>>= 0;
+  return from === to || (COMPATIBLE[from] || []).indexOf(to) >= 0;
+}
+
+/** Long header type bits → 'initial' | '0rtt' | 'handshake' | 'retry', or null. */
+function longPacketType(version, typeBits) {
+  var p = PROFILES[version >>> 0];
+  return p ? p.longTypes[typeBits & 3] : null;
+}
+
+/** Packet type → its long header type bits in `version`. */
+function longTypeBits(version, packetType) {
+  var p = PROFILES[version >>> 0];
+  var i = p ? p.longTypes.indexOf(packetType) : -1;
+  if (i < 0) throw new Error('no long header type ' + packetType + ' in QUIC version 0x' + (version >>> 0).toString(16));
+  return i;
+}
+
+/**
+ * A version as an application names it — 1, 0x6b3343cf, 'v1', 'v2' — as a
+ * version number; throws on one this implementation does not speak.
+ */
+function parseVersion(v, what) {
+  var n = null;
+  if (typeof v === 'number' && Number.isInteger(v)) n = v >>> 0;
+  else if (typeof v === 'string') {
+    var s = v.toLowerCase();
+    for (var k in PROFILES) if (PROFILES[k].name === s) n = PROFILES[k].version;
+  }
+  if (n === null || !PROFILES[n]) throw new TypeError((what || 'quicVersions') + ': unsupported QUIC version ' + JSON.stringify(v) + ' (v1 or v2)');
+  return n;
+}
+
+/** An option listing versions in preference order → [number, …]. */
+function parseVersionList(list, what) {
+  if (list === undefined || list === null) return null;
+  if (!Array.isArray(list) || list.length === 0) throw new TypeError((what || 'quicVersions') + ' must be a non-empty array of QUIC versions');
+  var out = [];
+  for (var i = 0; i < list.length; i++) {
+    var n = parseVersion(list[i], what);
+    if (out.indexOf(n) < 0) out.push(n);
+  }
+  return out;
+}
+
+function versionName(version) {
+  var p = PROFILES[version >>> 0];
+  return p ? p.name : '0x' + (version >>> 0).toString(16);
+}
+
+export {
+  QUIC_V1, QUIC_V2, SUPPORTED_VERSIONS,
+  versionProfile, isSupportedVersion, isCompatible,
+  longPacketType, longTypeBits,
+  parseVersion, parseVersionList, versionName
+};