quico 0.8.0 → 0.9.0

package/README.md

@@ -155,7 +155,7 @@ stack trace ends in code you can open, not in a `.node` binary.
 |---|---|
 | **Node.js 18+** | ESM only (`import`). Tested on 18, 20 and 22. |
 | **No compiler** | Pure JavaScript — no native addons. |
-| **Dependencies** | [`lemon-tls`](https://github.com/colocohen/lemon-tls) (TLS 1.3) and [`flat-ranges`](https://www.npmjs.com/package/flat-ranges) (range arithmetic). Nothing else. |
+| **Dependencies** | [`lemon-tls`](https://github.com/colocohen/lemon-tls) (TLS 1.3), [`flat-ranges`](https://www.npmjs.com/package/flat-ranges) (range arithmetic), and `cryptographic-formats` (certificate formats — the dates WebTransport's `serverCertificateHashes` checks; lemon-tls reads certificates with it too). Nothing else. |
 
 ```bash
 npm install quico
@@ -2507,7 +2507,7 @@ and you route datagrams yourself.
 | `quic.earlyDataStatus` | 0-RTT: `null` (none), `'offered'` (a client's, undecided), `'accepted'`, `'rejected'` |
 | `quic.isEarlyStream(id)` | Server: whether the stream was opened by 0-RTT data |
 | `quic.whenConfirmed(cb)` | `cb()` once the handshake is confirmed (RFC 9001 §4.1.2), at once if it is |
-| `quic.alpnProtocol`, `servername`, `getCertificate()`, `getTicketInfo()`, `isSessionReused()` | What the handshake decided, with `TLSSocket`'s names |
+| `quic.alpnProtocol`, `servername`, `getCertificate()`, `getTicketInfo()`, `isSessionReused()` | What the handshake decided, with `TLSSocket`'s names — `getCertificate()` in its shape too (`subject` and `issuer` as objects, `{ CN, O, … }`), lemon-tls's `certificateObject` |
 | `quic.on(event, fn)` / `off` | Event subscription |
 
 **Events:** `'connect'`, `'stream'` (`id, data, fin`), `'stream_reset'` (`id, code,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quico",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A pure JavaScript implementation of QUIC, HTTP/3, QPACK, and WebTransport for Node.js",
   "type": "module",
   "main": "index.cjs",
@@ -80,7 +80,8 @@
     }
   ],
   "dependencies": {
+    "cryptographic-formats": "^0.1.0",
     "flat-ranges": "^2.2.0",
-    "lemon-tls": "^0.10.0"
+    "lemon-tls": "^0.11.0"
   }
-}
+}

package/src/client.js

@@ -479,6 +479,7 @@ function request(url, options, callback) {
         startupCap: options.startupCap, pmtuDiscovery: options.pmtuDiscovery,
         maxUdpPayloadSize: options.maxUdpPayloadSize, initialRtt: options.initialRtt,
         reorderWindow: options.reorderWindow, initialCongestionWindow: options.initialCongestionWindow,
+        socketBufferSize: options.socketBufferSize,   // the UDP socket's buffers (utils.js)
         // 0-RTT with the saved session (below), off unless asked for.
         earlyData: options.earlyData === true
       };

package/src/connect_udp.js

@@ -53,7 +53,7 @@ import { EventEmitter } from 'node:events';
 import dgram from 'node:dgram';
 import dns from 'node:dns';
 import net from 'node:net';
-import { readVarInt, writeVarInt } from './utils.js';
+import { readVarInt, writeVarInt, checkedSocketBufferSize, udpSocketOptions } from './utils.js';
 
 var DEFAULT_TEMPLATE = '/.well-known/masque/udp/{target_host}/{target_port}/';
 var MIN_IDLE_MS = 120000;           // §3.1: "SHOULD NOT use a period lower than two minutes"
@@ -369,6 +369,9 @@ function createConnectUdp(options) {
     }
     var headers = opts.headers || null;
     if (opts.relay === false) { this._open(headers); return this; }
+    // The socket to the target, when this tunnel makes it (no opts.socket):
+    // its buffers (utils.js), 4 MB by default; socketBufferSize 0, the OS's.
+    var bufferSize = checkedSocketBufferSize(opts.socketBufferSize, 'accept({ socketBufferSize })');
 
     var allowPrivate = opts.allowPrivate != null ? !!opts.allowPrivate : allowPrivateDefault;
     var host = this.target.host;
