lemon-tls 0.4.0 → 0.5.0

package/src/dtls_session.js

@@ -27,6 +27,7 @@
  */
 
 import { EventEmitter } from 'node:events';
+import crypto from 'node:crypto';
 
 import TLSSession from './tls_session.js';
 import createSecureContext from './secure_context.js';
@@ -38,6 +39,7 @@ import {
   build_message,
   build_hello_verify_request,
   parse_hello_verify_request,
+  parse_hello,
 } from './wire.js';
 
 import {
@@ -59,6 +61,8 @@ import {
   parseDtlsAck,
 } from './record.js';
 
+import { timingSafeEqualU8 } from './utils.js';
+
 
 // ============================================================
 //  Helpers
@@ -130,6 +134,15 @@ function DTLSSession(options) {
     isServer: isServer,
     mtu: options.mtu || 1200,
 
+    // Upper bound on a single reassembled handshake message. The DTLS handshake
+    // header carries a 24-bit length (up to 16MB), which is attacker-controlled
+    // on the very first fragment. Without a cap, a peer could send one fragment
+    // claiming length 0xFFFFFF for several msg_seqs and force large allocations
+    // before anything is authenticated. 256KB comfortably fits a real
+    // certificate-chain flight while bounding the damage. Configurable via
+    // options.maxHandshakeMessageSize.
+    maxHandshakeMessageSize: options.maxHandshakeMessageSize || (256 * 1024),
+
     // Version (determined after negotiation)
     selectedVersion: null,  // DTLS version (0xFEFC or 0xFEFD)
 
@@ -146,12 +159,17 @@ function DTLSSession(options) {
     cipherSuite: null,
     hashName: null,
 
-    // Fragment reassembly: msg_seq → { totalLength, parts: { offset: Uint8Array } }
+    // Fragment reassembly: msg_seq → { totalLength, type, chunks:[{off,end,body}], covered }
     fragments: {},
 
     // Incoming handshake msg_seq tracking
     nextReadMsgSeq: 0,
 
+    // Out-of-order handshake buffering (RFC 6347 §4.2.4 / RFC 9147 §5.2):
+    // complete messages that arrive ahead of nextReadMsgSeq are held here,
+    // keyed by msg_seq, and drained in order once the gap is filled.
+    pendingMessages: {},   // msg_seq → { type, body }
+
     // Flight tracking for retransmission
     currentFlight: [],     // array of { epoch, data: Uint8Array (complete datagram) }
     retransmitTimer: null,
@@ -425,9 +443,18 @@ function DTLSSession(options) {
    * Returns array of DTLS handshake message fragments (each with reconstruction header).
    */
   function fragmentMessage(dtlsMsg, tlsMsg, msgSeq) {
-    let overhead = 13 + 16; // record header + AEAD tag (approximate)
-    let maxFragment = ctx.mtu - overhead;
-
+    // Record-layer overhead we must leave room for inside one datagram/MTU:
+    //   DTLS 1.2: 13-byte classic record header + 16-byte AEAD tag (+8 explicit
+    //             nonce for GCM, but that lives inside the encrypted payload the
+    //             record layer builds, so we keep a small safety margin).
+    //   DTLS 1.3: 5-byte unified header (2-byte seq + length) + 16-byte AEAD tag.
+    // Using the correct, smaller 1.3 overhead avoids over-fragmenting.
+    let isDtls13 = ctx.selectedVersion === DTLS_VERSION.DTLS1_3;
+    let recordOverhead = isDtls13 ? (5 + 16) : (13 + 16 + 8);
+    let maxFragment = ctx.mtu - recordOverhead;
+
+    // The DTLS handshake message header is 12 bytes; the body is what we chunk.
+    const HS_HDR = 12;
     if (dtlsMsg.length <= maxFragment) return [dtlsMsg];
 
     // Need to fragment: split the TLS body into chunks
@@ -436,8 +463,11 @@ function DTLSSession(options) {
     let fragments = [];
     let offset = 0;
 
+    // Each fragment carries its own 12-byte handshake header, so the payload
+    // budget per fragment is maxFragment - HS_HDR.
+    let maxChunk = Math.max(1, maxFragment - HS_HDR);
     while (offset < totalLength) {
-      let chunkLen = Math.min(maxFragment - 12, totalLength - offset); // 12 = DTLS handshake header
+      let chunkLen = Math.min(maxChunk, totalLength - offset);
       let frag = build_dtls_handshake(tlsMsg, msgSeq, offset, chunkLen);
       fragments.push(frag);
       offset += chunkLen;
@@ -483,7 +513,18 @@ function DTLSSession(options) {
 
     let records = parseDtlsDatagram(data, keysByEpoch);
 
+    // RFC 9147 §7: collect the record numbers of handshake records we received
+    // in this datagram so we can ACK them once, after processing. Only for
+    // DTLS 1.3, and only while we're still handshaking (post-handshake ACKs of
+    // NewSessionTicket etc. are optional and skipped here for simplicity).
+    let ackable = [];
+
     for (let i = 0; i < records.length; i++) {
+      if (records[i].type === CT.HANDSHAKE &&
+          ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
+        ackable.push({ epoch: records[i].epoch, seq: records[i].seq });
+      }
+
       processRecord(records[i]);
 
       // After CCS, keys are newly available — re-decrypt remaining epoch>0 records
@@ -500,6 +541,14 @@ function DTLSSession(options) {
         }
       }
     }
+
+    // Send a single ACK covering all handshake records received in this datagram.
+    // We ACK from the highest epoch for which we already have write keys (so the
+    // ACK itself is protected once handshake keys exist; epoch 0 before that).
+    if (ackable.length > 0) {
+      let ackEpoch = ctx.keys[3] ? 3 : (ctx.keys[2] ? 2 : 0);
+      sendAck(ackEpoch, ackable);
+    }
   }
 
   function processRecord(record) {
@@ -569,33 +618,68 @@ function DTLSSession(options) {
   }
 
   /**
-   * Reassemble a fragmented handshake message.
+   * Reassemble a (possibly fragmented) handshake message.
+   *
+   * RFC 6347 §4.2.3 / RFC 9147 §5.5: fragments may overlap and arrive out of
+   * order, because a retransmission can re-fragment the same message with
+   * different boundaries (e.g. after a PMTU change). We therefore copy each
+   * fragment's bytes into a full-length buffer and track coverage as a set of
+   * merged byte-ranges, rather than requiring each fragment to start exactly
+   * where the previous one ended.
    */
   function reassembleFragment(parsed) {
     let key = parsed.msg_seq;
-    if (!(key in ctx.fragments)) {
-      ctx.fragments[key] = { totalLength: parsed.length, type: parsed.type, parts: {} };
+
+    // Ignore fragments for messages we've already delivered.
+    if (key < ctx.nextReadMsgSeq) return;
+
+    // DoS guard: the 24-bit `length` is attacker-controlled on the first
+    // fragment. Reject anything claiming more than our cap BEFORE allocating,
+    // so a peer can't force huge buffers with a single unauthenticated packet.
+    if (parsed.length > ctx.maxHandshakeMessageSize) {
+      ev.emit('error', new Error('DTLS handshake message exceeds maxHandshakeMessageSize (' +
+        parsed.length + ' > ' + ctx.maxHandshakeMessageSize + ')'));
+      return;
     }
+
     let frag = ctx.fragments[key];
-    frag.parts[parsed.frag_offset] = parsed.body;
+    if (!frag) {
+      frag = ctx.fragments[key] = {
+        totalLength: parsed.length,
+        type: parsed.type,
+        buf: new Uint8Array(parsed.length),
+        ranges: [],   // sorted, merged [start, end) covered ranges
+      };
+    }
 
-    // Check if complete
-    let assembled = new Uint8Array(frag.totalLength);
-    let filled = 0;
-    let offsets = Object.keys(frag.parts).map(Number).sort((a, b) => a - b);
+    let start = parsed.frag_offset;
+    let end = parsed.frag_offset + parsed.frag_length;
 
-    for (let i = 0; i < offsets.length; i++) {
-      let part = frag.parts[offsets[i]];
-      if (offsets[i] !== filled) return; // gap — not complete yet
-      assembled.set(part, offsets[i]);
-      filled = offsets[i] + part.length;
-    }
+    // Bounds guard against a malformed fragment claiming to exceed totalLength.
+    if (end > frag.totalLength) return;
 
-    if (filled < frag.totalLength) return; // not complete
+    // Copy the fragment bytes in (overlaps simply overwrite with identical data).
+    frag.buf.set(parsed.body.subarray(0, parsed.frag_length), start);
 
-    // Complete — deliver
-    delete ctx.fragments[key];
-    deliverHandshakeMessage(frag.type, assembled, key);
+    // Merge [start, end) into the covered-range set.
+    frag.ranges.push([start, end]);
+    frag.ranges.sort((a, b) => a[0] - b[0]);
+    let merged = [];
+    for (let r of frag.ranges) {
+      if (merged.length && r[0] <= merged[merged.length - 1][1]) {
+        // Overlapping/adjacent → extend the previous range.
+        if (r[1] > merged[merged.length - 1][1]) merged[merged.length - 1][1] = r[1];
+      } else {
+        merged.push([r[0], r[1]]);
+      }
+    }
+    frag.ranges = merged;
+
+    // Complete when a single range covers [0, totalLength).
+    if (merged.length === 1 && merged[0][0] === 0 && merged[0][1] === frag.totalLength) {
+      delete ctx.fragments[key];
+      deliverHandshakeMessage(frag.type, frag.buf, key);
+    }
   }
 
   /**
@@ -603,18 +687,80 @@ function DTLSSession(options) {
    * Strips DTLS reconstruction → builds TLS format.
    */
   function deliverHandshakeMessage(type, body, msgSeq) {
-    // Skip if we've already processed this msg_seq
+    // Skip if we've already processed this msg_seq (duplicate / retransmit).
     if (msgSeq < ctx.nextReadMsgSeq) return;
-    ctx.nextReadMsgSeq = msgSeq + 1;
-
 
     // Check for HelloVerifyRequest (DTLS 1.2 server→client, type=3)
     if (type === 3 && !isServer) {
+      ctx.nextReadMsgSeq = msgSeq + 1;
       let hvr = parse_hello_verify_request(body);
       triggerClientHelloWithCookie(hvr.cookie);
       return;
     }
 
+    // ---- Server-side HelloVerifyRequest cookie exchange (RFC 6347 §4.2.1) ----
+    // For DTLS 1.2 with cookies enabled, the first ClientHello carries no cookie
+    // (or an empty one). We answer with a HelloVerifyRequest and do NOT process
+    // the ClientHello — that proves return-routability (the client must be at the
+    // address it claims before we allocate any handshake state). Only a second
+    // ClientHello echoing the correct cookie is processed.
+    //
+    // Note: msg_seq is NOT advanced for a rejected/HVR-triggering ClientHello, so
+    // the client's retried CH (which reuses msg_seq per RFC 6347) is still accepted.
+    if (type === 1 && isServer && options.useCookies === true &&
+        ctx.selectedVersion !== DTLS_VERSION.DTLS1_3) {
+
+      let ch = null;
+      try { ch = parse_hello({ kind: 'client', body: body }); } catch (e) { ch = null; }
+      let incomingCookie = (ch && ch.dtls_cookie) ? ch.dtls_cookie : new Uint8Array(0);
+
+      if (incomingCookie.length === 0) {
+        // First ClientHello → send HVR with a fresh cookie. Don't process the CH,
+        // don't advance msg_seq (the retry reuses the same msg_seq).
+        sendHelloVerifyRequest();
+        return;
+      }
+
+      // Second ClientHello: the cookie MUST match what we issued.
+      if (!ctx.hvrCookie || !timingSafeEqualU8(incomingCookie, ctx.hvrCookie)) {
+        // Cookie mismatch → silently drop (RFC 6347: server discards). Don't
+        // advance msg_seq; a correct retry can still arrive.
+        return;
+      }
+      // Cookie verified → fall through and process the ClientHello normally.
+    }
+
+    // ---- In-order delivery (RFC 6347 §4.2.4 / RFC 9147 §5.2) ----
+    // DTLS handshake messages must be handed to the TLS state machine strictly
+    // in msg_seq order. If this message is ahead of what we expect, buffer it
+    // and wait for the gap to fill. If it's the next expected one, feed it, then
+    // drain any consecutive messages that were buffered earlier.
+    if (msgSeq > ctx.nextReadMsgSeq) {
+      // Out of order — hold it (ignore a duplicate already buffered).
+      if (!(msgSeq in ctx.pendingMessages)) {
+        ctx.pendingMessages[msgSeq] = { type: type, body: body };
+      }
+      return;
+    }
+
+    // msgSeq === nextReadMsgSeq → feed it and advance.
+    feedHandshakeToTls(type, body, msgSeq);
+    ctx.nextReadMsgSeq = msgSeq + 1;
+
+    // Drain consecutively-numbered buffered messages.
+    while (ctx.nextReadMsgSeq in ctx.pendingMessages) {
+      let next = ctx.pendingMessages[ctx.nextReadMsgSeq];
+      delete ctx.pendingMessages[ctx.nextReadMsgSeq];
+      feedHandshakeToTls(next.type, next.body, ctx.nextReadMsgSeq);
+      ctx.nextReadMsgSeq++;
+    }
+  }
+
+  /**
+   * Feed one in-order handshake message to the TLSSession, converting from DTLS
+   * to TLS wire format and driving version detection.
+   */
+  function feedHandshakeToTls(type, body, msgSeq) {
     // Build TLS-format message: type(1) + length(3) + body
     let tlsMsg = build_message(type, body);
 
@@ -633,6 +779,23 @@ function DTLSSession(options) {
     }
   }
 
+  /**
+   * Server: build and send a HelloVerifyRequest with a fresh cookie (DTLS 1.2).
+   * The cookie is a CSPRNG value stored on the context; a matching cookie must
+   * come back in the client's second ClientHello (verified in
+   * deliverHandshakeMessage) before we process the handshake.
+   */
+  function sendHelloVerifyRequest() {
+    let cookie = new Uint8Array(crypto.randomBytes(32));
+    ctx.hvrCookie = cookie;
+    ctx.hvrDone = true;
+
+    // HVR always uses msg_seq 0 and is sent in the clear (epoch 0).
+    let hvrMsg = build_dtls_handshake(build_message(3, build_hello_verify_request({ cookie: cookie })), 0);
+    let record = buildDtlsPlaintext(CT.HANDSHAKE, 0, nextWriteSeq(0), hvrMsg);
+    ev.emit('packet', record);
+  }
+
   /**
    * Trigger a new ClientHello with cookie (DTLS 1.2 HVR response).
    */
@@ -650,6 +813,8 @@ function DTLSSession(options) {
     tls.context.message_sent_seq = 0;
     ctx.nextReadMsgSeq = 0;
     ctx.currentFlight = [];
+    ctx.fragments = {};          // discard any partial reassembly from CH1 flight
+    ctx.pendingMessages = {};    // discard any out-of-order buffer from CH1 flight
     transcriptMsgSeqs = [];
 
     // Push CH2 to transcript (transcriptHook will store TLS format for now,
@@ -734,6 +899,16 @@ function DTLSSession(options) {
   //  Handshake completion
   // ============================================================
 
+  // Forward 'clienthello' so server-side callers can inspect the peer's
+  // offered extensions (tls.getRemoteExtension / message.extensions) and
+  // set answering extensions via set_context({ local_extensions }) BEFORE
+  // the ServerHello is built — the emit is synchronous within ClientHello
+  // processing, ahead of hello construction. This is how DTLS-SRTP's
+  // use_srtp answer (RFC 5764 §4.1) gets negotiated generically.
+  tls.on('clienthello', function(data, message) {
+    ev.emit('clienthello', data, message);
+  });
+
   tls.on('secureConnect', function() {
     ctx.state = 'connected';
     cancelRetransmit();
@@ -786,23 +961,12 @@ function DTLSSession(options) {
   // ============================================================
 
   tls.on('hello', function() {
-    // Version is detected lazily in handshakeSecrets and message handlers
-
-    // DTLS 1.2 server: optionally send HelloVerifyRequest
-    if (isServer && ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 && !ctx.hvrDone && options.useCookies === true) {
-      ctx.hvrDone = true;
-      let cookie = new Uint8Array(32);
-      for (let i = 0; i < 32; i++) cookie[i] = Math.floor(Math.random() * 256);
-      ctx.hvrCookie = cookie;
-
-      let hvrBody = build_hello_verify_request({ cookie: cookie });
-      let hvrMsg = build_dtls_handshake(
-        build_message(3, hvrBody),
-        0
-      );
-      let record = buildDtlsPlaintext(CT.HANDSHAKE, 0, nextWriteSeq(0), hvrMsg);
-      ev.emit('packet', record);
-    }
+    // Version is detected lazily in handshakeSecrets and message handlers.
+    //
+    // Note: DTLS 1.2 HelloVerifyRequest is handled earlier, in
+    // deliverHandshakeMessage — the first (cookieless) ClientHello never reaches
+    // TLSSession, so by the time 'hello' fires here the cookie has already been
+    // verified. Nothing to do for HVR at this point.
   });
 
 
@@ -830,6 +994,21 @@ function DTLSSession(options) {
     /** Access to internal TLSSession (for advanced use). */
     get tls() { return tls; },
 
+    /**
+     * Export keying material (RFC 5705 / RFC 8446 §7.5).
+     * DTLS-SRTP: exportKeyingMaterial(len, 'EXTRACTOR-dtls_srtp') — no context.
+     * Returns Buffer, or null before secrets are available.
+     */
+    exportKeyingMaterial: function(length, label, context_value) {
+      return tls.exportKeyingMaterial(length, label, context_value);
+    },
+
+    /** Peer's hello extensions: [{ type, name, data, value }]. */
+    getRemoteExtensions: function() { return tls.getRemoteExtensions(); },
+
+    /** One peer extension by numeric type (e.g. 14 = use_srtp), or null. */
+    getRemoteExtension: function(type) { return tls.getRemoteExtension(type); },
+
     /** Current DTLS state. */
     get state() { return ctx.state; },
 

package/src/dtls_socket.js

@@ -81,6 +81,13 @@ function DTLSSocket(udpSocket, options) {
     ev.emit('session', ticket);
   });
 
+  // Server-side callers use this to inspect the peer's offered extensions
+  // (session.getRemoteExtension) and answer via set_context BEFORE the
+  // ServerHello is built — e.g. DTLS-SRTP's use_srtp (RFC 5764).
+  session.on('clienthello', function(data, message) {
+    ev.emit('clienthello', data, message);
+  });
+
   /**
    * Feed an incoming UDP datagram (filtered by remote address/port).
    * Called by the UDP socket's message handler or by DTLSServer.
@@ -122,6 +129,21 @@ function DTLSSocket(udpSocket, options) {
   self.getALPN = function() { return session.getALPN(); };
   self.getPeerCertificate = function() { return session.getPeerCertificate(); };
 
+  /** RFC 5705 / RFC 8446 §7.5 exporter (Node tls.TLSSocket parity).
+   *  DTLS-SRTP: exportKeyingMaterial(len, 'EXTRACTOR-dtls_srtp') — no context.
+   *  Returns Buffer, or null before secrets are available. */
+  self.exportKeyingMaterial = function(length, label, context_value) {
+    return session.exportKeyingMaterial(length, label, context_value);
+  };
+
+  /** Peer hello extensions / single extension by numeric type. */
+  self.getRemoteExtensions = function() { return session.getRemoteExtensions(); };
+  self.getRemoteExtension = function(type) { return session.getRemoteExtension(type); };
+
+  /** Pass config through to the underlying session (e.g. local_extensions
+   *  from a 'clienthello' handler). */
+  self.set_context = function(opts) { session.set_context(opts); };
+
   /** Access to internal DTLSSession (for advanced use). */
   self.session = session;
 

package/src/record.js

@@ -297,6 +297,37 @@ function getNonce12(salt4, explicit8) {
   return out;
 }
 
+/**
+ * TLS/DTLS 1.2 ChaCha20-Poly1305 nonce (RFC 7905 §2).
+ *
+ * Unlike AES-GCM, ChaCha20-Poly1305 in TLS 1.2 has NO explicit per-record nonce
+ * on the wire. The 12-byte nonce is the record's 64-bit sequence number, left-
+ * padded to 12 bytes, XORed with the 12-byte client/server write IV derived from
+ * the key block. This is the same construction TLS 1.3 uses — the difference from
+ * GCM (salt(4) || explicit(8)) is why the two must be handled separately.
+ *
+ * For DTLS the "sequence number" input is the 16-bit epoch concatenated with the
+ * 48-bit record sequence number, i.e. the same 64-bit value used in the AAD, so
+ * callers pass the full record seq and (for DTLS) fold the epoch into it.
+ */
+function getChachaNonce12(iv12, seq) {
+  const nonce = new Uint8Array(12);
+  nonce.set(iv12, 0);
+  // XOR the 64-bit seq into the LAST 8 bytes (big-endian), leaving the first 4
+  // bytes of the IV untouched — identical layout to TLS 1.3's getNonce.
+  const hi = (seq / 0x100000000) | 0;
+  const lo = seq >>> 0;
+  nonce[4]  ^= (hi >>> 24) & 0xff;
+  nonce[5]  ^= (hi >>> 16) & 0xff;
+  nonce[6]  ^= (hi >>> 8)  & 0xff;
+  nonce[7]  ^=  hi         & 0xff;
+  nonce[8]  ^= (lo >>> 24) & 0xff;
+  nonce[9]  ^= (lo >>> 16) & 0xff;
+  nonce[10] ^= (lo >>> 8)  & 0xff;
+  nonce[11] ^=  lo         & 0xff;
+  return nonce;
+}
+
 /**
  * Encode sequence number as 8-byte big-endian.
  * Perf: uses Number arithmetic (seq < 2^53 is always safe for TLS).
@@ -634,11 +665,36 @@ function buildDtlsAad12(epoch, seq, type, plaintextLen) {
   return aad;
 }
 
-/** Encrypt DTLS 1.2 record payload. Returns: explicit_nonce(8) || ciphertext || tag(16). */
+/** Encrypt DTLS 1.2 record payload. Returns: [explicit_nonce(8) ||] ciphertext || tag(16).
+ *
+ * AES-GCM: prepends an 8-byte explicit nonce (the record seq); nonce = salt(4) || seq(8).
+ * ChaCha20-Poly1305 (RFC 7905): NO explicit nonce on the wire; nonce = iv(12) XOR
+ *   (epoch(16) || seq(48)). Detected by ivSalt length (12 = ChaCha, 4 = GCM).
+ */
 function encryptDtls12(pt, key, ivSalt, epoch, seq, type) {
+  let aad = buildDtlsAad12(epoch, seq, type, pt.length);
+
+  // ChaCha20-Poly1305: full 12-byte IV, no explicit nonce (RFC 7905).
+  if (ivSalt.length === 12) {
+    // DTLS folds the 16-bit epoch above the 48-bit seq to form the 64-bit
+    // sequence input, matching the AAD's epoch||seq (RFC 6347 / RFC 9147).
+    let seq64 = epoch * 0x1000000000000 + seq;
+    let nonce = getChachaNonce12(ivSalt, seq64);
+    let cipher = crypto.createCipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+    cipher.setAAD(aad, { plaintextLength: pt.length });
+    let ct = cipher.update(pt);
+    cipher.final();
+    let tag = cipher.getAuthTag();
+    // No explicit nonce prefix for ChaCha.
+    let out = new Uint8Array(ct.length + tag.length);
+    out.set(new Uint8Array(ct), 0);
+    out.set(new Uint8Array(tag), ct.length);
+    return out;
+  }
+
+  // AES-GCM: explicit nonce (= record seq) prepended.
   let explicit = seqToBytes(seq);
   let nonce = getNonce12(ivSalt, explicit);
-  let aad = buildDtlsAad12(epoch, seq, type, pt.length);
   let algo = key.length === 16 ? 'aes-128-gcm' : 'aes-256-gcm';
   let cipher = crypto.createCipheriv(algo, key, nonce);
   cipher.setAAD(aad);
@@ -652,8 +708,28 @@ function encryptDtls12(pt, key, ivSalt, epoch, seq, type) {
   return out;
 }
 
-/** Decrypt DTLS 1.2 record fragment. Input: explicit_nonce(8) || ciphertext || tag(16). */
+/** Decrypt DTLS 1.2 record fragment.
+ *  AES-GCM input: explicit_nonce(8) || ciphertext || tag(16).
+ *  ChaCha20 input: ciphertext || tag(16)  (no explicit nonce — RFC 7905).
+ */
 function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
+  // ChaCha20-Poly1305: no explicit nonce; nonce = iv(12) XOR (epoch||seq).
+  if (ivSalt.length === 12) {
+    if (fragment.length < 16) throw new Error('DTLS 1.2 ChaCha fragment too short');
+    let ct  = fragment.slice(0, fragment.length - 16);
+    let tag = fragment.slice(fragment.length - 16);
+    let seq64 = epoch * 0x1000000000000 + seq;
+    let nonce = getChachaNonce12(ivSalt, seq64);
+    let aad = buildDtlsAad12(epoch, seq, type, ct.length);
+    let decipher = crypto.createDecipheriv('chacha20-poly1305', key, nonce, { authTagLength: 16 });
+    decipher.setAAD(aad, { plaintextLength: ct.length });
+    decipher.setAuthTag(tag);
+    let pt = decipher.update(ct);
+    decipher.final();
+    return new Uint8Array(pt);
+  }
+
+  // AES-GCM: strip the 8-byte explicit nonce.
   if (fragment.length < 24) throw new Error('DTLS 1.2 fragment too short');
   let explicit = fragment.slice(0, 8);
   let tag = fragment.slice(fragment.length - 16);
@@ -801,10 +877,42 @@ function buildEncryptedDtls13(innerType, plaintext, seq, epoch, keys) {
   return record;
 }
 
+/**
+ * Reconstruct a full DTLS 1.3 record sequence number from its truncated wire
+ * encoding (RFC 9147 §4.2.2).
+ *
+ * @param truncated  the low `bits` bits of the seq as sent on the wire
+ * @param bits       8 or 16 (how many low bits were transmitted)
+ * @param maxSeq     highest full seq already accepted in this epoch (-1 if none)
+ *
+ * Returns the full seq: the value congruent to `truncated` (mod 2^bits) that is
+ * closest to maxSeq+1. This tolerates reordering within half a window in each
+ * direction, which is what the sliding receive window expects.
+ */
+function reconstructDtlsSeq(truncated, bits, maxSeq) {
+  let window = Math.pow(2, bits);          // 256 or 65536
+  let expected = maxSeq + 1;               // where we expect the next record
+  let high = Math.floor(expected / window) * window;
+  let candidate = high + truncated;
+
+  // Pick whichever of {candidate-window, candidate, candidate+window} is nearest
+  // to `expected`, without going negative.
+  let best = candidate;
+  let bestDist = Math.abs(candidate - expected);
+  for (let delta of [-window, window]) {
+    let alt = candidate + delta;
+    if (alt < 0) continue;
+    let dist = Math.abs(alt - expected);
+    if (dist < bestDist) { best = alt; bestDist = dist; }
+  }
+  return best;
+}
+
+
 /**
  * Decrypt a DTLS 1.3 encrypted record.
  * data: full record bytes (starting with unified header byte)
- * keys: { key, iv, snKey, algo? }
+ * keys: { key, iv, snKey, algo?, maxReadSeq? }
  * Returns { epoch, seq, type, content } or null on failure.
  */
 function decryptEncryptedDtls13(data, keys) {
@@ -834,7 +942,19 @@ function decryptEncryptedDtls13(data, keys) {
 
   // Decrypt record number
   let rn = maskRecordNumber(keys.snKey, encRn, ciphertext);
-  let seq = hdr.seqLen2 ? ((rn[0] << 8) | rn[1]) : rn[0];
+  let truncated = hdr.seqLen2 ? ((rn[0] << 8) | rn[1]) : rn[0];
+
+  // RFC 9147 §4.2.2: the wire carries only the low 8 or 16 bits of the record
+  // sequence number. Reconstruct the full value by choosing the candidate
+  // congruent to `truncated` (mod window) that is closest to the highest seq
+  // we've already accepted in this epoch. Without this, seq silently wraps to 0
+  // after 2^16 records and every nonce/AAD past that point is wrong.
+  //
+  // keys.maxReadSeq holds the highest full seq accepted so far (per-epoch key
+  // object). It starts undefined → treated as -1 so the first record maps to
+  // its own truncated value.
+  let seq = reconstructDtlsSeq(truncated, hdr.seqLen2 ? 16 : 8,
+                               (keys.maxReadSeq === undefined ? -1 : keys.maxReadSeq));
 
   // Rebuild AAD with plaintext RN
   let hdrLen = 1 + rnLen + (hdr.hasLength ? 2 : 0);
@@ -863,6 +983,13 @@ function decryptEncryptedDtls13(data, keys) {
     decipher.final();
 
     let inner = parseInnerPlaintext(new Uint8Array(pt));
+
+    // Advance the per-epoch high-water mark only after the tag verified, so a
+    // forged/replayed record number can't poison future reconstruction.
+    if (keys.maxReadSeq === undefined || seq > keys.maxReadSeq) {
+      keys.maxReadSeq = seq;
+    }
+
     return {
       epoch: hdr.epoch,
       seq: seq,
@@ -1018,6 +1145,7 @@ export {
 
   // TLS 1.2
   getNonce12,
+  getChachaNonce12,
   seqToBytes,
   buildAad12,
   encrypt12,

package/src/session/ecdh.js

@@ -28,7 +28,22 @@ function x25519_get_shared_secret(localPrivateRaw, remotePublicRaw) {
   let pubDer  = Buffer.concat([X25519_SPKI_PREFIX, Buffer.from(remotePublicRaw)]);
   let privObj = crypto.createPrivateKey({ key: privDer, format: 'der', type: 'pkcs8' });
   let pubObj  = crypto.createPublicKey({ key: pubDer, format: 'der', type: 'spki' });
-  return new Uint8Array(crypto.diffieHellman({ privateKey: privObj, publicKey: pubObj }));
+  let secret  = new Uint8Array(crypto.diffieHellman({ privateKey: privObj, publicKey: pubObj }));
+
+  // RFC 7748 §6.1: implementations MUST reject an all-zero shared secret. A peer
+  // that sends a low-order/small-order public key can force the X25519 result to
+  // be all zeros — a value it knows in advance — which would let it choose the
+  // key material. The `break` here is safe (does not leak a secret): the peer's
+  // public key is public, so an early exit reveals nothing exploitable.
+  let allZero = true;
+  for (let i = 0; i < secret.length; i++) {
+    if (secret[i] !== 0) { allZero = false; break; }
+  }
+  if (allZero) {
+    throw new Error('X25519: all-zero shared secret — invalid peer public key (RFC 7748 §6.1)');
+  }
+
+  return secret;
 }
 
 /**