@@ -390,7 +393,7 @@ function createConnectUdp(options) {
       if (opts.socket) self._useSocket(opts.socket, false, pick.address, headers);
       else {
         var sock;
-        try { sock = dgram.createSocket(family === 6 ? 'udp6' : 'udp4'); }
+        try { sock = dgram.createSocket(udpSocketOptions({ type: family === 6 ? 'udp6' : 'udp4' }, bufferSize)); }
         catch (e2) { self._refuse(502, proxyStatus('proxy_internal_error'), e2); return; }
         sock.once('error', function (e3) {
           if (self.state === 'pending') self._refuse(502, proxyStatus('destination_ip_unroutable', e3.code), e3);

package/src/connect_udp_client.js

@@ -395,6 +395,7 @@ function ProxyH3Connection(key, proxy, o, ech) {
     if (self.state !== 'connecting') return;
     self.udp = createQuicClientSocket({
       remoteIp: ip, remotePort: proxy.port, hostname: o.servername || proxy.hostname,
+      socketBufferSize: o.socketBufferSize,
       rejectUnauthorized: o.rejectUnauthorized !== false, ca: o.ca || null,
       key: o.key || null, cert: o.cert || null, passphrase: o.passphrase,
       quicVersions: o.quicVersions,

package/src/crypto.js

@@ -607,6 +607,12 @@ function decrypt_quic_packet(array, readKey, readIv, readHp, ownCid, largestPn,
   return {
     packet_number: packetNumber,
     key_phase: keyPhase,
+    // The first byte with header protection removed: its reserved bits are
+    // the caller's to check — only once the AEAD has passed the packet
+    // (RFC 9000 §17.2, §17.3.1), since before that anyone could set them.
+    first_byte: array[0],
+    // null: the AEAD refused the packet. An empty Uint8Array: it passed, and
+    // there was nothing in it — a different thing (RFC 9000 §12.4).
     plaintext: plaintext
   };
 }

package/src/h3.js

@@ -307,8 +307,17 @@ function parseSettingsPayload(buf) {
   var list = [];
   var seen = {};
   while (offset < buf.length) {
-    var id = readVarInt(buf, offset); if (!id) break; offset += id.byteLength;
-    var val = readVarInt(buf, offset); if (!val) break; offset += val.byteLength;
+    // A payload that ends inside an identifier or before its value is
+    // H3_FRAME_ERROR (RFC 9114 §7.1). It was cut short silently: the setting
+    // dropped, the connection on.
+    var id = readVarInt(buf, offset);
+    var val = id ? readVarInt(buf, offset + id.byteLength) : null;
+    if (!id || !val) {
+      var te = new Error('SETTINGS payload ends inside a setting (' + (buf.length - offset) + ' byte(s) left)');
+      te.h3ErrorCode = 0x0106;
+      throw te;
+    }
+    offset += id.byteLength + val.byteLength;
     // RFC 9114 §7.2.4: an identifier twice, or one of HTTP/2's that HTTP/3
     // reserves (0x02-0x05), is H3_SETTINGS_ERROR.
     if (seen[id.value] || (id.value >= 0x02 && id.value <= 0x05)) {
@@ -646,6 +655,11 @@ function H3Connection(options) {
   var decoderStreamId = null;
   var qpackKnownReceived = 0;               // insertions the peer has acknowledged
   var qpackPendingAcks = 0;                 // insertions of THEIRS we owe an ack for
+  // Field sections we sent with a non-zero Required Insert Count, not yet
+  // acknowledged: stream id → [RIC, …] in the order sent (RFC 9204 §2.1.1).
+  // The decoder acknowledges each (Section Acknowledgment), or cancels the
+  // stream's; an acknowledgment for none is an error (§4.4.1).
+  var qpackUnacked = new Map();
 
   // ---- SETTINGS remembered for 0-RTT (RFC 9114 §7.2.4.2) ----
   //
@@ -744,9 +758,10 @@ function H3Connection(options) {
    * reference — and until an entry is below it, we send a literal instead.
    * That single number is what makes this encoder non-blocking.
    *
-   * Section acknowledgements and stream cancellations are parsed and skipped:
-   * they drive eviction accounting in an encoder that references
-   * unacknowledged entries, which this one never does.
+   * Each instruction is held to what we actually sent (RFC 9204 §4.4): a
+   * Section Acknowledgment for a section we have outstanding on that stream,
+   * an Insert Count Increment of at least 1 that does not pass the entries we
+   * inserted. Anything else is QPACK_DECODER_STREAM_ERROR.
    */
   function processQpackDecoderStream(s) {
     if (s.buffered === 0) return;
@@ -755,14 +770,41 @@ function H3Connection(options) {
     var buf = Buffer.from(copyBytes(s, s.buffered));
 
     var r = qpackParseDecoderInstructions(buf, 0);
-    if (r.increments > 0) {
-      qpackKnownReceived += r.increments;
-      if (DEBUG) console.log('[h3] qpack acked ' + r.increments +
-                             ' (known=' + qpackKnownReceived + ')');
+    for (var k = 0; k < r.instructions.length; k++) {
+      var ins = r.instructions[k];
+      if (ins.type === 'section_ack') {
+        var pend = qpackUnacked.get(ins.value);
+        if (!pend || pend.length === 0) {
+          throw qpackDecoderStreamError('Section Acknowledgment for stream ' + ins.value +
+                                        ', which has no field section awaiting one');
+        }
+        var ric = pend.shift();
+        if (pend.length === 0) qpackUnacked.delete(ins.value);
+        // §4.4.1: the acknowledged section's entries are now known received.
+        if (ric > qpackKnownReceived) qpackKnownReceived = ric;
+      } else if (ins.type === 'stream_cancel') {
+        qpackUnacked.delete(ins.value);
+      } else {
+        // §4.4.3: zero, or past what was inserted, is an error.
+        if (ins.value === 0) throw qpackDecoderStreamError('Insert Count Increment of 0');
+        if (qpackKnownReceived + ins.value > encoderTable.insertCount) {
+          throw qpackDecoderStreamError('Insert Count Increment to ' + (qpackKnownReceived + ins.value) +
+                                        ', beyond the ' + encoderTable.insertCount + ' entries inserted');
+        }
+        qpackKnownReceived += ins.value;
+      }
     }
+    if (DEBUG && r.instructions.length) console.log('[h3] qpack decoder instructions ' + r.instructions.length +
+                                                    ' (known=' + qpackKnownReceived + ')');
     consumeBytes(s, r.consumed);
   }
 
+  function qpackDecoderStreamError(msg) {
+    var err = new Error('QPACK decoder stream: ' + msg);
+    err.h3ErrorCode = H3_ERR.QPACK_DECODER_STREAM_ERROR;
+    return err;
+  }
+
   function evictQpackTable(limit) {
     // Oldest first, until what remains fits. Sizes in BYTES: measuring by
     // string length, as this did, undercounts any non-ASCII header value and
@@ -847,7 +889,15 @@ function H3Connection(options) {
     if (context.control_streams_sent) return;
     context.control_streams_sent = true;
 
-    var settings = buildSettingsPayload(localSettings(context));
+    // A reserved identifier among them, of a random N (RFC 9114 §7.2.4.1,
+    // 0x1f·N + 0x21): peers must ignore it — sending one keeps them honest.
+    // Not part of localSettings: 0-RTT's context (settingsContext) holds the
+    // ones that mean something, and this one changes every connection.
+    var greaseId = 0x1f * Math.floor(Math.random() * 0x10000) + 0x21;
+    var settings = concatUint8Arrays([
+      buildSettingsPayload(localSettings(context)),
+      writeVarInt(greaseId), writeVarInt(Math.floor(Math.random() * 64))
+    ]);
 
     var controlFrame = buildH3Frames([{ frame_type: 0x04, payload: settings }]);
 
@@ -878,6 +928,11 @@ function H3Connection(options) {
   }
 
 
+  // Our control and QPACK streams (sendControlStreams).
+  function isOwnCriticalStream(sid) {
+    return sid === (context.isServer ? 3 : 2) || sid === encoderStreamId || sid === decoderStreamId;
+  }
+
   // ---- Graceful shutdown: GOAWAY (RFC 9114 §5.2) ----
 
   function sendGoaway(id) {
@@ -1155,6 +1210,15 @@ function H3Connection(options) {
   // a WT stream, so it can be routed to its session.
   listenQuic('stream_reset', function (streamId, code) {
     var sid = Number(streamId);
+    // The peer's control or QPACK stream, reset: closed, which RFC 9114
+    // §6.2.1 and RFC 9204 §4.2 make a connection error however it happens.
+    // Only a FIN was caught (processStream); a RESET_STREAM left the
+    // connection serving on without them.
+    var crit = context.streams[sid];
+    if (crit && (crit.type === 'control' || crit.type === 'qpack_enc' || crit.type === 'qpack_dec')) {
+      connectionError(H3_ERR.H3_CLOSED_CRITICAL_STREAM, 'the peer reset its ' + crit.type + ' stream');
+      return;
+    }
     var wt = _wtStreams[sid];
     var wasParsing = sid in context.streams;
     // A client's request stream reset before its HEADERS came: there is no
@@ -1179,6 +1243,13 @@ function H3Connection(options) {
   // whole cancellation.
   listenQuic('stop_sending', function (streamId, code) {
     var sid = Number(streamId);
+    // Asked to stop one of OUR critical streams: QUIC has answered with
+    // RESET_STREAM, so it is closed — the same connection error (§6.2.1:
+    // "A receiver MUST NOT request that the sender close the control stream").
+    if (context.control_streams_sent && isOwnCriticalStream(sid)) {
+      connectionError(H3_ERR.H3_CLOSED_CRITICAL_STREAM, 'the peer stopped our ' + (sid === encoderStreamId ? 'QPACK encoder' : sid === decoderStreamId ? 'QPACK decoder' : 'control') + ' stream');
+      return;
+    }
     if (_abortedHere.has(sid)) return;
     ev.emit('stop_sending', sid, code);
   });
@@ -2124,6 +2195,11 @@ function H3Connection(options) {
     // Insertions FIRST, on their own stream: they are for the next request,
     // not this one.
     flushQpackInserts(enc.inserts);
+    if (enc.requiredInsertCount > 0) {
+      var pend = qpackUnacked.get(streamId);
+      if (pend) pend.push(enc.requiredInsertCount);
+      else qpackUnacked.set(streamId, [enc.requiredInsertCount]);
+    }
 
     var frame = buildH3Frames([{ frame_type: 1, payload: new Uint8Array(enc.block) }]);
     if (DEBUG) console.log('[h3] sendHeaders stream=' + streamId + ' len=' + frame.byteLength + ' fin=' + !!fin);

package/src/h3_client.js

@@ -248,6 +248,7 @@ function request(options, callback) {
     udpSocket = createQuicClientSocket({
       remoteIp: remoteIp,
       remotePort: remotePort,
+      socketBufferSize: options.socketBufferSize,
       // SNI and the name the certificate is checked for: tls.connect's
       // servername where given.
       hostname: options.servername || hostname,

package/src/h3_server.js

@@ -153,6 +153,7 @@ function createServer(options, handler) {
     maxUdpPayloadSize: options.maxUdpPayloadSize,
     initialRtt: options.initialRtt,
     reorderWindow: options.reorderWindow,
+    socketBufferSize: options.socketBufferSize,
     connectionOptions: options.connectionOptions,
     quicVersions: options.quicVersions,
     socket: options.socket || null,
@@ -1704,6 +1705,8 @@ function createServer(options, handler) {
 
   return {
     listen: function (p, h, cb) { closingServer = null; return qserver.listen(p, h, cb); },
+    // The UDP socket's address — after listen(0), the port the OS gave.
+    address: function () { return qserver.address(); },
     close: close,
     closeIdleConnections: closeIdleConnections,
     closeAllConnections: closeAllConnections,

package/src/qpack.js

@@ -270,6 +270,9 @@ var DECODER_INSERT_COUNT  = 0x00;   // 00xxxxxx
 function parseDecoderInstructions(buf, offset) {
   var increments = 0;
   var i = offset || 0;
+  // Each instruction in order, for the encoder to check (RFC 9204 §4.4):
+  // { type: 'section_ack' | 'stream_cancel' | 'increment', value }.
+  var instructions = [];
 
   // readPrefixedInt(buf, prefixBits, pos) — prefix width SECOND, position
   // THIRD, and it returns { value, next } rather than a byte length. Getting
@@ -284,19 +287,22 @@ function parseDecoderInstructions(buf, offset) {
       r = readPrefixedInt(buf, 7, i);
       if (!r) break;
       i = r.next;
+      instructions.push({ type: 'section_ack', value: r.value });
     } else if (b & DECODER_STREAM_CANCEL) {
       r = readPrefixedInt(buf, 6, i);
       if (!r) break;
       i = r.next;
+      instructions.push({ type: 'stream_cancel', value: r.value });
     } else {
       r = readPrefixedInt(buf, 6, i);
       if (!r) break;
       increments += r.value;
       i = r.next;
+      instructions.push({ type: 'increment', value: r.value });
     }
   }
 
-  return { increments: increments, consumed: i - (offset || 0) };
+  return { increments: increments, consumed: i - (offset || 0), instructions: instructions };
 }
 
 
@@ -439,7 +445,10 @@ function encodeHeaderBlock(headerList, table, options) {
 
   return {
     block: Buffer.from(prefix.concat(out)),
-    inserts: inserts
+    inserts: inserts,
+    // The section's Required Insert Count: non-zero, the peer acknowledges
+    // the section (Section Acknowledgment), which the encoder holds it to.
+    requiredInsertCount: maxRef
   };
 }